The L2/L5 commands read records in the sequence in which they are physically located in Data Storage.
This document covers the following topics:
The L5 command performs the same function as the L2 command, and, in addition, places each record read in hold status. If the record to be read and held is currently being held by another user, the user will be placed in wait status until the record becomes available. If the L5 command was issued with the command option 1 field set to "R", Adabas returns response code 145 if the record is not available.
The L2/L5 commands do not read records in any particular logical order unless the records were loaded initially in a particular logical sequence and no subsequent update changed this order.
The L2/L5 commands may be used to read an entire file at optimum speed since no access is required to the Associator (as with the L3 command), and all physical blocks are read in consecutive sequence.
The user specifies the file to be read and the fields within each record for which values are to be returned. The fields are specified in the format buffer. Adabas returns the requested field values in the record buffer.
The multifetch/prefetch option allows prior accessing of one or more sequential records, reducing overall operating time and eliminating the time needed for single-record fetches. Multi-/prefetching can be enabled by specifying "M", "O" (for multifetching), or "P" (for prefetching) in the command option 1 field. Refer to the section Using the Multifetch/Prefetch Feature for more information.
The compressed option (set by specifying "C." in the format buffer) causes the record read to be returned in compressed format, that is, as stored internally by Adabas.
| Field | Position | Format | Before Adabas Call | After Adabas Call |
|---|---|---|---|---|
| 1-2 | -- | -- | -- | |
| COMMAND CODE | 3-4 | alphanumeric | F | U |
| COMMAND ID | 5-8 | alphanumeric | F | U |
| FILE NUMBER | 9-10 | binary | F | U |
| RESPONSE CODE | 11-12 | binary | -- | A |
| ISN | 13-16 | binary | F | A |
| ISN LOWER LIMIT | 17-20 | binary | F | A |
| 21-24 | -- | -- | -- | |
| FORMAT BUFFER LENGTH | 25-26 | binary | F | U |
| RECORD BUFFER LENGTH | 27-28 | binary | F | U |
| 29-32 | -- | -- | -- | |
| ISN BUFFER LENGTH * | 33-34 | binary | F | U |
| COMMAND OPTION 1 | 35 | alphanumeric | F | U |
| 36-44 | -- | -- | -- | |
| ADDITIONS 2 | 45-48 | binary / binary | -- | A |
| ADDITIONS 3 | 49-56 | alphanumeric | F | A |
| ADDITIONS 4 | 57-64 | alphanumeric | F | A |
| ADDITIONS 5 | 65-72 | alphanumeric | F | -- |
| COMMAND TIME | 73-76 | binary | -- | A |
| USER AREA | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| FORMAT BUFFER | F** | U |
| RECORD BUFFER | -- | A |
| ISN BUFFER * | F | U |
where:
| F | Filled in by user before Adabas Call |
| A | Filled in by Adabas |
| U | Unchanged after Adabas call |
| * | The ISN buffer and length required only of the multi-/prefetch option is specified |
| ** | May contain compress option control characters "C." |
| -- | Not used |
L2/L5
This field must be set to a non-blank, non-zero value. It is used by Adabas to provide the records in the correct physical order and to avoid the repetitive interpretation of the format buffer. The value provided must not be modified during any given sequential pass of a file.
The first byte of this field may not be set to hexadecimal 'FF'.
If the command ID value is X'FFFFFFFF', automatic command ID generation will be in effect. In this case, the Adabas nucleus will generate values for command ID beginning with X'00000001', and will increment the value by 1 for each L2/L5 call. When specifying user-defined command IDs, the user must ensure that each command ID is unique.
See also the additions 5 field for separate format ID or global format ID usage.
Specify the binary number of the file to be read in this field. For the physical direct calls, specify the file number as follows:
For a one-byte file number, enter the file number in the rightmost byte (10); the leftmost byte (9), should be set to binary zero (B'0000 0000').
For a two-byte file number, use both bytes (9 and 10) of the field.
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. Non-zero response codes, which can also have accompanying subcodes returned in the rightmost half of the additions 2 field, are described in the Adabas Messages and Codes documentation.
Response code 3 indicates an end-of-file (EOF) condition was detected.
If this field is set to zero before the initial L2/L5 call, the sequential pass will begin with the first record contained in the first physical block of the file.
If this field is set to an ISN value before the initial L2/L5 call, the sequential pass will begin at the first record physically located after the record identified by the ISN specified. The ISN specified must be present in the file.
This field need not be modified by the user after the initial L2/L5 call. Adabas returns the ISN of the record which has been read in this field.
If either "M" or "O" (multifetching option) is specified in the command option 1 field, a non-zero value in this field determines the maximum number of records to be multifetched. If this value is zero, the number of records to be multifetched is limited by the record and ISN buffer lengths. Refer to the section Using the Multifetch/Prefetch Feature for more information.
The format buffer length (in bytes). The format buffer area defined in the user program must be as large as (or larger than) the length specified. If either multifetch option "M" or "O" is specified in the command option 1 field, this value must be less than 32 kilobytes.
The record buffer length (in bytes). The record buffer area defined in the user program must be as large as (or larger than) the length specified. If either multifetch option "M" or "O" is specified in the command option 1 field, this value must be less than 32 kilobytes.
The ISN buffer length (in bytes). The ISN buffer area defined in the user program must be as large as (or larger than) the length specified.
To improve performance by eliminating the time needed for single-record fetches, set option M, O, or P to enable multifetch or prefetch processing for the command. Refer to the section Using the Multifetch/Prefetch Feature for more information.
| Option | Description |
|---|---|
| M | Enable multifetching |
| O | Use multifetching with the "R" option described below |
| P | Use prefetching |
| R | (return) returns response code 145 if the record to be read and held by an L5 command is not available. |
If the command is processed successfully, the following information is returned in this field:
If the record buffer contains at least one valid field value, the leftmost two bytes contain the length (in binary form) of the compressed record accessed;
The rightmost two bytes contain the length (in binary form) of the decompressed fields selected by the format buffer and accessed.
Note:
This length information is not returned when the prefetch feature
is being used.
If the L2 or L5 command returns a non-zero response code, the rightmost two bytes may contain a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes documentation.
This field is used to provide an Adabas security or Adabas SAF Security password. If the database, file, or fields are security-protected, the user must provide a valid security password. Adabas sets the additions 3 field to blanks during command processing to enhance password integrity.
This field is used to provide a cipher code. If the file is ciphered, the user must provide a valid cipher code. If the file is not ciphered, this field should be set to blanks.
Adabas sets any cipher code to blanks during command processing, and returns a version code and database ID in the rightmost (low-order) three bytes of this field. For more information, see the section Control Block Fields.
This field may be used to provide a separate format ID which is to be used to identify the internal format buffer used for this command, or to provide a global format ID.
As long as the high-order (leftmost) bit of the first byte of the additions 5 field is not set to 1, the value provided in the command ID field will be used as the format ID as well.
If, however, this high-order bit is set to 1, the fifth through eighth bytes of the additions 5 field (additions 5 + 4(4)) will be used as the format ID.
If the two high-order (leftmost) bits of the first byte of additions 5 field are set to one (B'11'), the value in all eight bytes of the additions 5 field (additions 5 + 0(8)) is used as a global format ID (that is, the format ID can be used by several users at the same time).
See the section Command ID, Format ID, Global Format ID for more information and examples.
The fields for which values are to be returned are specified in this buffer. Format buffer syntax and examples are provided in the section Adabas Calling Procedure.
"C." in the first two positions of the format buffer indicates that the compressed option is to be in effect. This causes the record to be returned in compressed instead of decompressed format.
The format buffer may not be modified after the initial L2/L5 call has been issued.
Adabas returns the requested field values in this buffer. All field values are returned according to the standard length and format of each field, unless the user specifies a different length and/or format in the format buffer.
The ISN buffer is used only if the command-level multifetch or prefetch option is used. See the section Using the Multifetch/Prefetch Feature for more information. When multifetching is used, the L2/L5 command returns record descriptor elements, each up to 16 bytes long, in the ISN buffer (see the section BT/ET Multifetch Processing).
The following additional considerations are applicable for the L2/L5 command:
The command ID used with the L2/L5 command is saved internally and used by Adabas. It is released by Adabas when an end-of-file condition is detected, an RC or CL command is issued, or the Adabas session is terminated. The same command ID may not be used by the user for another read sequential command until it has been released.
The user is permitted to update and/or delete records from a file that is being read by the user with an L2/L5 command. Adabas maintains information about the last and next record to be provided to the user, and is able to provide the correct next record despite any interim record update or deletion performed by the user.
If another user is updating the file being read with an L2/L5 command, it is possible that the user reading with the L2/L5 command will not receive one or more records in the file, or may receive the same record more than once during a given sequential pass of the file.
File 2 is to be read in physical sequential order. All the values for all the fields within each record are to be returned.
| Command Code | L2 | |
|---|---|---|
| Command ID | EXL2 | nonblank CID required |
| File Number | 2 | |
| ISN | 0 | all records are to be read |
| Format Buffer Length | 3 | or larger |
| Record Buffer Length | 49 | or larger |
| Command Option 1 | b | return option not used |
| Additions 3 | password | file 2 is security-protected |
| Additions 4 | bbbbbbbb | file is not ciphered |
| Format Buffer | RG |
|---|
The L2 call is repeated to obtain each successive record. The ISN field need not be modified between calls.
File 2 is to be read in physical sequential order. The values for fields RA, XA, and XB (3 bytes unpacked) are to be returned. Each record read is to be placed in hold status for updating purposes.
| Command Code | L5 | |
|---|---|---|
| Command ID | EXL5 | nonblank CID is required |
| File Number | 2 | |
| ISN | 0 | all records are to be read |
| Format Buffer Length | 13 | or larger |
| Record Buffer Length | 21 | or larger |
| Command Option 1 | b | response code 145 option not used |
| Additions 3 | password | file 2 is security-protected |
| Additions 4 | bbbbbbbb | file 2 is not ciphered |
| Format Buffer | RA,XA,XB,3,U |
|---|
The L5 call is repeated to obtain each successive record. The ISN field need not be modified between L5 calls.
To complete logical transactions and release held records, ET logic users should issue an ET command. Non-ET users should release held records with an A4, E4, or RI command.
