This document covers the following topics:
The L9 command is used to determine the range of values present for a descriptor and the number of records which contain each value. With the Multifetch feature, it is also possible to return information for more than one descriptor value with a single call of the L9 command.
Adabas determines this information by reading the Associator inverted lists. No access to Data Storage is required.
The user specifies the file in which the descriptor is contained, the descriptor for which the values are to be returned and the value at which processing is to begin. Adabas returns (with each L9 call) the next value for the descriptor in the record buffer, along with the number of records containing that value in the ISN quantity field of the control block. The values are provided in ascending or descending order. Null values for descriptors defined with the null value suppression option are not returned.
The L9 command supports the Multifetch feature. This is indicated by the value `M' 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 descriptor values which can be processed by a single L9 call is limited by the following factors:
The ISN Lower Limit field can be used to specify the maximum number of descriptor values to process, thus avoiding internal overheads when only a limited number of descriptors are required.
If the value in the ISN Lower Limit field is 0, the number of descriptor values processed 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 | -/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 | F/U |
| Value 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 |
| Additions 1 | 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 | * F/U |
| Value Buffer | * 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 - Not used * optional (1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.
- Command Code
L9
- Command ID
This field must be set to a non-blank, non-zero value if a sequential pass is required. This value is used by Adabas to provide the values in the correct sequence and to avoid the 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 the file.
If only a single index value 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/Multifetch 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/Multifetch 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/Multifetch Buffer entry individually.
- ISN
If the descriptor for which values are to be returned is contained within a periodic group, this field is used
on the initial call to specify the occurrence number for which values are to returned if the search/value buffer is not defined. Otherwise the search buffer is used to determine the occurrence number, and the content of the ISN field is ignored. A value of zero indicates that all occurrences are to be returned. A non–zero value indicates that only values of the specified occurrence are to be returned.
by Adabas to return the occurrence number of the value being returned in the record buffer as a four–byte integer.
When the Multifetch feature is used, the ISN field refers to the first descriptor value which will be processed by the L9 command.
- ISN Lower Limit
If the Multifetch option is used, this field is used to limit the number of records to be returned. If this field is set to zero, the maximum number of records returned depends on the size of the record buffer and/or the size of the ISN buffer.
- ISN Quantity
Adabas returns in this field the number of records containing the value returned in the record buffer. If the Multifetch feature is used, this field refers to the first descriptor value 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.
If no search buffer length is supplied, the command starts from the lowest value.
- 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 data for multiple descriptor values. The number of descriptor values returned, and the number of bytes of data returned for each descriptor is stored in a corresponding entry in the ISN Buffer.
- Command Option 1
An `M' in this field invokes the Multifetch feature. See Programming Considerations, Using The Multifetch Feature for more detailed information.
- Command Option 2
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 `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.
When using the values `A' and `D', the processing sequence can be reversed simply by changing the content of the command option 2 field.
When writing new applications, Software AG strongly recommends the use of the values `A' and `D' for this field. The use of other values is supported in order to ensure upward compatibility.
If the field contains a blank value or any value other than `A' or `D', the descriptor values are processed as if the value `A' had been specified.
- Additions 1
If no search buffer or no value buffer has been supplied, Additions 1 must contain the name of the descriptor to be used to control the read sequence. The descriptor name is specified in the first two positions of this field. The remaining positions must be set to blanks. The descriptor name specified in Additions 1 must be the same as the descriptor name specified in the Format Buffer.
Phonetic descriptors must not be specified.
- Additions 2
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 format in which the values are to be returned must be specified in this buffer.
The syntax of the format buffer is:
name[,length][,format].
- name
The name of the descriptor for which values are to be returned. A phonetic descriptor may not be specified.
- length
The length in which the value is to be returned. If length is not specified, the value will be returned using the default length of the descriptor as specified in the FDT.
- format
The format in which the value is to be returned. The format specified must be compatible with the standard format of the descriptor. If the format is not specified, the value will be returned using the default format of the descriptor as specified in the FDT.
Adabas returns the descriptor values requested in this buffer. A different value is provided with each L9 call. The values are provided in ascending or descending sequence. If the descriptor is defined with the null value suppression option, the null value for the descriptor will not be returned.
When the Multifetch feature is used, the Record Buffer can contain data for multiple descriptor values. The number of descriptor values processed, and information concerning each descriptor value, is stored in the ISN/Multifetch 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 the value buffer is omitted, all of the values for a given descriptor (or all of the values for a given occurrence) will be processed. In this case, the Additions 1 field must contain the descriptor name.
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 interface, the ISN Buffer contains information which describes the descriptor 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 a descriptor entry returned in the Record Buffer, and contains the following unsigned integer values (each 4 bytes long):
the number of bytes of information in the Record Buffer for the descriptor value
the response code for the descriptor value (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 for the descriptor value in the Record Buffer.
if the descriptor is in a periodic group, the occurrence number within the periodic group.
the number of ISNs found for the descriptor
The following additional considerations are applicable for the L9 command:
The Command ID used with the L9 command is internally saved 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 command until it has been released.
The user is permitted to update and/or delete records from a file which is being read by the user with an L9 command. Adabas maintains information about the last and next value to be provided to the user and is able to provide the correct next value despite any interim record update or deletion performed by the user.
If another user is updating the file being read with an L9 command, it is possible that the user reading with the L9 command will not receive one or more values in the file.
The values for the descriptor RB in file 2 are to be returned. All values are to be returned.
Command Code L9
Command ID L901 (a non blank CID is required)
File Number 2
Format Buffer Length 3 (or larger)
Record Buffer Length 10 (or larger)
Search Buffer Length 5 (or larger)
Value Buffer Length 1 (or larger)
Command Option 2 A
Additions 3 Password (file 2 is security protected)
Format Buffer RB. (the values are to be returned using
standard length and format)
Search Buffer RB,1. (the values for descriptor RB are
to be returned, and the starting value is
being provided with standard format and
length = 1)
Value Buffer b (processing is to begin with the first
value for RB equal or greater than 'b'
Each successive L9 call will result in the return of the next value (values are provided in ascending order). The number of records containing the value is returned in the ISN Quantity field.
The values for descriptor AB in file 1 are to be returned. Only values which are equal to or greater than 20 are to be returned.
Command Code L9
Command ID L902 (a non blank CID is required)
File Number 1
Format Buffer Length 7 (or larger)
Record Buffer Length 3 (or larger)
Search Buffer Length 7 (or larger)
Value Buffer Length 2 (or larger)
Command Option 2 A
Additions 3 bbbbbbbb (file 1 is not security
protected)
Format Buffer AB,3,U. (the values are to be returned
with length = 3 and format = unpacked)
Search Buffer AB,2,U. (the values for the descriptor AB
are to be returned and the starting value
is to be provided as a 2 byte unpacked
number)
Value Buffer 0x3230 (Processing is to begin with the
first value for AB which is equal to or
greater than 20)
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;
