Versions Compared

Old Version 3

changes.mady.by.user IT Stonebranch

Saved on

compared with

New Version Current

changes.mady.by.user Stonebranch

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...


Panel
Table of Contents
maxlevel2

...

The Universal Controller Command Line Interface (CLI) is implemented as a set of functions that 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 function according to information specified in its required and optional Global parameters and function-specific parameters.

...

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 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 command line syntax is used for issuing the CLI command, uagcmd:
 

<pre> 
uagcmd
<i>function</i>
function
<i>Global
Global
parameters</i>
parameters
<i>function
function-specific parameter(s)
</i> </pre>
 Panel
 Html bobswift

     
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.
For example:
 
<pre>

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

</pre>
 Panel
 Html bobswift
 Html bobswift
In this example, the required Global Parameters are contained in the config.cfg configuration file.
 
...
None of these special characters identified in Special Characters Restrictions - =, |, +, and ~ - can be use in a task-variables= parameter.
...
For all supported platforms, the CLI is included in the Universal Agent 7.2.x package.
 
<ul>
<li> <code>
  • /CLI_HOME/
bin</code>
</ul>
  • bin
Replace CLI_HOME with the directory in which the Agent components are installed.
<ul>
<li> <code>DRIVE
  • DRIVE:\CLI_HOME\
bin</code>
</ul>
Replace:
<ul>
<li> <code>DRIVE</code> 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.
<li> <code>CLI_HOME</code> with the directory in which the Agent components are installed.
</ul>
  • 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.
     
UNIX
The CLI functions are installed in the following directory:
 Html bobswift
Windows
The CLI functions are installed in the following directory:
 Html bobswift
 Note
titleNote
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 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 
&lt;your
<your user 
name&gt;
name> not permitted to use the command line interface. Please check with your administrator.

</pre>
To remove the restriction, the system administrator must either:
...
 Note
titleNote
Password expiration is not applicable to LDAP authenticated users.
 Anchor
Global Parameters
Global Parameters
Global Parameters
The CLI provides the following Global parameters for use with any CLI function:
      
Parameter
Required
Optional
CA Certificate List

 (tick) 
Configuration File

 (tick) 
CRL File

 (tick) 
Encrypted File

 (tick) 
Encrypted File Key

 (tick) 
Help

 (tick) 
Message Level
 (tick) 
OMS NFT

 (tick) 
OMS Servers
 (tick) 

Password
 (tick) 

Queue Name

 (tick) 
SSL/TLS

 (tick) 
SSL/TLS Cipher List
 (tick) 
SSL/TLS Implementation
 (tick) 
SSL/TLS Minimum Protocol Version
 (tick) 
Timeout

 (tick) 
User ID
 (tick) 

Version

 (tick) 
The following information is provided below for each Global parameter:
...
     
Description
Trusted CA certificate list in PEM format. DD Name / Dataset Name / HFS File Name for z/OS; file path for other platforms.
PlatformsAll
Configuration File Entry
ssl.certstore=
Command Line Switch
-a
Environment Variable
n/a
Required
No
Default
(none)
Example
  • UNIX
    • /opt/cert/ca.pem
  • Windows
    • c:\cert\ca.pem
  • z/OS:
    • -a dd:CACERTS
    • -a CACERTS
    • -a “//’CACERTS’”
    • -a “//’CACERTS(mbr)’”
    • -a “/path/to/file/CACERTS”
 Anchor
Configuration File
Configuration File
Configuration File
     
Description
Configuration file containing one or more Global parameters. It can include the required required User ID, Password, and OMS Servers Global  Global parameters.
 Note
titleNote
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.admin
security.password=abc123
network.omsservers=7878@dallas01.acme.com,7878@dallas02.acme.com
network.omsnft=yes
config.timeout=60

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

 Note
titleNote
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.

PlatformsAll
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  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 or Password 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 or Password on the command line and/or in the Configuration File will override values stored in this file. 
 
 Note
titleNote
Universal Encrypt is  is included in every Agent installation package. 

PlatformsAll
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.
PlatformsAll
Configuration File Entry
n/a
Command Line Switch
-k
Environment Variable
n/a
Required
No
Default
(none)
Example

...
 Anchor
OMS Servers
OMS Servers
OMS Servers
<ul>
<li> 
  • PORT 
 
  •  is 
 
  •  the 
 
  •  TCP 
 
port
 on which the OMS server is listening. The OMS default port is 7878.
<li> HOST is the host name or IP address of the OMS server.
</ul>
  •  port on which the OMS server is listening. The OMS default port is 7878.
  • HOST is the host name or IP address of the OMS server.
If multiple OMS servers are specified, they must be comma-separated.
     
Description
Specifies one or more OMS server addresses used for network communication. 
 
The syntax of the value is PORT@HOST[,PORT@HOST...], where:
 Html bobswift
 Html bobswift
PlatformsAll
Configuration File Entry
network.omsservers=
Command Line Switch
-m
Environment Variable
OMSSERVERS
Required
Yes
Default

Example
network.omsservers=7878@dallas01.acme.com,7878@dallas02.acme.com
...
 Note
titleNote
If this parameter is specified, all other parameters (except Help) are ignored.
 Anchor
Function-Specific Parameters
Function-Specific Parameters
Function-Specific Parameters
Most functions contain one or more required and/or optional parameters that are specific to one or more functions.
...
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
...
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:
html-bobswift
 Panel
<pre>
 
 
Enter TSO or Workstation functions below:
 ===> uagcmdz ops-agent-status -c "//'USER.PARM(CMDOPTS)'" agent-type=windows

</pre>
This function will return data similar to the sample below:
html-bobswift
 Panel
<pre>
 
 
Agentname                       AgentType     Status
 agent-sys00101                  Windows       Active
 agent-sys00201                  Windows       Offline
 opscmd-complete

</pre>
 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
html-bobswift
 Panel
<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>
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