This document describes the syntax and parameters of the UNLOAD FILE function.
- FILE
FILE specifies the number of the file to be unloaded. Neither the checkpoint file nor the security file can be unloaded.
- CODE: Cipher Code
If the file to be unloaded is ciphered, CODE must supply the appropriate cipher code.
- DDISN: Create DDISN Output File of Unloaded ISNs
Specifying the DDISN parameter instructs ADAULD to write the list of unloaded ISNs to the sequential output file DDISN. DDISN is structured so that it can be used as input to ADALOD UPDATE for the purpose of deleting the unloaded records.
If the DDISN keyword is specified
but the DDISN file is missing in the JCL, ADAULD terminates with error 081.
and SORTSEQ specifies a hyperdescriptor or descriptor that refers to a multiple-value field, ADAULD terminates with error 133 because the DDISN may contain duplicate ISNs.
- ERRLIM: Error Threshold
ERRLIM sets the maximum number of nucleus response codes accepted by ADAULD before operation terminates. The default setting is one, which means that the first error terminates ADAULD with error 124.
The ERRLIM value may be set higher than one to tolerate conditions that occur intermittently such as response code 255 (ADARSP255 - all attached buffers allocated). In this case, the utility terminates with return code 8 and no user abend. The output file of ADAULD can be used, although records may be missing depending on the nucleus response code returned.
- ETID: Multiclient File Owner ID
When unloading multiclient files, the ETID parameter can be used to restrict UNLOAD processing to only the records owned by the specified user. If the ETID parameter is omitted, all records are unloaded.
If the SELCRIT/SELVAL parameters are specified for a multiclient file, the ETID parameter must also be specified.
- LPB: Prefetch Buffer Size
LPB specifies the size of the internal prefetch buffer. The maximum value is 32767 bytes.
By default, ADAULD attempts to make the prefetch buffer as large as possible to achieve the best performance. The LPB parameter gives the user the option of making the prefetch buffer smaller. This might be advisable, for example, if heavy use of prefetching causes ADAULD to consume too much nucleus resource relative to other users.
The default value depends on the length of the intermediate user buffer set by the ADARUN LU parameter. ADAULD subtracts the space required to accommodate the Adabas control information (108 bytes) and the specified maximum compressed record length (LRECL) from the LU value to determine the default LPB value. The result must be equal to or less than the maximum value allowed for LPB; that is, 32767 bytes.
The default value for LU is set to 65535 bytes, the maximum size, to accommodate the record buffer of utilities such as ADAULD that need the nucleus. If the LU value is too small, ADAULD may reduce the specified value for the LPB parameter.
- LRECL: Maximum Compressed Record Length
LRECL specifies, in bytes, the maximum compressed record length (including DVT) to be returned.
This length is used as an Adabas record buffer length. If this value is too small, a response code 53 (ADARSP053) occurs. The default is 4000 bytes; the maximum allowed is 32760 bytes.
Caution:
Please be sure to verify that the output data set is defined so it can store a record in this size.- MODE=SHORT: Exclude Descriptor Information
This parameter indicates whether the descriptor information used to build the normal index and upper index are to be included in the output.
If MODE=SHORT is specified, no descriptor information will be unloaded, and all descriptor information is stripped from the field definition table (FDT) when it is written to the output data set.
If the output is to be used as direct input to the ADALOD utility, the file will have no descriptors.
In the case of superdescriptors, MODE=SHORT unloads them as superfields. If the output is used as direct input to ADALOD, the loaded file will have superfields.
- NOUSERABEND: Termination without Abend
When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.
Note:
When NOUSERABEND is specified, we recommend that it be specified as the first parameter of the utility function (before all other parameters). This is necessary to ensure that its parameter error processing occurs properly.- NUMOUT: Number of Output Files
NUMOUT specifies the number of output files to be produced. If the number is greater than one, user exit 9 must be used to control DDOUT1 or DDOUT2 output file selection. For additional information, see the Adabas DBA Reference documentation. Permitted values are 1 (default) and 2.
- NUMREC: Number of Records to Be Unloaded
NUMREC limits the number of records to be unloaded. No limit will be in effect if the parameter is omitted.
- PASSWORD: File Password
The PASSWORD parameter must be specified if the file to be unloaded is password-protected.
- PLOGNUM: Protection Log Number
When SAVETAPE is specified and an online save tape is to be used as input to ADAULD, the corresponding protection log is expected as a DDPLOG sequential input data set. You can specify PLOGNUM or SYN1 or SYN4 to override the tape information.
- SAVETAPE
SAVETAPE is used to unload a file from a save tape. This is useful when moving a file from a save tape with one block size to a database with another, or when using a file from a save tape in one or another test environment.
If an online save tape is used, the TEMPDEV parameter must also be specified. PLOGNUM and SYN1 or SYN4 may be specified for online save tapes to override the information included on the tape.
For more information, see the section Processing a Save Tape as Input.
The SORTSEQ and SELCRIT parameters may not be used with SAVETAPE.
The ETID parameter may not be used with SAVETAPE. User exit 9 must be used to select records for a particular client of a multiclient file. For more information, see the section ADAULD User Exit 9.
If the file to be unloaded from the save tape is ciphered, the CODE parameter must be specified as usual.
Note:
Special SAVETAPE functions are available for use with the Adabas Delta Save Facility. For more information, see the Adabas Delta Save Facility Facility documentation.- SELCRIT: Selection Criterion
The SELCRIT parameter may be used to restrict the unloaded records to those which meet the selection criterion provided. The selection criterion must be provided using the search buffer syntax, as described in the Adabas Command Reference documentation.
For multiple criteria, you can specify each criterion with a separate ADAULD SELCRIT statement, as follows:
ADAULD SELCRIT ='AA, 20, A, D,' ADAULD SELCRIT ='AB, 10, A.'ADAULD concatenates this to:
'AA, 20, A, D, AB, 10, A.'The values that correspond to the selection criterion must be provided using the SELVAL parameter.
Caution:
If the value buffer, SELVAL parameter value, exceeds the total length of the fields defined in the search buffer, SELCRIT parameter value, those bytes in the value buffer beyond the total length of the search buffer fields will be ignored and not used in the search. So be sure to specify any search buffer field lengths in the SELCRIT parameter that exceed any search buffer field default lengths. Failure to do this could result in the wrong records being unloaded or the records that were wanted, not being found.- SELVAL: Values for Selection Criteria
SELVAL specifies the values corresponding to the selection criteria specified with the SELCRIT parameter. The value formats are the same as those used for the Value Buffer, as described in the Adabas Command Reference documentation.
Values can be on multiple lines. Packed decimal or binary values can be in hexadecimal format, as shown in the following example:
SELVAL='PARIS ' SELVAL=X'00149C' SELVAL='AB100'Caution:
If the value buffer, SELVAL parameter value, exceeds the total length of the fields defined in the search buffer, SELCRIT parameter value, those bytes in the value buffer beyond the total length of the search buffer fields will be ignored and not used in the search. So be sure to specify any search buffer field lengths in the SELCRIT parameter that exceed any search buffer field default lengths. Failure to do this could result in the wrong records being unloaded or the records that were wanted, not being found.- SORTSEQ: Unload Sequence
SORTSEQ specifies the sorting sequence for unloaded ISNs. If SORTSEQ is not specified, ISNs are unloaded in physical sequence.
If a descriptor name is specified, the records are unloaded in the ascending logical sequence of the descriptor values. You can specify the name of a descriptor, subdescriptor, superdescriptor, or hyperdescriptor. Do not refer to a field in a periodic group.
MU must be specified if the descriptor name refers to a multiple-value field. In this case, the same record is unloaded once for each different value for the descriptor in the record in ascending value order. If MU is not specified (the default), ADAULD rejects MU descriptors and issues an error message.
NU must be specified if the descriptor name refers to a field defined with the null suppression (NU) option. In this case, records of the descriptor that contain null values are not unloaded. If NU is not specified (the default), ADAULD rejects NU descriptors.
Note:
Even when the descriptor field is not null suppressed, the record is not represented in the inverted list if the descriptor field or a field following it has never been initialized (held a value). Therefore, the record will be dropped when the utility is executed.If SORTSEQ=ISN is specified, the records are unloaded in ascending ISN sequence.
If both SELCRIT/SELVAL and SORTSEQ are specified, the records are sorted in the Work pool area of the nucleus. Therefore, the ADARUN LS and LWP session parameters must provide enough space; see the Adabas Operations documentation for descriptions of the LS and LWP parameters.
- STARTISN: Starting ISN
STARTISN is used with the SELCRIT/SELVAL and SORTSEQ parameters to restrict the unloaded records according to ISN. Specifying STARTISN alone is not allowed.
Specifying STARTISN with SELCRIT/SELVAL causes all records with ISNs equal to or greater than the STARTISN-specified value and with field contents satisfying the SELCRIT/SELVAL criterion to be unloaded in ascending ISN sequence by descriptor name.
Specifying STARTISN with SORTSEQ=ISN unloads all records beginning with the STARTISN-specified record in ISN sequence.
- SYN1|SYN4: Starting Block Number
When SAVETAPE is specified and an online save tape is to be used as input to ADAULD, the corresponding protection log is expected as a DDPLOG sequential input data set.
You can specify PLOGNUM or SYN1 or SYN4 to override the tape information.
- TEMPDEV: Temporary Storage Device Type
When SAVETAPE is specified and an online save tape is to be used as input to ADAULD, a temp data set is used to store intermediate data during processing. The TEMPDEV parameter indicates the device type to be used for the temp data set. Refer to Enhancements to TEMP and SORT Processing in ADAINV, ADALOD and ADAULD for more details on specifying the TEMPDEV parameter.
The block size of the temp data set must be at least as large as the largest Data Storage block size of the file to be unloaded, plus 16 bytes.
- TEMPSIZE: Temporary Storage Size
TEMPSIZE specifies the size of the temp data set for the file. The size can be either in cylinders or blocks (followed by a "B").
The temp data set must be large enough to store all Data Storage blocks from the protection log. In the worst case scenario, it must have as many blocks as the file has Data Storage blocks but need not be larger than the PLOG data set. If the temp data set is too small, ADAULD error-136 (temp data set too small) is returned. Refer to Enhancements to TEMP and SORT Processing in ADAINV, ADALOD and ADAULD for more details on specifying the TEMPSIZE parameter.
- TEST: Test Syntax
This parameter tests the operation syntax without actually performing the operation. Only the syntax of the specified parameters can be tested; not the validity of values and variables.
- UTYPE: User Type
The user type to be in effect for the unload process.
If EXU (the default) is specified, the file cannot be updated, but other users can read the file.
If EXF is specified, only ADAULD can use the file; no other users can read or write the file.
When the TEMPSIZE parameter is omitted, various enhancements to TEMP processing are available to the user. See Enhancements to TEMP and SORT Processing in ADAINV, ADALOD and ADAULD for details.
ADAULD FILE=6
File 6 is to be unloaded. The records are to be unloaded in the sequence in which they are physically positioned in Data Storage.
ADAULD FILE=6,SORTSEQ=AA
File 6 is to be unloaded. The values for the descriptor AA are to be used to control the sequence in which the records are to be unloaded.
ADAULD FILE=6,SORTSEQ=ISN
File 6 is to be unloaded. The records are to be unloaded in ascending ISN sequence.
ADAULD FILE=6,SORTSEQ=ISN,STARTISN=10000
File 6 is to be unloaded. The records are to be unloaded in ascending ISN sequence. Only records which have an ISN equal or greater than 10000 are to be unloaded.
ADAULD FILE=6,SORTSEQ=AB,MODE=SHORT
File 6 is to be unloaded. The values for the descriptor AB are to be used to control the sequence in which the records are to be unloaded. The entries used to create the normal index and upper index are not to be unloaded. All descriptor information is removed from the field definition table (FDT) in the output.
ADAULD FILE=6,SELCRIT='AA,1,S,AA,2.',SELVAL='AMM'
File 6 is to be unloaded. Only records with AA=A through MM are to be unloaded. The records are returned in ISN sequence.
ADAULD FILE=6,UTYPE=EXF
File 6 is to be unloaded. The user type is indicated as EXF which locks the file during unload processing, preventing other users from reading or writing the file.