Universal Command Manager for z/OS

Overview

This page provides information on Universal Command (UCMD) Manager specific to the z/OS operating system.

UCMD Manager executes commands on any computer running the UCMD Server component.

You indicate to the UCMD Manager what command(s) to execute and how the standard input and output and error data should be processed. The UCMD Manager connects to the UCMD Server and processes your request.

The z/OS Batch Manager provides a batch job interface to remote computers running the UCMD Server component. The UCMD Manager executes remote commands as they would be if you entered them directly on the remote command line. Standard input and output and error files are supplied using JCL DD statements.

UCMD Manager registers with a locally running Universal Broker. Consequentially, a Universal Broker must be running in order for a UCMD Manager to execute.

Usage

UCMD Manager for z/OS executes as a batch job. It consists of:

  • Batch JCL
  • Configuration options

This section describes the JCL, configuration and configuration options, and command line syntax of UCMD Manager for z/OS.

JCL Procedure

The following figure illustrates the UCMD Manager for z/OS JCL procedure (UCMDPRC, located in the SUNVSAMP library) that is provided with the Universal Agent for z/OS installation to simplify the execution JCL and future maintenance.


//UCMDPRC  PROC UPARM=,               -- UCMD options
//             STDOUT='SYSOUT=*',     -- stdout of remote command
//             STDERR='SYSOUT=*',     -- stderr of remote command
//             STDIN='DUMMY',         -- stdin of remote command
//             UCMDPRE=#SHLQ.UNV
//*
//PS1      EXEC PGM=UCMD,PARM='ENVAR(TZ=EST5EDT)/&UPARM'
//STEPLIB  DD  DISP=SHR,DSN=&UCMDPRE..SUNVLOAD
//*
//UNVNLS   DD  DISP=SHR,DSN=&UCMDPRE..SUNVNLS
//UNVTRACE DD  SYSOUT=*
//*
//UNVOUT   DD  &STDOUT                         -- Remote stdout
//UNVERR   DD  &STDERR                         -- Remote stderr
//UNVIN    DD  &STDIN                          -- Remote stdin
//\*
//SYSPRINT DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//CEEDUMP  DD  SYSOUT=*


The procedure provides the parameters STDIN, STDOUT, and STDERR to specify the stdin, stdout, and stderr files, respectively, of the remote command.

The UPARM parameter is used to specify EXEC PARM keyword values for the UCMD program. The PARM values to the left of the slash ( / ) character are IBM Language Environment parameters.

For information regarding the Time Zone (TZ) environment variable, see z/OS Installation - Time Zone Environment Variable.

The UCMDPRE parameter specifies the data set name prefix of Universal Agent installation data sets.

DD Statements Used in JCL Procedure

The following table describes the DD statements used in the UCMD Manager for z/OS JCL procedure, above.

ddname

DCB Attributes *

Mode

Description

STEPLIB

DSORG=PO,
RECFM=U

input

Universal Agent load library containing the program being executed.

UNVNLS

DSORG=PO,
RECFM=(F, FB, V, VB)

input

Universal Agent national language support library. Contains message catalogs and code page translation tables.

UNVTRACE

DSORG=PS,
RECFM=(F, FB, V, VB)

output

UCMD trace output.

UNVOUT

DSORG=PS,
RECFM=(F, FB, V, VB)

output

Remote command's stdout file. When the remote command writes to its stdout file, this is the file to which it writes.

UNVERR

DSORG=PS,
RECFM=(F, FB, V, VB)

output

Remote command's stderr file. When the remote command writes to its stderr file, this is the file to which it writes.

UNVIN

DSORG=PS,
RECFM=(F, FB, V, VB)

input

Remote command's stdin file. When the remote command reads from its stdin file, this is the file from which it reads.

SYSPRINT

DSORG=PS,
RECFM=(F, FB, V, VB)

output

Standard output file for the UCMD program. UCMD does not write any messages to SYSPRINT.

SYSOUT

DSORG=PS,
RECFM=(F, FB, V, VB)

output

Standard error file for the UCMD program. UCMD writes its messages to SYSOUT.

