Introduction

The Universal Controller Command Line Interface (CLI) is implemented as a set of functions that perform specific actions in a Universal Controller. The results of the actions are written to the CLI standard output.

The CLI command, uagcmd, executes a function according to information specified in its required and optional Global parameters and function-specific parameters.

CLI Functions

CLI functions perform specific actions in a Universal Controller.

The CLI command, uagcmd, can execute functions on any system that has TCP/IP connectivity to the Universal Message Service (OMS).

The command line syntax for each execution of uagcmd must specify a single CLI function, required / optional Global parameters, and required / optional function-specific parameters. You must use the required Global parameters to connect to OMS Servers and to log on to a Controller (User ID and Password).

(See Pre-6.2.0.0 CLI Functions for a backward-compatible version of this syntax that can be used for pre-6.2.0.0 CLI functions.)

The following information is provided for each CLI Function:

• Description
• Command line syntax
• Function-specific parameters
• Example

Functions are listed alphabetically, by category, on the following pages:

Command Line Syntax

The following command line syntax is used for issuing the CLI command, uagcmd:
 

uagcmd function Global parameters function-specific parameter(s)

For example:
 

uagcmd ops-task-launch -c config.cfg -x encryptedfile.txt task-type=unix task-name=task01

In this example, the required Global Parameters are contained in the config.cfg configuration file.
 

Special Characters Restrictions

The following restrictions apply to the use of special characters in CLI function parameters.

Restrictions for task-variables= Parameter

None of these special characters identified in Special Characters Restrictions - =, |, +, and ~ - can be use in a task-variables= parameter.

Examples

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V=1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V|1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V+1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V~1" variable2=V2}
Parameter CMDVERB contains malformed name/value pair(s).
opscmd-complete

Pre-6.2.0.0 CLI Functions

For backward-compatibility, you can exclude uagcmd from the command line for all pre-6.2.0.0 CLI functions:
 

Return Codes

The following table identifies all return codes that can be returned in response to a function:

Supported Platforms

For all supported platforms, the CLI is included in the Universal Agent 7.2.x package.
 

CLI Login

User Restriction

You can be restricted from logging in to the CLI either of two ways:

1. The system level default for CLI access, specified by the System Default Command Line Access Universal Controller system property, has been set to No, and the Command Line Access field in the User Details for your user account is set to -- System Default --."
2. The Command Line Access field in the User Details for your user account is set to No, which overrides the System Default Command Line Access value.

If either restriction is in place, the following error message will display when you issue a CLI command:

User <your user name> not permitted to use the command line interface. Please check with your administrator.

To remove the restriction, the system administrator must either:

• Set the System Default Command Line Access property to Yes and set the Command Line access field on the User Definition screen for your user account to -- System Default --.
• Set the Command Line access field on the User Definition screen for your user account to Yes.

Password Expiration

While a password is expired, CLI access will be prohibited until the password has been changed.

Global Parameters

The CLI provides the following Global parameters for use with any CLI function:

Parameter	Required	Optional
CA Certificate List
Configuration File
CRL File
Encrypted File
Encrypted File Key
Help
Message Level
OMS NFT
OMS Servers
Password
Queue Name
SSL/TLS
SSL/TLS Cipher List
SSL/TLS 1.3 Cipher Suites
SSL/TLS Implementation
SSL/TLS Minimum Protocol Version
SSL/TLS Maximum Protocol Version
Timeout
User ID
Version

The following information is provided below for each Global parameter:

• Description
• Syntax for specifying the parameter.
• Requirement to use the parameter.
• Default value (if any).
• Example
   

Specifying Global Parameters

Three methods are available for specifying Global parameters:

1. Command line switches
2. Configuration file entries
3. Environment variables

CA Certificate List

Configuration File

CRL File

Encrypted File

Encrypted File Key

Help

Message Level

OMS NFT

OMS Servers

Password

Queue Name

SSL/TLS

SSL/TLS Cipher List

SSL/TLS 1.3 Cipher Suites

SSL/TLS Implementation

SSL/TLS Minimum Protocol Version

SSL/TLS Maximum Protocol Version

Timeout

User ID

Version

Function-Specific Parameters

Most functions contain one or more required and/or optional parameters that are specific to one or more functions.

Modifying Variables

Some function-specific parameters let you modify variables.

Currently, the CLI only supports the modification of User-Defined Variables: global variables, trigger variables, and task/workflow variables.

Modifying a task variable does not impact any existing task instances of that task. When the next task instance is created from the updated task, the new task instance will use the updated variable.

To modify a variable in a task or workflow, you can create a Set Variable action.

Using the CLI for z/OS

All CLI functions are supported in the z/OS environment. They are managed and executed by the program UAGCMDZ (with alias OPSCMDZ), which may execute as either a command processor or a standard z/OS batch job. UAGCMDZ is installed with the z/OS agent in library SUNVLOAD.

z/OS-Specific Syntax Requirements

The functions and syntax requirements for the z/OS environment are very similar to the other supported platforms with a few exceptions described below.

Command Line Options

When UAGCMDZ is executed as a batch program, command line parameters are specified with the step PARM keyword.

