Version 7.4.4
 —  Utilities  —

UPDATE: ADD/Delete Records

Warning:
If ADALOD UPDATE ends abnormally (due to insufficient space, for example), updates made to the file before the abnormal ending cannot be "backed out". Software AG therefore recommends that you perform ADASAV SAVE on the file before you run ADALOD UPDATE.

The UPDATE function adds and/or deletes a large number of records (ISNs) to and/or from an existing file. A single UPDATE operation can both add and delete ISNs.

Records to be added must be in compressed (ADACMP or ADAULD output) form and be in the DDEBAND/EBAND input dataset.

ISNs to be deleted must be specified by either or both of the DDISN and DELISN parameters.

Notes:

  1. The UPDATE function cannot be used with an Adabas system file if the Adabas nucleus is active, and cannot be used to change the checkpoint or security files.
  2. A multiclient file cannot be made part of an expanded file, and an expanded file cannot be converted to a multiclient file.

graphics/util_adalod_update.png

This document covers the following topics:


Essential Parameters

FILE: File Number

FILE specifies the number of the file to be updated. If a component file of an Adabas expanded file is specified, only that component file is updated; the other component files must be updated in separate UPDATE operations.

SORTSIZE: Sort Size

SORTSIZE is the number of blocks or cylinders available for the sort dataset.

TEMPSIZE: Temporary Storage Size

TEMPSIZE is the number of blocks or cylinders available for the temp dataset.

Top of page

Optional Parameters and Subparameters

ACRABN: Starting RABN for Address Converter

ACRABN causes additional space allocation for the address converter to begin at the specified RABN. ACRABN is effective only if MAXISN specifies an increase for the file's address converter.

ASSOVOLUME: Associator Extent Volume

Note:
The value for ASSOVOLUME must be enclosed in apostrophes.

ASSOVOLUME is effective only if MAXISN specifies an increase for the file's address converter.

ASSOVOLUME specifies the volume on which the file's address converter extents is to be allocated. If the requested number of blocks cannot be found on the specified volume, ADALOD retries the allocation while disregarding the ASSOVOLUME parameter.

If ACRABN is specified, ADALOD ignores the ASSOVOLUME value when allocating the address converter extent type. If ASSOVOLUME is not specified, the file's Associator space is allocated according to ADALOD's default allocation rules.

DDISN: Read ISNs to be Deleted from Sequential Dataset

If DDISN is specified, ISNs to be deleted are read from the DDISN/ISN sequential dataset. If both the DDISN and DELISN parameters are specified, the ISNs from the two lists are merged. The DDISN/ISN dataset must have variable or variable blocked records. See the section Formats for Specifying ISNs for more information.

When the UPDATE function is executed, all ISNs are first read and stored in the ISN pool in the order they occur. The size of the ISN pool (specified by LIP) must be large enough to store all data read from DDISN/ISN.

The records are then sorted in ascending order. Overlapping ranges and duplicate ISNs are not allowed. ISNs not found during processing are ignored.

When deleting ISNs from an Adabas expanded file, you can specify the complete ISN list for all component files; the UPDATE function automatically selects only the ISNs that are appropriate for the component file being processed.

DELISN: ISNs to be Deleted

DELISN specifies a list of the ISNs of records to be deleted. If both DDISN and DELISN are specified, the ISNs from the two lists are merged. A range list may be specified as:

DELISN=10-80,90,100-110 

Overlapping ranges and duplicate ISNs are not allowed. You can specify, at most, 32 single ISNs or ISN ranges. When deleting ISNs from an Adabas expanded file, you can specify the complete list for all component files. The UPDATE function selects the appropriate ISNs from the list and deletes them from the component file.

DSREUSE: Data Storage Reusage

DSREUSE indicates whether or not Data Storage space that becomes available as a result of a record deletion is to be reused.

This parameter is in effect for the execution of the UPDATE function only. The permanent setting of DSREUSE is not changed. That permanent setting is the default if this value is not specified.

ETID: Multiclient File Owner ID

The ETID parameter assigns a new owner ID to all records being added to an existing multiclient file. The owner ID is automatically adjusted to the length for owner IDs specified by LOWNERID when the multiclient file was last loaded. If no ETID is specified, all loaded records keep their owner IDs specified on the input source.

