PREP_PROCESS_FILENAME

Use the PREP_PROCESS_FILENAME script function to retrieve a list of files that are available in a specific computer directory. The script lets you filter for particular file names, and specify whether to include subdirectories and folders. On the host, the Agent retrieves the files. The script function returns a reference to a 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 each line in the data sequence.

Important! Agents for applications (Oracle applications, PeopleSoft, and SAP) do not support PREP_PROCESS_FILENAME.

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_FILENAME (Host, File name, [Wildcards], [Subfolder], [Filter] [,"COL=Definition1[, Definition2]"] ,"UC_LOGIN=Login object")

Parameters

  • PREP_PROCESS_FILENAME
    Retrieves a list of file names

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

  • File name
    Path and file name to search for
    Format: script literal or script variable
    Notes:

    • Use the wildcard character * to stand for any number of characters, or ? for a single character in the file name.
    • Do not use wildcards in the path.
    • Case sensitivity is determined by the parameter Wildcards.

  • Wildcards
    (Optional) Indicates whether the file name is specified with wildcard characters
    Format: script literal or script variable
    Allowed values:

    • Y (default)
      File name contains wildcard characters, case insensitive
    • N
      File name does not contain wildcard characters, case sensitive

  • Subfolder
    (Optional) Determines whether to include subfolders and subdirectories in the search
    Format: script literal or script variable
    Allowed values:

    • Y
      Subfolders and subdirectories are included
    • N (default)
      Subfolders and subdirectories are excluded

  • Filter
    (Optional) Additional filter for file names in the data sequence
    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.

  • COL
    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. For more information, see Granting Automation Engine Privileges.
    • Enclose the complete phrase UC_LOGIN=Login object in quotation marks.
    • (z/OS) UserIDs without a password (such as PROTECTED UserIDs in the Login object) cannot be used anymore since v12.1 when login security was improved and password requirements were changed. See Login (LOGIN)

Note: Include commas between the parameters even if you omit parameters. Do not place a comma after the last parameter that you specify.

Defining Columns

To split the data sequence lines into columns, specify the Column separation parameter as follows:

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
    • 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
    Note: If you specify Definition2, you must specify Definition1.
    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.
      • 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.

Return Codes

The script function retrieves a reference to a data sequence that contains a list of retrieved file names. The following return codes indicate errors:

  • 20240
    Login information is missing
  • 20303
    Automation Engine authorization error
  • 20349
    Agent is not available
  • 20510
    A CP or WP is specified instead of an Agent
  • 20514
    Invalid entry when used with wildcard characters

Examples

The following example lists all HTML documents contained in the Web Help of the Automation Engine documentation. The use of wildcards is explicitly specified. The resulting list of files is printed in the activation report.

:SET &HND# = PREP_PROCESS_FILENAME("WIN01","c:\AUTOMIC\documentation\webhelp\german\uc*.htm","Y",,,,"UC_LOGIN=WIN_LOGIN")
:
PROCESS &HND#
:   
SET &LINE# = GET_PROCESS_LINE(&HND#)
:  
PRINT &LINE#
:
ENDPROCESS

The following example creates a list of all stylesheets that are supplied with the Automation Engine documentation. All subfolders of the documentation directory are included in the search. The result contains no drive specification, and is written to the activation report.

:SET &HND# = PREP_PROCESS_FILENAME("WIN01", "\AUTOMIC\documentation\uc*.css","Y","Y",)
:
PROCESS &HND#
:   
SET &LINE# = GET_PROCESS_LINE(&HND#)
:  
PRINT &LINE#
:
ENDPROCESS

The following example creates a list of all AE programs. The individual lines are split in columns, with the columns separated by backslashes. The script retrieves the fifth column in the data sequence, which contains the file name of the program, and writes the results in the activation report.

:SET &HND# = PREP_PROCESS_FILENAME("WIN01","c:\AUTOMIC\server\bin\*.exe",,,,"COL=DELIMITER,DELIMITER=*\*")
:
PROCESS &HND
:
SET &LINE# = GET_PROCESS_LINE(&HND#,5)
:
PRINT &LINE#
:
ENDPROCESS

The following example retrieves the same files, but this time, a filter excludes all files except those that contain the string "server" in the file name.

:SET &HND# = PREP_PROCESS_FILENAME("WIN01","c:\AUTOMIC\server\bin\*.exe",,,"*server*","COL=DELIMITER,DELIMITER=*\*")
:
PROCESS &HND#
:
SET &LINE# = GET_PROCESS_LINE(&HND#,5)
:
PRINT &LINE#
:
ENDPROCESS

See also: