ARCHIVE

#### Search Results

Search

# ARCHIVE

File | 211
Op-Sys | BS2000 Note Support for z/VSE is deprecated. Support for BS2000 is also deprecated, except in conjunction with the ESM adapter. Features that are z/VSE and BS2000 specific will be removed from future releases.
Statement | `PROCESS`
Task | Run `ARCHIVE` utility.

Note
Due to performance considerations, this view should be used in single-user mode only.

## Common Fields for all Operating Systems

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`ERROR-CODE` | N3 |  |  |
`ERROR-TEXT` | A58 |  |  |
`NODE` | N5 |  | D |
`NODE-NAME` | A16 |  | D |
`SYSTEM-MESSAGE-CODE` | A10 |  |  |
`SYSTEM-CODE` | B2 |  |  |
`FUNCTION` | A8 |  | D |
`NOW` | A5 |  | D |
`DIRECTORY` | A54 |  | D |
`NEW-DIRECTORY` | A3 |  | D |
`CAT-ONLY` | A3 |  | D |
`ERASE` | A7 |  | D |
`SHARE` | A3 |  | D |
`LIST` | A10 |  | D |
`PASSWORD-ARRAY` | A8 | M/10 | D |
`SAVE-PASSWORD` | A8 |  | D |
`DRIVES` | N2 |  | D |
`DEVICE` | A8 |  | D |
`SAVE-DIRECTORY` | A3 |  | D |
`DAYS-UNUSED` | N5 |  | D |
`SAVE-ID` | A15 |  | D |
`CONTINUE-VOLSER-ARRAY` | A6 | M/5 | D |
`VOLSER-ARRAY` | A6 | M/10 | D |
`TAPES` | A8 |  | D |
`RETENTION-PERIOD` | N5 |  | D |
`CHANGED` | A12 |  | D |
`BACKUP-TYPE` | A1 |  | D |
`FILE-ARRAY` | A61 | M/20 | D |
`JOB-VARIABLE-ARRAY` | A61 | M/20 | D |
`EXCEPT-FILE-ARRAY` | A61 | M/20 | D |
`EXCEPT-JOB-VARIABLE-ARRAY` | A61 | M/20 | D |
`CONTINUE` | A13 |  | D |
`REPLACE` | A4 |  | D |
`SPACE` | A5 |  | D |
`FROM-OPTION` | A24 |  | D |
`SV-OPTION` | A100 |  | D |
`INQUIRE-POOL-OPTION` | A14 |  | D |
`POOL-OPERATION` | A6 |  | D |
`FORCE-PURGE` | A3 |  | D |
`STATUS-TYPE` | A6 |  | D |
`STATUS-USER` | A8 |  | D |
`TAPE-BLOCK-SIZE` | N2 |  | D |
`COMPRESS` | A3 |  | D |
`SAVE-ACL` | A3 |  | D |
`CONVERSION` | A4 |  | D |

The following fields correspond to parameters of the `ARCHIVE` command `PARAM`. They can be set only with the fisrt call, and will be ignored for all subsequent calls. Possible values for all fields are `YES` or `NO`.

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`PAR-CNS` | A3 |  | D | Default is `YES`.
`PAR-RESTART` | A3 |  | D | Default is `YES`.
`PAR-UNLOAD` | A3 |  | D | Default is `NO`.
`PAR-OPERATOR` | A3 |  | D | Default is `NO`.
`PAR-WRCHK` | A3 |  | D | Default is `NO`.
`PAR-SNR` | A3 |  | D | Default is `YES`.
`PAR-DESTROY` | A3 |  | D | Default is `NO`.
`PAR-CATID` | A3 |  | D | Default is `NO`.
`PAR-STREAM` | A3 |  | D | Default is `NO`.
`PAR-OLS` | A3 |  | D | Default is `NO`.

## Relevant Error Codes

