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.
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.
- 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:ActionClassProfileAccessEnable a user to execute <command> from the CLI
XFACILIT
M9.CLI.<command>
READ
- Some keywords require individual permissions:ActionClassProfileAccessEnable 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 optionXFACILIT
M9.CLI.RESTDSN.BYPASSACS
READ
Enable a user to delete an archived data set although it has a valid date that has not expiredXFACILIT
M9.CLI.DELARC.PURGE
READ
Enable a user to archive a data set without checking whether the data set has a backupXFACILIT
M9.CLI.ARCHIVE.NOBCK
READEnable 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 backupXFACILIT
M9.CLI.BACKDSN.NEWNAME
READ
Enable the user to specify a new data set backup date during data set backupXFACILIT
M9.CLI.BACKDSN.NEWDATE
READ
Enable the user to specify a new data set backup time during data set backupXFACILIT
M9.CLI.BACKDSN.NEWTIME
READ
Enable a user to delete a dataset backup without checking the backup's expiration dateXFACILIT
M9.CLI.DELBACK.PURGE
READ
Enable a user to delete a full volume backup without checking the backup's expiration dateXFACILIT
M9.CLI.DELVOL.PURGE
READ
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 |
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.
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.
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 |