The ETID parameter must be specified if the existing file is multiclient and the input file was not unloaded from a multiclient file. ETID must not be specified if the existing file is a non-multiclient file.

Note:
If the ETID parameter is used, the ADALOD utility requires an active nucleus. The nucleus will translate the ETID value into the internal owner ID value.

ISNREUSE: ISN Reusage

ISNREUSE indicates whether the ISN for a deleted record can be reassigned to a new record.

This ISNREUSE setting is in effect only during execution of the UPDATE function. The permanent ISNREUSE setting is unchanged. The permanent setting is the default if this value is not specified.

LIP: ISN Work Pool Size

LIP specifies the size of the work pool for containing ISNs to be deleted. Four bytes per ISN and eight bytes per ISN range are required in this pool. The value may be specified in bytes as a numeric value ("2048") or in kilobytes as a value followed by "K" ("2K"). The default for LIP is 2000 bytes.

LWP: Work Pool Size

LWP specifies the size of the work pool to be used for descriptor value sorting. The value can be specified in bytes or kilobytes followed by a "K". If no value is specified, the default is 1048576 bytes (or 1024K); however, to shorten ADALOD run time for files with very long descriptors or an unusually large number of descriptors, set LWP to a higher value. To avoid problems with the Sort dataset, a smaller LWP value should be specified when updating relatively small files.

The minimum work pool size depends on the sort dataset's device type:

Sort Device Minimum LWP Minimum LWP
Bytes Kilobytes
2000 106496 104K
2314 090112 88K
3375 131072 128K
3380 139264 136K
3390 159744 156K
MAXISN: Highest ISN to be Allocated to the File

The MAXISN parameter may be used to specify a new setting for the file. This parameter should be used if the current record count plus the number of ISNs (records) to be added exceeds the current MAXISN setting. The specified larger value determines the additional space required for the address converter, and causes ADALOD to allocate a new extent. A smaller MAXISN value causes no change in the address converter space.

Note:
The MAXISN setting for a file cannot be increased if the file was last loaded with NOACEXTENSION active.

The MAXISN setting should be increased by an amount suitable for all planned expansion; this avoids using up the address converter extent too quickly, and alleviates the need to either unload and reload the file or run the ADAORD REORFASSO utility because the maximum of five address converter extents has been allocated.

With the optional ACRABN parameter, the beginning of the new address converter extent can be set to a specific RABN number. See the ACRABN parameter description for more information.

If the MAXISN parameter is omitted, ADALOD allocates new address converter extents only if the old MAXISN value is exceeded.

NOUSERABEND: Termination without Abend

When an error is encountered while the function is running, the utility 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.

NUMREC: Limit Number of Records to Be Added

NUMREC limits the number of records to be added. If NUMREC is specified, ADALOD processing terminates after adding the number of records specified (unless an end-of-file condition on the input dataset has already caused ADALOD termination). If this parameter is omitted, all input records are added.

If the input dataset contains more records than specified by NUMREC, ADALOD adds the number of records specified by NUMREC and then terminates with condition code 4.

PASSWORD: File Password

If the file to be updated is password-protected, the parameter must be used to provide a valid password. There is no default for PASSWORD.

RESTART: Restart Interrupted ADALOD Execution

RESTART forces an interrupted ADALOD run to be restarted, beginning with the last "restart point" reached before the interruption. The "restart point" is the latest point of execution that can be restored from the Temp dataset.

If ADALOD is interrupted by a defined error condition, ADALOD issues a message indicating whether or not a restart is possible.

When restarting the ADALOD operation, the following parameters may be changed:

No other parameters can be changed. The DDEBAND/EBAND, DDFILEA/FILEA and DDISN/ISN datasets must remain the same.

SAVEDREC: Save Deleted Records on a Sequential File

SAVEDREC indicates that deleted records are to be written to a sequential dataset. The format of the dataset is identical to that created by the ADAULD utility with the MODE=SHORT option.

SKIPREC: Number of Records to Be Skipped

SKIPREC is the number of input records to be skipped before beginning to process updates. The default is 0 (no records are skipped).

SORTDEV: Sort Device Type