* The C runtime library determines the default DCB attributes. See the IBM manual OS/390 C/C++ Programming Guide for details on default DCB attributes for stream I/O.

DD Statement Categories

UCMD Manager DD statements are organized into the following categories:

Category

DD Statements

Runtime specifications

STEPLIB and UNVNLS.

Remote command standard files (stdin, stdout, and stderr)

UNVIN, UNVOUT, and UNVERR.

UCMD message and command files (stdin, stdout, and stderr)

SYSPRINT, SYSOUT, and UNVTRACE.

Command files

User-defined DD statements to which Universal Command commands refer.

UNVIN Concatenation Requirements

Sequential data sets can be concatenated on the UNVIN ddname. When the UNVIN ddname is open, it is treated as a single data set with the following attributes:

  1. The RECFM of the first data set in the concatenation.
  2. The LRECL of the first data set in the concatenation.
  3. The BLKSIZE of the largest block size in the concatenation.

IBM does not support concatenating data sets with differing RECFM values or LRECL values larger then the first data set in the concatenation. Unpredictable results, including ABENDs, may occur when these rules are not followed.

IBM documents concatenation rules in the IBM C/C++ Programming Guide.

JCL

The following figure illustrates the UCMD Manager for z/OS JCL using the UCMDPRC JCL procedure, above.


//jobname  JOB CLASS=A,MSGCLASS=X
//STEP1    EXEC UCMDPRC,
//         STDOUT='DISP=SHR,DSN=my.local.file'
//SYSIN    DD  *
 -cmd 'ucopy file' -host dallas -userid joe -pwd akkSdiq
\*


Job step STEP1 executes the procedure UCMDPRC with the STDOUT parameter set to a value that allocates a local file.

The command options are specified on the SYSIN DD.

Configuration

Configuration consists of:

  • Setting default options and preferences for all executions of UCMD Manager.
  • Setting options and preferences for a single execution of UCMD Manager.

These configuration options are read from the following sources:

  1. PARM keyword (command line)
  2. SYSIN ddname (command line)
  3. Command file ddname
  4. Configuration file

The order of precedence is the same as the list above; PARM keyword options being the highest and configuration file being the lowest. That is, options specified via a PARM keyword override options specified via a SYSIN ddname, and so on.

For detailed information on these methods of configuration, see Configuration Management.

Configuration File

The configuration file provides the simplest method of specifying default configuration options whose values you do not want changed with each command invocation. These values are used if the options are not read from one or more other sources.

Some options only can be specified in the configuration file; they have no corresponding command line equivalent. Other options cannot be specified in the configuration file; they must be specified via one or more other sources for a single execution of UCMD Manager.

The configuration file is provided to the UCMD Manager by the local Universal Broker with which it registers. The UCMD Manager configuration file is located in the UCMCFG00 member of the PDSE allocated to the UNVCONF ddname in the Universal Broker started task.

Note

For any changes to the UCMD Manager configuration file to become active, a Universal Broker refresh is required, or the Universal Broker started task must be restarted.

Configuration Options

This section describes the configuration options used to execute UCMD Manager for z/OS.

Configuration Options Categories

The following table categorizes the configuration options into logical areas of application. Each Category name is a link to a table of options in that category. Each Option Name in those tables is a link to detailed information about that option.

Category

Description

Certificates

X.509 certificate-related options.

Command

Command or script to execute on the remote system. If a script is being executed, the script may reside on the local host on which the Manager is running or the remote host on which the Server is running.

It also includes options to control the process environment in which the command executes.

Events

Options used to define event generation.

Local

Options required for local Broker registration.

Messages

Universal Command message options.

Miscellaneous

Options used to display command help and program versions.

Network

Processing options for all the data transferred between the remote and local systems.

Options

Alternative methods to specify configuration options.

Remote

Network address of the remote system and connection options.

Spool

Options that control whether or not the Manager spools its standard files and how they are processed.

Standard File

Processing options for the standard files transferred between the remote and local systems.

The STDFILE options are specified differently then the other options. There are three types of standard files: stdin, stdout, and stderr. Each standard file can have a different set of options applied. In order to distinguish between the standard files, the options must start with a standard file specification option (STDERR_SPEC, STDIN_SPEC, or STDOUT_SPEC). The standard file options (names starting with SIO_) follow the standard file specification option.

