Universal Command Manager for IBM i

Currently, IBM i runs Workload Automation 5.1.1.   These pages provide information for that version.

Overview

This page provides information on Universal Command (UCMD) Manager specific to the IBM i operating system.

UCMD Manager for IBM i provides an IBM i command interface to remote computers running the UCMD Server component. UCMD Manager executes remote commands as they would be if you entered the command directly on the remote command line.

On the command line, you must specify a command to execute and a remote Universal Broker. Additional input to each execution of the UCMD Manager command is made via configuration options, which control product behavior and resource allocation for that execution.

Remote standard input and output files are redirected to the UCMD Manager's standard input and output files.

Usage

UCMD Manager for IBM i executes as a CL command. This section describes the command environment, configuration and configuration options, and command line syntax.

Workload Automation 5 for IBM i Commands

The names of the Workload Automation 5 for IBM i commands that are installed in the IBM i QSYS library are tagged with the Workload Automation 5 for IBM i version / release / modification number, 511. The names of the commands installed in the Workload Automation 5 for IBM i product library, UNVPRD511, are untagged.

To maintain consistency across releases, you may prefer to use the untagged names in your production environment. The UCHGRLS (Change Release Tag) program lets you change the tagged command names in QSYS to the untagged command names in UNVPRD511.

(See UCHGRLS (Change Release Tag) Program for detailed information on UCHGRLS.)

These pages references the IBM i commands by their untagged names. If you are using commands with tagged names to run UCMD, substitute the tagged names for the untagged names in these references.

Command Execution Environment

The command is valid in all environments:

  1. Batch input streams
  2. CL programs
  3. REXX procedures
  4. CL ILE modules
  5. Interactive processing
  6. Passed to the system program QCMDEXC (or QCAEXEC) for processing

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.

UCMD Manager for IBM i configuration options are read from the following sources:

  1. STRUCM parameters
  2. Environment variables
  3. Configuration file

The order of precedence is the same as the list above; STRUCM parameters being the highest, and configuration file being the lowest. That is, options specified via STRUCM parameters override options specified via environment variables, and so on.

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

Configuration File

The configuration file, UNVPRD511/UNVCONF(UCMD), provides the simplest method of specifying configuration options whose values you do not want changed with each command invocation. These default 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.

Configuration Options

This section describes the configuration options used to execute UCMD Manager for IBM i.

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 use 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 command options.

Remote

Network address of the remote system and connection options.

Standard File

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