ADALOD uses the sort dataset to sort descriptor values. The SORTDEV parameter indicates the device type to be used for this dataset. This parameter is required only if the device type to be used is different from that specified by the ADARUN DEVICE parameter.

TEMPDEV: Temporary Storage Device Type

ADALOD uses the temp dataset to store intermediate data. The TEMPDEV parameter indicates the device type to be used for this dataset. 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.

TEST: Test Syntax

The TEST 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.

USERISN: User ISN Assignment

USERISN=YES indicates that the USERISN option for the file is to be in effect, and that the ISN for each new record is being supplied by the user in the input data. If USERISN=NO, Adabas assigns the ISN for each new record.

The specified USERISN setting is effective only while the UPDATE function is executing. The permanent USERISN setting is not changed, and is the default if this parameter is not specified.

When performing an ADALOD UPDATE function on a file with a hyperdescriptor for which the hyperexit changed the ISNs of descriptor values, USERISN=YES is no longer required for the aDD/load operation.

When adding records from a non-USERISN=YES file, the ADALOD parameter USERISN=NO must be specified and the file to be updated must have the USERISN option. This feature is useful for Adabas Text Retrieval (TRS).

Top of page

Examples

Example 1:

ADALOD  UPDATE FILE=6,MAXISN=18000
ADALOD         TEMPSIZE=10,SORTSIZE=5  

Records are to be added to file 6. The MAXISN for the file is to be increased to 18,000.

Example 2:

ADALOD  UPDATE FILE=7,TEMPSIZE=10,
ADALOD         ETID=USER3,SORTSIZE=5

Records with user's owner ID of USER3 are to be added to multiclient file 7.

Example 3:

ADALOD  UPDATE FILE=8,DELISN=1000-1999,5000-5999
ADALOD         TEMPSIZE=10,SORTSIZE=5

The records with ISNs 1,000 to 1,999 and 5,000 to 5,999 are to be deleted from file 8. If an input dataset is provided, records are to be added.

Example 4:

ADALOD  UPDATE FILE=6
ADALOD         DDISN,SAVEDREC
ADALOD         TEMPSIZE=10,SORTSIZE=5

Records are to be deleted from file 6. The ISNs of the records to be deleted are contained in an input dataset. The deleted records are to be saved on an output dataset.

Example 5:

ADALOD  UPDATE FILE=6,DDISN,LIP=20K,SKIPREC=500  
ADALOD         TEMPSIZE=5,SORTSIZE=10

Records are to be added and deleted from file 6. The ISNs which identify the records to be deleted are contained in an input dataset (DDISN). The size of the ISN pool is set to 20K. The first 500 records on the input dataset are to be skipped.

Top of page

Formats for Specifying ISNs

There are two formats for specifying ISNs in the DDISN or ISN dataset. The first format can be used in all cases where only 31-bit ISNs are specified. A record can contain a mix of single ISNs and ranges of ISNs.

The second format supports 32-bit ISNs and can only be used with Adabas version 6 and above. Each record can specify either single ISNs (indicated by X'00000000' in the first fullword) or ranges of ISNs (indicated by X'FFFFFFFF' in the first fullword).

If the first fullword in a record contains a value other than X'00000000' or X'FFFFFFFF', it is assumed to be the 31-bit format. The DDISN/ISN dataset can contain records in both formats.

Format 1: 31-Bit Format

A single ISN requires 4 bytes. Set the high-order bit to 0 and specify the ISN in bits 01-31:

graphics/lod11_at_anchord.png

A range of ISNs requires 8 bytes. In the first four bytes, specify the first ISN in the range as a single ISN; in the next four bytes, set the high-order bit to 1 and specify the last ISN:

graphics/lod11_at_anchorc.png

The following example shows a variable-length record containing the equivalent of DELISN=10-80,90,100-110:

graphics/lod11_at_anchorb.png

Format 2: 32-Bit Format

In the 32-bit format, the first fullword in each record indicates whether the record contains single ISNs or ranges of ISNs. To indicate single ISNs, put zero in the first fullword (X'00000000'); to indicate ranges of ISNs, put -1 (X'FFFFFFFF'). In the following example, the first record contains single ISNs; the second record contains ranges. The two records are identical except for the indicator in the first fullword.

graphics/lod11_at_anchora.png

