FREE-VOLUMES Release tapes

Privilege                ADA, DA, administrator without domains

This statement releases reserved tapes when their expiration date is reached. Exceptions to this are exported tapes and those tapes undergoing processing at the time.

DAs can only execute the statement in their own domain. The DOMAIN operand is thus meaningless for them.

Format

FREE-VOLUMES                                                                                                                                      Alias: FRV

VOLUME = *ALL / *INTERVAL(...) / *BY-FILE(...) / list-poss(10):<vsn> / *BY-VOLUME-GROUP(...)
	*INTERVAL(...)
		|	FROM = *FIRST / <vsn>
		|	,TO = *LAST / <vsn>
		|	,FROM-FSEQ = 1 / <integer 1..9999>
	*BY-FILE(...)
		|	FILE-NAME = <filename 1..41 without-cat-user>
		|	,VERSION = *ALL / *LATEST / <integer -9999..0>
		|	,USER-IDENTIFICATION = *ALL / <name 1..8>
		|	,TYPE-OF-VOLUMES = *ANY / *OBSOLETE
	*BY-VOLUME-GROUP(...)
		|	VOLUME-GROUP = <text 1..32 without-sep>
,FREE-LOCATION = *ANY / <alphanum-name 1..8>
, DOMAIN = *ANY / *OWN / *STD-DOMAIN / <alphanum-name 1..8>
,INIT-FILE = MARENADM.INIT-FILE / <filename 1..54 without-gen-vers>(...) / *DUMMY(...) / *NONE
	<filename 1..54 without-gen-vers>(...)
		|	SELECT = *BY-INIT-FLAG / *ALL
		|	,INIT-LOCATION = *NONE / <alphanum-name 1..8>
		|	,USER-IDENTIFICATION = SYSMAREN / <name 1..8>
		|	,ACCOUNT = *NONE / <alphanum-name 1..8>
	*DUMMY(...)
		|	SELECT = *BY-INIT-FLAG / *ALL
		|	,INIT-LOCATION = *NONE / <alphanum-name 1..8>
		|	,USER-IDENTIFICATION = SYSMAREN / <name 1..8>
		|	,ACCOUNT = *NONE / <alphanum-name 1..8>
,CHECK-DIRECTORY = *YES / *NO
,CHECK-TSOSCAT = *NO / *YES
,OVERFLOW-CONTROL = *BY-PROGRAM / *BY-SYSTEM

Operands

VOLUME =
Tapes from the MAREN catalog which are to be processed.

VOLUME = *ALL
All tapes from this MAREN catalog are to be processed.

VOLUME = *INTERVAL(...)
All tapes whose archive number lies within the range specified below are processed.

FROM = *FIRST
All tapes are processed, starting with the lowest available archive number.

FROM = <vsn>
Archive number. All tapes whose archive number is greater than or equal to the specified archive number are processed.

TO = *LAST
All tapes are processed up to the highest existing archive number.

TO = <vsn>
Archive number. All tapes whose archive number is less than or equal to the specified archive number are processed.

FROM-FSEQ = 1 / <integer 1..9999>
File sequence number of the FROM operand. Specifies the precise file sequence number at which processing is to begin. This operand is relevant only if the statement is issued via the program interface.

VOLUME = *BY-FILE(...)
All tapes belonging to a file or a tape set are to be processed.

FILE-NAME = <filename 1..41 without-cat-user>
Specifies the file name for which a tape set is to be processed.

VERSION =
This operand can be used to select a specific version (or status) of the specified file for which the associated tapes are to be processed.

VERSION = *ALL
Processes all versions which exist for the specified file name.

VERSION = *LATEST
Processes the latest version of the file (i.e. the last one created).

VERSION = <integer -9999..0>
Specifying 0 is equivalent to specifying *LATEST, specifying -1 indicates the penultimate file status, etc.

USER-IDENTIFICATION =
This operand selects the user ID to which the tapes are assigned (archive entry field USER-ID).

USER-IDENTIFICATION = *ALL
The user IDs are not evaluated during selection.

USER-IDENTIFICATION = <name 1..8>
Only those archive numbers which are assigned to the specified user ID are processed.

TYPE-OF-VOLUMES =
This operand selects the volume sequences (catalog entry field VOLUME-SEQUENCE) within a tape set. These numbers are usually unique. Some numbers may be duplicated following a restart.