Code | Text | BS2000
--- | --- | ---
530 | Access denied by Security Facility. | X
531 | Password missing or incorrect. | X
565 | Syntax error in dataset name. | X
658 | Dataset is not cataloged. | X
722 | Requested dataset not found. | X
733 | User ID does not exist. | X
734 | `ARCHIVE` run with errors. | X
750 | Invalid operand within operand list. | X
756 | Job variable name missing or invalid. | X
798 | Task was not started under TSOS. | X
799 | Entire System Server internal error. | X
853 | Retention cycle unexpired `/ NEWNAME` exists. | X
881 | Error occurred while opening file. | X
984 | Server is not authorized to access. | X
992 | Requested job variable not found. | X

## Field Descriptions

For detailed information, refer to documentation of SNI's product `ARCHIVE`. Some field descriptions simply refer to the corresponding `ARCHIVE` command to avoid duplicate explanations.

Field Name | Format/Length | Operating System
--- | --- | ---
`FUNCTION` | (A8) |

The possible values for this field relate to the corresponding `ARCHIVE` command to be executed, unless stated otherwise:

Value | Explanation
--- | ---
`FILES` |
`FILESC` | Continuation of `FILES` for more file definitions than are possible in one call with `FILES` function.
`JOBVAR` |
`JOBVARC` | Continuation of `JOBVAR` for more job variables than are possible in one call with `JOBVAR` function.
`DELETE` |
`EXPORT` |
`IMPORT` |
`INQUIRE` |
`LIST` |
`POOL` |
`PROCESS` |
`PURGE` |
`RESTORE` |
`SAVE` |
`STATUS` |
`CLOSE` | This must be the last call and starts the `ARCHIVE` execution.

Field Name | Format/Length | Operating System
--- | --- | ---
`BACKUP-TYPE` | (A1) |

Relevant for function `SAVE`. Minimum backup level.

Field Name | Format/Length | Operating System
--- | --- | ---
`CAT-ONLY` | (A3) |

Relevant for functions `SAVE`, `EXPORT`.

Option | Explanation
--- | ---
`NO` | Default. Files are saved including catalog entry.
`YES` | Only catalog entries are saved.

Field Name | Format/Length | Operating System
--- | --- | ---
`CHANGED` | (A12) |

Relevant for function `SAVE`. Possible values:

Value | Explanation
--- | ---
`YES` | Default. Only changed files are saved.
`YES,LARGE` | Only changed `LARGE` files are saved.
`YES,n` | Same as `YES,LARGE`, where `n` is the minimum file size in PAM pages.
`NO` | Save all objects.

Field Name | Format/Length | Operating System
--- | --- | ---
`COMPRESS` | (A3) |

Relevant for functions `SAVE`, `EXPORT`. Specifies whether a compress is to be done with save. Possible values:

Value | Explanation
--- | ---
`NO` | Default. Compress is not performed.
`YES` | Compress is performed.

Field Name | Format/Length | Operating System
--- | --- | ---
`CONTINUE` | (A13) |

Relevant for functions `SAVE`, `EXPORT`. Continuation of a previous `SAVE`/`EXPORT` run. Possible values:

Value | Explanation
--- | ---
`SVID` | `SAVE-ID` must be given.
`SVID,VSN-LIST` | `SAVE-ID` and `CONTINUE-VOLSER-ARRAY` must be given.
`VSN-LIST` | `CONTINUE-VOLSER-ARRAY` must be given.

Field Name | Format/Length | Operating System
--- | --- | ---
`CONTINUE-VOLSER-ARRAY` | (A6) |

Relevant for functions `SAVE`, `EXPORT`. Maximum of 5 volumes if keyword `VSN-LIST` is specified in field `CONTINUE`.

Field Name | Format/Length | Operating System
--- | --- | ---
`CONVERSION` | (A4) |

Relevant for functions `RESTORE`, `IMPORT`. PAM key conversion required to import or restore files to non-key disks. Possible values:

Value | Explanation
--- | ---
`NO` | Default.
`CONV` |
`STD` |

Field Name | Format/Length | Operating System
--- | --- | ---
`DAYS-UNUSED` | (N5) |

Relevant for functions `SAVE`, `EXPORT`. Number of days the object to be saved must have been unused.

Field Name | Format/Length | Operating System
--- | --- | ---
`DEVICE` | (A8) |

Relevant for functions `SAVE`, `EXPORT`, `RESTORE`, `IMPORT`, `POOL`, `LIST`. Device type (for example, `T9G`).