At the program interface level, 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_FILE_SPEC, STDIN_FILE_SPEC, or STDOUT_FILE_SPEC). The standard file options (see #Standard File Category Options) follow the standard file specification option. The STRUCM command interface hides this difference from the user.

User

User account the command executes with on the remote system.

Certificate Category Options

Option Name

Description

CA_CERTIFICATES

Location of the PEM formatted trusted CA X.509 certificates

CERTIFICATE

Location of Manager's PEM formatted X.509 certificate.

CERTIFICATE_REVOCATION_LIST

Location of Manager's PEM-formatted CRL.

PRIVATE_KEY

Location of Manager's PEM formatted RSA private key.

PRIVATE_KEY_PWD

Password for the Manager's PRIVATE_KEY.

VERIFY_HOST_NAME

Specification for whether or not the Broker's X.509 certificate host name field must be verified.

VERIFY_SERIAL_NUMBER

Specification for whether or not 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

Specification for whether or not the command runs in a login environment.

MANAGER_FAULT_TOLERANT

Specification for whether or not manager fault tolerance is used.

SCRIPT_FILE

Local script file to execute on the remote system.

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

PLF_DIRECTORY

Program Lock File (PLF) directory where the program lock files are located.

Messages Category Options

Option Name

Description

MESSAGE_LANGUAGE

Language of messages written.

MESSAGE_LEVEL

Level of messages written.

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.

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

Length of time that a 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.

Note

This option was introduced to IBM i in version 5.1.1.0.

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.

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.

ENCRYPTION_KEY

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

SERVER_OPTIONS

UCMD Server options that can be overridden by UCMD Managers.

UENCRYPTED_CODEPAGE

Character code page that Universal Command Manager uses to translate characters within a command file that has been encrypted with the Universal Encrypt utility.

Remote Category Options

Option Name

Description

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

OUTBOUND_IP

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

REMOTE_HOST

TCP/IP host name of the remote Broker.

REMOTE_PORT

TCP/IP port number of the remote Broker.

Standard File Category Options

Option Name

Description

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.

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 STRUCM parameter form of the configuration options — of UCMD Manager for IBM i.

After the positional options, which appear immediately after the STRUCM command, the options are organized by category.

STRUCM
{ CMD(command) [CMDTYPE({cmd|cmdref|rexx})] | SCRFILE(file) [SCRMBR(member)]
   [OPTIONS(options)] [SCRTYPE(type)] }
HOST(hostaddress)
[PORT(port)]
[USERID(user) [PWD(pwd)] ]

REMOTE CATEGORY:
[CONNECTTO(seconds)]
[DNSEXPAND(*option)]
[HOSTSELECT(*option)]
[HSTNMRTYCT(count)]
[MFTSAFMODE(*option)]
[OUTBOUNDIP(host)]

OPTIONS CATEGORY:
[ASSIGNPROC(*options)]
[CMDFILE(file) [CMDMBR(member)] ] | [ECMFILE(file) [ECMMBR(member)]
   [KEY(key)] ]
[ECMFILECP(codepage)]
[SERVER(options)]

COMMAND CATEGORY:
[CMDID(id)]
[EXITCDMAP(option)]
[LOGIN({yes|no})]
[MANAGERFT({yes|no})]

MESSAGES CATEGORY:
[MSGLANG(language)]
[MSGLEVEL(*{trace|audit|info|warn|error})]		NOTE: Value *trace* turns trace on.
[TRCLINES(lines)]
[TRCTBL(size,{error|always|never}) ]
[CACERTS(file [lib] ) [CACERTSMBR(member)] [VFYHSTNM({yes|no|hostname})]
   [VFYSERNUM(number)] ]
[CERT(file [lib] ) [CERTMBR(member)]
   PVTKEYF(file [lib] ) [PVTKEYFMBR(member)] [PVTKEYPWD(password)] ]
[CRLFILE(file [lib]) [CRLMBR(member)] ]

NETWORK CATEGORY:
[AUTH(*{yes|no})]
[CODEPAGE(codepage)]
[COMPRESS(*{yes|no}[CMPRSMTH*{zlib|hasp}] ) ]
[CTLCPHRLST(cipherlist)]
[DELAY(seconds)]
[DFTCPHR(cipher)]
[DTACPHRLST(cipherlist)]
[ENCRYPT(*{yes|no})]
[FRCCMPLT({yes|no})]
[JOBRTN(seconds)]
[MINSSLPROTOCOL(option)] [NETWORKFT({yes|no})] [RESTART({yes|no|auto}) [MANAGERFT({yes|no}) [CMDID(id)] ] ] [RETRYCNT(number)] [RETRYINT(seconds)] [SERFILE(output_file)] [SERMBR(member)] [SERMODE(*{text|binary})] [SERCPG(codepage)] [SERRCP(codepage)] [SINFILE(input_file)] [SINMBR(member)] [SINMODE(*{text|binary})] [SINCPG(codepage)] [SINRCP(codepage)] [SOTCPG(codepage)] [SOTFILE(output_file)] [SOTMBR(member)] [SOTMODE(*{text|binary})] [SOTRCP(codepage)] LOCAL CATEGORY: [PLFDIR(directory)] MISCELLANEOUS CATEGORY: [COMMENT(user-defined string)] STRUCM VERSION(*{yes|no})


* The command file (CMDFILE or ECMFILE) can contain some or all required and/or optional configuration options, including CMD (or SCRFILE) and HOST. If a command file is specified on the command line, and it contains the required CMD (or SCRFILE) and HOST options, those options do not have to be specified additionally on the command line.