Universal Control Manager for zOS

Introduction

This Universal Control (UCTL) Manager information is specific to the z/OS operating system.

UCTL Manager for z/OS executes as a batch job.

Control Requests

UCTL Manager for z/OS supports all three Universal Control control requests:

  1. Start (START_CMD option)
  2. Stop (STOP_CMD option)
  3. Refresh (REFRESH_CMD option)

JCL Procedure

The following figure identifies the UCTL Manager for z/OS JCL procedure (UCTLPRC, located in the SUNVSAMP library) that is provided to simplify the execution JCL and future maintenance.


DD Statements used in JCL Procedure

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

ddname

DCB Attributes *

Mode

Description

STEPLIB

DSORG=PO,
RECFM=U

Input

Load library containing the program being executed.

UNVNLS

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

Input

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

UNVTRACE

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

Output

UCTL trace output.

SYSPRINT

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

Output

stdout file for the UCTL program. UCTL does not write any messages to SYSPRINT.

SYSOUT *

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

Output

stderr file for the UCTL program. UCTL writes its messages to SYSOUT.

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

JCL

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

Job step STEP1 executes UCTLPRC.

The configuration options are specified on the SYSIN DD.

Configuration

Configuration consists of:

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

Configuration Sources

Configuration options are read from the following sources:

  1. PARM keyword
  2. SYSIN ddname
  3. Command file ddname
  4. Configuration file

The order of precedence is the same as the list above; command line 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.

Detailed information on these methods of configuration can be found in Configuration Management.

Configuration File

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

The configuration file, provided by the local Universal Broker, provides the simplest method of specifying configuration options whose values will not change 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 UCTL Manager.

Note

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

Configuration Options Categories

The following table categorizes the configuration options used to execute Universal Control Manager for z/OS 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

Command

Control command to execute.

Remote

Network address of the remote system.

User

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

Certificates

X.509 certificate related options.

Events

Options used to define event generation.

Local

Options required for local broker registration.

Messages

Universal Control message options.

Network

Options used to control the process of network data.

Options

Alternative methods to specify command options.

Miscellaneous

Options use to display command help and program versions.

The UCTL Manager configuration options for each category are summarized in the following tables.

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

Location of Manager's PEM-formatted CRL.

PRIVATE_KEY

ddname of Manager's PEM-formatted RSA private key.

PRIVATE_KEY_PWD

Password for the Manager's PRIVATE_KEY.

SSL_IMPLEMENTATION

SSL/TLS implementation to be used for network communications

VERIFY_HOST_NAME

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

VERIFY_SERIAL_NUMBER

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

Command Category Options

Option Name

Description

COMMAND_ID

Identity of the started component.

REFRESH_CMD

Instruction to a Broker to refresh configuration data.

START_CMD

Instruction to a Broker to start a component.

STOP_CMD

Instruction to stop a component being executed by a Broker.

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

Miscellaneous Category Options

Option Name

Description

HELP

Write command option help.

VERSION

Write program version.

Network Category Options

Option Name

Description

CODE_PAGE

Code page used to translate text data to and from the network.

CTL_SSL_CIPHER_LIST

SSL/TLS cipher list for the control session.

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.

Options Category Options

Option Name

Description

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.

Remote Category Options

Option Name

Description

HOSTNAME_RETRY_COUNT

Number of host connection attempts before ending with an error.

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.

User Category Options

Option Name

Description

USER_ID

User ID or account with which to execute the Control 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 Universal Control Manager for z/OS.

uctl
{ -start compname [-cmdid id] | -stop compID [-userid user [-pwd password] ] |
-refresh [compname] }
-host hostaddress
[-file ddname | -encryptedfile ddname [-key key] ] *
[-port port]
[-cmdid id]
[-hostname_retry_count count]
[-outboundip host]
[-ssl_implementation {openssl | system}
[-system_id ID]
[-lang language]
[-level {trace|audit|info|warn|error}]
[-msg_suppression_list list ]
[-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]
[-codepage codepage]
[-ctl_ssl_cipher_list cipherlist]
[-min_ssl_protocol option]
[-delay seconds]

uctl
{ -help | -version }


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