OS/2 Shareware BBS: 5 Edit

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / parsomat.zip / manual.txt < prev next >

Wrap

Text File | 2001-07-15 | 440KB | 11,738 lines

=========================================================================== =========================================================================== ============================ ============================ ============================ ============================ ============================ PARSE-O-MATIC ============================ ============================ ============================ ============================ ============================ =========================================================================== =========================================================================== Copyright (C) 1986, 2001 by Pinnacle Software (Toronto) +-------------------------- WIDE APPLICABILITY ---------------------------+ | | | | | Runs under Windows (3.x, 95, 98, NT, Me, 2000), OS/2, | | and Novell (DR-DOS). | | | | Can be invoked by other Windows, DOS or OS/2 programs | | such as FoxPro, Pascal, Visual Basic, C++, Delphi and | | so on, with success verification (return code or log) | | | | Can be run under DOS emulators (e.g. Macintosh, Unix) | | for convenient cross-platform conversion. | | | | | +------- HERE ARE A FEW OF THE THINGS PARSE-O-MATIC CAN DO FOR YOU -------+ | | | | | Importing Exporting Automated Editing | | Text Extraction Data Conversion Table Lookup | | Retabulation Info Weeding Selective Copying | | Binary-File to Text Report Reformatting Wide-Text Folding | | Auto-Batch Creation Comm-log Trimming Tab Replacement | | Character Filtering Column Switching DBF Interpretation | | De-uppercasing Name Properization And much more! | | | | | +---- INPUT AND OUTPUT METHODS CURRENTLY SUPPORTED BY PARSE-O-MATIC ------+ | | | | | Input: Text (any format), Binary, DBF (DBase), Fixed-Record-Length, | | Variable-Record-Length, EBCDIC | | | | Output: Text (e.g. flat, comma-delimited, paginated, hex), Binary, | | Fixed-Record-Length, Variable-Record-Length, EBCDIC, | | Generic output devices (e.g. COM1: or LPT2:) | | | | | +-------------------------------------------------------------------------+ +------------ UNSOLICITED TESTIMONIALS (USED WITH PERMISSION) ------------+ | | | | | "Parse-O-Matic is absolutely great. I use it when I collect data | | from the McDonald's restaurants in Switzerland. POM has paid for | | itself so many times ..." -- Chris Friedli | | | | | +-------------------------------------------------------------------------+ | | | | | "Parse-O-Matic is a wonderful time saver .... Each report that I | | can convert from our ... accounting system saves our company about | | 500 man hours per year." -- R. Brooker | | | | | +-------------------------------------------------------------------------+ | | | | | "In 30 years of working with computers, this is by far the easiest | | way I have found to extract data from files. I was very surprised | | that the program just took a few seconds to chew its way through | | 1MB of data. You ought to mention it's FAST." -- Koenraad Rutgers | | | | | +-------------------------------------------------------------------------+ | | | | | "Parse-O-Matic is THE greatest parsing package .... I wrote my own | | software for parsing ... then I was introduced to POM and have been | | using it ever since. Good job!" -- Jeff Tallent, Vestax Securities | | | | | +-------------------------------------------------------------------------+ +---------------------- PARSE-O-MATIC IS VERSATILE -----------------------+ | | | | | | | This manual was formatted by Parse-O-Matic, from plain text files. | | The table of contents was also generated by Parse-O-Matic. | | | | | | | +-------------------------------------------------------------------------+ +------------------------ WHO USES PARSE-O-MATIC? ------------------------+ | | | | | Some of our distinguished customers include: | | | | | | Bankers Trust HBO (Home Box Office) Philip Morris | | | | Berliner Volksbank Harris Semiconductor Pitney Bowes | | | | Boeing Home Box Office Prentice Hall | | | | Bridgestone Hughes Procter and Gamble | | | | CIBA Vision Ingram Rank Xerox | | | | Calcomp Canada Carrefour France Kodak | | | | Royal Bank Champion Int'l Lipton Tea | | | | Royal Caribbean CompUSA May Department Stores | | | | SmithKline Beacham Degussa McCain Foods | | | | Southwest Bancorp Dresdner Bank McDonald's | | | | Sun Life Eaton Monsanto France | | | | Sundstrand Aerospace Eddy NEC | | | | Target European American Bank Nestle | | | | Visa International First Bank System Nike | | | | Yale University Press First Federal Novell | | | | Ziff-Davis Georgia Gulf Pacific Gas & Electric | | | | | +-------------------------------------------------------------------------+ +-------------------------------------------------------------------------+ | | | | | The above list includes our best known customers, but omits | | city, state or provincial government offices and hospitals. | | | | | +-------------------------------------------------------------------------+ ============================================================================ TABLE OF CONTENTS ============================================================================ INTRODUCTION 1 What is Parse-O-Matic? 1 Parse-O-Matic Versus Automatic Converters 1 Why You Need Parse-O-Matic -- An Example 2 Parse-O-Matic to the Rescue! 2 How It Works 3 How To Contact Us 3 FUNDAMENTALS 4 The Parse-O-Matic Command 4 The POM File 4 Padding for Clarity 5 A Simple Example 6 QUICK REFERENCE 7 Command Descriptions 7 Basic Commands 7 Output Commands 7 Input Commands 7 Input Filters 7 Flow Control Commands 8 Variable Modifiers 8 Free-Form Commands 8 Positional Commands 8 Date Commands 8 Calculation Commands 9 Input Preprocessors 9 Lookup Commands 9 Data Converters 9 Miscellaneous Commands 9 Command Formats 10 BASIC COMMANDS 13 The SET Command 13 Basic Usage 13 The Trimming String 14 Non-Keyable Characters 15 The Null-Handling String 15 The IF Command 16 OUTPUT COMMANDS 17 The KEEP Command 17 The OFILE Command 18 Basic Usage 19 Closing the Output File 19 Strong Deduction 19 Weak Deduction 20 Appended Deductions 21 The OUT and OUTEND Commands 21 Generating a Blank Line 22 Missing Output 22 The OUTHDG Command 22 The OUTPAGE Command 23 The PAGELEN Command 24 INPUT COMMANDS 26 The GET Command 26 Variable Length Records 27 Delimiter-Terminated Data 29 Handling Long Delimiter-Terminated Data 30 Using GET with Text Files 30 End-of-File Considerations 31 The GETTEXT Command 32 The READNEXT Command 33 End of File Conditions 33 Optional Comparisons 34 Ignoring Null Lines 34 Saving the Previous Line 34 The PEEK Command 35 The REWIND Command 36 Why REWIND is Necessary 36 Using REWIND 37 Example 37 INPUT FILTERS 38 The MINLEN Command 38 The IGNORE Command 39 The ACCEPT Command 39 Clustered Accepts 40 FLOW CONTROL COMMANDS 41 The BEGIN Command 41 The CALL Command 43 Variable CALLs 43 Making Your Technique Obvious 44 Avoiding Unknown Code Sections 44 The CODE Command 45 Performance Considerations 46 Nested Subroutine Calls 46 Variable Code Sections 46 A Note to Experienced Programmers 47 The ELSE Command 47 The END Command 48 The AGAIN Command 49 Using AGAIN for Variable-Length Data 50 Pointless Command Combinations 51 Examples 52 The DONE Command 53 The NEXTFILE Command 55 The HALT Command 56 The SETERROR Command 57 The PROLOGUE Command 58 The EPILOGUE Command 59 VARIABLE MODIFIERS 61 The TRIM Command 61 The PAD Command 62 The CHANGE Command 62 The CVTCASE Command 63 Control Settings 64 The PROPER Command 64 The INSERT Command 66 The APPEND Command 67 The OVERLAY Command 68 Simple Arrays 69 The MAPFILE Command 70 What is a Map File? 70 Sample Map Files 70 Map File Format 71 Search Order 71 Case Matching 73 Reverse Mapping 73 Irreversible Mapping 74 Memory Limitations 75 An Example of Remapping 75 The REMAP Command 76 REMAP Versus CHANGE 77 Using REMAP 77 FREE-FORM COMMANDS 78 What are Free-Form Commands? 78 The PARSE Command 78 Decapsulators 79 Sample Application 80 The Occurrence Number 80 Finding the Last Occurrence 81 Unsuccessful Searches 81 The Control Setting 82 The Plain Decapsulator 82 The Null Decapsulator 83 Why Null Decapsulators Work Differently 84 Overlapping Decapsulators 84 Parsing Empty Fields 85 Additional Examples 85 The PEEL Command 85 The Control Setting 86 Parsing Empty Fields 87 The Left-Peeling Technique 88 The Leftover Technique 88 The PEELX Command 89 POSITIONAL COMMANDS 91 General Discussion 91 What are Positional Commands? 91 Why Use Positional Commands? 91 A Cautionary Note 92 Negative Positional Indices 93 The SETLEN Command 94 The DELETE Command 95 The COPY Command 96 The EXTRACT Command 97 The FINDPOSN Command 98 The Plain String Find 98 Using a Single Decapsulator 99 The Encapsulated String Find 99 Control Settings 101 Insoluble Searches 102 Null Decapsulators 102 Finding The Last Word 103 Who Needs This? 103 The SCANPOSN Command 104 The Scanlist 105 Accommodating Variation 105 Handling Prefixes and Suffixes 106 Controlling the Search 106 Leftmost, Rightmost, Find-Any 107 The Best Match Principle 108 DATE COMMANDS 110 General Discussion 110 The POMDATE.CFG File 110 Date Formats 110 The TODAY Command 112 The DATE Command 113 The MONTHNUM Command 114 The ZERODATE Command 115 CALCULATION COMMANDS 116 The CALC Command 116 The CALCREAL Command 118 The INC and DEC Commands 119 The ROUNDING Command 120 The CALCBITS Command 121 INPUT PREPROCESSORS 123 The SPLIT Command 123 Indicating Actual Input Length 124 Non-Contiguous Splits 124 The CHOP Command 125 Manual Reading 125 LOOKUP COMMANDS 126 The LOOKUP Command 126 Search Method 127 Limitations 127 Null Lines and Comments 128 Multiple Columns 128 LOOKUP Versus REMAP 129 The LOOKFILE Command 129 The LOOKCOLS Command 130 The LOOKSPEC Command 131 DATA CONVERTERS 132 The MAKEDATA Command 132 Creating Binary Data 132 Converting Dates 133 Practical Considerations 134 The MAKETEXT Command 134 Converting Binary Data 135 Converting Dates 135 Practical Considerations 135 MISCELLANEOUS COMMANDS 136 The ERASE Command 136 The FILESIZE Command 137 The GETENV Command 138 Disappearing Environment Variables 138 Examples 139 The LOG Command 139 The MSGWAIT Command 140 Standard Behavior 141 Setting a Time-Out Delay 141 Color Cues 141 Key Stacking 141 Exceptions 142 A Word of Caution 142 The PAUSE Command 142 The RANDOM Command 143 The SHOWNOTE Command 144 Other Notes 145 Slowing Down 145 The SOUND Command 145 The LISTEN Utility 146 Changing the Error Message Sound 146 The TRACE Command 147 TERMS 148 Values 148 Variables 148 Predefined Values 149 $FLINE 149 $FLUPC 150 $LASTFLINE 150 $SPLIT 151 $LINECOUNTER 151 Running Out of Variables, Literals or Lines 152 Delimiters 153 Illegal Characters 153 Using Comparators 153 Literal Comparators 154 Numerical Comparators 155 Length Comparators 155 Literal Comparisons and Sort Order 155 Numeric Comparisons 156 Upgrading from Earlier Versions 157 Predefined Data Types 157 Interpreting Data Formats in a File 158 DEDUCED VARIABLES 159 Deduced Variables 159 Definition 159 The Look-Up Process 160 Restrictions 160 Usage Guidelines 161 Array Variables 162 Multidimensional Arrays 163 Eponymous Variables 164 Drawbacks and Advantages 165 VALUE TECHNIQUES 166 Uninitialized and Persistent Variables 166 Example 166 Inline Incrementing and Decrementing 167 Line Counters 168 The SHOWNUM Utility 168 Quick Reference Screen 168 Converting a Number 169 Converting a Character 169 Windows Considerations 170 PROGRAMMING TECHNIQUES 171 Tracing 171 Logging 171 COMMAND-LINE TECHNIQUES 173 Quiet Mode 173 User-Specified Command-Line Parameters 173 Case Considerations 174 Spaces in Values 174 Command-Line Switches 175 Hex and Decimal Code Strings 175 Summary 176 FILE HANDLING 177 How Parse-O-Matic Searches for a File 177 How Parse-O-Matic Opens an Output File 178 Appending to an Output File 180 Sending Output to a Device 181 COM Ports 181 DbF Files 182 POM and Wildcards 182 OPERATIONAL TECHNIQUES 184 Parse-O-Matic Job (POJ) Files 184 Simple Usage 184 Commenting a Job File 185 Prompting for File Names 185 Suggesting File Names 186 Optional Parameters 186 Examples 187 Encrypted (Scrambled) POM Files 187 The SCRAMBLE Utility 187 Why Scramble a POM File? 188 Support Considerations 188 Batch Files 189 Unattended Operation 193 Examples 195 OPERATIONAL CONSIDERATIONS 196 Running Parse-O-Matic on 8088 and 8086 Machines 196 Running Parse-O-Matic from Another Program 196 Solving Memory Problems 196 RUNNING UNDER WINDOWS 197 Compatibility 197 Setting Up for Windows 95 197 Setting Up an Association for the POM File 197 Setting Up an Association for a POJ (Job) File 198 Setting Up an Association for the BAT File (Optional) 199 Setting Up for Windows 98, Me, 2000 200 Additional Associations (Optional) 200 Installing the ShowNum Utility 201 Long File Names in Windows 201 The WINUTIL Utility 201 Limitations 202 Quick Reference Screen 202 Sample Batch File 202 Detecting if Windows is Running 203 Copying the Clipboard to a Text File 203 Copying a Text File to the Clipboard 204 The SEE Utility 204 ============================================================================ INTRODUCTION ============================================================================ ---------------------- What is Parse-O-Matic? ---------------------- Parse-O-Matic is a programmable file-parser. Simple enough for even a non- programmer to master, it can help out in countless ways. If you have a file you want to edit, manipulate, or change around, Parse-O-Matic may be just the tool you need. Parse-O-Matic can also speed up or automate long or repetitive editing tasks. ----------------------------------------- Parse-O-Matic Versus Automatic Converters ----------------------------------------- Parse-O-Matic is not an "automatic file converter". It will not, for example, convert WordPerfect files to MS-Word format, or convert Lotus 1-2-3 Spreadsheets DIRECTLY to Excel files -- although it can read reports from one program and convert them to another format (e.g. comma-delimited), which can be imported by the other program. One advantage of this method (as opposed to automatic file conversion) is that you can create an "intelligent" importing procedure, which can make decisions and modify data. You could, for example, eliminate certain types of records, tidy up names, convert case, unify fields, make calculations, and so on. 1 ---------------------------------------- Why You Need Parse-O-Matic -- An Example ---------------------------------------- There are plenty of programs out there that have valuable data locked away inside them. How do you get that data OUT of one program and into another one? Some programs provide a feature which "exports" a file into some kind of generic format. Perhaps the most popular of these formats is known as a "comma-delimited file", which is a text file in which each data field is separated by a comma. Character strings -- which might themselves contain commas -- are surrounded by double quotes. So a few lines from a comma-delimited file might look something like this (an export from a hypothetical database of people who owe your company money): "JONES","FRED","1234 GREEN AVENUE", "KANSAS CITY", "MO",293.64 "SMITH","JOHN","2343 OAK STREET","NEW YORK","NY",22.50 "WILLIAMS","JOSEPH","23 GARDEN CRESCENT","TORONTO","ON",16.99 Unfortunately, not all programs export or import data in this format. Even more frustrating is a program that exports data in a format that is ALMOST what you need! If that's the case, you might decide to spend a few hours in a text editor, modifying the export file so that the other program can understand it. Or you might write a program to do the editing for you. Both solutions are time-consuming. An even more challenging problem arises when a program which has no export capability does have the ability to "print" reports to a file. You can write a program to read these files and convert them to something you can use, but this can be a LOT of work! ---------------------------- Parse-O-Matic to the Rescue! ---------------------------- Parse-O-Matic is a utility that reads a file, interprets the data, and outputs the result to another file. It can help you "boil down" data to its essential information. You can also use it to convert NEARLY compatible import files, or generate printable reports. 2 ------------ How It Works ------------ You need three things: 1) The Parse-O-Matic program 2) A Parse-O-Matic "POM" file (to tell Parse-O-Matic what to do) 3) The input file The input file might be a report or data file from another program, or text captured from a communications session. Parse-O-Matic can handle many types of input. We've provided several sample input files. For example, the file XMPDAT02.TXT comes from the AccPac accounting software. AccPac is a great program, but its export capabilities leave something to be desired. Parse-O-Matic can help! To see detailed demonstrations of how various files can be parsed, enter INFO at the DOS prompt (or run INFO.BAT from Windows or OS/2), then select TUTORIAL from the menu. ----------------- How To Contact Us ----------------- If you have any questions about Parse-O-Matic, you can write to us at the following address: Pinnacle Software, 80 Mornelle Court #310, Toronto, ON, Canada M1E 4P8 You can also contact us electronically at the following addresses: Voice Line: 416-287-8892 Internet Email: psoftinfo@aol.com Web Site: http://members.aol.com/psoftinfo 3 ============================================================================ FUNDAMENTALS ============================================================================ This documentation assumes that you are an experienced computer user. If you have trouble, you might ask a programmer to help you -- POM file creation is a little like programming! ------------------------- The Parse-O-Matic Command ------------------------- The basic format of the Parse-O-Matic command line is: POM pom-file input-file output-file Here is an example, as you would type it at the DOS command line, or as a command in a batch file: POM POMFILE.POM REPORT.TXT OUTPUT.TXT For a more formal description of the command line, start up POM by typing this command at the DOS prompt: POM Another method of calling the POM command is to specify a job (.POJ) file. This is explained later, in the "Operational Planning" chapter -- see "Parse-O-Matic Job (POJ) Files". Briefly, a job file lets you save the Parse-O-Matic command-line specifications in a text file. ------------ The POM File ------------ The POM file is a text file with a .POM extension. The following conventions are used when interpreting the POM file: - Null lines and lines starting with a semi-colon (comments) are ignored. - A POM file may contain up to 750 lines of specifications. Comment lines do not count in this total. A POM file does not rely on "loops" (to use the programming term). Each line or record of the input file is processed by the entire POM file. If you would like this expressed in terms of programming languages, here is what POM does: 4 +-------------------------------------------------------------------------+ | START: If there's nothing left in the input file, go to QUIT. | | Read a line from the input file | | Do everything in the POM file | | Go to START | | QUIT: Tell the user you are finished! | +-------------------------------------------------------------------------+ The method by which Parse-O-Matic finds the POM file is discussed in the section "How Parse-O-Matic Searches for a File". ------------------- Padding for Clarity ------------------- Spaces and tabs between the words and variables in a POM file line are generally ignored (except in the case of the "output picture" of the OUT and OUTEND commands). You can use spaces to make the commands in your POM files easier to read. Additionally, in any line in the POM file, the following terms are ignored: THEN ELSE (There is a POM command named ELSE, but Parse-O-Matic can tell that this is not "padding".) Finally, the equals ("=") character is ignored if it is found in a place where no comparison is taking place. This will be demonstrated below. You can use these techniques to make your POM files easier to read. For example, the IF command can be written in several ways: Very terse: IF PRICE = "0.00" BONUS "0.00" "1.00" Padded with spaces: IF PRICE = "0.00" BONUS "0.00" "1.00" Fully padded: IF PRICE = "0.00" THEN BONUS = "0.00" ELSE "1.00" In the last example, the first equals sign ("=") is a "comparator". (For details about comparators, see the section entitled "Using Comparators".) The second equals sign is not really required, but it does make the line easier to understand. 5 ---------------- A Simple Example ---------------- Let's say you have a text file called NAMES.TXT that looks like this: WILLIAMS JACK SMITH JOHNNY JOHNSON MARY : : Column 1 Column 12 Now let's say you want to switch the columns, so that the first name appears first. Your first step is to create a file using a text editor. The file would look like this: SET last = $FLINE[ 1 10] SET first = $FLINE[12 17] PAD first "R" " " "10" OUTEND |{first} {last} The first two lines tell Parse-O-Matic which text to extract from each input line. For the first line of the input file, the variable named 'last' will be given the value "WILLIAMS ". You will notice there are two spaces at the end. That is because we take every character from position 1 to position 10 -- which in this case includes two spaces. The PAD line adds enough spaces on the right side of the variable named 'first' to make sure that it is 10 characters long. The OUTEND command sends the two variables to the output file. Save the file with the name TEST.POM and exit your text editor. At the DOS prompt, enter this command: POM TEST.POM NAMES.TXT OUTPUT.TXT This will run the POM file (TEST.POM) on every line of the input file (NAMES.TXT) and place the output in the file OUTPUT.TXT, which will then look like this: JACK WILLIAMS JOHNNY SMITH MARY JOHNSON : : Column 1 Column 12 Of course, for such a simple task, it would be easier to switch the columns yourself, using a text editor. But when you are dealing with large amounts of data, and want to guard against typing errors, Parse-O-Matic can save you a lot of time, effort and risk. It also lets you automate editing operations that you perform frequently. 6 ============================================================================ QUICK REFERENCE ============================================================================ -------------------- Command Descriptions -------------------- This manual's explanations of the commands are grouped by related functions, in the following order: --------------------------------------------------------------------------- Basic Commands --------------------------------------------------------------------------- SET Assigns a value to a variable IF Conditionally assigns a value to a variable --------------------------------------------------------------------------- Output Commands --------------------------------------------------------------------------- KEEP Do a page eject if less than the specified number of lines remain OFILE Specify output file or device OUT Sends text and variables to the output file OUTEND Like OUT but adds a new line at end (Carriage Return/Linefeed) OUTHDG Sets up title lines to appear at the top of a report or each page OUTPAGE Starts a new page PAGELEN Sets the page length for a report --------------------------------------------------------------------------- Input Commands --------------------------------------------------------------------------- GET Manually reads bytes from the input file GETTEXT Manually reads bytes from the input file, converts them to text READNEXT Moves to next input line but retains your place in the POM file REWIND Backs up a specified number of bytes in an input file PEEK Looks at the next line in a text input file --------------------------------------------------------------------------- Input Filters --------------------------------------------------------------------------- MINLEN Sets minimum length required for an input line to be processed IGNORE Ignores an input line that meets the specified condition ACCEPT Accepts an input line that meets the specified condition 7 --------------------------------------------------------------------------- Flow Control Commands --------------------------------------------------------------------------- BEGIN Defines the conditions for processing the code block CALL Calls a subroutine code block CODE Marks the start of a subroutine code block ELSE Defines the start of code to be processed if the BEGIN fails END Ends a code block (BEGIN/END, CODE/END, PROLOGUE/END etc.) AGAIN Conditionally returns to the corresponding BEGIN command DONE Reads the next input line and starts at the top of the POM file NEXTFILE Skips the current input file and proceeds to the next (if any) HALT Terminates all processing if a given condition exists SETERROR Sets the program return code PROLOGUE Defines code block to run before any input lines are processed EPILOGUE Defines code block to run after all input lines are processed --------------------------------------------------------------------------- Variable Modifiers --------------------------------------------------------------------------- TRIM Removes a character from the left, right or all of a variable PAD Centers, or left/right-justifies variable to a specified width CHANGE Replaces all occurrences of a string in a variable PROPER Properizes a variable (e.g. "JOHN SMITH" becomes "John Smith") INSERT Inserts a string on the left or right, or at a "found" position APPEND Concatenates several variables into one variable OVERLAY Extends or overwrites portions of a variable CVTCASE Converts a value to uppercase or lowercase MAPFILE Reads a file containing data transformations for REMAP REMAP Transforms sub-strings into other strings --------------------------------------------------------------------------- Free-Form Commands --------------------------------------------------------------------------- PARSE Obtains a variable found between delimiters in free-form data PEEL Works like PARSE, but removes the "found" text from the data PEELX Works like PEEL, but assumes presence of delimiter on last search --------------------------------------------------------------------------- Positional Commands --------------------------------------------------------------------------- SETLEN Sets a variable according to the length of a value DELETE Removes a range of characters from a variable COPY Copies a range of characters from a value to a variable EXTRACT Like COPY, but removes the characters from the source variable FINDPOSN Finds the starting or ending position of a value in another SCANPOSN Finds "best match" in list of values, returns start/end positions --------------------------------------------------------------------------- Date Commands --------------------------------------------------------------------------- TODAY Sets a variable to today's date, in a variety of formats DATE Sets a given year, month and day, in a variety of formats MONTHNUM Sets the month number of a given month, expressed as text 8 --------------------------------------------------------------------------- Calculation Commands --------------------------------------------------------------------------- CALC Performs arithmetic functions on integer values CALCREAL Performs arithmetic functions on decimal values DEC Subtract a number from another (used for counters) INC Add a number to another (used for counters) ROUNDING Controls rounding in CALCREAL operations --------------------------------------------------------------------------- Input Preprocessors --------------------------------------------------------------------------- SPLIT Breaks up a wide text file (more than 255 characters) CHOP Breaks up a fixed-record-length file --------------------------------------------------------------------------- Lookup Commands --------------------------------------------------------------------------- LOOKUP Looks up a word in another file and returns a corresponding value LOOKFILE Specifies the file that the LOOKUP command will use (see also /L) LOOKCOLS Specifies the format of the look-up file LOOKSPEC Controls the behavior of the LOOKUP command --------------------------------------------------------------------------- Data Converters --------------------------------------------------------------------------- MAKEDATA Converts text into binary format MAKETEXT Converts binary format into text --------------------------------------------------------------------------- Miscellaneous Commands --------------------------------------------------------------------------- ERASE Deletes a file FILESIZE Obtains the size of a file (in bytes) GETENV Obtains a system environment variable (e.g. PATH) LOG Adds a line to the processing log MSGWAIT Controls the behavior of error messages PAUSE Delays the specified number of milliseconds RANDOM Generates a random number SHOWNOTE Displays a message on the processing screen SOUND Makes a noise or sets the noise generated by error messages TRACE Traces a variable (results saved in the text file POM.TRC) 9 --------------- Command Formats --------------- The following comment lines are for quick-reference. You can copy them into your own POM files to make programming easier. ---------------------------------- --------------------------------------- COMMAND FORMATS EXAMPLE ---------------------------------- --------------------------------------- ACCEPT comp ACCEPT $FLINE[1 3] = "YES" AGAIN [comp] AGAIN linecntr #< "3" APPEND var val val [val [val]] APPEND name first last BEGIN [comp] BEGIN linecntr #< "3" CALL val CALL "Format Price Field" CALC var num operation num CALC total total "+" sold CALCBITS var char operation char CALCBITS z byte1 "XOR" $80 CALCREAL var num operation num CALCREAL salary hours "*" rate CHANGE var val val CHANGE date "/" "-" CHOP from to [,from to] [...] CHOP 1 250, 251 300 CODE val CODE "Format Price Field" COPY var val ixfrom [ixto] COPY x $FLINE "-2" "-1" CVTCASE var val [ctl] CVTCASE x $FLINE "L7" DATE var num num num [ctl] DATE x "98" "12" "31" DEC var val DEC x "2" DELETE var ixfrom [ixto] DELETE x "3" "5" DONE [comp] DONE $FLINE = "End Data" ELSE ELSE END END EPILOGUE EPILOGUE ERASE file ERASE "C:\MYFILES\OUTPUT.TXT" EXTRACT var var ixfrom [ixto] EXTRACT x $FLINE "15" "30" FILESIZE var file FILESIZE x "C:\MYFILES\INPUT.TXT" FINDPOSN var val left [right [ctl]] FINDPOSN x $FLINE "2*/" GET var ctl [ctl [ctl]] GET x #0 "END" "I" GETENV var val GETENV x "COMSPEC" GETTEXT var ctl [ctl] GETTEXT date "WORD" "DATE" HALT comp val [ctl] HALT x = y "Item repeated" IF comp var val [val] IF x = "Y" THEN z = "N" INC var val INC x "2" IGNORE comp IGNORE price = "0.00" INSERT var ctl val INSERT price "L" "$" KEEP num KEEP "5" LOG comp val [val [val]] LOG x = y "Item repeated" LOOKCOLS num num num num LOOKCOLS "1" "3" "8" "255" LOOKFILE file LOOKFILE "C:\TABLES\DATA.TBL" LOOKSPEC ctl ctl ctl LOOKSPEC "Y" "N" "N" LOOKUP var val LOOKUP phonenum "FRED JONES" MAKEDATA var val ctl MAKEDATA x "255" "BYTE" MAKETEXT var val ctl MAKETEXT z x "BYTE" MAPFILE file val [ctl] MAPFILE "XYZ.MPF" "XYZ" "ANYCASE" MINLEN num [num] MINLEN "15" "1" MONTHNUM var val MONTHNUM x "February" 10 MSGWAIT num MSGWAIT "60" NEXTFILE [comp] NEXTFILE $FLINE = "End File" OFILE file [val [ctl]] OFILE "C:\MYFILES\OUT.TXT" OUT [comp] |pic OUT z = "X" |{price} OUTEND [comp] |pic OUTEND z = "X" |{$FLINE} OUTHDG val OUTHDG "LIST OF EMPLOYEES" OUTPAGE [comp] OUTPAGE partnum <> oldpartnum OVERLAY var val from OVERLAY x "***" "15" PAD var ctl char num PAD sernum "L" "0" "10" PAGELEN num [ctl] PAGELEN "66" "N" PARSE var val left right [ctl] PARSE x $FLINE "2*(" "3*)" "I" PAUSE num PAUSE "1000" PEEK var PEEK nextline PEEL var var left right [ctl] PEEL x $FLINE "2*(" "3*)" "I" PEELX var var left right [ctl] PEELX word wordlist "" " " PROLOGUE PROLOGUE PROPER var [ctl [file]] PROPER custname "I" "XY.PEF" RANDOM var val val RANDOM roll "1" "6" READNEXT [comp] READNEXT $FLINE[1 5] = "NOTE:" REMAP var [val] REMAP $FLINE "BIN2CODE" REWIND [num] REWIND "15" ROUNDING val ROUNDING "N" SCANPOSN var var val val [ctl] SCANPOSN from to $FLINE "/MR/MISS/MRS" SET var val [val [val]] SET price $FLINE[20 26] "L$" "0" SETERROR [comp] val SETERROR custname = "NONE" "123" SETLEN var val SETLEN length custname SHOWNOTE val [val] [val] [...] SHOWNOTE "Processing record #" recnum SOUND ctl SOUND "BUZZ" SPLIT from to [,from to] [...] SPLIT 1 250, 251 300 TODAY var [ctl] TODAY x "?y/?n/?d" TRACE var TRACE price TRIM var ctl char TRIM price "R" "$" ZERODATE num num num ZERODATE "1753" "12" "31" ---------------------------------- --------------------------------------- The following conventions are used in the preceding table: comp A comparison (Example: Name = "John") ctl Variable or literal: command control specifications file File name (see "How Parse-O-Matic Searches for a File") from Variable or literal: a starting character position (see Note #1) ixfrom Variable or literal: character position (beginning from...) ixto Variable or literal: character position (ending at...) left Variable or literal: a delimiter-search parameter (decapsulator) num Variable or literal: must contain a number (see Note #1) pic Output picture used by OUT and OUTEND right Variable or literal: a delimiter-search parameter (decapsulator) to Variable or literal: an ending position (see Note #1) val Variable or literal whose value is being read var Variable that is being set [xxx] Square brackets indicate optional items 11 Note #1: Tabs, spaces and commas are stripped from numeric values The commands are explained in detail in the following sections. A summary of the commands and default settings appear, as comments, in the file QUICKREF.POM. You can copy these comments into your own POM file as a convenient quick reference. 12 ============================================================================ BASIC COMMANDS ============================================================================ --------------- The SET Command --------------- FORMAT: SET var1 value1 [value2 [value3]] PURPOSE: SET assigns value1 to the variable var1. PARAMETERS: var1 is the variable being set value1 is the value being read value2 is the optional trimming string value3 is the optional null-handling string ALTERNATIVES: The COPY command, or just about any command that sets a variable. SEE ALSO: The TRIM Command ----------- Basic Usage ----------- The usual reason to use the SET command is to set a variable from the input line (represented by the variable $FLINE) prior to cleaning it up with TRIM. For example, if the input line looked like this: JOHN SMITH 555-1234 322 Westchester Lane Architect | | | | | Column 1 Col 12 Col 22 Col 33 Col 57 then we could extract the last name from the input line with these two POM commands: SET name1 = $FLINE[12 21] <-- Sets the variable name1 from the input line TRIM name1 "R" " " <-- Trims any spaces on the right side SET would first assign the variable name1 this value: "SMITH " After the TRIM, the variable name1 would have the value: "SMITH" You will also use SET if you plan to include a portion of text string in the output, since the OUT and OUTEND commands do not recognize substrings (e.g. myvar[10 20]) after the "|" marker; they only recognize plain text and complete variables. 13 ------------------- The Trimming String ------------------- After SETting a variable, you may wish to use one or more TRIM commands to "tidy up" the variable by removing leading and trailing spaces, extraneous commas, and so on. However, you can do this at the same time as you do the SET command, using the optional "trimming string". The trimming string is a list of pairs of characters. The first character in the pair is the TRIM specification, while the second is the character being trimmed. Consider the following POM code: SET xyz = "xx$3.00xx" SET price1 = xyz <-- Sets price1 to "XX$3.00XX" TRIM price1 "B" "x" <-- Sets price1 to "$3.00" TRIM price1 "L" "$" <-- Sets price1 to "3.00" This achieves the desired result (i.e. it gets rid of the "x" characters and the dollar sign), but it takes up four lines of code. You can use SET's trimming string to accomplish the same thing: SET xyz = "xx$3.00xx" SET price1 = xyz "BxL$" <-- Sets price1 to "3.00" The "BxL$" trimming string (made up of the character pairs "Bx" and "L$") instructs Parse-O-Matic as follows: CHAR TRIMMING PAIR OPERATION ---- --------- Bx Strip away "x" on Both sides of the value, yielding "$3.00", then... L$ Strip the dollar sign on the Left side, yielding "3.00" The trimming string is interpreted from left to right. Thus, the following commands would NOT produce the same result as the previous example: SET xyz = "xx$3.00xx" SET price1 = xyz "L$Bx" Parse-O-Matic will try to strip the dollar signs on the left, but since there are none there, it will move on to the next step without changing anything. It will then remove the "x" characters. The final result will be "$3.00", not "3.00". 14 ---------------------- Non-Keyable Characters ---------------------- In the trimming string, the second character in each character-pair must be a keyable character (i.e. something you can type on your keyboard and see on your screen). You can not use the $hex or #decimal representations (see "Values" in the "Terms" chapter). The following command is valid: SET num1 = $FLINE[10 20] "B A," This will remove the spaces on both sides and eliminate any commas. The following command is NOT valid: SET hex1 = $FLINE[10 20] "B$00R#13" The SET command can not translate the $00 code into "hex character zero". Similarly, it does not recognize the #13 as "decimal character 13" (which is, by the way, the ASCII "carriage return" character). To strip non-keyable characters, use the TRIM command. ------------------------ The Null-Handling String ------------------------ Sometimes you want to assign a "default" value to a variable if it turns out to be null (i.e. empty). Here is one way to do this: SET xyz = "" <-- This is a null string SET price1 = xyz <-- Sets price1 to "" IF price1 = "" THEN price1 = "0" <-- Sets price1 to "0" It is easier to do this by using the null-handling string, as in this example: SET xyz = "$3.00" <-- This is a normal price SET price1 = xyz "L$" "0.00" <-- Sets price1 to "3.00" SET xyz = "$" <-- This is just a dollar sign! SET price2 = xyz "L$" "0.00" <-- Sets price2 to "0.00" In the first case (xyz = "$3.00"), all we had to do was strip away the dollar sign to obtain the price. In the second case (xyz = "$"), we ended up with a null value after stripping away the dollar sign. In such case, the null-handling string ("0.00") specified the default value. 15 Sometimes you don't want to do any triming, but you do want to check for a default value. Nevertheless, the trimming string must be included in the command, as a "place holder". For example: SET xyz = "Fred Smith" <-- This is a normal name SET name1 = xyz "" "Unknown" <-- Sets name1 to "Fred Smith" SET xyz = "" <-- This is a null string SET name2 = xyz "" "Unknown" <-- Sets name2 to "Unknown" As you can see, no trimming was necessary, but we nevertheless had to include the trimming string, even though it was null (meaning, "Don't do any trimming"). -------------- The IF Command -------------- FORMAT: IF value1 [comparator] value2 var1 value3 [value4] PURPOSE: If value1 equals value2, var1 is set to value3. Otherwise, it is set to value4 (if value4 is missing, nothing is done, and var1 is not changed). NOTES: For an explanation of comparators, see "Using Comparators". In the following explanation, we will demonstrate the command using only the "literally identical" ("=") comparator. ALTERNATIVES: The BEGIN command Here is an example of the IF command... SET EARNING = $FLINE[20 23] IF EARNING = "0.00" THEN BONUS = "0.00" ELSE "1.00" This obtains the value between columns 20 and 26, then checks if it equals "0.00". If it does, the variable BONUS is set to 0.00. If not, BONUS is set to "1.00". The "THEN" and "ELSE" are "padding" and can be omitted. 16 ============================================================================ OUTPUT COMMANDS ============================================================================ ---------------- The KEEP Command ---------------- FORMAT: KEEP value1 PURPOSE: KEEP does a page eject if less than the specified number of lines remain on the page. PARAMETERS: value1 is the minimum number of lines required to avoid doing a page eject. ALTERNATIVES: The OUTPAGE command, used with $LINECOUNTER NOTES: KEEP has no effect unless the page length is set, using the PAGELEN command. SEE ALSO: "The OutHdg Command" When you are sending output to a file that will be printed (or sending output directly to a printer -- see "How Parse-O-Matic Opens an Output File"), you sometimes want to ensure that certain lines of data are kept together on the same page. The most common situation involves a heading that precedes some associated data; you do not want to have the heading by itself at the bottom of one page, with the data on the next. Consider this POM file: PAGELEN "55" <-- Set the output page length SET part = $FLINE[ 1 10] <-+ SET type = $FLINE[12 20] | Extract the fields SET quantity = $FLINE[22 30] <-+ BEGIN lasttype <> type <-- Detect a change in part type SET lasttype = part <-- Remember this part type KEEP "4" <-- Make sure we have 4 lines left OUTEND | <-- Output a blank line OUTEND |PART TYPE: {type} <-- Output a header END <-- End of code block OUTEND {part} {quantity} <-- Output part data This POM file will always make sure that at least two part numbers follow the heading; a heading will never be "stranded" by itself at the end of a page. 17 ----------------- The OFILE Command ----------------- FORMAT: OFILE value1 OFILE value1 [value2 [value3]] PURPOSE: OFILE specifies a new output file or device. PARAMETERS: value1 is the name of the output file or device value1 can also be a subcommand (i.e. a command for OFILE) value2 is the default extension for the DEDUCE subcommand value3 is the control value for the DEDUCE subcommand DEFAULTS: value2 defaults to "" for the DEDUCE subcommand value3 defaults to "WEAK" for the DEDUCE subcommand ALTERNATIVES: Specify the name of the output file on the POM command line SEE ALSO: "How Parse-O-Matic Opens an Output File" "Sending Output to a Device" When you start up Parse-O-Matic, you can specify the name of the output file on the command line. For example: POM MYPOM.POM INPUT.TXT OUTPUT.TXT In this case, the output file is named OUTPUT.TXT. All data from the output commands (OUT, OUTEND etc.) are sent to this file. If you omit the output file name from the POM command, like this: POM MYPOM.POM INPUT.TXT then Parse-O-Matic assumes the output file is named POMOUT.TXT (in the current directory). 18 ----------- Basic Usage ----------- Once the name of the output file has been determined, Parse-O-Matic will use that file until it is changed, using the OFILE command. For example: OFILE "C:\XYZ.TXT" This will change the output file to C:\XYZ.TXT. If the file already exists, it will be renamed with a BAK extension. However, you can tell Parse-O-Matic to append to the end of an existing file by placing a plus sign in front of the file name: OFILE "+C:\XYZ.TXT" (See "Appending to Output Files" and "POM and Wildcards" for additional details on appending to output files). ----------------------- Closing the Output File ----------------------- Sometimes you want your POM file to explicitly close the output file before doing additional processing. By closing the file explicitly, you ensure that all output has been written to the disk. To explicitly close the output file, use OFILE's CLOSE subcommand: OFILE "(CLOSE)" It is rarely necessary to explicitly close the output file, since this is done automatically when Parse-O-Matic finishes processing. You only need to do this if you suspect that a failure may occur between an OUT[END] command and the next OFILE command (or the completion of processing). ---------------- Strong Deduction ---------------- Sometimes you want to relate the name of the output file to the input file. For example, if the input file is XYZ.TXT, you might want to name the output file XYZ.OUT -- in other words, the same root name (XYZ) but a different extension (OUT). The OFILE command can do this with the DEDUCE subcommand, as follows: OFILE "(DEDUCE)" "OUT" "STRONG" The (DEDUCE) subcommand tells OFILE that you want it to use the same root name as the input file. The "OUT" part of this example is the extension you want to use. "STRONG" means that you want to override the existing output file, even if the user specified one on the command line. 19 Here is another example: OFILE "(DEDUCE)" "CSV" "STRONG" This uses the same root name as the input file, but uses the CSV extension (CSV usually signifies a comma-separated-value file). Once again, the "STRONG" parameter means that the new output file will be opened even if the user specified an output file on the POM command line. -------------- Weak Deduction -------------- Sometimes you want to set the output file name only if the user has not specified one on the POM command line. You can do this with OFILE's DEDUCE subcommand: OFILE "(DEDUCE)" "CSV" "WEAK" If the user ran POM with this command: POM MYFILE.POM ACCOUNT.DAT then the output file would be set to ACCOUNT.CSV. However, if the user explicitly specified an output file: POM MYFILE.POM ACCOUNT.DAT MYOUTPUT.TXT then the weak OFILE command would be ignored and output would continue to be directed to the MYOUTPUT.TXT file. Weak deduction is generally used in the PROLOGUE section of a POM file. It is particularly useful when wildcards are used (See "POM and Wildcards"). Consider this POM command: POM MYFILE.POM *.DAT You could put the following OFILE command in the PROLOGUE: OFILE "(DEDUCE)" "TXT" <-- "WEAK" is the default deduction This would create a separate output file for each file that is processed. So if you had three DAT files, named A.DAT, B.DAT and C.DAT, you would create three output files, named A.TXT, B.TXT and C.TXT. Because this is a weak deduction, the user is not forced to use your output method. If the user typed the POM command this way: POM MYFILE.POM *.DAT MYOUTPUT.TXT then all the output (from all of the input files) would go to MYOUTPUT.TXT. 20 NOTE: When a user does not specify an output file, Parse-O-Matic temporarily assumes that the output file is named POMOUT.TXT. If the user actually types POMOUT.TXT on the command line, Parse-O-Matic treats it as if no output file name had been typed. ------------------- Appended Deductions ------------------- An alternative to the DEDUCE subcommand is the +DEDUCE subcommand. This will figure out the output file name as before, but all output will be appended to the end. This is useful for daily processing when you want to accumulate data in your output file or files. For example: OFILE "(+deduce)" "txt" "strong" <-- Note that case does not matter If the user started POM with this command: POM MYFILE.POM ACCOUNT.DAT then the output file would be set to ACCOUNT.TXT, and all output would be placed at the end of the existing file of that name. --------------------------- The OUT and OUTEND Commands --------------------------- FORMAT: OUT[END] [value1 [comparator] value2] |output-picture PURPOSE: The OUT command generates output without an end-of-line (i.e. carriage return and linefeed characters). The OUTEND command generates output and also adds an end-of-line. NOTES: For an explanation of comparators, see "Using Comparators". In the following explanation, we will demonstrate the command using only the "literally identical" ("=") comparator. When value1 equals value2, a line is sent to the output file, according to the output picture. Within the output picture, all text is taken literally (i.e. " is taken to mean literally that -- a quotation mark character). The only exception to this is variable names, which are identified by the { and } characters. For example, a POM file that contained the following single line: OUTEND "X" = "X" |{$FLINE} would simply output every line from the input file (not very useful!). 21 The "X" = "X" part of the command is the comparison which controls when output occurs. In the example above, both values being compared are the same, so output will always occur. You can not use substrings after the "|" marker. Thus, the following line is NOT legal: OUTEND $FLINE[1 3] = "IBM" |{$FLINE[1 15]} The correct way to code this is as follows: SET CODE = $FLINE[1 15] OUTEND $FLINE[1 3] = "IBM" |{CODE} This outputs the first 15 characters of any line that contains the letters "IBM" in the first three positions. ----------------------- Generating a Blank Line ----------------------- To send a blank line to a text output file, specify OUTEND without any data following the | marker, as follows: OUTEND | -------------- Missing Output -------------- If you find that an OUT or OUTEND command is not displaying a variable, but puts "nothing" in its place, check the spelling of the variable name in each place it is used. Consider this example: SET varablex = $FLINE[1 12] OUTEND |XX{variablex}ZZ The SET command spelled "variablex" incorrectly -- it left out the "i". When OUTEND encounters the variable named "variablex", it sees that it does not have a value, so it replaces it with "nothing", yielding the result "XXZZ". ------------------ The OUTHDG Command ------------------ FORMAT: OUTHDG value1 PURPOSE: OUTHDG is used to place text headers in your output. ALTERNATIVES: The OUTEND command, used with PROLOGUE SEE ALSO: "The PageLen Command" and "The OutPage Command" 22 If you were parsing data to create an employee report, you might use OUTHDG like this: SET EMPNUM = $FLINE[ 1 5] SET NAME = $FLINE[10 28] SET PHONE = $FLINE[30 45] OUTHDG "EMPL# NAME PHONE NUMBER" OUTHDG "----- ------------------- ------------" OUTEND |{EMPNUM} {NAME} {PHONE} The value following the OUTHDG command is sent to the output file only once. That is to say, after an OUTHDG sends a value to the output file, subsequent encounters with that OUTHDG command are ignored -- unless the PAGELEN command is used. To specify a blank line in a heading, use the following command: OUTHDG "" If your output is bound for a continuous-paper printer (e.g. a dot-matrix printer with tractor feed), you may find it useful to use one or more blank lines at the beginning of the header, in order to skip over the perforation in the paper. ------------------- The OUTPAGE Command ------------------- FORMAT: OUTPAGE [value1 [comparison] value2] PURPOSE: Sends a page eject to the output file (or device). NOTES: For an explanation of comparators, see "Using Comparators". SEE ALSO: "The Pagelen Command", "The OutHdg Command", "$LINECOUNTER" If the comparison in the OUTPAGE command is true, or if it is omitted, OUTPAGE will send a "page eject" to the output file or device. (See "Sending Output to a Device") Some exceptions apply, however. The page eject is not sent under the following circumstances: - If the comparison is false (e.g. OUTPAGE "Y" = "N") - If the page length is set to "0" (the default). Use the PAGELEN command to specify a different page length. - If the output file is not yet open. That is to say, if no output has been sent to the output via one of the other output commands (e.g. OUT, OUTEND, OUTHDG), then OUTPAGE will do nothing. (See "How Parse-O-Matic Opens an Output File") - If the output is already at the top of a page. 23 If form feeds are enabled (via the PAGELEN command), OUTPAGE sends a page eject by sending a Form Feed character (ASCII 12) to the output. If form feeds are not enabled, OUTPAGE sends blank lines (i.e. linefeeds) until the requisite number of lines appear on the page. OUTPAGE does NOT automatically place OUTHDG text at the top of the page. OUTHDG text is not "stored"; it is executed in the POM file at the place it occurs. Here is an example of using OUTPAGE and OUTHDG together: PAGELEN "55" "Y" SET partnum = $FLINE[ 1 7] SET descrip = $FLINE[12 60] OUTPAGE partnum <> oldpartnum OUTHDG |PARTNUM DESCRIPTION OUTHDG |------- ----------- OUTEND |{partnum} {descrip} SET oldpartnum = partnum This will generate a new page, complete with headings, when the partnum variable is different from the oldpartnum variable. Also, because of the interaction between OUTHDG and PAGELEN, they headings will appear on a new page if you run out of room on the current page. ------------------- The PAGELEN Command ------------------- FORMAT: PAGELEN value1 [value2] PURPOSE: The PAGELEN command specifies the length of the output page. PARAMETERS: value1 is the page length value2 specifies if form feeds should be used NUMERICS: Tabs, spaces and commas are stripped from value1 DEFAULTS: value2 = "Y" When text is sent to an output file by OUTHDG and OUTEND, the lines are counted. The default value for page length is zero, which means that the output is a single page of infinite length. As such, OUTHDG headings appear only the first time they are encountered, and OUTPAGE commands are ignored. If you specify a page length greater than zero, OUTHDG headings become re-enabled once the specified number of output lines have been generated, or after an OUTPAGE command is performed. A typical value is as follows: PAGELEN "55" This is an ideal page length for most laser printers. Dot matrix printers typically use a page length of 66. 24 Parse-O-Matic inserts a "form feed" (ASCII 12) character between pages. You can turn this off, however, by specifying the page length this way: PAGELEN "66" "N" The "N" specification means, "No, don't use form feeds". Another acceptable value is "Y", meaning "Yes, use form feeds", but since this is the default, you do not have to specify it. 25 ============================================================================ INPUT COMMANDS ============================================================================ --------------- The GET Command --------------- ** ADVANCED COMMAND FOR EXPERIENCED USERS ** FORMAT: GET var1 value1 [value2] (Variable length records) GET var1 value1 "END" [value3] (Delimiter-terminated data) GET var1 "EOF" (Detects end-of-file) PURPOSE: Manually reads bytes from the input file. RESTRICTIONS: The input file must be described with CHOP or SPLIT. NOTES: Data is normally read automatically from the input file. GET is used only when you want precise control of the reading process. GET works only with files whose format is defined by a CHOP or SPLIT command. (You can read a file a byte at a time by using CHOP 1-1 in your POM file. You can also use CHOP 0 to do all reading manually.) SEE ALSO: "The Chop Command" and "The Split Command" The GET command is especially helpful for: 1) Variable length records 2) Delimiter-terminated data (such as zero-terminated text strings) 3) Text files with embedded binary data These methods are described in detail below. 26 ----------------------- Variable Length Records ----------------------- FORMAT: GET var1 value1 [value2] PURPOSE: Reads a variable-length record. PARAMETERS: var1 is the variable being set value1 specifies how many bytes to read, expressed as: A value in text format (example: GET x "10") A predefined data type (example: GET x "INTEGER") A value in byte format (example: GET x len "BYTE") value2 specifies the data representation used by value1 This can be "TEXT" (the default) or "BYTE" May also include "STRICT" (the default) or "LOOSE" NUMERICS: Tabs, spaces and commas are stripped from value1, if it is numeric, and in text format DEFAULTS: value2 = "TEXT" SEE ALSO: "Predefined Data Types" GET can read up to 255 bytes into a variable, as specified by value1. For example: GET xyz "10" This reads 10 bytes from the input file into the xyz variable, and advances the file pointer. That is to say, after the GET command shown above is executed, the next data Parse-O-Matic reads will be 10 bytes further along. If the requested number of bytes is not available in the input file, Parse-O-Matic terminates with an error message. In a typical application, variable-length data is preceded in the input file by a byte that gives its length. You can read the length, then use it directly, as follows: GET len "1" "TEXT" <-- Get the length byte GET xyz len "BYTE" <-- Read in the data In the first command, the word "TEXT" means that the length specification (i.e. "1") is plain text. ("TEXT" is the default, so you can omit it.) In the second command, GET reads len bytes from the input file. The word "BYTE" means that the length specification is a binary number, not a text string. 27 To clarify this, let us assume that the input file contains a length byte (say hex 4F, which equals 79 in decimal). This is followed by 79 bytes of data. The first GET command (GET len "1") reads in the length byte (hex 4F or decimal 79). The second GET command (GET xyz len "BYTE") reads 79 bytes and places the result in the xyz variable. The maximum variable length that a single GET command can handle is 255 bytes (i.e. the largest number represented by a single byte). Here are some additional examples of the GET command: SAMPLE COMMAND EXPLANATION ----------------- ----------- GET x "5" "TEXT" Reads 5 bytes into the x variable GET x "5" Same as above (since "TEXT" is the default) GET x len In this case, len must contain a text number (e.g. "7") GET x len "BYTE" In this case, len must be a byte (i.e. binary format) When the number is in "TEXT" format, spaces and tabs are ignored. Thus, the following command is valid: GET abc " 5 " "TEXT" You can also specify the length of the data as a predefined data type (see "Predefined Data Types" and "The MakeData Command"). Some examples... SAMPLE COMMAND EXPLANATION ----------------- ----------- GET x "INTEGER" Reads in an integer value (2 bytes long) GET x "SHORTINT" Reads in a short integer value (1 byte long) GET x "BYTE" Reads in a byte value (1 byte long) GET x "LONGINT" Reads in a long integer (4 bytes long) GET x "REAL" Reads in a real value (6 bytes long) GET x "REAL 2" Same as above (the decimal precision value 2 is ignored) TECHNICAL NOTE: In some applications, you will find that a variable-length record may be followed by a "noise" byte. This can occur if the program that created the input file "aligns data to word boundaries" and the record you are reading has an odd number of bytes. In such case, your POM file must determine (using CALC commands) if the length byte is odd or even, and react accordingly. 28 ------------------------- Delimiter-Terminated Data ------------------------- FORMAT: GET var1 value1 "END" [value3] PURPOSE: Reads delimiter-terminated data from the input file. PARAMETERS: var1 is the variable being set value1 is the terminating character you are searching for "END" means you are searching for a terminating character value3 is "I" (for Include) or "X" (for eXclude) DEFAULTS: value3 = "X" ALTERNATIVES: The PARSE and PEEL commands The FINDPOSN command used with the COPY command One common way to represent variable-length text data in a file is to terminate the text string with the null (ASCII 0) character. You can read in this kind of data with the GET command, as follows: GET abc #0 "END" <-- #0 means ASCII zero (See "Values") This reads the input file until the null (ASCII 0) character is found, or until 255 characters have been read in (whichever comes first). The terminating character is not included in the string unless you explicitly request it. There are two forms of GET command that control this behavior: GET abc #0 "END" "X" <-- Exclude the terminating character (default) GET abc #0 "END" "I" <-- Include the terminating character Here is a sample POM file that reads a data file that consists entirely of zero-terminated strings: CHOP 0 <-- This means you will handle all file reading GET abc #0 "END" <-- Read in the data OUTEND |{abc} <-- Send the data to the output file 29 --------------------------------------- Handling Long Delimiter-Terminated Data --------------------------------------- If some of the data is more than 255 characters long, you can handle it as follows: CHOP 0 <-- Handle all file reading manually GET data #0 "END" "I" <-- Include the terminating character SETLEN len data <-- Get the length of the string COPY lastchar data len <-- Get the last character BEGIN lastchar = #0 <-- Test the last character DELETE data len <-- Remove the last character (the terminator) OUTEND |{data} <-- Output the string, and start a new line ELSE OUT |{data} <-- Output the string, but stay on the same line END All of the examples given above assume that the terminating character is ASCII 0 (i.e. #0), because this is by far the most common terminator. However, you can use other values, if required: GET data "X" "END" In actual usage, it is not likely that you will find data strings that are terminated by an "X" character, but the capability is there if the need arises. ------------------------- Using GET with Text Files ------------------------- While the GET command is normally used with a file which is CHOPped (see "The Chop Command"), you may occasionally find it useful with ordinary text files. For example, an input file may be almost entirely text (i.e. each line ends with a carriage return and a linefeed), but may also contain some binary data. In such cases, you may find it useful to use the GET command to process the binary data. However, since GET is not available under standard text processing, you must describe the file with the SPLIT command. Here is an example which detects and extracts binary data until the character $FF is encountered: 30 SPLIT 1-255 <-- Process this as a SPLIT file BEGIN $FLINE[1 10] = "Binary:" <-- Detect the start of binary data BEGIN <-- Start of loop GET x "1" <-- Get a byte OUT |{x} <-- Send it to output AGAIN x <> $FF <-- See if we are finished ELSE <-- Handle ordinary text OUTEND |{$FLINE} <-- Output ordinary text END <-- End of BEGIN/ELSE/END code block Note that SPLIT 1-255 does not mean that each text line is 255 characters long; it means that each line is UP TO 255 characters long. -------------------------- End-of-File Considerations -------------------------- When you ask the GET command to get something (e.g. a certain number of bytes), it will normally cause Parse-O-Matic to terminate if it reaches the end of the input file before it has fulfilled its mission. The assumption here is that when you ask for something, you want precisely that -- not something less. However, in some parsing applications you do not know precisely what "lies ahead" in the input file. In such cases, you may run up against the end of file unexpectedly. GET provides two ways to handle this. The first method simply checks to see if you are already at the end of the file: GET x "EOF" This sets the x variable to "Y" (for Yes) if you are at the end of the input file. Otherwise, it sets the x variable to "N" (for No). Here is an example, which simply copies a file: CHOP 0 <-- Handle all file-reading manually BEGIN GET x "EOF" <-- Check if we're at the end of the input file BEGIN x = "N" GET byte "1" <-- Get a byte OUT |{byte} <-- Send it to the output file END AGAIN x = "N" An alternative method is to use a "LOOSE" GET command, as in this example: 31 CHOP 0 BEGIN GET x "1" "TEXT LOOSE" OUT |{x} AGAIN x <> "" The LOOSE parameter tells Parse-O-Matic "don't terminate if you have less than the specified number of bytes". (The default is "STRICT", but since it IS the default, you never actually have to include it in the command.) Thus, all of the following commands are valid: GET x $05 "BYTE LOOSE" <-- Get from 0 to 5 bytes of data GET x $05 "BYTE STRICT" <-- Get exactly 5 bytes of data, or terminate GET x "5" "TEXT LOOSE" <-- Get from 0 to 5 bytes of data GET x "5" "LOOSE" <-- Same as "TEXT LOOSE" GET x "1" <-- Same as "TEXT STRICT" ------------------- The GETTEXT Command ------------------- ** ADVANCED COMMAND FOR EXPERIENCED USERS ** FORMAT: GETTEXT var1 value1 [value2] PURPOSE: Manually reads bytes from the input file, then converts them into text format. PARAMETERS: var1 is the variable being set value1 is the predefined data type in the input file value2 is the MAKETEXT "convert from" parameter DEFAULTS: If value2 is omitted, it is assumed to be the same as value1 NOTES: Before studying this command, you should already be familiar with the GET and MAKETEXT commands. SEE ALSO: "Predefined Data Types" When reading a binary file, you frequently need to read numeric values then convert them to text. For example: GET x "WORD" <-- Read a two-byte number from the file MAKETEXT y x "WORD" <-- Convert it into text form You can do both of these operations at once, using the GETTEXT command: GETTEXT y "WORD" This reads a "WORD" (two binary bytes) from the input file, and then converts it into text (e.g. "1234"). 32 You only need to use value2 if you are converting a number to a text-based data type such as "DATE". For example: ZERODATE "1936" "1" "1" <-- Set "day zero" GETTEXT date "LONGINT" "DATE Y/M/?d" <-- Get and convert a date The GETTEXT command is also helpful if you are reading text data from a fixed-length field, but it is padded with spaces or nulls: GETTEXT x "80" "TRIMMED" This reads in 80 characters, then removes tabs, spaces and nulls from either end of the string. -------------------- The READNEXT Command -------------------- FORMAT: READNEXT [value [comparator] value] PURPOSE: The READNEXT command gets the next line of the input file (in other words, it replaces the current $FLINE), while maintaining your place in the POM file. NOTES: For an explanation of comparators, see "Using Comparators". SEE ALSO: "The MinLen Command" and "Line Counters" READNEXT is helpful if you know for certain what type of information the next line will contain. Here is an example: SET note = "" SET customer = $FLINE[1 20] BEGIN $FLINE ^ "See note below" READNEXT SET note = $FLINE[1 20] END OUTEND |{customer} {note} If the input line contains the words "See note below", Parse-O-Matic will read the next line of the input file (replacing the current $FLINE), thus obtaining the comment about the customer. ---------------------- End of File Conditions ---------------------- If you do a READNEXT at the end of the input file, READNEXT will set $FLINE to null (""). The POM file will continue processing. 33 -------------------- Optional Comparisons -------------------- READNEXT can make a comparison. This is useful for skipping extraneous lines of input. For example: READNEXT $FLINE[1 5] = "NOTE:" This obtains the next input line if the current input line starts with "NOTE:". ------------------- Ignoring Null Lines ------------------- By default, READNEXT will read null lines from the input file. If you want it to ignore null lines, you can use an optional parameter of the MINLEN command to specify a minimum length for the READNEXT command. For details, see "The MinLen Command". If you are reading a DBF (DBase) file, you can not "ignore null lines", because the data is not in line format. In such case, you must check a particular field to see if it is null. (See "DBF Files") If you are using the CHOP or SPLIT commands, it may not be particularly useful to "ignore null lines", since by definition you are requesting a particular number of bytes each time the input is read. Nevertheless, if you do a READNEXT at the end of the input file, READNEXT will set $FLINE to null (""), and continue processing the POM file. ------------------------ Saving the Previous Line ------------------------ When you do a READNEXT, there is no simple way to return to the previous line of the input file. You could use the REWIND command, but if you need a line for other work, it is usually much easier to save a copy: SET note = "" SET customer = $FLINE[1 20] SET saveline = $FLINE BEGIN $FLINE ^ "See note below" READNEXT SET note = $FLINE[1 20] END SET custnum = saveline[22 25] OUTEND |{custnum} {customer} {note} The example above is not very efficient; it would make more sense to extract custnum BEFORE you use READNEXT. However, in some applications you may find it necessary to save $FLINE before doing a READNEXT. 34 ---------------- The PEEK Command ---------------- FORMAT: PEEK var1 PURPOSE: Looks at the next input line in a simple text file. PARAMETERS: var1 is the variable being set RESTRICTIONS: PEEK can not be used with SPLIT, CHOPped or DBF files. For SPLIT or CHOPped files, you can simulate PEEK by using the GET and REWIND commands. NOTES: If you are at the end of the input file, PEEK will set var1 to a null value (""). WARNING: You can use PEEK only once for each pass through the POM file. If you use it more than once, you will lose data. ALTERNATIVES: The READNEXT command If you are processing a simple text file (i.e. a text file in which no input line exceeds 255 characters), you can find out what is on the next input line by using the PEEK command. Consider this input file: Fred Jones Pencil $ 0.25 Pen $ 1.25 Mary Smith Protractor $ 1.00 Compass $ 2.50 Pen $ 1.25 Calligraphy Kit $ 15.30 In this input file, a customer's name is followed by one or more items that he or she purchased. The input file does not contain a number telling us how many of each item there are. If it is our intention to add up the prices to obtain a total, it would be helpful if we had some warning that we have reached the last item. Fortunately, a null line (or end of file) follows each list of items. We can use the PEEK command to take advantage of this, as in the following POM file: 35 BEGIN $FLINE[18] <> "$" <-- Is this a price line? OUTEND |Customer Name: $FLINE <-- Output customer's name DONE <-- We're finished with this line END PEEK nextline <-- Find out what the next line contains BEGIN nextline = "" <-- If it's null, we have no more items OUTEND |Total: {total} <-- Output the total for all purchases SET total = "0.0" <-- Reset the total ELSE CALCREAL total = total "+" $FLINE[19 24] <-- Accumulate the total END ------------------ The REWIND Command ------------------ FORMAT: REWIND [value1] PURPOSE: REWIND backs up to an earlier point in the input file. NUMERICS: Tabs, spaces and commas are stripped from value1 DEFAULTS: If value1 is omitted, input file is rewound to the beginning RESTRICTIONS: The input file must be described with CHOP or SPLIT. SEE ALSO: "Using GET with Text Files" ----------------------- Why REWIND is Necessary ----------------------- Normally, when you process an input file, you read forward in the file. However, on occasion you may find it necessary to back up to an earlier point in the file. Here is a typical situation where this is necessary: you are looking for one of several strings of data, and when you find one of them, you want to: - Back up in the input file, to the beginning of the string you found - Use DONE to start processing the POM file from the top Because you rewound, the processing will include the text that you found. This is a handy alternative to saving the text and appending it to the front of $FLINE -- see "The Leftover Technique" for an example of that method. In another situation, you need to know something near the middle or end of the file, and once you have found out what that is, you want to rewind to the beginning and start processing again. This is known as "multiple-pass" processing, because you pass through the input file more than once. 36 ------------ Using REWIND ------------ If REWIND is used without any parameters (or if you specify REWIND "0"), Parse-O-Matic resets the input file to the beginning. This will usually be done in a BEGIN/END block, because if you reset the file each time you process the POM file, it will run forever. If REWIND is given a numeric parameter, it will back up that many bytes. (If you are processing a text file, remember to include two bytes for carriage return and linefeed, as necessary.) If the REWIND command is asked to rewind before the beginning of the file, it simply resets to the top. For example, if you have read 15 bytes out of the input file, and you issue the command REWIND "99", the next byte you read will be the first byte of the file. ------- Example ------- Consider this POM file: CHOP 0 <-- Handle all reading manually GET x "1" <-- Get a byte GET x "1" <-- Get another byte OUT |{x} <-- Output the byte REWIND "1" <-- Back up one byte GET x "1" <-- Get the same byte again OUT |{x} <-- Output the byte NEXTFILE <-- Stop processing this input file The code shown above will output the second character of an input file twice, then stop -- not very useful, except as a demonstration! 37 ============================================================================ INPUT FILTERS ============================================================================ ------------------ The MINLEN Command ------------------ FORMAT: MINLEN value1 [value2] PURPOSE: MINLEN specifies the minimum length an input line must be to be considered for parsing. PARAMETERS: value1 is the minimum input line length value2 is the minimum length for a READNEXT command NUMERICS: Tabs, spaces and commas are stripped from value1 and value2 DEFAULTS: value2 = "0" SEE ALSO: "The ReadNext Command" If you omit the MINLEN command, the minimum length is assumed to be 1. That is to say, all lines 1 character or longer will be processed and shorter lines (null lines in other words) will be ignored. MINLEN is useful for ignoring brief information lines that clutter up a report that you are parsing. For example, in the sample file EXAMPL02.POM, the MINLEN command is set to 85 to ensure that all lines shorter than 85 characters long will be ignored. This simplifies the coding considerably. The longest allowable input line is 255 characters, unless you use the SPLIT or CHOP command (see "The Split Command" and "The Chop Command"). The optional setting value2 specifies the minimum length for a READNEXT command. If omitted, this value is assumed to be "0", meaning that READNEXT will, by default, read null lines. If you set value2 to "1", READNEXT will keep reading until it finds an input line of 1 or more characters, or hits the end of file. The value2 setting has no effect if you are reading a DBF (DBase) file. 38 ------------------ The IGNORE Command ------------------ FORMAT: IGNORE value1 [comparator] value2 PURPOSE: When the comparison is true, the input line is ignored and all further processing on the input line stops. NOTES: For an explanation of comparators, see "Using Comparators". ALTERNATIVES: The ACCEPT and BEGIN commands Here is a typical application of the IGNORE command: IGNORE $FLINE[3 9] ^ "Date" This skips any input line that contains the word "Date" between columns 3 and 9 ($FLINE is the line just read from the input file). ------------------ The ACCEPT Command ------------------ FORMAT: ACCEPT value1 [comparator] value2 PURPOSE: The ACCEPT command accepts the input line if the comparison is true. value2. ACCEPT commands can be "clustered" to allow a series of related tests. NOTES: For an explanation of comparators, see "Using Comparators". In the following explanation, we will demonstrate the command using only the "literally identical" ("=") comparator. ALTERNATIVES: The IGNORE command If the entire POM file reads as follows: ACCEPT $FLINE[15 17] = "YES" OUTEND "X" = "X" |{$FLINE} then any input line that contains "YES" starting in column 15 is sent to the output file. All other lines are ignored. 39 ----------------- Clustered Accepts ----------------- Sometimes you have to check more than one value to see if the input line is valid. You do this by using "clustered ACCEPTs", which are several ACCEPT commands in a row. Briefly stated, if you have several ACCEPTs in a row ("clustered"), they are all processed to determine if the input line is acceptable or not. If even one ACCEPT matches up, the line is accepted. To express this in more detail... When the comparison is true, the line is accepted, and processing of the POM file continues for that input line, even if the immediately following ACCEPTs do NOT produce a match. After all, we've already got a match! If value1 does NOT contain value2, Parse-O-Matic looks at the next command in the POM file. If it is not another ACCEPT, the input line is ignored. If it is another ACCEPT, maybe it will product a match -- so Parse-O-Matic moves to that command. The following POM file uses clustered ACCEPTs to accept any line that contains the name "FRED" or "MARY" between columns 5 and 8, or contains the word "MEMBER" between columns 20 and 25. SET NAME = $FLINE[5 8] <-- Set the variable ACCEPT NAME = "FRED" <-- Look for FRED ACCEPT NAME = "MARY" <-- Look for MARY ACCEPT $FLINE[20 25] = "MEMBER" <-- Look for MEMBER OUTEND "X" = "X" |{$FLINE} <-- Output the line if we get this far The following example will NOT work, however: ACCEPT $FLINE[20 25] = "MEMBER" SET NAME = $FLINE[5 8] ACCEPT NAME = "FRED" ACCEPT NAME = "MARY" OUTEND "X" = "X" |{$FLINE} It will not work because the ACCEPTs are not clustered; if the first ACCEPT fails, the input line is rejected as soon as the SET command is encountered. The next two ACCEPTs are not reached in such case. 40 ============================================================================ FLOW CONTROL COMMANDS ============================================================================ ----------------- The BEGIN Command ----------------- FORMAT: The basic format for the BEGIN command is as follows: BEGIN value1 [comparator] value2 : Dependant code : END PURPOSE: If the comparison is true (e.g. value1 equals value2), then the dependant code (the POM lines between the BEGIN and the END) are executed. If the comparison is false, then the dependant code is skipped. NOTES: For an explanation of comparators, see "Using Comparators". In the following explanation, we will demonstrate the command using only the "literally identical" ("=") comparator. SEE ALSO: "The Else Command" and "The Again Command" It is traditional in programming to indent code that appears in blocks such as Parse-O-Matic's BEGIN/END technique. This makes the logic of the POM file easier for us to understand. For example: BEGIN datatype = "Employee" SET phone = $FLINE[ 1 10] SET address = $FLINE[12 31] END BEGIN/END blocks can be nested. That is to say, you can have BEGIN/END blocks inside other BEGIN/END blocks. Here is an example, with arrows to indicate the levels of each BEGIN/END block... BEGIN datatype = "Employee" <--------------------- SET phone = $FLINE[ 1 10] | SET address = $FLINE[12 31] | SET areacode = phone[1 3] | First BEGIN areacode = "514" <------- Second | Level SET local = "Y" | Level | Block SET tax = "Y" <------- Block | END | END <--------------------- 41 In this case, the "inner" block (starting with BEGIN areacode = "514") is reached only if the "outer" block (BEGIN datatype = "Employee") is true. If the outer block is false, the inner block is ignored. A nested BEGIN/END block must always be completely inside the outer block. Study the following (incorrect) example: BEGIN datatype = "Employee" <---- SET phone = $FLINE[ 1 10] | First SET areacode = phone[1 3] | Level BEGIN areacode = "514" <--- | Block? SET local = "Y" | | END | <---- SET tax = "Y" | END <--- Second Level Block? Parse-O-Matic does not pay attention to the indenting -- it is only a tradition we use to make the file easier to read. The code will be understood this way: BEGIN datatype = "Employee" <--------------------- SET phone = $FLINE[ 1 10] | First SET areacode = phone[1 3] | Level BEGIN areacode = "514" <--- Second | Block SET local = "Y" | Level | END <--- Block | SET tax = "Y" | END <--------------------- You can nest BEGIN/END blocks up to 25 deep -- although it is unlikely you will ever need that much nesting. Here is an example of code that uses nesting up to three deep: BEGIN datatype = "Dog" <---------------------------------- SET breed = $FLINE[1 10] | First BEGIN breed = "Collie" <----------------------- | Level SET noise = "Woof" | Second | Block BEGIN name = "Spot" <------ Third | Level | SET attitude = "Friendly" | Level | Block | END <------ Block | | END <----------------------- | BEGIN breed = "Other" <----------------------- Another | SET noise = "Arf" | Second | SET attitude = "Unknown" | Level | END <----------------------- Block | END <---------------------------------- Once again, the indentation is for clarity only and does not affect the way the POM file runs. However, you will find that it makes your POM file much easier to understand. 42 ---------------- The CALL Command ---------------- FORMAT: CALL value1 PURPOSE: Executes a subroutine (see "The Code Command") PARAMETERS: value1 is the name of the subroutine The basic concepts of the CALL and CODE commands are discussed in the section entitled "The Code Command". -------------- Variable CALLs -------------- value1 will usually be a literal (e.g. CALL "Output Field"). However, it can also be a variable. For example: IF $FLINE[1] = "0" THEN routine = "Handle Type 0" ELSE "Handle Type 1" CALL routine This calls the subroutine "Handle Type 0" if the first character of $FLINE is "0". Otherwise, it calls the subroutine "Handle Type 1". An alternative to this approach is: 43 BEGIN $FLINE[1] = "0" (code to handle Type 1 records) ELSE (code to handle other types of records) END Both methods accomplish the same thing, so the one you choose is largely a matter of personal preference. In general, however, you should use CALL and CODE only when the same code is required in several different places in the POM file. There are some exceptions however, as described in the next section... ----------------------------- Making Your Technique Obvious ----------------------------- Consider this example: APPEND routine "Type" $FLINE[1] CALL routine You can use this method to call subroutines named "Type0", "Type1", "Type2" and so on, according to the first character of $FLINE. This can make your POM file a lot easier to understand. Additionally, you may sometimes want to break up large parsing jobs into distinct pieces. Thus, the main part of your POM file might read as follows: CALL "Break Up Fields" CALL "Clean Up Data" CALL "Send to Output" If each of these steps is quite long and involved, your POM file may be easier to read and understand by using CALL, as shown, to portray the basic steps. ------------------------------ Avoiding Unknown Code Sections ------------------------------ If you attempt to call a subroutine that does not exist, Parse-O-Matic will terminate with an error message, saying it can not find the CODE section. It is a good idea to check for this possibility, as in this example: LOG "012345" ~ $FLINE[1] "Unknown record type: " $FLINE[1] HALT "012345" ~ $FLINE[1] "Unknown record type -- see processing log" APPEND routine "Type" $FLINE[1] CALL routine This will provide a more meaningful error message if the first character of $FLINE is not one that you expected (zero through five, in the example given above). 44 ---------------- The CODE Command ---------------- FORMAT: The format of a subroutine is as follows: CODE value1 : Code run when this subroutine is invoked by the CALL command : END PURPOSE: Defines a subroutine PARAMETERS: value1 is the name of the subroutine NOTES: value1 can be up to 255 characters long and may contain any characters (including spaces). Case is not important, so "Read New Data" is treated the same as "READ NEW DATA". Leading and trailing spaces and tabs are ignored. Subroutines are useful when a POM file has to perform the same series of commands in several different circumstances. Consider this POM file: SET field = $FLINE[10 20] <-- Get a field CALL "Output Date Field" <-- Run a subroutine SET field = $FLINE[30 40] <-- Get a field CALL "Output Date Field" <-- Run a subroutine CODE "Output Date Field" <-- Start of subroutine <-+ CHANGE field " " "/" <-- Correct date format | CHANGE field "\" "/" <-- Correct date format | CHANGE field "-" "/" <-- Correct date format | Subroutine CVTCASE field field <-- Convert to uppercase | OUTEND |{field} <-- Output the field | END <-- End of subroutine <-+ In this example, the subroutine (named "Output Date Field") tidies up the data before sending it to the output file. For example, if the date field is "10 31 98", it is converted to "10/31/98". As you can see, subroutines can reduce the number of lines in a POM file. Also, if you give your subroutines meaningful names, your POM file will be much easier to understand. Subroutines also make it easier to update a POM file. For example, if you noticed that the date field is sometimes delimited with the "plus" symbol, you could simply add the line CHANGE field "+" "/" to the "Output Date Field" subroutine. In other words, you would add a single line of code instead of several lines. Subroutines are ignored by Parse-O-Matic unless they are explicitly invoked by a CALL command. 45 -------------------------- Performance Considerations -------------------------- If you have a POM file with a lot of subroutines, you can improve its performance slightly by moving all the CODE sections to the end of the file, and placing a DONE command in front of them. This saves Parse-O-Matic the trouble of reading through them each time it processes a line. ----------------------- Nested Subroutine Calls ----------------------- You can call a subroutine from within a subroutine. For example: CODE "Clean Up Date Field" CHANGE field " " "/" CHANGE field "\" "/" CHANGE field "-" "/" CVTCASE field field END CODE "Output Date Field" CALL "Clean Up Date Field" OUTEND |{field} END The second subroutine ("Output Date Field") calls the first subroutine ("Clean Up Date Field"). This feature is useful if several subroutines require the same processing. You must be careful not to have circular references (a subroutine that calls a subroutine which in turn calls the first subroutine). This will call Parse-O-Matic to fail. Subroutine calls can be nested up to 25 deep. That is to say, a subroutine can call a second subroutine, which can call a third subroutine, and so on, all the way up the 24th subroutine calling the 25th subroutine. It is, however, unlikely that you will ever nest subroutines more than two or three deep. ---------------------- Variable Code Sections ---------------------- You may be wondering if you can place a variable in the value1 position of the CODE command, just as you can have a variable CALL command. While it is possible to do so (i.e. Parse-O-Matic will not fail), we do not officially support this usage, as we see no reason for it. If you do find a reason for it, make sure that the variable is first converted to uppercase. 46 --------------------------------- A Note to Experienced Programmers --------------------------------- Experienced programmers of other languages (e.g. Pascal, C, Basic, etc.) may wonder if there is a way to pass one or more variables to a subroutine. Parse-O-Matic does not currently support traditional features such as functions, variable-passing or local variables. These features (and other niceties such as code libraries) may be added in a later release. Parse-O-Matic's design is guided primarily by customer demand. ---------------- The ELSE Command ---------------- FORMAT: The format of a BEGIN/ELSE/END block is as follows: BEGIN value1 [comparator] value2 : Code that is run if the comparison is true : ELSE : Code that is run if the comparison is false : END PURPOSE: The ELSE command tells Parse-O-Matic to execute the following block of code (up until the END command) if the corresponding BEGIN comparison is NOT true. NOTES: The ELSE command is not the same as the ELSE used to pad the IF statement (e.g. IF xyz = "3" THEN x = "Y" ELSE "N"). In the IF command, ELSE makes the statement more clear, but it can be omitted (e.g. IF $FLINE[1] "3" x "Y" "N"). Here is an example of a BEGIN/ELSE/END block: BEGIN $FLINE[1 10] = "JOHN SMITH" SET x = "This is John" ELSE SET x = "This is not John" END If you are using several levels of nesting, it is a good idea to indent your code to show the relationship of the BEGIN, ELSE and END statements: 47 BEGIN datatype = "Dog" <---------------------------------- SET breed = $FLINE[1 10] | First BEGIN breed = "Collie" <----------------------- | Level SET noise = "Woof" | Second | Block BEGIN name = "Spot" <------ Third | Level | SET attitude = "Friendly" | Level | Block | END <------ Block | | ELSE | | SET noise = "Arf" | | SET attitude = "Unknown" | | END <----------------------- | END <---------------------------------- The ELSE is at "Level 2". This is because there are three BEGINs ahead of it, but only one END (3 - 1 = 2). --------------- The END Command --------------- FORMAT: END PURPOSE: Marks the end of a BEGIN, PROLOGUE or EPILOGUE code block. The END command marks the end of a "code block". A code block is a series of lines in a POM file that may be run if the conditions are right. For a more detailed discussion of the END command, see the following sections: - "The Begin Command" - "The Prologue Command" - "The Epilogue Command" 48 ----------------- The AGAIN Command ----------------- FORMAT #1: BEGIN [value1 [comparator] value2] : Code executed if the BEGIN comparison is true or omitted : AGAIN [value1 [comparator] value2] FORMAT #2: BEGIN value1 [comparator] value2 : Code executed if the BEGIN comparison is true : ELSE : Code executed if the BEGIN comparison is false : AGAIN [value1 [comparator] value2] PURPOSE: Controls the repetition of a BEGIN block. NOTES: For an explanation of comparators, see "Using Comparators". SEE ALSO: "The ReadNext Command", "The Begin Command", "The Else Command" and "Uninitialized and Persistent Variables" DEFAULTS: If the comparison part of the AGAIN command is omitted: - AGAIN repeats if the BEGIN comparison was true or omitted - AGAIN does not repeat if the BEGIN comparison was false ADVISORY: If you are familiar with other computer languages, you may be tempted to use AGAIN to create loops when none are required. Remember that a POM file is repeated (i.e. looped) each time a record or line is read from the input file. The AGAIN command is most appropriate when you have input records with a variable number of items. The AGAIN command allows you to implement "loops". A loop is a section of code that can be repeated one or more times. AGAIN returns to the corresponding BEGIN if the comparison is true, or if it is omitted. Since the BEGIN can also have a comparison, and can be used with the ELSE command, this allows many variations: 49 COMMAND ARRANGEMENT EFFECT ------------------------------ ----------------------------------------- BEGIN AGAIN Loops forever BEGIN comp AGAIN Loops until the BEGIN comparison is false BEGIN AGAIN comp Loops until the AGAIN comparison is false BEGIN comp AGAIN comp Loops until either comparison is false BEGIN comp ELSE AGAIN comp Loops until either comparison is false BEGIN comp ELSE AGAIN Loops until the BEGIN comparison is false In the last two examples, the ELSE code is run when the BEGIN comparison is false, then processing continues on the POM line after the AGAIN command. When a BEGIN comparison is false, the comparison (if any) of the AGAIN command is not evaluated. To put it another way: the AGAIN comparison is considered only if the BEGIN comparison is true or omitted. ------------------------------------ Using AGAIN for Variable-Length Data ------------------------------------ Let us say you have a text file that contains the names of people belonging to various clubs. The file lists the name of the club, then the number of people in each club, and then the names: Chess Club 3 John Smith Mary Jones Fred Williams Hopscotch Club 0 Tennis Club 2 Jack Martin Debbie Harris 50 You could process this input file with the following POM file: PAD $FLINE "R" " " "17" <-- Pad the club name out with spaces OUT |{$FLINE} <-- Send the club name to the output file READNEXT <-- Get the number of members SET members = $FLINE <-- Remember this number BEGIN members = "0" <-- Check if we have any members OUT |(None) <-- Report if we have no members ELSE <-- If we have members, do the next part SET count = "0" <-- Initialize a counter BEGIN <-- Start the loop READNEXT <-- Get the person's name SET count = count+ <-- Count this person OUT |{$FLINE} <-- Send the name to the file OUT count #< members |/ <-- Add a separator if not the last name AGAIN count #< members <-- Go back if we have more members END <-- Corresponds to the first BEGIN OUTEND | <-- Start a new line after each club This POM file would generate the following output: Chess Club John Smith/Mary Jones/Fred Williams Hopscotch Club (None) Tennis Club Jack Martin/Debbie Harris ------------------------------ Pointless Command Combinations ------------------------------ Some combinations of BEGIN, ELSE and AGAIN are pointless. The following command arrangements contain code that is never run: COMMAND ARRANGEMENT NOTE ------------------------------ ------------------------------------------ BEGIN ELSE AGAIN comp The ELSE portion is never executed BEGIN ELSE AGAIN Loops forever; the ELSE portion never runs 51 -------- Examples -------- Either of these two POM files will read a text file and ignore any lines that contain the words "COW": Using the AGAIN Command Using the IGNORE Command ----------------------- ------------------------ BEGIN $FLINE ^ "COW" IGNORE $FLINE ^ "COW" READNEXT OUTEND |{$FLINE} AGAIN OUTEND |{$FLINE} The shorter POM file is more efficient, but the results would be the roughly the same for both. Remember that a POM file is processed each time Parse-O-Matic reads an input record (or line), so the second version is, in effect, looping as many times as there are records in the file. The following POM file will read one line from a file, then send the string [6]123[7]123[6]123[7]123 to the output file: SET z = "0" BEGIN <----------------------------- SET y = "5" | First BEGIN y <> "7" <------------------ | Level SET x = "0" | Second | (Outermost) SET y = y+ | Level | Loop APPEND s s "[" y "]" | Loop | BEGIN x <> "3" <-------- | | SET x = x+ | Third | | APPEND s s x | Level | | AGAIN <-------- | | AGAIN <------------------ | SET z = z+ | AGAIN z <> "2" <----------------------------- OUTEND |{s} NEXTFILE The third level (innermost) loop ... generates 123 The second level (middle) loop ..... generates [6]123[7]123 The first level (outermost) loop ... generates [6]123[7]123[6]123[7]123 52 The following POM file will read one line from a file, then send the string "XXXY" to the output file: SET z = "0" <-- Initialize a counter SET s = "" <-- Initialize the string we will output BEGIN z < "3" <-- Check if the counter has reached "3" SET z = z+ <-- Add one to the counter APPEND s s "X" <-- Add an "X" to the end of the output string ELSE /__ The ELSE section is run when APPEND s s "Y" \ the BEGIN comparison is false AGAIN <-- Go back to the BEGIN OUTEND |{s} <-- Continue here after the ELSE portion NEXTFILE <-- Stop reading the input file ---------------- The DONE Command ---------------- FORMAT: DONE [value1 [comparator] value2] PURPOSE: The DONE command will discontinue processing the POM file and proceed to the next input line, whereupon the POM file will restart at the top. NOTES: For an explanation of comparators, see "Using Comparators". In the following explanation, we will demonstrate the command using only the "literally identical" ("=") comparator. ALTERNATIVES: The NEXTFILE, IGNORE and ACCEPT commands The DONE command is most useful when you have a long series of BEGIN/END blocks which make a related comparison. For example: 53 SET salesrep = $FLINE[11 50] SET region = $FLINE[ 1 2] BEGIN region = "US" OUTEND |Sales representative for U.S.A.: {salesrep} DONE END BEGIN region = "CN" OUTEND |Sales representative for Canada: {salesrep} DONE END BEGIN region = "EU" OUTEND |Sales representative for Europe: {salesrep} DONE END : etc. As you can see, if one of the BEGIN comparisons is true, all of the following ones will inevitably be false. Rather than processing all the others, you can use the DONE command to bail out and get ready for the next input line. The DONE command provides two benefits: - It can speed up processing slightly - It makes full traces easier to understand For an explanation of traces, see the section entitled "Tracing". Unless you use a comparison (explained later), the DONE command is useful only inside BEGIN/ELSE/END blocks. If you write a POM file like this: SET custnum = $FLINE[ 1 10] SET custname = $FLINE[11 50] DONE OUTEND |{custname} {custnum} then the OUTEND statement will NEVER be reached. Here is how you specify a comparison for the DONE command: DONE $FLINE = "End of Data" This discontinues the POM file, and proceeds to the next input line, if the current input line ($FLINE) is "End of Data". 54 -------------------- The NEXTFILE Command -------------------- FORMAT: NEXTFILE [value [comparator] value] PURPOSE: NEXTFILE discontinues processing the current input file and proceeds to the next one, restarting the POM file from the top. NOTES: For an explanation of comparators, see "Using Comparators". In the following explanation, we will demonstrate the command using only the "literally identical" ("=") comparator. ALTERNATIVES: The HALT command The NEXTFILE command is useful when you process multiple input files (see "POM and Wildcards"). Here is an example, which we will call TEST.POM: BEGIN $FLINE = "End of Data" OUTEND |{numlines} lines of data printed SET numlines = "" NEXTFILE END SET numlines = numlines+ OUTEND |{$FLINE} Let's say you have three text files: DATA1.XYZ, DATA2.XYZ and DATA3.XYZ. The last line of each file says "End of Data". You could copy all three files to the file OUTPUT.TXT with this command: POM TEST.POM DATA?.XYZ OUTPUT.TXT This would copy the data from each file, but when it gets to the line reading "End of Data", it records the number of lines of data that were printed. Any lines after the "End of Data" line are skipped, because of the NEXTFILE command. The NEXTFILE command can specify a comparison. Here is an example: NEXTFILE $FLINE = "End of Data" OUTEND |{$FLINE} Assuming the same input files (DATA1.XYZ etc.), and using the same POM command as last time, this POM file would simply copy up to (but not including" the line that reads "End of Data" in each input file. 55 ---------------- The HALT Command ---------------- FORMAT: HALT value1 comparison value2 value3 [value4] PURPOSE: The HALT command will terminate Parse-O-Matic processing if the comparison is true. PARAMETERS: value1 is any value value2 is any value value3 is the message to be displayed value4 is the optional error level (between 100 to 199) NUMERICS: Tabs, spaces and commas are stripped from value4 ALTERNATIVES: The NEXTFILE and SETERROR commands SEE ALSO: "The MsgWait Command" Here is an example of the HALT command: HALT sales = "0" "Zero sales!" If the variable named sales is "0", Parse-O-Matic will display an error box reading "Zero sales!" and terminate after you have pressed a key. A copy of the message is also placed in the processing log POMLOG.TXT (see "Logging"). When a HALT condition occurs, Parse-O-Matic terminates with a DOS error level of 100. You can specify a different value, using value4. This is useful if you are calling Parse-O-Matic from a batch file or application program and want to handle different errors in different ways. You can set value4 to any number between 100 and 199. Consider these examples: HALT sales = "0" "Zero sales" "150" HALT sales[1] = "-" "Negative sales" "160" This terminates Parse-O-Matic with an error level of 150 if sales are zero. If the first character of sales is a minus sign, Parse-O-Matic terminates with an error level of 160. When coding batch files, remember that the IF ERRORLEVEL command is considered "True" if the error is the specified value or higher. This means you should always test the higher value first. See your operating system manual for details. 56 -------------------- The SETERROR Command -------------------- FORMAT: SETERROR [value1 comparison value2] value3 PURPOSE: The SETERROR command will set the program return code if the comparison is true (or if it is omitted). PARAMETERS: value1 is any value value2 is any value value3 is the program return code value (between 100 to 199) NUMERICS: Tabs, spaces and commas are stripped from value3 ALTERNATIVES: The HALT command The SETERROR command sets the program return code, which you can check when Parse-O-Matic has completed processing. This lets you pass information back to the batch file or program that called Parse-O-Matic. When coding batch files, remember that the IF ERRORLEVEL command is considered "True" if the error is the specified value or higher. This means you should always test the higher value first. See your operating system manual for details. Here is a sample POM file, which we will name ERRTEST.POM: SET custname = $FLINE[ 1 20] SET owed = $FLINE[25 30] SET status = $FLINE[62 68] SETERROR status = "OVERDUE" "100" OUTEND |{custname} {owed} {status} Here is a sample batch file that uses ERRTEST.POM: @ECHO OFF POM ERRTEST.POM INPUT.TXT OUTPUT.TXT IF ERRORLEVEL 200 GOTO PERR IF ERRORLEVEL 100 GOTO OVERDUE GOTO QUIT :PERR ECHO A syntax or processing error was detected by Parse-O-Matic GOTO QUIT :OVERDUE ECHO We have at least one overdue account :QUIT 57 -------------------- The PROLOGUE Command -------------------- FORMAT: The format for PROLOGUE (used with the END command) is: PROLOGUE : Dependant code : END PURPOSE: PROLOGUE defines dependant code which is run before the first line of the input file is read. SEE ALSO: "The Epilogue Command" PROLOGUE can be used to set up some variables, or set up a heading -- anything you only want to do once per input file, at the very start. Here is an example of the PROLOGUE command: PROLOGUE SET both = "B" SET space = " " END SET firstname = $FLINE[ 1 10] SET lastname = $FLINE[15 25] TRIM firstname both space TRIM lastname both space OUTEND |{firstname} {lastname} When the input file is first opened, the PROLOGUE section sets the variables "both" and "space". Once they're set, you don't have to change them (since you are just using them to make the code easier to read). Thus, it makes sense to set them only at the beginning of processing and not bother setting them each time the POM file is executed (i.e. each time an input line is read). If you are working with multiple files (see "POM and Wildcards"), the PROLOGUE is run for each input file. If you want to run some code for the first file only, you can set a "flag", as in this example: 58 BEGIN firstfile = "" SET firstfile = "N" OUTEND |First file only ELSE OUTEND |Subsequent files END NEXTFILE If you run this POM file on several files at once, using wildcards, the first line of the output file will contain the words "First file only", since the variable "firstfile" has not yet been assigned a value. On subsequent files, the variable will have the value "N", so the following lines of the output file will read "Subsequent files". -------------------- The EPILOGUE Command -------------------- FORMAT: The format for EPILOGUE (used with the END command) is: EPILOGUE : Dependant code : END PURPOSE: EPILOGUE defines dependant code which is run after the last line of the input file is read and the POM file is executed to process it. In other words, once all the input data is finished, the POM file runs one last time -- but only the code in the EPILOGUE section. SEE ALSO: "The Prologue Command" You can use EPILOGUE to output final results. Let's say your input file looks like this: DESCRIPTION UNITS SOLD UNIT PRICE Wildebeest food 325 $ 9.99 Horse cologne 13 $ 3.25 Moose alarm 210 $ 5.95 : : : : : (Column positions) 1 18 27 33 41 You can find out the total number of units sold (of all types) with the following POM file: 59 IGNORE $FLINE[1 7] = "DESCRIP" CALC units = units "+" $FLINE[18 27] EPILOGUE OUTEND |Total units sold = {units} END This POM file adds up the number of units sold. The only output is the single line generated by the OUTEND in the EPILOGUE. If you are processing multiple files (see "POM and Wildcards"), the EPILOGUE is run after each input file is finished. 60 ============================================================================ VARIABLE MODIFIERS ============================================================================ ---------------- The TRIM Command ---------------- FORMAT: TRIM var1 value1 value2 PURPOSE: TRIM removes the character in value2 from var1. PARAMETERS: var1 is the variable being set value1 is "A" = All; "B" = Both ends; "L" = Left side only; "R" = Right side only; "M" = Multiples value2 is the character to be removed. ALTERNATIVES: The SET, CHANGE and REMAP commands The TRIM command gets rid of unwanted characters in a variable. It is typically used to remove blanks from either side of text, or leading zeros from numeric data. For example, to remove commas and the leading dollar sign from a number: SET PRICE = $FLINE[20 26] <-- Get the variable from the input file TRIM PRICE "A" "," <-- Trim All TRIM PRICE "L" "$" <-- Trim Left Here is how it works: If the input contains the string: "$25,783" The first TRIM changes it to: "$25783" The second TRIM changes it to: "25783" You can also squeeze out multiple occurrences of a given character. For example, to remove multiple spaces from a variable named xyz, use this command: TRIM xyz "M" " " If xyz has the value " A B C ", the command shown above changes it to " A B C ". You can then get rid of the spaces at both ends with this command: TRIM xyz "B" " " This changes the xyz variable to "A B C". 61 --------------- The PAD Command --------------- FORMAT: PAD var1 value1 value2 value3 : : : : MEANING: Variable Control Char Number PURPOSE: PAD makes var1 a specified length, padded with a specified character. PARAMETERS: var1 is the variable being set value1 is "L", "R", or "C" (Left, Right or Center) value2 is the character used to pad the string value3 is the desired string length NUMERICS: Tabs, spaces and commas are stripped from value3 ALTERNATIVES: The CHANGE command Here is an example of the PAD command. If the variable ABC is already set to "1234" ... PAD ABC "L" "0" "7" left-pads it 7 characters wide with zeros ("0001234") PAD ABC "R" " " "5" right-pads it 5 characters wide with spaces ("1234 ") PAD ABC "C" "*" "8" centers it, 8 wide, with asterisks ("**1234**") If the length is less than the length of the string, it is unchanged. For example, if you set variable XYZ to "PINNACLE", then PAD XYZ "R" " " "3" leaves the string as-is ("PINNACLE"). Thus, PAD can not be used to shorten a string. If it is your intention to make XYZ 3 letters long, you can use the SET command: SET XYZ = XYZ[1 3] ------------------ The CHANGE Command ------------------ FORMAT: CHANGE var1 value1 value2 PURPOSE: The CHANGE command replaces ALL occurrences of value1 with value2. ALTERNATIVES: The TRIM command. (The CHANGE command is more powerful than TRIM, but is not as efficient). 62 Here is an example of the CHANGE command in action: SET DATE = $FLINE[31 38] CHANGE DATE "/" "--" If the SET command assigns DATE the value: "93/10/15" Then the CHANGE command converts it to: "93--10--15" ------------------- The CVTCASE Command ------------------- FORMAT: CVTCASE var1 value1 [value2] PURPOSE: CVTCASE converts a value to uppercase or lowercase. PARAMETERS: var1 is the variable being set value1 is the value being converted value2 is the optional control setting DEFAULTS: value2 = "UI" ALTERNATIVES: The PROPER or REMAP commands; $FLUPC CVTCASE converts value1 to uppercase or lowercase and places the result in var1. Here are some examples: COMMAND DESCRIPTION --------------------------- -------------------------------- CVTCASE xyz "Test Case" "U" Sets variable xyz to "TEST CASE" CVTCASE xyz "Test Case" "L" Sets variable xyz to "test case" CVTCASE xyz "Test Case" Sets variable xyz to "TEST CASE" In the last example, the optional control parameter (value2) was omitted. In such case, CVTCASE will convert the value to uppercase. 63 ---------------- Control Settings ---------------- The control setting (value2) can be one or two characters long, or it can be omitted (in which case it is assumed to be "UI"). Here are the available settings for value2: SETTING CONVERT TO CHARACTER SET ------- ---------- ------------------ "L" Lowercase IBM Extended ASCII "LI" Lowercase IBM Extended ASCII "L7" Lowercase 7-bit ASCII "U" Uppercase IBM Extended ASCII "UI" Uppercase IBM Extended ASCII "U7" Uppercase 7-bit ASCII The IBM Extended ASCII character set defines diacritical (accented) characters such as "U Umlaut" and "C Cedille"; these are located in the ASCII table above value 127. It is the standard character set used by MS-DOS and PC-DOS. The 7-bit ASCII character set is concerned only with the characters in the original definition of ASCII (American Standard Code for Information Interchange), which does not support diacritical characters. As such, uppercasing and lowercasing affect only alphabetic characters ("A" to "Z", and "a" to "z"). This character set is used by many mini-computers, and is the standard character set of the Unix operating system. The eighth bit is not ignored if you use CVTCASE with the 7-bit ASCII character set. If you wish to set the eighth bit to zero (perhaps because it is a parity bit), you should use the REMAP command. ------------------ The PROPER Command ------------------ FORMAT: PROPER var1 [value1 [value2]] PURPOSE: The PROPER command converts uppercase text (LIKE THIS) to mixed-case text (Like This). PARAMETERS: var1 is the variable being set value1 is the methods setting value2 is the name of the Properization Exception File DEFAULTS: value1 = "IW" ALTERNATIVES: The CHANGE command; $FLUPC (uppercase version of $FLINE) 64 The PROPER command is useful when you have a list of names of people and addresses. You can also use PROPER to change text that has been typed in uppercase into normal text, with capital letters at the beginning of sentences. The simplest way to convert a variable is as follows: PROPER CustName If CustName contains "JOHN SMITH", it will be changed to "John Smith". The conversion routine is fairly intelligent. For example, if it is converting the words "JAGUAR XJS", it can tell that XJS is not a word (since it does not contain any vowels) and so the end result will be "Jaguar XJS". Other "strange-looking" items such as serial numbers can often be recognized by the PROPER command, and left untouched. Nevertheless, it is impossible to handle all situations, so the PROPER command supports a "Properization Exceptions File" (known as a PEF file). A PEF file lists unusual combinations of letters (typically abbreviations, such as Dr.). The Parse-O-Matic package includes a file named GENERIC.PEF, which you may find helpful. You can view it with the SEE program provided with Parse-O-Matic. A PEF file is prepared with a text editor and contains one "exception" per line. Null or blank lines, or lines that start with a semicolon, are ignored. The longest word that can be specified is 255 characters. Spaces are permitted, but leading and trailing spaces and tabs are ignored. To use the PEF file in your PROPER command, place the file name after the variable name and method setting. For example: PROPER CustName "W" "GENERIC.PEF" The "W" is the method setting (explained later). "GENERIC.PEF" is the name of the PEF file. When Parse-O-Matic looks for the PEF file, it looks for it in the current directory unless an explicit path is specified, then searches elsewhere, if necessary. (For details, see the section entitled "How Parse-O-Matic Searches for a File".) If it can not find it there, it looks in the directory where POM.EXE is located. You can, if you wish, specify a complete path to the file, as in this example: PROPER Address "W" "C:\MYFILES\MYPEF.XYZ" If you don't need an exceptions file, you should not use it, since it slows down processing somewhat. Needless to say, the more items you have in the PEF file, the more it slows down processing. 65 The method setting allows you to specify what PROPER does. There are several kinds of controls, as follows: METHOD DESCRIPTION ------ ----------- I Intelligent determination of non-words S Upcase the first character of each sentence U Upcase the first alphanumeric character of the line W Upcase the first letter of each word The default method setting is "IW", so if you omit the method setting, or specify a null setting (e.g. PROPER CustName "" "XYZ.PEF"), PROPER will upcase non-words, and the first letter of each word. NOTE: If you specify a PEF file, you must also specify a method setting, even if it is null. The line PROPER x "GENERIC.PEF" would not be understood by Parse-O-Matic. The correct format would be: PROPER x "" "GENERIC.PEF" The examples provided with Parse-O-Matic demonstrate some ways you can use the PROPER command. To see the examples, enter INFO at the DOS prompt, or run INFO.BAT from Windows, then select TUTORIAL. ------------------ The INSERT Command ------------------ FORMAT: INSERT var1 value1 value2 PURPOSE: The INSERT command inserts text on the left or right of var1, or at a "found text" position. PARAMETERS: var1 is the variable being set value1 is "L" or "R" (Left or Right) or a find-string (e.g. "<HELLO") value2 is the value to be inserted ALTERNATIVES: The APPEND and CHANGE commands 66 For example, if the variable ABC is set to "Parse-O-Matic", then INSERT ABC "L" "Register " sets ABC to "Register Parse-O-Matic" INSERT ABC "R" " is super" sets ABC to "Parse-O-Matic is super" You can use a find-string to insert text either before or after the first occurrence of the text you specify. For example, if the variable xyz is set to "One a day", then INSERT xyz "<e" "c" sets xyz to "Once a day" INSERT xyz ">One " "hour " sets xyz to "One hour a day" The < prefix means "insert value1 before the found text". The > prefix means "insert value1 after the found text". If the find-string is not found, nothing is done. NOTE: Prior to version 3.40 of Parse-O-Matic, the "insert before" opera- tion was denoted by the @ prefix rather than the < prefix. This still works, so you do not have to change your POM files. ------------------ The APPEND Command ------------------ FORMAT: APPEND var1 value1 value2 [value3 [value4]] PURPOSE: The APPEND command concatenates (adds together) two or more values and places the result in var1. NOTES: No variable can hold more than 255 characters. ALTERNATIVES: The INSERT command Here is an example of the APPEND command: APPEND xyz "AB" "CD" "EF" "GHIJ" This command sets the variable xyz to "ABCDEFGHIJ". The third and fourth values (value3 and value4 in the FORMAT shown above) are optional. Thus, you can use APPEND with only two values. For example: SET x1 = "AB" SET x2 = "CD" APPEND x3 x1 x2 This sets the variable x3 to "ABCD". You can concatenate a maximum of four values with a single APPEND command. If you require additional concaten- ations, you can use more APPEND commands: 67 APPEND myvar "ABC" "DEF" "GHI" "JKL" APPEND myvar myvar "MNO" "PQR" The first line sets the variable myvar to "ABCDEFGHIJKL". The second line set myvar to its previous value, plus "MNOPQR", so that its final value is "ABCDEFGHIJKLMNOPQR". ------------------- The OVERLAY Command ------------------- FORMAT: OVERLAY var1 value1 value2 PURPOSE: The OVERLAY command overwrites a portion of a variable with a value, at the specified position. The length of the variable is padded with spaces if necessary. PARAMETERS: var1 is the variable to be overwritten value1 is the data which will be placed into var1 value2 is the position, in var1, where value1 will be placed NOTES: No variable can hold more than 255 characters. NUMERICS: Tabs, spaces and commas are stripped from value2 value2 must be between "1" and "255" SEE ALSO: "The Append Command" and "The Insert Command" The OVERLAY command lets you replace part of a variable, starting at a particular position. Here is an example: SET x = "ABCDEFG" SET y = "pom" OVERLAY x y "4" This will change the x variable so it contains "ABCpomG", since it places the "pom" at position "4". If value2 is greater than the length of var1, var1 is padded with spaces to allow value2 to be placed at the specified position. For example: SET x = "ABCDEFG" SET y = "pom" OVERLAY x y "10" This will change the x variable to "ABCDEFG pom". Since var1 was less than 10 characters, it had to be extended to allow the "pom" to start in position "10". 68 Since no variable can be more than 255 characters, OVERLAY will truncate the result if it extends beyond that: SET x = "ABCDEFG" SET y = "pom" OVERLAY x y "254" The x variable will be 255 characters long (starting with "ABCDEFG", followed by many spaces) and end with "po", since the "p" is in position "254" and the "o" is in the last legal position (i.e. "255"). Here are some additional examples: SET x = "" <-- Set x to a null (empty) string OVERLAY x "ABC" "1" <-- Set x to "ABC" (i.e. the "A" is at position "1") OVERLAY x "DEF" "4" <-- Change x from "ABC" to "ABCDEF" OVERLAY x "IJ" "9" <-- Change x to "ABCDEF IJ" OVERLAY x "GH" "7" <-- Change x to "ABCDEFGHIJ" ------------- Simple Arrays ------------- You can use OVERLAY to perform some simple array processing, provided the total length of the data items does not exceed 255 characters. For example, you could store 25 items of up to 10 characters each in a 250-character variable. Here is a helpful subroutine (see "The Code Command") for this kind of operation: CODE "Calc Array Indexes" SET ItemSize = "10" CALC IndexStart = Index- "*" ItemSize CALC IndexEnd = IndexStart "+" ItemSize SET IndexStart = IndexStart+ END This will provide pointers for an array of 25 items of up to 10 characters each, with indexes of 1 to 10. You can use this information with both the OVERLAY and COPY commands. You could extract the 15th item as follows: SET Index = "15" CALL "Calc Array Indexes" COPY x MyArray IndexStart IndexEnd For a more sophisticated and flexible method of handling arrays, see "Array Variables". 69 ------------------- The MAPFILE Command ------------------- FORMAT: value1 value2 [value3] PURPOSE: MAPFILE reads a file containing data for the REMAP command PARAMETERS: value1 is the name of the map file value2 is the map name, used by the REMAP command value3 is the control settings (AnyCase/MatchCase/Transpose) DEFAULTS: value3 = "MATCHCASE" NOTES: The maximum length of a map name is 12 characters SEE ALSO: "The Remap Command", "How Parse-O-Matic Searches for a File" The MAPFILE command reads in a file which contains data for the REMAP command, and assigns a name to the collection of data so the REMAP command can refer to it. ------------------- What is a Map File? ------------------- A map file is an ordinary text file; you can create or edit the file with a standard text editor, or a word-processor in "generic text" mode. Map files are usually given the .MPF extension. A map file contains a list of "mappings". Here are some other words with approximately the same meaning as "mapping": Translation Correlation Substitution Equivalence Replacement In other words, the map file contains a list of data items that should be replaced by other data items. ---------------- Sample Map Files ---------------- The following map files are included in the standard Parse-O-Matic package: FILE NAME DESCRIPTION ------------ ---------------------------------------------------------- BIN2CHAR.MPF Converts binary data into printable characters and periods BIN2CODE.MPF Converts binary data into hex codes (e.g. 3F 2C A3) ASC2EBCD.MPF Converts ASCII data to EBCDIC and vice-versa 70 --------------- Map File Format --------------- The map file contains one mapping per line. Each mapping consists of two Parse-O-Matic literals, separated by one or more spaces or tabs. The first value is the "find" column, while the second value is the "replace" column. Here are some examples: "123" "LOS ANGELES" <-- Both values are "literal text strings" $39 "9" <-- A hex code and a literal text string #48 "Zero" <-- A decimal code and a literal text string $FF$30 #00#00 <-- Hex and decimal literals These columns are lined up for clarity; there is no need to start in a particular column. Any leading or trailing spaces are removed from a line, and any number of spaces or tabs can appear between the columns. The following line is NOT valid: 123 LOS ANGELES The line must use text, hex or decimal literals (e.g. "text", $FF, #FF). Null or blank lines, or lines that start with a semicolon, are ignored. The longest line that can be specified is 255 characters. The longest value that can be specified is 80 characters (after translation, if it is in hex or decimal mode). ------------ Search Order ------------ The REMAP command performs substitutions in the order that they appear in the map file. In most cases, the longer "find" strings should appear first. For example, let us say you create a map file named FORWARD.MPF, which looks like this: "123" "in Los Angeles" "12" "in Montreal" "1" "in Town of Mount Royal" "2" "in Podunk" 71 Now let's say you run the following POM file, named FORWARD.POM: MAPFILE "FORWARD" SET comment = "Forward the memo to office 123" REMAP comment OUTEND |{comment} This will produce the following output: Forward the memo to office in Los Angeles This happens because the string "123" is replaced by the string "in Los Angeles". If the order of the lines in FORWARD.MPF are reversed, FORWARD.POM will produce the following output: Forward memo to Office in Town of Mount RoyalinPodunk3 This happens because the "1" is found (and replaced) first, followed by the "2". Since there is no "3" in FORWARD.MPF, it is left alone. Parse-O-Matic does NOT enforce the principle of "progressively shorter 'find' strings". If you are processing a lot of data, you can improve processing speed slightly by placing a short, frequently-used "find" string near the top of the list. As long as it is not a sub-string of (i.e. contained within) one of the following strings, it will not cause any problems. 72 ------------- Case Matching ------------- You can set value3 to "AnyCase" or "MatchCase" (the default). ANYCASE: The find string need not match in case ("John" = "JOHN") MATCHCASE: The find string must match ("John" does not match "JOHN") Processing is faster if you use the default setting (MatchCase). --------------- Reverse Mapping --------------- If you want the mapping process to work "backwards", you can use the "Transpose" control setting in value3. For example: MAPFILE "MYFILE.MPF" "MYFILE" "AnyCase Transpose" This reverses the mapping process: the "find" column is treated like the "replace with" column, and vice-versa. The standard Parse-O-Matic package contains a map file (ASC2EBCD.MPF) which will translate ASCII files into EBCDIC files -- and vice-versa. NOTE: EBCDIC is a character representation used on certain large mainframe computers. Both ASCII and EBCDIC characters are eight bits long, but EBCDIC uses different bit patterns for most characters. Since both the "find" and "replace with" columns in ASC2EBCD.MPF are only one character wide, and since there is no duplication within either column, the translation process is perfectly reversible. For example: 73 PROLOGUE CHOP 1 20 <-- Read 20 bytes at a time MAPFILE "ASC2EBCD.MPF" "EBCDIC" <-+ MAPFILE "ASC2EBCD.MPF" "ASCII" "TRANSPOSE" | Set up maps MAPFILE "BIN2CODE.MPF" "CODE" <-+ END SET x = $FLINE <-+ REMAP x "CODE" | Display original text in OUTEND |[ORIGINAL] [{$FLINE}] | normal & hex-coded form OUTEND |[ORIGINAL] [{x}] <-+ REMAP $FLINE "EBCDIC" <-+ SET x = $FLINE | Convert to EBCDIC and REMAP x "CODE" | display in coded form OUTEND |[EBCDIC ] [{x}] <-+ REMAP $FLINE "ASCII" <-+ SET x = $FLINE | Convert EBCDIC back to REMAP x "CODE" | ASCII; display hex code OUTEND |[ASCII ] [{x}] <-+ OUTEND | <-- Output a separator line You can run this POM file against any file, then view the output file. You will see how the original text is converted into EBCDIC and then the EBCDIC is converted back to ASCII. (Most of the data in the output file is represented in "hex dump" format, since your computer is not designed to display EBCDIC.) TRANSPOSE will often let you use a single map file instead of two, but before using this technique you should carefully consider how mapping will take place (see "Irreversible Mapping", below). -------------------- Irreversible Mapping -------------------- Consider the following POM file: MAPFILE "MYMAP.MPF" "XYZ" MAPFILE "MYMAP.MPF" "ZYX" "TRANSPOSE" REMAP $FLINE "XYZ" REMAP $FLINE "ZYX" OUTEND |{$FLINE} In many cases, this is equivalent to the following one-line POM file: OUTEND |{$FLINE} because the first REMAP changes $FLINE one way, and the second REMAP changes it back. 74 This is not true in ALL cases, however. In some circumstances a REMAP is not reversible. Consider the following map file: "XYZ" "CAB" "ABC" "C" "DEF" "ABC" Now consider the following sequence of events. (The * and # characters show what gets replaced in each step.) Original string . . . . . . . . . ABCDEF ***### *### Remap produces this result . . . . CABC *** *** Transposed remap of result . . . . XYZC If you follow the steps of the substitutions, you will see where the confusion arises. As a general rule, simple substitutions (with no duplications in whole or in part) are reversible, but if you have any doubts, you can always take the safe route and use a separate map file for each direction. (See "Search Order", above, for additional insight into this matter.) ------------------ Memory Limitations ------------------ The MAPFILE command reads the map data into RAM memory. You will normally have sufficient memory for thousands of bytes worth of mappings. However, if you do not have enough memory to hold the data, Parse-O-Matic will display an error message, then terminate. (See "Solving Memory Problems") To help you track memory usage, the MAPFILE command records memory status (bytes used and bytes left) in the processing log (see "Logging"). ----------------------- An Example of Remapping ----------------------- The standard Parse-O-Matic package contains two sample map files: BIN2CODE.MPF maps single bytes to hex codes (e.g. Hex $31 becomes "31 ") BIN2CHAR.MPF maps single bytes to either printable characters or periods You can view these files with the SEE program (included with Parse-O-Matic) or you can load them into a text editor program. Here is a POM file that uses the sample map files to create a hex dump of a binary file: 75 CHOP 1 16 <-- Read the file 16 bytes at a time SETLEN w $FLINE <-- Get the actual number of bytes read BEGIN w <> "16" PAD $FLINE "R" #0 "16" <-- If less than 16 bytes, pad with nulls END SET x = $FLINE <-- Make a copy of $FLINE SET y = $FLINE <-- Make a copy of $FLINE MAPFILE "BIN2CHAR" "CHAR" <-- See Note MAPFILE "BIN2CODE.MPF" "CODE" REMAP x "CHAR" <-- Change the bytes to printable characters REMAP y "CODE" <-- Change the bytes to hex codes OUTEND |x y <-- Output the line Note: Since the file name (value1) does not have an extension, Parse-O-Matic will add the .MPF extension. Thus, the actual file name Parse-O-Matic looks for is "BIN2CHAR.MPF". ----------------- The REMAP Command ----------------- FORMAT: REMAP var1 value1 PURPOSE: REMAP transforms sub-strings into other strings PARAMETERS: var1 is the variable being transformed value1 is the map name (see "The MapFile Command") ALTERNATIVES: The LOOKUP and CHANGE commands SEE ALSO: "The MapFile Command" The REMAP command performs intensive substitutions on a variable. It is equivalent to a large number of CHANGE commands, but has the following advantages: - It is faster than using a large number of CHANGEs - It does not expend your available values (see "Values") - It prevents multiple substitutions 76 ------------------- REMAP Versus CHANGE ------------------- The "multiple substitution" issue is most important distinction between CHANGE and REMAP. REMAP protects substituted text from being resubstituted. Consider the following POM lines: SET x = "cat dog mouse" CHANGE x "cat" "dog" CHANGE x "dog" "cat" You might expect these lines to change x to "Dog Cat Mouse", but the actual result is "cat cat mouse". The first CHANGE command sets the x variable to "dog dog mouse". The next command changes the dogs into cats! You can avoid this problem by using intermediate substitutions or some such work-around, but this ends up complicating the POM file considerably. Moreover, this approach can be unwieldy if you have to perform a large number of substitutions. ----------- Using REMAP ----------- To accomplish the "cat/dog" substitution mentioned earlier, you can create a map file (named CATDOG.MPF) with a text editor. It will look like this: "cat" "dog" "dog" "cat" Your POM file will then look like this: MAPFILE "CATDOG.MPF" "PETS" SET x = "cat dog mouse" REMAP x "PETS" This will change the x variable to "dog cat mouse". For another example of the REMAP command, see "The MapFile Command". 77 ============================================================================ FREE-FORM COMMANDS ============================================================================ ---------------------------- What are Free-Form Commands? ---------------------------- The free-form commands are used for extracting information from an input line that does not have its data in precise columns. Consider the following input file: Mouse Gazelle Mouse Elephant Dog Giraffe Elk Mongoose Monkey Snake Caribou Trout | | | | Column 1 Col 11 Col 21 Col 31 Extracting data that is arranged in tidy columns is simple -- all you need is the SET command. However, you will need a more powerful command if the data is "free-form", like this: Mouse,Gazelle,Mouse,Elephant Dog,Giraffe,Elk,Mongoose Monkey,Snake,Caribou,Trout The data is not arranged in tidy columns. For tasks like this, you need the free-form commands. ----------------- The PARSE Command ----------------- FORMAT: PARSE var1 value1 value2 value3 [value4] : : : : : MEANING: Variable Source From To Control PURPOSE: PARSE sets var1 to the text (found in value1) between text fragments specified by value2 and value3. PARAMETERS: var1 is the variable being set value1 is the source text being read value2 specifies the starting position (decapsulator) value3 specifies the ending position (decapsulator) value4 is the optional control setting DEFAULTS: value4 = "X" ALTERNATIVES: The PEEL command, and COPY used with FINDPOSN 78 Consider the following free-form data: Mouse,Gazelle,Mouse,Elephant Dog,Giraffe,Elk,Mongoose Monkey,Snake,Caribou,Trout The PARSE command lets you extract the "Nth" item. For example, to extract the third item in each line in the free-form example above, you could use this command: PARSE xyz $FLINE "2*," "3*," This means "set the variable xyz by looking in $FLINE (the line just read from the input file) and taking everything between the second comma and the third comma". For the three lines in the sample input file, the variable xyz is set to Mouse, then Elk, then Caribou. ------------- Decapsulators ------------- In the "From" specification in the previous example (i.e. the "2*," part of the command): 2 means "the second occurrence" * is a delimiter to mark the end of the occurrence number , is the text you are looking for Both the "From" and "To" specifications use this format. Commands using this format are said to use "decapsulators", because you are extracting text that is encapsulated (i.e. surrounded) by other text. Decapsulators may be used to find more than a single character. The surrounding text can be up to 80 characters long. Let's say the input file looks like this: Mouse%:Gazelle%:Mouse%:Elephant Dog%:Giraffe%:Elk%:Mongoose Monkey%:Snake%:Caribou%:Trout You can extract the third item in each line with this command: PARSE xyz $FLINE "2*%:" "3*%:" ___ ______ _ ___ _ ___ | | | | | | Variable to set | | | | | The value to parse | | | "To" text being sought "From" occurrence number | "To" occurrence number "From" text being sought This command sets the variable xyz to Mouse, then Elk, then Caribou. 79 ------------------ Sample Application ------------------ The PARSE command is particularly useful for extracting information from comma-delimited files. Here is an example of a comma-delimited file: "Mouse","Gazelle","Mouse","Elephant" "Dog","Giraffe","Elk","Mongoose" "Monkey","Snake","Caribou","Trout" You can extract all the fields with this series of commands (note the use of doubled-up quotes to represent a single quotation mark -- see the section "Delimiters" for details): PARSE field1 $FLINE "1*""" "2*""" PARSE field2 $FLINE "3*""" "4*""" PARSE field3 $FLINE "5*""" "6*""" PARSE field4 $FLINE "7*""" "8*""" For the first line of the sample input file, field1 is set to Mouse, field2 is set to Gazelle, and so on. --------------------- The Occurrence Number --------------------- The occurrence number must be between 1 and 255. The following lines are not valid PARSE commands: PARSE xyz $FLINE "0*," "1*," <-- "From" decapsulator invalid: uses 0 PARSE xyz $FLINE "1*," "256*," <-- "To" decapsulator invalid: uses 256 The occurrence number must always be followed by a "*" so you can search for a number. Consider the following example (the meaning of which would be unclear without the "*" delimiter): PARSE xyz "XXX2YYY2ZZZ2" "1*2" "2*2" This sets xyz to the text occurring between the first "2" and the second "2". In other words, xyz is set to "YYY". 80 --------------------------- Finding the Last Occurrence --------------------------- A decapsulator can refer to "the LAST occurrence": PARSE xyz "AaaBAbbBAccB" ">*A" ">*B" In both decapsulators, the ">" symbol means "the last occurrence". Thus, the command tells Parse-O-Matic, "Set the xyz variable to everything between the last A and the last B". This sets the xyz variable to "cc". You can also use the "<" character to mean "the FIRST occurrence", although this is somewhat redundant, since the following commands are equivalent: PARSE xyz "AaaBAbbBAccB" "<*A" "<*B" PARSE xyz "AaaBAbbBAccB" "1*A" "1*B" PARSE xyz "AaaBAbbBAccB" "A" "B" All three commands set the xyz variable to "aa". --------------------- Unsuccessful Searches --------------------- If PARSE does not find the search text, the variable will be set to a null (""). Here are two examples: PARSE abc "ABCDEFGHIJ" "1*K" "1*J" <-- There is no "K" PARSE abc "ABCDEFGHIJ" "1*A" "1*X" <-- There is no "X" If the "from" value is less than the "to" value, Parse-O-Matic will display an error message, then terminate. For example: PARSE abc "ABCDEFGHIJ" "1*J" "1*A" <-- "J" comes after "A" This kind of failure typically happens if the input data contains an odd arrangement of text that you had not foreseen. 81 ------------------- The Control Setting ------------------- The PARSE command has an optional "Control" parameter, which tells PARSE whether to include or exclude the surrounding text that was found. By default (as shown in all of the preceding examples), the delimiting text is excluded. However, if you want to include it, you can add "I" at the end of the PARSE command, as in this example: PARSE xyz "aXcaYcaZc" "2*a" "2*c" "I" This tells Parse-O-Matic to give you everything between the second "a" and the second "c" -- including the "a" and "c". In other words, this sets the variable xyz to "aYc". You can also set the Control specification to "X" (meaning "exclude"), although since this is the default setting for PARSE, it really isn't necessary. Here is an example: PARSE xyz "a1ca2ca3c" "2*a" "2*c" "X" This sets the variable xyz to "2". ---------------------- The Plain Decapsulator ---------------------- The occurrence number is not always needed. Either the "From" or "To" decapsulator can be represented as a plain string, as follows: PARSE $FLINE "ABC" "XYZ" This means: - Start at the first "ABC" found in the value being parsed - End with the first "XYZ" found in the value being parsed 82 --------------------- The Null Decapsulator --------------------- Here is helpful variation of the "From" decapsulator: "" means "Start from the first character in the value being parsed" A similar variation can be used with the "To" decapsulator: "" means "End with the last character in the value being parsed" If you use the null ("") decapsulator for "From" or "To", the "found" value (the first character for "From", or the last character for "To") will always be included (see "Overlapping Decapsulators" for the single exception to this rule). Here is an example: PARSE xyz "ABCABCABC" "" "2*C" This sets the variable xyz to "ABCAB". The "From" value (i.e. the first character) is NOT excluded. However, when PARSE finds the "To" value (i.e. the second occurrence of the letter C) it IS excluded. If you want to include the second "C", you should write the command this way: PARSE xyz "ABCABCABC" "" "2*C" "I" The following two commands accomplish the same thing: PARSE xyz "ABCD" "" "" SET xyz "ABCD" They are equivalent because the PARSE command means "Set the variable xyz with everything between (and including) the first and last character". 83 --------------------------------------- Why Null Decapsulators Work Differently --------------------------------------- The reason that PARSE treats the null ("") decapsulator differently may not be immediately obvious, since the examples given here are very simple, and not representative of "real world" applications. However, in day-to-day usage, you will frequently find it helpful to be able to specify a command that says, "Give me everything from the beginning of the line to just before such-and-such". Here is a command that means "Give me everything from just after the dollar sign, to the end of the line": PARSE xyz "I'd like to have $250.00" "1*$" "" This sets xyz to "250.00". If you want to include the dollar sign, write the command this way: PARSE xyz "I'd like to have $250.00" "1*$" "" "I" ------------------------- Overlapping Decapsulators ------------------------- Earlier, it was mentioned that the text found by the null decapsulator is "always included" and is not affected by the "X" (Exclude) control. There is one exception to this: if the null decapsulator's "found text" is contained in the text found by the other decapsulator, it WILL be affected. For example: PARSE x "ABCDEFABCDEF" "" "1*AB" "X" This command tells Parse-O-Matic "give me everything between the first character and the first occurrence of AB". Since the two items overlap (i.e. the first "AB" includes the first character), the first character does indeed get excluded. As a result, the x variable is set to an empty string (""). Here is another example: PARSE x "ABCDEFABCDEF" ">*F" "" "X" This command tells Parse-O-Matic "give me everything between the last occurrence of F and the last character". Both decapsulators refer to the same character (i.e. the final "F"), so it is excluded. As a result, the x variable is set to an empty string (""). NOTE: In some circumstances, the FINDPOSN command is NOT affected by this exception. It will do its best to make sense of your request if the decapsulators overlap, and one of them is a null decapsulator. For details, see "The FindPosn Command". 84 -------------------- Parsing Empty Fields -------------------- Consider the following command: PARSE x ",,,JOHN,SMITH" "2*," "3*," There is nothing between the second and third comma, so the x variable is set to "" (an empty string). Now consider this command: PARSE x ",,,JOHN,SMITH" "" "," You are asking for everything from the first character to the first comma (which also happens to be the first character). Obviously, there is nothing "between" the two characters, so the x variable would be set to "" (an empty string). ------------------- Additional Examples ------------------- For more examples of the PARSE command, see the demonstrations provided with Parse-O-Matic (type INFO at the DOS prompt, or run INFO.BAT from Windows, then select TUTORIAL). ---------------- The PEEL Command ---------------- FORMAT: PEEL var1 var2 value1 value2 [value3] : : : : : MEANING: Variable Source From To Control PURPOSE: The PEEL command works just like PARSE, but after setting var1, it REMOVES the parsed value (including the delimiters) from var2. PARAMETERS: var1 is the variable being set var2 is the source text being read value1 specifies the starting position (decapsulator) value2 specifies the ending position (decapsulator) value3 is the optional control setting DEFAULTS: value3 = "X" (See "The PARSE Command" for discussion) When you are breaking up a complex line into fields, PEEL can simplify matters considerably, because the line being interpreted gradually becomes less complex. 85 Here is a simple example. Let's say you have an input file containing a single line: AA/BB/CC/DD If you run this POM file against the input file: PEEL x $FLINE "" "/" <-- Strip out the AA and remove the / OUTEND |{x} PEEL x $FLINE "" "/" <-- Strip out the BB and remove the / OUTEND |{x} PEEL x $FLINE "" "/" <-- Strip out the CC and remove the / OUTEND |{x} OUTEND |{$FLINE} then the output file will look like this: AA BB CC DD What is happening is that $FLINE is gradually being stripped of the text that is being found. After the first PEEL, $FLINE contains "BB/CC/DD", and so on. After the final PEEL, $FLINE only contains "DD". ------------------- The Control Setting ------------------- The "I" and "X" control parameters behave the same way as they do in the PARSE command: they specify whether or not the surrounding text is included in var1. Take note, however, that the starting and ending characters are always removed from var2, along with the "found" text, regardless of the control parameter. In other words, the control parameter only affects the first variable (x in the example above), not the second ($FLINE in the example). 86 -------------------- Parsing Empty Fields -------------------- Consider the following commands: SET z = ",,,JOHN,SMITH" PEEL x z "2*," "3*," There is nothing between the second and third comma, so the x variable is set to "" (an empty string). After the PEEL command, the z variable will be two commas shorter (",JOHN,SMITH,23.00"). If you are trying to extract data from a comma-delimited line, this is probably not what you want (since it gets rid of two commas). When taking apart a delimited file, it often makes sense to start peeling from the left side of the string. Consider these commands: SET z = ",,,JOHN,SMITH" PEEL x z "" "," You are asking for everything from the first character to the first comma (which also happens to be the first character). Obviously, there is nothing "between" the two characters, so the x variable would be set to "" (an empty string). After the PEEL command, the z variable will be one comma shorter (",,JOHN,SMITH"). 87 -------------------------- The Left-Peeling Technique -------------------------- You can use the "left-peeling" technique to take apart an entire line. This is especially useful when interpreting a comma-delimited file. SET z = ",,MARY,JONES," PEEL a z "" "," <-- Sets the a variable to "" PEEL b z "" "," <-- Sets the b variable to "" PEEL c z "" "," <-- Sets the c variable to "MARY" PEEL d z "" "," <-- Sets the d variable to "JONES" SET e = z <-- Sets the e variable to "" The e variable is null because there is nothing after the last comma -- in other words, the final field is empty. If the initial value of the z variable was ",,MARY,JONES,99" then the e variable would be set to "99". ---------------------- The Leftover Technique ---------------------- Sometimes you are faced with a parsing task in which the input lines are more than 255 characters long, yet there is no way to know where each field begins. This makes it impossible to use the SPLIT command in the usual way. This type of problem generally arises when processing comma-delimited or tab-delimited files. Here is a sample POM file which handles input lines up to 300 characters long, provided that no field is more than 155 characters long. 88 SPLIT 1-100, 101-200, 201-300 <-- Process input lines in three segments IGNORE $FLINE = "" <-- Ignore any splits that yield nothing BEGIN leftover <> "" <-- See if we have anything left over APPEND $FLINE leftover $FLINE <-- Append what's left over SET leftover = "" <-- We've used up the left over data END BEGIN <-- Loop through the parts we can extract FINDPOSN x $09 <-- Look for a tab BEGIN x <> "0" <-- See if we found a tab SET foundtab = "Y" <-- Yes, we found a tab PEEL x $FLINE "" #09 <-- Peel away everything up to the tab OUTEND |{x} <-- Process the text we peeled away ELSE SET foundtab = "N" <-- No, we didn't find a tab BEGIN $SPLIT = "3" <-- See if this is the last of the text OUTEND |{$FLINE} <-- Output whatever is left over ELSE SET leftover = $FLINE <-- Save this part for the next split END END AGAIN foundtab = "Y" <-- Continue if this segment had a tab ----------------- The PEELX Command ----------------- FORMAT: PEELX var1 var2 value1 value2 [value3] : : : : : MEANING: Variable Source From To Control PURPOSE: The PEELX command works just like PEEL, but if it can not find the delimiters being sought, it sets var1 to var2, and var2 to null. PARAMETERS: var1 is the variable being set var2 is the source text being read value1 specifies the starting position (decapsulator) value2 specifies the ending position (decapsulator) value3 is the optional control setting DEFAULTS: value3 = "X" (See "The PARSE Command" for discussion) The PEELX command works exactly the same as the PEEL command, except that if it can not find the text being sought (as specified by value1 and value2), it sets var1 to var2 and sets var2 to null. This is very useful when you are stripping away one item at a time from the left side of a string. For example, let us say you had an input line that contained part numbers arranged like this: A100-34 A100-35 A202-34 A303-35 B143-99 B716-34 89 Now let us say that you wanted to output every part number that contained "-34". The obvious choice is to peel off each part number at the space, but the last part number does not have a space after it. You could take the extra step of appending a space, but PEELX saves you the trouble, as in this example: BEGIN PEELX word $FLINE "" " " OUTEND word ^ "-34" |{word} AGAIN $FLINE <> "" The PEELX command strips out the part numbers as "A100-34", "A100-35" and so on, until $FLINE contains only "B716-34". Then, when PEELX looks for a space, it does not find it. So it sets the variable "word" to "B716-34" and sets $FLINE to null. 90 ============================================================================ POSITIONAL COMMANDS ============================================================================ ------------------ General Discussion ------------------ NOTE: If you are a programmer, you may be tempted to use positional commands even when other Parse-O-Matic commands are more efficient. The positional approach is reminiscent of the parsing strategies used in traditional programming languages, so you may use them because of their familiarity. The following material discusses this issue, to help you to create shorter, faster POM files. ----------------------------- What are Positional Commands? ----------------------------- Parse-O-Matic's positional commands let you work with the numeric position of one text string in another. For example, if the variable xyz contains the value "ABCD": SEARCH POSITION STRING IN xyz COMMENTS ------ -------- ----------------------------------------- "A" "1" "A" appears in the 1st position of "ABCD" "AB" "1" "ABCD" "1" "C" "3" "C" appears in the 3rd position of "ABCD" "CD" "3" "D" "4" "AC" "0" "0" since "AC" does not appear in "ABCD" ---------------------------- Why Use Positional Commands? ---------------------------- Positional commands give you the precise control you need for certain difficult parsing tasks. For example, if you want to obtain the last three characters of a string of known length (e.g. "ABCDEFG"), the standard approach is: SET abc = "ABCDEFG" SET xyz = abc[5 7] However, if the length of the string is not known, you can not use the substrings in [square brackets]. (To make Parse-O-Matic run as fast as possible for standard parsing jobs, you can not use variables within square brackets.) 91 If the length of the string is not known, you can use positional commands to obtain the last three characters. Here is an example: SET abc = "Unknown" SETLEN len abc CALC lenminus = len "-" "2" COPY xyz abc lenminus len The SETLEN command finds the length (i.e. the last character position) of the abc variable. In this case, the answer is "7", since "Unknown" is seven characters long. The CALC command subtracts "2" from this length, setting the lenminus variable to "5". Finally, the COPY command copies from position "5" to "7", setting the variable xyz to "own" -- the last three characters of the abc variable. ----------------- A Cautionary Note ----------------- Positional commands are useful for some applications, but many parsing jobs do not require them. The commands SET, IF, PARSE and PEEL can usually do the same job with less effort. For example, the following approaches are equivalent: STANDARD APPROACH POSITIONAL APPROACH ----------------- --------------------- SET abc "AB/CD" SET abc = "AB/CD" PARSE xyz abc "/" FINDPOSN n abc "/" COPY xyz abc n+ The positional approach requires more lines than the standard approach to extracting the characters after the "/" character. Another problem is that because positional commands give you fine control of the parsing process, it is up to you to guard against exceptional situations. Consider this example: FINDPOSN x $FLINE "/" CALC x = x "+" "1" COPY xyz $FLINE x If $FLINE (the current input line) contains the value "ABC/DEF": FINDPOSN sets x to "4" (the position of the "/" character) CALC increases x to "5" COPY sets xyz to "DEF" -- from position "5" to the end of $FLINE Unfortunately, a problem occurs if $FLINE does not contain a slash: FINDPOSN sets x to "0" (meaning the "/" was not found) CALC increases x to "1" COPY copies from position "1" to the end of $FLINE 92 This may not be what you intended. If you want to return a null string when $FLINE does not contain a slash, you could use a single PARSE command: PARSE xyz $FLINE "/" This copies anything after the slash to the xyz variable. If $FLINE does not contain a slash, xyz is set to "". The precise control provided by Parse-O-Matic's positional commands makes them indispensible for certain parsing applications. Just remember that with added power comes added responsibility: you will sometimes have to add extra code to handle unusual situations. --------------------------- Negative Positional Indices --------------------------- In most cases, you will use the COPY, DELETE and EXTRACT commands with absolute character positions. For example: SET x = "ABCDE" COPY y x "2" "4" This sets variable y to "BCD". However, sometimes you need to work from the other end (i.e. the right-hand side) of the variable. For this reason, COPY, DELETE and EXTRACT support negative indices, which count back from the right edge of the variable. For example, let's say you want to find out what the last two characters of a variable are. You could do it this way: SET x = "ABCDE" <-- Sets the variable SETLEN xlen x <-- Finds out how long it is CALC x1 = xlen "-" "1" <-- Calculates the 2nd-to-last position COPY z x x1 xlen <-- Copies the last two characters This sets the variable z to "DE", which is indeed the last two characters of the x variable. 93 An easier method is to use negative positional indices (available in the COPY, DELETE and EXTRACT commands). In this case, the solution is much simpler: SET x = "ABCDE" COPY z x "-2" "-1" This sets the variable z to "DE". The "from" specification of "-2" means "the second-to-last character". The "-1" specification means "the last character". (Strictly speaking, you could omit the "-1", since the default "to" value is "copy to the end of the variable".) In most parsing applications, it is unusual to work from the right-hand side of the variable (see "The Left-Peeling Method" for comparison) because data tends to be read from left to right. However, negative positional indices do give you some additional flexibility that may be useful in difficult parsing situations. ------------------ The SETLEN Command ------------------ FORMAT: SETLEN var1 value1 PURPOSE: SETLEN sets var1 to the length of value1. Here is an example of the SETLEN command: SET x = "ABCD" SETLEN y x This sets variable y to "4". One handy application for SETLEN is to underline text. For example: SET name = $FLINE[1 15] TRIM name "B" " " SETLEN nlen name SET uline = "" PAD uline "L" "-" nlen OUTEND |{name} OUTEND |{uline} If the input line contains the name "JOHN SMITH", the output would be: JOHN SMITH ---------- For another example that does underlining, see "POM and Wildcards". 94 ------------------ The DELETE Command ------------------ FORMAT: DELETE var1 value1 [value2] PURPOSE: The DELETE command removes a range of characters (specified as a starting and ending position) from a variable. PARAMETERS: var1 is the variable from which characters will be removed value1 is the starting position (e.g. "1" = First character) can be a negative index ("-3" = 3rd-to-last character) value2 is the optional ending position; if it is omitted, it is assumed to mean "the last character in var1" can be a negative index ("-2" = 2nd-to-last character) NOTES: If value1 is null or "0", value1 = "1" If value2 is null or "0", value2 = "last character in var1" ALTERNATIVES: The PEEL, TRIM, CHANGE, SET and APPEND commands Here is an example of the DELETE command: SET x = "ABC///DEF" DELETE x "4" "6" This deletes from position 4 to 6, so the variable x is set to "ABCDEF". If value2 is omitted, DELETE assumes you wish to delete everything from the starting position to the end of the string. For example: SET x = "ABC///DEF" DELETE x "4" This sets x to "ABC". 95 ---------------- The COPY Command ---------------- FORMAT: COPY var1 value1 value2 [value3] PURPOSE: The COPY command copies a range of characters (specified as a starting and ending position) from a value to a variable. PARAMETERS: var1 is the variable being set value1 is the source value, from which you will copy text value2 is the starting position (e.g. "1" = First character) can be a negative index ("-3" = 3rd-to-last character) value3 is the optional ending position; if it is omitted, it is assumed to mean "the last character in value1" can be a negative index ("-2" = 2nd-to-last character) NUMERICS: Tabs, spaces and commas are stripped from value2 and value3 NOTES: If value2 is null or "0", value1 = "1" If value3 is null or "0", value3 = "last char in value1" ALTERNATIVES: The SET command Here is an example of the COPY command: SET x = "ABC///DEF" COPY y x "4" "6" This copies from position 4 to 6, so the variable y is set to "///". If value2 is omitted, COPY assumes you wish to copy everything from the starting position to the end of the string. For example: SET x = "ABC///DEF" COPY y x "4" This sets y to "///DEF". To make your POM files easier to read, you might consider padding the COPY command with an equals sign to remind you that a variable is being set. For example: COPY y = x "4" "6" This emphasizes that the variable y is being set to a substring of x. For more information about padding, see "Padding for Clarity". 96 ------------------- The EXTRACT Command ------------------- FORMAT: EXTRACT var1 var2 value1 [value2] PURPOSE: The EXTRACT command works like COPY, but removes the characters from the source variable after copying them to a variable. PARAMETERS: var1 is the variable that will contain the characters extracted from var2 var2 is the variable from which characters will be copied to var1, then removed value1 is the starting position (e.g. "1" = First character) can be a negative index ("-3" = 3rd-to-last character) value2 is the optional ending position; if it is omitted, it is assumed to mean "the last character in var2" can be a negative index ("-2" = 2nd-to-last character) NUMERICS: Tabs, spaces and commas are stripped from value1 and value2 NOTES: If value1 is null or "0", value1 = "1" If value2 is null or "0", value2 = "last character in var2" ALTERNATIVES: The PEEL command Here is an example of the EXTRACT command: SET x = "ABC///DEF" EXTRACT y x "4" "6" This copies from position 4 to 6, so the variable y is set to "///". The characters copied to variable y are removed from x, so that it now contains the value "ABCDEF". If value2 is omitted, EXTRACT assumes you wish to extract everything from the starting position to the end of the string. For example: SET x = "ABC///DEF" EXTRACT y x "4" This sets y to "///DEF", while the variable x is set to "ABC" (i.e. the original value for x, with the extracted characters removed). 97 -------------------- The FINDPOSN Command -------------------- FORMAT: FINDPOSN var1 value1 value2 [value3 [value4]] : : : : : MEANING: 1) Variable Source Find : : 2) Variable Source From To Control PURPOSE: The FINDPOSN command finds one text string in another. It locates the starting or ending position of a string, or a string delimited by one or two other strings. PARAMETERS: var1 is the variable that will contain the position if the string is found (e.g. "2" means it was found in the second position of value1; "0" means the string was not found) value1 is the string being searched value2 is the string being sought, or... the left-most part of a string being sought value3 is the right-most part of the string being sought; if it is set to null (""), it is assumed to mean "the last character in value1" value4 is the control setting DEFAULTS: value4 = "IS" ALTERNATIVES: The SCANPOSN command SEE ALSO: This section is much easier to understand if you have studied "The Parse Command". There are two ways to use the FINDPOSN command: the "Plain String Find" and the "Embedded String Find". These are discussed below. --------------------- The Plain String Find --------------------- In its simplest form, the Plain String Find locates a string (value2) in another string (value1) and assigns its position to a variable (var1). Here is an example: FINDPOSN x $FLINE "Fred" This looks for the first occurrence of "Fred" in $FLINE (the current input line). If $FLINE contains "Hello Fred!", the command will set the variable x to "7", since "Fred" starts in the seventh character position. 98 --------------------------- Using a Single Decapsulator --------------------------- Sometimes you don't want to find the FIRST occurrence, but the second, third, and so on. You can use a single decapsulator (see "The Parse Command") to specify this. For example: SET z = "This is the way to demonstrate the FINDPOSN command" FINDPOSN x z "the" FINDPOSN y z "2*the" The first FINDPOSN command finds the first occurrence of "the", using a plain string, so it sets the variable x to "9", since the first "the" starts in the ninth position. The second FINDPOSN command uses a decapsulator with the occurrence number "2*", which means "look for the second occurrence". Thus, it sets the variable y to "32", since the second "the" occurs in that position. Incidentally, the first FINDPOSN could also have been written this way: FINDPOSN x z "1*the" which is another way of saying, "Look for the first occurrence". However, if no occurrence number is specified, FINDPOSN assumes you are looking for the first occurrence. ---------------------------- The Encapsulated String Find ---------------------------- NOTE: The Encapsulated String Find is very similar to the PARSE command. If you do not find the following discussion sufficiently instructive, you can gain some additional insight by reading the section of this manual entitled "The Parse Command". The Encapsulated String Find looks for a string that is encapsulated by (i.e. located between) two other strings. This is useful if your input data contains text that is surrounded by delimiters. One common example is the "comma-delimited" file (see "Why You Need Parse-O-Matic -- An Example" for a sample). Here is another situation where data is surrounded by delimiters: 99 |Mouse |Gazelle|Mouse |Elephant| |Dog |Giraffe|Elk |Mongoose| |Monkey|Snake |Caribou|Trout | One can imagine an application that would create tabular data like this -- cleverly (but annoyingly) reducing the column widths to the minimum. This would make the column starting and ending positions unpredictable. You could use the PARSE command to obtain values from each column, but if you have a lot of data, it would be more efficient to determine the starting and ending positions at the outset. Let's say you wanted to extract the third column. You could set up your POM file like this: BEGIN startposn = "" FINDPOSN startposn $FLINE "3*|" "4*|" "XS" FINDPOSN endposn $FLINE "3*|" "4*|" "XE" HALT startposn = "0" "Missing delimiter!" END COPY animal $FLINE startposn endposn OUTEND |{animal} The lines between the BEGIN and END are run only once for the entire parsing job, since they set the startposn variable to something other than a null ("") string. (See "Uninitialized and Persistent Variables") The first FINDPOSN command uses the decapsulators "3*|" and "4*|" to locate the text between the third and fourth "|" delimiters, but because of the "XS" control value (described later), startposn is set to the position AFTER the delimiter. (Briefly, "XS" means "exclude the found text, and refer to the starting position of the text that follows it.) Thus, the variable startposn is set to "12"; "Mouse" starts in the twelfth position. The second FINDPOSN command sets the ending position (endposn) in a similar way. It finds the third and fourth "|" delimiters, but because of the "XE" control setting, it sets endposn to the position BEFORE the fourth delimiter. (Briefly, "XE" means "exclude the found text, and refer to the ending position of the text that precedes it.) The HALT command is simply a safeguard to ensure that the input data follows the correct format. If the first FINDPOSN fails to find the third or fourth "|" delimiter, it will set startposn to "0" (meaning "not found"). The COPY command copies $FLINE (the current input line) from the starting position (startposn) to the ending position (endposn). This value is then output by the OUTEND command. 100 ---------------- Control Settings ---------------- The control settings give you precise control of the part of the string to which you are referring. Valid control settings are: SETTING MEANING ------- ------- IS Include found text and report where the entire text starts IE Include found text and report where the entire text ends XS Exclude found text and report where the delimited text starts XE Exclude found text and report where the delimited text ends NOTE: While FINDPOSN greatly resembles the PARSE command, the default control setting is different. In PARSE, the control setting is assumed to be "X" if it is omitted. In FINDPOSN, however, the control setting is assumed to be "IS" if it is omitted. Let us assume that the we set the variable z as follows: SET z = "ABzzzCDEFzzzGH" This produces the following results: COMMAND VALUE FOR x VARIABLE --------------------------------- -------------------- FINDPOSN x z "1*zzz" "2*zzz" "IS" "3" FINDPOSN x z "1*zzz" "2*zzz" "XS" "6" FINDPOSN x z "1*zzz" "2*zzz" "XE" "9" FINDPOSN x z "1*zzz" "2*zzz" "IE" "12" The following illustration may make the results easier to understand: +------------------------------------------------------------------------+ | | | Measuring Scale: 12345678901234 | | -------------- | | Command: FINDPOSN x "ABzzzCDEFzzzGH" "zzz" "2*zzz" "<control>" | | | | | | | | Control Value: IS XS XE IE | | Results: 3 6 9 12 | | | +------------------------------------------------------------------------+ In the example, the control values have the following specific meanings: "IS" ("Include, Start") = start of entire text (from "1*zzz" to "2*zzz") "XS" ("Exclude, Start") = start of text after the "from" item ("1*zzz") "XE" ("Exclude, End") = end of text before the "to" item ("2*zzz") "IE" ("Include, End") = end of entire text (from "1*zzz" to "2*zzz") 101 ------------------ Insoluble Searches ------------------ FINDPOSN returns "0" (zero) when it can not find a string, or if it is presented with an insoluble dilemma. Here are some examples: FINDPOSN x "CatDog" "Moose" <-- "Moose" can not be found FINDPOSN x "ABCDEF" "A" "G" <-- "G" can not be found FINDPOSN x "ABCDEF" "A" "2*E" <-- There is no second "E" Here is another insoluble search: FINDPOSN x "ABCDEF" "C" "D" "XS" FINDPOSN x "ABCDEF" "C" "D" "XE" There is nothing between the "from" and "to" delimiters. Since we are excluding the delimiters themselves (with "XS" and "XE" specifications), we can not provide a "start" or "end" value for what we found -- we didn't find anything! Hence, we have nothing for which to return a starting or ending position. ------------------ Null Decapsulators ------------------ Consider these next two commands: FINDPOSN x "ABCDEF" "F" "" "XS" FINDPOSN x "ABCDEF" "F" "" "XE" What comes between "F" and the end of the string? Bear in mind, however, that when you use a null ("") to mean "the last character", it is not excluded (see "The Null Decapsulator" in the section entitled "The Parse Command", for a discussion). Thus, the two FINDPOSN commands "find" the final character "F", and both return "6". These both return "6" because the "F" is both the starting and ending position of what we found, and we included (rather than excluded) the starting and ending delimiters ("F" and the last character, respectively). Similarly, the following commands return a "1": FINDPOSN x "ABCDEF" "" "A" "XS" FINDPOSN x "ABCDEF" "" "A" "XE" Even though there is nothing between "A" and "the first character", the first character is not excluded, since we are using a null decapsulator. As a result, we find the string "A" and return its position, which is "1". 102 --------------------- Finding The Last Word --------------------- One common use for FINDPOSN is to find the last occurrence of a word in a line of text. Consider the following lines: SET z = "Parse-O-Matic is a fine product!" FINDPOSN x z ">* " "" "XS" This will set the x variable to 25 (the position of the final word). The command looks for the last "space" character (which is in position 24), then (because of the "XS" control) returns the position of the character following it. --------------- Who Needs This? --------------- At this point, you may be wondering, "Why do I need to have this kind of precise control?" Well, in most cases you don't, so you will tend to use the "Plain String Find" (described earlier). However, certain complex parsing applications demand that you make a distinction between the text that encapsulates a piece of text, and the encapsulated text itself. When faced with this kind of task, you will see that Parse-O-Matic's FINDPOSN command lets you accomplish in one line what would take dozens of lines in a traditional programming language. 103 -------------------- The SCANPOSN Command -------------------- FORMAT: SCANPOSN var1 var2 value1 value2 [value3] : : : : : MEANING: from to source scanlist control PURPOSE: SCANPOSN searches the source value for one of the scanterms in the scanlist (see "Terminology", below). SCANPOSN finds out which scanterm provides the best match, then returns the "from" (starting) and "to" (ending) positions of that scanterm in the source value. TERMINOLOGY: scanterm An item in a scanlist; one of the things you are searching the source value for. scanlist A list of scanterms. Here is an example of a scanlist: "/Mr/Mrs/Ms" PARAMETERS: var1 is the variable that will contain the starting position if one of the scanterms is found (e.g. "2" means it was found in the second position of value1; "0" means SCANPOSN did not find any of the scanterms) var2 is the variable that will contain the ending position if one of the scanterms is found value1 is the source string -- the string being searched value2 is the scanlist (see "Terminology", above) value3 is the optional control string DEFAULTS: value3 = "I" (i.e. Ignore case) ALTERNATIVES: The FINDPOSN command A common requirement in parsing is to find out if one of several strings can be found in another string. For example, you might want to find out if a name starts with a "salutation" (Mr., Mrs., Ms.). You can do this by looping through the various strings and comparing each one, but SCANPOSN lets you do all this with a single command. For example, to search for a salutation in a string: SCANPOSN from to $FLINE "/Mr./Mrs./Miss/Ms." If $FLINE (the line just read from the input file) contains one of the scanterms in the scanlist, SCANPOSN will set the "from" and "to" variables. Thus, if $FLINE contains "Ms. Mary Jones", the "from" variable is set to "1" and the "to" variable is set to "3" (since "Ms." goes from positions 1 to 3 in $FLINE). If none of the scanterms is found, the "from" variable is set to "0". Thus, if $FLINE contains "John Smith", no salutation is found, and the SCANPOSN command shown above will set the "from" variable to "0". 104 ------------ The Scanlist ------------ The scanlist can contain one or more scanterms. The FIRST character in the scanlist is interpreted as the delimiter (separator) for the scanterms. Thus, the following scanlists are all valid: "/Mr./Mrs./Miss/Ms." <-- Delimiter is: / "xMr.xMrs.xMissxMs." <-- Delimiter is: x "@Library@School@Gymnasium@Clinic/Hospital" <-- Delimiter is: @ "/Cow" <-- Delimiter is: / The first example ("/Mr./Mrs./Miss/Ms.") has already been demonstrated. The second example uses the letter "x" as a delimiter. This would cause a problem if one of the scanterms contained an "x", since it would be treated as TWO scanterms. For example: "xJohnxTrixiexFred" The name "Trixie" contains an "x", so it would be broken down into two scanterms ("Tri" and "ie"). You should always choose a scanlist delimiter that does not appear in the list of scanterms. ----------------------- Accommodating Variation ----------------------- When you design a scanlist, you should take into account the possibility that the input might contain strange variations. Consider this command: SCANPOSN x y "Mr John Smith" "/Mr./Mrs./Ms." This will set the x variable to "0" because the "Mr" is followed by a space, not a period. A more "forgiving" command would be: SCANPOSN x y "Mr John Smith" "/Mr./Mrs./Ms./Mr /Mrs /Ms " This would successfully locate the "Mr " string, and set x to "1" and y to "3". (The "3" points to the space.) 105 ------------------------------ Handling Prefixes and Suffixes ------------------------------ When designing a scanlist, you should consider that a scanterm might be part of a word. For example: SCANPOSN x y "Mississipi Sue" "/MR./MRS./MISS/MS." This will find the "Miss" in Mississippi, even though this is not part of a salutation. A more appropriate command would be: SCANPOSN x y "Mississipi Sue" "/MR./MRS./MISS /MS." The space after "Miss" in the scanlist ensures that if it is found, it will be separate from any word following it. The trailing space is not necessary for the scanterm "MR.", since no word contains a period. However, if you do include spaces after the periods (as in "/MR. /MRS. /MISS /MS. ") it may simplify your subsequent parsing operations. You must also take suffixes into account. For example: SCANPOSN x y "Zinc Enterprises" "/INC/CO/ENTERPRISES" This will find the "inc" in "Zinc". You can add a space in front of each scanterm to ensure that it is separated from any other word: SCANPOSN x y "Zinc Enterprises" "/ INC/ CO/ ENTERPRISES" You may be tempted to put spaces on both sides of a word, to handle both prefixes and suffixes. However, consider this example: SCANPOSN x y "Wazoo Inc" "/ INC / CO / ENTERPRISES " None of the scanterms is found, because the "Inc" in the source string does not end in a space. You can address this kind of problem with the control settings (described next). ---------------------- Controlling the Search ---------------------- Unless otherwise instructed, SCANPOSN will find the first scanterm that appears anywhere in the source string, and return its start and end positions. You can modify this behavior by using the optional control parameter (value3). The control parameter contains one or more characters, each of which has a special meaning. 106 CHARACTER MEANING --------- ------- < Find the leftmost match > Find the rightmost match I Ignore case (e.g. Xyz matches XYZ) M Match case (e.g. Xyz does not match XYZ) Here are some valid control settings: SETTING MEANING ------- ------- "<M" Find the leftmost match, which much match case "<I" Find the leftmost match, ignoring case ">M" Find the rightmost match, which must match case "M" Find any match, but the case must be the same NOTES: If neither "I" nor "M" are specified, SCANPOSN assumes "I". If neither "<" nor ">" are specified, SCANPOSN does a "Find-Any" search (explained below). ----------------------------- Leftmost, Rightmost, Find-Any ----------------------------- The ">" (rightmost) control setting tells SCANPOSN to find the scanterm that has the highest "to" value with the lowest "from" value. This means that ALL of the scanterms are evaluated. Consider this command: SCANPOSN x y "SHREWxxxCATxxxMOUSExxx" "/CAT/DOGGY/MOUSE/ELK" ">" SCANPOSN finds "CAT", but continues looking to see if there are any better matches to the right. Eventually it finds MOUSE and sets x to "15" and y to "19" (pointing at "MOUSE"). If you use the "<" (leftmost) parameter, SCANPOSN will check all the scanterms to find out which one has the lowest "from" position with the highest "to" value. SCANPOSN x y "SHREWxxxCATxxxMOUSExxx" "/CAT/DOGGY/MOUSE/ELK" "<" This will set x to "9" and y to "11" (pointing at "CAT"). If you do not specify "<" or ">", SCANPOSN finds the first scanterm it can, and ignores the rest. SCANPOSN x y "SHREWxxxCATxxxMOUSExxx" "/CAT/DOGGY/MOUSE/ELK" The first scanterm is "CAT", and this can be found at positions 9 to 11. SCANPOSN will return those values, and ignore the rest of the scanterms. The absence of a "<" or ">" is known as a "Find-Any" search. You can use this if you want to know if one of the scanterms appears in the source string, but you are not interested in finding out which one. 107 ------------------------ The Best Match Principle ------------------------ NOTE: The "Best Match" principle does not apply to the "Find-Any" search. It applies only to the Leftmost ("<") and Rightmost (">") searches. To use the SCANPOSN command effectively, you must understand the concept of "the best match". This can be illustrated with an example: SCANPOSN x y "MegaWhizco International" "/CO/WHIZCO/MEGAWHIZ" ">" The SCANPOSN command finds the scanterm CO at positions 5 to 6. However, it continues looking for an even better match. It finds that WHIZCO is just as far to the right (i.e. it ends at position 6), but has a lower starting position. This makes it a "better" match. The next scanterm (MEGAWHIZ) has a lower starting position, but its ending position is not as good (i.e. not as far to the right). It is rejected because we are looking for the rightmost string. As a result, SCANPOSN will set x to "1" and y to "6". In other words, when SCANPOSN is looking for the rightmost scanterm, it will first identify the "found" scanterms which have the highest ending position, and then choose the longest one. Here is an example using a leftmost search: SCANPOSN x y "Our catalog is enclosed" "CAT/MOOSE/CATALOG/DOG" "<" The SCANPOSN finds CAT at positions 5 to 7, but as it continues checking the scanterms, it finds that CATALOG is just as far to the left (i.e. it starts at position 5), but it is a better match since it has a higher ending position. As a result, SCANPOSN will set x to "5" and y to "11". The "Best Match" principle does not affect "Find-Any" searches. For example: SCANPOSN x y "Our catalog is enclosed" "CAT/MOOSE/CATALOG/DOG" This sets x to "5" and y to "7". Since this is a "Find-Any" search (i.e. neither "<" nor ">" are specified in the control settings), SCANPOSN stops looking as soon as it has found a match. 108 When doing a Find-Any search, you can not be sure if any of the other scan terms appear in the source string. For example: SCANPOSN x y "Our cat and dog are upstairs" "CAT/DOG" This will find CAT and stop looking for additional matches. If you change the order of the scanlist, you will get different values: SCANPOSN x y "Our cat and dog are upstairs" "DOG/CAT" Thus, a Find-Any search is useful only for detecting if one of the scanterms appears in the source string. After doing a Find-Any search, you can check if the "from" value is "0" (meaning no scanterms were found). If it is not "0", it means one of the terms WAS found. For example: SET source = "Our cat catalog is enclosed" SET scanlist = "CATALOG/MOOSE/CAT/DOG" SCANPOSN from to source scanlist BEGIN from = "0" OUTEND |None of the scanterms appeared in the string {source} ELSE OUTEND |At least one of the scanterms appears in the string {source} END 109 ============================================================================ DATE COMMANDS ============================================================================ ------------------ General Discussion ------------------ Parse-O-Matic's date-oriented commands provide you with a convenient way to work with dates. While you can accomplish the same thing using other Parse-O-Matic commands (LOOKUP, PAD etc.), the date functions are optimized for speed, so if your parsing job does a lot of date-format conversions, it will run faster. -------------------- The POMDATE.CFG File -------------------- When a date command is first executed, Parse-O-Matic reads in a file named POMDATE.CFG. (The method by which Parse-O-Matic finds the file is discussed in the section "How Parse-O-Matic Searches for a File".) POMDATE.CFG is a self-documenting text file that contains the default date format string (explained later), and the names of the twelve months. You can edit this file with a standard text editor, or a word-processor in "generic text" mode. As originally supplied with Parse-O-Matic, the default date format string is "?y/?n/?d", which produces YY/MM/DD dates (e.g. July 1 1998 becomes 98/07/01). You can change this to reflect your own preference. If you are parsing data in a language other than English, you can also change the names of the months. ------------ Date Formats ------------ A date format is a sequence of characters that briefly describes the appearance of a date. For example, the format "Y-T-?n" describes a year/month/day format that looks like this: 1998-JULY-02 The following characters have a special meaning in the date format string: d M m n T t Y y ? For these special characters, uppercase and lowercase are important. For example, "T" is not the same as "t". All characters other than the special characters are interpreted "as-is", and are included in the final date string. 110 The following table explains the meaning of the special characters used to specify year, month and day, using the date July 2, 1998 for the examples: CHAR MEANING SAMPLE FORMAT SAMPLE RESULT ---- -------------------------- ------------- ------------- Y 4-digit year d-m-Y 2-Jul-1998 y 1- or 2-digit year d-m-y 2-Jul-98 n 1- or 2-digit month d/n/y 2/7/98 m 3-letter month d/m/y 2/Jul/98 M 3-letter month (uppercase) d M y 2 JUL 98 t Month t d, Y July 2, 1998 T Month (uppercase) T d Y JULY 2 1998 d Day y/m/d 98/7/2 The ? character can be used in the date format to pad out one-digit values to two digits. The following table uses the date February 3, 2001 for the examples: SAMPLE DATE FORMAT SAMPLE RESULT ------------------ ------------- y-?n-?d 1-02-03 ?y/m/?d 01/Feb/03 ?n/?d Y 02/01 2001 t '?y February '01 As the last example shows, it is not necessary to use month, day and year; you can omit any item to obtain an abbreviated date. 111 ----------------- The TODAY Command ----------------- FORMAT: TODAY var1 [value1] PURPOSE: The TODAY command sets a variable (var1) to today's date, in a variety of formats. DEFAULTS: If value1 is not specified, TODAY uses the default date format, which is specified in the file POMDATE.CFG. NOTES: For a discussion of date formats (including the default date format), see the "General Discussion" section at the beginning of this chapter. SEE ALSO: "The Date Command" Assuming today's date is July 1 1998, here are some examples: COMMAND THE VARIABLE xyz IS SET TO... ------------------- ----------------------------- TODAY xyz The default date format TODAY xyz "" The default date format TODAY xyz "Y-M-?d" 1998-JUL-01 TODAY xyz "t d Y" July 1 1998 TODAY xyz "t 'y" July '98 As the last example shows, it is not necessary to use month, day and year; you can omit any item to obtain an abbreviated date. 112 ---------------- The DATE Command ---------------- FORMAT: DATE var1 value1 value2 value3 [value4] PURPOSE: The DATE command sets a variable (var1) to given year (value1), month (value2) and day (value3), or a subset of these items, in a variety of formats, as specified by the format string (value4). PARAMETERS: var1 is the variable being set value1 is the year (e.g. "1998" or "98") value2 is the month (e.g. "1" = January) value3 is the day (1 to 31) value4 is the date format NUMERICS: Tabs, spaces and commas are stripped from value1, 2 and 3 DEFAULTS: If value4 is omitted, DATE uses the default date format, which is specified in the file POMDATE.CFG. NOTES: For a discussion of date formats (including the default date format), see the "General Discussion" section at the beginning of this chapter. SEE ALSO: "The Today Command" Assuming the date being set is July 1 1998, here are some examples: COMMAND THE VARIABLE xyz IS SET TO... ---------------------------------- ----------------------------- DATE xyz "98" "07" "01" The default date format DATE xyz "1998" "07" "01" "" The default date format DATE xyz "98" "7" "1" "Y-M-?d" 1998-JUL-01 DATE xyz "98" "07" "01" "t d Y" July 1 1998 DATE xyz "98" "7" "01" "t 'y" July '98 DATE xyz "98" "7" "" "t 'y" July '98 As the last two examples show, it is not necessary to use month, day and year; you can omit any item to obtain an abbreviated date. If a date is outside a valid range, Parse-O-Matic halts with an error. Acceptable value ranges are: Year 0 to 9999; Month 1 to 12; Day 1 to 31 If the year is between 0 and 99, Parse-O-Matic makes the following assumptions: - If the number is between 80 and 99, it means 1980 to 1999 - If the number is between 0 and 79, it means 2000 to 2079 Parse-O-Matic does not check that a date is "possible", so you could set a date to "February 31, 2001", even though February never has 31 days. 113 -------------------- The MONTHNUM Command -------------------- FORMAT: MONTHNUM var1 value1 PURPOSE: The MONTHNUM command sets the month number of a given month. ALTERNATIVES: The LOOKUP command Here is an example of the MONTHNUM command: MONTHNUM xyz "February" This will set the variable xyz to "2". The comparison is performed on the basis of the number of characters available, without regard to case, so the following would also work: MONTHNUM xyz "FEB" If the result is ambiguous, Parse-O-Matic returns the first match. For example: MONTHNUM xyz "JU" This will set xyz to "6", although it could refer to either June or July. If MONTHNUM can not find a match, it will return a null ("") string. For example: MONTHNUM xyz "ZZZ" Since no month starts with "ZZZ", this will set xyz to "". If you are writing a Parse-O-Matic application that will be run in several languages (using different POMDATE.CFG files), you should carefully study the names of the months in each language to avoid problems. In English, it is always sufficient to provide the first three letters. In French, however, you need at least four letters, to distinguish between "Juin" (June) and "Juillet" (July). Parse-O-Matic can use only one POMDATE.CFG file at a time, so the MONTHNUM command can not be used to translate month names from one language to another. You can, however, accomplish the same thing with the LOOKUP command. 114 -------------------- The ZERODATE Command -------------------- ** ADVANCED COMMAND FOR EXPERIENCED USERS ** FORMAT: ZERODATE value1 value2 value3 PURPOSE: Specifies "day zero" for the date serial number used by the MAKETEXT command when it uses the DATE predefined data type. PARAMETERS: value1 is the year (e.g. "1900") value2 is the month (e.g. "12" for December) value3 is the day (e.g. "5") NUMERICS: Tabs, spaces and commas are stripped from value1, 2 and 3 DEFAULTS: If the ZERODATE command is omitted, the zero date is assumed to be Jan. 1, 1753 (equivalent to ZERODATE "1753" "1" "1"). SEE ALSO: "The MakeText Command" and "Predefined Data Types" A "date serial number" is a common method of representing a date in a data file. It works by counting the number of days since a given date, taking into account the extra days for leap years. Leap years occur in every year that is divisible by four, with the exception of century years -- unless they are divisible by 400. Thus, 1900 is not a leap year, but 2000 is. The ZERODATE command specifies "Day 0". For example, if you specify ZERODATE "1918" "11" "11" (November 11, 1918), you get the following: DATE DATE SERIAL NUMBER ----------------- ------------------ November 9, 1918 -2 November 10, 1918 -1 November 11, 1918 0 November 12, 1918 1 November 13, 1918 2 ... and so on. Most programs set the zero date far enough back that negative numbers are not encountered in normal usage. ZERODATE will not accept a starting year before "1753", which was the first full year that most of the Western world started using the Gregorian calendar. 115 ============================================================================ CALCULATION COMMANDS ============================================================================ ---------------- The CALC Command ---------------- FORMAT: CALC var1 value1 operation value2 PURPOSE: The CALC command performs an integer arithmetic operation on the two values and assigns the answer to var1. NUMERICS: Tabs, spaces and commas are stripped from value1 and value2 ALTERNATIVES: The CALCREAL command SEE ALSO: "Inline Incrementing and Decrementing" Integer arithmetic refers to whole numbers. 1, 10 and 10000 are integers, while 2.0, 3.14159 and 98.5 are not. Let's say your input file looks like this: DESCRIPTION UNITS SOLD UNIT PRICE ---------------- ---------- ---------- Dog collar 15 $ 3.00 Cat collar 25 $ 2.50 Cat caller 3 $ 7.25 Birdie num-nums 1,305 $ 6.25 ---------------- ---------- ---------- End of Data : : : : : : : : : : (Column positions) 1 18 27 33 41 116 You can find out the total number of units sold (of all types) with the following POM file: IGNORE $FLINE[1 7] = "DESCRIP" IGNORE $FLINE[1 7] = "-------" BEGIN $FLINE = "End of Data" OUTEND |Total units sold = {units} ELSE CALC units = units "+" $FLINE[18 27] END As you can see from the example, all spaces and commas are stripped from the number. Tab characters (ASCII 09) are also stripped. You will also notice that CALC can not be used for the prices, since they are not integer data. To add up the prices, you must use the CALCREAL command (see "The CalcReal Command"). Note in particular that the operation ("+" in this case) is in quotes. If you omit the quotes, Parse-O-Matic will report an error. The following operations can be performed with CALC: SYMBOL DESCRIPTION --------- -------------------------------------------- "+" value1 plus value2 "-" value1 minus value2 "*" value1 times value2 "/" value1 divided by value2 (remainder ignored) "HIGHEST" the larger number (value1 or value2) "LOWEST" the smaller number (value1 or value2) Here are some more examples of the CALC command: COMMAND ANSWER -------------------------------- ------ CALC answer = "12" "/" "4" "3" CALC answer = "12" "HIGHEST" "4" "12" CALC answer = "12" "LOWEST" "4" "4" CALC answer = "12" "-" "4" "8" CALC answer = "12" "+" "4" "16" CALC answer = "12" "*" "4" "48" CALC can handle numbers between -2,147,483,648 and 2,147,483,647. 117 -------------------- The CALCREAL Command -------------------- FORMAT: CALCREAL var1 value1 operation value2 [fixed-decimals] PURPOSE: CALCREAL works the same way as CALC, except that it handles decimal numbers. NUMERICS: Tabs, spaces and commas are stripped from value1, value2, and the "fixed-decimals" value ALTERNATIVES: The CALC command SEE ALSO: "The Rounding Command" Using the sample data given in the CALC section, you could write the following POM file: IGNORE $FLINE[1 7] = "DESCRIP" IGNORE $FLINE[1 7] = "-------" BEGIN $FLINE = "End of Data" OUTEND |Total units sold = {units} OUTEND |Total value sold = {value} ELSE CALC units = units "+" $FLINE[18 27] CALCREAL value = value "+" $FLINE[33 41] END CALCREAL can handle values +/- 99,999,999,999, but its accuracy decreases when you are dealing with large numbers, as approximated below: Accurate to 1 decimal place between +/- 9,999,999,999 Accurate to 2 decimal places between +/- 999,999,999 Accurate to 3 decimal places between +/- 99,999,999 Accurate to 4 decimal places between +/- 9,999,999 Accurate to 5 decimal places between +/- 999,999 You can specify a fixed number of decimal positions in the answer by using the optional "fixed-decimals" value. For example: SET z = "3.14159" CALCREAL x = z "+" "0" "2" <-- This sets x to "3.14" CALCREAL x = z "+" "0" "4" <-- This sets x to "3.1415" You will notice, in the second example, that no "rounding" takes place. The number is simply truncated at the requested decimal position. 118 Here are some more examples of the CALCREAL command: COMMAND ANSWER ----------------------------------------------- -------- CALCREAL answer = "12.0" "*" "4.0" "2" "48.00" CALCREAL answer = "12.0" "HIGHEST" "4.0" "2" "12.00" CALCREAL answer = "12" "LOWEST "4" "1" "4.0" CALCREAL answer = "12" "-" "4" "3" "8.000" CALCREAL answer = "12" "+" "4" "1" "16.0" CALCREAL answer = "7" "/" "2" "2" "3.50" CALCREAL answer = "7" "/" "2" "3.5" CALCREAL answer = "7" "*" "2" "14.0" As shown in the examples, if you do not use the optional fixed-decimal value, calculations are in "floating point". That is to say, the answer has as many decimal places as necessary. (Bear in mind the accuracy restrictions mentioned earlier.) Trailing zeros are removed, unless there are no digits after the decimal point, in which case a 0 is added. ------------------------ The INC and DEC Commands ------------------------ FORMAT: INC var1 [value1] DEC var1 [value1] PURPOSE: INC: Adds 1 (or whatever value1 is set to) to var1 DEC: Subtracts 1 (or whatever value1 is set to) from var1 NUMERICS: Tabs, spaces and commas are stripped from var1 and value1. Both var1 and value1 must be integers. var1 must be between -2147483640 and 2147483647. value1 must be between -100000000 and 100000000. DEFAULTS: If value1 is not specified, it is assumed to be "1". ALTERNATIVES: The CALC command SEE ALSO: "Inline Incrementing and Decrementing" The INC command adds "1" to var1, while the DEC command subtracts "1". You can also specify a number other than "1" by specifying the optional value1. Here is a sample sequence of commands... SET x = "" <-- Parse-O-Matic treats null numerics as equal to "0" INC x <-- Sets x to "1" INC x <-- Sets x to "2" DEC x <-- Sets x to "1" INC x "2" <-- Sets x to "3" DEC x "3" <-- Sets x to "0" 119 Note that if you specify a negative value for value1, INC and DEC work the opposite way. For example, if you subtract "-1" from "2", you would get "3". Here are some examples: SET x = "10" DEC x "-2" <-- Sets x to "12" INC x "-3" <-- Sets x to "9" Incrementing or decrementing a variable by "0" leaves it unchanged. -------------------- The ROUNDING Command -------------------- FORMAT: ROUNDING "Y" or ROUNDING "N" PURPOSE: Controls rounding of answers given by the CALCREAL command when it is in "fixed-decimal" mode. PARAMETERS: ROUNDING "Y" turns on rounding (the default) ROUNDING "N" turns off rounding ALTERNATIVES: The CALCREAL command can be used in "floating point" mode, and you can perform rounding and truncation operations yourself, within the POM file. Due to the way that real numbers (as opposed to integers) are calculated in binary, CALCREAL can sometimes return unexpected results. For example: CALCREAL x = "400.00" "-" "390.60" produces the answer "9.399999" rather than the expected answer of "9.4". This discrepancy is due to the nature of real-mode calculations in binary (i.e. inside the computer). The answer is actually very close indeed to the correct answer, yet it could cause problems if you specify the actual number of digits of precision ("fixed-decimals" mode instead of "floating point" mode). For example: ROUNDING "N" <-- This is explained later CALCREAL x = "400.00" "-" "390.60" "2" <-- 2 digits of precision This sets the x variable to "3.39", which is clearly wrong. What has happened is that the remaining digits of the floating-point answer were simply truncated (i.e. removed). 120 Normally, Parse-O-Matic's built-in rounding will add a small value appropriate to the number of digits of fixed-decimal precision you have specified: PRECISION SAMPLE NUMBER ROUNDING VALUE --------- ------------- -------------- 1 9.9 + 0.05 2 9.99 + 0.005 3 9.999 + 0.0005 ... and so on. Thus, CALCREAL "400.00" "-" "390.60" "2" first generates the floating-point answer "9.3999999999", adds "0.005", yielding "9.4049999999". This is then truncated to two digits, yielding "9.40", which is the correct answer. You can turn this rounding behavior off with the following command: ROUNDING "N" You can turn it back on with this command: ROUNDING "Y" By default, rounding is enabled, so unless you explicitly turn it off, there is no need to use the ROUNDING "Y" command. No rounding is performed when CALCREAL is used in "floating-point" mode. -------------------- The CALCBITS Command -------------------- ** ADVANCED COMMAND FOR EXPERIENCED USERS ** FORMAT: CALCBITS var1 value1 operation value2 PURPOSE: CALCBITS performs logical operations SEE ALSO: "The MakeData Command" The CALCBITS command performs "bit-wise" operations on single bytes. The following operations can be performed with CALCBITS: SYMBOL DESCRIPTION --------- --------------------------------- "AND" value1 AND value2 "OR" value1 OR value2 "XOR" value1 XOR value2 "SHR" Shift value1 right by value2 bits "SHL" Shift value1 left by value2 bits Let us say you want to strip the high bit from all of the bytes in an input file. You could accomplish this with the following POM file: 121 CHOP 1-1 <-- Read the input file one byte at a time CALCBITS z $FLINE "AND" $7F <-- Remove the high bit from the byte OUT |{z} <-- Send the result to the output file Note that because we are reading the file one byte at a time, $FLINE is always one byte long. Parse-O-Matic will terminate with an error message if you attempt to use CALCBITS with a value longer than one byte. Thus, assuming the variable xyz contains "ABCDEF", the following line is valid: CALCBITS answer = xyz[3] "AND" $7F However, the following line would not be permitted because it refers to more than one byte: CALCBITS answer = xyz[3 4] "AND" $7F Here are some more examples of the CALCBITS command: COMMAND ANSWER COMMENTS ------------------------------- ------ ------------------------------ CALCBITS answer = $FF "AND" $7F $7F CALCBITS answer = "9" "AND" $39 $39 $39 is the character "9" CALCBITS answer = $F0 "OR" $0F $FF CALCBITS answer = $7F "XOR" $08 $77 CALCBITS answer = $80 "SHR" $01 $40 $80 = 10000000; $40 = 01000000 CALCBITS answer = $01 "SHR" $01 $00 $01 = 00000001; $00 = 00000000 CALCBITS answer = $01 "SHL" $01 $02 $01 = 00000001; $02 = 00000010 CALCBITS answer = $80 "SHL" $01 $00 $80 = 10000000; $00 = 00000000 In most of these examples, we use hex notation (e.g. $01), but you can also use single characters (e.g. "3" which is equivalent to $33) or decimal notation (e.g. #64 which is equivalent to $40). However, you should always bear in mind that you are working with the underlying bit pattern. The following lines are NOT equivalent: CALCBITS answer = $7F "SHL" $01 <-- Shifts left one bit CALCBITS answer = $7F "SHL" "1" <-- This is not the same! The second line interprets "1" as hex $31 (decimal 49). There is obviously no point in shifting an eight-bit byte 49 positions to the left. 122 ============================================================================ INPUT PREPROCESSORS ============================================================================ ----------------- The SPLIT Command ----------------- FORMAT: SPLIT from-position to-position [,from-pos'n to-pos'n] [...] SEE ALSO: "The Leftover Technique" IMPORTANT: This command is analyzed at compile time, which means it can not be used conditionally (i.e. in a BEGIN/END block). The maximum length of an input line from a text file is 255 characters. If your input file is wider than that, you must break up the file into manageable chunks, using the SPLIT command. This command lets you specify the way in which each input line is broken up so that it will look like several SEPARATE lines. For example, if your input lines were up to 300 characters wide, you could specify: SPLIT 1 255, 256 300 This breaks up each line as if it was two lines. (If some of the lines are less than 256 characters, they will still be treated as two lines, although the second line will be null (i.e. empty).) You can specify up to 130 splits (use multiple SPLIT commands if necessary). With SPLIT, Parse-O-Matic can handle large input records, up to a maximum total length of 32767 characters. The best way of handling SPLIT or CHOPped files is to use a combination of the $SPLIT variable (explained in more detail later) and BEGIN/END. For example: SPLIT 1 250, 251 300 BEGIN $SPLIT = "1" SET a = $FLINE[ 1 10] SET b = $FLINE[11 20] END BEGIN $SPLIT = "2" SET x = $FLINE[ 1 10] SET y = $FLINE[11 20] OUTEND |{a} {b} {x} {y} END This outputs the data which appears (in the input file) in columns 1-10, 11-20, 251-260 and 261-280. 123 ------------------------------ Indicating Actual Input Length ------------------------------ The final split must indicate the maximum length of the line. Thus, if you have a text file with a maximum line length of 275, you still have to indicate this, even if you are only interested in the first 100 characters: SPLIT 1-100, 101-275 You could use IGNORE $SPLIT = "2" to get rid of the additional text lines. --------------------- Non-Contiguous Splits --------------------- Your splits do not have to be contiguous. For example, the following SPLIT command is legal: SPLIT 5 39, 41 100, 247 285 The first four characters of each split would be ignored, so your first split would contain only the characters at positions 5 to 39 of the line. Similarly, the second split would contain the 41st through 100th character, and the third split would contain the 247th through 285th character. 124 ---------------- The CHOP Command ---------------- FORMAT: CHOP from-position to-position [,from-pos'n to-pos'n] [...] CHOP 0 PURPOSE: Controls the number of bytes Parse-O-Matic will read from the input file each time it processes the POM file. SEE ALSO: "The Get Command" IMPORTANT: This command is analyzed at compile time, which means it can not be used conditionally (i.e. in a BEGIN/END block). The CHOP command works the same way as the SPLIT command, with one exception: it informs Parse-O-Matic that the input is a fixed-record- length file. In other words, it means that the input records are distinguished by having a particular (and exact) length, rather than being separated by end-of-line characters (Carriage Return, Linefeed) as is the case for a standard text file. Thus, if you have an input file containing fixed-length records, each of which is 200 characters wide, you could specify it like this: CHOP 1 200 If the input record is more than 255 characters, you must break it up into smaller chunks. For example, if the input record was 300 characters wide, you could break it up like this: CHOP 1 250, 251 300 By using CHOP, Parse-O-Matic can handle input records up to 32767 characters wide. You can use the $SPLIT variable to manage your use of CHOP. See the example in the section describing the SPLIT command. -------------- Manual Reading -------------- There is a special form of the CHOP command, which looks like this: CHOP 0 This tells Parse-O-Matic that you will handle all file reading yourself. In such case, $FLINE is always null. The only way to get data from the input file is with the GET command. When you use CHOP 0 for manual reading, the MINLEN and READNEXT commands have no meaning. If you place them in the POM file, they are ignored. 125 ============================================================================ LOOKUP COMMANDS ============================================================================ ------------------ The LOOKUP Command ------------------ FORMAT: LOOKUP var1 value1 PURPOSE: The LOOKUP command searches for value1 in a text file (the name of which is specified either by the LOOKFILE command or the /L startup parameter). When POM finds it, it sets var1 to another value found on the same line. ALTERNATIVES: The REMAP command Let us suppose you created a text file, named NAMES.TBL, like this: R. REAGAN Ronald Reagan D. EISENHOWER Dwight Eisenhower G. BUSH George Bush B. CLINTON Bill Clinton : : Column 1 Column 18 This file can be used to look up a name, as in this POM file: LOOKFILE "NAMES.TBL" LOOKCOLS "1" "17" "18" "34" SET oldname = $FLINE[21 37] TRIM oldname "R" " " LOOKUP newname = oldname OUTEND |{oldname} {newname} The LOOKFILE command specifies the name of the look-up file. The LOOKCOLS command specifies the starting and end columns for both the "text-to-look- for" field (known as the key field) and the "text-to-get" field (known as the data field). The LOOKUP command will look for oldname in NAMES.TBL. If oldname is set to "G. BUSH", LOOKUP sets newname to "George Bush". If, however, oldname is set to "G. WASHINGTON", which doesn't appear in NAMES.TBL, newname is set to "" (that is to say, an empty string). 126 ------------- Search Method ------------- When searching for the key field, LOOKUP compares text according to the length of the string you are looking for. If your LOOKUP file looks like this: ABCDEF 456 ABC 678 XYZABC 345 XYZ 123 then the command LOOKUP x = "XYZ" would match on "XYZABC". If this search procedure is a problem for you, there are two ways you can deal with it: 1) Pad your search strings before searching, as in this example: PAD search "R" " " "6" LOOKUP x = search If the search variable was original set to "XYZ", the PAD command would set it to "XYZ ", which would not match XYZABC. 2) Put the shorter key fields in the lookup file ahead of the longer ones (of which they are a sub-string), as in this example: ABC 678 ABCDEF 456 XYZ 123 XYZABC 345 It is worth pointing out that this look-up file is sorted in ASCII order (whereas the example given earlier was not). A sorted file can be more efficient, as explained in "The LookSpec Command". ----------- Limitations ----------- There is no limit to the number of lines that you can put in a look-up file. However, the more lines there are, the longer it will take to process (because there is more to search). The maximum length of a line in a look-up file is 255 characters. 127 ----------------------- Null Lines and Comments ----------------------- In the look-up file, null (empty) lines are ignored. You can also include comments in the file by starting the line with a semi-colon: ; Some of the Presidents of the United States R. REAGAN Ronald Reagan D. EISENHOWER Dwight Eisenhower G. BUSH George Bush The LOOKUP command can be used for more than just names, of course. You could use it to look up prices, phone numbers, addresses and so on. ---------------- Multiple Columns ---------------- You can use the same lookup file to find different items that are related to the same key field. For example, let's say you have created a lookup file, named EMPLOYEE.TBL, which looks like this: ; EMPLOYEE# NAME PHONE 00001 John Smith 555-1212 00002 Mary Jones 555-2121 00003 Fred Johnson 555-1122 You could look up an employee's name and phone number as follows: LOOKFILE "EMPLOYEE.TBL" LOOKCOLS "3" "7" "15" "37" LOOKSPEC "N" "Y" "N" LOOKUP empdata = "00002" SET name = empdata[ 1 12] SET phone = empdata[16 23] TRIM name "B" " " TRIM phone "B" " " You could, of course, specify a different LOOKCOLS prior to each LOOKUP, but that would mean reading the disk twice. It most cases, it is faster to obtain the data all at once, then extract it. 128 ------------------- LOOKUP Versus REMAP ------------------- If you have only a few thousand bytes of lookup data, you might be able to use the REMAP command instead of LOOKUP. However, you can not simply replace LOOKFILE and LOOKUP with MAPFILE and REMAP. REMAP does not return a null value if it can not find the item being sought, so you will have to change your POM file to compare the original string with the revised string, in order to see if it has changed (i.e. it was found). Even with this test, REMAP might "fool you" if it finds a partial match. If you are processing a lot of input data, using REMAP may speed up processing, since REMAP works in RAM memory, while LOOKUP reads the disk. However, if your disk uses "caching", the performance improvement may be negligible. -------------------- The LOOKFILE Command -------------------- FORMAT: LOOKFILE value1 PURPOSE: The LOOKFILE command specifies the name of the look-up file for the next LOOKUP command. SEE ALSO: "How Parse-O-Matic Searches for a File" LOOKFILE lets you use several look-up files in one POM file. For example: SET name = $FLINE[1 20] ; Look up the name LOOKFILE "NAMES.TBL" LOOKCOLS "1" "25" "30" "50" LOOKUP fullname = name ; Look up phone number LOOKFILE "PHONE.TBL" LOOKCOLS "1" "25" "30" "40" LOOKUP phone = name ; Output result OUTEND |{name} {fullname} {newname} If you only have one look-up file, you may omit the LOOKFILE command and specify the file name on the command line, using the /L parameter. For example, you could write a POM file like this: 129 SET name = $FLINE[1 20] ; Look up the name LOOKCOLS "1" "25" "30" "50" LOOKUP fullname = name ; Output result OUTEND |{name} {fullname} Your POM command could then look like this: POM MYPOM.POM INPUT.TXT OUTPUT.TXT /LC:\MYFILES\NAMES.TBL This technique allows you to use several different look-up files with the same POM file, simply by changing the command line. (The method by which Parse-O-Matic finds the file is discussed in the section "How Parse-O-Matic Searches for a File".) The longest line allowed in a look-up file is 255 characters long. If you specify a null look-up file name (e.g. LOOKFILE ""), Parse-O-Matic closes the current look-up file (if one is open). This is necessary if you wish to delete the file, using the ERASE command. -------------------- The LOOKCOLS Command -------------------- FORMAT: LOOKCOLS value1 value2 value3 value4 PURPOSE: The LOOKCOLS command specifies the starting and ending columns for the key and data fields in a look-up file (see the explanation of the LOOKUP command for an overview of look-up files). PARAMETERS: value1 specifies the starting column for the key field value2 specified the ending column for the key field value3 specifies the starting column for the data field value4 specified the ending column for the data field NUMERICS: Tabs, spaces and commas are stripped from value1, 2, 3 and 4 You can specify a null value to indicate "same as last time". For example: SET name = $FLINE[1 20] LOOKFILE "NAMES.TBL" LOOKCOLS "1" "25" "30" "50" LOOKUP fullname = name LOOKFILE "PHONE.TBL" LOOKCOLS "" "" "" "40" LOOKUP phonenum = name OUTEND |{name} {fullname} {phonenum} The second LOOKCOLS command uses the same numbers for the first three values that the first LOOKCOLS command used. 130 If you do not specify a LOOKCOLS command, the default values are: Key Field: Starting column = 1 Ending column = 10 Data Field: Starting column = 12 Ending column = 255 This is equivalent to LOOKCOLS "1" "10" "12" "255". -------------------- The LOOKSPEC Command -------------------- FORMAT: LOOKSPEC value1 value2 value3 PURPOSE: The LOOKSPEC command configures the way the next LOOKUP command will work. PARAMETERS: value1 = Trim ("Y" or "N" -- default "Y") value2 = Sorted ("Y" or "N" -- default "N") value3 = Case-sensitive ("Y" or "N" -- default "N") The Trim setting specifies whether or not the data field should have spaces stripped off both ends. The Sorted setting specifies whether or not the look-up file is sorted by the key field. A sorted file is much faster than an unsorted file. This is especially noticeable if you have a large look-up file and a lot of input to process. The Case-sensitive setting specifies whether or not LOOKUP should distin- guish between upper and lower case when searching. The default setting is "N" (No), so that LOOKUP would find "John Smith", even if it appeared in the look-up file as "JOHN SMITH". It is usually safest to set Case- sensitivity to "N", but if you set it to "Y", searching is slightly faster. You can specify a null value to indicate "same as last time". For example: SET name = $FLINE[1 20] LOOKFILE "DATA.TBL" LOOKCOLS "1" "25" "30" "50" LOOKSPEC "Y" "Y" "Y" LOOKUP fullname = name LOOKCOLS "" "" "60" "70" LOOKSPEC "N" "" "" LOOKUP phonenum = name OUTEND |{name} {fullname} {phonenum} The second LOOKSPEC command uses the same settings for Sorted and Case- sensitivity as the first one, but specifies a different Trim setting. 131 ============================================================================ DATA CONVERTERS ============================================================================ -------------------- The MAKEDATA Command -------------------- ** ADVANCED COMMAND FOR EXPERIENCED USERS ** FORMAT: MAKEDATA var1 value1 value2 PURPOSE: MAKEDATA converts text data into a binary format. PARAMETERS: var1 is the variable being set value1 is the text data you want to convert value2 is the predefined data type you want to create NUMERICS: Tabs, spaces and commas are stripped from value1, if it is numeric (as indicated by value2) SEE ALSO: "Predefined Data Types" and "The CalcBits Command" When you are writing to a binary file (using the OUT command), you often need to convert text information to a binary representation. MAKEDATA recognizes many standard data formats (see "Predefined Data Types"). -------------------- Creating Binary Data -------------------- Let us say you have a four-line text file that looks like this: 1234 -456 23 90211 Here is a POM file that reads the numbers from the file, then outputs them in binary format, as 16-bit signed integers: MAKEDATA z $FLINE "INTEGER" <-- Convert the number to an integer OUT |{z} <-- Send the integer to the output file We use OUT instead of OUTEND, since OUTEND would put an end-of-line (Carriage Return, Line Feed) after the data. If the POM file shown in the example was run with the input data shown, it would create an output file containing four integers. In other words, the file would be eight bytes long (four integers of two bytes each). 132 ---------------- Converting Dates ---------------- In some files, a date serial number (see "The ZeroDate Command") might be represented by a numeric format such as INTEGER or LONGINT. To write a date serial number to the output file, you must first convert the date with MAKEDATA, then use MAKEDATA again to convert the resulting number to the appropriate data type. The value1 part of the MAKEDATA must be in a precise format: "YYYY [M]M [D]D" <-- Square brackets indicate optional digits That is to say: 1) A four-digit year 2) A space 3) A one or two digit month (January = 1 or 01, December = 12) 4) A space 5) A one or two digit day of the month (e.g. 1 or 01 or 31) You can assemble the date string from various other data, using the DATE command. Let us say you have a one-line text file that contains the date in Month-Day-Year format: 01-01-2001 You can read this file and output a date serial number as a long integer (LONGINT) with the following POM file: ZERODATE "2000" "1" "1" <-- Set "day zero" SET year = $FLINE[7 10] <-- Get the year SET month = $FLINE[1 2] <-- Get the month SET day = $FLINE[4 5] <-- Get the day of the month DATE x year month day "Y ?n ?d" <-- Set x to "2001 01 01" MAKEDATA y x "DATE" <-- Set y to "366" MAKEDATA z y "LONGINT" <-- Set z to a long integer OUT |{z} <-- Place it in the output file A typical problem with date data is that the year does not include the first two digits (e.g. you have "97" instead of "1997"). In such cases, your POM file has to make a decision as to which century the date belongs to. Here is one way to handle this situation: BEGIN year #>= "50" CALC year = year + "1900" ELSE CALC year = year + "2000" END 133 This works around the problem as follows: Any year between is placed in Examples ---------------- ---------------- -------------- "50" and "99" the 20th century "1950" "1999" "00" and "49" the 21st century "2000" "2049" You have to be careful when choosing the "cut-off date" (1950, in the example above). You should make your decision only after studying your input data carefully. ------------------------ Practical Considerations ------------------------ The examples shown here assume that your input file contains only one kind of data. In most cases, you will use the CHOP command to obtain complete data records of fixed length, then use SET to extract portions thereof. If you are reading a file with variable-length records, you can use CHOP 0 (manual reading) and the GET command. -------------------- The MAKETEXT Command -------------------- ** ADVANCED COMMAND FOR EXPERIENCED USERS ** FORMAT: MAKETEXT var1 value1 value2 PURPOSE: MAKETEXT converts binary data into text format. PARAMETERS: var1 is the variable being set value1 is the data you want to convert value2 is the predefined data type of value1 NOTES: value1 is normally in binary (i.e. it looks like "garbage characters" if you output it to a text file). However, if value2 specifies the DATE data type, value1 must be in text form (e.g. "1234"). The reason for this difference is described in the "Converting Dates" section below. SEE ALSO: "Predefined Data Types" When reading a binary file (using the CHOP command), you often need to convert binary information to a text representation. MAKETEXT recognizes many standard data formats (see "Predefined Data Types"). 134 ---------------------- Converting Binary Data ---------------------- Let us say you have a binary file that contains several WORD values (unsigned integers, each of which is 2 bytes long). You can read and decode them with the following POM file: CHOP 1-2 <-- Read the file two bytes at a time MAKETEXT x $FLINE "WORD" <-- Convert the WORD to text format OUTEND |{x} <-- Output the data to a text file ---------------- Converting Dates ---------------- MAKETEXT can convert a date serial number (see "The ZeroDate Command") to a formatted date. Since there is no standard data format for date serial numbers, you must use MAKETEXT to convert the number into text form, and then use MAKETEXT again to format the date. Let us say you have a binary file that contains dates, represented as LONGINTs (4-byte signed integers). You could convert them to dates with the following POM file: CHOP 1-4 <-- Read 4 bytes at a time ZERODATE "1936" "1" "1" <-- Set the "zero date" MAKETEXT x $FLINE "LONGINT" <-- Convert the binary data to a text number MAKETEXT y x "DATE Y-M-?d" <-- Convert to text date (e.g. "1998-JUL-01") OUTEND |{y} <-- Output the date to a text file ------------------------ Practical Considerations ------------------------ The examples shown here assume that your input file contains only one kind of data. In most cases, you will use the CHOP command to obtain complete data records of fixed length, then use SET to extract portions thereof. If you are reading a file with variable-length records, you can use CHOP 0 (manual reading) and the GET command. 135 ============================================================================ MISCELLANEOUS COMMANDS ============================================================================ ----------------- The ERASE Command ----------------- FORMAT: ERASE value1 PURPOSE: Deletes a file (if it exists). PARAMETERS: value1 is the name of the file to be deleted SEE ALSO: "Long File Names in Win95" Here is an example of the ERASE command: ERASE "C:\XYZ.TXT" This will delete the file C:\XYZ.TXT if it exists. If it does not exist, nothing is done. You can not delete the current input file, output file, trace file or lookup file. If you attempt to do so, Parse-O-Matic will terminate with an error. You can not delete a device (e.g. ERASE "LPT1:"). The ERASE command simply ignores such requests. If value1 is preceded by a "+" character, the plus sign is ignored. See "How Parse-O-Matic Opens an Output File" for an explanation of the significance of the plus sign. 136 -------------------- The FILESIZE Command -------------------- FORMAT: FILESIZE var1 value1 PURPOSE: Determines the size of a file, in bytes PARAMETERS: var1 is the variable being set with the file size value1 is the name of the file SEE ALSO: "Long File Names in Win95" The FILESIZE command can be used to obtain the size of a file, or to see if a file exists. If the file does not exist, FILESIZE sets var1 to a null ("") string. If the file exists, FILESIZE sets var1 to the number of bytes in the file (from 0 to 2,147,483,647 bytes). For those rare files that are larger than 2,147,483,647 bytes, FILESIZE will produce an unpredictable result and may even cause Parse-O-Matic to fail. Nevertheless, it is possible to process such large files -- all of the other commands will work normally. 137 ------------------ The GETENV Command ------------------ FORMAT: GETENV var1 value1 PURPOSE: GETENV obtains a system environment variable PARAMETERS: var1 is the variable being set value1 is the name of the system environment variable NOTES: System environment variables are sometimes referred to as "DOS Environment Variables" or "SET Variables". SEE ALSO: Explanations of the SET & PATH commands in your DOS manual, or "The Environment Area" in your Windows or OS/2 manual. ALTERNATIVES: See "Command-line Parameters" in the "Command-Line Techniques" section of this manual. GETENV enables you to access certain important settings that concern your computer's operating system. To see what settings are available, enter the following command at the DOS prompt: SET This will display the contents of your computer's "environment area". Two of the most important values in the environment area are COMSPEC and PATH. These are briefly described later, but refer to your operating system manual for full details. GETENV removes all spaces, tabs and equals-signs ("=") from value1, converts it to uppercase, then looks it up in the system environment area. - If it finds it, var1 is set to the corresponding value. - If it does not find it, var1 is set to an empty (null) string. ---------------------------------- Disappearing Environment Variables ---------------------------------- Sometimes an environment variable disappears for no apparent reason. There are two likely reasons for this: 1) You ran out of environment space. There is only a limited amount of room in the system environment area (which is located in RAM memory). If you think this is the problem, type your DOS SET command to save a variable into the system environment, then type SET by itself to review the contents of the environment. If your variable does not appear, consult your operating system manual to find out how to expand your environment space. 138 2) It was set by a COPY of the operating system. If you are in Windows and you run DOS, then use the DOS SET command, it will only affect the environment area associated with the copy of DOS that you are running. When you exit this copy and start up another one, it will not contain the variable. You can address this problem by setting the variable in your AUTOEXEC.BAT file, or by running a batch file that sets the variable before running Parse-O-Matic. -------- Examples -------- The following command will determine which directories get searched when you are looking for a program or a file: GETENV path "PATH" To find out the name of your command interpreter (usually COMMAND.COM) and where it is located, try this command: GETENV comspec "COMSPEC" You can use GETENV as a simple "input routine" for Parse-O-Matic applications. For details, see "Controlling a POM File from the Command Line", in the section entitled "Effective Use of Batch Files". --------------- The LOG Command --------------- FORMAT: LOG value1 [comparator] value2 value3 [value4 [value5]] PURPOSE: LOG places a message (value3) in the processing log file (POMLOG.TXT) if the comparison is true. Both value4 and value5 are optional; if they are present, they are added to end of value3. NOTES: The processing log is described in the section "Logging". ALTERNATIVES: The SHOWNOTE command 139 Here is an example of the LOG command: SET emplnumb = $FLINE[ 1 9] SET sales = $FLINE[10 20] TRIM sales "B" " " LOG sales = "0" "WARNING! Zero sales for employee number:" LOG sales = "0" emplnumb This adds two warning lines to the processing log if the sales figures is zero. The logging feature lets you run Parse-O-Matic unattended, then come back later to review (via the processing log) any exceptional conditions. For some additional comments on logging, see "Unattended Operation". The maximum length of a LOG string (value3, plus value4 and value5 if present) is 245 characters. ------------------- The MSGWAIT Command ------------------- FORMAT: MSGWAIT value1 PURPOSE: MSGWAIT controls the amount of time that a processing error message appears on the screen before it times out. (Messages from the HALT command are treated as error messages.) PARAMETERS: value1 is the delay time in seconds NUMERICS: Tabs, spaces and commas are stripped from value1 DEFAULTS: If the MSGWAIT command is not included in the POM file, and an error occurs, Parse-O-Matic will wait until you press a key; the message will not time out. NOTES: If value1 is "0", error messages will not time out. The maximum value for value1 is 60000 (about 16 hours). You can set value1 to "1", but one second is usually too short a delay; a value of "60" (one minute) is better. SEE ALSO: "The Halt Command", "Unattended Operation", "Quiet Mode" The MSGWAIT command lets you control the behavior of error messages that appear during the processing of an input file. This is helpful if you have created POM applications that are run unattended. If Parse-O-Matic was invoked by a batch file or application program, you want may error messages to "time out", allowing Parse-O-Matic to terminate, and processing to continue. 140 ----------------- Standard Behavior ----------------- If Parse-O-Matic encounters an error while reading in a POM file (i.e. during the "compile" step), it displays a message on the screen and waits until you press a key. Parse-O-Matic then terminates. When running the actual POM file (i.e. while processing the input file), Parse-O-Matic will normally behave the same way: if an error occurs (or if a HALT command is encountered), it will display a message on the screen and wait for you to press a key before it terminates. ------------------------ Setting a Time-Out Delay ------------------------ You can use the MSGWAIT command to tell Parse-O-Matic to continue ("time out") after a certain number of seconds. For example: MSGWAIT "60" This tells Parse-O-Matic to wait about 60 seconds if an error is encountered while processing the input file. Parse-O-Matic will then terminate. (The actual delay depends on the type of computer you are using; a delay of "60" will typically last between 55 and 65 seconds). ---------- Color Cues ---------- If you have a color monitor, you can tell if a message will "time out" by the color of the "Press a key to continue" prompt: - If it is magenta (sometimes called "purple") it will NOT time out - If it is blue, if WILL time out ------------ Key Stacking ------------ To ensure that an error message is not inadvertently bypassed, "stacked" keystrokes are ignored by Parse-O-Matic. That is to say, if you press several keys before an error message is displayed, Parse-O-Matic gets rid of them before displaying the message. 141 ---------- Exceptions ---------- If Parse-O-Matic is processing an empty input file, it will display the warning "Input file is empty", then continue processing the POM file when you press a key, or after a delay of about 60 seconds. The MSGWAIT command does not affect messages that report errors detected during the compilation (initial read-in) of the POM file. The MSGWAIT command does not affect the "Retry or Cancel" message that appears if you are dealing with a device (see "Sending Output to a Device"). ----------------- A Word of Caution ----------------- A POM file should be thoroughly tested before setting the MSGWAIT time to a value other than "0". Most error messages are serious enough to justify waiting until the user acknowledges them. If you call Parse-O-Matic from a batch file or application program, you can check the success of the parsing job by checking the return code. (See "Effective Use of Batch Files" and "Running Parse-O-Matic from Another Program"). If there was a processing error and you did not check the parsing job (either by testing the program return code, or by consulting the processing log), the resulting oversight could be serious. ----------------- The PAUSE Command ----------------- FORMAT: PAUSE value1 PURPOSE: Delays the specified number of milliseconds PARAMETERS: value1 is the delay time (between 1 and 65500) NUMERICS: Tabs, spaces and commas are stripped from value1 NOTES: 1 millisecond = One thousandth of a second 100 milliseconds = One tenth of a second 1000 milliseconds = One second 60000 milliseconds = One minute 142 Here are some typical applications of the PAUSE command: - Slow down Parse-O-Matic so you can watch the processing screen - Give a slow laser printer extra time to eject a page after an OUTPAGE - Give you time to remove a page from a dot-matrix printer after an OUTPAGE - Give a communications device time to complete its current operation Here is an example of the latter application: OFILE "COM1:" <-- Direct output to the modem on COM1 OUTEND |ATZ <-- Send a modem initialization command PAUSE "1000" <-- Wait one second for the command to complete OUTEND |ATDT555-1234 <-- Send a dialing command to the modem If your PAUSE command is 200 milliseconds or longer, Parse-O-Matic displays a "PAUSED" message in the lower right corner of the processing screen. While this appears, you can press any key to end the pause. (We recommend that you use the spacebar -- and avoid the Esc key. Parse-O-Matic processing will be terminated if the PAUSE happens to end at the precise moment your finger is coming down on the Esc key!) ------------------ The RANDOM Command ------------------ FORMAT: RANDOM var1 value1 value2 PURPOSE: Generates a random integer number PARAMETERS: var1 is the variable being set value1 is the minimum number allowed (between 0 and 65534) value2 is the maximum number allowed (between 0 and 65534) NUMERICS: Tabs, spaces and commas are stripped from value1 The RANDOM command generates a random number in the range specified by value1 and value2. For example, to simulate the rolling of a six-sided die: RANDOM roll "1" "6" The first time you call this, it might set the roll variable to "3". The next time, it might set it to "1". The roll variable will never be lower than "1" or higher than "6". 143 The minimum value must always be less than or equal to the maximum value. Thus, the following statement will cause an error: RANDOM x "100" "1" <-- This is incorrect If value1 and value2 are the same, RANDOM will always generate the same number. SET n = "50" RANDOM z n n This will always set the z variable to 50. -------------------- The SHOWNOTE Command -------------------- FORMAT: SHOWNOTE value1 [value2] [value3] [value4] [value5] PURPOSE: Displays a message on the processing screen PARAMETERS: value1 to value5 are values that will be displayed ALTERNATIVES: The LOG command When you are doing especially intense parsing, it is nice to see some kind of indication of what is happening. The SHOWNOTE command displays a message up to 40 characters long in the lower left corner of the processing screen. For example: SHOWNOTE "Reading employee data" This will display the message "Reading employee data" until the parsing job ends, or until another SHOWNOTE command is encountered. You can remove a note from the processing screen by providing a null value: SHOWNOTE "" This clears a note that is already on the processing screen. You can display up to 5 values in a SHOWNOTE message. Each value will be separated from the others by a space. For example: SHOWNOTE "Employee:" empnum " -- Last name:" lastname This would display a note like this: Employee: 314159 -- Last name: Smith 144 Bear in mind that you have only 40 characters for the note. If the lastname variable in the preceding example was "Von Neumann", the display would be truncated to forty characters, and display the note as follows: Employee: 314159 -- Last name: Von Neuma ----------- Other Notes ----------- There are three kinds of notes that are displayed in the lower right corner of the processing screen: TYPE OF NOTE COLOR TEXT REASON ------------- ---------- -------------------- -------------------- SHOWNOTE Light Grey Whatever you specify The SHOWNOTE command PAUSE Light Red PAUSED The PAUSE command Error message Red TRYING TO PRINT Printer is offline In most cases, these messages will not interfere with each other. ------------ Slowing Down ------------ If you are running Parse-O-Matic on a fast machine, your SHOWNOTE messages blaze by so fast that there are not particularly helpful. Here is a POM file that demonstrates one solution: SET line_counter = line_counter+ SET note_control = note_control+ BEGIN note_control = "100" SET note_control = "0" SHOWNOTE "Processing line #" line_counter END OUTEND |{$FLINE} This will perform the SHOWNOTE command on every hundredth input line. ----------------- The SOUND Command ----------------- FORMAT: SOUND value PURPOSE: The SOUND command performs two functions: 1) It makes a noise, or ... 2) It sets the noise made when an error occurs 145 The SOUND command has a repertoire of nine distinctive noises: BEEP BIP BUZZ EDGE ERROR HUH PIP TRILL WHOOP These sounds are useful for alerting you to unusual situations. Let's say you wanted to be warned if one of the fields in a file comes up blank. You could write the code this way: BEGIN lastname = "" SOUND "WHOOP" SET lastname = "?" END Case is not important; the following commands are all equivalent: SOUND "WHOOP" SOUND "Whoop" SOUND "whoop" ------------------ The LISTEN Utility ------------------ You can listen to any given sound by using the LISTEN command at the DOS prompt. To hear what TRILL sounds like, enter this command: LISTEN trill By default, Parse-O-Matic error messages will alert you by playing the ERROR sound. To hear this sound, enter the following command at the DOS prompt: LISTEN error -------------------------------- Changing the Error Message Sound -------------------------------- If you find the error message sound noise annoying, you can replace it with one of the other sounds by using the special ERRMSG specification of the SOUND command. For example, to replace the ERROR sound with the BUZZ sound, place this line at the top of your POM file: SOUND "ERRMSG BUZZ" If you don't want any sound made when an error occurs, use this command: SOUND "ERRMSG QUIET" The ERRMSG specification will only affect errors generated during the actual running of the POM file. If an error is encountered while Parse-O-Matic is compiling the POM file, it will use the ERROR sound when it reports the problem. 146 ----------------- The TRACE Command ----------------- FORMAT: TRACE var1 PURPOSE: The TRACE command is an alternative to standard tracing (see "Tracing", in the "Programming Techniques" section). PARAMETERS: var1 is the variable being traced. When you include a TRACE command in your POM file, Parse-O-Matic will create a text file, named POM.TRC, and use it to keep a detailed record of POM's processing. Here is an example of the TRACE command: TRACE PRICE This traces the variable named "PRICE". After processing, the file POM.TRC will show everything that happened, and give the value of PRICE at the TRACE line. NOTE: Since trace files are so detailed, they can be very large. If you are trying to debug a POM file using TRACE, it is a good idea to use a small input file. 147 ============================================================================ TERMS ============================================================================ ------ Values ------ A value can be specified in the following ways: FORMAT OR SAMPLE DESCRIPTION ------------------ ----------- "text" A literal text string #number An ASCII character, in decimal (e.g. #32 = Space) #number#number... Several ASCII characters (e.g. #32#32 = 2 Spaces) $xx A byte, in hexadecimal (e.g. $2F = decimal 47) $xx$xx... Several hex bytes ($ff$ff = binary 1111111111111111) VARNAME The name of a variable VARNAME[start end] A substring of a variable VARNAME[start] A single character VARNAME+ Inline incremented variable (explained below) VARNAME- Inline decremented variable (explained below) (x,@y,z) Deduced variable name (see "Deduced Variables") x,y Explictly specified deduced variable --------- Variables --------- A variable is a named spot in your computer's memory that holds some data. Variable names can be up to 12 characters long. There is no distinction between upper and lower case in the variable name. A POM file can contain about 2000 variables and literals. In general, variable names should: - Use letters, numbers and the underscore character - Start with a letter It is possible to create variables that do not adhere to these rules, but this may cause you problems later on (particularly in subsequent releases of Parse-O-Matic which may use special characters to denote particular kinds of variables, or operations performed thereon). The # character is used to specify a literal text string of one or more characters. Follow each # with the decimal value of the ASCII character you want. Here are some useful values: #10 = Line Feed #12 = Form Feed #13 = Carriage Return 148 ----------------- Predefined Values ----------------- Parse-O-Matic predefines several variables. These are: VARIABLE DESCRIPTION ------------ ------------------------------------------------------------ $FLINE The line just read from the file (max. length 255 chars) (*) $FLUPC The line just read from the file, in uppercase (*) $LASTFLINE The previous value of $FLINE (*) $SPLIT The CHOP or SPLIT number you are currently processing (*) $LINECOUNTER The page line to which output will go next (*) $COMMAND The current POM command line (see "POM and Wildcards") $BRL The { character (used in OUT and OUTEND) $BRR The } character (used in OUT and OUTEND) $TAB The tab character (Hex $09; ASCII 09) (*) This is discussed in more detail, below. Although these predefined variables start with a dollar sign ($), it does not mean they are in some way "hexadecimal" (as in the case of the hex values mentioned earlier). In this case, the $ character indicates that the variables are defined by Parse-O-Matic. In general, you should avoid creating variables that start with anything but a letter. ------ $FLINE ------ CONTAINS: The line just read from the input file SEE ALSO: The READNEXT, GET and GETTEXT commands $FLINE contains the data just read from the input file (exception: see "DBF Files"). The data can be intelligible (human-readable) text, or it can be binary information -- Parse-O-Matic does not care what $FLINE contains. The maximum length of $FLINE is 255 bytes. You can use the SETLEN command to determine its actual length. 149 ------ $FLUPC ------ CONTAINS: The line just read from the input file, in uppercase SEE ALSO: The PROPER and CVTCASE commands $FLUPC is the same as the $FLINE variable, but in uppercase. Any changes to $FLINE will affect $FLUPC, since they are simply different "views" of the same data. $FLUPC is useful for checking for text inside the current input line if case is not important, and for obtaining the uppercase version of the data. For example: BEGIN $FLUPC ^ "PART#" <-- Detect "Part#", "part#" or "PART#" SET partnum = $FLUPC[10 15] <-- Extract the part number, in uppercase SET partname = $FLINE[16 30] <-- Extract the part name, as-is END Since $FLUPC is really just a different view of $FLINE, a modification of $FLUPC (for example, using the PEEL command) is transient and usually pointless; the next reference to $FLUPC will simply return the uppercase version of $FLINE. ---------- $LASTFLINE ---------- CONTAINS: The previous value of $FLINE SEE ALSO: The discussion of $FLINE, above When parsing data, we frequently need to refer back to the input line we just saw. This information is contained in the $LASTFLINE variable. The $LASTFLINE variable is affected by READNEXT, since that updates $FLINE. DBase files do not set $LASTFLINE, since they do not use $FLINE. At the start of parsing, $LASTFLINE is set to null (""). 150 ------ $SPLIT ------ CONTAINS: The CHOP or SPLIT number you are currently processing SEE ALSO: The GET and GETTEXT commands Since $FLINE has a maximum length of 255 characters, you will have to use the SPLIT or CHOP command if your input file is wider than that. NOTE: Use SPLIT for text files Use CHOP for fixed-record-length files The $SPLIT variable reports which segment of a CHOPped or SPLIT input line you are currently processing. For example, if you use this command... CHOP 1 255, 256 380 then $SPLIT will be set to "1" when Parse-O-Matic processes columns 1 to 255, and it will be set to "2" when processing columns 256 to 380. ------------ $LINECOUNTER ------------ CONTAINS: The page line to which output will go next SEE ALSO: "How Parse-O-Matic Opens an Output File" The $LINECOUNTER variable lets you know the number of the next output line. Consider this POM file: OUTEND |LINE# {$LINECOUNTER} OUTEND |LINE# {$LINECOUNTER} OUTEND |LINE# {$LINECOUNTER} DONE This will produce the following output: LINE# 1 LINE# 2 LINE# 3 The OUTPAGE command will reset the $LINECOUNTER to "1", since the next output line will be at the top of the page. OUTHDG commands also affect the $LINECOUNTER variable. The $LINECOUNTER variable is active even if you have not used the PAGELEN command to set the page length. By default, the page length is "0" (meaning "infinite"), which means that $LINECOUNTER will always be one greater than the total number of output lines. However, if you specify an explicit page length (e.g. PAGELEN "55"), $LINECOUNTER is reset to "1" after each page eject. 151 Using the SET command on $LINECOUNTER has no effect. In some special cases, however, you may wish to reset $LINECOUNTER to "1". You can do this -- even though you are not at the top of the page -- with the PAGELEN "0" command. (You can then follow this with another PAGELEN command if you want to restore the actual page length.) Here is a sample POM file that demonstrates why you might want to reset the $LINECOUNTER variable. It will format a text file which contains a form feed character (ASCII 12) at the end of each page, while placing page numbers at the bottom of each page as a "running footing": PROLOGUE <-- Start of prologue MINLEN "0" <-- Allow null lines SET pagenum = "1" <-- Set first page number END <-- End of prologue BEGIN $FLINE ^ #12 <-- Does this line have a form feed? BEGIN $LINECOUNTER #<= "54" <-+ OUTEND | | Put blank lines to the end of the page AGAIN <-+ APPEND x pagenum #12 <-- Set up the footer (including form feed) PAD x "L" " " "80" <-- Format the footer OUTEND |{x} <-- Output the footer SET pagenum = pagenum+ <-- Increment the page number PAGELEN "0" <-- Reset $LINECOUNTER to "1" ELSE OUTEND | {$FLINE} <-- Output a regular line END Note that as far as Parse-O-Matic is concerned, the "actual" output page length is "0" (i.e. "infinite"), but this POM file will output a text file that contains 55 lines per page. (A POM file similar to the one shown is used, with several others, to format this manual.) ------------------------------------------- Running Out of Variables, Literals or Lines ------------------------------------------- A POM file can contain 750 lines (not counting comment lines), and about 2000 variables and literals. If you have a very large POM file, this may not be enough, and you will be forced to do the processing with two or more POM files. You can link these together with a batch file, as follows: @ECHO OFF POM POMFILE1.POM INPUT.TXT TEMP.TXT IF ERRORLEVEL 1 GOTO QUIT POM POMFILE2.POM TEMP.TXT FINAL.TXT :QUIT 152 ---------- Delimiters ---------- If you need to specify a quotation mark, use "". For example: IGNORE $FLINE = "He said ""Hello"" to me." This ignores any line containing: He said "Hello" to me. ------------------ Illegal Characters ------------------ No POM command can contain these ASCII characters: HEX DECIMAL NAME ------- ------- -------------------- $00 #00 NULL $0A #10 LF (Linefeed) $0D #13 CR (Carriage Return) Of course, LF and CR do appear at the end of each line in the POM file, since a POM file is a text file. If you need to use one of the illegal characters in a POM command, use either the $ or # character to denote hex or decimal literals (e.g. SET linefeed = $0A). ----------------- Using Comparators ----------------- Several POM command decide what to do by comparing two values. For example: IF $FLINE[1 3] = "XYZ" THEN x = "3" ELSE "4" In this example, if the first three characters of $FLINE are "XYZ", the variable x is set to "3", otherwise it is set to "4". The first equals sign ("=") is a "comparator", because it defines how two values will be compared. The second equals sign is not a comparator; it is simply padding, which makes the line easier to understand (see the section "Padding for Clarity" for details). Parse-O-Matic supports several types of comparators: TYPE OF COMPARATOR WHAT IT DOES ---------- ------------------------- Literal Compares values character by character Numerical Compares the arithmetic values of real or integer numbers Length Compares the length of one value with a number 153 Whenever a comparator is required, but is omitted, it is assumed to be "literally identical". Thus, the following lines are equivalent: IF x y z "3" "4" (This is very terse, but it works) IF x y THEN z = "3" ELSE "4" (The "equals" comparator is omitted) IF x = y THEN z = "3" ELSE "4" (This is a lot easier to read) ------------------- Literal Comparators ------------------- Here is a list of literal comparators: COMPARATOR MEANING COMMENTS ---------- -------------------- ----------- = Identical <> Not identical > Higher See NOTE #1 >= Higher, or identical See NOTE #1 < Lower See NOTE #1 <= Lower, or identical See NOTE #1 ^ Contains ~ Does not contain SAMEAS Basically the same See NOTE #2 LONGER Length is longer SHORTER Length is shorter SAMELEN Length is the same NOTE #1: Depends on PC-ASCII sort order. Refer to the section "Literal Comparisons and Sort Order" for details. NOTE #2: The two variables are considered the same if they contain the same text, regardless of upper or lower case, and any surrounding whitespace. Thus " CHESHIRE CAT " is the same as "Chesire Cat". With some restrictions (discussed later), literal comparators work on numeric and alphabetic data. Here are some examples of literal comparisons that are "true": "ABC" <> "ABCD" "3" <> "4" "ABC" <= "ABCD" "3" <= "4" "ABC" < "ABCD" "3" < "4" "ABC" SHORTER "ABCD" "3" SAMELEN "4" "ABC" >= "ABC" "ABC" <> "CDE" "ABC" <= "ABC" "ABC" <= "CDE" "ABC" = "ABC" "ABC" < "CDE" "ABC" ^ "ABC" "ABC" SAMELEN "CDE" "ABC" SAMELEN "ABC" "ABC" ~ "CDE" 154 --------------------- Numerical Comparators --------------------- Here is a list of numerical comparators: COMPARATOR MEANING ---------- -------------------- #= Equal #<> Not equal #> Greater #>= Greater, or equal #< Less than #<= Less than, or equal ------------------ Length Comparators ------------------ Here is a list of length comparators: COMPARATOR MEANING ---------- -------------------- LEN= Equal LEN<> Not equal LEN> Greater LEN>= Greater, or equal LEN< Less than LEN<= Less than, or equal The length of the value on the left side of the comparator is compared with a number on the right side of the comparator. For example: IF $FLINE LEN= "0" THEN NullLine = "YES" ELSE "NO" ---------------------------------- Literal Comparisons and Sort Order ---------------------------------- Some of the literal comparators compare text according to "PC-ASCII sort order". For plain English text, this works fine. However, if your text contains diacritical (accented) characters, you should be aware that some comparisons will not work correctly. For example, the "A-Umlaut" character appears in the PC-ASCII character set AFTER the PC-ASCII value for "Z". 155 ------------------- Numeric Comparisons ------------------- Some confusion can arise if you use literal comparators on numbers. For example, this doesn't work as you might expect at first glance: SET count = count+ BEGIN count >= "2" OUTEND x = x |{count} END You might expect this POM file to output any number greater than or equal to "2", but in fact, you will get a different result, because the comparison is a literal (text) comparison. In the example above, "2" to "9" are greater or equal to "2", but "10" (which starts with "1") is less, as is evident when you sort several numbers alphabetically: 1 10 11 15 100 2 20 200 3 30 As you can see, the values 1, 10, 11 and 15 come before "2" when sorted alphabetically. To compare numbers, you should use the numeric comparators. The correct way to code the previous example is as follows: SET count = count+ BEGIN Count #>= "2" <-- Note the #>= comparator OUTEND x = x |{count} END Written in this way, numbers greater than or equal to two will be output. 156 Here are some examples of numeric comparisons that are "true": "345" #<> "567" "1.23" #<> "9.87" "345" #<= "567" "1.23" #<= "9.87" "567" #> "345" "9.87" #> "1.23" "3" #< "6.2" The last example compares an integer ("3") with a real number ("6.2"). The numeric comparators automatically check if one of the numbers contains a decimal point. In such case, the comparison is performed in "real number" mode, which imposes the accuracy restrictions described in the section "The CalcReal Command". This might create a problem if you are comparing a decimal number with a large integer, but this is rarely a cause for worry, since most parsing jobs tend to compare similar types of numbers. ------------------------------- Upgrading from Earlier Versions ------------------------------- IF YOU USED PARSE-O-MATIC PRIOR TO VERSION 3.00: Because the comparator defaults to "literally identical" if it is omitted, POM files created before version 3.00 will continue to function normally -- with two notable exceptions. In older versions, the IGNORE and ACCEPT commands defaulted to "contains". If you have POM files that were created for older versions, you should check your IGNORE and ACCEPT commands to ensure that they are doing what you want them to. --------------------- Predefined Data Types --------------------- For certain commands (e.g. MAKEDATA, MAKETEXT, GET and GETTEXT), Parse-O-Matic has internal definitions of certain data representations; these are known as Parse-O-Matic's "predefined data types": DATA TYPE BYTES MINIMUM VALUE MAXIMUM VALUE COMMENTS --------- ----- ------------- ------------- ----------- BYTE 1 0 255 INTEGER 2 -32768 32767 LONGINT 4 -2147483648 2147483647 REAL 6 -9999999999.9 9999999999.9 See NOTE #1 SHORTINT 1 -128 127 WORD 2 0 65535 DATE - - - See NOTE #2 TRIMMED - 0 chars 255 chars See NOTE #3 NOTE #1: The minimum and maximum values depend on the number of digits of precision. See "The CalcReal Command" for details. 157 NOTE #2: The DATE type does not have a specific length. In some input files, a date serial number might be represented by a numeric format such as INTEGER or LONGINT. For more information, see the discussions of the MAKETEXT, MAKEDATA and GETTEXT commands. NOTE #3: The TRIMMED type does not have a specific length. You can use it with MAKETEXT and GETTEXT commands to remove the spaces, tabs and nulls on either side of a string. It can also be used with MAKEDATA, but since this can produce a field of indeterminate length, it is rarely useful in such a role. Certain predefined data types can have a qualifier, which provides additional information. All commands that use predefined data types will accept the qualifier, but only the MAKETEXT command makes use of it. DATA TYPE QUALIFIER DESCRIPTION EXAMPLES --------- ------------------------ ------------------------------------- REAL Number of decimal places "REAL 2" -> 3.14 "REAL 4" -> 3.1415 DATE Date format "DATE ?y/?n/?d" -> "96/12/01" ----------------------------------- Interpreting Data Formats in a File ----------------------------------- When inspecting a hex dump of a binary file, bear in mind that on PC-compatible computers, the bytes that comprise a number are often reversed. For example, for the INTEGER and WORD data types, the eight most significant bits of numeric values are usually placed AFTER the eight least significant bits. Thus, the decimal value 5099 will appear as EB 13 in the file, not 13 EB, despite the fact that decimal 5099 equals hex 13EB. If you are dealing with data that treats numbers differently, you can sometimes work around the problem by reversing the order of the bytes before performing the conversion. For example, if the file contains a WORD data type, but has the most significant byte FIRST, you can switch things around, as demonstrated by this POM file: CHOP 0 <-- Read the file manually GET x "WORD" <-- Get two bytes from the file APPEND y = x[2] x[1] <-- Flip the bytes around MAKETEXT z y "WORD" <-- Convert the number OUTEND |{z} <-- Output the result 158 ============================================================================ DEDUCED VARIABLES ============================================================================ ----------------- Deduced Variables ----------------- ---------- Definition ---------- "Deduced Variable Names" (generally referred to as "Deduced Variables") provide you with powerful means for organizing and processing data. This particular approach to handling variable data is not available in most high-level languages (e.g. C, Pascal, Basic) but is extremely helpful for a content-oriented language such as Parse-O-Matic. A deduced variable is a variable for which the actual name is not known when the program is being written. The name itself is deduced when the actual POM line is run. It is almost as if you could write a line like this: SET whatever-variable-I-should-be-using-now = "3" There are several rules by which the name is deduced. By creating similar circumstances later on in the program, you can deduce the same variable name in another spot. Deduced variables are always surrounded by parentheses. Here are some sample deduced variable names: SAMPLE PARTS* DEDUCTIONS EQUIVALENT VARIABLE NAME ---------- ------ ---------- ------------------------ (X) 1 None X (X,Y) 2 None X,Y (X,Y,Z) 3 None X,Y,Z (X,@Y) 2 1 X,something (X,@Y,@Z) 3 2 X,something,something (@X,YYY,@Z) 3 2 something,YYY,something (*) A deduced variable has a maximum of three parts. As you can see: - When part of the deduced variable is NOT preceded by the "@" character, it is taken "as-is". - When part of the deduced variable **IS** preceded by the "@" character, it must be looked up. 159 ------------------- The Look-Up Process ------------------- The look-up process is simple: Parse-O-Matic looks up the variable following the "@" character and inserts it into the deduced variable name. For example: SET Y = "BBB" SET Z = "CCC" SET (AAA,@Y,@Z) = "Quick Brown Fox" SET line = (AAA,BBB,CCC) OUTEND |{line} ------------ Restrictions ------------ There are certain limitations that affect the use of deduced variables. - You can not use them in the output picture of an OUT or OUTEND command. For example, the following line will result in an error: OUTEND |We have {(PRODSTOCK,@PRODNUM} {(PRODNAMES,@PRODNUM)} in stock. The correct way to do this is as follows: SET prodstock = (PRODSTOCK,@PRODNUM) SET prodname = (PRODNAMES,@PRODNUM) OUTEND |We have {prodstock} {prodname} in stock. - The length of the deduced variable name can not exceed 12 characters. The following lines will result in an error: SET Part2 = "YYYYYYYYYY" SET Part3 = "ZZZZZZZZZZ" SET (XX,@Part2,@Part3) = "99" This causes an error because Parse-O-Matic tries to create a variable named XX,YYYYYYYYYY,ZZZZZZZZZZ -- which is 24 characters long (including the commas). The maximum length for a Parse-O-Matic variable (of any kind) is 12 characters. The following lines WOULD work: SET Part2 = "YYYY" SET Part3 = "ZZZZ" SET (XX,@Part2,@Part3) = "99" This would set the variable XX,YYYY,ZZZZ (which is 12 characters long, counting the commas) to "99". 160 - Deduced variables can not be used for variable CALL commands. The following line would not work: CALL (ROUTINE,@RTYPE) You would have to do this as follows: SET CallTemp = (ROUTINE,@RTYPE) CALL CallTemp ---------------- Usage Guidelines ---------------- If you know the precise name of the deduced variable you are setting, you can specify it directly, without the parentheses. Thus, the following two commands are the same: SET (CUST,NAME,1) = "Fred Jones" SET CUST,NAME,1 = "Fred Jones" In other words, if a deduced variable name does not include a look-up (i.e. the "@" character), it is not actually being deduced. If you use substrings with deduced variables, you must specify the indexes immediately after the closing parenthesis. Thus: (Data,@Y,@Z)[10 80] <-- This is okay (Data,@Y,@Z) [10 80] <-- This is wrong ( Data, @Y, @Z )[ 10 80 ] <-- This is okay The third example shows that you can use spaces within the parentheses and the brackets to improve readability. Variables are "persistent" (see "Uninitialized and Persistent Variables"). This can be a problem if you are creating variables (particularly arrays) while processing multiple input files: all variables created for the previous input file are still around. For this reason, you may find it necessary to create an initializing section (in the PROLOGUE) which ensures that all working variables are "set to zero", so to speak. 161 --------------- Array Variables --------------- NOTE: For background information, please see "Deduced Variables - Definition". Array variables are deduced variables that use something distinctive about each input item (e.g. a product number) to allow data for similar input items to be treated in the same way. Here is an example of array handling: ------------------------- Example: Product Numbers ------------------------- A common requirement in data processing is to assign a number to items that are different instances of the same thing. For example, let's say your input file contained a summary of the number of items sold at your store at various times of the day. You could assign a "Product Number" to each item, as in the following four-line input file: 10:33 AM 101 Oranges 15 11:04 AM 102 Lemons 4 03:15 PM 104 Bananas 20 04:41 PM 102 Lemons 25 : : : : : : : : Time Product Product Quantity Sold Code Name Sold You could add up the total sales for each item, as follows: SET ProdCode = $FLINE[11 13] SET Quantity = $FLINE[27 28] SET (Name,@ProdCode) = $FLINE[16 22] CALC (Sold,@ProdCode) = (Sold,@ProdCode) "+" Quantity The first three lines obtain the product code (e.g. 101 for Oranges), the quantity sold, and the product name. The fourth line adds the quantity sold to the appropriate product. Thus, after all four input lines have been processed, you will have created six deduced variables: VARIABLE VALUE --------------- ----- Name,101 "Oranges" Name,102 "Lemons " Name,104 "Bananas" Sold,101 "15" Sold,102 "29" <-- "29" is the total of 2nd and 4th input lines Sold,104 "20" 162 There are no variables created for product numbers that did not appear in the input file, so if (for example) you test the value of Sold,103 it will be reported as a null (empty) value. That is because it was never assigned a value. Now that you have added up the totals, you can output them in the EPILOGUE section of the POM file. (The EPILOGUE is the last section of POM code run, after all the input lines have been read.) EPILOGUE SET MaxProdCode = "104" SET ProdCode = "100" BEGIN IF (Sold,@ProdCode) <> "" THEN NumSold = (Sold,@ProdCode) ELSE "NONE" PAD (Name,@ProdCode) "R" " " "7" SET ProdName = (Name,@ProdCode) OUTEND |Product # {ProdCode} ({ProdName}): Sold {NumSold} SET ProdCode = ProdCode+ AGAIN ProdCode #<= MaxProdCode END The output from the POM file will look like this: Product # 100 ( ): Sold NONE Product # 101 (Oranges): Sold 15 Product # 102 (Lemons ): Sold 29 Product # 103 ( ): Sold NONE Product # 104 (Bananas): Sold 20 There is no data for products 100 and 103, since they did not appear in the input file, so they do not show any data in the output. ----------------------- Multidimensional Arrays ----------------------- The example given above used "two dimensional arrays", which is to say that each array has two parts (e.g. Sold,101 has the parts Sold and 101). Since deduced variables can have up to three parts, you can create arrays of up to three dimensions. 163 ------------------- Eponymous Variables ------------------- NOTE: For background information, please see "Deduced Variables - Definition". Sometimes you do not have a convenient number (such as a product number) to organize your arrays. In such cases, you can use the input item itself as the name of the variable. This technique is known as "eponymous variables". (Eponymous means "self-naming".) Let us say your store sells only two items -- dogs and cats -- and you do not have a product number for each. Your input file may look like this: 10:00 Cat 1 10:30 Dog 2 11:00 Cat 10 11:30 Cat 1 12:00 Dog 1 You can add up the items with the following POM file: SET type = $FLINE[ 8 10] SET quant = $FLINE[14 15] CALC (@type) = (@type) "+" quant After all of the input lines are read, you will have created two eponymous variables, as follows: VARIABLE VALUE --------------- ----- Cat "12" <-- Total of input lines 1, 3 and 4 Dog "3" <-- Total of input lines 2 and 5 The totals can then be output in the EPILOGUE, using the following POM code: EPILOGUE OUTEND |Cats sold: {Cat} OUTEND |Dogs sold: {Dog} END If you decide to add cows to your product line-up, you need only add a single line to your EPILOGUE: OUTEND |Cows sold: {Cow} Eponymous techniques can be more complicated than the example shown. For example, you could create sub-categories such as Dog,Beagle,Large. 164 ------------------------ Drawbacks and Advantages ------------------------ The main drawback of eponymous variables is that the POM file must "know" all the possible variable names in order to output them. If you have a small number of items (e.g. Cat, Dog, Cow) this is not a serious problem. If you DO have a large number of items, you can build an array -- "on the fly" as it were -- that adds each new eponymous variable name as it is created. You could then loop through this array, during output, to obtain the names. This may sound complex, but it is enormously powerful. It means that you can create a parsing application that can handle input files containing items whose names are unknown to you. A properly constructed POM file would handle new items without any modifications to the POM code. 165 ============================================================================ VALUE TECHNIQUES ============================================================================ This section describes useful techniques you can use when dealing with variables and literals. -------------------------------------- Uninitialized and Persistent Variables -------------------------------------- Even before a variable is assigned a value (using the SET command, for example), you can use it in a POM command. An uninitialized variable has a null value ("") and is treated normally by all commands. EXCEPTION: To help you catch coding errors, the OUT and OUTEND commands do not allow you to output an uninitialized variable. If you attempt to do so, Parse-O-Matic issues a warning, and processing is terminated. Variables are "persistent": once you have assigned a value to a variable, it retains that value until it is changed. Even if you open a new input file (see "POM and Wildcards") or a new output file (see "The OFile Command"), all variables will retain their values; they will not be "reset" back to null. (Of course, when Parse-O-Matic ends, all variables disappear; they are not retained between separate runs of POM.) ------- Example ------- Here is an example which illustrates why persistent variables are useful: PAGELEN "55" <-- Set page length SET partnum = $FLINE[ 1 10] <-- Extract the part number SET descrip = $FLINE[12 60] <-- Extract the description BEGIN lastpart <> partnum <-- Is this a new part number? OUTPAGE <-- Generate a page eject OUTHDG |PartNumber Description <-- Output a heading OUTHDG |---------- ----------- <-- Output a heading SET lastpart = partnum <-- Remember the current part number END <-- End of BEGIN block OUTEND |{partnum} {descrip} <-- Output the part number The first time a line is read from the input file, the lastpart variable will be null ("") because it has not yet been initialized. As a result, the BEGIN block will be executed. (The OUTPAGE command will be ignored in this first instance, since no data has been sent to the output file.) The BEGIN block also sets the lastpart variable, which will retain that value until it is changed. 166 When the second input line is read (and the POM code is run again from the top), the BEGIN block will be run only if the current part number is different from the previous one (which we saved in the lastpart variable). However, if the partnum variable is different, the BEGIN block will be run, outputting the page eject and headings, and once again saving the partnum in the lastpart variable, so we can check it during the third input line -- and so on. ------------------------------------ Inline Incrementing and Decrementing ------------------------------------ You can add "1" to a variable in a command. For example: SET x = "3" SET x = x+ After the second statement, x would have the value "4". Here are some additional examples: - Incrementing "1" gives you "2" - Incrementing "9" gives you "10" - Incrementing "99" gives you "100" The first time a variable is referenced, it has a null value (unless you SET it yourself). If you increment a null variable, it will be changed from "" (i.e. null) to "1". You can also subtract "1" from a variable in a command: SET x = "3" SET x = x- After the second statement, x would have the value "2". Here are some additional examples: - Decrementing "0" gives you "-1" - Decrementing "1" gives you "0" - Decrementing "99" gives you "98" When you do an inline increment or decrement, the variable itself is not changed. (C programmers take note!) For example: SET y = "3" SET x = y- After the second line, the x variable will equal "2", while the y variable will still equal "3". 167 You can use inline incrementing or decrementing with substrings: SET y = "X23X" SET x = y[2 3]+ After the second line, the x variable will equal "24", while the y variable will still equal "X23X". Only integer numeric values can be incremented or decremented. If you attempt to increment or decrement another type of variable (e.g. text or a decimal number), Parse-O-Matic will halt, and report an error. ------------- Line Counters ------------- If your input record is divided over several lines (due to its original format or perhaps because you used the SPLIT or CHOP command), it is helpful to set up a line counter. The following example extracts the first six characters of the second line of input records that span three lines (designated lines 0, 1 & 2): IF LineCntr = "1" THEN MyField = $FLINE[1 6] OUTEND LineCntr = "1" |{MyField} IF LineCntr = "2" THEN LineCntr = "" ELSE LineCntr+ For an alternative to line counters, see "The ReadNext Command". ------------------- The SHOWNUM Utility ------------------- The ShowNum program (SHOWNUM.EXE in the standard Parse-O-Matic package) is a small utility which converts a hex number to decimal and vice-versa. It can also convert a character to its ASCII equivalent value in decimal or hex. ShowNum is helpful when you are working on a task that forces you to deal with data in hex or decimal form. It is a handy tool if you are working with binary input or output files. You can probably find fancier conversion-reference utilities than SHOWNUM, but this one comes ready-to-go with Parse-O-Matic -- and it is free. You may give unaltered copies of SHOWNUM to anybody without paying royalties. ---------------------- Quick Reference Screen ---------------------- To display a quick-reference help screen, enter the following command at the DOS prompt: SHOWNUM /? 168 If you are calling SHOWNUM from Windows, you can add the /P (Pause) option to make it wait for a keypress before terminating: SHOWNUM /? /P ------------------- Converting a Number ------------------- To find out what the decimal number 123 is in hexadecimal, enter the following command at the DOS prompt: SHOWNUM #123 The # character tells ShowNum that the number is in decimal. The program will display: #123 = $7B To find out what hex 400F is in decimal, enter the following command at the DOS prompt: SHOWNUM $400F The $ character tells ShowNum that the number is in hexadecimal. The program will display: $400F = #16399 ShowNum can handle numbers between -2,147,483,648 (hex $80000000) and 2,147,483,647 (hex $7FFFFFFF). ---------------------- Converting a Character ---------------------- To find out a character's ASCII equivalent value in decimal and hex, use the SHOWNUM utility this way: SHOWNUM A This will display: A = #65 $41 In other words, the letter "A" is ASCII decimal 65, which is hex 41. 169 You can enclose the character in quotes if you wish. This is strictly necessary only if you are trying to remember the values for "space": SHOWNUM " " This will display: " " = #32 $20 Character conversion works only one character at a time: SHOWNUM "ABCD" <-- This is incorrect This would display: "ABCD" = #65 $41 As you can see, only the first character ("A") is being converted. ---------------------- Windows Considerations ---------------------- If you call SHOWNUM.EXE from Windows, your answer will vanish when the program ends and the window closes. For this reason, the file SHOWNUM.BAT has been included in the standard Parse-O-Matic package. You can use this exactly like SHOWNUM.EXE, but it pauses after the answer is displayed. For additional details, see "Installing the SHOWNUM Utility" in the "Running Under Windows" section of this manual. 170 ============================================================================ PROGRAMMING TECHNIQUES ============================================================================ This section describes techniques that will help you create and debug POM files. ------- Tracing ------- By setting the DOS variable POM to ALL, you can generate a trace file, named POM.TRC. This is helpful if you have trouble understanding why your file isn't being parsed properly. But be sure to test it with a SMALL input file; the trace is quite detailed, and it can easily generate a huge output file. To save space, you can specify a particular list of variables to be traced, rather than tracing everything. For example, to trace only the variable PRICE, enter this DOS command: SET POM=PRICE To trace several variables, separate the variable names by slashes, as in this example: SET POM=PRICE/BONUS/NAME This traces the three variables PRICE, BONUS and NAME. ------- Logging ------- Every time Parse-O-Matic runs, it creates a "processing log". This is a text file named POMLOG.TXT, which is placed in Parse-O-Matic's home directory. (For example, if POM.EXE is located in C:\POM, the file will be C:\POM\POMLOG.TXT even if you run POM from another directory.) If the file POMLOG.TXT already exists, it is renamed to POMLOG.BAK. The processing log file POMLOG.TXT contains a report of what happened during the last run of Parse-O-Matic. Usually, the file will be quite short and look something like this: COMMAND: POM TEST.POM TEST.TXT TEMP.TXT DATE: AUG 01 1997 17:50:10 TEST.TXT opened for processing 17:50:14 TEST.TXT processing completed The first line gives the DOS command line, while the second gives the date. Subsequent lines give the time (Hours:Minutes:Seconds) and a progress or error message. 171 If you encounter an error during processing, the text of the warning message is saved in the processing log. It might look something like this: COMMAND: POM TEST.POM TEST.TXT TEMP.TXT DATE: AUG 01 1997 17:50:10 TEST.TXT opened for processing 17:50:10 Execution error in line number 3 of POM file TEST.POM 17:50:11 Required parameter is missing in OUT If you process multiple input files, POMLOG.TXT might look something like this: COMMAND: POM EXAMPL15.POM DATA*.TXT TEMP.TXT DATE: AUG 01 1997 14:21:27 DATA01.TXT opened for processing 14:21:28 DATA01.TXT processing completed 14:21:28 DATA02.TXT opened for processing 14:21:28 DATA02.TXT processing completed 14:21:28 DATA03.TXT opened for processing 14:21:28 DATA03.TXT processing completed 14:21:28 3 files processed If for some reason the processing log can not be created, Parse-O-Matic will continue to run; it will not terminate. For some additional comments on logging, see "Unattended Operation". 172 ============================================================================ COMMAND-LINE TECHNIQUES ============================================================================ This section describe the various options available at the command line. ---------- Quiet Mode ---------- Sometimes you don't want the user to see the Parse-O-Matic processing screen. In such cases, you can use the "Quiet Mode" switch (/Q) on the command line. For example: POM XYZ.POM MYFILE.TXT TEMP.TXT /Q The /Q switch suppresses the display of the processing screen. The only time a user will see anything is if there is a problem (for example: the input file was not found). In such case, Parse-O-Matic will make a noise via the PC speaker, then display a message (see "Unattended Operation" and "The MSGWAIT Command" for some background information). -------------------------------------- User-Specified Command-Line Parameters -------------------------------------- Some POM applications are easier to use if you can pass a value on the command line. For example, let us say you have created a POM file that will search a text file for a particular word, and output all the lines that contain that word. You could manually change the POM file each time, but this is not a practical solution if many people will be using the application. The alternative is to use user-defined command line parameters to pass the value. Consider this POM file, which we will name FINDWORD.POM: ACCEPT $FLINE ^ $CMDLINEX OUTEND |{$FLINE} This will output any lines that contain (^) the value of $CMDLINEX. This variable is set if you use the /X command line parameter. Thus, you would call the POM file as follows: POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /Xadministration This would read the file INPUT.TXT and send any lines containing the word "administration" (in lowercase) to the file OUTPUT.TXT. 173 There are three user-specified command line parameters: PARAMETER SETS VARIABLE --------- ------------- /X $CMDLINEX /Y $CMDLINEY /Z $CMDLINEZ Like all variables, the $CMDLINEx variables can be in uppercase, lowercase or mixed case (e.g. $CmdLineX). ------------------- Case Considerations ------------------- The parameter letter (e.g. /X) can be in uppercase or lowercase. The following two command lines are equivalent: POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /Xadministration POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /xadministration The value following the parameter letter is passed on "as-is"; it is not converted to uppercase or changed in any way. You could modify the FINDWORD file (described earlier) to ignore case, as follows: CVTCASE $CMDLINEX $CMDLINEX <-- Convert the /X value to uppercase ACCEPT $FLUPC ^ $CMDLINEX <-- Compare to the uppercase version of $FLINE OUTEND |{$FLINE} <-- Output the line if the value was found ---------------- Spaces in Values ---------------- Since command-line parameters are separated by spaces, you must enclose your parameter value in quotes if it contains one or more spaces. For example: POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /X"Mr. Jones" If the parameter value contains quotes, they must be doubled-up. Thus, if you were using the FINDWORD application to find The "King" of American Jazz the command would look like this: POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /X"The ""King"" of American Jazz" 174 --------------------- Command-Line Switches --------------------- Sometimes you want a command-line parameter to simply mean "do something". If it is missing from the command line, it would mean "don't do it". You could specify /ZY (for "Yes, do it") and /ZN (for "No, don't do it"), but there is an easier way. If a command-line parameter is missing, Parse-O-Matic sets its corresponding $CMDLINEx variable to "N" (meaning, "No, it's not there"). If the parameter is present -- with no value following it -- Parse-O-Matic sets the $CMDLINEx variable to "Y" (meaning "Yes, it's there"). We can use this method to refine the FINDWORD application described earlier... BEGIN $CMDLINEZ = "Y" CVTCASE $CMDLINEX $CMDLINEX ACCEPT $FLUPC ^ $CMDLINEX ELSE ACCEPT $FLINE ^ $CMDLINEX END OUTEND |{$FLINE} In this case, the /X value (the word we are looking for) will be tested without regard to case (i.e. uppercase or lowercase letters) if /Z is present on the command line. If /Z is missing, we will look for an exact match. Here are two sample command lines: POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /X"Mr. Jones" POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /X"Mr. Jones" /Z The first command would not match "Mr. Jones" with "mr. jones". The second command would consider the two strings equivalent. ---------------------------- Hex and Decimal Code Strings ---------------------------- You can specify precise values either as a decimal ("ASCII") value, or as hexadecimal. For example, the following three commands are equivalent: POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /X" 01" POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /X$20$30$31 POM FINDWORD.POM INPUT.TXT OUTPUT.TXT /X#32#45#49 All three specify the search string " 01". The second one uses decimal notation for the characters, while the third one uses hexadecimal codes for the characters. 175 You can not mix the decimal, hex and literal representations. Here are two examples: /X#32"22"#32 is not permitted /X" 22 " could be used instead /X#32#50#50#32 could also be used /X$30#50 is not permitted /X02 could be used instead /X"02" could also be used ------- Summary ------- SAMPLE COMMAND LINE VALUE OF $CMDLINEX ---------------------------------- ------------------ POM A.POM B.TXT C.TXT /XHarry Harry POM A.POM B.TXT C.TXT /X"The King" The King POM A.POM B.TXT C.TXT /X Y POM A.POM B.TXT C.TXT /XY Y POM A.POM B.TXT C.TXT /XN N POM A.POM B.TXT C.TXT N POM A.POM B.TXT C.TXT /X$30$31 01 POM A.POM B.TXT C.TXT /X#48#50 02 176 ============================================================================ FILE HANDLING ============================================================================ ------------------------------------- How Parse-O-Matic Searches for a File ------------------------------------- When Parse-O-Matic needs to read a file, it follows this procedure: 1) Parse-O-Matic tidies up the file name in the following ways: - It removes spaces and tabs - It converts the file name to uppercase - As per DOS convention, slashes (/) are converted to backslashes (\) - If this type of file has a default extension, and if the file name does not have a period (i.e. dot) in the name, the extension is added. 2) If the file name is fully qualified (i.e. drive and path, or both), Parse-O-Matic tries to open that file. If it can not, it terminates with an error message. 3) If the file name is not fully qualified, Parse-O-Matic follows this procedure: - It first looks for the file in the current directory. - If then looks in the directory where the Parse-O-Matic program (POM.EXE) is located. - It then searches the DOS PATH for the file. (For information about the PATH command, refer to your operating system manual.) - If none of these steps locate the file, Parse-O-Matic terminates with an error message. The following types of files are affected... TYPE OF FILE DEFAULT EXTENSION REFER TO MANUAL SECTION ---------------------- ----------------- ----------------------- POM (Control) File .POM "The POM File" POJ (Job) File .POJ "Parse-O-Matic Job (POJ) Files" Date Information File See NOTE #1 "The POMDATE.CFG File" Lookup File See NOTE #2 "The LookFile Command" Properization Exception See NOTE #2 "The Proper Command" Map File .MPF "The MAPFILE Command" NOTE #1: The Date Information File is always called POMDATE.CFG. You can put your standard version in the Parse-O-Matic directory. If you wish to override it, you should place the modified copy in your current (logged) directory. NOTE #2: This type of file does not have a default extension. However, we recommend "TBL" (i.e. "Table") for Lookup files and "PEF" for Properization Exception Files. 177 Parse-O-Matic does NOT search for input and output files. They must be in the current directory, or must have a fully qualified path. If the input file is missing an extension, it is assumed to be TXT. If the output file is not specified in the POM command, it is assumed to be Output File") Since Parse-O-Matic searches for files, you can place frequently-used Lookup and POM files in a directory in your DOS path. -------------------------------------- How Parse-O-Matic Opens an Output File -------------------------------------- Parse-O-Matic opens an output file the first time one of the output commands (e.g. OUT, OUTEND, OUTHDG) has something to send to the file. When opening an output file, Parse-O-Matic follows this procedure: 1) Normally, the name of the output file is specified on the POM command line or (if it is omitted there), it is specified in an OFILE command within the POM file. If no output file name was given using either method, the name is set to POMOUT.TXT (in the current directory). 2) Parse-O-Matic tidies up the file name in the following ways: - It removes spaces and tabs - It converts the file name to uppercase - As per DOS convention, slashes (/) are converted to backslashes (\) - If the file name does not have an extension, and it does not end in a period or a colon, the extension TXT is added. Thus: C:\XYZ becomes C:\XYZ.TXT C:\XYZ. stays the same C:\XYZ.DAT stays the same LPT2: stays the same (see "Sending Output to a Device") 3) The output file name is compared to the input file name. If they are the same, Parse-O-Matic terminates with an error. You can not send output to the input file, nor can you read input from the output file. 4A) If the file name is preceded by a plus sign ("+"), Parse-O-Matic will append output to the file. Here are some examples: +C:\XYZ.TXT output will be appended to the file +LPT1: this refers to a device, so the "+" is ignored If the file to which you are appending does not already exist, it is first created, as an empty file. 178 4B) If the file name is NOT preceded by a plus sign, the following procedure takes place: - If a file with the specified name already exists, it is renamed with a .BAK extension (replacing any previous file with that name). - The file is created, as an empty file For example, if you run Parse-O-Matic as follows: POM MYPOM.POM INPUT.TXT C:\XYZ.TXT then if C:\XYZ.TXT already exists, it is renamed to C:\XYZ.BAK. 5) Output is directed to the output file until Parse-O-Matic ends or a new output file name is specified by the OFILE command. REMINDER: Parse-O-Matic does not open the output file until it is time to send it some data from the output commands (OUT, OUTEND etc.). If no data is sent to the output file, it will contain its original data (assuming it already existed). If this is a problem, you can either delete the output file before running Parse-O-Matic, or place the following commands in the PROLOGUE: ERASE "OUTPUT.TXT" <-- Delete the output file OFILE "OUTPUT.TXT" <-- Specify the output file If you do this, and no data is sent to the output file, the file will not exist. You can check if POM failed by consulting the DOS ERRORLEVEL. (See your operating system manual for an explanation of ERRORLEVEL.) - If the ERRORLEVEL is 0 and the file does not exist, it means that POM ran successfully, but no output was sent to the file. - If the ERRORLEVEL is 1 or higher, and the file does not exist, it means that POM failed, or you used the HALT command before any output was sent to the file. If you are calling Parse-O-Matic from a program (rather than a batch file), you can check the error level using the facilities built in to the language in which the program was written. For example, Turbo Pascal lets you run another program with the EXEC command, after which you can extract the ERRORLEVEL from the low byte of the DosExitCode variable. 179 --------------------------- Appending to an Output File --------------------------- If you want to add data to the end of the output file, you have three alternatives: 1) Use wildcards, as explained in "POM and Wildcards". In such case, the output file is empty when the first output line is generated (although see method #2 for an exception). When processing with wildcards, all output is sent to the same file, unless you change the file with the OFILE command (see "The OFile Command"). 2) Prefix the output file name with a plus sign. This tells Parse-O- Matic that you want to add data to the end of the file, rather than starting with an empty file. You can use this method on the command line: POM MYPOM.POM INPUT.TXT +C:\MYFILES\OUTPUT.TXT You can also use this method in the OFILE command: OFILE "+C:\MYFILES\OUTPUT.TXT" In these examples, we provided the full path name to the output file. If you do not specify a path name (e.g. OFILE "+OUTPUT.TXT"), the output file is placed in the current directory. 3) Use a batch file and the DOS COPY command to control the concatenation of output files. This method is less convenient, but it allows you to bypass the addition of the new output if there is a processing error. Here is a sample batch file (comments appear after the arrows): @ECHO OFF <-- Turn batch echoing off IF EXIST OUTPUT.TXT DELETE OUTPUT.TXT <-- Get rid of old output file POM MYPOM.POM INPUT.TXT OUTPUT.TXT <-- Parse the input file IF ERRORLEVEL 1 GOTO QUIT <-- Quit if there was an error IF NOT EXIST OUTPUT.TXT GOTO QUIT <-- Quit if no output generated IF EXIST SAFETY.TXT DELETE SAFETY.TXT <-- Get rid of old safety file RENAME MAINFILE.TXT SAFETY.TXT <-- Backup the original file COPY SAVE.TXT+OUTPUT.TXT MAINFILE.TXT <-- Add the new output :QUIT <-- Batch file label for GOTO This method has the added advantage of creating a backup copy of the original output file. If the data in the file is particularly important, you could place the file SAFETY.TXT on another hard drive. 180 -------------------------- Sending Output to a Device -------------------------- Parse-O-Matic recognizes that an "output file" is actually a device if it has a colon (":") at the end of the name. You can direct Parse-O-Matic's output to a standard device such as COM1: or LPT2: by specifying the device name accordingly. For example: POM XYZ.POM INPUT.TXT LPT1: This directs the output to the LPT1 printer. Parse-O-Matic can detect a "Not Ready" condition in most cases. A printer is Not Ready when it is offline, out of paper, or its print buffer is full. If a Not Ready condition occurs, the following happens: - If you are running in Quiet Mode (/Q on the POM command line), a Not Ready condition terminates Parse-O-Matic with a DOS ERRORLEVEL of 243. - If you are not running in Quiet Mode, a message box gives you the option of trying again, or canceling processing. If you cancel, Parse-O-Matic terminates with a DOS ERRORLEVEL of 244. --------- COM Ports --------- If you are sending output to a COM port (e.g. COM1:) you should first set the baud rate with the DOS MODE command, or Pinnacle Software's MODEM program (available on our BBS and Web site). The MODEM program is particularly useful if your COM port is driving a modem. Parse-O-Matic talks to the operating system's COM device driver rather than the modem itself, so before you send data to a modem, it is a good idea to use the MODEM program to check that the modem is online and functioning properly. If you are using a high-speed modem (9600 bps or higher) and you find that you sometimes lose some characters, the operating system or the modem may not be handling a "Not Ready" condition properly during handshaking. In such case, you may find it necessary to turn off buffering (locked DTE speed) and run at a maximum speed of 9600 bps. For a quick course in high-speed modems and buffering, see the Trouble-Shooting Guide included with Pinnacle Software's Sapphire Bulletin Board System (also available on our BBS and Web site). For an example of sending output to a COM port, see "The Pause Command". 181 --------- DbF Files --------- If Parse-O-Matic notices that the input file is a "DBase" file (i.e. it has a DBF extension -- for example: MYFILE.DBF), it will change the way it processes the data. For instance, the variable $FLINE is not defined. Rather, each of the fields in the database are pre-parsed. Thus, if you have a DBF file containing three fields (EMPNUM, NAME, PHONE), your entire POM file might look like this: IGNORE DELETED "Y" OUTEND |{EMPNUM} {NAME} {PHONE} The DELETED variable is created automatically for each record. If it is set to "Y", it means the record has been deleted from the database and is probably not valid. In most cases, you will want to ignore such records. If you do not know what the field names are, you can obtain the list with the following POM file: TRACE DELETED Afterwards, when you inspect the trace file (POM.TRC), you will see a summary of all the fields. Since there are no output commands (e.g. OUTEND and OUTHDG), the output file will be empty. NOTE: Parse-O-Matic does not currently support DBF "Memo" fields. ----------------- POM and Wildcards ----------------- You can process multiple input files with the same POM file by specifying a DOS "wildcard" at the DOS command prompt. All output is then directed to the same output file. For example: POM XYZ.POM *.TXT OUTPUT.TXT This runs the XYZ POM file on each file in the current directory with a TXT extension and sends all output to the file OUTPUT.TXT. The POM file can determine which file it is reading by using the predefined variable $COMMAND, which contains the current POM command line. 182 Consider the following scenario: - You have installed POM.EXE in the directory path C:\UTILITY\POM - The current directory contains ABC.POM, MARK.TXT, MARY.TXT and JOHN.TXT - You enter the command POM ABC *.DAT OUT.TXT Parse-O-Matic runs ABC.POM against the three TXT files. On the first input file, $COMMAND will look like this: C:\UTILITY\POM.EXE ABC.POM MARK.TXT OUT.TXT On the next two input files, it looks like this: C:\UTILITY\POM.EXE ABC.POM MARY.TXT OUT.TXT C:\UTILITY\POM.EXE ABC.POM JOHN.TXT OUT.TXT Note that the file OUT.TXT is NOT processed, even though it has a TXT extension. POM will always avoid processing the output file. Let's say you wanted to concatenate both MARK.TXT and MARY.TXT, and put the file name at the top. You could do it with this POM file, named ABC.POM: SET cmd = $COMMAND <-- Get the command line BEGIN cmd <> lastcmd <-- Has it changed? PARSE fname cmd "2* " "3* " <-- Extract the input file name SETLEN flen fname <-- Get length of input file name SET uline = "" <-- Initialize underline PAD uline "L" "-" flen <-- Set underline OUTEND lastcmd <> "" | <-- Output a linefeed unless OUTEND lastcmd <> "" | <-- this is the first file OUTEND |{fname} <-- Output the file name OUTEND |{uline} <-- Output the underline OUTEND | <-- Output a linefeed SET lastcmd = $COMMAND <-- Remember this command line END <-- End of code block OUTEND |{$FLINE} <-- Output a line from the input You could then process MARK.TXT and MARY.TXT with this command line: POM ABC M*.TXT OUT.TXT This processes any file starting with an "M" that has a TXT extension. Another way to run the command is as follows: POM ABC M???.TXT OUT.TXT This processes any four-letter TXT file that starts with "M". For details about DOS wildcards, consult your operating system manual. 183 ============================================================================ OPERATIONAL TECHNIQUES ============================================================================ ----------------------------- Parse-O-Matic Job (POJ) Files ----------------------------- As explained earlier, a standard Parse-O-Matic command line looks like this: Format: POM pom-file input-file output-file [optional parameters] Example: POM POMFILE.POM REPORT.TXT OUTPUT.TXT You can save the command specifications in a Parse-O-Matic job (.POJ) file so that you do not have to type them over and over again. A POJ file is essentially a single-line text file that contains the specifications. ------------ Simple Usage ------------ Let's say you create a text file named MYJOB.POJ which contains the following line: POMFILE.POM REPORT.TXT OUTPUT.TXT You can then run the parsing job with the following command: POM MYJOB.POJ This would be the same as typing: POM POMFILE.POM REPORT.TXT OUTPUT.TXT NOTE: Do NOT include the POM command in the job file. For example: XYZ.POM ABC.TXT DEF.TXT <-- Correct POM XYZ.POM ABC.TXT DEF.TXT <-- Incorrect; the initial POM is not needed 184 --------------------- Commenting a Job File --------------------- The POJ file can contain explanatory comments so you can document its purpose: null lines and lines that start with a semi-colon are ignored. Thus, the MYJOB.POJ example (described above) could also have been written this way: ; Sample JOB file POMFILE.POM REPORT.TXT OUTPUT.TXT This first line is ignored, so as far as Parse-O-Matic is concerned, the job file contains only one line -- the command specifications. (The sample PBJ files are indented here to offset them from the descriptive text, but a semi-colon must appear in column one to be recognized as a comment.) ------------------------ Prompting for File Names ------------------------ Job files are especially helpful when you don't know in advance which files will be processed, and you would like to prompt for a file name. This lets you use one POM command-line to handle different situations. Let's say you create a text file named MYJOB2.POJ, which contains the following lines: ; Sample prompted job file POMFILE.POM % OUTPUT.TXT You can then run this job with the following DOS command: POM MYJOB2.POJ or simply: POM MYJOB2 Since a single command-line parameter is assumed to refer to a POJ file. The % character means "Ask the user for this file". Since, in this example, the % is in the second position, Parse-O-Matic will prompt you for the name of the input file or mask. (If you press Esc or enter a null name, processing is terminated with a warning message.) 185 Here is another example: ; Sample prompted job file POMFILE.POM % % This will prompt for both the input file and output file names. Now consider this example: ; Sample prompted job file % % % This will prompt for the POM, input and output file names -- which is not particularly helpful! --------------------- Suggesting File Names --------------------- A % prompt will open a box on the screen to ask you for a file name (with an appropriate explanation of what it required) but it will not suggest a name. You can "feed" Parse-O-Matic a suggested name, which you can then accept by hitting Enter, or modify by typing a new one. To provide this default value, place the suggested file name after the % character. For example: ; Sample prompted job file, with recommended file names POMFILE.POM %INPUT.TXT %OUTPUT.TXT When you are asked to specify the input file name, the name INPUT.TXT will appear in the prompt box. It can be accepted as-is, or changed. Incidentally, if you do not provide a suggested file name for the output file, Parse-O-Matic will automatically suggest the name POMOUT.TXT. ------------------- Optional Parameters ------------------- You can include optional parameters in your job file line. For example: POMFILE.POM ABC.TXT XYZ.TXT /Q Because of the /Q parameter, this will parse ABC.TXT in "Quiet mode" (i.e. the processing screen will not be displayed). You can not prompt for optional parameters. 186 Because the output file name is optional in the POM command (defaulting to POMOUT.TXT if it is omitted, which can then be altered in the POM file itself with the OFILE command), it is possible to leave out the output file name (or prompt) in the job file: POMFILE.POM ABC.TXT /Q This assumes that the output file name is POMOUT.TXT, just as if you had typed the following command at the DOS prompt: POM POMFILE.POM ABC.TXT /Q -------- Examples -------- The standard Parse-O-Matic package contains two sample job files, named SAMPJOB1.POJ and SAMPJOB2.POJ, which demonstrate simple and prompted usage of job files. Both files are self-documenting, so view or print them out to find out how to use them. ------------------------------- Encrypted (Scrambled) POM Files ------------------------------- Parse-O-Matic comes with a simple encryption program (named SCRAMBLE) which renders a POM file unreadable to humans yet still usable by Parse-O-Matic. -------------------- The SCRAMBLE Utility -------------------- The format of the SCRAMBLE command (entered at the DOS prompt) is as follows: SCRAMBLE filename password The filename is the name of your POM file, which will be "scrambled" into a seemingly meaningless jumble of characters. The original POM file is renamed with a BAK extension, so if you scramble MYFILE.POM, as in this command: SCRAMBLE MYFILE.POM PRIVATE then two files will be created: MYFILE.POM The scrambled POM file MYFILE.BAK The original POM file 187 The password is a code word of six letters or more that you can use to unscramble the file. To do this, simply enter the SCRAMBLE command again, using the same password. SCRAMBLE ignores case, so the password "SECRET" is equivalent to "Secret". If the wrong password is entered, SCRAMBLE issues a warning message, pauses briefly, then terminates without doing anything else. For a brief summary of SCRAMBLE, enter the following command at the DOS prompt: SCRAMBLE /? ------------------------ Why Scramble a POM File? ------------------------ If you are distributing a POM application, you may not want the end-users to be able to tamper with the POM file. If they alter a scrambled POM file, they will almost certainly render it inoperable. The encryption scheme used by SCRAMBLE (and Parse-O-Matic) is not highly sophisticated, so there are no export restrictions on the technology. The encryption could probably be "cracked" by a professional cryptologist within a day. However, it should confound regular users sufficiently that they will not alter, excerpt or modify your POM code. When Parse-O-Matic notices that the POM file is encrypted, it disables tracing. This prevents the user from using the trace facility to get a listing of the POM file. ---------------------- Support Considerations ---------------------- The SCRAMBLE program does NOT have to be present in the Parse-O-Matic directory for Parse-O-Matic to read scrambled files. If you are shipping a scrambled POM file to a user, you might consider sending along a copy of SCRAMBLE if you think the user might have to make some on-site changes to the POM file. However, in order to do this, the user would have to know your POM file's scrambling password. In most cases it is probably better to provide the user with a fresh file (direct from you) when changes are needed. Scrambled POM files can be used with unregistered evaluation copies of Parse-O-Matic, although the legal requirement remains: continued use of Parse-O-Matic beyond 90 days requires a license (see "Licensing"). This lets your client try out your Parse-O-Matic solution without paying for Parse-O-Matic OR seeing your POM code. 188 ----------- Batch Files ----------- The built-in batch (BAT) capability of DOS and Windows is often overlooked, even by seasoned computer professionals. You can use batch files to make Parse-O-Matic easier to use. Batch files are created with a text editor (such as DOS EDIT, or Windows Notepad). -------------------------------------- Example #1: Save Yourself Some Typing -------------------------------------- Here is a simple batch file (comments appear after the arrows): @ECHO OFF <-- Turn off command-line echoing POM MYPOM.POM INPUT.TXT OUTPUT.TXT <-- Run Parse-O-Matic IF ERRORLEVEL 1 GOTO QUIT <-- Quit if an error occurred SEE OUTPUT.TXT <-- View the output file :QUIT <-- Batch file label The advantage of this batch file is that it saves you the trouble of typing in the entire POM command line each time you want to parse the file. ---------------------------------------- Example #2: Streamline Your Development ---------------------------------------- Here is a batch file which is useful during the development of a POM file. @ECHO OFF DEVELOP 50 MYPOM.POM IN.TXT C:\MYFILES\OUT.TXT This batch file calls DEVELOP.BAT (included with Parse-O-Matic), which displays a menu with the following options: INPUT ------ View input file EDIT ------- Edit POM file PARSE ------ Run parsing job OUTPUT ----- View output file QUIT ------- Finished This lets you do the parsing, view the result, make changes to the POM file if necessary, then parse again. You will find that this technique makes development proceed quickly. Here is an explanation of the second line of the batch file: 189 DEVELOP 50 MYPOM.POM IN.TXT C:\MYFILES\OUT.TXT : : : : : : : : : : : : : : Name of output file <----- : : : : | : : : Name of input file <-------- See NOTE #1 : : : | : : Name of POM file <----- : : : Save position for menu <-------- See NOTE #2 : Invokes the batch file DEVELOP.BAT NOTE #1: You must provide the full path to the files (unless they are in the current directory) and the extension. NOTE #2: The "save position" remembers where you were in the menu. You may use values 49 to 99 to provide a "memory" for 50 different batch files that call DEVELOP.BAT. (The other values are reserved for the Parse-O-Matic installation and tutorial procedures.) If 50 is not enough, you can place additional batch files in another directory; the menu save file (POM.MSV) is always placed in the current directory. In order for DEVELOP.BAT to work correctly when you are in a directory other than the Parse-O-Matic directory, you must place the Parse-O-Matic directory in your DOS PATH (see your operating system manual for details). Your PATH must also include the directory to a text editor. (In the original Parse-O-Matic package, DEVELOP.BAT calls up DOS EDIT.) You may find it instructive to study the file DEVELOP.BAT by loading it into a text editor. The batch file contains some comments which explain how it works. As mentioned in one of the comments, you may wish to change the text editor that the batch file calls for editing the POM file. You may also find the program PSMENU.EXE useful. For a brief description, type PSMENU /? at the DOS prompt. To study a typical menu definition file, enter the command SEE POM.MNU at the DOS prompt. ---------------------------------- Example #3: Automatic Batch Files ---------------------------------- Let's say that each day you have a text file, named DELLIST.TXT, which lists the names of the files that need to be deleted: FRED.TXT MARY.TXT JOHN.TXT HARRY.TXT You could write a POM file (we'll call it MAKEDEL.POM) to write a batch file to delete the files. It would look like this: 190 PROLOGUE OUTEND |@ECHO OFF END IGNORE $FLINE = "COMMAND.COM" <-- An example of a safety feature! OUTEND $FLINE <> "" |DEL {$FLINE} You could automate the entire procedure with the following batch file (which we'll call DAILYDEL.BAT): @ECHO OFF <-- Turn off command-line echoing POM MAKEDEL.POM DELLIST.TXT TEMP.BAT <-- Create the batch file TEMP.BAT IF ERRORLEVEL 1 GOTO QUIT <-- Quit if an error occurred TEMP.BAT <-- Run the batch file DEL TEMP.BAT <-- Delete it :QUIT <-- Batch file label The second line of DAILYDEL.BAT runs Parse-O-Matic to create a batch file named TEMP.BAT. Given the input file shown earlier, TEMP.BAT would look like this: @ECHO OFF DEL FRED.TXT DEL MARY.TXT DEL JOHN.TXT DEL HARRY.TXT After TEMP.BAT is created, DAILYDEL.BAT runs TEMP.BAT (thus deleting all the files listed in DELLIST.TXT). This is only a simple example. Parse-O-Matic's ability to create batch files based on input data provides you with a very powerful tool for automating daily administrative tasks. When you write automatic applications, you should be careful to include routines in both the batch files and the POM files to handle any unusual conditions. In MAKEDEL.POM, we checked the file to be sure that it wasn't "COMMAND.COM", because if that file is deleted, your system will probably stop working! 191 --------------------------------------------------------- Example #4: Controlling a POM File from the Command Line --------------------------------------------------------- Consider the following batch file, which we will call SELECT.BAT: @ECHO OFF <-- Turn off command-line echoing IF (%1) == () GOTO ERROR <-- Make sure we have a parameter SET XYZ=;1 <-- Set the environment variable XYZ POM SELECT.POM INPUT.TXT OUT.TXT <-- Run the POM file SELECT.POM GOTO QUIT <-- Jump to the QUIT label :ERROR <-+ ECHO Missing parameter | Error-handling routine PAUSE <-+ :QUIT <-- Batch file label SET XYZ= <-- Get rid of the environment variable SELECT.BAT can be used with this POM file, which will we name SELECT.POM: PROLOGUE GETENV xyz "XYZ" END OUTEND $FLINE ^ xyz |{$FLINE} You can use SELECT.BAT to output only those lines that contain the variable that you specify. For example, you can enter the following command at the DOS prompt: SELECT MARY This will output only those lines (from INPUT.TXT) that contain "MARY". If you wish to ignore distinctions between uppercase and lowercase, change the last line of SELECT.POM accordingly: OUTEND $FLUPC ^ xyz |{$FLINE} Batch file parameters are separated by spaces on the command line, so the following command would not work as you might expect: SELECT MARY FRED JOHN This would set the batch variable %1 to MARY, ;2 to FRED and ;3 to JOHN. One way to deal with this is to eliminate the spaces when you run the batch file: SELECT MARY/FRED/JOHN 192 You can then replace the OUTEND command in SELECT.POM with these lines: APPEND x xyz "/" <-- Set the x variable to "MARY/FRED/JOHN/" BEGIN x <> "" <-- We will loop through all of the names PEEL y x "" "/" <-- Move a name to the y variable OUTEND $FLUPC ^ y |{$FLINE} <-- Output a line if it contains the name AGAIN <-- Go back to the BEGIN Bear in mind that the system environment space is limited. If you have problems with an application like this one, refer to "The GETENV Command", in the section entitled "Disappearing Environment Variables". -------------------- Unattended Operation -------------------- You can design applications that run themselves while you are not there. There are two reasons why you might want to do this: - You can run long processing jobs just before leaving work at night - Parse-O-Matic is useful, but it isn't very interesting to watch! Several features of Parse-O-Matic facilitate "unattended operation". - The SOUND command can alert you if something unusual happens; you don't have to stare at the screen to make sure that everything is working. - All error messages (which say "Press a key to continue") make a noise via the PC speaker (see "The Sound Command"). - You can use the MSGWAIT command to let processing continue if there is an error (see "The MSGWAIT Command"). - The processing log (see "Logging") can be used to check processing. Let's say you wanted to concatenate (add together) several enormous text files. You could start with the following POM file (named ADD.POM): SET cmd = $COMMAND BEGIN cmd <> lastcmd SOUND "BEEP" SET lastcmd = cmd END OUTEND |{$FLINE} You could then enter the command POM ADD.POM *.TXT ALL.TXT and walk away. Whenever a new file is started, you will hear a beep. When you come back, you can check the file POMLOG.TXT (which will be located in the same directory as POM.EXE). It might look something like this: 193 COMMAND: POM ADD.POM *.TXT ALL.TXT DATE: AUG 01 1997 16:39:12 JOHN.TXT opened for processing 16:45:28 JOHN.TXT processing completed 16:45:29 MARY.TXT opened for processing 16:52:10 MARY.TXT processing completed 16:52:11 FRED.TXT opened for processing 17:03:33 FRED.TXT processing completed If you are processing multiple files, and each one uses a different POM file (and hence requires a separate run of Parse-O-Matic) you can write your batch file so that it renames the log files. This lets you review each log file later. For example: @ECHO OFF POM JOHN.POM JOHN.TXT JOHN.LST RENAME C:\POM\POMLOG.TXT JOHN.LOG POM MARY.POM MARY.TXT MARY.LST RENAME C:\POM\POMLOG.TXT MARY.LOG POM FRED.POM FRED.TXT FRED.LST RENAME C:\POM\POMLOG.TXT FRED.LOG When processing is complete, the files JOHN.LOG, MARY.LOG and FRED.LOG will be available in the directory C:\POM for your inspection. Here is a slightly more sophisticated version of the batch file: @ECHO OFF POM JOHN.POM JOHN.TXT JOHN.LST IF ERRORLEVEL 1 GOTO QUIT RENAME C:\POM\POMLOG.TXT JOHN.LOG POM MARY.POM MARY.TXT MARY.LST IF ERRORLEVEL 1 GOTO QUIT RENAME C:\POM\POMLOG.TXT MARY.LOG POM FRED.POM FRED.TXT FRED.LST IF ERRORLEVEL 1 GOTO QUIT RENAME C:\POM\POMLOG.TXT FRED.LOG :QUIT The IF ERRORLEVEL lines jump to the end of the batch file if Parse-O-Matic generates an error of 1 or higher. When coding batch files, remember that the IF ERRORLEVEL command is considered "True" if the error is the specified value or higher. This means you should always test the higher value first. See your operating system manual for details. 194 -------- Examples -------- Many of the techniques described in this manual are demonstrated by the examples provided with the standard Parse-O-Matic package. To see these examples, switch to your Parse-O-Matic directory, type INFO at the DOS prompt, or run INFO.BAT from Windows or OS/2, then select TUTORIAL. 195 ============================================================================ OPERATIONAL CONSIDERATIONS ============================================================================ ----------------------------------------------- Running Parse-O-Matic on 8088 and 8086 Machines ----------------------------------------------- Parse-O-Matic is designed to run on 80286 machines and higher, in "protected mode". If you have a pressing need to run it on an old 8088 or 8086-class "real mode" machine (e.g. PC or XT), we may be able to prepare a custom copy for you. Contact us for details. ------------------------------------------ Running Parse-O-Matic from Another Program ------------------------------------------ If you are calling Parse-O-Matic from a program written in a high-level language (such as Pascal, Delphi, C or Basic), you can check its success or failure by consulting the "DOS Error Level". Most languages have built-in facilities to test this value. For example, Turbo Pascal lets you run another program with the EXEC command, after which you can extract the ERRORLEVEL from the low byte of the DosExitCode variable. You can also check the DOSERROR return code to check for invocation errors. Some typical errors include: Program not found, Path not found, Access denied, Not enough memory. On long parsing jobs (taking 3 seconds or more on your slowest machine), it is perhaps best to let the user see the processing screen rather than running in Quiet Mode (see "Quiet Mode"). If nothing else, it gives him or her something to look at, and provides assurance that the machine has not stopped working. ----------------------- Solving Memory Problems ----------------------- Parse-O-Matic does all of its work in standard memory; it does not use Extended or Expanded memory. This is rarely a problem, but if you do somehow run out of memory, there are some steps you can take... You can often free up some extra memory by unloading unused device drivers and DOS TSR ("Terminate and Stay Resident") programs. (TSR's are sometimes called "DOS Pop-Ups") Alternatively, most drivers and TSR's can be safely moved into high memory, using the LOADHIGH function in your AUTOEXEC.BAT, or the DEVICEHIGH function in CONFIG.SYS. Some older drivers and TSR's will not tolerate this kind of relocation. 196 ============================================================================ RUNNING UNDER WINDOWS ============================================================================ ------------- Compatibility ------------- Parse-O-Matic is a DOS program, which has a few advantages and a few minor disadvantages for Windows users. The primary advantage is that a Parse-O-Matic application can run on any PC-compatible machine, whether it is running DOS, Windows, or OS/2. Emulators are also available which will let you run Parse-O-Matic (and other DOS software) on Macintosh, Unix, Linux and other computers. Since Parse-O-Matic has no user interface to speak of, Windows' wonderful graphical environment is not particularly important. The only operational difference is that to interrupt Parse-O-Matic processing, you press the Esc key instead of clicking on a Cancel button. Performance is a consideration if you are running Parse-O-Matic at the same time as 32-bit applications under Windows; it will slow them down slightly. However, unless you are multi-tasking heavily, performance is not an issue because the usual bottleneck is the responsiveness and transfer speed of the hard disk, not the speed at which the Parse-O-Matic program runs. ------------------------- Setting Up for Windows 95 ------------------------- To use Parse-O-Matic under Windows, you need the following items, which are included in the standard Parse-O-Matic package: 1) The POM file (icon file POM_FILE.ICO) 2) A batch file (icon file BAT.ICO) These two icon files are included in the standard Parse-O-Matic package. You may find it helpful to copy them to your main Windows directory so that the associations you set for them are not lost if you install a new version of Parse-O-Matic and then delete the original POM directory. ------------------------------------------ Setting Up an Association for the POM File ------------------------------------------ When you click on a POM file, it should call up a text editor. To configure this, follow these steps: 1) Double-click on "My Computer" 2) From the pull-down menu, select View/Options 197 3) Dialog Box: Options Click on the File Types tab Click on the New Type button 4) Dialog Box: Add New File Type Description: Parse-O-Matic Control File Associated extension: POM Click on the New button 5) Dialog Box: New Action Action: &Edit Application used: NOTEPAD.EXE (or the path to your favorite editor) Click on the OK button 6) Dialog Box: Add New File Type Click on the Change Icon button Click on the Browse button File name: The full path to POM_FILE.ICO (e.g. C:\POM\POM_FILE.ICO) Press Enter 7) Dialog Box: Change Icon Click the OK button 8) Dialog Box: Add New File Type Click the Close button 9) Dialog Box: Options Click the Close button Once you have followed these steps, you can double-click on the POM file icon when you are in Windows Explorer or a file folder, and it will be opened with the file editor you specified in step 5. ---------------------------------------------- Setting Up an Association for a POJ (Job) File ---------------------------------------------- When you click on a POJ file, it should call up Parse-O-Matic. To configure this, follow these steps: 1) Double-click on "My Computer" 2) From the pull-down menu, select View/Options 3) Dialog Box: Options Click on the File Types tab Click on the New Type button 4) Dialog Box: Add New File Type Description: Parse-O-Matic Control File Associated extension: POJ Click on the New button 198 5) Dialog Box: New Action Action: &Open Application used: The path to POM.EXE (e.g. C:\POM\POM.EXE) Click on the OK button 6) Dialog Box: Add New File Type Click on the Change Icon button Click on the Browse button File name: The path to POJ_FILE.ICO (e.g. C:\POM\POJ_FILE.ICO) Press Enter 7) Dialog Box: Change Icon Click the OK button 8) Dialog Box: Add New File Type Click the Close button 9) Dialog Box: Options Click the Close button Once you have followed these steps, you can double-click on the POJ file icon when you are in Windows Explorer or a file folder, and it will start up Parse-O-Matic and run to specified job (POJ) file. ----------------------------------------------------- Setting Up an Association for the BAT File (Optional) ----------------------------------------------------- Windows 95 is already set up to process batch (BAT) files. However, Parse-O-Matic comes with an alternative icon which is more distinctive than the one supplied with Windows. (The Parse-O-Matic icon looks like a bat -- a sonar-equipped flying critter with an undeserved bad reputation). To change the icon, follow these steps: 1) Double-click on "My Computer" 2) From the pull-down menu, select View/Options 3) Dialog Box: Options On the list box, find and double-click on MS-DOS Batch File 4) Dialog Box: Edit File Type Click on the Change Icon button 5) Dialog Box: Change Icon Click the Browse button File name: The full path to BAT.ICO (e.g. C:\POM\BAT.ICO) Press Enter 6) Dialog Box: Change Icon Click the OK button 199 7) Dialog Box: Edit File Type Click the Close button 8) Dialog Box: Options Click the Close button After following this procedure, your batch (BAT) file icons will be much more noticeable when they appear in Windows Explorer or a file folder. To edit the batch file, right-click on the icon and select Edit. To run the batch file, simply double-click the icon. For a discussion of batch files, see "Batch Files". ----------------------------------- Setting Up for Windows 98, Me, 2000 ----------------------------------- Under Windows, when you click on file types that are not recognized (which will initially be the case for .POM and .POJ files), Windows offers to assign them to a particular program. You need to associate .POM files with your favorite text editor, and .POJ files with POM.EXE. When you double-click an unrecognized file type, Windows will ask you what program you want to use to open that file. You should start by typing in a description for the file type (e.g. "POM Job File" for .POJ files and "POM Script File" for .POM files). You then point to the appropriate program. In the case of .POJ files, you will click on the "Other..." button to point to the program POM.EXE. ---------------------------------- Additional Associations (Optional) ---------------------------------- After associating .POJ files with POM.EXE and .POM files with your favorite text editor, you can provide additional, right-clickable options (such as opening a .POJ file with a text editor). Under WinMe, you do this as follows: - Double-click "My Computer" (located on your desktop) - Select "Tools", then "Folder Options" - Click on the "File Types" tab - Click on the file type you want to enhance (POM or POJ) - Click on "Advanced" 200 ------------------------------ Installing the ShowNum Utility ------------------------------ The ShowNum program is a small utility which converts a hex number to decimal and vice-versa, or displays the ASCII value of a character (see "The ShowNum Utility"). To install ShowNum as a Windows shortcut: 1) Select "File/New/Shortcut" from the pull-down menu of any folder. 2) Specify the path name to SHOWNUM.BAT, followed by a question mark. For example: C:\POM\SHOWNUM.BAT ? The ? means "Prompt for input before calling the batch file". 3) After you have finished defining the shortcut, right-click on the icon, select "Properties", then the "Program" tab, and make sure the "Close on exit" box is checked off. You can then use ShowNum by double-clicking its icon. You will be prompted to enter a number, and the answer will be displayed. -------------------------- Long File Names in Windows -------------------------- Although Parse-O-Matic runs under Windows, it will only recognize standard "8.3" DOS file names; it does not use the long file names supported by Windows. You can determine the underlying DOS name of a file by checking its "Properties" in Windows Explorer, or by using the DIR command while in DOS mode. ------------------- The WINUTIL Utility ------------------- The WinUtil program (WINUTIL.EXE in the standard Parse-O-Matic package) is a small utility which provides some Windows functions if you are running in a DOS window. WinUtil can detect if Windows is running, and lets you copy a file to the Windows clipboard, or create a file from the contents of the clipboard. 201 ----------- Limitations ----------- WinUtil does not work with Windows 3.1 or earlier. It has been tested under Windows 95, 98 and Me. WinUtil requires the use of 8.3 style file names. That is to say, it can not handle the long file names that were introduced by Windows 95. WinUtil can handle clipboard data up to 65535 bytes. Attempts to process a larger amount of data will cause an error. ---------------------- Quick Reference Screen ---------------------- To display a quick-reference help screen, enter the following command at the DOS prompt: WINUTIL /? ----------------- Sample Batch File ----------------- You will usually use WinUtil in a batch file. For example: @ECHO OFF <-- Turn off echo WINUTIL CHECK <-- See if Windows is running IF ERRORLEVEL 1 GOTO OKWIN <-- Skip ahead if Windows is running ECHO Windows is not running! <-- Display warning GOTO QUIT <-- Skip ahead to end of batch file :OKWIN <-- Batch file label WINUTIL CLIP WRITE work.txt <-- Copy the clipboard to a text file POM editwork.pom in.txt out.txt <-- Modify the text file with POM IF ERRORLEVEL 1 GOTO OOPS <-- Stop if there's an error WINUTIL CLIP READ out.txt <-- Copy the text file to the clipboard DEL in.txt <-- Erase work file DEL out.txt <-- Erase work file GOTO QUIT <-- Skip ahead to end of batch file :OOPS <-- Batch file label ECHO Parsing job failed <-- Display warning PAUSE <-- Wait for a key to be pressed :QUIT <-- Batch file label 202 ------------------------------- Detecting if Windows is Running ------------------------------- To check if Windows is running, use the following command format on the DOS command line, or in a batch file: FORMAT: WINUTIL CHECK [V] EXAMPLE: WINUTIL CHECK The V parameter is optional. If it is included, WinUtil will operate in "verbose" mode. That is to say, it will display one of the following messages: Windows is running Windows is NOT running If the V parameter is omitted, WinUtil does not display a message. If Windows is running, WinUtil sets the DOS return code to 1. If Windows is not running, WinUtil sets the DOS return code to 0. You can test the return code using the IF ERRORLEVEL batch file function. (See "Sample Batch File", above, for an example.) ------------------------------------ Copying the Clipboard to a Text File ------------------------------------ To copy the Windows clipboard to a text file, use the following command format on the DOS command line, or in a batch file: FORMAT: WINUTIL CLIP WRITE filename EXAMPLE: WINUTIL CLIP WRITE clip.txt The DOS return code is set as follows: 0 The operation was successfully carried out 1 The clipboard did not contain any text 255 A processing error occurred If the file you are writing to already exists, it is renamed with a .BAK extension. 203 ------------------------------------ Copying a Text File to the Clipboard ------------------------------------ To copy a text file to the Windows clipboard, use the following command format on the DOS command line, or in a batch file: FORMAT: WINUTIL CLIP READ filename EXAMPLE: WINUTIL CLIP READ clip.txt The DOS return code is set as follows: 0 The operation was successfully carried out 1 The text file did not contain any text 255 A processing error occurred --------------- The SEE Utility --------------- Parse-O-Matic comes with a file view/print/extract utility known as SEE (SEE.EXE). The copy included in the standard package is for single-user operation with an evaluation or registered copy of Parse-O-Matic. It may not be distributed (even if you have purchased a Distribution License for Parse-O-Matic). You may purchase a registered copy of SEE (including the full manual and walk-through). Multi-copy and Distribution Licenses are available. For more information: please phone us at +1-416-287-8892. 204