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

PREP_PROCESS

Script Function: This script function uses specific Job objects (event jobs) in order to process commands on a computer and it returns the Console output that can be used for further processing as an internal list (data sequence).

Syntax

PREP_PROCESS(Host, EventJob, [Filter], Action, [Column separation]..., [UC_LOGIN=Login object])

Syntax	Description/Format
Host	Computer (agent name) on which the event runs. Format: script literal or script variable
EventJob	Name part of the event job that should be executed. Format: script literal or script variable
Filter	Defines a filter condition for the content of the returned line (case insensitive). Format: script literal or script variable Default value: "*"
Action	Assigns a value to a script variable of the event job, Format: script literal or script variable. Default value: "" Specific syntax: Variable=Assignment Variable - Name of the event job's script variable which assumes the value assignment. It is specified without the & character. Assignment - Value of the script variable. This is mainly an action (command, program call or activation of a file) that should be executed in the target system, or any other value assignment (variables of the attribute dialog). You can use variables set in the ATTRDIA.* include objects found in client 0. The sixth example below sets the queue object assignment for UNIX. A specific syntax is required in order to query the UNIX file system.
Column separation	You can also specify that data sequence lines should be subdivided in columns. Use the following format: COL=Definition1[, Definition2]. Format: script literal or script variable Definition1: Allowed values: "NONE" (default value), "FILE", "LENGTH", "DELIMITER" "NONE" = No subdivision in columns "FILE" = A column definition is used in the first line of the file which the agent creates if event jobs start which execute the SAP JCL element R3_GET_MONITOR ("R3MONITOR" uses the parameter EventJob of the system client's template event job "EVENT.R3MONITOR" ). "LENGTH" = Predefined column size. Requires LENGTH_TAB= for Definition2 "DELIMITER" = Columns are separated by a delimiter. Requires DELIMITER= as Definition2 Definition2: Defines 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 column definitions must be separated by commas (maximum 22 columns). Quotes are also required before the first and after the last column definition. Double quotation marks must be used if single quotation marks have been used as script literals for Definition2 and vice versa. Example: "LENGTH_TAB='10=Department,25=Head,10=Budget'" "DELIMITER" Columns that should be separated by characters can be specified in the form Delimiter. "" = You can use any characters of your choice. They only indicate that the string they enclose is a Delimiter. These characters are not shown in the output. Delimiter = A string of a maximum length of 10 characters which separates the columns. The characters of a line are returned as columns that are positioned before, in between or after the Delimiter* string. A column is not separated if a line does not include a Delimiter. If you have used single quotation marks as Delimiters, you must enclose Definition2 in double quotation marks and vice versa. Default value: Semi colon (;) Example: "DELIMITER='" 'DELIMITER=@"@' Note that separation by columns only works correctly if values do not contain the reserved String "§§§".
UC_LOGIN	Name of a Login object. Format: script literal or script variable Note that this script function requires login data. The relevant event job must include valid login information if the parameter UC_LOGIN has not been specified.

Return code
Reference to the data sequence of the command.

Comments

The script function PREP_PROCESS creates a data sequence such as the results of:

OS commands of BS2000, MPE, UNIX, VMS and Windows,
BS2000 Console commands,
UNIX file system queries,
SAP monitors, SAP system log and SAP jobs

Executing a BS2000 Console command or querying a UNIX file system requires the AE utilities UCYEBXXZ or UCXE???F to be installed.

Console and OS commands are processed by means of event jobs which start in the background on the computer of the specified agent (Host). A command's result lines are available in the form of an internal list (data sequence) via the script function's return code.
The names of event jobs are structured as follows: "EVENT.EventJob". "EVENT." is a pre-determined part of the job name. The part "EventJob", however, can be defined in any way. The definition of an event job is given in terms of particular attributes and the general script structure.
event jobs are supplied in system client 0000. You can use them directly or as a template in the individual clients. If required, you can adjust their contents. Keep in mind to change the script procedure in EVENT.UNIXCMD to avoid that the report will be deleted if a return code >0 occurs.

The following internal steps are passed when the data sequence that is provided by PREP_PROCESS is being processed:

The event job that has been specified using the parameter EventJob is activated (job name: EVENT.EventJob).
The event job runs on the Host and performs the action that is specified in Action. Line by line, it redirects the action result to a data sequence.
Lines are only considered if their contents comply with the parameter Filter. Using this parameter is optional.
You can specify any value assignment in the parameter Action.
In the OS commands of BS2000, MPE, UNIX, VMS and Windows, as well as the BS2000 console commands, variable primarily supplies the value for the script variable "&CMD". You can also assign values to script variables that are available within the attribute dialog. When the event job starts, the corresponding Include is processed in the script and supplied with values internally (depending on the EventJob),without the attribute dialog being displayed.
A specific parameter syntax applies for querying UNIX file systems.
The data sequence that has been generated on the Host is transferred to the Automation Engine via file transfer in order to be processed. By default, the name of the file that is transferred from the Host to the Automation Engine is "ERRRRRRR.TXT". The following placeholders are used for the variable parts:

E - Event
RRRRRRR - Running number (RunID) of the task

Note that the RunID is shown as a converted string (see RUNNR2ALPHA) and not as a number.

By default, this script function reads an entire line. You can also access it in a structured way if the line has been subdivided into columns. The following rules apply:

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

GET_PROCESS_LINE can be used to access particular columns.

The script function returns a data sequence reference. This reference is passed to the script statements :PROCESS and :ENDPROCESS as a start parameter. In combination with the script function GET_PROCESS_LINE, you can now process each individual line of the data sequence and its columns.

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

You cannot assign a new value to the script variable which contains the data sequence reference. The data sequence must be discarded with the script statement :CLOSE_PROCESS first, and then the variable can be reused.

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

In the first example, the command "/STA P" is executed on the BS2000 computer "C70". The required ID and account are read from the Login object.

:SET &HND# = PREP_PROCESS("C70","BS2000CMD",,"CMD=/STA P","UC_LOGIN=ADMIN")

The next example executes a command on a BS2000 console which outputs all open applications. No filter is specified for the line content.

:SET &HND# = PREP_PROCESS("C70","BS2000UCON",,"CMD=/BCDISP DISP=O","UC_LOGIN=ADMIN")

The third example retrieves the directories of a given drive on the Windows computer "WIN23".

:SET &HND# = PREP_PROCESS("WIN23","WINCMD","*DIR*","CMD=DIR C:","UC_LOGIN=ADMIN")

The fourth example reads the SAP monitor "MON1" from the monitor set "AE". The individual columns of the monitor data which have been defined in the file should be accessed. User and SAP client are read from the specified Login object.

:SET &HND# = PREP_PROCESS("T46","R3MONITOR","*","MONSET=AE","MONNAM=MON1","COL=FILE","UC_LOGIN=AEADMIN")

The fifth example runs a command on the UNIX agent "UNIX01" which returns information about connections with the port 2400.

:SET &HND# = PREP_PROCESS("UNIX01","UNIXCMD",,"CMD=netstat -an | grep 2400","UC_LOGIN=LOGIN.UNIX")

The sixth example sets the queue object assignment. Note that the value of uc_queue in this example comes from the ATTRDIA.UXIX include object.

:SET &HND# = PREP_PROCESS("UNIX01",'*','cmd=dir','uc_queue=&$QUEUE#',"UC_LOGIN=LOGIN.UNIX")

Script element	Description
:CLOSE_PROCESS	Discards an unnecessary data sequence.
:PROCESS... :TERM_PROCESS... :ENDPROCESS	They are used to define a loop for line by line processing of data sequences. For example, the contents of sequential files or the result of a command.
GET_PROCESS_LINE	This is used to retrieve content from the current line of a data sequence.