This document covers the following topics:
The L3/L6 command is used to read a record from a set of records which are stored in logical sequential order based on the ascending or descending sequence of the values for a given descriptor. Using the Multifetch feature, it is also possible to read multiple records with a single L3/L6 command.
The user specifies the file to be read, the descriptor to be used to control the read sequence (phonetic descriptors may not be used), and the fields within each record for which values are to be returned. Adabas returns the requested field values in the record buffer.
Optionally, a starting value, ending value or a range of values may be specified. In addition, positioning to a given value during the sequential read allows the user to `browse' through a file without having to read each record.
The L6 command performs the same function as the L3 command, and, in addition, places the record in shared or exclusive hold status, i.e. locks the record for other users. The L6 command should be used if the user needs to prevent other users from updating the record, e.g. because he wants to update the record. Please refer to Concepts and Facilities, Competitive Updating, Shared Locks and Hierarchical Locking for further information. If the user already holds a shared lock for the record and requests an exclusive lock now, the lock is upgraded to the exclusive locking mode. If the user already holds an exclusive lock for the record, the locking mode remains unchanged.
If the previous command for this command ID was issued with the ‘Q’ option, and the record read has not yet been released from shared hold status afterwards, this record read will be released from shared hold status again with the following exceptions:
If the same record has been read with the command option ‘Q’ in more than one command sequence, the record is only released if the next record has been read for all these command sequences, or an RC has been performed.
It is not released if another command has locked the same record exclusively, or the record has been shared locked with the command option ‘S’.
The L3/L6 command supports the Multifetch feature. This is indicated by one of the values `M' or `O' in the Command Option 1 field (see the description of the Command Option 1 field for more details).
When the Multifetch feature is used, the maximum number of records which can be returned for a single L3/L6 call is limited by the following factors:
The ISN Lower Limit field can be used to specify the maximum number of records to be returned, thus avoiding internal overheads when only a limited number of records are required.
If the value in the ISN Lower Limit field is 0, the number of records returned is limited only by the size of the ISN/Multifetch Buffer and the Record Buffer.
| Field | Format | |
|---|---|---|
| Call Type | B | F/U |
| Reserved (internal use) | -/- | |
| Command Code | A | F/U |
| Command ID | B | F/U |
| File Number | B | F/U (1) |
| Response Code | B | F/A (1) |
| ISN | B | F/A |
| ISN Lower Limit | B | F/U |
| ISN Quantity | B | -/A |
| Format Buffer Length (ACB only) | B | F/U |
| Record Buffer Length (ACB only) | B | F/U |
| Search Buffer Length (ACB only) | B | V F/U |
| Value Buffer Length (ACB only) | B | V F/U |
| ISN Buffer Length (ACB only) | B | F/U |
| Command Option 1 | A | F/U |
| Command Option 2 | A | F/U |
| Command Option 3 (ACBX only) | ||
| Additions 1 | A | F/A |
| Additions 2 | A,B | -/A |
| Additions 3 | A | F/A |
| Additions 5 | A | F/U |
| Command Time | B | -/A |
| Buffer | |
|---|---|
| Format Buffer | F/U |
| Record Buffer | –/A |
| Search Buffer | V F/U |
| Value Buffer | V F/U |
| ISN Buffer | –/A |
- 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 V Required if starting or ending values or range of values specified – Not used (1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.
- Command Code
L3/L6
- Command ID
This field must be set to a non-blank, non-zero value if a sequential pass is required. The value provided is used by Adabas to provide the records in the correct sequence and to avoid repetitive interpretation of the format buffer.
The high-order byte of this field must not be set to hexadecimal `FF', except when automatic command ID generation is used (see Programming Considerations, Using Command IDs for additional information).
This field must not be modified during a given sequential pass of a file.
If only a single record is to be read, this field may be set to blanks or binary zeros.
- File Number
The number of the file to be read.
- Response Code
Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully.
Response code 3 indicates that all entries of the specified descriptor have been processed or that the ending descriptor-value condition has become true.
If the Multifetch feature is used and an error occurs before or while processing the first record, the response code is returned in this field. In this case, the contents of the ISN Buffer and Record Buffer are undefined.
If an error is detected for the second or any subsequent ISN during the processing loop of the Multifetch feature, the first non-zero response code will terminate the multifetch processing. In this case, the response code will be stored as an additional entry in the ISN Buffer itself, not in the Response Code field of the Control Block. Since there are two possible locations for a response code, an application program should check first the Response Code field in the Control Block for errors of a general nature, then in the response code field of each ISN Buffer entry individually.
- ISN
Together with the starting descriptor value specified in the value buffer, this field is used to determine the start position for the initial L3/L6 call, in cases where several records can have the same descriptor value (matching descriptor-value entries) and when value-repositioning is to be performed. Refer to Example 5, "Using Value Start or Repositioning Option", for more details.
If an ISN of zero is specified, reading starts at the lowest (ascending sequence) or highest (descending sequence) ISN within the matching starting descriptor-value entries.
If a non-zero ISN is specified, reading starts at the closest ISN within the matching starting descriptor-value entries that is greater than (ascending sequence) or less than (descending sequence) the ISN specified in the control block. If the resultant ISN is outside the range of ISNs that match the starting descriptor value, the current position is moved to the next descriptor value and its lowest ISN (ascending sequence) or to the previous descriptor value and its highest ISN (descending sequence).
This field is ignored if the starting descriptor value does not match, or if the GT (ascending sequence) or LT (descending sequence) comparators are specified in the search buffer.
Adabas returns the ISN of the record which has been read in this field.
When the Multifetch feature is used, the first record to be read is determined as described above. The ISNs of the other records read with this L3/L6 command follow according to the logical sequence being used.
- ISN Lower Limit
If the Multifetch feature is used, the maximum number of records read by a single L3/L6 command is limited to the value specified in this field. If this value is 0, the number of records is limited only by the size of the ISN Buffer and the Record Buffer.
- ISN Quantity
If the descriptor for which values are to be returned is in a periodic group, Adabas returns the occurrence number in which the returned value is located in this field. If the Multifetch feature is used, this field refers to the first record returned.
- Format Buffer Length (ACB only)
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.
- Record Buffer Length (ACB only)
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.
- Search Buffer Length (ACB only)
The search buffer length (in bytes) if a starting value, ending value or a range of values has been specified.
The search buffer length is ignored if no value buffer is specified.
- Value Buffer Length (ACB only)
The value buffer length (in bytes) if a starting value, ending value or a range of values has been specified.
The value buffer length is ignored if no search buffer is specified.
- ISN Buffer Length (ACB only)
The length of the ISN Buffer. This value must be specified when the Multifetch feature is used. See the description of the ISN Buffer for information on how to calculate the length.
When the Multifetch feature is used, the Record Buffer can contain multiple records. The number of records returned, and the length of each record is stored in a corresponding entry in the ISN Buffer.
- Command Option 1
An `R' in this field indicates that the Return option is to be used. If an L6 command is issued, and the record to be read and held is currently held by another user, Adabas will return response code 145 rather than placing the user in wait status until the record becomes available.
An `M' in this field indicates that the Multifetch feature is to be used.
If the Multifetch feature is required with the Return option, the value `O' should be used instead of `M'.
- Command Option 2
The entry in this field specifies the sequence in which the entries for the given descriptor are processed.
An `A' in this field indicates that the descriptor values are to be read in ascending sequence. A starting value, ending value or range of values can be specified optionally. If the search buffer or value buffer is omitted, all of the entries for the given descriptor will be processed.
A `V' in this field indicates that the descriptor values are to be read in ascending sequence with a starting value. Both the search buffer and the value buffer must be present.
A `D' in this field indicates that the descriptor values are to be read in descending sequence. A starting value, ending value or range of values can be specified optionally. If the search buffer or value buffer is omitted, all of the entries for the given descriptor will be processed.
A blank value or any value other than the three specified above indicates that all descriptor values are to be processed in ascending sequence. The search buffer and value buffer will be ignored if they are specified.
When writing new applications, Software AG strongly recommends the use of the value `A' for this field. The use of the value `V' is supported in order to ensure upward compatibility.
When using the values `A' and `D', the processing sequence can be reversed simply by changing the contents of the command option 2 field.
- Command Option 3 (ACBX only)
The command option 3 is relevant only for an L6 command.
A ‘C’ in this field indicates that a shared lock is to be acquired for this record only as long as the command is active. If the record was already locked before, the record remains locked. Using this option avoids dirty reads: you see only the committed states of the record.
An ‘S’ in this field indicates that the record is to be placed in shared hold status. The lock will be released again when the current transaction is committed or backed out. If the command belongs to a subtransaction, the lock is also released when the current subtransaction is backed out. You can also release the lock with an RI command.
A ‘Q’ in this field indicates that the record is to be placed in shared hold status. The lock is released again at start of next sequential read command for this read sequence, or when one of the events happens that releases a record read with ‘S’ option, whichever happens first. If the same record is read by more than one command with ‘Q’ option, the record is released only when, for all these command sequences, either the next record has been read, or an RC command has been issued. If the same record has also been read by another command with ‘S’ option, or the record has been locked exclusively, the record is not released by reading the next record of the command sequence. The ‘Q’ option is not allowed in combination with the command option 1 = ‘M’ (multifetch feature).
A blank in this field indicates that the record is locked exclusively.
- Additions 1
The descriptor to be used to control the read sequence must be specified in this field. The descriptor name is specified in the first two positions of this field. The remaining positions must be set to blanks on the initial L3 call.
Phonetic descriptors must not be specified.
A descriptor which is a multiple-value field or derived from a periodic group may be specified, in which case the possibility exists that the same record may be read several times (once for each different value within a given record) during the sequential pass of the file.
If the descriptor specified is defined with the null value suppression (NU or NC) option, any records containing a null value for the descriptor will not be read.
If a search buffer is specified, the descriptor(s) in the search buffer must be identical to the descriptor specified in the Additions 1 field.
This field should not be modified by the user between L3/L6 calls. The exception to this rule is when the user wishes to reposition to a particular value during a sequential pass. Setting the last six positions of this field to blanks will cause a new setting of the start and ending value according to the current search and value buffer.
If response 3 occurs, Adabas sets the last six positions of this field to blanks.
- Additions 2
If the command completes successfully, and at least one Adabas field is requested in the format buffer, Adabas returns in the first two bytes of this field the compressed record length of the data storage record that was accessed, in binary format. The last two bytes contain the length of the decompressed fields selected by the Format Buffer in binary format. If the Multifetch feature is used, this information refers to the first record read.
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.
- Additions 5
This field may be used to provide a separate format buffer ID that is used to identify the internal format buffer used for this command, or to provide a global format buffer ID.
As long as the first byte of the Additions 5 field is not alphanumeric, the value provided in the command ID field will also be used as the format buffer ID.
If the first byte is a lower case character, the bytes 5 to 8 of the Additions 5 field will be used as a separate local format buffer ID.
If the first byte is a digit or an upper case character, the Additions 5 field (8 bytes) will be used as a separate global format buffer ID, which means that the format buffer ID can be used by several users in parallel.
See Programming Considerations, Using Command IDs for additional information and examples.
The fields for which values are to be returned must be specified in this buffer. The syntax and examples of format buffer construction are provided in Calling Adabas, Format and Record Buffers.
Adabas returns the requested field values in this buffer. The field values are returned according to the standard format and length of each field, unless the user has explicitly requested a different format and/or length in the format buffer.
When the Multifetch feature is used, the Record Buffer can contain data returned from multiple records. The Record Buffer consists of several entries, whereby each entry contains the requested field values from a single record. The number of entries returned, and the length of each entry is stored in a corresponding entry in the ISN Buffer.
The search buffer is only required if a starting value, ending value or both are specified in the value buffer in order to limit the number of descriptor entries to be retrieved.
If either the search buffer or value buffer are omitted, all of the values for the given descriptor will be processed.
In a sequence of search buffer elements, a comma is used as separating character and a period as terminating character.
The syntax of the search buffer is provided in Calling Adabas, Search and Value Buffers.
The value buffer contains the starting value or the ending value or the lower and upper limits of a range in accordance with the specifications contained in the search buffer.
When the Multifetch feature is used with the ACB buffer, the ISN Buffer contains information which describes the entries returned in the Record Buffer. If you use the Multifetch feature with the ACBX interface, multifetch buffers are used instead.
The first 4 bytes of the respective buffer specify the number of 16–byte entries which follow in the that buffer. Each 16–byte entry corresponds to an entry returned in the Record Buffer, and contains the following unsigned integer values (each 4 bytes long):
the length of the entry in the Record Buffer
the response code for the entry in the Record Buffer (this can
be different from the value in the Response Code field in the Control Block)
If
this value is non-zero, this means that an error occurred which caused the
multifetch processing to be terminated. In this case, there is no corresponding
entry in the Record Buffer.
the ISN
if the field for which values are to be returned is a descriptor in a periodic group, the occurrence number within the periodic group.
The following additional considerations are applicable for the L3/L6 command:
The Command ID used with the L3/L6 command is saved internally and used by Adabas. It will be 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.
Command IDs are not released at the end of a global transaction.
The user is permitted to update and/or delete records from a file which is being read by the user with an L3/L6 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 L3/L6 command, it is possible that the user reading with the L3/L6 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 logical sequential order. The descriptor RB is to be used for sequence control. The values for the fields RA and RB are to be returned. The entire file is to be read.
Command Code L3
Command ID EX01 (a non-blank CID is required)
File Number 2
Format Buffer Length 6 (or larger)
Record Buffer Length 18 (or larger)
Command Option 1 b (Return option not used)
Command Option 2 A
Additions 1 RBbbbbbb (descriptor RB to be used for
sequence control)
Additions 3 Password (file 2 is security protected)
Format Buffer RA,RB.
The L3 call is repeated to obtain each successive record. The CID and ADDITIONS 1 field must not be modified between L3 calls. Response code 3 will be returned when all records have been read.
File 1 is to be read in logical sequential order. The descriptor AA is to be used for sequence control. The values for fields AA and AB are to be returned. Each record read is to be placed in hold status.
Command Code L6
Command ID EX02 (non blank CID required)
File Number 1
Format Buffer Length 3 (or larger)
Record Buffer Length 10 (or larger)
Command Option 1 b (Return option not used)
Command Option 2 A
Additions 1 AAbbbbbb (descriptor AA to be used for
sequence control)
Additions 3 bbbbbbbb (file 1 is not security protected)
Format Buffer GA.
Each record read should be released by an ET command (ET logic users), or RI command (non–ET logic users).
The same requirement as Example 1 except that reading is to begin with the value `N'.
Command Code L3
Command ID EX03 (non blank CID required)
File Number 2
ISN 0 (reading is to start with the lowest ISN that
contains the value given in the value buffer)
Format Buffer Length 6 (or larger)
Record Buffer Length 18 (or larger)
Search Buffer Length 7 (or larger)
Value Buffer Length 1 (or larger)
Command Option 1 b (Return option not used)
Command Option 2 A
Additions 1 RBbbbbbb (RB is to be used for sequence
control)
Additions 3 Password (file 2 is security protected)
Format Buffer RA,RB.
Search Buffer RB,1,A. (GE is implicit)
Value Buffer N (reading to begin with value N)
The initial L3 call will result in the return of the first record which contains the value N for the descriptor RB. If no records exist with this value, the first record which contains a value greater than N (such as NA) will be returned.
The same requirement as example 3 except that a value repositioning is to be performed. The sequential read process is to continue with the value Q.
Command Code L3
Command ID EX03 (the CID field may not be changed
when performing a value repositioning)
File Number 2
ISN 0 (position to the lowest ISN that contains
the value specified in the value buffer)
Format Buffer Length 6 (or larger)
Record Buffer Length 18 (or larger)
Search Buffer Length 7 (or larger)
Value Buffer Length 1 (or larger)
Command Option 1 b (Return option not used)
Command Option 2 A
Additions 1 RBbbbbbb (the last six positions of this
field must be set to blank for value
repositioning)
Additions 3 Password (file 2 is security protected)
Format Buffer RA,RB.
Search Buffer RB,1,A.
Value Buffer Q (repositioning is to be to value Q)
Inverted list for the descriptor used for sequence control:
Value ISN List
A 1,4 B 2 D 3,5
Initial L3/L6 command with Command Option 2 = A, or subsequent L3/L6 command with Command Option 2 = A and last six bytes of Additions 1 reset to blanks (value repositioning):
| User-supplied Value | User-supplied ISN | ISN with which reading will start (or continue) |
|---|---|---|
| A | 0 | 1 |
| A | 1 | 4 |
| A | 2 | 4 |
| A | 4 | 2 |
| A | 5 | 2 |
| B | 0 | 2 |
| B | 1 | 2 |
| B | 2 | 3 |
| B | 3 | 3 |
| BABC | 1 | 3 |
| C | 0 | 3 |
| D | 0 | 3 |
| D | 3 | 5 |
| D | 4 | 5 |
| D | 5 | Response Code 3 |
| E–Z | – | Response Code 3 |
The following example illustrates the possibilities of using the ascending/descending option in conjunction with various search buffer and value buffer contents. The following applies to the file being read:
the values V1 and V2 are both present, otherwise the "GE" and "LE" examples would be the same as the "GT" and "LT" examples;
ISN=0 (no further positioning within matching start values).