User

User account that the command executes with on the remote system.

Certificate Category Options

Option Name

Description

CA_CERTIFICATES

ddname of the PEM-formatted trusted CA X.509 certificates.

CERTIFICATE

ddname of Manager's PEM-formatted X.509 certificate.

CERTIFICATE_EXPIRATION_NOTICE

Number of days prior to certificate expiration to begin issuing informational messages about the expiration.

CERTIFICATE_REVOCATION_LIST

ddname of the PEM-formatted CRL.

PRIVATE_KEY

ddname of Manager's PEM formatted RSA private key.

PRIVATE_KEY_PWD

Password for the Manager's PRIVATE_KEY.

SAF_KEY_RING

SAF certificate key ring name.

SAF_KEY_RING_LABEL

SAF key ring certificate label.

SSL_IMPLEMENTATION

SSL/TLS implementation.

VERIFY_HOST_NAME

Specifies that the Broker's X.509 certificate host name field must be verified.

VERIFY_SERIAL_NUMBER

Specifies that the Broker's X.509 certificate serial number field must be verified.

Command Category Options

Option Name

Description

COMMAND

Remote command to execute.

COMMAND_ID

Unique command ID associated the unit of work.

COMMAND_TYPE

Type of command specified with option COMMAND.

EXIT_CODE_MAP

Allows exit codes from the user process executed by UCMD Server to be translated (mapped) to a corresponding exit code for UCMD Manager.

LOGIN

Specifies whether or not the command runs in a login environment.

MANAGER_FAULT_TOLERANT

Specification for whether or not the manager fault tolerant feature is used.

SCRIPT_FILE

Local script file to execute on the remote system.

SCRIPT_LINE_IGNORE_MASK

Regular expression that is matched against each line of the script being sent to the remote system. Any line that matches the mask will be ignored and not sent to the remote system as part of the script.

SCRIPT_OPTIONS

Command line options passed to the script file.

SCRIPT_TYPE

Type of script file specified by option SCRIPT_FILE.

Events Category Options

Option Name

Description

ACTIVITY_MONITORING

Specification for whether or not product activity monitoring events are generated.

EVENT_GENERATION

Events to be generated as persistent events.

Local Category Options

Option Name

Description

SYSTEM_ID

Local Universal Broker with which the UCMD Manager must register.

Messages Category Options

Option Name

Description

MESSAGE_LANGUAGE

Language of messages written.

MESSAGE_LEVEL

Level of messages written.

MSG_SUPPRESSION_LIST

List of message IDs representing Universal messages to be suppressed.

TRACE_FILE_LINES

Maximum number of lines written to a trace file before it wraps around.

TRACE_TABLE

Memory trace table specification.

Miscellaneous Category Options

Option Name

Description

COMMENT

User-defined string.

HELP

Write command option help.

VERSION

Write program version.

Network Category Options

Option Name

Description

CODE_PAGE

Code page used for text translation.

CTL_SSL_CIPHER_LIST

SSL/TLS cipher list for the control session.

DATA_AUTHENTICATION

Specification for whether or not data integrity checks are performed on all standard I/O files.

DATA_COMPRESSION

Specification for whether or not data is compressed on all standard I/O files.

DATA_ENCRYPTION

Specification for whether or not data is encrypted on all standard I/O files.

DATA_SSL_CIPHER_LIST

SSL/TLS cipher list for the data sessions.

DEFAULT_CIPHER

Default SSL/TLS cipher used for data sessions.

FORCE_COMPLETE

Forces a manager fault tolerant server in a PENDING communication state to COMPLETED state without retrieving the spooled data.

JOB_RETENTION

Specifies how long a restartable Server waits for a reconnect after the user process completes.

MIN_SSL_PROTOCOL

Minimum SSL/TLS protocol level that will be negotiated and used for communications channels.

NETWORK_DELAY

Maximum number of seconds considered acceptable to wait for data communications.

NETWORK_FAULT_TOLERANT

Specification for whether or not the network fault tolerant protocol is used.

