LF Command (Read Field Definitions)

#### Search Results

Search

# LF Command (Read Field Definitions)

This document covers the following topics:

- Function and Use

- Control Block

- Record Buffer for Command Option 2 = 'S'

- Record Buffer for Command Option 2 = Blank

- Record Buffer for Command Option 2 = ‘X’ and ‘F’

- Example

## Function and Use

The LF command is used to read the field definition information for a file.

The user specifies the file number for which the field definitions are to be returned.

Adabas returns the field definition information in the record buffer. The following information is returned for each field:

- Level number;

- Name;

- Standard length;

- Standard format;

- Definition options.

This command can be used to obtain the standard field length and format of a field during program execution in order to dynamically create a format or search buffer.

The timestamp when the field definitions were last updated is returned in the record buffer when the command option 2 = ‘X’. This may be one of the following:

- The time when the file was created;

- The time when a field was last added, changed or deleted;

- A descriptor was last inverted or released.

If a file is imported with ADAORD or restored with ADABCK, the timestamp of the import or restore is not stored; the original timestamp of the file when it was exported or dumped is kept.

Note
The LF command only reads meta information on the file, but not the file itself. For this reason, an LF command can also be performed on a file that is currently exclusively locked by an application program or which is locked by a utility.

##### LF Command, Procedure Flow

### Control Block

Field | Format |
--- | --- | ---
Call Type | B | F/U
Reserved (internal use) |  | -/-
Command Code | A | F/U
Command ID | B | -/-
File Number | B | F/U (1)
Response Code | B | F/A (1)
Record Buffer Length (ACB only) | B | F/U
Command Option 2 | A | F/U
Additions 2 | A,B | -/A
Additions 3 | A | F/A
Command Time | B | -/A
User Area |  | F/U

### Buffer Areas

Buffer |
--- | ---
Format Buffer | */–
Record Buffer | –/A
Search Buffer | –/–
Value Buffer | –/–
ISN Buffer | –/–

> Formats:

>   A | alphanumeric
>   B | binary

> x/y before/after Adabas call - x and y can take the values:

>   A | Filled in by Adabas
>   F | To be filled in by User
>   U | Unchanged after Adabas call
>   - | Not used
>   * | Not used but must be included in parameter list of CALL statement

>   (1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.

## Control Block

> Command Code

>   LF

> File Number

>   The number of the file for which the field definition information is to be returned.

> Response Code

>   Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully.

> Record Buffer Length (ACB only)

>   The record buffer length (in bytes). The length specified must be large enough to contain all field definition information for the file and must not be greater than the size of the record buffer area defined in the user program.

> Command Option 2

>   The setting of this field determines the format and type of information to be returned in the record buffer.

>   An ‘S’ in this field returns the standard information on the file that was available already with Adabas Version 6.1. However, this information is not complete; in particular, the new features introduced with Adabas Version 6.2 are not supported.

>   An ‘X’ in this field returns extended information on the file in the record buffer. This contains all information required to create a file with the same FDT.

>   An ‘F’ in this field returns full information on the FDT. It is similar to the ‘X’ option but with the difference that logically-deleted fields are also returned in the record buffer.

>   Notes:

>   1. You can only load data with the ADAMUP utility if the FDT of the decompressed data is the same as the FDT of the target file, including the logically-deleted fields.
>   2. Logically-deleted fields are returned in the record buffer without field names.

>   A blank in this field returns only the basic information on the fields of the file; only a subset of the options is returned. No information on special descriptors is returned.

> Additions 2

>   Adabas returns the total length of the returned structure in this field.

>   For some response codes, Adabas returns detailed information in this field. See Adabas Messages And Codes for further information.

> Additions 3

>   This field is used to provide a security password.

>   If the file to be used is not security protected, this field should be set to blanks. If the file is security protected, the user must provide a valid password.

>   Adabas sets this field to blanks during command processing to protect the integrity of any password provided.

## Record Buffer for Command Option 2 = 'S'

All field definition information is returned in the record buffer.

Setting the Command Option 2 field to 'S' returns the information in the following format:

### Record Buffer General Layout

Bytes | Usage
--- | ---
1 - 2 | Total length of information
3 - 4 | Number of fields in the FDT (including SDT)
5 -N | Field definitions, each 8 bytes long
N - M | SDT (Special Descriptor Table) Special descriptors are: subdescriptors superdescriptors phonetic descriptors hyperdescriptors collation descriptors For SDT definitions, an SDT element has an integral length and is a multiple of 8 bytes.

### FDT Field Definitions

Bytes | Usage
--- | ---
1 | Indicator field name 'F'
2 - 3 | Field name
4 | Definition options (00 = no definition options) 0x 01 = unique descriptor 0x 02 = parent of sub-/superdescriptor 0x 04 = parent of phonetic descriptor 0x 08 = PE group field/ PE inner group/ elementary field within PE group 0x 10 = null suppression 0x 20 = multiple field 0x 40 = fixed format 0x 80 = descriptor
5 | Level number (binary)
6 | Length (group = 0)
7 | Format (Space (no format) for group) A = alpha B = binary F = fixed point G = floating point P = packed decimal U = unpacked decimal W = Unicode
8 | 0x01 = NC option is active 0x02 = NN option is active 0x04 = LB option is active 0x08 = LA option is active 0x10 = XI (exclude PE occurrence number from UQ) option 0x20 = HF option is active 0x40 = NV option is active 0x80 = NB option is active

| Warning: In order to be mainframe-compatible, the bit for the NV option has been changed: in Adabas Version 3.3 and earlier, NV option = 0x04; in Adabas Version 5.1 and higher and Adabas on mainframes, NV option = 0x40.

### SDT Field Definitions

Byte 1 | Indicates
--- | ---
C | Collation descriptor, see collation descriptor definition
H | Hyperdescriptor, see hyperdescriptor definition
P | Phonetic descriptor, see phonetic descriptor definition
S | Subdescriptor, see subdescriptor definition
T | Superdescriptor, see superdescriptor definition

### Collation Descriptor Definitions

Bytes | Usage
--- | ---
1 | C indicates collation descriptor
2 - 3 | Collation descriptor name
4 | Definition options 0x 01 = unique descriptor 0x 02 = XI (exclude PE occurrence number from UQ) option 0x 04 = no HE option 0x 08 = periodic 0x 10 = NU 0x 20 = multiple field 0x 40 = unused 0x 80 = unused
5 | Unused
6 | Length (255 means length > 254)
7 - 8 | Parent field name

### Hyperdescriptor Definitions

Bytes | Usage
--- | ---
1 | H indicates hyperdescriptor
2 - 3 | Hyperdescriptor name
4 | Definition options 0x 01 = unique descriptor 0x 02 = unused 0x 04 = HE option used 0x 08 = periodic 0x 10 = null suppression 0x 20 = multiple field 0x 40 = unused 0x 80 = unused
5 | Hyperexit number
6 | Length
7 | Format A = alphanumeric B = binary F = fixed point G = floating point P = packed decimal U = unpacked decimal W = Unicode
8 | Unused
1 - 2 | 0x0000 indicates continuation
3 - 8 | parent field name list (2 bytes each)

### Phonetic Descriptor Definition

Bytes | Usage
--- | ---
1 | P indicates phonetic descriptor
2 - 3 | Phonetic descriptor name
4 | Unused
5 - 6 | Parent field name
7 -8 | Unused

### Subdescriptor Definition

Bytes | Usage
--- | ---
1 | S indicates subdescriptor
2 - 3 | Subdescriptor name
4 | Definition options 0x 01 = unique descriptor 0x 02 = packed format 0x 04 = SQL null value representation 0x 08 = periodic 0x 10 = null suppression 0x 20 = multiple field 0x 40 = XI (exclude PE occurrence number from UQ) option 0x 80 = descriptor
5 - 6 | Parent field name
7 | From byte
8 | To byte

### Superdescriptor Definition

Bytes | Usage
--- | ---
1 | T indicates superdescriptor
2 - 3 | Superdescriptor name
4 | Definition options 0x 01 = unique descriptor 0x 02 = unused 0x 04 = unused 0x 08 = periodic 0x 10 = null suppression 0x 20 = multiple field 0x 40 = XI (exclude PE occurrence number from UQ) option 0x 80 = descriptor
5 - 6 | Parent field 1
7 | From byte
8 | To byte

For the second and subsequent parent fields, the following table applies:

Bytes | Usage
--- | ---
1 | 0x00 indicates continuation
2 - 3 | Unused
4 | Format of superdescriptor
5 - 6 | Parent field name
7 | From byte
8 | To byte

## Record Buffer for Command Option 2 = Blank

Information for all fields of a file, but not for special descriptors (for example, superdescriptors), is returned in the record buffer, Setting the command option 2 to blank returns the information in the following format:

### Record Buffer General Layout

Bytes | Usage
--- | ---
1 - 4 | Number of fields in the FDT (excluding special descriptors)
5 -N | Field definitions, each 6 bytes long

### FDT Field Definitions

Bytes | Usage
--- | ---
1 | Level number (binary)
2 - 3 | Field name
4 | Length (0 for groups, 255 means length > 254)
5 | Format
6 | Definition options (00 = no definition options) 0x 80 = unique descriptor 0x 40 = parent of sub-/superdescriptor 0x 20 = parent of phonetic descriptor 0x 10 = PE group field/ PE inner group/ elementary field within PE group 0x 08 = null suppression 0x 04 = multiple field 0x 02 = fixed format 0x 01 = descriptor

Note
The definition options in the record buffer for command option 2 = blank are not mainframe-compatible. Mainframe-compatible LF commands are only possible with command option 2 = S.

## Record Buffer for Command Option 2 = ‘X’ and ‘F’

Setting command option 2 to ‘X’ or ‘F’returns the information in the following format:

### Record Buffer General Layout

Bytes | Usage
--- | ---
1 - 4 | Total length of information
5 | Structure level (= 0) (with S option you get ‘F’ at this location)
6 | Flag byte for future use
7 - 8 | Number of entries in the FDT including Special Descriptor Table (SDT) and Referential Integrity Constraint Table (RIT) The maximum number of entries in the FDT including SDT is 3214; additionally referential integri-ty constraints can be defined for a file.
9 -16 | Unix timestamp (microseconds since 1970)
17 - N | Field definitions, each 16 bytes long. Larger entries may be possible in future versions.
(N+1) - M | SDT (Special Descriptor Table). Special descriptors are: Subdescriptors Superdescriptors Phonetic descriptors Hyperdescriptors Collation descriptors The length of an SDT definition is a multiple of 4 bytes.
(M+1) - L | RIT (Referential Integrity Constraint Table)

#### Notes:

- Each entry in the record buffer begins with the following fields:

  - Byte 1: Type of the entry

  - Byte 2: Length of the entry

  - Byte 3-4: Name of the entry

  - Byte 5: Format (Not for RI constraints)

  - Byte 6: Options (Not for RI constraints)

  - Descriptor length (Only for SDT entries)

- In order to be compatible with future Adabas versions, please consider the following:

  - Future Adabas versions may provide additional entry types for the ‘X’ option, therefore, you should not consider unknown entry types to be an error.

  - The record buffer entries may be larger than with the current Adabas version. Therefore, you should always use the entry length field to skip to the next entry. The information currently returned in the record buffer will also be returned at the same position in a record buffer entry with future Adabas versions.

  - The length of each entry is aligned to 4 bytes so that you can access 4-byte integer values without alignment problems.

- There may be more entries returned in the LF command than specified in the file definition, because the names of referential integrity constraints are defined only for the file containing the foreign key, but they are also re-turned by the LF command for the file containing the primary key.

### FDT Field Definitions

Bytes | Usage
--- | ---
1 | Indicator field name ‘F’
2 | Total length of ‘F’ entry
3-4 | Field name
5 | Format
6 | Definition options (00 = no definition options) 0x 01 = unique descriptor 0x 02 = parent of sub-/superdescriptor 0x 04 = parent of phonetic descriptor 0x 08 = PE group field/ PE inner group/ elementary field within PE group 0x 10 = null suppression 0x 20 = multiple field 0x 40 = fixed format 0x 80 = descriptor
7 | 0x01 = NC option is active 0x02 = NN option is active 0x04 = LB option is active 0x08 = LA option is active 0x10 = XI (exclude PE occurrence number from UQ) option 0x20 = HF option is active 0x40 = NV option is active 0x80 = NB option is active
8 | Level number
9 | Date/time edit masks: 1 = E(DATE) 2 = E(TIME) 3 = E(DATETIME) 4 = E(TIMESTAMP) 5 = E(NATDATE) 6 = E(NATTIME) 7 = E(UNIXTIME) 8 = E(XTIMESTAMP)
10 | Suboptions: For DT option (indicated by byte 9 not equal to 0): Bit 0x01 = TZ option is active For desrciptor option (indicated by bit 0x80 in byte 6): Bit 0x02 = TR option is active For SY option (indicated by byte 11 not equal to 0): Bit 0x40 = CR option is active
11 | SY function: 1 = TIME 2 = SESSIONID 3 = OPUSER
12 | Deactivation flag (only with command option ‘F’) : Bit 0x01 = Field logically deleted
13-16 | Field length

### SDT Field Definitions

There are SDT field definitions for the same descriptor types and with the same first byte as for the ‘S’ option.

#### Collation Descriptor Definitions

Bytes | Usage
--- | ---
1 | C indicates collation descriptor
2 | Total length of C entry
3-4 | Collation descriptor name
5 | Format of parent field (On open systems only W, on mainframe also A is possible)
6 | Definition options (same as byte 4 for ‘S’ option)
7-8 | Standard length
9-10 | Parent field name
11-12 | Maximum internal length
13 | Additional options 0x04 = LA 0x08 = LB 0x80 = Collation defined via collation exit Not set: collation defined via ICU Other bits: unused
14 | String length of collation attribute string (length byte and termination null character not included)
15-14 + byte 14 | Collation attribute string as null terminated string, for example: “‘de’,PRIMARY” If collation defined via collation exit: exit number as null terminated string, for example: “1”

Notes:

1. The C entry length is aligned to 4 bytes.
2. The format of parent field is relevant if you specify a parent field value in the value buffer. If the collation descriptor is defined without the HE option, you can also specify the internal collation descriptor values. These values have the format A with the option NV.

#### Hyperdescriptor Definitions

Bytes | Usage
--- | ---
1 | H indicates hyperdescriptor
2 | Total length of H entry
3-4 | Hyperdescriptor name
5 | Format
6 | Definition options (same as byte 4 for ‘S’ option)
7-8 | Hyperdescriptor length
9 | Exit number
10 | Additional options (mainframe only, same as byte 8 for ‘S’ option)
11 | unused
12 | Number of parent fields
13-12 + 2* byte 12 | Parent field names

Note
The H entry length is aligned to 4 bytes.

#### Phonetic Descriptor Definitions

Bytes | Usage
--- | ---
1 | P indicates phonetic descriptor
2 | Total length of P entry
3-4 | Phonetic descriptor name
5 | Format (currently only A supported)
6 | Options (unused)
7-8 | Descriptor length
9-10 | unused
11-12 | Parent field name

#### Sub-/Superdescriptor Definitions

Bytes | Usage
--- | ---
1 | S indicates subdescriptor T indicates superdescriptor
2 | Total length of entry
3-4 | Sub-/superdescriptor name
5 | Format
6 | Definition options (same as byte 4 for ‘S’ option)
7-8 | Descriptor length
9 | unused
10 | Number of parent fields (1 for subdescriptor, > 1 for superdescriptor)
11-10 + 6*byte 10 | Parent field entries – for each parent field: Parent field name (2 bytes) From byte (2 bytes) To byte (2 bytes)

Note
The sub-/superdescriptor entry length is aligned to 4 bytes.

#### Referential Integrity Definitions

Bytes | Usage
--- | ---
1 | R indicates referential constraint
2 | Total length of R entry
3-4 | Constraint name
5-8 | Reference file In case of primary file entry, the file of the foreign key In case of foreign file entry, the file of the primary key
9-10 | Primary key name (00 means ISN)
11-12 | Foreign key name
13 | 1 primary file entry 2 foreign file entry
14 | Update action: 0 No action 1 Cascade 2 Set NULL
15 | Delete action: 0 No action 1 Cascade 2 Set NULL
16 | Unused

The FDTs of each of the two referenced files contain an entry for a referential constraint. If both the foreign and primary key are in the same file for a referential constraint, the FDT of this file contains two entries for this constraint.

Note
The name of a referential integrity constraint may also occur as the name of a field or special descriptor of the file.

## Example

The field definition information (including features introduced with Adabas version 6.2) for file 1 is to be read.

#### Control Block:

    Command Code          LF

    File Number           1 (field definitions for file 1 requested)

    Record Buffer Length  100

    Command Option 2      X

    Additions 3           bbbbbbbb (file is not security protected)

### On this page

- Function and Use
- Control Block
- Record Buffer for Command Option 2 = 'S'
- Record Buffer for Command Option 2 = Blank
- Record Buffer for Command Option 2 = ‘X’ and ‘F’
- Example