 |
|
The Output File Node identifies a text file from which you want to extract values to be assigned to output or buffer variables.
Configuring an Output File node requires two parameters:
Name: the name of the output file. At run-time the system will look for a file with this exact name located within the working directory for the application that has generated it. (Note: this introduces a limitation, as output files for different applications must have different names. If you have two applications, each creating an output file with the same name, one application after running must rename the file).
Description: the node description will appear as tooltip when the mouse stop over the node in the Work Flow canvas.
The next step is then to specify how the output or buffer variables should be extracted from the output file (i.e., what the mining rules are). To do this you need to first select the variables that you desire to extract from the output file (in the Possible output nodes section of the configuration panel). Then you must click on the button to open the template output editor. When you do this, a file chooser dialog will pop-up, allowing you to select a text file to be used as a template for defining the mining rules.
You are strongly encouraged to use as a template an output file actually generated by the application. When you select the file you can also specify the encoding to be used to open the file. By default, this is the same as the one you specified in the node properties dialog, but you might decide to change it at this time. Once you select the desired file, and the proper encoding, the output file will appear in a text editor (the Template Output Editor).The encoding (or more precisely the character set) used for the text file. The selection of available encodings is machine-dependent. The encoding selected here must match the encoding used by the application to generate the file. Typically this is ASCII, but some application might use different encodings (e.g., to support accented letters, or Japanese characters).
The Output File node input connector must be connected to one, and only one, data output connector. This can be the output data connector of one, and only one, Script node. When you connect the node, you must also indicate for which values of the node exit value you want the file to be processed (see Section 4.2.7, "Conditional Expression Legal Syntax"). Only when the node exit value matches the condition the variables are extracted from the output file.
The Output File node output can be connected to one or more Output Variable or Buffer Variable nodes. The mining rules for extracting the values for these variables from the file must be specified using the template output editor.
Three error messages can be associated with an output file node:
| 108 | MISSING MINING RULE(S) IN OUTPUT FILE | One or more of the variables to be extracted has not been associated with a mining rule |
| 112 | MISSING OUTPUT LINK(S) | The output file is not connected to any output/buffer variable |
| 113 | MISSING INPUT LINK(S) | The output file input is not connected to any node |
The Template Output Editor allows you to graphically describe how you want the variables to be extracted from an output file generated by an external application.
The Template Output Editor dialog is divided into two main panels. The top panel contains a text editor with the current template for the output file; the bottom panel contains a list of the output and buffer variables that are connected to the output file node, and that thus need to be extracted from the file (each variable must appear once, and only once, in the file).
There are three different type of mining rules that can be used to extract variables: Absolute, Relative and Block Relative. We will now describe in detail how you can define these different rules.
An absolute mining rule should be used whenever you know the absolute (i.e., relative to the beginning of the output file) position of the value you want to assign to a variable. More precisely, you must know the row and column number on which the value will appear. The number of columns in a row is determined by the number of "tokens" in each row, where with tokens we intend sequence of characters delimited by one or more spaces, equal signs, tab characters, less than or greater than signs, parenthesis, brackets, square brackets, tilde, pound, percentage sign, slash, back slash, and puntuation marks. Thus, each row can have a different number of columns.
Assigning an absolute mining rule to a variable is a three-step process. You first need to select in the bottom panel the variable that you want to associate with the mining rule. Then you must select in the top panel the area of text containing the value that you want to assign to the variable. Finally, you have to click the right mouse button, and from the contextual menu that will appear you'll need to select Absolute Position. The area of text containing the value for the variable is now highlighted in red. Also, in the bottom panel the mining rule will now appear, indicating row and column numbers for the token that will need to be extracted from the file.
A relative mining rule should be used whenever you do not know the absolute position of the value, but you know where the value appears relative to the n-th occurence in the output file of a given string. More precisely, you must know the number of rows and columns from the reference string where the value will appear. While the variable must be purely numeric, the reference string can be any string, as long as it all fits in a single row (i.e., it can contain white space and other characters that are not part of a token as defined above).
Assigning a relative mining rule to a variable is slightly more complex. Like before, you first need to select in the bottom panel the variable that you want to associate with the mining rule. Then you must select in the top panel the area of text containing the reference string relative to which you know the position of the variable. To assign the reference string you now have to click the right mouse button, and from the contextual menu that will appear you'll need to select Relative Position. The area of text containing the reference string is now highlighted in green. Also, in the bottom panel the mining rule for the variable will now appear, indicating the reference string and its occurence within the output file. Note that the rule is now in red, as it does not represent a legal mining rule yet.
You now need now to tell the system where the variable is relative to the reference string. To do so, you must select in the top panel the area of text containing the value that you want to assign to the variable. Then, you have to click the right mouse button, and from the contextual menu that will appear you'll need to select Select Relative. The area of text containing the value for the variable is now highlighted in red. Also, in the bottom panel the mining rule is now completed, indicating row and column numbers for the variable, relative to the reference string. Note that the rule is now in black, as it is now legal.
You can think of a block relative mining rule as a relative mining rule for which the reference string is located not starting from the beginning of the file, but from the m-th occurence of another string (the block string). In other words, the block string allows you to identify the start of a block of text within the file, and you then define a relative mining rule starting from that point in the file. The block string, just like the reference string, can be any string, as long as it all fits in a single row (i.e., it can contain white space and other characters that are not part of a token as defined above).
Assigning a block relative mining rule to a variable requires one additional step. Like before, you first need to select in the bottom panel the variable that you want to associate with the mining rule. Then you must select in the top panel the area of text containing the block string relative to which you know the occurence of the reference string. To assign the block string you now have to click the right mouse button, and from the contextual menu that will appear you'll need to select Block Position. The area of text containing the reference string is now highlighted in blue. Also, in the bottom panel the mining rule for the variable will now appear, indicating the block string and its occurence within the output file. Note that the rule is now in red, as it does not represent a legal mining rule yet.
You now need to select the relative string. Like before, you must select in the top panel the area of text containing the reference string relative to which you know the position of the variable. To assign the reference string you now have to click the right mouse button, and from the contextual menu that will appear you'll need to select Select Tag. The area of text containing the reference string is now highlighted in green. Also, in the bottom panel the mining rule will now indicate the reference string and its occurence from the block string down. The mining rule is still displayed in red, as it does not represent a legal mining rule yet.
You need now to tell the system where the variable is relative to the reference string. To do so, you must select in the top panel the area of text containing the value that you want to assign to the variable. Then, you have to click the right mouse button, and from the contextual menu that will appear you'll need to select Select Relative. The area of text containing the value for the variable is now highlighted in red. Also, in the bottom panel the mining rule is now completed, indicating row and column numbers for the variable, relative to the reference string. Note that the rule is now in black, as it is now legal.
The menu and the toolbar at the top of the dialog can be used to perform some additional operations on the template. More precisely, the menu allows you to carry out the following operations:
-> (Ctrl-O): Loads a file from the file system into the template editor.
-> (Ctrl-S): Saves the current content of the template editor into an external file. Note: this will be an ordinary text file; no mininig rules will be saved into it.
The menu instead enables you to carry out the following operations:
-> (Ctrl-F): Locates a string within the template.
-> (F3): Repeats the search for the last string used in a find command.
-> (Ctrl-G): Jumps to a specific line number within the template.
Some of these operations can also be invoked using the buttons in the toolbar.
In the toolbar there is also an encoding selector, which allows you to change the encoding to be used to save the template. This can become useful if you introduce in the template characters that are not supported by the original encoding (e.g., accented letters or Far East characters). Of course, you must be sure that the involved application will be able to use such encoding.
In addition, you can specify the convention to be used to terminate each line in the template. Here you can select either the DOS format, or the UNIX format. In the former case, each line is terminated by a CR - LF pair (carriage return - line feed); if the UNIX format is select, only a LF is indicate a line termination. Specifying the correct line termination is especially important for DOS operation, because UNIX-terminated text files could be interpreted incorrectly.
The contextual menu (displayed when the right button on the mouse is pressed on the top panel, allows you to carry out another operation, in addition to the mining rule description discussed above. Also, if you select a variable from the list at the bottom, and a mining rule has been associated with that variable (regarless of whether is valid or not), you can remove the mining rule by selecting Remove Variable on the contextual menu.