For example:

 //STEP01   EXEC PGM=UAGCMDZ,
 //  PARM='ops-agent-status -c dd:CMDOPTS agent-type=windows'

Syntax for Options That Accept File Names: -a, -c, -e, and -x

If you use the -a, -c, -e, and -x command line switches for specifying a file on the command line, you must use one of the following formats for the file name.

For example, for the -c (Configuration File) command line switch:

Line Numbers in Configuration File

Do not place line numbers in columns 73-80. The entire 80-byte record is read and processed as input.

Methods for Issuing CLI Functions in z/OS

Three methods are available for running UAGCMDZ and executing CLI functions:

• Using a batch job.
• Under a TSO session.
• Using a batch TSO Terminal Monitor Program (TMP).

In each example where data sets are specified, we use:

Running OCLI Functions in a Batch Job

The CLI program UAGCMDZ executes a single function as a JCL batch job step. If multiple functions are to be executed, run each one as an individual job step.

The following example illustrates running UAGCMDZ as a batch job to request the status of all Windows Agents.

 //jobname  JOB (acctg-info),'your name',MSGCLASS=X,MSGLEVEL=(1,1),
 //             CLASS=A,NOTIFY=&SYSUID
 //*
 //STEP01   EXEC PGM=UAGCMDZ,
 // PARM='ops-agent-status -c dd:CMDOPTS agent-type=windows'
 //STEPLIB  DD DISP=SHR,DSN=UNV.SUNVLOAD
 //SYSPRINT DD SYSOUT=*
 //SYSOUT   DD SYSOUT=*
 //CMDOPTS  DD DSN=USER.PARM(CMDOPTS),DISP=SHR
 //CEEDUMP  DD SYSOUT=*

In this example:

The step PARM value specifies the CLI function and its options.

The job step can include only one function.

The STEPLIB points to the z/OS Agent load library.

The output will be in SYSPRINT.

CMDOPTS is a DDNAME that references the location of the function parameters.

Issuing CLI Functions under TSO

You can also issue CLI functions under a TSO session.

The sample command string below shows a CLI function issued from an ISPF Command Shell prompt:

 Enter TSO or Workstation functions below:
 ===> uagcmdz ops-agent-status -c "//'USER.PARM(CMDOPTS)'" agent-type=windows

This function will return data similar to the sample below:

 Agentname                       AgentType     Status
 agent-sys00101                  Windows       Active
 agent-sys00201                  Windows       Offline
 opscmd-complete

Issuing CLI Functions as a Batch TSO

The following two examples show how to issue a CLI function in a batch TSO.

Example One

//CMDZBAT  JOB (acctg-info),'your name',MSGCLASS=X,MSGLEVEL=(1,1),
 //             CLASS=A,NOTIFY=&SYSUID,TIME=5
 //*
 //STEP01   EXEC PGM=IKJEFT01,DYNAMNBR=200,REGION=40M
 //STEPLIB  DD DISP=SHR,DSN=UNV.SUNVLOAD
 //SYSPRINT DD SYSOUT=*
 //SYSOUT   DD SYSOUT=*
 //SYSTSPRT DD SYSOUT=*
 //CMDOPTS  DD DSN=USER.PARM(CMDOPTS),DISP=SHR
 //SYSTSIN DD *
 uagcmdz ops-agent-status -c dd:CMDOPTS agent-type=windows
 /*

Output will be in SYSTSPRT.

Example Two

 //REXXAGNT JOB (acctg-info),'your name',MSGCLASS=X,MSGLEVEL=(1,1),
 //             CLASS=A,NOTIFY=&SYSUID,TIME=5
 //*
 //STEP01   EXEC PGM=IKJEFT01,DYNAMNBR=200,REGION=40M
 //STEPLIB  DD DISP=SHR,DSN=UNV.SUNVLOAD
 //SYSEXEC  DD DSN=USER.REXX,DISP=SHR
 //SYSPRINT DD SYSOUT=*
 //SYSTSPRT DD SYSOUT=*
 //CMDOPTS  DD DSN=USER.PARM(CMDOPTS),DISP=SHR
 //SYSTSIN DD *
   %OUTTRAP1
 /*

The following REXX EXEC must be located in USER.REXX(OUTTRAP1):

 /**************************** REXX *********************************/
 /* Using OUTTRAP to                                                */
 /*         (1) Obtain z/OS agent status                            */
 /*         (2) Test status from the response               */
 /*         (3) Launch a task if the agent status is Active         */
 /*******************************************************************/
 x = OUTTRAP('OPS.')
  uagcmdz "ops-agent-status -c dd:CMDOPTS agent-type=""z/OS"""
 SAY 'RC is:' RC
 SAY OPS.0 'records were read.'
 launch = 'NO'
 DO i = 1 to OPS.0 WHILE launch = 'NO'
  IF SUBSTR(OPS.i,61,6) = 'Active' THEN
   DO
    launch = 'YES'
    uagcmdz "ops-task-launch -c dd:CMDOPTS task-name=DUMPT"
   END
 END
 DO i = 1 to OPS.0
   SAY OPS.i
 END
 y = OUTTRAP('OFF')