This document covers the following topics:
The L1/L4 command is used to read a single record from Data Storage. Using the Multifetch feature, it is also possible to read multiple records with a single L1/L4 command.
The user specifies the file number and ISN of the record to be read. The user indicates in the format buffer which fields are to be read. Adabas returns the requested field values in the record buffer.
The GET NEXT option provides for the reading of the records identified by the ISNs contained in an ISN list (which has been created previously by a Sx command) without the user having to provide the ISN of the record to be read with each L1/L4 call. Adabas automatically selects the ISN from the list and reads the record identified by that ISN. If the ISN no longer exists, the ISN is skipped, and the next ISN of the ISN list is read. Therefore, the number of ISNs read before you get a response code 3 (end of ISN list) may be smaller than the ISN quantity of the corresponding Sx command.
The READ ISN SEQUENCE option provides for the reading of a record identified by ISN, and if the ISN specified is not present in the file, the reading of the record with the next higher ISN which is present.
The THRU ‘K’ option is an extension to the READ ISN SEQUENCE option, this option allows the user to input the 'thru ISN' in the ISNQ field, while the 'from ISN' is specified in the ISN field. If the THRU ‘K’ op-tion is specified, the ISNQ field must also be specified. On the next call after reaching the 'Thru ISN,' it will receive a Resp 3.
The L4 command performs the same function as the L1 command, and, in addition, places the record in shared or exclusive hold status, i.e. locks the record for other users. The L4 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 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 GET NEXT option is used and the previous command for this command ID was issued with the command option ‘Q’, 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 sequences, 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 command option ‘S’.
The L1/L4 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). The Multifetch feature for the L1/L4 command is only available when used together with the following Command Option 2 values:
'I' (read in ascending ISN sequence)
'J' (read in ISN descending sequence, if ISNQ is specified will execute as read THRU option)
'K' (read in ISN sequence with TRHU option in ascending sequence)
'N' (get next after FIND)
The THRU ‘K’ option is an extension to the READ ISN SEQUENCE ‘I’ option, this option allows the user to input the 'thru ISN' in the ISNQ field, while the 'from ISN' is specified in the ISN field. If the THRU ‘K’ op-tion is specified, the ISNQ field must also be specified. On the next call after reaching the 'Thru ISN,' it will receive a Resp 3.
Extended to the 'J' option, wherein if ISNQ is specified, the THRU option is established for ISN descend-ing order, maintaining the same input mechanism 'Thru ISN' in the ISNQ field while specifying the 'from ISN' in the ISN field. A Response 3 will be received on the subsequent call after reaching the 'Thru ISN.'
When the Multifetch feature is used, the maximum number of records which can be returned for a single L1/L4 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/or the Record Buffer.
If the THRU option is set, it depends on the ‘Thru ISN’ set in ISNQ while taking into account the two factors mentioned above.
| 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 |
| Format Buffer Length (ACB only) | B | F/U |
| Record Buffer Length (ACB only) | B | 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) | A | F/U |
| Additions 2 | A,B | -/A |
| Additions 3 | A | F/A |
| Additions 5 | A | F/U |
| Command Time | B | -/A |
| User Area | F/U |
| Buffer | |
|---|---|
| Format Buffer | F/U |
| Record Buffer | –/A |
| Search Buffer | –/– |
| Value Buffer | –/– |
| 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 - 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
L1/L4
- Command ID
If a series of records is to be read with a series of L1/L4 calls and the same fields are to be specified in the format buffer for each call, this field should be set to a non-blank, non-zero value. This reduces the time required to process each L1/L4 call.
If the GET NEXT option is to be used, the Command ID of the ISN list to be used must be specified in this field. The format buffer may not be changed between successive L1/L4 calls when the GET NEXT option is used.
If only a single record is to be read, or if the format buffer is to be modified between L1/L4 calls, this field should be set to blanks or binary zeros.
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).
- File Number
The number of the file which contains the record 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 an end-of-list condition (possible only if GET NEXT or ISN SEQUENCE option is used).
If the Multifetch feature is used and an error occurs 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
The ISN of the record to be read. If the GET NEXT option is used, the following rules apply for this field:
Adabas automatically selects ISNs from the ISN list in the order in which they are contained in the list, independent of the setting of this field;
If the user wishes to position to a given ISN in the list, he has to use an S1/S4 command. See Programming Considerations, Retrieving ISN Lists for additional information.
If the READ ISN SEQUENCE option is used, the record identified by the ISN provided in this field will be read. If the ISN is not present in the file, the record with the next highest ISN will be read.
The GET NEXT and the READ ISN SEQUENCE options are mutually exclusive.
Adabas returns the ISN of the record which has been read in this field. This applies regardless of any options used.
If the Multifetch feature is used, the ISN returned in the control block is the ISN of the first record returned.
- ISN Lower Limit
If the Multifetch feature is used, the maximum number of records read by a single L1/L4 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.
If command option ‘L’ is used, and the Format Buffer contains a segment with *-position, the input value contains the current position of the segment. The value is increased by the length specified for the segment.
- 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.
- ISN Buffer Length (ACB only)
The ISN buffer length (in bytes). If the length of the ISN buffer is less than 20 bytes, the Multifetch feature will be ignored, and an Adabas response 53 will be returned.
This field is only used in conjunction with the Multifetch feature.
- Command Option 1
An 'R' in this field indicates that the return option is to be used. If an L4 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' or an 'O' in this field invokes the Multifetch feature. See Programming Considerations, Using The Multifetch Feature for additional information. The Multifetch feature can only be used if the Command Option 2 field is set to 'I' or 'N'.
- Command Option 2
An 'N' in this field indicates that the GET NEXT option is to be used. This option is used to read the records identified by the ISNs which are contained in an ISN list, without having to provide the ISN of the record to be read with each L1/L4 call. The ISN list to be used must be specified in the Command ID field. Response code 3 will be returned when all the ISNs in the list have been selected.
An 'I' in this field indicates that the READ ISN SEQUENCE option is to be used. Adabas will read the record identified by the ISN specified in the ISN field if the ISN is present in the file. If the ISN is not present, the record with the next highest ISN will be read. If the ISN is not present and no higher ISN is present in the file, no record will be read and response code 3 will be returned.
A 'J' in this field indicates that the READ ISN SEQUENCE IN DESCENDING ORDER option is used. Adabas reads the record identified by the ISN specified in the ISN field if the ISN is present in the file. If the ISN is not present, the record with the next lower ISN is read. If the ISN is not present and no lower ISN is present in the file, no record is read and response code 3 is returned. For reading the record with the highest existing ISN, set command option 2 to ‘J’ and ACBXISN to a big value, e.g. 4294967295 or X'FFFFFFFF'.
An ‘L’ in this field is only allowed if the format buffer contains a segment with *-position. Then the ISN Lower Limit field is used to determine the current position of the segment with *-position. Without the command option ‘L’, the current position of a segment with *-position is the first (leftmost) byte of the field value. The ‘L’ option is not allowed together with the Multifetch feature.
- Command Option 3 (ACBX only)
The command option 3 field is only relevant for an L4 command.
A ‘C’ in this field indicates that a shared lock is to be acquired for this record for only as long as the command is active. If the record was already locked before, it 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 the next sequential read command for this read sequence, or when one of the events occurs that releases a record read with ‘S’ option, whichever happens first. If the same record is read by more than one command with the ‘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 the ‘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 Command Option 1 = ‘M’ (multifetch feature).
A blank in this field indicates that the record is locked exclusively.
- 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 the 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 user specifies the fields to be read in this buffer. The format buffer definition, syntax and examples are provided in Calling Adabas, Format and Record Buffers.
Adabas returns the requested field values in this buffer. All values are returned according to the standard format and length of the field, unless the user has explicitly requested a different length and/or format 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.
When the Multifetch feature is used with the ACB interface, 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
an unused field
The Command ID used is internally saved and used by Adabas. It will be released by Adabas when an end–of–file condition is detected, when an RC or CL command is issued, or when the Adabas session is terminated. The same command ID must 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.
Note:
The Adabas file definitions in Appendix
A are used in all examples in this section.
ISN 4 in file 1 is to be read. The values for fields AA and AB are to be returned.
Command Code L1
Command ID bbbb (only 1 record is to be read)
File Number 1
ISN 4
Format Buffer Length 6 (or larger)
Record Buffer Length 10 (or larger)
Command Option 2 b (Get Next or Read ISN Seq. options not
used)
Additions 3 bbbbbbbb (file is not security protected)
Format Buffer AA,AB.
A set of records for which the ISNs have been previously obtained by a FIND command are to be read from file 2. The values for fields RA and XB are to be returned with the value for field XB to be returned with length 3 and format U.
Command Code L1
Command ID ABCD (a non-blank CID is recommended for
a series of reads in which the same
fields are being read in each record).
File Number 2
ISN n (ISNs are taken from the ISN list
created by the Find command).
Format Buffer Length 10 (or larger)
Record Buffer Length 11 (or larger)
Command Option 2 b (Get Next or Read ISN Seq. options not
used)
Additions 3 Password (file is security protected)
Format Buffer RA,XB,3,U.
Note:
n indicates an ISN from the ISN list which resulted from the FIND command. The L1
call is repeated for each ISN in the ISN list.
The requirement as stated for example 2 may also be resolved by using the GET NEXT option.
Command Code L1
Command ID ABCD (CID of ISN list to be used)
File Number 2
ISN 0 (the entire ISN list is to be selected
starting with the first ISN in the list)
Format Buffer Length 10 (or larger)
Record Buffer Length 11 (or larger)
Command Option 2 N (Get Next option to be used)
Additions 3 Password (file 2 is security protected)
Additions 5 APL3FB01 (a global format buffer ID is
recommended for series of reads in
which the same fields are read in each
record for several users using the same
application)
Format Buffer RA,XB,3,U.
The L1 call is repeated for each ISN in the ISN list. No changes to the control block are required between L1 calls. Response code 3 will be returned when all the ISNs in the list have been selected.
ISN 5 in file 2 is to be read and held for updating. The values for fields XC and XD are to be returned.
Command Code L4 (Read With Hold)
Command ID bbbb (only 1 record to be read)
File Number 2
ISN 5
Format Buffer Length 6 (or larger)
Record Buffer Length 14 (or larger)
Command Option 1 b (Return option not used)
Command Option 2 b (Get Next or Read ISN Seq. options not
used)
Additions 3 Password (file is security protected)
Format Buffer XC,XD.
File 1 is to be read using the READ ISN SEQUENCE option. The values for fields AA, AB and AC are to be returned.
Command Code L1
Command ID BCDE (non–blank CID is recommended when a
series of records for which the same
fields are to be returned is to be read)
File Number 1
ISN 1 (If ISN 1 is not present, the record
with the next higher ISN will be read)
Format Buffer Length 6 (or larger)
Record Buffer Length 30 (or larger)
Command Option 2 I (Read ISN Sequence option is invoked)
Additions 3 bbbbbbbb (file is not security protected)
Format Buffer GA,AC.
Adabas returns the ISN of the record which has been read in the ISN field of the control block. The record with the next highest ISN may be read by adding one to the ISN field and repeating the L1 command.
The record identified by ISN 2 in file 1 is to be read. The value for field AA, all values for the multiple value field MF and all occurrences of the periodic group GB are to be returned.
Issue an L1 call to obtain the count of the number of values which exist for MF and the highest occurrence count for GB.
Command Code L1
Command ID bbbb (only 1 record is to be read)
File Number 1
ISN 2
Format Buffer Length 8 (or larger)
Record Buffer Length 2 (or larger)
Command Option 2 b (Get Next or Read ISN Seq. option not
used)
Format Buffer MFC,GBC.
Assuming that the result of the above L1 call was that the record contains 4 values for MF and 6 occurrences for GB, repeat the L1 call using the following format buffer:
AA,MF1-4,GB1-6
For each call, the length of the format and record buffers must be sufficiently large to accommodate all entries and values.
When using this procedure to read a series of records, a non-blank CID should be used in step 1 and a blank CID should be used for step 2, since the content of the format buffer may vary with each step 2 call.
An alternative solution for example 5 usually provides better performance if the number of values/occurrences is small (less than 6) in a large percentage of the records.
Issue an L1 call in which the counts for MF and GB are requested, plus the expected number of values and occurrences of MF and GB, plus field AA.
Assuming that the expected number of values for MF is 2 and the expected number of occurrences of GB is 3, the format buffer for step 1 would be:
AA,MFC,GBC,MF1-2,GB1-3
Maximum performance is normally achieved if a number which will retrieve all of the values/occurrences in 90 per cent of the records is specified.
If the count received for MF exceeds 2 or the count received for GB exceeds 3, then a format buffer similar to that in step 2 above would be used to obtain the additional values and/or occurrences. Otherwise, no additional call is required.
The LOB field L1 of the record with ISN 6 is to be read. Assume that you have defined an area of 1,000,000 bytes for the LOB value. The LOB value can then be read with the following command:
Command Code L1
Command ID EFGH
File Number 2
ISN 6
Command Option 1 b (Return option not used)
Command Option 2 b (Get Next or Read ISN Seq. options not used)
Additions 3 Password (file is security protected)
Format Buffer 1 L1L.
Record Buffer 1 Length 4
Format Buffer 2 L1,*.
Record Buffer 2 Length 1000000
If the LOB value is larger than 1,000,000 bytes, you can allocate a new memory area that is large enough for the LOB value, set the record buffer 2 length to the new value, and repeat the call.
A set of records has previously been found by an S1 command with command ID “ABCD” without format and ISN buffer.
The LOB field L1 is read piecemeal in segments of 1,000,000 bytes. The first call for a record uses the Get Next option to fetch the next record of the ISN list, and reads the first segment of the LOB value:
Command Code L4 (read with hold)
Command ID ABCD
File Number 2
ISN unchanged from S1 command
ISN Lower Limit 0
Command Option 1 b (Return option not used)
Command Option 2 N (Get Next option)
Command Option 3 Q (Shared hold until next record read)
Additions 3 Password (file is security protected)
Format Buffer 1 L1L.
Record Buffer 1 Length 4
Format Buffer 2 L1(*,1000000).
Record Buffer 2 Length 1000000
If the length of the LOB field is larger than 1.000.000, you can read the next segment of the LOB value with the following command:
Command Code L1
Command ID ABCD
File Number 2
ISN unchanged from L4 command
ISN Lower Limit unchanged from previous call
Command Option 1 b (Return option not used)
Command Option 2 L (*-position determined by ISN Lower Limit)
Additions 3 Password (file is security protected)
Format Buffer 1 L1L.
Record Buffer 1 Length 4
Format Buffer 2 L1(*,1000000).
Record Buffer 2 Length 1000000
In order to read the complete LOB value, you must repeat this L1 call without changing the ISN Lower Limit between the calls, either as often as indicated by the LOB length or until you get a response code 3.
If additional fields are to be read in the previous example, you would read these other fields several times, which is superfluous. Therefore, you can use two different format buffers for the L4 command for the non-LOB fields and the L1 command for the LOB field segment:
Command Code L4 (Read with Hold)
Command ID ABCD
File Number 2
ISN unchanged from S1 command
Command Option 1 b (Return option not used)
Command Option 2 N (Get Next option)
Command Option 3 Q (Shared hold until next record read)
Additions 3 Password (file is security protected)
Format Buffer 1 L1L,RG.
Record Buffer 1 Length 53 (or larger)
The LOB field is read piecemeal in segments of 1.000.000 bytes with the following command:
Command Code L1
Command ID EFGH
File Number 2
ISN unchanged from L4 command
ISN Lower Limit 0
Command Option 1 b (Return option not used)
Command Option 2 L (*-position determined by ISN Lower Limit)
Additions 3 Password (file is security protected)
Format Buffer 1 L1L,(*,1000000).
Record Buffer 1 Length 1000000 (or larger)
In order to read the complete LOB value, you must repeat this L1 call without changing the ISN Lower Limit between the calls, either as often as indicated by the LOB length or until you get response code 3.