TYPE-OF-VOLUMES = *ANY
The volume sequences for a tape set are not checked to establish whether they occur more than once.

TYPE-OF-VOLUMES = *OBSOLETE
If tape sequence numbers occur more than once for a tape set, all are selected except the one most recently created.

VOLUME = list-poss(10):<vsn>
Archive number. Up to ten archive numbers may be specified.

VOLUME = *BY-VOLUME-GROUP(...)
All tapes of the specified volume group are processed.

VOLUME-GROUP = <text 1..32 without-sep>
Specifies the volume group to which a tape must belong for it to be processed. “*” can be entered as the last character. In this case all volume groups which begin with the specified string are selected.

FREE-LOCATION =
Selects according to the location to which the tapes are to be moved (cf. the operand of the same name in the statements MODIFY-VOLUME-ATTRIBUTES on "MODIFY-VOLUME-ATTRIBUTES Modify attributes of tapes in the MAREN catalog" and ADD-RESERVED-VOLUMES on "ADD-RESERVED-VOLUME Generate MAREN catalog entries"). The explicit specification of FREE-LOCATION may not be combined with the VOLUME = *BY-FILE operand.

FREE-LOCATION = *ANY
The tapes of all locations are processed.

FREE-LOCATION = <alphanum-name 1..8>
The tapes of the specified location are processed.

DOMAIN =
The tapes are selected according to domains.

DOMAIN = *ANY
The tapes from all domains are processed.

DOMAIN = *OWN
The tapes of the user’s own domain are processed. The user’s own domain is the domain of the system on which the ADA is currently working or the domain in which he/she has taken over the DA role.

DOMAIN = *STD-DOMAIN
The tapes of the standard domain are processed.

DOMAIN = <alphanum-name 1..8>
The tapes of the specified domain are processed.

INIT-FILE =
Specifies the file to which the settings for initialization are to be written (output file). The file type is SAM. This file is created only if at least one tape needs to be initialized.

INIT-FILE = MARENADM.INIT-FILE
The initialization file with the default name is generated. This name is also used as the default name for the INITIALIZE-VOLUMES statement.

INIT-FILE = <filename 1..54 without-gen-vers>(...)
Name of the output file to be created.

SELECT =
Specifies which of the released tapes are  to be initialized.

SELECT = *BY-INIT-FLAG
Only those tapes whose catalog entries contain INIT=YES are to be initialized, i.e. only those tapes which were written to while protection characteristics were set. Tapes in whose catalog entries the catalog entry field CLOSE-INDICATOR has the value OPENED are also initialized (see notes on "FREE-VOLUMES Release tapes").

SELECT = *ALL
All released tapes are to be initialized.

INIT-LOCATION =
Location name or symbolic location name.

INIT-LOCATION = *NONE
The catalog entry field HOME-LOCATION is not modified.

INIT-LOCATION = <alphanum-name 1..8>
This location name is stored in the catalog entry field HOME-LOCATION. After successful initialization and release, the HOME-LOCATION catalog entry field is filled with the content of the FREE-LOCATION catalog entry field.

USER-IDENTIFICATION = SYSMAREN / <name 1..8>
Specifies the user ID to which the tapes in the MAREN catalog are to be assigned until they have been initialized and subsequently finally released.

ACCOUNT = *NONE / <alphanum-name 1..8>
Account number of the specified user ID.

INIT-FILE = *DUMMY(...)
No output file is created. The tapes affected are simply assigned to the specified user ID and account number and moved to the desired storage location. If an output file is specified in a subsequent release run, the catalog entries of these tapes are likewise output there and are thus available for initialization.

SELECT =
Specifies which of the released tapes is to be initialized.

SELECT = *BY-INIT-FLAG
Only those tapes whose catalog entries contain INIT=YES are to be initialized, i.e. only those tapes which were written to while protection characteristics were set. Tapes in whose catalog entries the catalog entry field CLOSE-INDICATOR has been assigned the value OPENED are also initialized (see notes).

SELECT = *ALL
All released tapes are to be initialized.

INIT-LOCATION =
Location name or symbolic location name.

INIT-LOCATION = *NONE
The catalog entry field HOME-LOCATION is not modified.

INIT-LOCATION = <alphanum-name 1..8>
This location name is stored in the catalog entry field HOME-LOCATION. After successful initialization and release, the HOME-LOCATION catalog entry field is filled with the content of the FREE-LOCATION catalog entry field.