RECONNECT_RETRY_COUNT

Maximum number of network fault tolerant reconnect attempts.

RECONNECT_RETRY_INTERVAL

Number of seconds between network fault tolerant reconnect attempts.

RESTART

Specification for whether or not the manager is requesting restart.

SERVER_STOP_CONDITIONS

Exit codes that cause Universal Broker to cancel the corresponding UCMD Server of the exited UCMD Manager.

Options Category Options

Option Name

Description

ASSIGN_PROCESS_TO_JOB

Specification for whether or not UCMD Server assigns child processes to a single Windows job object.

COMMAND_FILE_ENCRYPTED

Encrypted command file.

COMMAND_FILE_PLAIN

Plain text command file.

ELEVATE_USER_TOKEN

Overrides the UCMD Server ELEVATE_USER_TOKEN configuration option that determines whether a Windows process executes with highest available privileges. This option allows a process to obtain a user access token that is not subject to User Account Control (UAC) restrictions.

ENCRYPTION_KEY

Encryption key used to decrypt an encrypted command file specified by option COMMAND_FILE_ENCRYPTED.

SERVER_OPTIONS

Universal Command Server options that can be overridden by Managers.

UENCRYPTED_CODEPAGE

Character code page to be used when translating characters found within the encrypted command file.

Remote Category Options

Option Name

Description

CONNECT_RETRY_COUNT

Number of times that a UCMD Manager will attempt to establish a connection with a remote Universal Broker.

CONNECT_RETRY_INTERVAL

Number of seconds between failed attempts to establish a connection with a remote Universal Broker.

CONNECT_TIMEOUT

Amount of time that a UCMD Manager will wait for a connection to a remote Universal Broker to complete.

DNS_EXPAND

Number of IP addresses returned to UCMD Manager following a DNS query issued to resolve a host name.

HOST_SELECTION

Host in the REMOTE_HOST list that the UCMD Manager will choose to begin its attempts to connect to a remote Universal Broker.

HOSTNAME_RETRY_COUNT

Number of times that UCMD will attempt to resolve the host name of a specified Universal Broker before it ends with a connect error.

MFT_SAFE_MODE

Situations in which more than one host may be specified in the REMOTE_HOST list when manager fault tolerance (MFT) is enabled.

MSG_SUPPRESSION_LIST

List of message IDs representing Universal messages to be suppressed.

OUTBOUND_IP

Host or IP address to use for all outgoing IP connections.

REMOTE_HOST

List of one or more hosts upon which a command may run.

REMOTE_PORT

TCP/IP port number of the remote Broker.

Standard File Category Options

Option Name

Description

SIO_DATA_AUTHENTICATION

Specifies if data integrity checks are performed on a standard file.

SIO_DATA_COMPRESSION

Specifies if and how data is compressed on a standard file.

SIO_DATA_ENCRYPTION

Specifies if data is encrypted on a standard file.

SIO_LOCAL_CODE_PAGE

Code page used for local text translation on a standard file.

SIO_LOCAL_FILE

Local file used for a standard file instead of the default.

SIO_MODE

Translation mode of a standard file.

SIO_REMOTE_CODE_PAGE

Code page used for remote text translation on a standard file.

SIO_TRAILING_SPACES

Read trailing spaces of z/OS fixed format records.

STDERR_FILE_SPEC

Start of standard error file specification options.

STDIN_FILE_SPEC

Start of standard input file specification options.

STDOUT_FILE_SPEC

Start of standard output file specification options.

User Category Options

Option Name

Description

USER_ID

User ID or account with which to execute the remote command.

USER_PASSWORD

Password associated with USER_ID.

Command Line Syntax

The following figure illustrates the command line syntax — using the command line, long form of the configuration options — of UCMD Manager for z/OS.


ucmd
{ -cmd command [-cmd_type {cmdref|shell|stc} ] | -script ddname
  [-options options] [-script_type type] [-script_line_ignore_mask mask] }
