Automation Engine Script Guide > Ordered by Function > Data Sequences > PREP_PROCESS_FILENAME

PREP_PROCESS_FILENAME

Script Function: It retrieves a list of the file names that are available in a specified computer directory and provides the result for further processing in the form of an internal list (data sequence).

Syntax

PREP_PROCESS_FILENAME(Host, File name, [Wildcards], [Subfolder], [Filter] [,"COL=Definition1[, [Definition2]"],["UC_LOGIN=Login object"])

Syntax

Description/Format

Host 

The computer (name of the agent) on which the files are stored.
Format: script literal or script variable 

File name 

The path and the file name that should be searched.
Format: script literal or script variable

The wildcard characters "*" and "?" can be used in file names. "*" stands for any character, "?" for exactly one. Paths must not contain wildcard characters.

Whether uppercase and lowercase letters are considered depends on what is specified in the parameter Wildcards.

Wildcards 

This indicates whether the file name is specified with wildcard characters.
Format: script literal or script variable

Allowed values: "Y" (default value) and "N"

"Y" = File name with wildcard characters; uppercase and lowercase letters are not distinguished
"N" = File name without wildcard characters; uppercase and lowercase letters are distinguished

Subfolder 

This indicates whether subfolders or subdirectories should be included in the search.
Format: script literal or script variable

Allowed value: "Y" and "N" (default value)

"Y" = Subfolders or subdirectories
"N" = Subfolders or subdirectories not considered

Filter 

This is an additional option for filtering the lines of the data sequence.
Format: script literal or script variable

Case-insensitive; uppercase or lowercase spelling is accepted. The wildcard characters "*" and "?" can be used. "*" stands for any character, "?" for exactly one. Default: "*" 

Definition1 

This determines whether the lines of the data sequence should be split in columns.
Format: script literal or script variable

Allowed values: "NONE" (default value), "LENGTH", "DELIMITER"

"NONE" = No columns
"LENGTH" = Specified size of the column. Requires LENGTH_TAB= as Definition2
"DELIMITER" = Columns are divided by delimiters. Requires DELIMITER= as Definition2

Definition2 

This determines 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 (limit: 22 columns). Quotations must additionally 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.

    For example:

    "COL=LENGTH,LENGTH_TAB='3=drive,100=file name'"
     
  • "DELIMITER"

    The delimiter is specified in the form *Delimiter*.
    "*" = freely defined delimiter
    = A string that includes a maximum of 10 characters and separates the columns. If single quotations are used as Delimiters, the whole phraseCOL=Definition1[,Definition2] must be enclosed in double quotations and vice versa.

    Default value: Semicolon (;)

    For example:

    "COL=DELIMITER,DELIMITER=*'*"
    'COL=DELIMITER,DELIMITER=@"@'

Login object

The name of a Login object.
Format: script literal or script variable

Put the complete phrase UC_LOGIN=Login object in inverted commas.

Return code

The reference to a data sequence of the file list.

"20240" - Login information is missing.
"20303" - Automation Engine authorization error.
"20349" - The agent is not available.
"20510" - A CP/WP has been specified instead of an agent.
"20514" - Invalid entry when used with wildcard characters. 

Comments

The script function PREP_PROCESS_FILENAME provides a list of file names for further processing with AE Script. On the host, the files are retrieved by the agent and processed as a data sequence.

The parameter File name is used to call the files that should be listed. If File name contains a drive indication, all found files are displayed in the same way. You can specify whether subfolders or subdirectories should be considered. You can also filter the list of files that were found.

Wildcards, Subfolders, Filters and the parameters for splitting columns are optional. Note that you must use a comma in order to indicate that one of the parameters is not used. You can use any of the optional parameters as the last parameter. Make sure that no comma is used after the last parameter. Definition2 cannot be used without Definition1.

By default, the script function GET_PROCESS_LINE reads the complete line of a data sequence. You can also access it in a structured way when the lines are divided in columns. The following rules apply in this case:

To access particular columns, you can use GET_PROCESS_LINE.

 By using the optional parameter UC_LOGIN, you can assign the name of a Login object to this script function. PREP_PROCESS_FILENAME uses the login data that has been defined in the Login object. In doing so, you can access connected network drives, for example. Users require the Privilege "File transfer: Start without user ID" when the script function PREP_PROCESS_FILENAME should be used without the parameter UC_LOGIN.

The script function's return code refers to a data sequence which is passed on to the script statements :PROCESS and :ENDPROCESS in the form of 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.

Note that no error will occur when the data sequence does not contain the required content.The only effect is that the data sequence that is defined between :PROCESS and :ENDPROCESS does not take place.

You cannot assign a new value to the script variable that contains the reference to the data sequence. You must first discard the data sequence that includes the script statement CLOSE_PROCESS, and then you can reuse the variable.

Agents for applications (Oracle Applications, PeopleSoft or SAP) do not support PREP_PROCESS_FILENAME.

This script statement causes all open transactions of the script to be written to the AE databaseA database is an organized collection of data including relevant data structures..

Examples

The following example lists all HTML documents that the WebHelp of the Automation Engine Documentation includes. It is explicitly specified that wildcard characters are used. The result will be written to 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 second example creates a list of all stylesheets that are supplied with the Automation Engine Documentation. All subfolders of the documentation directory should be searched. The result contains no drive specification and is written to the 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 third example creates a list of all AE programs. The individual lines are split in columns. The columns are separated by backslashes. The 5th column that contains the file name of the program is accessed while the data sequence is being processed. The result is written to the activation protocol.

: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 fourth example is based on the third example but a filter is set so that only the file name of the Automation Engine is written to the activation protocol.

: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:

Script element Description

:CLOSE_PROCESS

Discards 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.

Script Elements - Data Sequences

About Scripts
Script Elements - Alphabetical Listing
Script Elements - Ordered by Function