CHANGE: Change Standard Length or Format of a Field

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.

graphics/util_adadbs_change.png

This document covers the following topics:

Essential Parameters
Optional Parameters
Example

Essential Parameters

FILE: File Containing the Field

The file in which the field whose length is to be changed is contained. An Adabas system file may not be specified.

FIELD: Field to be Changed

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: Adabas Field Definition to be Changed
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:
This is only allowed if the file has no records. TZ may not be set for date-time edit mask names DATE, TIME and NATDATE.

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:
This is only allowed if the file has no records.

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.
FORMAT=P: New Field Format

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.

LENGTH: New Field Length

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.

OPTION: New Field Option

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.

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: This is only allowed if the file has no records. TZ may not be set for date-time edit mask names DATE, TIME and NATDATE.
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: This is only allowed if the file has no records.

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

Optional Parameters

INPARALLEL: Execute function in parallel

When INPARALLEL=YES (the default) is specified, the function may be executed even if other users are active on the file. Adabas performs the function while all application commands against the file are temporarily quiesced and suspended. The integrity of the file targeted by the ADADBS function is maintained.

INPARALLEL=YES can be specified only for the function CHANGE FIELD with OPTION=NOUQ.

With INPARALLEL=NO, the function requires exclusive file control – that is, no applications can be executing against the file. Adabas refuses to execute the function (with response code 48) if other users are active on the file.

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.

PASSWORD: File Password

The password of the file containing the field to be changed. This parameter is required if the file is password-protected.

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. See Syntax Checking with the TEST Parameter for more information on using the TEST parameter in ADADBS functions.

Example

The standard length of field AB in file 5 is to be changed to 11 bytes.

ADADBS CHANGE FILE=5,FIELD='AB',LENGTH=11