 |
||||||||
| Values,Literals and Variables | ||||||||
| A value is a parameter for a scripting command.It can be specified in the following ways: —————— ———————————————————————————————————————————— Example Explanation —————— ———————————————————————————————————————————— 'Text' A text string (note the quotes) 15 A number '15' Another way to represent a number (i.e.as text) VarName The name of a variable VarName [10 20 ] Substring of a variable (columns 10 to 20 in this case) VarName [19 ] Substring of a variable (a single character) VarName+A numeric variable,plus 1 (e.g.MyVar =MyVar+) VarName-A numeric variable,minus 1 (e.g.MyVar =MyVar-) VarName(10) An array variable —————— ———————————————————————————————————————————— A “literal ” is a parameter in a script command that does not get changed when the script is running..The first three examples in the table above are literals.Literals are enclosed in 'quotes'— unless they are numbers,in which case the quotes are optional. A “variable ” is a named spot in your computer''s memory that holds some data.Variables must start with an unaccented letter (A to Z).Case is ignored,so variables named MyVar,myvar and MYVAR are considered the same. Substring ranges in square brackets such as MyVar [ 1 10 ] must refer to fixed range of column positions.If the script needs to vary the substring range,you should use the Cols command. |
||||||||
| Array Variables | ||||||||
| Array variables are recognized as such because the variable name is immediately followed by the “open parenthesis ” character.. You can use any kind of number as the index value (integer or real).In fact,you can use any kind of text as the index.For example,you could create an array variable named MyArray('Cat').You can use this feature to create multidimensional arrays (e.g.the index could be '0,3,XYZ'). Uninitialized array elements are assigned the value contained in the special variable $NotDefined.By default this contains the value '[ND ]',but you can assign a different value to $NotDefined if you wish. |
||||||||
| Special Variables | ||||||||
| Parse-O-Matic applications make available certain internal variables.You can recognize these as “special ” variables because — unlike user--defined variables — these start with a dollar--sign ($)character. Because these variables are used by Parse-O-Matic itself,you should avoid altering them.Your script can either make a copy of a special variable (e.g.MyData =$OutData),or use commands such as Cols to extract the part you want (e.g.MyData =Cols $OutData 10 20). Depending on the Parse-O-Matic application,some special variables may not be available,or may not behave precisely as explained here.These departures from the standard will typically be described in the application's user manual. |
||||||||
| Frequently-Used | ||||||||
| Here are the special variables that are used most often. ———————————— ———————————————————————————————————————————— Special Variable Explanation ———————————— ———————————————————————————————————————————— $OutData Data that the application is sending to the script $Data The line of input data (see explanation below) $PrevData The previous line of input data read by the application $ReadLines The number of lines (or records)read from the input file ———————————— ———————————————————————————————————————————— If you are using the Parse-O-Matic Power Tool application,the $OutData and $Data variables refer to the same thing.In all other Parse-O-Matic applications (such as TextHarvest ),the input data (i.e.$Data)is preprocessed by the application itself before being passed to the script as $OutData.(The variable name $OutData literally means “preprocessed data sent as output to the script ”).In such cases,your script should use $OutData rather than $Data,as it may not contain the actual input data from the file. The $OutData variable can usually be altered without causing problems for the underlying application.If this is not the case,the documentation accompanying the application should state this explicitly. |
||||||||
| Input/Output | ||||||||
| Here are the special variables related to input and output: ———————————— ———————————————————————————————————————————— Special Variable Explanation ———————————— ———————————————————————————————————————————— $ActualIFN Name of the current input file (including path) $ActualOFN Name of the current output file (including path) $AppendingOutput Set to 'Y'if output is being added to pre-existing file $BytesOutCount Number of bytes sent,so far,to the output file $ClipboardOutput Set to 'Y'if output will go to the Windows clipboard $InputFileBytes Number of bytes (including buffered)read from input $OutCSVRec The accumulator string used by the OutCSV command $Wildcarding Y =Multiple input files;N =Processing only one file ———————————— ———————————————————————————————————————————— |
||||||||
| User Interface | ||||||||
| ———————————— ———————————————————————————————————————————— Special Variable Explanation ———————————— ———————————————————————————————————————————— $CaptionX Caption for the first option box (usually 'Option &X') $CaptionY Caption for the second option box (usually 'Option &Y') $CaptionZ Caption for the third option box (usually 'Option &Z') $IFNMask What actually appears in the Input File box $OptionX First options box - These variables contain the values $OptionY Second options box - in the input boxes near the bottom $OptionZ Third options box - of the Parsing Parameters window ———————————— ———————————————————————————————————————————— |
||||||||
| Miscellaneous | ||||||||
| Here are various special variables that do not fit into the previously mentioned categories: ———————————— ———————————————————————————————————————————— Special Variable Explanation ———————————— ———————————————————————————————————————————— $AppParms(n) Array of parameters (see application's documentation) $Compare Dynamic comparator (e.g.If X $Compare Y Done) $EndOfData See “Manual Read Commands ” $Ignore See explanation below $NotDefined Contains the value for uninitialized array variables $Scrambled 'Y'=script has been scrambled (user cannot view source) $StepName Processing step (see application's documentation) $Success See explanation below $TestMode Set to 'Y'if the application is running in Test Mode ———————————— ———————————————————————————————————————————— |
||||||||
| The $Ignore Variable | ||||||||
| The $Ignore special variable is used when a function returns a value but you are not interested in what that value is.For example: $Ignore =Parse MyData '2*/''3*/''Cut' This removes everything between the second and third slashes in the variable named MyData.Using $Ignore helps make a script self-documenting.That is to say,if you place a result in $Ignore,it serves as a reminder that you are not using the information elsewhere in the script. You may sometimes get an error message that looks something like this: Warning:The following variables are referenced only once in ScrMyScript MyVariable While this error message is usually caused by a mistyped variable name,it can also happen if you use a “throw-away ” variable to get rid of a value — and only use it that one time..To avoid getting this message, use the $Ignore variable. |
||||||||
| The $Success Variable | ||||||||
| Certain commands (such as Overlay and SetFromFile)set a special variable named $Success.This is set to 'Y'(meaning,“Yes,it succeeded ”)if the command succeeded and 'N'(for “No ”)if it failed. Consider this script sample: MyVar =SetFromFile 'MyText.txt' If $Success ='N'MyVar ='No data' If the SetFromFile command fails — which would happen if the file was not found — then $$Success is set to 'N'.If it succeeds,though,$Success is set to 'Y'. When a script first runs,$Success is initially set to 'N'.Once a command sets the value of $Success,it retains its value until set by another command.Because of this,you should test $Success immediately after the command that sets it.Consider this situation: MyVar =SetFromFile 'MyText.txt' Overlay MyVar 'CUSTOMER''Customer' If $Success ='N'then MyVar ='No data' The programmer has apparently forgotten that Overlay also sets $Success.A better approach would be as follows: MyVar =SetFromFile 'MyText.txt' If $Success ='N'MyVar ='No data' If $Success ='Y'Overlay MyVar 'CUSTOMER''Customer' This example performs the tests and operations in a more logical order. |
||||||||
| Special Syntax | ||||||||
| Continuation of Long Lines | ||||||||
| If a script line is too long for convenient viewing in your text editor,you can continue it on the next line by using the >>symbol.For example: CustomerInfo =CustSalutation FirstCustName MiddleCustName >> LastCustName '('CustomerPhoneNumber ')' You can put comments (i.e.a semicolon followed by some text)after the continuation symbol,though if you put the continuation symbol after the start of a comment,the following line of script is considered to be part of the comment. In the example above,the continuation line was indented by two spaces.This is not mandatory,but it does serve as a reminder that the line is a continuation. |
||||||||
| Embedding Quotes in Text Literals | ||||||||
| Since text literals begin and end with 'quotes',you cannot simply put a quote inside a text literal.To represent a quote within a text literal,put two quotes in a row.For example: MyVar ='Isn''t ''scripting''fun?' This will set MyVar to: Isn't 'scripting'fun? Note that each instance of a doubled-up quote has been replaced by a single instance. |
||||||||
| Untypeable Characters | ||||||||
| You can specify either hexadecimal or decimal representation of bytes when coding a literal: MyVar =$0A$0D MyVar =#10#13 The first example uses hexadecimal notation to define the Carriage Return and Linefeed characters.The second example uses decimal notation to do the same thing. You can also mix text and untypeable characters,as in these examples: MyVar ='Hello'$0A$0D MyVar ='Hello'$0A $0D MyVar ='Hello'#010#01 Any of the examples above will set the variable MyVar to 'Hello'followed by the Carriage Return and Linefeed characters. |
||||||||
| Free and Advanced Scripting | ||||||||
| Script-enabled Parse-O-Matic applications let you use the majority of the basic scripting features at no extra charge.Some of the more powerful capabilities,however,require the Parse-O-Matic Advanced Edition from Pyroto,Inc.The price is US $199 for a single license.Quantity discounts are available. If you use an Advanced Scripting command and do not have the License,the program will display a pop-up window.You can skip over this window,so you can make sure that the Advancing Scripting command is appropriate for your requirements.You may try out the Advanced Scripting commands at no charge for up to 30 days. You can visit http://www.parseomatic.com/parse/ParseOMaticAdvanced.aspx to learnmore about obtaining the Parse-O-Matic Advanced Edition,or simply wait until you are prompted about the License by the program. |
||||||||
| Sample Scripts | ||||||||
| Script-enabled Parse-O-Matic applications are often delivered with sample scripts (which typically have the word Sample in their names).If you are using a program other than the Parse-O-Matic Power Tool ,please refer to your application's documentation to find out which sample scripts are included. Here is a list of the sample scripts included with the Parse-O-Matic Power Tool application: |
||||||||
|
||||||||
| Adv =Uses Advanced Scripting commands It is best to study these scripts in the order they are listed above.To view a script,click on the button with the folder icon next to the Script File input box.You can then select a script and view it by clicking the View button . To try out the sample script ScriptSample01.txt : • Set Script File to ScriptSample01.txt • Set Input File to ThingsToDo.txt You can simply clear the input box and press Tab;ThingsToDo.txt is the script's default input file. • Set Output File to an appropriate file name such as Output.txt You can simply clear the input box and press Tab;Output.txt is the script's default output file. • Make sure Autoview is checked and Append is not checked • Click the Start button Once the output file is displayed,you may find it helpful to view the input file,so you can understand how the output data was transformed. All of the sample scripts have default input and output file names defined,so you can try each one using the technique described above.That is to say,specify the Script File first,then fill in the Input File and Output File names by clearing the input box and pressing Tab. In addition to the sample scripts included with most script-enabled Parse-O-Matic applications,you can find additional sample scripts in the Pyroto,Inc.Knowledge Base,available at www.Parse-O-Matic.com. |
||||||||
| About Older Parse-O-Matic Applications | ||||||||
| Parse-O-Matic was originally created in 1985.We have learned a lot about parsing since that time,and the design of Parse-O-Matic Scripting reflects this. As our long-time customers have probably noticed by now,Parse-O-Matic Scripts are similar to the POM files used by our old DOS-based program,but the POM files are not compatible.For example,the old $FLINE variable is now represented by $Data.This does not mean that the old DOS-based program is no longer useful.Certain kinds of operations (such as those performed on binary files)are currently impractical with Scripting,and some arcane capabilities (such as bit-wise operations and date arithmetic)are not implemented. (This page is part of the online user manual for Parse-O-Matic. Parse-O-Matic is a programmable parsing tool that can extract, manipulate, convert or mine existing data sources and turn them into importable data. For more information on Parse-O-Matic products and conversion services, please visit www.ParseOMatic.com) |
||||||||