ADAULD (File Unloading)

This document describes the utility "ADAULD".

The following topics are covered:


Functional Overview

The utility ADAULD unloads an Adabas file, i.e. records are retrieved from a database or an Adabas backup copy, and written to a sequential file.

The main reasons for unloading a file are:

  • To change the space allocation, to reduce the number of logical extents assigned to the index, Address Converter or Data Storage, and/or to change the padding factor. In this case, the file has to be unloaded, deleted and reloaded. These features are also available with ADAORD;

  • To create one or more test files, all containing the same data. This procedure requires a file to be unloaded and then reloaded using a different file number. This feature is also available with ADAORD;

  • To extract data from a file for subsequent input to ADAMUP. This is useful for moving records from a production database to an archive database;

  • To re-establish a file that has been archived on an Adabas backup copy.

When unloading a file from a database, the records may be unloaded in:

Logical sequence

The records are unloaded in an ascending sequence based on the values of a user-specified descriptor;

ISN sequence

The records are unloaded in ascending ISN sequence;

Physical sequence

The records are unloaded in the order in which they are physically located in Data Storage.

Unloading in logical or ISN sequence requires the nucleus to be active. The nucleus is not required when unloading in physical sequence, provided ADAULD has access to the database container files.

When unloading from an Adabas backup copy, the records are unloaded in the sequence in which they were stored by ADABCK. This is generally in ascending data RABN sequence. However, this sequence cannot be guaranteed when the DRIVES option was used or when the dump was made online (please refer to the DRIVES option of the utility ADABCK for more detailed information).

The unloaded records are output in compressed format and are identical to the records produced by the compression utility ADACMP. Since each data record is preceded by its ISN, these ISNs can be used as user ISNs when reloading the file (please refer to the USERISN option of the utility ADAMUP for more detailed information).

The user can specify that the descriptor values required to recreate the index for the file are omitted during the UNLOAD process (SHORT option). This reduces the unload processing time. This option must not be used if the output is intended as direct input for ADAMUP.

Note:
If the file contains collation descriptors, the ICU version is not changed for the unloaded data. You can load the data with ADAMUP to a file with the same fields, but a different ICU version only if the file is empty, and if you use the NEW_FDT option for ADAMUP.

After completion, ADAULD returns one of the following exit status values:

0

Records have been successfully unloaded, and no database corruption was detected.

12

The unload was successful, but corrupted data records were detected, which were not unloaded. It is recommended that you run ADAVFY in order to obtain more information about the database corruptions.

15

The unload was successful, but no records were unloaded. In scripts, you can check for this status value if further activities are required only after unloading at least one record.

255

Unload was not successful.

This utility is a single-function utility.

Procedure Flow

graphics/adauld1.png

BACKUP_COPY Function

The sequential files ULD00n, ULDDTA, ULDDVT can have multiple extents. For detailed information about files with multiple extents, see Adabas Basics, Using Utilities.

graphics/adauld2.png

DBID Function

The sequential files ULDDTA, ULDDVT can have multiple extents. For detailed information about files with multiple extents, see Adabas Basics, Using Utilities.

Data Set Environment
Variable/
Logical Name
Storage
Medium
Additional Information
Associator ASSOx Disk, Tape see note 2
Data storage DATAx Disk, Tape see note 2
Backup copy ULD00n Disk, Tape Output of ADABCK's DUMP function, input for ADAULD
Unloaded data ULDDTA Disk, Tape (see note 1)  
Unloaded descriptor values ULDDVT Disk, Tape (see note 1)  
Control statements stdin/
SYS$INPUT
  Utilities Manual
ADAULD messages stdout/
SYS$OUTPUT
  Messages and Codes
Temporary storage TEMPx Disk, Tape see note 3 and 4
Work storage WORK1 Disk, Tape see note 2

Notes:

  1. A named pipe can be used for this sequential file (not on OpenVMS) see Adabas Basics, Using Utilities for details).
  2. Required by offline unload. Will also increase the speed of online unload using physical sequence.
  3. Only required if unloading from a backup copy with the online option being used. If the utility is executed offline, WORK may be used as TEMP if there is no Autorestart pending, by setting the environment variable TEMP1 to the same value as WORK1.
  4. The ADAULD BACKUP_COPY function does not read the DBxxx.INI file to find TEMP, therefore you must specify TEMP via environment variables.

Checkpoints

The following table shows the nucleus requirements for each function and the checkpoint written:

Function Nucleus must be active Nucleus must NOT be active Nucleus is NOT required Checkpoint written
BACKUP_COPY     X -
DBID X(see note 1) X(see note 3) X(see note2) SYNX

Notes:

  1. When unloading in logical sequence or ISN sequence or when the database container file cannot be accessed by ADAULD (e.g. when unloading from a remote node). Also applies if a file contains LOB data, because LOB data must be unloaded in logical sequence. Also applies if the search buffer and value buffer are provided.
  2. When unloading in physical sequence and ADAULD has access to the database container files.
  3. When unloading an Adabas system file.

