 |
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:
This document covers the following topics:
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 is the number of blocks or cylinders available for the sort dataset.
TEMPSIZE is the number of blocks or cylinders available for the temp dataset.
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.
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.
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 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 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.
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 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 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 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 |
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.
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 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.
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 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:
TEMPSIZE can be increased to make the temp dataset larger. Note, however, that the temp dataset contents must not be changed because it contains information necessary for the restart operation;
The SORTSIZE and SORTDEV parameters and the sort dataset can be changed.
No other parameters can be changed. The DDEBAND/EBAND, DDFILEA/FILEA and DDISN/ISN datasets must remain the same.
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 is the number of input records to be skipped before beginning to process updates. The default is 0 (no records are skipped).
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.
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.
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=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).
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.
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.
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.
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.
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.
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.
A single ISN requires 4 bytes. Set the high-order bit to 0 and specify the ISN in bits 01-31:
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:
The following example shows a variable-length record containing the equivalent of DELISN=10-80,90,100-110:
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.
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.
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.
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.
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.
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.
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.
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=...
.
-