User Command Environment

The user request is initiated by the Universal Command Server Initiator program (UCMSINIT) running under the UCMSINIT pre-start job via the UCMSRV program running under the Universal Command Server (UCMSRV) job.

The UCMSINIT program:

1. Performs environment setup required to execute user commands or scripts.
2. Redirects the job log as requested.
3. Changes the user profile if user security is active.
4. Initiates the user request.
5. Monitors the user's request as it runs.
6. Catches any exceptions that occur.

Following completion of the users request, the UCMSRV program:

1. Processes the UCMSINIT job logs as required.
2. Returns the UCMSINIT job logs to the Universal Command Manager and, optionally, keeps a job log copy on the local iSeries server, as requested.
3. Cleans up the environment.

The UCMSRV program also handles fault tolerant requests from the Universal Command Manager.

By default, the UCMSINIT job log is returned to the Universal Command Manager via the standard error output stream (stderr). 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 to the Universal Command Manager. They are left in the spool. 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.

Both the UCMSINIT and UCMSRV pre-start jobs are defined in the UNVUBR511 subsystem. By default, there are always at least three each of the UCMSINIT and UCMSRV pre-start jobs running under the UNVUBR511 subsystem.

Initiator (UCMSINIT) Exit Points

The Initiator (UCMSINIT) calls two user exits:

1. UCMSJOBI is called once for job initialization.
2. UCMSJOBT is called once for job termination.

The CL source code is provided in UNVPRD511/UNVCLSRC.

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

CRTBNDCL PGM(UNVPRD511/exitname)
               SRCFILE(UNVPRD511/UNVCLSRC)
               SRCMBR(exitname)

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

UCMSJOBI

The UCMSJOBI 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 requested by the Manager. If the exit issues unhandled messages with a severity greater than or equal to the value of the UCMD Server END_SEVERITY option, the job will terminate without executing any user commands.

UCMSJOBI sets the current library to the current library specified in the user profile under which the job runs. However, if the UCMD Server LOGIN option is enabled, there may be a conflict between the current library set by UCMSJOBI and by the LOGIN functionality. To avoid this conflict, a new UCMSJOBI LOGIN parameter specifies that when LOGIN is active, UCMSJOBI no longer sets the current library.

If the 3.2.0 (or later) version of UCMSJOBI is used to replace UCMSJOBI on a 3.1.1 system, an exception will occur because of the new LOGIN parameter.

UCMSJOBT

The UCMSJOBT 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 requested by the UCMD Manager. The exit will always be called once UCMSJOBI returns successfully. If UCMSJOBI issues an unhandled message that causes job termination, UCMSJOBT will not be called.

User Command Exit Code

The exit code returned to the UCMD Manager indicates the success or failure of the user-requested command. The exit code is returned to the UCMD Manager by the UCMD Server (UCMSRV) based on the exit code that it receives from the Initiator (UCMSINIT). 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.

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

In the event of an error not associated with the user-requested command, UCMSINIT returns exit code 99. If the error occurs following set up for returning the UCMSINIT 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.

Depending on the job's logging settings and the severity of the error, no job jog may be saved. If an exception results in job termination, the returned exit code will be based on the numeric portion of the message identifier. The last four hexadecimal digits are used for the return code, with the most common being 9901 (decimal 39169). However, partial truncation, to the lower three digits, also occurs for managers running on some platforms.

If a job ends as a result of the ENDJOB command, whether issued directly or indirectly, the exit code will be the special value 199.

User Identification

UCMD Server can operate with user security active or inactive, based on the user security configuration option.

• With user security active, the UCMD Server requires the UCMD Manager to supply a valid user ID and password for the local system. The user command executes with the user profile of the received user ID.
• With user security inactive, the UCMD Server does not require the UCMD Manager to supply a valid user ID. The user command executes with the user profile of the UCMD Server. The user profile of the UCMD Server is inherited from the Universal Broker. The inherited user profile is UNVUBR511; 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 whether user security is active or inactive:

• With user security active, the user's current library and working directory is the home directory of the user profile specified in the UCMD Manager.
• With user security inactive, the current library and the working directory are those for the user profile associated with the service program. The default user profile defined and associated with the service program at installation is UNVUBR511.

User Commands

UCMD Server accepts four forms of commands from a UCMD Manager.

1. Single CL command
2. Single REXX line
3. CL command file
4. REXX EXEC file

Single CL Command

The remote UCMD Manager specifies a CL command using the COMMAND (-cmd) option.

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. Limit -cmd option length to 1000 bytes.

Single REXX Line