Control Parameters

The following control parameters are available:

     BACKUP_COPY = number, FILE = number 
                   [,FDT]
                   [,NUMREC = number]
D                  [,[NO]ONLINE] 
D                  [, [NO]SHORT | [NO]SINGLE_FILE ]
                   [,SKIPREC = number] 
D                  [,[NO]USEREXIT]

     DBID = number , FILE = number
            [,FDT] 
D           [,[NO]LITERAL]
            [,NUMREC = number]
            [,SEARCH_BUFFER = string, VALUE_BUFFER = string] 
D           [, [NO]SHORT | [NO]SINGLE_FILE  ]
            [,SKIPREC = number] 
            [,SORTSEQ = { string | ISN } ]
            [,STARTISN = number]
D           [,[NO]USEREXIT]

BACKUP_COPY

BACKUP_COPY = number
              ,FILE = number 
              [,FDT]
              [,NUMREC = number]
              [,[NO]ONLINE] 
              [,[NO]SHORT | [NO]SINGLE_FILE ]
              [,SKIPREC = number] 
              [,[NO]USEREXIT]

This function unloads records from an Adabas backup copy. You are not allowed to specify a LOB file. "BACKUP_COPY=number" specifies the ID of the database from which the backup copy was derived, and "FILE=number" specifies the file number. Both offline and online backup copies can be used. If a LOB file is assigned to the file specified, a partial reload using the ADAMUP parameters NUMREC, SKIPREC is not possible.

FDT

This parameter displays the FDT of the file to be unloaded.

FILE = number

This parameter specifies the file to be unloaded.

NUMREC = number

This parameter limits the number of data records retrieved from the file when unloading. All records are unloaded if NUMREC is omitted and SKIPREC is not specified. You cannot use NUMREC if a LOB file is assigned to the file to be reloaded.

[NO]ONLINE

This option indicates whether the backup copy might contain online data storage blocks for the file to be unloaded.

If the backup copy is expected to contain online data storage blocks, two passes are made when processing the backup copy. This is because the most recent version of each data storage block has to be found. Setting this option to NOONLINE unloads in one pass and saves a considerable amount of processing time, at the risk of ADAULD terminating with an error message if an online data storage block is detected.

The default used depends on whether or not the Adabas nucleus was active when the backup was made.

[NO]SHORT

This option indicates whether the descriptor values used to build up the index should be included in the output or omitted.

If SHORT is specified, no descriptor values are unloaded.

If the output is intended as direct input for the mass update utility, the file must be unloaded in NOSHORT mode.

SHORT and SINGLE_FILE are mutually exclusive.

NOSHORT is the default.

[NO]SINGLE_FILE

If this option is set to SINGLE_FILE, ADAULD writes the DVT and DATA information to a single data set (ULDDTA).

SINGLE_FILE and SHORT are mutually exclusive.

The default is NOSINGLE_FILE.

SKIPREC = number

This parameter specifies the number of records to be skipped before unloading is started. You cannot use SKIPREC if a LOB file is assigned to the file to be reloaded.

[NO]USEREXIT

A user-written routine is dynamically loaded. A pointer to an input parameter block and a pointer to an output parameter are passed with each call (please see the include file adauex.h for more information). For each record retrieved from the database, the decision can be made whether to unload the record (write it to the unload file), skip it or terminate execution immediately.

The environment variable/logical name ADAUEX_7 must point to a user-written routine.

See Adabas Basics, User Exits and Hyperexits for more details.

NOUSEREXIT is the default.

DBID

