PREP_PROCESS

Use the PREP_PROCESS script function to create a data sequence based on target system commands. The function uses event jobs to process the commands on a defined host, and returns the output as an internal list (data sequence) that you can use for further processing.

This page includes the following:

Overview

PREP_PROCESS returns a reference to the data sequence. This reference is passed on to :PROCESS... :TERM_PROCESS... :ENDPROCESS. By default, PREP_PROCESS reads a complete line. The script function lets you structure the lines by splitting them into columns.

Tip: Use GET_PROCESS_LINE to access and process particular columns in the returned data sequence.

The script function supports the following OS commands:

BS2000
UNIX
VMS
Windows

The script function also supports the following other types of commands:

BS2000 console commands
UNIX file system queries
SAP monitors
SAP system logs
SAP jobs

Important!

(BS2000) To execute a BS2000 console command, the utility UCYEBXXZ must be installed. See Installing the Agent for BS2000.
(UNIX) Querying the UNIX file system requires the utility UCXE???F to be installed. See PREP_PROCESS - Querying the UNIX File System.
(Windows) To execute a Windows command on a host where UAC is enabled, add UC_LOGON_AS_BATCH=Y as a parameter of PREP_PROCESS. This is not required when the parameter Batch Mode: Log on a batch user is activated in the parameter section of the Job object. For more information, see Windows Jobs.

Notes:

No error message is displayed if the data sequence does not contain the indicated content. In this case, the data sequence that is defined between :PROCESS and :ENDPROCESS is not processed.
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.
This script function writes all open transactions of the script to the AE database. For more information, see Script Processing.

Syntax

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

Parameters

PREP_PROCESS
Returns a data sequence
Host
Name of the Agent on which the Event job runs
Format: script literal or script variable
EventJob
Name part of the Event job to execute
For more information, see Event Jobs below.
Format: script literal or script variable
Filter
(Optional) Filters for content in the returned line
Note: the filter condition is case insensitive.
Format: script literal or script variable
Default value: *
Action
Assigns a value to a script variable in the Event job
For more information, see Defining Actions.
Format: script literal or script variable
Notes:
- By default, the value is empty.
- Specify the variable name without the leading ampersand (&).
Example: cmd = os_command
Column separation
(Optional) Defines whether and how to split the data sequence lines into columns
Format: script literal or script variable
Notes:
- Separation by columns only works correctly if values do not contain the reserved string §§§.
- Use the following format COL=Definition1[, Definition2]. For more information, see Defining Columns.
Login object
(Optional) Name of a Login object
Format: script literal or script variable
Important! If you do not specify a Login object, then the relevant Event object must include valid login information.

Defining Actions

The Action parameter lets you assign a value to a script variable in the Event job. The value that you assign to the script variable can be any type of value, including the following:

Action
Command
Program call
File activation to execute in the target system

In the following types of commands, the Action that you define typically supplies the value of script variable &CMD in the Event job:

BS2000 OS and console commands
UNIX OS commands
VMS OS commands
Windows OS commands

You can also assign object attribute values to script variables. For more information, see Modifying Object Attributes. 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.

Defining Columns

If you want 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
Allowed values:
- NONE
  Lines are not split into columns
- FILE
  (SAP) A column definition is used in the first line of the file that the Agent creates when an Event job starts that executes the SAP JCL element R3_GET_MONITOR. R3MONITOR uses the EventJob parameter of the EVENT.R3MONITOR template event job of the system client.
- 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: "LENGTH_TAB='10=Department,25=Head,10=Budget'"
  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:
  "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.

Event Jobs

By default, client 0 includes the following Event jobs in the PREP_PROCESS folder of the Process Assembly perspective:

EVENT.BS2000CMD
EVENT.BS2000UCON
EVENT.NSK.CMD
EVENT.R3GETJOB
EVENT.R3MONITOR
EVENT.R3SYSLOG
EVENT.UNIXCMD
EVENT.UNIXFS
EVENT.VMSCMD
EVENT.WINCMD

You can use the Event jobs as they are, or adjust them for your own event jobs. The names of these event jobs are structured as follows:

EVENT.EventJob

EVENT.
Predefined part of the job name
EventJob
Freely define this part of the name

The definition of an event job is given in terms of particular attributes and the general scripting structure.

Processing

When the data sequence returned by PREP_PROCESS is processed, the following internal steps are carried out:

The Event job that you specify in the EventJob parameter is activated. The job name is EVENT.EventJob.
The Event job runs on the Host that you specify.
The job performs the Action that you specify. Line by line, the job redirects the action result to a data sequence.
Note: If you have defined a Filter, only the lines that comply with the filter are considered.
The data sequence that is generated on the Host is transferred to the Automation Engine for processing. The default 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
RunID of the task

Note:

RUNNR2ALPHA

Examples

The following script uses PREP_PROCESS to run a ping command for a given server, and reacts to the output. To simplify the parsing, the script sets a filter to return only the result line.

:SET &HND# = PREP_PROCESS(PSA,wincmd,'loss','cmd=ping www.automic.com','uc_login=login.common')

! For test purposes, use an IP address of a server that does not exist

!:SET &HND# = PREP_PROCESS(PSA,,'loss','cmd=ping 10.0.0.123','uc_login=login.common')

:PROCESS &HND#

:SET &LINE# = GET_PROCESS_LINE(&HND#)

:PRINT &LINE#

:IF STR_FIND(&LINE#,'100% loss') > 0

:PRINT ALARM Webserver is not reachable

! Define necessary actions here

:ENDIF

:ENDPROCESS

If everything is fine, the script just prints the retrieved result line in the activation report:

Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),

If something is wrong and the retrieved results include a line that indicates a 100% loss, the script prints the alarm message in the activation report, and carries out actions that you have defined to remedy such situations.

Packets: Sent = 4, Received = 0, Lost = 4 (100% loss),

ALARM Webserver is not reachable

The following examples show different parameters that you can define for PREP_PROCESS.

Execute the /STA P command on a BS2000 computer that is called C70. The required ID and account are read from a Login object.
:SET &HND# = PREP_PROCESS("C70","BS2000CMD",,"CMD=/STA P","UC_LOGIN=ADMIN")
Execute 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")
Retrieve the directories of a given drive on a Windows computer that is called WIN23.
:SET &HND# = PREP_PROCESS("WIN23","WINCMD","*DIR*","CMD=DIR C:","UC_LOGIN=ADMIN")
Read an SAP monitor that is called MON1 from the AE monitor set. The script accesses the columns of monitor data which have been defined in the file itself. The 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")
Run a command on a UNIX agent that is called UNIX01. The script returns information about connections with the port 2400.
:SET &HND# = PREP_PROCESS("UNIX01","UNIXCMD",,"CMD=netstat -an | grep 2400","UC_LOGIN=LOGIN.UNIX")