The LF command reads the characteristics of all fields in a file.
We recommend that you set unused ACB and ACBX fields to binary zeros before the direct call is initiated.
This document covers the following topics:
The LF command is used to read the field definition information for a file. This command is used primarily by Adabas subsystems; it is normally not used by an application program.
The user specifies the file number for which the field definitions are to be returned.
Adabas provides the field information in the record buffer in one of three formats, according to the setting of the Command Option 2 field.
This section describes ACB interface direct calls for the LF command. It covers the following topics:
| Field | Position | Format | Before Adabas Call | After Adabas Call |
|---|---|---|---|---|
| 1-2 | -- | -- | -- | |
| Command Code | 3-4 | alphanumeric | F | U |
| 5-8 | -- | -- | -- | |
| File Number | 9-10 | binary | F | U |
| Response Code | 11-12 | binary | -- | A |
| 13-26 | -- | -- | -- | |
| Record Buffer Length | 27-28 | binary | F | U |
| 29-35 | -- | -- | -- | |
| Command Option 2 | 36 | alphanumeric | F | U |
| 37-48 | -- | -- | -- | |
| Additions 3 | 49-56 | alphanumeric | F | A |
| 57-72 | -- | -- | -- | |
| Command Time | 73-76 | binary | -- | A |
| User Area | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| Format | * | -- |
| Record | -- | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Not used but must be included in parameter list of call statement |
| -- | Not used |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
LF
The number of the file for which the field definition information is to be returned.
Note:
When using two-byte file numbers and database IDs, a X'30' must
be coded in the first byte of the control block.
Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully. If the LF command returns a nonzero response code, the rightmost two bytes of Adabas control block bytes 45-48 (Additions 2 field) may contain a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.
The record buffer length (in bytes). The length specified must be large enough to contain all field definition information for the file, but not larger than the size of the record buffer area defined in the user program. If you specify the internal format (I) Command Option, the maximum possible output is four Associator blocks.
The setting of the Command Option 2 field determines the format and type of field information to be returned in the record buffer.
| Option | Description |
|---|---|
| S | Returns all field information, including collation
descriptor, subfield and superfield, subdescriptor, superdescriptor,
hyperdescriptor, and phonetic descriptor information.
If you are using Adabas 8, and an LF command with Command Option 2 set to "S" is run, and large object (LB) fields are encountered, the LB field description is returned in an F-type field element. Bit 6 in the second format byte (at offset 7 or byte 8 in the element) is set to indicate that the LB (large object) option is set for the field. In addition, bit 1 of the second format byte indicates whether the LB field is defined with the NB (no blank compression) option. Note: |
| I | Returns all field information in Adabas internal format. |
If this field is left blank or contains binary zero, the LF command returns field information excluding sub-/super-/hyper-/phonetic or collation descriptor information. This is the same format as provided in Adabas version 4.
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.
If the accessed file is password-protected, Adabas replaces the password with blanks during command processing to protect password integrity.
The field definition information for file 1 is to be read.
| Command Code | LF | |
|---|---|---|
| File Number | 1 | field definitions requested for file 1 |
| Record Buffer Length | 100 | |
| Command Option 2 | S | information for all types of descriptors and sub/superfields is to be returned |
| Additions 3 | bbbbbbbb (blanks) | file is not security-protected |
This section describes ACBX interface direct calls for the LF command. It covers the following topics:
| Field | Position | Format | Before Adabas Call | After Adabas Call |
|---|---|---|---|---|
| 1-2 | --- | --- | --- | |
| Version Indicator | 3-4 | binary | F | U |
| 5-6 | --- | --- | --- | |
| Command Code | 7-8 | alphanumeric | F | U |
| 9-10 | --- | --- | --- | |
| Response Code | 11-12 | binary | --- | A |
| 13-16 | --- | --- | --- | |
| Database ID | 17-20 | numeric | F | U |
| File Number | 21-24 | numeric | F | U |
| 25-49 | --- | --- | --- | |
| Command Option 2 | 50 | alphanumeric | F | U |
| 51-68 | --- | --- | --- | |
| Additions 3 | 69-76 | alphanumeric/ binary | F | A |
| 77-114 | --- | --- | --- | |
| Error Subcode | 115-116 | binary | --- | A |
| 117-144 | --- | --- | --- | |
| Command Time | 145-152 | binary | --- | A |
| User Area | 153-168 | not applicable | --- | U |
| --- | 169-193 | do not touch | --- | --- |
| ABD and Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| Format | * | -- |
| Record | -- | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Not used but should be included in Adabas call or one will be automatically generated. |
| -- | Not used |
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
F2
LF
Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully. Non-zero response codes, which can also have accompanying subcodes returned in the Error Subcode (ACBXERRC) field, are described in the Adabas Messages and Codes Manual documentation.
Use this field to specify the database ID. The Adabas call will be directed to this database.
This field is a four-byte binary field, but at this time only two-byte database IDs are supported. Therefore, the database ID should be specified in the low-order part (rightmost bytes) of the field, with leading binary zeros.
If this field is set to binary zeros, the Adabas API uses either the database ID from the ADARUN cards provided in DDCARD input data or the default database ID value provided in the LNKGBLS module linked with or loaded by the link routine.
Use this field to specify the number of the file for which the field definition information is to be returned.
This field is a four-byte binary field, but the file number should be specified in the low-order part (rightmost bytes) of the field, with leading binary zeros.
The setting of the Command Option 2 field determines the format and type of field information to be returned in the record buffer.
| Option | Description |
|---|---|
| S | Returns all field information, including collation
descriptor, subfield and superfield, subdescriptor, superdescriptor,
hyperdescriptor, and phonetic descriptor information.
If you are using Adabas 8, and an LF command with Command Option 2 set to "S" is run, and large object (LB) fields are encountered, the LB field description is returned in an F-type field element. Bit 6 in the second format byte (at offset 7 or byte 8 in the element) is set to indicate that the LB (large object) option is set for the field. In addition, bit 1 of the second format byte indicates whether the LB field is defined with the NB (no blank compression) option. |
| I | Returns all field information in Adabas internal format. |
If this field is left blank or contains binary zero, the LF command returns field information excluding sub-/super-/hyper-/phonetic or collation descriptor information. This is the same format as provided in Adabas version 4.
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.
If the accessed file is password-protected, Adabas replaces the password with blanks during command processing to protect password integrity.
If the command returns a nonzero response code, this field contains a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.
The following buffers apply to the LF command:
A format buffer is not used by the LF command, but should be included in the Adabas call. If this is an ACB interface direct call and a format buffer is not specified, a processing error will occur; ACB interface direct calls expect buffers to be specified in a set sequence. If this is an ACBX interface direct call and a format buffer is not specified, one will be automatically generated.
All field definition information is returned in the record buffer.
If the Command Option 2 field is set to "S", all field information, including collation descriptor, subdescriptor, superdescriptor, hyperdescriptor, and phonetic descriptor and sub-/superfield information is returned in the following format:
Note:
If you are using Adabas 8, and an LF command with Command Option 2
set to "S" is run, and large object (LB) fields are
encountered, the LB field description is returned in an F-type FDT field
definition. Bit 6 in the second format byte (at offset 7 or byte 8 in the
element) is set to indicate that the LB (large object) option is set for the
field. In addition, bit 1 of the second format byte indicates whether the LB
field is defined with the NB (no blank compression) option.
| Bytes | Usage |
|---|---|
| 1-2 | total length of information |
| 3-4 | number of fields in the FDT (including SDTs, as described below) |
| 5-n | field definitions: each entry is 8 bytes, maximum number of entries is 926 |
| (n+1) - m | special descriptor table (SDT) including
|
The syntax of FDT field definitions is:
'F' field-name option level length format
The following table describes this syntax:
| Notation | Bytes | Usage | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 'F' | 1 | 'F' indicates FDT field definition | ||||||||||||||
| field-name | 2-3 | field name | ||||||||||||||
| option | 4 | definition options: | ||||||||||||||
|
||||||||||||||||
| level | 5 | level number (in binary) | ||||||||||||||
| length | 6 | length | ||||||||||||||
| format | 7 | type of data: | ||||||||||||||
|
||||||||||||||||
| 8 | options (continued) | |||||||||||||||
|
Note:
A field within a periodic group has the following
characteristics: - an option field (byte 4) with bit 5=1; and - a level field
(byte 5) with level number greater than 1. The periodic group field
itself always has option bit 5=1 and a level number of 1.
X SDT-definition
where X is one of the following:
| 'C' | collation descriptor, see the section Collation Descriptor Definition |
| 'H' | hyperdescriptor, see the section Hyperdescriptor Definition |
| 'P' | phonetic descriptor, see the section Phonetic Descriptor Definition |
| 'S' | subfield/descriptor, see the section Subfield/Subdescriptor Definition |
| 'T' | superfield/descriptor, see the sectionSuperdescriptor/Superfield Definition |
| X'00' | element continuation |
'C' name option exit length p-field-name
| Notation | Bytes | Usage | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 'C' | 1 | 'C' indicates collation descriptor | ||||||||||||
| name | 2-3 | collation descriptor name | ||||||||||||
| option | 4 | definition options: | ||||||||||||
|
||||||||||||||
| exit | 5 | collation exit number (binary, values 1-8 permitted) | ||||||||||||
| length | 6 | length | ||||||||||||
| p-field-name | 7-8 | parent-field name |
'H' name option exit length format X'00' X'00' X'00' p-fieldname-list ...
| Notation | Bytes | Usage | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 'H' | 1 | 'H' indicates a hyperdescriptor definition | ||||||||||||
| name | 2-3 | hyperdescriptor name | ||||||||||||
| option | 4 | definition options: | ||||||||||||
|
||||||||||||||
| level | 5 | hyperexit number (binary; values 1-31 permitted) | ||||||||||||
| length | 6 | length | ||||||||||||
| format | 7 | format: | ||||||||||||
|
||||||||||||||
| X'00' | 8 | options (continued) | ||||||||||||
|
A hyperdescriptor parent-field name list is an extension of a hyperdescriptor definition. It has the following format for all eight-byte groups after the first:
| Notation | Bytes | Explanation |
|---|---|---|
| X'00' | 1 | X'00' indicates continuation |
| X'00' | 2 | (unused) |
| p-fieldname-list... | 3-8 | parent-field name list: each name is two bytes; six bytes total (that is, three names. If fewer than three names are provided, the additional bytes are filled with X'00'). |
'P' desc-name option p-field-name X'0000'
| Notation | Bytes | Explanation |
|---|---|---|
| 'P' | 1 | 'P' indicates phonetic descriptor |
| desc-name | 2-3 | phonetic descriptor name |
| option | 4 | (unused) |
| p-field-name | 5-6 | parent-field name |
| X'0000' | 7-8 | (unused; set to nulls) |
'S' s-name option p-field-name from to
| Notation | Bytes | Usage | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 'S' | 1 | 'S' indicates subdescriptor/subfield | ||||||||||||
| s-name | 2-3 | subdescriptor or subfield name | ||||||||||||
| option | 4 | definition options: | ||||||||||||
|
||||||||||||||
| p-field-name | 5-6 | parent-field name | ||||||||||||
| from | 7 | starting (inclusive) byte | ||||||||||||
| to | 8 | ending (inclusive) byte |
'T' sup-name option p-field-name from to X'00' X'000000'p-field-name from to
| Notation | Bytes | Usage | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 'T' | 1 | 'T' indicates superdescriptor/superfield | ||||||||||||
| sup-name | 2-3 | superdescriptor name | ||||||||||||
| option | 4 | definition options: | ||||||||||||
|
||||||||||||||
| p-field-name | 5-6 | parent-field name | ||||||||||||
| from | 7 | starting (inclusive) byte | ||||||||||||
| to | 8 | ending (inclusive) byte |
Extension of a superdescriptor or superfield definition has the following format on all eight-byte groups after the first:
| Notation | Bytes | Explanation |
|---|---|---|
| X'00' | 1 | indicates continuation |
| X'000000' | 2-4 | (unused) |
| p-field-name | 5-6 | parent-field name |
| from | 7 | starting (inclusive) byte |
| to | 8 | ending (inclusive) byte |
If "I" is set for Command Option 2, field information is returned in Adabas internal format:
| Bytes | Contents | |||||
|---|---|---|---|---|---|---|
| 1 | X'80' | |||||
| 2 | B'00000xyz' where xyz are ciphering bits: 1=yes; 0=no | |||||
|
||||||
| 3-4 | binary zeros | |||||
| 5-8 | total inclusive length of FDT, including field definition table (FDT proper), FDT index, and special descriptor table (SDT) [ = p – 4] | |||||
| 9-12 | Inclusive length of field definition table (FDT proper) [ = n – 8] | |||||
| 13-n | FDT field descriptor elements (20 bytes per element; see the following description) | |||||
| n+1 to n+4 | Inclusive length of FDT index [ = m – n] | |||||
| n+5 to m | FDT index | |||||
| m+1 to m+4 | Inclusive length of special descriptor table (SDT) [ = p – m] | |||||
| m+5 to p | Special descriptor table (SDT) |
The format of each FDT field descriptor elements is described in the following table:
| Offset | Contents |
|---|---|
| 0 | field level |
| 1 - 2 | field name |
| 3 | special field options |
| 4 - 6 | reserved |
| 7 | default field length |
| 8 | field format |
| 9 | descriptor definition options |
| 10 | special descriptor parent options |
| 11 | periodic group count field |
| 12-13 | FDT element chain pointer |
| 14 | field security levels |
| 15 - 19 | reserved |
The meaning of FDT elements is described in the Adabas architecture training information.
The FDT is stored in up to four Associator blocks. Therefore, the maximum possible record buffer length is the length of four Associator blocks.
Note:
Command option 2 may be set to values other than
"I" or "S" to support
older programs; these values do not support newer features. Software AG
recommends "I" or "S" for
new programs.
If the Command Option 2 field contains neither "I" nor "S", the field information returned excludes collation descriptor and sub-/super-/hyper-/phonetic descriptor information. The information is provided in the same format as provided in Adabas version 4:
n field-def
where:
| n | is the number of fields in the file. The number is provided as a four-byte binary number in the first four bytes of the record buffer. |
| field-def | is the field definition information for each field within the file. The information for each field is provided in six bytes according to the following format: |
| Bytes | Usage | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | level number (binary) | |||||||||||||||
| 2 - 3 | name (alphanumeric) | |||||||||||||||
| 4 | standard length (binary) | |||||||||||||||
| 5 | standard format (alphanumeric): | |||||||||||||||
|
||||||||||||||||
| 6 | definition options: | |||||||||||||||
|
The information for the next field immediately follows the information for the preceding field with no intervening spaces.
