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

Last modified 3mo ago

Action	Class	Profile	Access
Enable a user to execute <command> from the CLI	`XFACILIT`	`M9.CLI.<command>`	`READ`

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`

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

	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

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

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