Field Name | Format/Length | Operating System
--- | --- | ---
`DIRECTORY` | (A54) |

Relevant for functions `SAVE`, `EXPORT`, `RESTORE`, `IMPORT`, `POOL`, `LIST`, `PURGE`, `INQUIRE`. Name of directory file. Default is `NONE`.

Field Name | Format/Length | Operating System
--- | --- | ---
`DRIVES` | (N2) |

Relevant for functions `SAVE`, `EXPORT`, `RESTORE`, `IMPORT`, `LIST`. Number of drives to be used in parallel.

Field Name | Format/Length | Operating System
--- | --- | ---
`ERASE` | (A7) |

Relevant for functions `SAVE`, `EXPORT`. Specifies erasing of objects after `SAVE` or `EXPORT`. Possible values:

Value | Explanation
--- | ---
`NO` | Default. Objects are not erased.
`ALL` | Objects are erased regardless of access and retpd.
`ALLP` | For TSOS only: objects are erased regardless of access, retpd and passwords.
`ALLCNS` | Same as `ALL`, but also for CNS files.
`ALLCNP` | For TSOS only: same as `ALLCNS`, regardless of passwords.
`YES` | Objects are erased, if allowed by access, retpd and password definition.

Field Name | Format/Length | Operating System
--- | --- | ---
`EXCEPT-FILE-ARRAY` | (A61) |

Relevant for functions `FILES`, `FILESC`. Maximum of 20 file expressions for `EXCEPT` option of `ARCHIVES FILES` command. Same syntax as for `FILE-ARRAY`.

Field Name | Format/Length | Operating System
--- | --- | ---
`EXCEPT-JOB-VARIABLE-ARRAY` | (A61) |

Relevant for functions `JOBVAR`, `JOBVARC`. Maximum of 20 JV expressions for `EXCEPT` option of `ARCHIVES JOBVAR` command. Same syntax as for `JOB-VARIABLE-ARRAY`.

Field Name | Format/Length | Operating System
--- | --- | ---
`FILE-ARRAY` | (A61) |

Relevant for functions `FILES`, `FILESC`, `INQUIRE`. Maximum of 20 file expressions, where a file expression can be a file name of a file name prefixed by `THRU=` or `RENAME=`.

Field Name | Format/Length | Operating System
--- | --- | ---
`FORCE-PURGE` | (A3) |

Relevant for function `PURGE`. Specify to force purging of saved versions. Possible values:

Value | Explanation
--- | ---
`NO` | Default. Saved versions are not purged.
`YES` | Saved versions are purged.

Field Name | Format/Length | Operating System
--- | --- | ---
`FROM-OPTION` | (A24) |

Relevant for functions `RESTORE`, `IMPORT`, `LIST`. Possible values:

- `LATEST`

- `LATEST,STATE`

- `SVID`

- `SVID,STATE,yymmdd.hhmmss`

- `SVID,VSN-LIST`

- `VSN-LIST`

- `yymmdd.hhmmss`

- `yymmdd.hhmmss,STATE`

If `SVID` is specified, the field `SAVE-ID` must be specified. If `VSN-LIST` is specified, the `VOLSER-ARRAY` field must be specified.

Field Name | Format/Length | Operating System
--- | --- | ---
`INQUIRE-POOL-OPTION` | (A14) |

Relevant for function `INQUIRE`. Possible values:

- `POOL`

- `POOL,AVAILABLE`

Field Name | Format/Length | Operating System
--- | --- | ---
`JOB-VARIABLE-ARRAY` | (A61) |

Relevant for functions `JOBVAR`, `JOBVARC`, `INQUIRE`. Maximum of 20 JV expressions, where a JV expression can be a JV name or a JV name prefixed by `THRU=` or `RENAME=`.

Field Name | Format/Length | Operating System
--- | --- | ---
`LIST` | (A10) |

Relevant for functions `SAVE`, `EXPORT`, `RESTORE`, `IMPORT`, `PURGE`, `LIST`, `INQUIRE`. Destination for `ARCHIVE` report. Possible values:

- `BOTH`

- `NONE`

- `SYSLST`

- `SYSOUT`

Some functions allow the adding of `,ALL`, see the `ARCHIVE` documentation.

