User Command Environment

The user request is initiated by the INITIATOR program running under the UNVSRV pre-start job via the UAGSRV program running under a different UNVSRV pre-start job.

The INITIATOR program:

1. Performs environment setup required to execute user commands or scripts.

2. Changes the user profile if user credentials are specified in the associated task definition.

3. Initiates the user request.

4. Monitors the user's request as it runs.

5. Catches any exceptions that occur and prints their content to stderr.

Following completion of the user request, the INITIATOR program:

1. Cleans up the environment.

2. Returns the maximum severity code encountered while processing the user request to be used as the exit code for the associated task instance.

The INITIATOR job log is retained on the system in the pending state. The spool file output produced by the executed commands is written to the user's default spool output queue. The spool files produced by the commands are not returned with the task instance output. If you would like the command output returned to the Universal Command Manager as well as the job log, see Universal Submit Job for an execution method that returns all command spool files as well as the job log.

The UNVSRV pre-start job is defined in the UNVUBR770 subsystem. By default, there are always at least three UNVSRV pre-start jobs running under the UNVUBR770 subsystem.

Initiator (INITIATOR) Exit Points

The Initiator (INITIATOR) calls two user exits:

1. UAGSJOBI is called once for job initialization.

2. UAGSJOBT is called once for job termination.

The CL source code is provided in UNVPRD770/UNVCLSRC.

The CL source files are compiled and bound with the following command:

Change the exitname to the name of the exit to be compiled and bound.

UAGSJOBI

The UAGSJOBI exit is called before any user command is executed. This exit can be used to customize the job's environment to meet local requirements. It executes under the user profile associated with the credentials specified in the associated task definition. If no credentials are specified, the UNVUBR770 user profile is used. If the exit issues unhandled messages with a severity greater than or equal to the value of the UAG Server END_SEVERITY option, the job will terminate without executing any user commands.

UAGSJOBT

The UAGSJOBT exit is called after all user commands have completed. The current exit code is passed in as a parameter. The exit executes under the user profile associated with the credentials specified in the associated task definition. If no credentials are specified, it executes under the UNVUBR770 user profile. The exit will always be called once UAGSJOBI returns successfully. If UAGSJOBI issues an unhandled message that causes job termination, UAGSJOBT will not be called.

User Command Exit Code

The exit code returned to the task instance in the Controller indicates the success or failure of the user-requested command. The exit code is returned by UAG based on the exit code that it receives from the Initiator (INITIATOR). The Initiator sets its exit code based on the highest severity of the IBM i messages propagated to it from user commands or scripts. The Initiator traps and handles all *ESCAPE, *NOTIFY, *STATUS messages and function checks.

INITIATOR continues executing user commands as long as the highest message severity is less than the severity specified by the UAG Server END_SEVERITY option.

In the event of an error not associated with the user-requested command, UAGSINIT returns exit code 99. If the error occurs following set up for returning the UAGSINIT job log to the user, the job log is returned as usual. Otherwise, no job log is returned and the user must check the output queues for a job log associated with the failure.

User Identification

• Task definitions that specify credentials will execute user commands in a job set to specified user profile.

• For task definitions that do not specify credentials, the user profile used for the job that runs the user commands is inherited from the Universal Broker. The inherited user profile is UNVUBR770; as installed, this profile provides a very high level of authority including *ALLOBJ, *SPLCTL, and *JOBCTL.

Current Library and Working Directory

The current library and working directory of a user command depends on the user profile under which the job runs:

User Commands

UAG accepts four forms of commands from task definitions specified in the Controller.

1. Single CL command

2. Single REXX line

3. Single PASE command

4. CL command script

5. REXX EXEC script

Single CL Command

The IBM i task type in the Controller specifies a command type of CL via the "Command Type" drop down in the task definition form.

The CL command must be of a type that can be executed by the QCMDEXC API. This is indicated by the command description in the CL Reference manual by the keyword Exec in the upper right corner of the command's syntax diagram.

Single REXX Line

The IBM i task type in the Controller specifies a command type of REXX via the "Command Type" drop down in the task definition form.

REXX and any associated commands must be of a type that can be executed by the QCMDEXC API as described in Single CL Command above.

Multiple statements contained in the single line command must be separated by semicolons as described in the REXX manuals. The first statement does not require a REXX comment.

For example, the following command sends the text "'Change current library to ABC" to standard output and changes the current library:

A user may use a simple REXX program in this context to setup and execute programs on the IBM i.

REXX provides the benefit of using standard output (STDOUT) and standard input (STDIN) files as part of their environment. The SAY command writes to STDOUT and the PULL command reads from STDIN.

STDOUT from REXX on the IBM i is redirected back to STDIN of the Command Manager and REXX STDIN on the IBM i is redirected from the STDOUT of the Command Manager. CL command files do not use STDOUT or STDIN directly.

Single PASE Command

The IBM i task type in the Controller specifies a command type of PASE via the "Command Type" drop down in the task definition form.

CL Command Script

The IBM i task type in the Controller specifies a CL command script by selecting Script from the "Command or Script" drop down and selecting the target script from the "Script" dropdown in the task definition form.  Additionally, in order to be processed as a CL script, the script name must use an extension of ".cl".  For example, "my_cl_script.cl".

The script contains a sequence of CL commands to be executed in sequential order. The commands are executed from first to last or until a command generates a message with a severity greater than or equal to the UAG Server END_SEVERITY option.

The CL commands are limited to the same set of CL commands described in Single CL commands above.

Each command is executed within the same job environment. This is similar to a batch job execution, but // CL commands cannot be used.

Blank lines and CL comment lines are ignored in the script.

CL line continuation characters (+ and -) can be used in the script and are processed accordingly.

The first line cannot be a comment line containing the word REXX.

REXX EXEC File

The IBM i task type in the Controller specifies a REXX command script by selecting Script from the "Command or Script" drop down and selecting the target script from the "Script" dropdown in the task definition form.  Additionally, in order to be processed as a REXX script, the script name must use an extension of ".rexx".  For example, "my_rexx_script.rexx".

REXX EXECs have the benefit of using standard output (STDOUT) and standard input (STDIN) files as part of their environment. The SAY command writes to STDOUT and the PULL command reads from STDIN.