ARCHIVE

File 211
Op-Sys BS2000/OSD
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/OSD
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-LIST.

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