Panel

Table of Contents

maxlevel	2

...

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.

Anchor
Functions
Functions
CLI Functions

...

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 9863189 and to log on to a Controller (User ID 9863189 and Password 9863189).

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

...

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

html-bobswift

Panel

<pre>

uagcmd

function

function

Global

Global

parameters

parameters

function

function-specific parameter(s)

</pre>

Command Line Entry	Description
uagcmd	CLI command that executes all CLI functions.
function	CLI function that performs a specific action in a Universal Controller.
Global parameters	CLI parameters (required and optional) available for all functions.
function-specific parameter(s)	CLI parameters (required and optional) specific to one or more functions.

...

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

...

Note

title	Note

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

Anchor
Special Characters Restrictions
Special Characters Restrictions
Special Characters Restrictions

...

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

...

UNIX

The CLI functions are installed in the following directory:

/CLI_HOME/bin

Replace CLI_HOME with the directory in which the Agent components are installed.

Windows

The CLI functions are installed in the following directory:

DRIVE:\CLI_HOME\bin

Replace:

DRIVE with the drive they are installed on. Add the appropriate directory for your O/S to your PATH environment variable in order to execute the functions without specifying their full path name.
CLI_HOME with the directory in which the Agent components are installed.

Note

title	Note

Do not use fully qualified file names (that is, with the .exe extension) in CLI for Windows parameters; an error will occur.

z/OS

The CLI is implemented with a single program, UAGCMDZ. UAGCMDZ (with alias OPSCMDZ) is installed in the SUNVLOAD library as part of the Universal Agent for z/OS Installation package.

See Using the CLI for z/OS 9863189 for detailed information on using the CLI in a z/OS environment.

...

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

html-bobswift

Panel

<pre>

User

<your

<your user

name>

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

</pre>

To remove the restriction, the system administrator must either:

...

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

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

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

...

Three methods are available for specifying Global parameters:

Command line switches
Configuration file entries
Environment variables

...

Description

Configuration file containing one or more Global parameters. It can include the required User ID 9863189, Password 9863189, and OMS Servers 9863189 Global parameters.

Note

title	Note

The configuration file syntax is cfggroup.cfgopt=cfgval, where cfggroup is the group to which the option belongs, cfgopt is the option name, and cfgval is the option value.

For example:

security.userid=ops.adminsecurity.password=abc123network.omsservers=7878@dallas01.acme.com,7878@dallas02.acme.comnetwork.omsnft=yesconfig.timeout=60

You also can specify individual Global parameters (required and optional) on the command line.

Note

title	Note

A sample CLI configuration file, cmdtools.props, is created during the installation of the CLI (an optionally installed component of Universal Agent). However, you can create a configuration file with any name; it must exist in the directory from where you are issuing the uagcmd command.

Platforms All

Configuration File Entry

n/a

Command Line Switch

-c

Environment Variable

n/a

Required

No

Default

(none)

Example

UNIX
- /opt/cfgopt/cfgval.pem
Windows
- c:\cfgopt\cfgval.pem
z/OS:
- -c dd:cfgval
- -c cfgval
- -c “//’cfgval’”
- -c “//’cfgval(mbr)’”
- -c “/path/to/file/cfgval”

...

Description

Complete path to a file encrypted with the Universal Encrypt utility that contains encrypted user credentials.

This file can be used to store encrypted Controller credentials that would otherwise be specified using the User ID 9863189 or Password 9863189 parameters. One or both of these parameters can be encrypted and stored in this file. Any other parameters stored in the encrypted file are ignored.

Any values specified by User ID 9863189 or Password 9863189 on the command line and/or in the Configuration File 9863189 will override values stored in this file.

Note

title	Note

Universal Encrypt is included in every Agent installation package.

Platforms All

Configuration File Entry

n/a

Command Line Switch

-x

Environment Variable

n/a

Required

No

Default

(none)

Example

UNIX

/opt/encfile/fname.enc

Windows

c:\encfile\fname.enc

z/OS

-x dd:fname
-x fname
-x “//’fname’”
-x “//’fname(mbr)’”
-x “/path/to/encfile/fname”

...

Description	Optional key that was passed to the Universal Encrypt utility when the encrypted file specified by -x was created.
Platforms	All
Configuration File Entry	n/a
Command Line Switch	-k
Environment Variable	n/a
Required	No
Default	(none)
Example

...

Note

title	Note

If this parameter is specified, all other parameters (except Help 9863189) are ignored.

Anchor
Function-Specific Parameters
Function-Specific Parameters
Function-Specific Parameters

...

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

Note
IBM’s z/OS Language Environment (LE) interprets the first forward slash (/) in a parameter string as a separator between parameters meant for LE and parameters meant for the program being executed. To avoid confusion, parameters which contain a forward slash should be enclosed in double quotes. For instance agent-type=z/OS should be agent-type=”z/OS”.

Command Line Options

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

For example:

html-bobswift

Panel

<pre>

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

</pre>

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

...

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

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

...

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

html-bobswift

Panel

<pre>

//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=*

</pre>

In this example:

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

...

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

<pre>

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

</pre>

Panel

Html bobswift

This function will return data similar to the sample below:

<pre>

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

</pre>

Panel

Html bobswift

Anchor
Issuing CLI Functions as a Batch TSO
Issuing CLI Functions as a Batch TSO
Issuing CLI Functions as a Batch TSO

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

Example One

<pre>

//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
 /*

</pre>

Panel

Html bobswift

Output will be in SYSTSPRT.

Example Two

<pre>

 //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
 /*

</pre>

Panel

Html bobswift

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

<pre>

 /**************************** 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')

</pre>

Panel

Html bobswift

Versions Compared

Old Version 5

New Version 6

Key

Anchor
Functions
Functions
CLI Functions

Anchor
Special Characters Restrictions
Special Characters Restrictions
Special Characters Restrictions

Anchor
Function-Specific Parameters
Function-Specific Parameters
Function-Specific Parameters

Command Line Options

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

Anchor
Issuing CLI Functions as a Batch TSO
Issuing CLI Functions as a Batch TSO
Issuing CLI Functions as a Batch TSO

Example One

Example Two

Page Comparison

Versions Compared

Old Version 5

New Version 6

Key

AnchorFunctionsFunctionsCLI Functions

AnchorSpecial Characters RestrictionsSpecial Characters RestrictionsSpecial Characters Restrictions

AnchorFunction-Specific ParametersFunction-Specific ParametersFunction-Specific Parameters

Command Line Options

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

AnchorIssuing CLI Functions as a Batch TSOIssuing CLI Functions as a Batch TSOIssuing CLI Functions as a Batch TSO

Example One

Example Two

Anchor
Functions
Functions
CLI Functions

Anchor
Special Characters Restrictions
Special Characters Restrictions
Special Characters Restrictions

Anchor
Function-Specific Parameters
Function-Specific Parameters
Function-Specific Parameters

Anchor
Issuing CLI Functions as a Batch TSO
Issuing CLI Functions as a Batch TSO
Issuing CLI Functions as a Batch TSO