[-host hostlist
[-connect_retry_count number]
[-connect_retry_interval seconds]
[-connect_timeout seconds]
[-dns_expand {yes|no} ]
[-host_selection {sequential|random} ]
[-mft_safe_mode {yes|no} ]
[-file ddname | -encryptedfile ddname [-key key] ]  *
[-port port]
[-system_id ID]
[-userid user [-pwd pwd] ]
[-hostname_retry_count count]
[-outboundip host]
[-server options]
[-uencrypted_codepage codepage]
[-elevate_user_token {yes|no} ]
[-assign_process_to_job option]
[-managerft {yes|no} ]
[-cmdid id]
[-login {yes|no} ]
[-lang language ]
[-level {trace|audit|info|warn|error}[,{time|notime} ]
[-msg_suppression_list list ]
[-tracefilelines lines]
[-trace_table size,{error|always|never} ]
[-ssl_implementation {openssl|system} ]
[-ca_certs ddname [-verify_host_name {yes|no|hostname} ] 
   [-verify_serial_number number] ]
[-cert ddname -private_key ddname [-private_key_pwd password] ]
[-days number]
[-crl ddname]
[-saf_key_ring name [-saf_key_ring_label label] ]
[-ctl_ssl_cipher_list cipherlist]
[-data_ssl_cipher_list cipherlist]
[-default_cipher cipher]
[-forcecomplete {yes|no} ]
[-job_retention seconds]
[-delay seconds]
[-min_ssl_protocol option]
[-networkft {yes|no} ]
[-retry_count number]
[-retry_interval seconds]
[-restart {yes|no|auto} [-managerft {yes|no} [-cmdid id] ] ]
[-server_stop_conditions codes]
[-codepage codepage]
[-compress {yes|no}[,{zlib|hasp} ] ]
[-encrypt {yes|no} ]
[-authenticate {yes|no} ]
[-stdin | -stdout | -stderr]
   [-codepage codepage]
   [-compress {yes|no}[,{zlib|hasp} ] ]
   [-encrypt {yes|no} ]
   [-authenticate {yes|no} ]
   [-localfile ddname]
   [-mode {text|binary}[,{ucs|direct} ] [-trailingspaces {yes|no} ] ]
   [-remotecodepage codepage]
[-exit_code_map map]
[-comment text]

ucmd
{ -help | -version }

* The command file (-file or -encryptedfile) can contain some or all required and/or optional configuration options, including -cmd (or -script) and -host. If a command file is specified on the command line, and it contains the required -cmd (or -script) and -host options, those options do not have to be specified additionally on the command line.

Shutdown Procedure

When the UCMD Manager and UCMD Server are configured to use the network fault tolerant protocol, the z/OS Manager must be shut down properly in order for the UCMD Server and user command to shut down as well. If not properly shut down, the UCMD Server will wait for a period of time for the UCMD Manager to reestablish network connections.

If the UCMD Manager and UCMD Server are not configured to use the network fault tolerant protocol, the z/OS Manager can be shut down with any available method.

Fault Tolerant Shutdown

The z/OS Manager is a z/OS UNIX System Services (USS) application. A shutdown sequence is initiated by sending a USS termination signal to the job. The UCMD Manager detects the signal and promptly sends a terminate message to the UCMD Server. Upon receiving the terminate message, the UCMD Server starts its shutdown sequence.

A termination signal is sent to a z/OS Manager, as shown in the following steps:

Step 1

For the z/OS Manager job to be shut down, obtain its USS process identifier (PID). The PID of a job is displayed with the DISPLAY OMVS console command:
 

 
(userid is the user identifier with which the batch job executes.)
 
If you do not know the user identifier, all USS work can be displayed with the following command:
 

 
The batch job's name and address space identifier are listed. Find the job name and address space identifier of the job to be terminated and obtain its process identifier from the PID column.

Step 2

Send a termination signal to the process identifier with the MODIFY BPXOINIT command:
 

 
(pid is the process identifier obtained from Step 1.)

Non-Fault Tolerant Shutdown

Since the UCMD Server shutdown sequence is started as soon as a network connection is prematurely closed, the z/OS Manager shutdown can be initiated with any available z/OS job termination method.

The most common and safest method is the CANCEL console command:

(jobname is the name of the z/OS Manager batch job to terminate.)