PREP_PROCESS

Use the PREP_PROCESS script function to generate a data sequence from target system commands. This function uses event jobs to execute commands on a specified host, returning the output as an internal data sequence for subsequent processing.

This page includes the following:

Overview

PREP_PROCESS yields a reference to a data sequence, which you must pass to the :PROCESS... :TERM_PROCESS... :ENDPROCESS statements. While the function reads entire lines by default, you can configure it to split these lines into structured columns.

Tip: Use GET_PROCESS_LINE to access and manipulate specific columns within the returned data sequence.

The script function supports the following operating system commands:

  • BS2000
  • UNIX
  • VMS
  • Windows

Additionally, the function supports the following specialized command types:

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

Important Considerations

Keep the following technical requirements and system behaviors in mind when using PREP_PROCESS:

  • BS2000 Commands: To execute BS2000 console commands, you must install the UCYEBXXZ utility. See Installing the Agent for BS2000.
  • UNIX Queries: Querying the UNIX file system requires the UCXE???F utility. See PREP_PROCESS - Querying the UNIX File System.
  • Windows UAC: To execute commands on Windows hosts with User Account Control (UAC) enabled, you must include the UC_LOGON_AS_BATCH=Y parameter. However, this parameter is unnecessary if you have already activated the Batch Mode: Log on a batch user option in the Job object's settings. For more information, see Windows Jobs.
  • Empty Data Sequences: If the retrieved data sequence lacks the specified content, the system suppresses error messages and simply skips the processing block defined between :PROCESS and :ENDPROCESS.
  • Variable Reassignment: You cannot directly reassign a new value to a script variable that currently holds a data sequence reference. Instead, use :CLOSE_PROCESS to discard the active data sequence before performing a new assignment.
  • Database Transactions: This function automatically commits all open script transactions to the AE database. For more information, see Script Processing.

Syntax

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

Note: Only include the [UC_LOGON_AS_BATCH=Y] parameter when executing commands on Windows Agents where UAC is enabled. Omit this parameter in all other scenarios.

Parameters

Parameter Description Format Default Value
Host Specifies the name of the Agent responsible for running the Event job. Script literal or script variable n.a.
EventJob Defines the specific name segment of the Event job to execute. For more information, see Event Jobs below. Script literal or script variable n.a.
Filter (Optional) Applies a case-insensitive filter to isolate specific content within the returned lines. Script literal or script variable *
Action

Assigns a value to a script variable inside the Event job. For more information, see Defining Actions.

Notes: Specify the variable name without its leading ampersand (&).

Example: cmd = os_command

 Script literal or script variable Empty string
Column separation

(Optional) Determines how to split the incoming data sequence lines into structural columns.

Notes: Column separation fails if the text values contain the reserved string ยงยงยง. Use the syntax format COL=Definition1[, Definition2]. For more information, see Defining Columns.

 Script literal or script variable n.a.
UC_LOGIN=Login object (Optional) Declares the Login object. Important! If omitted, the referenced Event object must inherently contain valid login credentials. Script literal or script variable n.a.

Defining Actions

The Action parameter assigns values to script variables located inside the Event job. This parameter supports various value types, including actions, commands, program calls, or file activations intended for the target system.

For OS-level tasks (BS2000, UNIX, VMS, and Windows commands), the Action parameter typically populates the &CMD script variable inside the Event job.

You can also map object attribute values directly to script variables. For more information, see Modifying Object Attributes. Upon starting, the Event job internally processes the corresponding Include and supplies the values silently, bypassing the attribute dialog.

Defining Columns

To split data sequence lines into discrete columns, structure your Column separation parameter syntax as follows:

COL=Definition1[, Definition2]

Parameter Description Allowed Values Default Value
COL Acts as the base keyword invoking column separation. n.a. n.a.
Definition1 Dictates the method used to split the sequence lines.

  • NONE: Keeps lines intact without splitting.

  • FILE: (SAP only) Leverages the column definition from the file's first line, created when an Event job executes the SAP JCL element R3_GET_MONITOR. This relies on the EVENT.R3MONITOR template's parameters.

  • LENGTH: Imposes fixed column sizes (requires LENGTH_TAB in Definition2).

  • DELIMITER: Splits columns based on a specific character delimiter (requires DELIMITER in Definition2).

 NONE
Definition2 (Optional) Defines exact column sizes, names, or the specific delimiter character.

  • LENGTH_TAB: Assigns precise character limits and optional names to each column.

    Example: "LENGTH_TAB='10=Department,25=Head,10=Budget'".
    You can specify up to 22 comma-separated columns, allocating up to 2048 bytes overall and up to 255 characters per column. Optional names can reach 32 characters. Enclose the entire definition within quotation marks, alternating single and double quotes as needed.

  • DELIMITER: Identifies a boundary character (up to 10 characters long) used to split the data.

    Example: "DELIMITER=*'*" or 'DELIMITER=@"@'.
    Always wrap your chosen delimiter in arbitrary boundary characters (e.g., *Delimiter*), which will remain hidden in the output. Lines lacking the delimiter are not separated.

 ; (for DELIMITER)

Event Jobs

Client 0 natively provides several Event jobs located 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 deploy these standard Event jobs directly or customize them to meet specific requirements. Their nomenclature strictly follows the EVENT.EventJob structure, where "EVENT." is a mandatory prefix and "EventJob" represents your custom designation.

Processing

When the system processes the PREP_PROCESS data sequence, it executes the following sequential steps:

  1. The system activates the designated Event job using the EVENT.EventJob name structure.
  2. The Event job executes on the targeted Host.
  3. The job runs the defined Action and redirects the output line-by-line into a data sequence. If you specified a Filter, the system strictly isolates the compliant lines.
  4. The generated data sequence transfers from the Host to the Automation Engine. The transferred file defaults to the name ERRRRRRR.TXT, where "E" signifies Event and "RRRRRRR" represents the converted string format of the task's RunID.

Note: For details on converting numbers to strings for RunIDs, see RUNNR2ALPHA.

Examples

The following script deploys PREP_PROCESS to issue a ping command against a specified server, analyzing the output. It filters for the word 'loss' to isolate 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 the ping succeeds, the script outputs the result line to the activation report:

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

If the ping fails and identifies a 100% packet loss, the script triggers an alarm message in the activation report and executes any subsequent remedial actions:

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

ALARM Webserver is not reachable

Review these additional configurations demonstrating PREP_PROCESS parameter versatility:

  • BS2000 Command: Executes the /STA P command on host C70, extracting authentication details from the ADMIN Login object.

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

  • Console Command: Runs a BS2000 console command outputting open applications, without applying a line filter.

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

  • Directory Listing: Fetches directory details from the WIN23 Windows host.

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

  • SAP Monitor: Reads the MON1 SAP monitor, accessing internally defined data columns via the AEADMIN Login object.

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

  • UNIX Query: Scans the UNIX01 agent for active connections traversing port 2400.

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

See also:

seealso

Script Elements for Data Sequences