Overview

There are three types of work that a z/OS Universal Command Server can execute:

1. z/OS USS commands and scripts
2. Started Tasks
3. Command References

In all cases, the work executes in its own address space with its own user identity. No Universal Agent programs share the address space with the unit of work started by the Server.

z/OS UNIX System Services Command

The UCMD Server's default command type is the z/OS USS shell. This can be customized with the COMMAND_TYPE configuration option. USS shell commands are executed in a USS process within its own address space.

A UCMD Manager requests the execution of a USS command by specifying a COMMAND_TYPE of shell. USS scripts are requested by specifying a SCRIPT_TYPE of shell.

The environmental attributes of the user process are described in the following sections.

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 z/OS user ID and a password. The user process executes with the user ID and the primary and secondary group IDs of the user. The user profile must have a properly defined OMVS segment.

• With user security inactive, the Server does not require the Manager to supply a valid user ID. The user process executes with the user ID of the Server. The Server inherits its user ID from the Broker started task, which is a superuser account (UID 0). The superuser account provides a lot of access to the operating system that a user process typically does not require. Setting security inactive is not recommended because of the level of access it permits the user process.

Working Directory

The working directory of a user process depends on whether user security is active or inactive:

• With user security active, a user process's working directory is the home directory of the user ID as defined in the user profile's OMVS segment HOME parameter value.

• With user security inactive, a user process's working directory is the working directory as defined by the Universal Broker's user profile OMVS segment HOME parameter value. All user processes executed will use the same directory. Care should be taken to avoid name clashes and other consequences of multiple processes sharing a working directory.

Command Shell

The UCMD Manager LOGIN option and the UCMD Server LOGIN option determine what command shell is used.

For non-login environments, the default is shell /bin/sh. The shell used for non-login environments is configurable with the SHELL option.

For login environments, the shell defined in the user ID's OMVS segment with the SHELL option is used. The shell environment is created as if the user logged on interactively. For example, the shell's .profile is used to initialize the environment.

The non-login environment is similar to the environment that the cron scheduler provides. User resource files, such as .profile, are not utilized.

The application scripts being executed and your local system management policies should be used to determine which method is best.

If user security is inactive, the default shell /bin/sh always is used independent of the SHELL option.

Environment Variables

Environment variables are inherited from the Universal Command Server, which in turn inherits them from the Universal Broker. If security is active, certain variables are modified to match the user environment: HOME, LOGNAME, USER, PWD, and SHELL. Their values are updated to reflect the values for the new environment.

The following variables are added if not found in the environment: HOME, USER, SHELL, and UCMDENV. The UCMDENV variable is set to a value of 1. It can be used within scripts to determine if Universal Command has invoked them.

The UCMD Manager LOGIN option and the UCMD Server LOGIN option have an impact on the environment variables defined. For login environments, the user's shell is invoked as a login shell, which, in turn, uses the shell profile file in the user's home directory. So any environment variables set in the profile file also will be defined.

If user security is inactive, no changes are made to the environment variables.

Started Tasks

The Universal Command Server has the ability to execute z/OS started tasks. Started tasks have some advantages over USS commands. They execute z/OS programs using standard JCL. The JCL must be predefined in a system procedure library.

UCMD Managers refer to the started task by name and optionally provide an input file and JCL overrides. A Manager requests the execution of a started task by specifying a COMMAND_TYPE of stc.

Started task requests are processed by the Universal Command Server Command Processor for Started Tasks (UCMSCPST). The Command Processor (CP) is executed by the Server as a USS process within its own address space.

The STC CP execution environment is the same as the USS command environment described in z/OS UNIX System Services Command.

Extended MCS Console

The started task is started with the START system command through an extended MCS console. Refer to the IBM MVS System Commands manual for a complete description of the START command.

The extended MCS console is established with the following attributes:
 

Extended MCS consoles can be protected so that only permitted users have the authority to issue commands. The RACF OPERCMDS class is used to establish user security for extended MCS consoles.

Refer to the IBM MVS Planning: Operations and the Security Server RACF Security Administrator Guide manuals for complete details.

START System Command

The UCMD Manager provides the START command parameters. The STC CP adds parameter STDIN with a value of a cataloged dynamically allocated data set that contains the standard input from the Manager.

The syntax of the START command that is generated based on options passed to UCMD is as follows:

S manager-cmd,STDIN=stdin-dataset

The manager-cmd value is the command value provided by the UCMD Manager. The stdin-dataset value is the dynamically allocated data set that contains the Manager's standard input data.

As an example, the following Manager command, executed from a Windows system:

ucmd -c "prdtask,opt=abc" -cmd_type stc -u ts0023 ...

results in a START command as follows:

S PRDTASK,OPT=ABC,STDIN=TS0023.UCM.C08AD835.STDIN

Access to UCMD Manager started task requests and the associated command value can be protected with Universal Access Control Lists. See Universal Command Server for zOS - UACL for complete details on protecting request types.

Standard Input

A Manager can provide an input file to the started task via the UCMD Manager's standard input file. The Manager's standard input file is first spooled to a cataloged data set. The fully qualified data set name is passed to the started task as JCL procedure parameter STDIN.

The dynamically allocated stdin data set is allocated with a name formatted as: hlq.UCM.C_cid_.STDIN

In this format:

• hlq - High-level qualifier is one of the following:
  • User ID with which the STC is executed.
  • Value of the configuration option STDIN_HLQ.
• cid - Component ID of the STC CP. The value is the last seven of eight digits of the component ID in a hexadecimal format.

Standard input data sets dynamically allocated by the UCMD Server are deleted after the STC completes execution.

The UCMD Server's default stdin data set attributes are set with the DEFAULT_STDIN_ALLOC configuration option. The default values are DSORG=PS, RECFM=VB, LRECL=1024, UNIT=SYSDA, SPACE=(CYL,(5,5),RLSE). The UCMD Manager, optionally, can provide data set attributes using the Manager SERVER_OPTIONS value specifying the Server STDIN_ALLOC option described below.

Instead of the Manager providing a standard input file, the Manager may provide the name of an existing data set allocated on the Server system. That is accomplished with a Manager SERVER_OPTIONS value specifying the Server STDIN_ALLOC option described below.

Standard Output and Error

The JES SYSOUT produced by the STC can be returned to the UCMD Manager as standard output and standard error. The STC JESLOG data (JESMSGLG, JESJCL, and JESYSMSG data) is returned as standard error. All step SYSOUT data is returned as standard output.

The STC CP will retrieve SYSOUT data after the STC completes execution. The SYSOUT must be spooled to the JES class specified by the UCMD Server JES_SELECT_CLAS option. Additionally, the SYSOUT data must be held. Released SYSOUT is not retrieved.

Each SYSOUT file is retrieve and written to the appropriate standard I/O file. Message UNV2435I prefixes each SYSOUT file. The message lists the ddname, step, procstep, and spool data set name of each SYSOUT file. The maximum number of records returned per SYSOUT file is controlled with the UCMD Server JES_MAX_LINES_READ configuration option.

After the SYSOUT files are retrieved, their disposition is controlled by the JES_DELETE_SPOOL_FILE and JES_SELECT_CLAS Server options.

JCL Requirements

The started task JCL can specify a job or a procedure. Job JCL must come from either the IEFJOBS or IEFPDSI ddnames of the master JCL. Procedure JCL comes from either the IEFPDSI or JES procedure libraries.

In determining on whether to use job or procedure JCL, refer to the IBM MVS JCL Reference manual for a description of the advantages and disadvantages.

The first step of the started task must execute the Universal Started Task Support program, UCMSS000. The STC Support program establishes the user ID for the address space and performs necessary communication with the STC CP.

The following figure illustrates a started task procedure JCL.

//UCMREQ   PROC
//*
//UCMSS000 EXEC PGM=UCMSS000
//STEPLIB  DD   DISP=SHR,DSN=UNV.SUNVLOAD
//STDIN    DD   DISP=SHR,DSN=&STDIN
//SYSUDUMP DD   SYSOUT=H
//*
//S1       EXEC PGM=ABC123
//SYSOUT   DD  SYSOUT=A,HOLD=YES
//SYSPRINT DD  SYSOUT=A,HOLD=YES
//SYSIN    DD  DISP=SHR,DSN=&STDIN

The JCL executes two steps:

1. The first step executes the Universal Command Started Task Support program.
2. The second step executes program ABC123. (This second step - and any subsequent steps - can be any z/OS program.)

The UCMSS000 program accepts one input parameter on the PARM keyword of the EXEC statement. The parameter SWUSR controls whether or not the address space user ID is switched or not. The format of the parameter is:

SWUSR={YES|NO}

A value of YES specifies the user ID is switched. A value of NO specifies the user ID is not switched. The default is YES.

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 are defined as PDS members. The command reference PDS is allocated to the UNVCREF ddname of the Broker started task.

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

z/OS command references can define any valid command type, such as USS shell commands and scripts and started task commands.

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

USS Command Reference Example

The following command reference executes a ucopy command to read a file.

# Command reference to read a file.
#

-format cmd
-type   shell

ucopy /opt/application/file.txt

STC Command Reference Example

The following command reference starts started task SCHEDINT.

# Command reference to scheduler interface.
#

-format cmd
-type   stc

SCHEDINT,OPT=ABC