USER-IDENTIFICATION = SYSMAREN / <name 1..8>
Specifies the user ID to which the tapes in the MAREN catalog are to be assigned until they have been initialized and subsequently finally released.

ACCOUNT = *NONE / <alphanum-name 1..8>
Account number of the specified user ID.

INIT-FILE = *NONE
No file is created. Tapes with INIT=YES are likewise released without being initialized. Initialization takes place automatically using MARENUCP. These tapes cannot be reserved using RESERVE-FREE-VOLUMES.

CHECK-DIRECTORY =
Specifies whether or not to check if there is another tape allocated to a directory before the tape is released.

CHECK-DIRECTORY = *YES
A tape that is still allocated to a directory is not released.

CHECK-DIRECTORY = *NO
The tape is released regardless of whether or not it is still allocated to a directory.

CHECK-TSOSCAT =
Defines whether, before the tape is released, a check should be made to see whether tape files contained in the MAREN catalog are also entered in the TSOSCAT.

CHECK-TSOSCAT = *NO
The tape is released irrespective of whether tape files contained in the MAREN catalog are also entered in the TSOSCAT.

CHECK-TSOSCAT = *YES
A check is made to see whether tape files contained in the MAREN catalog are also entered in the TSOSCAT. If this is the case, the calling user ID receives warning MARM220 which must be answered and can continue or abort the action.

OVERFLOW-CONTROL =
Type of screen overflow control in interactive mode.

OVERFLOW-CONTROL = *BY-PROGRAM
Control by the program: after eighteen catalog entries have been processed, a message is displayed inquiring whether the current operation is to be continued or aborted.

OVERFLOW-CONTROL = *BY-SYSTEM
Control by BS2000: Screen overflow control is based entirely on the system parameter TCHOFLO or the value set in the MODIFY-TERMINAL-OPTIONS command.

Notes

• If the INIT-FILE operand is specified, the tapes to be initialized are not released. Instead, the specified catalog entries are modified as follows:

  USER-ID ACCOUNT HOME-LOCATION USER-ACCESS PASSWORD FILE-NAME

  = = = = = =

  User ID (USER-IDENTIFICATION operand) Account number (ACCOUNT operand) Initialization location (INIT-LOCATION operand) OWNER-ONLY YES Blanks

  Subsequent to modification, the entries are written to the specified file. This file should then be used as the input file for a subsequent initialization run using the INITIALIZE-VOLUMES statement.

• The initialization flag is not given the correct value until a tape file is closed or a volume is swapped. If generation of an output tape is aborted, e.g. due to a hardware fault, you will not be able to tell from the catalog entry whether the tape has been written with security attributes. Tapes of this kind have the value OPENED in the CLOSE-INDICATOR catalog entry field of the catalog entry. They should, however, be initialized just in case.

• During the release procedure, the tape status is reset internally from “reserved” to “free”, the contents of the FREE-LOCATION catalog entry field are copied to the HOME-LOCATION field, and the PASSWORD catalog entry field is deleted. All other catalog entry fields remain unchanged until a new reservation is made. Modifying HOME-LOCATION causes the tapes involved to be moved to the location specified in FREE-LOCATION the next time a clear-up run is performed.

• All existing multifile catalog entries with an FSEQ > 1 are deleted.

• If a file name is specified in the FILE-NAME operand, the VOLUME operand must be set to the default value *ALL. If one of the selected catalog entries contains the attribute FILE-SEQ > 1 with this type of file-name-specific release, processing is aborted.

• For performance reasons, in shared mode the FREE-VOLUMES statement should only be executed on the system with the MAREN catalog.

• If a reserved tape is released which was entered in the MAREN catalog with DEVICE-TYPE=TAPE-UxE, MAREN changes the device type to TAPE-Ux because the device type TAPE-UxE does not exist for free tapes and not supported for any other statements..

Examples

Example 1

//free-volumes volume=(id4001,tape01,idx005),init-file=*none
%  MARM137 VOLUME 'ID4001' NOW FREE ( USER ID 'USER1', FILE NAME' ' )
%  MARM137 VOLUME 'TAPE01' NOW FREE ( USER ID 'USERXY08', FILE NAME ' ' )
%  MARM137 VOLUME 'IDX005' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM122 TOTAL OF 3 VOLUMES RELEASED
%  MARM170 STATEMENT '//FREE-VOLUMES' PROCESSED


