Version 8.2.5
 —  Utilities  —

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:

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

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:

graphics/util_fndef.png

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:

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.

Top of page

Optional Parameters

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.

Top of page

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

Top of page