The remote UCMD Manager specifies a single REXX line using the COMMAND (-cmd) option with the COMMAND_TYPE (-cmd_type) option of rexx.

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. Limit COMMAND option length to 1000 bytes.

Multiple statements contained in the single line command must be separated by semicolons as described in the REXX manuals. The first statement does no 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:

ucmd -c "say 'Change current library to ABC'; \"CHGCURLIB CURLIB(ABC) \"" -i as400 -u qsysopr -w qsysopr -cmd_type rexx

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.

CL Command File

The remote UCMD Manager specifies a CL command file using the SCRIPT_FILE (-script) option.

The command file 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 UCMD 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 command file.

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

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

REXX EXEC File

The remote UCMD Manager specifies a REXX EXEC file by using the SCRIPT_FILE (-script) option.

This same UCMD Manager option is used to specify a CL command file. To distinguish between a REXX EXEC and a CL command file, the first line of the file containing the REXX EXEC must be a comment line containing the word REXX. The case of the letters does not matter.

For example, the following line is sufficient to indicate a REXX EXEC file:

/* 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.

The STDOUT file is redirected back to the STDOUT of the UCMD Manager and the STDIN is redirected from the STDIN of the UCMD Manager. CL command files do not directly use STDOUT and STDIN.

Command References

A command reference is a file on a Universal Command (UCMD) Server system that contains a pre-defined command or script.

The UCMD Manager requests execution of a command reference by specifying:

• Name of the command reference, in the COMMAND option.
• cmdref (command reference) value, in the COMMAND_TYPE option.

The UCMD Server searches the system for its directory of command references, as specified in the UCMD Server CMD_REFERENCE_DIRECTORY option, and executes the command or script in the command reference.

The UCMD Manager does not provide a command or script; everything is defined within the command reference. This provides the ability to define and control precisely what is executed by the UCMD Server.

Optionally, UCMD Managers provide an input file (via standard input) and options.

Command references that execute IBM i commands or REXX scripts are defined as files in the UNVCMDREF library. Each file can contain only one member. For security reasons, the library name is set to UNVCMDREF; this name cannot be changed or redefined.

For example, the following UCMD Manager command can be used from Windows or UNIX to request execution of the command reference cref100 and pass it options opt1 and opt2:

ucmd -c "cref100 opt1,opt2" -cmd_type cmdref ...

IBM i command references can define command types cmd and rexx.

For a complete discussion of Command References, see Command References.

Command Reference Example

The following command reference contains a command to display a library catalog.

To use this cmdref, invoke UCMD Manager using:

ucmd -c "cmdref_cmd" -cmd_type cmdref -u xxxx -w zzzz -i as400

In this case, the user (xxxx) has authority to call the IBM i system object QWCRJBST and cmdref_cmd is the name of the command reference file on the IBM i.

# -- File named cmdref_cmd in library UNVCMDREF --
# Use USBMJOB to execute the DSPLIB command.
#
-format cmd
-type cmd

usbmjob cmd(dsplib qsysopr)

The next command reference contains a series of four commands which are executed in sequence from top to bottom.

Invoke these commands from system as4test using:

ucmd -c "cref_test" -cmd_type cmdref -u xxxx -w zzzz -i as4test

In this case, the user (xxxx) has authority to call the IBM i system object QWCRJBST and cref_test is the name of the command reference file on the IBM i.

# -- File named cref_test in library UCVCMDREF --
# Execute a series of commands.  The output of the first two will remain
# on the output queue associated with the job's printer.  The output of
# the second two (by means of USBMJOB) will be directed to standard output
# and sent to the system running the Universal Command Manager.
#
-format script
-type cmd

DSPUSRPRF USRPRF(QUSER)
dspcurdir
usbmjob cmd(dsplib quser)
usbmjob cmd(dsplibl)

REXX Command Reference Example

The following command reference sends the message and the library catalog to standard output. The job logs are sent to standard error.

To invoke this cmdref on system denver, use:

ucmd -c "rexx_test" -cmd_type cmdref -u xxxx -w zzzz -i denver

In this case, the user (xxxx) has authority to call the IBM i system object QWCRJBST and rexx_test is the name of the command reference file on the IBM i.

Once again, the user, designated by the -u option, requires access to the object QWCRJBST. Without this access, usbmjob will fail.

# -- File named rexx_test in library UCVCMDREF --
# Use USBMJOB to execute the DSPLIB command.
#
-format script
-type rexx

say "Submitting job to display library qsysopr"
'usbmjob cmd(dsplib qsysopr)'