PREP_PROCESS_FILE

Script Function: Uses filter criteria to retrieve the content of a text file which is available on a particular computer line by line. It provides the result for further processing in the form of an internal list (data sequence).

Syntax

PREP_PROCESS_FILE (Host, File,[ Filter] [, "COL=Definition1[, Definition2]"][, UC_LOGIN=Login object])

Syntax	Description/Format
Host	The computer (name of an agent) on which the file is located. Format: script literal or script variable
File	The name of the text file that should be read. Format: script literal or script variable The name of a file which is part of a data group can be retrieved using the script function GET_FILESYSTEM.
Filter	The definition of a filter condition for the content of a line. Case insensitive. Format: script literal or script variable Default value: "*"
Definition1	Determines whether the lines of the data sequence should be divided in columns. Format: script literal or script variable Allowed values: "NONE" (default), "FILE", "LENGTH", "DELIMITER" "NONE" = No columns "FILE" = The columns are defined in the file "LENGTH" = Specified size of the column. Requires LENGTH_TAB= for Definition2 "DELIMITER" = Columns separated by a delimiter. Requires DELIMITER= as Definition2
Definition2	Fixes column sizes and names (optional) or the delimiter. Format: script literal or script variable Allowed values: "LENGTH_TAB" and "DELIMITER" "LENGTH_TAB" Column sizes and names (optional) are specified in the form Column size=[Column name]. The column size is defined through a number of characters. The individual columns are separated by commas (maximum 22 columns). Quotations must be set before the first and after the last column definition. If double quotations are used for Definition2 as script literal, single quotations must be used for specification or vice versa. Example: "COL=LENGTH,LENGTH_TAB='3=drive,100=file name'" "DELIMITER" The delimiter is specified in the form Delimiter. "" = freely defined delimiter. Delimiter = String of not more than 10 characters which separates the columns. If single quotations are used as Delimiters, the whole phrase COL=Definition1[,Definition2] must be enclosed in double quotations and vice versa. Default value: Semi colon (;) Example: "COL=DELIMITER,DELIMITER='*" 'COL=DELIMITER,DELIMITER=@"@' Tabulators can also be defined as separators: 'DELIMITER=<TAB>'
UC_LOGIN	The name of a Login object. Format: script literal or script variable

Return code
Reference to a data sequence of the file

Comments

The script function PREP_PROCESS_FILE provides the contents of a text file - for example a LOG or trace file - for further processing with AE scripts.

This script function reads the entire line of a data sequence. It can, however, also be accessed when the line is subdivided into columns. The following restrictions apply:

maximal 22 columns with a total size of 2048 bytes,
column size maximal 255 characters and
column name maximum 32 characters.

The columns can also be defined in the file itself (first line).

Example:

COL=LENGTH,LENGTH_TAB='74=PATH,25=NAME,5=VALUE,2=STATUS,9=DATE,7=TIME'

GET_PROCESS_LINE may be used to access particular columns.

With the optional parameter UC_LOGIN, the name of a Login object may be assigned to the script function. Access to the file to be read and its transfer from the host to the Automation Engine is made with the login data defined in the Login object. Users require the privilege "File transfer: Start without User ID" if the script function PREP_PROCESS_FILE should be used without the UC_LOGIN parameter.

The return code of the script function is the reference to this data sequence. It is given to the script statements :PROCESS and :ENDPROCESS as start parameters. In combination with the script function GET_PROCESS_LINE, each individual line of the data sequence and its columns can now be processed.

No error occurs if the data sequence does not contain the required content. The processing of the data sequence that is defined between :PROCESS and :ENDPROCESS does simply not take place.

No new value can be assigned to the script variable containing the data sequence reference. The data sequence must be discarded with the script statement CLOSE_PROCESS first and then the variable can be re-used.

Only the OS agent supports PREP_PROCESS_FILE. It cannot be used in combination with agents for Databases, Oracle Applications, PeopleSoft, SAP, JMX or Rapid Automation.

Keep in mind that the processing of huge files affects the agent's performance.

The script statement causes all open transactions of the script to be written to the AE database.

Examples

The first example prints all lines of the file "\\FServer\UC4\BSP\INPUT.TXT" that contain the string "Start" to the activation protocol.

:SET &HND#=PREP_PROCESS_FILE(WIN21,"\\FServer\UC4\BSP\INPUT.TXT","*Start*")
:PROCESS &HND#
: SET &LINE#=GET_PROCESS_LINE(&HND#)
: PRINT &LINE#
:ENDPROCESS

The second example reads all lines of a file whereas the parameter "COL=FILE" specifies that column names and widths are defined in the file itself. The Login object provided is used to log on.

:SET &HND = PREP_PROCESS_FILE(WIN21, "\\FServer\LOG.TXT", ,"COL=FILE",'UC_LOGIN=UC4FT')

Example three is similar to the above one, however, the parameter "COL=LENGTH" denotes that column definitions are specified with the subsequent parameter. Column definitions can be a column width that is assigned to a column name or a width only. Columns without a name are ignored.

:SET &HND = PREP_PROCESS_FILE(WIN21, "\\FServer\UC4\DIALOG\TEMP\UCDJ_LOGG_01.TXT","*DB-INFO*","COL=LENGTH,LENGTH_TAB='8=DATE,1,6=TIME,7,200=TEXT'")

In the next example, the parameter "COL=DELIMITER" says that a separator is specified with the next parameter – the tabulator. The script prints the third column only.

:SET &HND# = PREP_PROCESS_FILE(UNIX01, "/uc4/test.txt",,"COL=DELIMITER,DELIMITER=*<TAB>*")
:PROCESS &HND#
: SET &LINE# = GET_PROCESS_LINE(&HND#,3)
: PRINT &LINE#
:ENDPROCESS

Script element	Description
:CLOSE_PROCESS	Rejects an unnecessary data sequence
:PROCESS... :TERM_PROCESS... :ENDPROCESS	Loop for line by line processing of a data sequence - a sequential file or a command result, for example
GET_PROCESS_LINE	This is used to retrieve content from the current line of a data sequence.