Top of page

UPDATE Data and Space Requirements

The following general information describes data requirements for UPDATE operation, and how ADALOD UPDATE allocates space. For more information about space allocation, refer to the Adabas DBA Reference documentation.

Input Data for UPDATE Operations

Records to be added must be in the form of compressed data records produced by the ADACMP or ADAULD utility. The field definitions used for the ADACMP run must agree with the definitions for the file to which the records will be added as contained in the field definition table (FDT).

Note:
Records being added to a ciphered file must already be encrypted using the same cipher code as was used for the records already in the file.

The ISNs of records to be deleted may be provided with the DELISN parameter and/or in an input dataset. If provided in an input dataset, each ISN must be provided as a 4-byte binary number. The dataset must have the record format VARIABLE BLOCKED. If desired, all ISNs to be added to or deleted from an Adabas expanded file can be specified; the UPDATE function selects the appropriate ISNs for the component file being processed.

UPDATE Space Allocation

If records are to be added and a larger MAXISN value has been specified, an additional address converter extent will be allocated by ADALOD. The size of the new extent is based on the difference between the new MAXISN and the previous MAXISN setting. If either insufficient space is available for the new extent or the maximum of five extents has already been allocated, processing ends with an error message.

If an additional Data Storage extent is required, ADALOD allocates an additional extent equal to approximately 25 percent of the total size of the Data Storage extents currently allocated to the file. As for the address converter, processing ends with an error message if either sufficient space is not available for the added extent or the maximum of five extents has already been allocated.

Generating UPDATE Descriptor Information

When adding records, ADALOD UPDATE generates a list of all descriptor values and the corresponding ISNs of the new records, and writes this information to the temp dataset.

Associator Updating with UPDATE

Before processing the input, ADALOD UPDATE copies the file's existing normal index to the temp dataset, but removes the descriptor values of any ISNs to be deleted.

ADALOD sorts the information written to temp during the input phase and merges the sorted values with the current normal index. The normal index is reordered during this process, and the Associator block padding factor is reestablished for each block. A new upper index is then created.

Empty space in partially filled blocks resulting from descriptor updating is reused. This can increase the number of empty blocks at the end of the index. Although one or more normal index and/or upper index extents may become empty as the result of the reorder process, ADALOD does not condense, delete, or change the size of these extents.

If new free space is needed for the normal index or upper index, ADALOD allocates an additional extent (or extents). Each additional extent allocated is equal to approximately 25 percent of the total current space allocated to the index. If insufficient space is available for the additional extent or if the maximum of five extents has already been allocated, ADALOD terminates with an error message.

Top of page

Mass Updates of Expanded Files

Using ADALOD UPDATE for a mass update to an expanded file, records must be added to or deleted from each component file individually. However, each component file can be processed using the same ADALOD commands.

When deleting a record with DELISN or DDISN, the complete list of ISNs to be deleted from all component files can be supplied. ADALOD automatically selects only the ISN values from the specified range that is appropriate for the component file currently being processed.

The same is true when adding new records with USERISN=YES.

When new expanded file records are being added with USERISN=NO but no free ISN is found, the loader cannot allocate a new address converter extent since the ISN range cannot be increased (NOACEXTENSION is active for all component files). Instead, ADALOD creates the index as though end-of-file had been reached. The remaining records not loaded may be added later to another component file using the SKIPREC parameter.

ADALOD does not check for unique descriptor values across component file boundaries.

Example:

The following is an example for performing a mass update to an expanded file (only the relevant parts of the complete jobs are shown):

              .
              .
//DDEBAND    DD DSN=MOREDATA.LOAD.PART1-2,...
//DDKARTE    DD *
ADALOD UPDATE FILE=40,USERISN=YES
ADALOD        DELISN=9000001-9500000,12000001-14000000
ADALOD        SORTSIZE=...,TEMPSIZE=...
              .
              .
//DDEBAND    DD DSN=MOREDATA.LOAD.PART1-2,...
//DDKARTE    DD *
ADALOD LOAD   FILE=41,USERISN=YES
ADALOD        DELISN=9000001-9500000,12000001-14000000
ADALOD        SORTSIZE=...,TEMPSIZE=...
              .
              -

Top of page