LF Command (Read Field Definitions)

This document covers the following topics:


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.

graphics/lf.png

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
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 = unused
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 = unused
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 = unused
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
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)