The CHANGE function can be used to change the standard length of an Adabas field or the format of a field, including the change of:
a unique descriptor field to simply a descriptor field;
the time zone of the field;
a normal alphanumeric (A) field to a long-alpha (LA) field; or
the default field format from unpacked (U) to packed (P).
Only one of these changes may be performed per function execution.
No modifications to records in Data Storage are made by this function. The user is, therefore, responsible for preventing references to the field that would cause invalid results because of an inconsistency between the new standard length as defined to Adabas and the actual number of bytes contained in the record.
When changing the length of an Adabas expanded file field, the change must be made to each individual component file of the expanded file. Each CHANGE operation on a component file causes a message that confirms the change, and returns condition code 4.
This document covers the following topics:
The file in which the field whose length is to be changed is contained. An Adabas system file may not be specified.
The field whose standard length is to be changed. The field cannot be one that was defined with the FI option, or a field with a defined length of zero (variable-length field). Specify the field name between apostrophes (').
The FIELD and FNDEF parameters are mutually exclusive; either the FIELD parameter or the FNDEF parameter can be specified in a given ADADBS CHANGE utility request. However, more than one ADADBS CHANGE request can occur in a single run.
FNDEF specifies an Adabas field (data) definition that should be changed. One FNDEF statement is required for each field to be changed. The syntax used in constructing field definition entries is:
Each definition must adhere to the field definition syntax as described for the ADACMP utility in FNDEF: Field and Group Definition and FNDEF: Periodic Group Definition in the section entitled Field Definition Statements, in the ADACMP documentation.
Note the following Adabas field definitions change considerations:
The only field format change supported is the change from U format to P format. This is only supported if the field does not have the FI (fixed storage length) option set and is not the parent of a special field or descriptor.
Any new length specified must be compatible with the new field format and field options. Such a change alters the behavior of Adabas commands and utilities (such as ADACMP) where the field length is not specified in a format or search buffer.
The following field option or option combination changes are allowed:
| Field Options of Original Field Definition | Changes Allowed | Notes |
|---|---|---|
| CR (system field insertion only option) is set or is not set. | none | The setting of the CR option cannot be altered using ADADBS CHANGE. It must remain unchanged. |
| No DT (date-time edit mask) is set. | DT can be set.
TZ (time zone) can be specified or not specified. |
No data checking is performed to ensure that
the values in the database are compliant with the DT edit mask specified. The
date-time edit mask can only be changed for a field with the TZ option if the
file has no records.
TZ cannot be specified if the edit mask name is DATE, TIME, or NATDATE. In addition, due to the differing internal representations of date-time fields, TZ cannot be specified if the file already has records loaded. |
| DT (date-time edit mask) is set. | DT setting can be removed. | Once the DT setting is removed, you can no longer specify a date-time edit mask for the field in the format buffer. The date-time edit mask can only be changed for a field with the TZ option if the file has no records. |
| NB (trailing blanks) is not set. | NB can be set. | Once NB is set, Adabas will not remove trailing blanks for the field. |
| NU (null value) is set. | NC (SQL null value) can be set | Once NC is set, empty values in fields are converted to null values. |
| NC (SQL null value) and NN (SQL no-null value) are set. | NC and NN can be removed. | Once NC and NN are removed, blank, non-null values are allowed for the field.. |
| NC (SQL null value) and NN (SQL no-null value) are set. | NN can be removed, but NC must remain unchanged. | In insert commands, the field is not mandatory anymore in the format buffer. If not specified, the field will be assigned a null value. |
| NV (no conversion) is set. | NV can be removed. | Once NV is removed, A or W-format fields are processed in the record buffer after being converted. This changes the behavior of cross-platform calls. |
| NV (no conversion) is not set. | NV can be set. | Once NV is added, A or W-format fields are processed in the record buffer without being converted. This changes the behavior of cross-platform calls. |
| SY (system field) is set or is not set. | none | The setting of the SY option cannot be altered using ADADBS CHANGE. It must remain unchanged. |
| TZ (time zone) is not set, but a DT (date-time edit mask) is specified. | TZ can be set and DT must remain unchanged. | Once TZ is set, date-time values in the
database are converted from UTC to local time when specifying a date-time edit
mask.
In addition, due to the differing internal representations of date-time fields, TZ cannot be specified if the file already has records loaded. Note: |
| TZ (time zone) is set. | TZ can be removed. | If the file already has records loaded, TZ
cannot be removed due to the differing internal representations of date-time
fields. Once TZ is removed, date-time values in the database are no longer
converted from UTC to local time when specifying a date-time edit mask.
Note: |
For example, assume that the FDT has the field NT defined as
01,NT,7,P,NU. The following ADADBS CHANGE statement adds the
date-time edit mask NATTIME to the NT field definition:
ADADBS CHANGE FILE=201,FNDEF='01,NT,7,P,NU,DT=E(NATTIME)'
The FIELD and FNDEF parameters are mutually exclusive; either the FIELD parameter or the FNDEF parameter can be specified in a given ADADBS CHANGE utility request.
The new standard field format. The only field format change supported is from "U" (unpacked) to "P" (packed). The field cannot be a parent of a subdescriptor, a superdescriptor, or a hyperdescriptor.
One of the subparameters FORMAT, LENGTH, or OPTION must be specified when the FIELD parameter is specified; but only one of the three may be specified.
The new standard length for the field. A length of 0 is not permitted, nor can a field with an existing defined length of zero (such as a variable-length field) be redefined to a standard length.
One of the subparameters FORMAT, LENGTH, or OPTION must be specified when the FIELD parameter is specified; but only one of the three may be specified.
The new field option. The following field option changes are supported:
| Field Option | Description |
|---|---|
| LA | Changes a normal alphanumeric (A) field to long-alpha (LA). |
| NOUQ | Removes the unique descriptor (UQ) option from a descriptor field (DE). |
One of the subparameters FORMAT, LENGTH, or OPTION must be specified when the FIELD parameter is specified; but only one of the three may be specified.
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). When NOUSERABEND is specified, it must be specified as the first parameter (before all other parameters) for the utility function.
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.
The password of the file containing the field to be changed. This parameter is required if the file is password-protected.
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. See Syntax Checking with the TEST Parameter for more information on using the TEST parameter in ADADBS functions.
The standard length of field AB in file 5 is to be changed to 11 bytes.
ADADBS CHANGE FILE=5,FIELD='AB',LENGTH=11
