PREP_PROCESS_FILE

Use the PREP_PROCESS_FILE script function to retrieve the content of a text file, such as a log or trace file, which is available on a particular computer. The content of the file is stored in an internal list (data sequence) line by line. The script lets you filter for a particular text in the file. The script function returns a reference to the data sequence that you can use for further processing by assigning the return code to the :PROCESS script statement. Use the GET_PROCESS_LINE script function to access content in the data sequence.

Important!

• PREP_PROCESS_FILE only works with OS Agents. Do not use the function in combination with Agents for databases, Oracle applications, PeopleSoft, SAP, JMX, or Rapid Automation.
• (UNIX) Permissions that are set by using ACL commands are not considered.
• Processing large files affects the performance of the Agent.

Notes:

• The script function causes all open transactions of the script to be written to the AE database. For more information, see Script Processing.
• You cannot assign a new value to the script variable that contains the reference to the data sequence. Use :CLOSE_PROCESS to discard the existing data sequence, and then assign a new value.
• There is no error message if the data sequence does not contain the content that you specify. The :PROCESS script statement does not process the data sequence in this case.

Syntax

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

Parameters

• PREP_PROCESS_FILE
  Retrieves the content of a text file

• Host
  Name of the Agent on the computer on which the file is located
  Format: script literal or script variable

• File
  Name of the text file to read
  Format: script literal or script variable
  Tip: Use a script function to retrieve the name of a file which is a part of a data group. For more information, see GET_FILESYSTEM.

• Filter
  (Optional) Filters for particular content of a line
  Format: script literal or script variable
  Default value: *
  Notes:

  • The filter is case insensitive.
  • Use the wildcard character * to stand for any number of characters, or ? for a single character in a filter.

• COL
  (Optional) Defines whether and how to split the data sequence lines into columns
  Format: script literal or script variable
  Use the following format COL=Definition1[, Definition2]. For more information, see Defining Columns.

• Login object
  (Optional) Name of a Login object
  The login data in the Login object is checked for access to the file to be read. The actual file access and transfer to the Automation Engine is done by the effective user of the Agent.
  Format: script literal or script variable
  Important! If you do not specify a Login object, the user must have the following privilege: File Transfer: Start without Login object specified and the FT_ANONYMOUS=Y must be set. For more information, see Granting Automation Engine Privileges and UC_HOSTCHAR_DEFAULT - Host Characteristics

Defining Columns

This script function reads the entire line of a data sequence. The data can also be accessed when the line is divided into columns. The columns can be defined in the first line of the file itself, or specified in the parameters of PREP_PROCESS_FILE. The following restrictions apply:

• Maximum number of columns: 22
• Total size: 2048 bytes
• Maximum column size: 255 characters
• Maximum length of column name: 32 characters

Important! The script aborts if you exceed these limits.

To define columns in the script function, specify the following parameters:

COL=Definition1[, Definition2]

Where

• COL
  Keyword for column separation

• Definition1
  Defines whether the data sequence lines are split into columns
  Format: script literal or script variable
  Allowed values:

  • NONE
    Lines are not split into columns
  • FILE
    Uses column definition from the file
  • LENGTH
    Sets a predefined column size
    Note: Use LENGTH_TAB in Definition2 to specify the size.
  • DELIMITER
    Separates columns with a delimiter
    Note: Use DELIMITER in Definition2 to specify the delimiter.

• Definition2
  (Optional) Defines column sizes and names, or the delimiter
  Format: script literal or script variable
  Allowed values:

  • LENGTH_TAB
    Specifies column sizes and column names
    Example:"COL=LENGTH,LENGTH_TAB='3=drive,100=file name'"
    Notes:
    • Separate individual column definitions with commas.
    • Specify up to 22 columns with a total of 2048 bytes.
    • Specify the column size as the number of characters. The maximum size is 255 characters.
    • (Optional) specify column names. Names can be up to 32 characters long.
    • Use quotation marks before the first and after the last column definition. Use double quotation marks if you use single quotation marks for script literals in Definition2, or vice versa.
  • DELIMITER
    Defines a delimiter that separates columns
    The lines of the data sequence are returned as columns that are placed before, between or after the delimiter string.
    Example:
    "COL=DELIMITER,DELIMITER=*'*"
    'COL=DELIMITER,DELIMITER=@"@'
    Default value: ;
    Notes:
    • You can use any characters as the delimiter.
    • You can also use the tabulator as a delimiter: 'DELIMITER=<TAB>'
    • The delimiter can be a string of up to 10 characters.
    • Enclose the delimiter with any character: *Delimiter*. The enclosing characters are not displayed in the output.
    • A column is not separated if a line does not include a delimiter.
    • If you use single quotation marks as delimiters, then you must enclose Definition2 in double quotation marks, or vice versa.

Examples

The following example reads the contents of a text file, and retrieves all lines that contain the string "Start". The script prints the retrieved lines in the activation report.

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

The following example reads all lines of a file, and divides the retrieved data into columns as defined in the first line of the file itself. The script specifies a Login object to log on to the computer where the file is located.

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

The following script includes parameters that define column names and widths. 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='74=PATH,25=NAME,5=VALUE,2=STATUS,9=DATE,7=TIME'")

The following script defines the tabulator as a separator for the columns. The script only prints the content of the third column in the activation report.

: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

See also: