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.

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.
• PREP_PROCESS causes all open transactions of the script to be written 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 0000 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:

1. The Event job that you specify in the EventJob parameter is activated. The job name is EVENT.EventJob.
   
2. The Event job runs on the Host that you specify.
3. 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.
4. 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: The RunID is shown as a converted string, and not as a number. For more information, see 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")

See also: