Cloud Data Manager

CLI Overview

The Model9 MF 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

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

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