Note
If `ARCHIVE` is called with the Entire System Server in multi-user mode, the destinations `SYSLST` and `SYSOUT` will be those of the Entire System Server task.

Field Name | Format/Length | Operating System
--- | --- | ---
`NEW-DIRECTORY` | (A3) |

Relevant for functions `SAVE`, `EXPORT`, `POOL`.

Value | Explanation
--- | ---
`NO` | Default. `DIRECTORY` field specifies existing directory.
`YES` | `DIRECTORY` field specifies new directory.

Field Name | Format/Length | Operating System
--- | --- | ---
`NOW` | (A3) |

Relevant for functions `SAVE`, `EXPORT`, `RESTORE`, `IMPORT`, `POOL`, `PURGE`, `LIST`. Possible values:

Value | Explanation
--- | ---
`YES` | Default. Start immediately after function `CLOSE` is specified.
`NO` | Put `ARCHIVE` command to file for later execution with function `PROCESS` (or cancel with `DELETE`).
`t` | Time in seconds: same as `NO`, where the time specified is an execution time limit for an `ARCHIVE` task started later.

Field Name | Format/Length | Operating System
--- | --- | ---
`PASSWORD-ARRAY` | (A8) |

Relevant for functions `SAVE`, `EXPORT`, `RESTORE`, `IMPORT`, `POOL`, `PURGE`, `LIST`, `INQUIRE`. If files or job variables are password-protected, maximum of 10 passwords. Only the first password will be used with function `INQUIRE`.

Field Name | Format/Length | Operating System
--- | --- | ---
`POOL-OPERATION` | (A6) |

Relevant for function `POOL`. Possible values:

- `ADD`

- `REMOVE`

Field Name | Format/Length | Operating System
--- | --- | ---
`REPLACE` | (A4) |

Relevant for functions `RESTORE`, `IMPORT`. Possible values:

Value | Explanation
--- | ---
`NO` | Default. Objects are not replaced.
`ALL` | Objects are replaced regardless of access and retpd.
`ALLP` | For TSOS only: objects are replaced regardless of access, retpd and passwords.
`YES` | Objects are replaced, if allowed by access, retpd and password definition.

Field Name | Format/Length | Operating System
--- | --- | ---
`RETENTION-PERIOD` | (N5) |

Relevant for functions `SAVE`, `EXPORT`. Retention period for save version in number of days.

Field Name | Format/Length | Operating System
--- | --- | ---
`SAVE-ACL` | (A3) |

Relevant for function `SAVE`. Only for `SECOS`/`FACS`. Save ACL entries. Possible values:

Value | Explanation
--- | ---
`NO` | Default. ACL entries are not saved.
`YES` | ACL entries are saved.

Field Name | Format/Length | Operating System
--- | --- | ---
`SAVE-DIRECTORY` | (A3) |

Relevant for functions `SAVE`, `EXPORT`. Possible values:

Value | Explanation
--- | ---
`NO` | Directory is not saved.
`YES` | Save directory also.

Field Name | Format/Length | Operating System
--- | --- | ---
`SAVE-ID` | (A15) |

Relevant for functions `SAVE`, `EXPORT`, `PROCESS`, `DELETE`. `ARCHIVE` Save Identifier, in case the keyword `SVID` was specified in field `FROM-OPTION` or `CONTINUE`.

Field Name | Format/Length | Operating System
--- | --- | ---
`SAVE-PASSWORD` | (A8) |

Relevant for functions `SAVE`, `EXPORT`, `RESTORE`, `IMPORT`. Password for the `SAVE` run.

Field Name | Format/Length | Operating System
--- | --- | ---
`SHARE` | (A3) |

Relevant for functions `SAVE`, `EXPORT`. Possible values:

Value | Explanation
--- | ---
`NO` | Saved objects and volumes are not sharable.
`YES` | Saved objects and volumes are sharable.

Field Name | Format/Length | Operating System
--- | --- | ---
`SPACE` | (A5) |

Relevant for functions `RESTORE`, `IMPORT`. Possible values:

Value | Explanation
--- | ---
`REORG` | Default.
`KEEP` |

Field Name | Format/Length | Operating System
--- | --- | ---
`STATUS-TYPE` | (A6) |