The tapes with the specified archive numbers are released, provided their expiration date has elapsed. They can now be used for new reservations.

Example 2

//free-vol vol=*int(id5000,id6000),init-file=*none
%  MARM137 VOLUME 'ID5001' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM137 VOLUME 'ID5002' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM137 VOLUME 'ID5003' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM137 VOLUME 'ID5004' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM137 VOLUME 'ID5005' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM137 VOLUME 'ID5008' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM137 VOLUME 'ID5009' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM137 VOLUME 'ID5010' NOW FREE ( USER ID 'USER1', FILE NAME ' ' )
%  MARM122 TOTAL OF 10 VOLUMES RELEASED
%  MARM170 STATEMENT '//FREE-VOLUMES' PROCESSED


All tapes whose archive numbers are in the range id5000 to id6000 are released, provided their expiration date has elapsed.

Example 3

//free-vol vol=*int(tlt001,tlt020),init-file=maren.init(select=*by-init-flag,init-loc=robtls,user-id=init0001)
%  MARM130 VOLUME 'TLT001' RELEASED FOR INITIALIZATION; USER ID 'SYSMAREN',
FILE NAME ' ', CURRENT LOCATION 'CENTRAL'
%  MARM130 VOLUME 'TLT002' RELEASED FOR INITIALIZATION; USER ID 'SYSMAREN',
FILE NAME ' ', CURRENT LOCATION 'CENTRAL'
...
%  MARM137 VOLUME 'TLT011' NOW FREE ( USER ID 'INIT0001', FILE NAME ' ' )
%  MARM137 VOLUME 'TLT012' NOW FREE ( USER ID 'INIT0001', FILE NAME ' ' )
...
%  MARM122 TOTAL OF 6 VOLUMES RELEASED
%  MARM119 FILE 'MAREN.INIT' WITH 10 RECORDS CREATED
%  MARM170 STATEMENT '//FREE-VOLUMES' PROCESSED

//show-vol-attr vol=tlt001,information=*normal
VOLUME    = TLT001       FILE-SEQ      = 0001          DEV-TYPE    = TAPE-C5

USER-ID   = INIT0001     HOME-LOCATION = ROBTLS        RESERV-DATE =
ACCOUNT   =              FREE-LOCATION = CENTRAL       FREE-DATE   = <date>
USER-ACC  = OWNER-ONLY   TEMP-LOCATION = CENTRAL       EXPIR-DATE  =
PASSWORD  = C'INIT'     /-0908736029/
EXPORT    = C'                                                  '  /
REMARK /1 = C'                        ' /2 = C'          ' /3 = C' '
USER-FIELD= C'                                                      '
FILE-NAME =
SAVE-FILE =                 SUBSAVE/SEQ =   /    CR-JOB/REQUEST-NA  =
FREE-POOL = *NO                                  CR-CAT-ID          =
VOL-GROUP =                                      CR-USER-ID         =
VOL-SEQ   = 0001       CR-DATE      =            LAST-ACC-DATE      =
FIRST-VOL =            CR-TIME      =            LAST-ACC-TIME      =
CLOSE-IND =            LAST-CL-DATE =            LAST-ACC-USER-ID   =
VOL-STATUS= RESERVED   LAST-CL-TIME =            LAST-ACC-ACCOUNT   =
INIT      = YES        REG-DATE     =            LAST-ACC-JOB-NAME  =
ADM-FIELD = C'        ' /2 = C'                ' LAST-ACC-TSN       =
                                                 LAST-ACC-HOSTNAME  =
                                                 LAST-WRITE-BLK-CNT =


//show-vol-attr vol=tlt016,information=*normal
VOLUME    = TLT016       FILE-SEQ      = 0001          DEV-TYPE    = TAPE-C5

