Links

CLI Overview

The Model9 Mainframe Command Line Interface (CLI) is a set of commands that perform Model9 actions directly from TSO/E or in batch operations, without dependency on the Model9 Management Server. The CLI facilitates everyday operations such as listing and restoring data sets and volumes. The CLI can be executed from the TSO/E command line for ad-hoc operations, be embedded in REXX for internal interfaces, or be executed using batch jobs for maintenance and business resumption activities.

Installation considerations

Using the CLI requires:
  • A listener that is installed as part of the agent’s installation procedure.
  • The M9CLI REXX to be concatenated to TSO.
For more information, see the Model9 installation guide.

Security considerations

  • Any user running the CLI must have an OMVS UID defined in RACF.
  • Some CLI commands require permissions:
    • ARCHIVE - UPDATE access is required for the target data set.
    • RECALL - READ access is required for the target data set.
    • BACKDSN -
      • ALTER access is required for the target data set.
      • When specifying NEWNAME: READ access is required for the backed up data set name, and UPDATE access for the target new name.
    • DELBACK - ALTER access is required for the target data set.
    • RESTDSN - ALTER access is required for the target data set, READ access is required for the source data set.
  • Additionally, Individual permissions are required per command, in the following pattern:
    Action
    Class
    Profile
    Access
    Enable a user to execute <command> from the CLI
    XFACILIT
    M9.CLI.<command>
    READ
  • Some keywords require individual permissions:
    Action
    Class
    Profile
    Access
    Enable a user to recall a data set while bypassing the ACS routines option
    XFACILIT
    M9.CLI.RECALL.BYPASSACS
    READ
    Enable a user to restore a data set while bypassing the ACS routines option
    XFACILIT
    M9.CLI.RESTDSN.BYPASSACS
    READ
    Enable a user to delete an archived data set although it has a valid date that has not expired
    XFACILIT
    M9.CLI.DELARC.PURGE
    READ
    Enable a user to archive a data set without checking whether the data set has a backup
    XFACILIT
    M9.CLI.ARCHIVE.NOBCK
    READ
    Enable a user to specify a retention period and set an expiration date while archiving a data set. The user-specified retention period overrides all other definitions, including DFSMS Management Class attributes.
    XFACILIT
    M9.CLI.ARCHIVE.RETPD
    READ
    Enable the user to specify a new data set name during data set backup
    XFACILIT
    M9.CLI.BACKDSN.NEWNAME
    READ
    Enable the user to specify a new data set backup date during data set backup
    XFACILIT
    M9.CLI.BACKDSN.NEWDATE
    READ
    Enable the user to specify a new data set backup time during data set backup
    XFACILIT
    M9.CLI.BACKDSN.NEWTIME
    READ
    Enable a user to delete a dataset backup without checking the backup's expiration date
    XFACILIT
    M9.CLI.DELBACK.PURGE
    READ
    Enable a user to delete a full volume backup without checking the backup's expiration date
    XFACILIT
    M9.CLI.DELVOL.PURGE
    READ

CLI Commands

The supported commands are shown in the following table:
Command
Description
LISTDSN
List all archives, backup copies and imported data sets that exist for the specified data set or pattern
LISTVOL
List volume full dump copies that exist for the specified volume or pattern
RESTDSN
Restore a data set from a backup copy
RESTVOL
Restore a volume from a volume full dump copy
ARCHIVE
Archive a data set
RECALL
Recall a data set from archive, allocate and recatalog it back on disk
DELARC
Delete an archived data set without recalling it first
BACKDSN
Backup a data set
DELBACK
Delete a backup created by the BACKDSN command
DELVOL
Delete a backup version of a volume

Identifying the data set / volume for the command

The LISTDSN and LISTVOL commands must include either a specific name or a pattern as a parameter. The issued command will display all the backup copies / archives / volume full dump copies that meet the criteria. The accepted pattern adheres to the z/OS ISPF conventions.
Data set name pattern
Description
Example
Selects
%
Single-character variable
SYS%.PROCLIB
SYS1.PROCLIB SYS2.PROCLIB
*
1-8 character variable
SYS2.*.PROCLIB
SYS2.DBA.PROCLIB SYS2.USER.PROCLIB
SYS2.*
SYS2.PROCLIB
SYS2.PARMLIB
SYS*.PROCLIB
SYS2.PROCLIB
SYSDB.PROCLIB
**
Any number (including zero) of 0-8 character variables
SYS2.**.PROCLIB
SYS2.PROCLIB
SYS2.DBA.PROCLIB SYS2.DBA.DEV.PROCLIB SYS2.USER.PROCLIB
SYS2.**
SYS2.PROCLIB
SYS2.PARMLIB
SYS2.DBA.PROCLIB SYS2.DBA.DEV.PROCLIB SYS2.USER.PROCLIB
SYS2.USER.LOAD
Note
When specifying a data set name without a pattern suffix such as * or **, it will be treated as a specific name and not a prefix. This is intended to simplify the CLI interface by allowing the use of data set names and volumes without quotation marks.
Volume serial pattern
Description
Example
Selects
%
Single-character variable
M%INST
M1INST
M2INST
*
**
0-8 character variable. When selecting volumes, ‘**’ behaves the same as ‘*’
M*ST
M1INST
M2INST
M2ZZST
M3ZZST
M2*
M2INST
M2ZZST
The RESTDSN and RESTVOL commands operate on a single data set / volume. The input can be a specific data set / volume name, or a pattern, as long as it matches one data set / volume. A user can use the LISTDSN / LISTVOL command to identify a data set / volume to be restored, and then change the command name to RESTDSN / RESTVOL while leaving the rest of the parameters the same in order to perform the restore. The command will be executed for the latest backup copy / archive / volume full dump copy that meets the criteria, unless specified otherwise. For these commands, further filtering is possible by using:
Option
Description
DATE
The date on which the backup copy / archive / volume full dump copy was created
DATERANGE
A range of dates on which the backup copy / archive / volume full dump copy was created
ENTRY
A positive sequential number that represents the sequence of listed backup copies / volume full dump copies in a given command - “0” being the latest, “1” being the previous, and so on. It allows selection of a backup copy / volume full dump copy other than the latest. For example, when listing using DATE, the ENTRY will list copies created on the same day, at different times of the day.
UNIQUEID
A sequence of characters, that when combined with the data set/volume name, uniquely identifies the backup copy / archive / volume full dump copy
The ARCHIVE and RECALL commands must receive a specific data set name, no further filtering is available.

Output

The command is processed synchronously and the output is redirected to STDOUT. When invoked in TSO, the output will be displayed on the screen. When invoked in a batch job, it will be redirected to a SYSPRINT DD card. If the requester of the command is not available, in the event that the job or TSO session was cancelled, the output will be printed in the executing agent's log. The exception is LISTDSN and LISTVOL outputs, which will not be printed to the agent's log as their outputs may be very large.

Return Codes

The following table lists the possible return codes from CLI commands.
RC
Description
0
The command was executed successfully.
4
The command ended with a warning / no records were selected. An appropriate message will be displayed
8
The command ended in an error. An appropriate message will be displayed.
10
Syntax error
12
A timeout occurred while the request was being processed/queued at the agent
14
No agent available - Unable to send request to agent
16
Unexpected error