This statement is only available to the HSMS administrator; it reorganizes version backup archives. During reorganization, save files and their save versions are copied and only valid file versions are transferred to the new save file and save version respectively.
The decision as to which file versions are valid is made according to the file attribute NUM-OF-BACKUP-VERS, which specifies how many versions of a file are to be stored in the version backup archive. The value NUM-OF-BACKUP-VERS is copied to the archive directory for each backup run and each time the CHECK-CATALOGED-FILES statement is executed. This is evaluated during a reorganization run.
During the reorganization, files that have been deleted on the pubset but have not yet been marked for deletion (see //MODIFY-ARCHIVE ARCHIVE-NAME=...,FILES=...) are also copied. These files are also valid files.
The new save files and save versions created during reorganization receive current time stamps, and their sequence is not guaranteed. However, the time stamps of the original save versions (SVID) are retained internally and serve the user as selection criteria for information functions or when restoring files. A list of the file versions according their original creation is provided:
//SHA ...SELECT=*FILES(INFORMATION=*ORIGINAL)
The functionality of the REORGANIZE-VERSION-BACKUP statement includes the following functions
- Copying save files to the specified storage medium (TO-STORAGE), whereby only valid file versions are copied.
- Subsequent removal of the original save files from the archive.
If an error occurs during the reorganization run, a roll-back mechanism is started: all new save versions and files are removed, the previous ones remain in their original state before the reorganization. The save files on disk storage that only contain obsolete save versions are removed in any case.
By default, the REORGANIZE-VERSION-BACKUP statement processes all save versions in the version backup archive. However, it is possible to select save files for reorganization according to their creation date, that is, reorganization of all save files from the past to the specified creation date of the SFID.
During reorganization to storage level S2, each save file on disk is copied to a new save file on tape as a save version with the current date after reorganization. When reorganizing to disk storage, all save versions from tape are written to separate save files on disk. New save files are created during reorganization: continuing existing save files is not supported during reorganization.
The retention period of the save files is taken from the attributes of the version backup archive.
By default, the save files which do not contain any obsolete file version, are not taken for reorganization. From HSMS V12.0D it is possible to force the reorganization for such save files, in other words to move such save files to specified storage medium irrespective to existence of obsolete file versions. These options are controlled by EXECUTION-MODE operand.
Format (only for HSMS administrators)
REORGANIZE-VERSION-BACKUP | Alias: RVB | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) privileged operand or operand value
ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>
Name of the version backup archive to be reorganized.
The archive must already exist and be defined as version backup archive.
If the archive directory is protected by a password, this password must be entered by means of the ADD-PASSWORD command prior to statement.
ARCHIVE-NAME =*SYSVERSION(...)
The system version backup archive of the given pubset is to be reorganized.
PUBSET-ID = <cat-id>
Catalog ID of the S0-pubset which system version backup archive is to be reorganized. In the case of SM-environment it must be the same as specified in CAT-ID sub operand. Otherwise the statement is rejected.
ENVIRONMENT =
Defines the HSMS environment in which the HSMS statement is to be processed.
ENVIRONMENT = *STD
*STD is set to the value *SINGLE-FEATURE.
ENVIRONMENT = *SINGLE-FEATURE
The HSMS statement is valid in the SF environment.
ENVIRONMENT = *SYSTEM-MANAGED(...)
The HSMS statement is valid in the specified SM pubset environment.
CATALOG-ID = <cat-id>
Catalog ID of the SM pubset for which the HSMS statement is valid.
SAVE-FILE-ID =
Determines the save files that are to be reorganized.
SAVE-FILE-ID = *ALL
All save files within the version backup archive are reorganized.
SAVE-FILE-ID = *BY-ATTRIBUTES(...)
Only those save files are reorganized which were created within a certain period. If nothing further is specified, all save versions are selected.
CREATED-BEFORE = *LATEST-DATE / <date with-compl>(...) / < integer -99999..0 days >(...)
Only those save versions are reorganized which were created before the specified date.
The default is *LATEST-DATE, in other words the time period with no upper limit.
If a date is specified explicitly (absolutely or relatively), an additional time specification can define the period limit more precisely.
CREATED-BEFORE = <date with-compl>(...)
Date as absolute specification.
TIME = 23:59:59 / <time>
Time in the format hh:mm:ss.
CREATED-BEFORE = <integer -99999..0 days >(...)
Date as relative specification in days to the current date.
TIME = 23:59:59 / <time>
Time in the format hh:mm:ss.
EXECUTION-MODE =
Defines the mode in which the selected save files will be processed.
EXECUTION-MODE = *STD
Save files will only be reorganized if there are obsolete file versions within specified range of save files.
EXECUTION-MODE = *FORCED-MOVE
All selected save files will be reorganized, irrespective of existence of obsolete file versions. Obsolete versions will not be copied. If there are no obsolete file versions, statement changes nothing but the location of the save files.
SAVE-DIRECTORY = *NO / *YES
Determines whether the directory file of the output archive used for this run is also to be written to the output volume as the last file of the run. The directory file is only written to the output volume for the last save file generated.
TO-STORAGE =
Defines the storage level on which save files are created after reorganization.
TO-STORAGE = *S2-STORAGE-LEVEL(...)
The save files are to be reorganized to storage level S2. Save files from disk storages reorganized to the separate save versions within one save file on S2 level.
The volumes to be used can be specified.
VOLUMES = *FROM-POOL
The volumes are to be taken from the volume pool of the specified archive, i.e. the pool of the archive directory or the associated MAREN pool.
VOLUMES = *FROM-OPERATOR
The volumes are to be allocated by the operator on request.
VOLUMES = list-poss(20): <vsn 1..6>
List of volume serial numbers, which will be requested in the specified order.
DEVICE-TYPE = *STD / <device>
Device type of the requested volumes. The device type must belong to the class “TAPE”. Only device types known in the system are accepted. In interactive mode, DEVICE-TYPE=? calls up a list of the available device types.
Unless otherwise specified, the preset value from the archive definition applies if a new save file is created (S2-DEVICE-TYPE).
LOCATION = *STD / *ANY / <alphanum-name 1..8>
Location used for requesting volumes. This location must be known to MAREN. If the location manager is in use, the location should be properly defined in MARENLM. Otherwise MAREN ignores the specified value.
If MAREN is not in use, you must specify for LOCATION the value *ANY, or *STD if *ANY is the default location of the archive.
LOCATION = *STD
The default location of the archive is used.
LOCATION = *ANY
No location is to be used.
TO-STORAGE = *S1-STORAGE-LEVEL
The generated save versions will be stored in save files (each save version is a separate save file) on the S1 pubset of S0-pubset for which the given version backup archive is a system archive or S0-pubset defined in PUBSET-ID or S1 volume set(s), which must have been defined earlier.
The save file is allocated according to the following rule:
- if the version backup archive is defined in SF-environment, the save files are created on the S1 pubset of S0-pubset for which the given version backup archive is a system archive (in case archive is given by its name) or S1 pubset of S0-pubset defined in PUBSET-ID (in case *SYSVERSION is given) which must have been defined earlier,
- if the version backup archive is defined in SM-environment, the save file is moved to special S1 volume set or to all HSMS-CONTROLLED volume sets depending on the definition in SM-PUBSETS-PARAMETERS of the SM-pubset.
TO-STORAGE = *PUBLIC-DISK(...)
This value is only valid in an SF pubset environment.
The save files are reorganized on to a pubset.
PUBSET-ID = <cat-id>
Catalog ID of the pubset.
TO-STORAGE = *NET-STORAGE(...)
This value is only valid in an SF pubset environment.
The save files are reorganized on to Net-Storage.
VOLUMES = list-poss(16): <vsn 1..6>
Specifies the Net-Storage volume to which the files are saved after reorganization. The specified volume must be accessible.
More than one Net-Storage volume can also be specified in a list (e.g. when there is more than one save task).
OPERATION-CONTROL =
Enables the user to define certain parameters which are relevant to the execution of the backup run.
OPERATION-CONTROL = *STD
The default values of the operands described below apply.
OPERATION-CONTROL = *PARAMETERS(...)
The operands controlling the backup run can be modified as follows:
REQUEST-NAME = *STD / <name 1..8>
Request name that can be used in the HSMS request management statements (DELETE-REQUESTS, RESTART-REQUESTS and SHOW-REQUESTS) to refer to this request. The name is extended internally by a prefix derived from the user ID (or SYSHSMS for the HSMS administrator) and a suffix in the form of a time stamp. Unless otherwise specified, the request name is formed by the short code “RVB#” and the TSN of the calling user task yyyy as follows: RVB#yyyy.
REQUEST-DESCRIPTOR = *NONE / <text 1..60>
It is possible to enter any text that describes the request in more detail.
This text is displayed at the operator console when the request is started. The text can be output using the HSMS statement SHOW-REQUESTS.
CONTROL-JV = *NONE / <filename 1..80 without-gen-vers>
Specifies the name of a job variable that HSMS supplies with various values corresponding to important actions performed by HSMS/ARCHIVE.
The HSMS administrator issuing the request can query the job variable to obtain an overview of the current processing status. How to use the job variable is described in detail in the “HSMS Vol. 1” manual [1] in the section “Job variable for request monitoring”.
EXPRESS-REQUEST = *NO / *YES
Determines whether tape access is to take place during the sessions defined for express requests.
WAIT-FOR-COMPLETION = *NO / *YES
Specifies whether the user wishes to wait until processing of his or her request has been completed (synchronous processing) or whether control is to be returned to the user after the validity of the HSMS statement has been checked (asynchronous processing). The maximum wait times for batch tasks and interactive tasks are different and are determined by preset global HSMS parameters.
Interactive tasks are permitted to carry out synchronous statement processing during tape sessions only.
TAPE-CONTROL =
Defines the parameters which are relevant for copying to tape.
TAPE-CONTROL = *STD
The preset values from the definition of the archive to be reorganized apply.
TAPE-CONTROL = *PARAMETERS(...)
The operands relevant for backup to tape can be modified as follows:
BLOCKING-FACTOR = *STD / <integer 2..15 2Kbyte > / *MAX
Blocking factor to be used for writing the save file to tape.
The default value *STD selects the blocking factor from the archive definition.
If this also contains the default value, the default values of the ARCHIVE parameters apply (SYSPAR.ARCHIVE.vvv: BLOCK-SIZE-TAPE for tapes, BLOCK-SIZE-T-C for magnetic tape cartridges).
For performance reasons it is recommmended to write blocks with maximum size to tape.
This will be achieved already by using the default values. In the case of magnetic tape cartridges this is a blocking factor of 128 (256k per block)
The values 2 to 15 should not be used anymore and are supported for compatibiliy reasons only.
*MAX selects the maximum blocking factor possible in the current BS2000 version independent of the settings in the archive and the ARCHIVE parameters. Currently this is the value 128.
UNLOAD-TAPE = *STD / *NO / *YES
Specifies whether or not tapes are to be unloaded after processing.
The preset value from the archive definition applies unless otherwise specified.
It is possible that HSMS will ignore the value of this operand in order to avoid irrational tape processing, for example to avoid unloading a tape several times while rewinding it.
DISK-CONTROL =
Defines the parameters which are relevant for copying to disk.
DISK-CONTROL = *STD
The preset values from the definition of the archive to be reorganized apply.
DISK-CONTROL = *PARAMETERS(...)
The operands relevant for copying to disk can be modified as follows:
PRIMARY-ALLOCATION = *STD / <integer 36..50331645 2Kbyte >
Size in PAM pages of the primary allocation for save file creation on disk (see the description of the CREATE-FILE command in the “Commands” manual [5]). Unless otherwise specified, the preset value from the archive definition applies.
SECONDARY-ALLOCATION = *STD / <integer 0..32767 2Kbyte >
Size in PAM pages of the secondary allocation for save file extension on disk (see the description of the CREATE-FILE command in the “Commands” manual [5]).
Unless otherwise specified (*STD), the preset value from the archive definition applies.
Values from 1 through 35 are not permitted.
WRITE-CHECK = *STD / *NO / *YES
Specifies whether a read-after-write check is to be performed after each write operation for error detection purposes. Note that read-after-write checking will result in longer execution times.
Unless otherwise specified, the preset value from the archive definition applies.
DESTROY-BY-DELETE = *STD / *NO / *YES
Specifies whether the storage space released by save file deletion is to be erased by overwriting it with binary zeros for data privacy reasons. Note that erasure by overwriting will result in longer execution times for save file deletion.
Unless otherwise specified, the preset value from the archive definition applies.
PERFORMANCE-ANALYSIS =
Specifies whether a statistics file is to be produced for each ARCHIVE subtask. ARCHIVE writes a new line to this statistics file:
when it opens a save file ARCHIVE.SAVE.FILE.
when it closes this save file.
whenever it begins saving or restoring a new file.
every 2 seconds while it is saving/restoring.
This gives a detailed overview of the ARCHIVE activities taking place during the save and restore operations.
PERFORMANCE-ANALYSIS = *NO
No statistics file is to be produced.
PERFORMANCE-ANALYSIS = *YES(...)
A statistics file is to be produced for each ARCHIVE subtask.
SEPARATOR = ; / <c-string 1..1>
Character that is inserted between the different fields in the statistics files. This enables programs such as EXCEL or LOTUS to differentiate the different fields.The default value is “ ; ”. This corresponds to the EXCEL default setting.
REPORT =
Serves to define whether a report is to be output for this reorganization request and to determine the scope of this report.
REPORT = *SUMMARY
A summary of the results of the reorganization request, including any error messages, is to be output.
REPORT = *FULL
A full report is to be output, including a list of all valid file versions which have been copied during reorganization.
REPORT = *NONE
No report is to be output.
OUTPUT =
Specifies where the report is to be output.
OUTPUT = *STD
The output destination of the report is determined by the default value that is defined by the global HSMS parameter OUTPUT.
OUTPUT = *PRINTER
The report for this reorganization request is to be printed.
OUTPUT = *NONE
No report is output. Nevertheless the report is available as a pdf file via the SE manager application Backup Monitoring, if the monitoring is activated in the global HSMS parameters.
OUTPUT = *MAIL
The report for this reorganization request is sent as an email attachment to the address which is entered in the caller’s user entry. If it is not possible to send the report by email, it is printed out.
OUTPUT = *LIBRARY-ELEMENT(...)
The report for this reorganization request is edited and output to the specified PLAM library element (type P). If this is not possible, the report is printed out.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the element. A type P element is created with a version which contains the user ID plus the date and time.
OUTPUT = <filename 1..54 without-gen-vers>
The report for this reorganization request is be edited and written to the specified file.If the file already exists, the following applies:
if it is a non-empty SAM file, it is continued
if it is not a SAM file, the report is printed.