USER-ID   = INIT0001     HOME-LOCATION = CENTRAL       RESERV-DATE = <date>
ACCOUNT   =              FREE-LOCATION = CENTRAL       FREE-DATE   = <date>
USER-ACC  = OWNER-ONLY   TEMP-LOCATION = CENTRAL       EXPIR-DATE  =
PASSWORD  = NONE
EXPORT    = C'                                                  '  /
REMARK /1 = C'                        ' /2 = C'          ' /3 = C' '
USER-FIELD= C'                                                      '
FILE-NAME =
SAVE-FILE =                 SUBSAVE/SEQ =   /    CR-JOB/REQUEST-NA  =
FREE-POOL = *NO                                  CR-CAT-ID          =
VOL-GROUP =                                      CR-USER-ID         =
VOL-SEQ   = 0001       CR-DATE      =            LAST-ACC-DATE      =
FIRST-VOL =            CR-TIME      =            LAST-ACC-TIME      =
CLOSE-IND =            LAST-CL-DATE =            LAST-ACC-USER-ID   =
VOL-STATUS= FREE       LAST-CL-TIME =            LAST-ACC-ACCOUNT   =
INIT      = NO         REG-DATE     =            LAST-ACC-JOB-NAME  =
ADM-FIELD = C'        ' /2 = C'                ' LAST-ACC-TSN       =
                                                 LAST-ACC-HOSTNAME  =
                                                 LAST-WRITE-BLK-CNT =


All tapes between TLT001 and TLT020 whose expiration date has elapsed are released. All tapes with INIT=NO whose expiration date has elapsed are released (total of 6 with the archive numbers TLT011 to TLT016; see also output of the catalog entryTLT016). All tapes with INIT=YES whose expiration date has been reached are reserved for the user ID INIT0001. However, they are no longer available to the original user ID. The modified MAREN catalog entries are written to the file MAREN.INIT (total of 10 with the archive numbers TLT001 to TLT010; see also output of the catalog entry TLT001). If this file is subsequently assigned as an input file in an initialization run (INITIALIZE-VOLUMES statement), the tapes are then first definitively released and are thus available for new reservations.

Example 4

//free-vol vol=*by-file(fi-name=sample.dmsfile.1,version=-3),init-file=*dummy(select=*all,init-loc=da11loc)
%  MARM130 VOLUME 'GRA002' RELEASED FOR INITIALIZATION; USER ID 'MAREN001',
FILE NAME 'SAMPLE.DMSFILE.1', CURRENT LOCATION 'LOCESSAI'
%  MARM122 TOTAL OF 0 VOLUMES RELEASED
%  MARM170 STATEMENT '//FREE-VOLUMES' PROCESSED

//show-vol-attr vol=gra002, info=*normal
VOLUME    = GRA002       FILE-SEQ      = 0001          DEV-TYPE    =  TAPE-C4
USER-ID   = SYSMAREN     HOME-LOCATION = DA11LOC       RESERV-DATE =  <date>
ACCOUNT   =              FREE-LOCATION = LOCESSAI      FREE-DATE   =  <date>
USER-ACC  = OWNER-ONLY   TEMP-LOCATION = LOCESSAI      EXPIR-DATE  =
PASSWORD  = C'INIT'     X'C9D5C9E3'       /-0908736029/
EXPORT    = C'                                                  '  /
REMARK /1 = C'                        ' /2 = C'          ' /3 = C'          '
USER-FIELD= C'                                                      '
FILE-NAME =
SAVE-FILE =                 SUBSAVE/SEQ =   /    CR-JOB/REQUEST-NA  =
FREE-POOL = *NO                                  CR-CAT-ID          =
VOL-GROUP =                                      CR-USER-ID         =
VOL-SEQ   = 0001       CR-DATE      = <date>     LAST-ACC-DATE      = <date>
FIRST-VOL = GRA002     CR-TIME      = <time>     LAST-ACC-TIME      = <time>
CLOSE-IND = CLOSED     LAST-CL-DATE = <date>     LAST-ACC-USER-ID   =MAREN001
VOL-STATUS= RESERVED   LAST-CL-TIME = <time>     LAST-ACC-ACCOUNT   =MAREN001
INIT      = YES        REG-DATE     = <date>     LAST-ACC-JOB-NAME  =MAREN001
ADM-FIELD = C'        ' /2 = C'                ' LAST-ACC-TSN       =
                                                 LAST-ACC-HOSTNAME  =D049ZE70
                                                 LAST-WRITE-BLK-CNT =


The tapes recorded when creating version -3 of the file SAMPLE.DMSFILE.1 whose expiration date has elapsed are reserved to the user ID SYSMAREN (default value) and transported to the storage location da11loc. There is no selection on the basis of the initialization ID in the MAREN catalog entry (SELECT=*ALL). No file is created for a subsequent initialization run.