LF Command: Read Field Definitions
The LF command reads the characteristics of all fields in a file.
This document covers the following topics:
Function and Use
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.
Command: LF
User Control Block
| 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 |
User Buffer Areas
| Buffer |
Before Adabas Call |
After Adabas Call |
| FORMAT BUFFER |
* |
-- |
| RECORD BUFFER |
-- |
A |
where:
| F |
Filled in by user before Adabas Call |
| A |
Filled in by Adabas |
| U |
Unchanged after Adabas call |
| * |
Not used but must be included in parameter list
of call statement
|
| -- |
Not used |
Control Block
- Command Code
-
LF
- File Number
-
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.
- Response Code
-
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 documentation.
- Record Buffer Length
-
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.
- Command Option 2: Type of Information to Be Displayed
-
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.
|
| 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.
- Additions 3: Password
-
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.
Record Buffer
All field definition information is returned in the record buffer.
Command Option 2 is Set to "S"
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:
| 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 length of a sub-/phonetic/collation descriptor
element is eight bytes. Superdescriptor or hyperdescriptor elements are two or
more 8-byte entries long.
|
- FDT Field Definitions
-
'F' field-name option level length format
| Notation |
Bytes |
Usage |
| 'F' |
1 |
'F' indicates FDT field definition |
| field-name |
2-3 |
field name |
| option |
4 |
definition options: |
| bit 1=1 |
descriptor |
| bit 2=1 |
fixed length |
| bit 3=1 |
multiple-value field |
| bit 4=1 |
null suppression |
| bit 5=1 |
periodic-group field |
| bit 6=1 |
parent of phonetic descriptor |
| bit 7=1 |
parent of sub-/superdescriptor |
| bit 8=1 |
unique descriptor |
|
| level |
5 |
level number (in binary) |
| length |
6 |
length |
| format |
7 |
type of data: |
| A |
alphanumeric |
| B |
binary |
| F |
fixed point |
| G |
floating point |
| P |
packed decimal |
| U |
unpacked decimal |
| W |
wide-character |
|
| 8 |
options (continued) |
| bit 1 |
(unused) |
| bit 2=1 |
NV (not converted) option |
| bit 3 |
(unused) |
| bit 4=1 |
XI (exclude PE occurrence number from UQ)
option
|
| bit 5=1 |
LA (long alpha) option |
| bit 6 |
(unused) |
| bit 7=1 |
NN option |
| bit 8=1 |
NC option |
|
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.
- SDT Field Definitions
-
X SDT-definition
where X is one of the following:
Collation Descriptor
Definition
'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: |
| bit 1=1 |
descriptor |
| bit 2=1 |
exclude PE occurrence number from
UQ
|
| bit 3=1 |
multiple-value format |
| bit 4=1 |
null-value suppression |
| bit 5=1 |
periodic-group field |
| bits 6-7 |
(unused) |
| bit 8=1 |
unique descriptor |
|
| exit |
5 |
collation exit number (binary, values 1-8
permitted)
|
| length |
6 |
length |
| p-field-name |
7-8 |
parent-field name |
Hyperdescriptor
Definition
'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: |
| bit 1 |
(unused) |
| bit 2=1 |
fixed length |
| bit 3=1 |
multiple value |
| bit 4=1 |
null-value suppression |
| bit 5=1 |
periodic group |
| bit 6-7 |
(unused) |
| bit 8=1 |
unique descriptor |
|
| level |
5 |
hyperexit number (binary; values 1-31
permitted)
|
| length |
6 |
length |
| format |
7 |
format: |
| A |
alphanumeric |
| B |
binary |
| F |
fixed point |
| G |
floating point |
| P |
packed decimal |
| U |
unpacked decimal |
|
| X'00' |
8 |
options (continued) |
| bits 1-3 |
(unused) |
| bit 4=1 |
XI (exclude PE occurrence number from UQ)
option
|
| bits 5-8 |
(unused) |
|
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').
|
Phonetic Descriptor
Definition
'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) |
Subfield/Subdescriptor
Definition
'S's-name option p-field-name from to
| Notation |
Bytes |
Usage |
| 'S' |
1 |
'S' indicates subdescriptor/subfield |
| s-name |
2-3 |
subdescriptor/subfield name |
| option |
4 |
definition options: |
| bit 1=1 |
descriptor |
| bit 2=1 |
exclude PE occurrence number from
UQ
|
| bit 3=1 |
multiple-value format |
| bit 4=1 |
null-value suppression |
| bit 5=1 |
periodic-group field |
| bit 6-7 |
(unused) |
| bit 8=1 |
unique descriptor |
|
| p-field-name |
5-6 |
parent-field name |
| from |
7 |
starting (inclusive) byte |
| to |
8 |
ending (inclusive) byte |
Superdescriptor/Superfield
Definition
'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: |
| bit 1=1 |
descriptor |
| bit 2=1 |
exclude PE occurrence number from
UQ
|
| bit 3=1 |
multiple-value format |
| bit 4=1 |
null-value suppression |
| bit 5=1 |
periodic-group field |
| bit 6-7 |
(unused) |
| bit 8=1 |
unique descriptor |
|
| 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 |
Command Option 2 is Set to "I"
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 |
total length of FDT, FDT upper index
(UI), and SDT (length bytes included)
|
| 5-6 |
FDT length, in bytes (length bytes
included)
|
| 7-n |
FDT field descriptor elements (10 bytes
per element; see the following description)
|
| n+1 & n+2 |
length of FDT upper index (UI)
structure (including length bytes)
|
| n+3 to n+3+(n+1/n+2) |
upper index (UI) |
| UI & UI+1 |
SDT table length (including length
bytes)
|
| UI+2 to UI+2 + (UI/UI+1) |
SDT table structure |
FDT elements beginning in byte 7 each have the format of the FDTE
DSECT:
| Element Byte |
Format |
| 0 |
level definition |
| 1 - 2 |
field name |
| 3 |
field length |
| 4 |
field format |
| 5 |
descriptor definition |
| 6 |
periodic group descriptor |
| 7 |
security control byte |
| 8 - 9 |
FDT element pointer |
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.
Command Option 2 is Set to Neither S Nor I
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): |
| A |
alphanumeric |
| B |
binary |
| F |
fixed point |
| G |
floating point |
| P |
packed decimal |
| U |
unpacked decimal |
| W |
wide-character |
|
| 6 |
definition options: |
| bit1=1 |
descriptor |
| bit 2=1 |
fixed storage |
| bit 3=1 |
multiple-value field |
| bit 4=1 |
null-value suppression |
| bit 5=1 |
periodic group field |
| bit 6=1 |
phonetic source field |
| bit 7=1 |
sub-/superdescriptor source field |
| bit 8=1 |
unique descriptor |
|
The information for the next field immediately follows the information
for the preceding field with no intervening spaces.
Example
The field definition information for file 1 is to be read.
Control Block
| 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 |
file is not security-protected |