DBID = number 
       ,FILE = number
       [,FDT]
       [,[NO]LITERAL
       [,NUMREC = number] 
       [,SEARCH_BUFFER = string]
       [,[NO]SHORT | [NO]SINGLE_FILE ]
       [,SKIPREC = number] 
       [,SORTSEQ = { string | ISN }]
       [,STARTISN = number] 
       [,[NO]USEREXIT]
       [,VALUE_BUFFER = string]

This function unloads records from the specified database.

FDT

This parameter displays the FDT of the file to be unloaded.

FILE = number

This parameter specifies the file to be unloaded. You are not allowed to specify a LOB file.

[NO]LITERAL

If this option is set to LITERAL, leading blanks and lower case characters can be specified in the value buffer and remain relevant in the string, i.e. they are not removed or converted to upper case. If NOLITERAL is set, lower case characters will be transformed to upper case, and leading blanks will be suppressed except when the value is specified as a hexadecimal value.

NOLITERAL is the default.

NUMREC = number

This parameter limits the number of data records retrieved from the file when unloading. All records of the file are unloaded if NUMREC is omitted and SKIPREC or STARTISN are not specified.

SEARCH_BUFFER = string

This parameter is used to restrict the unloaded records to those which meet the selection criterion provided. The selection criterion must be provided according to the syntax for search buffer entries as described in the Command Reference Manual.

The maximum length of this parameter is 200 bytes. For complex entries, use the following method:

adauld: search_buffer=aa,20,a,d,\
> ab,10,a.

ADAULD will concatenate this to:

aa,20,a,d,ab,10,a.

The values which correspond to the selection criterion are provided by the VALUE_BUFFER parameter.

[NO]SHORT

This option indicates whether the descriptor values used to build up the index should be included in the output or omitted.

If SHORT is specified, no descriptor values are unloaded.

If the output is intended as direct input for the mass update utility, the file must be unloaded in NOSHORT mode.

SHORT and SINGLE_FILE are mutually exclusive.

NOSHORT is the default.

[NO]SINGLE_FILE

If this option is set to SINGLE_FILE, ADAULD writes the DVT and DTA information to a single data set (ULDDTA).

SINGLE_FILE and SHORT are mutually exclusive.

The default is NOSINGLE_FILE.

SKIPREC = number

This parameter specifies the number of data records to be skipped before unloading is started.

When used together with the STARTISN parameter, positioning is carried out before skipping.

SORTSEQ = string

This parameter controls the sequence in which the file is unloaded. If specified, it may either contain the field name of a descriptor, sub- or superdescriptor (1) or the keyword `ISN' (2). The default is physical sequence (3).

  1. Logical sequence

    If a string specifies a field name of a descriptor or sub/superdescriptor, the records are unloaded in ascending logical sequence of the descriptor values to which the field name refers. The field name must not refer to a descriptor contained within a periodic group.

    If the field name refers to a descriptor which is a multiple-value field, the same record may be unloaded more than once (once for each different descriptor value in the record). Therefore, it is not recommended to use this type of descriptor to control the unload sequence.

    If the field name refers to a descriptor defined with the NU or NC option, the records with a null value for the descriptor are not unloaded.

  2. ISN sequence

    If `ISN' is specified, the records are unloaded in ascending ISN sequence.

  3. Physical sequence

    If the SORTSEQ parameter is omitted, the records are unloaded in the physical sequence in which they are stored in the Data Storage.

    If a search buffer has been specified and the SORTSEQ parameter has been omitted, the records are unloaded in ascending ISN sequence.

STARTISN = number

If the SORTSEQ = ISN option is used or a search buffer is provided, the STARTISN parameter may be specified to start unloading at a given ISN rather than from the lowest ISN in the file. If the specified ISN does not exist, unloading starts at the next highest ISN found.

[NO]USEREXIT

A user-written routine is dynamically loaded. A pointer to an input parameter block and a pointer to an output parameter are passed with each call (please see the include file adauex.h for more information). For each record retrieved from the database, the decision can be made whether to unload the record (write it to the unload file), skip it or terminate execution immediately.

The environment variable/logical name ADAUEX_7 must point to a user-written routine.

See Adabas Basics, User Exits and Hyperexits for more details.

NOUSEREXIT is the default.

VALUE_BUFFER = string

If a selection criterion is specified with the SEARCH_BUFFER parameter, this parameter is used to supply the values which correspond to the selection criterion. The maximum length of this parameter is 2000 bytes.

Note:
See also [NO]LITERAL, which controls the conversion of the value buffer to upper case.

Examples

Example 1

adauld: backup_copy = 3, file = 6

File 6 on the backup copy of database 3 is unloaded. A TEMP data set and two passes through the backup copy may be required, depending on the default setting of the [NO]ONLINE option.

Example 2

adauld: backup_copy = 3, file = 6
adauld: single, noonline

The same file is unloaded. Both data records and descriptor value table entries are written to the same output file. The backup copy is processed in one pass as no online blocks are expected. No TEMP data set is required.

Example 3

adauld: dbid = 3, file = 6, skiprec = 100

File 6 in database 3 is unloaded. The records are unloaded in the physical sequence in which they are stored in the Data Storage. The first 100 records found are not written to the output files.

Example 4

adauld: dbid = 3, file = 6
adauld: numrec = 10
adauld: sortseq = ab
adauld: short

Ten records from file 6 in database 3 are unloaded. The values of the descriptor AB are used to control the sequence in which the records are retrieved. The values required to re-create the inverted list when reloading are omitted.

Example 5

adauld: dbid = 3, file = 6, sortseq = isn, startisn = 123

File 6 in database 3 is unloaded. The records are unloaded in ascending ISN sequence starting at ISN 123.

TEMP Data Set Space Estimation

When unloading from an Adabas backup copy without the NOONLINE option set, the TEMP data set is required to accumulate information about online block occurrences.

The formula TRH=DRH/1000 can be used as a rough estimate with the default TEMP block size (4 kilobytes).

The following formula may be used to calculate the exact requirements:

X = ENTIRE ((DRH / BSTD) * 4)

TRH = X + ENTIRE (X / BSTD / 8) + 1

where:

ENTIRE

the next highest integer

BSTD

TEMP block size in bytes.

DRH

highest Data Storage RABN in the database on the backup copy. The SUMMARY function of the ADABCK utility can be used to obtain this number.

TRH

highest RABN required on TEMP.

Restart Considerations

ADAULD has no restart capability. An interrupted ADAULD run must be re-executed from the beginning.