Relevant for function `STATUS`. Type of `ARCHIVE` tasks for which status information is required. Possible values:

Value | Explanation
--- | ---
`LATER` | Default.
`ACTIVE` |

Field Name | Format/Length | Operating System
--- | --- | ---
`STATUS-USER` | (A8) |

Relevant for function `STATUS`. Only for TSOS: user ID for which status information is required.

Field Name | Format/Length | Operating System
--- | --- | ---
SV-OPTION | (A100) |

Relevant for functions `INQUIRE` and `PURGE`. For possible values, see the `SV` option of the corresponding `ARCHIVE` commands.

Field Name | Format/Length | Operating System
--- | --- | ---
`TAPE-BLOCK-SIZE` | (N2) |

Relevant for functions `SAVE`, `EXPORT`. Block size in number of PAM pages. Maximum is 15.

Field Name | Format/Length | Operating System
--- | --- | ---
`TAPES` | (A8) |

Relevant for functions `SAVE`, `EXPORT`. Possible values:

Value | Explanation
--- | ---
`OPERATOR` | Volumes are required from operator.
`POOL` | Volumes are taken from pool of directory.
`VSN-LIST` | Volumes are specified in field `VOLSER-ARRAY`.

Field Name | Format/Length | Operating System
--- | --- | ---
`VOLSER-ARRAY` | (A6) |

Relevant for functions `SAVE`, `EXPORT`, `POOL`. A maximum of 10 volumes can be specified. Required also for functions `RESTORE`, `IMPORT`, `UST` when field `FROM-OPTION=VSN-LIS`T.

## Example

The following `ARCHIVE` commands are created by the example program shown below:

    PARAM UNLOAD=YES
    FILES NAME=(MYFILE.1,MYFILE.2,MYFILE.SHARE.),
                     NAME=(BADFILE,RENAME=NICEFILE)
    EXPORT SHARE=YES,DEVICE=T-C1,LIST=BOTH,
                     TAPES=(MYTAPE)

      DEFINE DATA
                  LOCAL USING ARCHIV-L
      END-DEFINE
      *
      * ---  build first part of FILES command and set PARAM options  ---
      *
      PROCESS ARCHIVE
        USING NODE           = 148
            , FUNCTION       = 'FILES'
            , PAR-UNLOAD     = 'YES'
            , FILE-ARRAY     = 'MYFILE.1'      /*  FIRST FILE
            , FILE-ARRAY     = 'MYFILE.2'      /*  SECOND FILE
            , FILE-ARRAY     = 'MYFILE.SHARE.' /*  ALL FILES STARTING  *
                   WITH THIS PREFIX
      *
      IF ERROR-CODE NE 0
        WRITE ERROR-TEXT
        ESCAPE ROUTINE
      END-IF
      *
      * ---  continue FILES command  ---
      *
      PROCESS ARCHIVE
        USING NODE           = 148
            , FUNCTION       = 'FILESC'
            , FILE-ARRAY     = 'BADFILE'         /* rename this file
            , FILE-ARRAY     = 'RENAME=NICEFILE' /* .. with this name
        *
      IF ERROR-CODE NE 0
        WRITE ERROR-TEXT
        ESCAPE ROUTINE
      END-IF
      *
      * ---  build EXPORT command  ----
      *
      PROCESS ARCHIVE
        USING NODE           = 148
            , FUNCTION       = 'EXPORT'
            , LIST           = 'BOTH'
            , SHARE          = 'YES'
            , DEVICE         = 'T-C1'
            , VOLSER-ARRAY   = 'MYTAPE'
      *
      IF ERROR-CODE NE 0
        WRITE ERROR-TEXT
        ESCAPE ROUTINE
      END-IF
      *
      * ---  ready to go  ---
      *
      PROCESS ARCHIVE
        USING NODE           = 148
            , FUNCTION       = 'CLOSE'         /* execute ARCHIVE
      *
      IF ERROR-CODE NE 0
        WRITE ERROR-TEXT
        ESCAPE ROUTINE
      END-IF
      END

### On this page

- Common Fields for all Operating Systems
- Relevant Error Codes
- Field Descriptions
- Example