Version 8.2.5
 —  Utilities  —

UNLOAD FILE: Unload Specified File

graphics/util_adauld.png

This document describes the syntax and parameters of the UNLOAD FILE function.


Essential Parameter

FILE

FILE specifies the number of the file to be unloaded. Neither the checkpoint file nor the security file can be unloaded.

Top of page

Optional Parameters and Subparameters

CODE: Cipher Code

If the file to be unloaded is ciphered, CODE must supply the appropriate cipher code.

DDISN: Create DD/ISN Output File of Unloaded ISNs

Specifying the DDISN parameter instructs ADAULD to write the list of unloaded ISNs to the sequential output file DD/ISN. DD/ISN 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

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.

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 DD/OUT1 or DD/OUT2 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 DD/PLOG sequential input data set.

If an online save tape created using ADASAV version 5.1 is to be used, the additional parameters PLOGNUM and SYN1 or SYN4 must be specified:

For online save tapes created using ADASAV version 5.2 or above, this information is included on the tape. 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. If the online save tape was created using ADASAV version 5.1, the parameters PLOGNUM and SYN1 or SYN4 must also be specified. PLOGNUM and SYN1 or SYN4 may be specified for online save tapes created using ADASAV version 5.2 or above 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.

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'
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.

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.

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 DD/PLOG sequential input data set.

If an online save tape created using ADASAV version 5.1 is to be used, the additional parameters PLOGNUM and SYN1 or SYN4 must be specified:

For online save tapes created using ADASAV version 5.2 or above, this information is included on the tape. 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. This parameter is required only if the device type to be used is different from the standard device type assigned to Temp by the ADARUN DEVICE 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.

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.

Top of page

Examples

Example 1:

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.

Example 2:

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.

Example 3:

ADAULD FILE=6,SORTSEQ=ISN

File 6 is to be unloaded. The records are to be unloaded in ascending ISN sequence.

Example 4:

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.

Example 5:

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.

Example 6:

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.

Example 7:

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.

Top of page