The L9 command reads the values of a specified descriptor.
We recommend that you set unused ACB and ACBX fields to binary zeros before the direct call is initiated.
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 that contain each value.
Specify the file containing the descriptor, the descriptor for which the values are to be returned, and the value at which processing is to begin. Each L9 call returns the next value for the descriptor in the record buffer, and the count of records containing that value in the ISN quantity field. The values may be either positive or negative. Null values for descriptors defined with the null value suppression (NU) option are not returned.
The multifetch and prefetch options improve performance by reading several descriptor values at a time. Multifetching can be enabled by specifying "M" (for multifetching) in the Command Option 1 field. Refer to the section Using the Multifetch/Prefetch Feature for more information.
The "I" option specified in the Command Option 2 field returns the ISNs of each value in the record buffer. The L9 command reads the Associator inverted lists only; no Data Storage access is required.
Within a logical read sequence, the direction of the read can be changed at any time from ascending to descending or back by specifying "A" or "D" for Command Option 2. See Example 3: Overview of Sequence Options for an overview of sequence options resulting from the choice of A or D for Command Option 2 and various search and value buffer options. The ascending and descending options are not supported with multifetch processing.
This section describes ACB interface direct calls for the L9 command. It covers the following topics:
| 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 | -- | A |
| ISN Lower Limit | 17-20 | binary | F | A |
| ISN Quantity | 21-24 | binary | -- | A |
| Format Buffer Length | 25-26 | binary | F | U |
| Record Buffer Length | 27-28 | binary | F | U |
| Search Buffer Length | 29-30 | binary | F | U |
| Value Buffer Length | 31-32 | binary | F | U |
| ISN Buffer Length * | 33-34 | binary | F | U |
| Command Option 1 | 35 | alphanumeric | F | U |
| Command Option 2 | 36 | alphanumeric | F | U |
| Additions 1 | 37-44 | alphanumeric | F | U |
| Additions 2 | 45-48 | binary | -- | A |
| Additions 3 | 49-56 | alphanumeric | F | A |
| 57-64 | -- | -- | -- | |
| Additions 5 | 65-72 | alphanumeric | F | U |
| Command Time | 73-76 | binary | -- | A |
| User Area | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| Format | F | U |
| Record | -- | A |
| Search | F | U |
| Value | F | U |
| ISN * | -- | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | The ISN buffer and length required only if the multifetch or prefetch option is specified |
| -- | Not used |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
L9
This field must be set to a non-blank, non-zero value. This value is used by Adabas to provide the values in the correct sequence and to avoid the repetitive interpretation of the format buffer.
This field must not be modified during a given sequential pass of the file.
The first byte of this field may not be set to hexadecimal 'FF'.
Specify the binary number of the file to be read in this field. For 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 Manual documentation.
Response code 3 indicates that an end-of-file condition has been detected.
If the descriptor for which values are to be returned is contained within a periodic group, Adabas returns in this field the occurrence number in which the value being returned is located. The occurrence number is provided in binary format in the two low-order bytes.
If the prefetch option is specified, any occurrence for prefetched values is returned in the header preceding the value in the ISN buffer.
Adabas returns values in this field as follows:
| Command Option 1 | Command Option 2 | The L9 command . . . |
|---|---|---|
| blank | I | returns the ISNs for each value in the record buffer; no value is returned in the ISN lower limit field. |
| not I | places the first ISN of the returned ISN list in the ISN lower limit field. | |
| P (prefetch) | I | returns the first ISN in the record buffer and all prefetched descriptor values in the ISN buffer, preceded by a 16-byte header; no value is returned in the ISN lower limit field. |
| not I | places the first ISN of the last value prefetched in the ISN lower limit field. | |
| M (multifetch) | I | returns the group of multifetched records in the record buffer and a description of these records in the caller's ISN buffer; no value is returned in the ISN lower limit field. |
| not I | places the first ISN of the last value multifetched in the ISN lower limit field. |
If Command Option 1 is set to "M" (multifetch option), you can set:
a non-zero value in the ISN lower limit field to limit the number of values to be multifetched.
zero in the ISN lower limit field to multifetch all values.
Refer to the section Using the Multifetch/Prefetch Feature for more information.
Except when the return ISNs option (I) is specified in Command Option 2, Adabas uses this field to return the number of records containing the value returned in the record buffer.
If the prefetch option is specified, the count of prefetched values is in the header that precedes the value in the ISN buffer.
The format buffer length (in bytes). The format buffer area defined in the user program must be at least as large as the length specified.
The record buffer length (in bytes). The record buffer area defined in the user program must be at least as large as the length specified.
The search buffer length (in bytes). The search buffer area defined in the user program must be at least as large as the length specified.
The value buffer length (in bytes). The value buffer area defined in the user program must be at least as large as the length specified.
The ISN buffer length (in bytes).
When the Command Option 1 field is set to "P", the L9 command uses the ISN buffer to hold prefetched descriptor values. The ISN buffer must be large enough to hold the largest descriptor value plus a 16-byte header preceding each value. The actual ISN buffer area defined in the user program must be at least as large as the length specified.
Specifying one of these options indicates that the (command-level) prefetch or multifetch option is to be used. The multifetch/prefetch option can improve performance reading several descriptor values at a time thereby eliminating the time needed for single-record fetches. For more information, see the section Using the Multifetch/Prefetch Feature.
| Option | Description |
|---|---|
| M (multifetching) | Multifetch processing is enabled.
In conjunction with this option, you can set:
|
| P (prefetching) | Prefetch processing is enabled. |
If the M or P options are specified, the L9 command puts all prefetched or multifetched descriptor values in the ISN buffer, preceded by a 16-byte header. The ISN buffer must be large enough to hold the largest descriptor value plus 16 bytes. The actual ISN buffer area defined in the user program must be at least as large as the ISN buffer length specified.
| Option | Description |
|---|---|
| I | Adabas stores the ISNs for each value in the record buffer, as well as the values themselves. The L9 command reads the Associator inverted lists only; no Data Storage access is required. |
| A | The descriptor's entries are processed in ascending order. |
| D | The descriptor's entries are processed in descending order. |
If both the search and value buffer lengths are set to zero, a value in the Additions 1 field is the name of the descriptor for which values are to be returned. The name must be the same as the descriptor name specified in the format buffer.
In this case, L9 processes all values for the specified descriptor from the beginning of the file.
The descriptor name is specified in the first two positions of this field. The remaining positions must be set to blanks.
If the L9 command returns a nonzero response code, the rightmost two bytes of this field may contain a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.
This field is used to provide an Adabas 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.
Use this field to specify a separate format ID that identifies the internal format buffer used for this command, or to provide a global format ID allowing use of the internal format buffer by all users.
As long as the leftmost bit of the Additions 5 field is set to 0, the value provided in the command ID field is used as the format ID as well.
If, however, this bit is set to 1, the fifth through eighth bytes of the Additions 5 field are 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'), all eight bytes of the Additions 5 field are 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.
All values for the descriptor RB in file 2 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 |
| 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 equal to 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 |
| Additions 3 | bbbbbbbb (blanks) | file 1 is not security-protected |
| Format Buffer | AB,3,U. | the values are to be returned with length=3 and with 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 | X'F2F0' | processing is to begin with the first value for AB that is equal to or greater than 20 |
The following table illustrates the possibilities for using the ascending/descending option in conjunction with various search buffer and value buffer contents. The following applies to the file being read:
This section describes ACBX interface direct calls for the L9 command. It covers the following topics:
| Field | Position | Format | Before Adabas Call | After Adabas Call |
|---|---|---|---|---|
| 1-2 | --- | --- | --- | |
| Version Indicator | 3-4 | binary | F | U |
| 5-6 | --- | --- | --- | |
| Command Code | 7-8 | alphanumeric | F | U |
| 9-10 | --- | --- | --- | |
| Response Code | 11-12 | binary | --- | A |
| Command ID | 13-16 | alphanumeric/ binary | F | U |
| Database ID | 17-20 | numeric | F | U |
| File Number | 21-24 | numeric | F | U |
| 25-28 | --- | --- | --- | |
| ISN | 29-32 | binary | --- | A |
| 33-36 | --- | --- | --- | |
| ISN Lower Limit | 37-40 | binary | F | A |
| 41-44 | --- | --- | --- | |
| ISN Quantity | 45-48 | binary | --- | A |
| Command Option 1 | 49 | alphanumeric | F | U |
| Command Option 2 | 50 | alphanumeric | F | U |
| 51-56 | --- | --- | --- | |
| Additions 1 | 57-64 | alphanumeric/ binary | F | U |
| --- | 65-68 | --- | --- | --- |
| Additions 3 | 69-76 | alphanumeric/ binary | F | A |
| 77-84 | --- | --- | --- | |
| Additions 5 | 85-92 | alphanumeric/ binary | F | U |
| 93-114 | --- | --- | --- | |
| Error Subcode | 115-116 | binary | --- | A |
| 117-144 | --- | --- | --- | |
| Command Time | 145-152 | binary | --- | A |
| User Area | 153-168 | not applicable | --- | U |
| --- | 169-193 | do not touch | --- | --- |
| ABD and Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| Format | F | U |
| Record | --- | A |
| Search | F | U |
| Value | F | U |
| Multifetch * | --- | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | The multifetch buffer is required only if the multifetch option is specified |
| --- | Not used |
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
F2
L9
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 Error Subcode (ACBXERRC) field, are described in the Adabas Messages and Codes Manual documentation.
Response code 3 indicates that an end-of-file condition has been detected.
This field must be set to a non-blank, non-zero value. This value is used by Adabas to provide the values in the correct sequence and to avoid the repetitive interpretation of the format buffer.
This field must not be modified during a given sequential pass of the file.
The first byte of this field may not be set to hexadecimal 'FF'.
Use this field to specify the database ID. The Adabas call will be directed to this database.
This field is a four-byte binary field, but at this time only two-byte database IDs are supported. Therefore, the database ID should be specified in the low-order part (rightmost bytes) of the field, with leading binary zeros.
If this field is set to binary zeros, the Adabas API uses either the database ID from the ADARUN cards provided in DDCARD input data or the default database ID value provided in the LNKGBLS module linked with or loaded by the link routine.
Use this field to specify the number of the file to which the Adabas call should be directed.
This field is a four-byte binary field, but the file number should be specified in the low-order part (rightmost bytes) of the field, with leading binary zeros.
If the descriptor for which values are to be returned is contained within a periodic group, Adabas returns in this field the occurrence number in which the value being returned is located. The occurrence number is provided in binary format in the two low-order bytes.
If the prefetch option is specified, any occurrence for prefetched values is returned in the header preceding the value in the ISN buffer.
Adabas returns values in this field as follows:
| Cmd Op 1 | Cmd Op 2 | The L9 command . . . |
|---|---|---|
| blank | I | returns the ISNs for each value in the record buffer; no value is returned in the ISN lower limit field. |
| not I | places the first ISN of the returned ISN list in the ISN lower limit field. | |
| P(refetch) | I | returns the first ISN in the record buffer and all prefetched descriptor values in the ISN buffer, preceded by a 16-byte header; no value is returned in the ISN lower limit field. |
| not I | places the first ISN of the last value prefetched in the ISN lower limit field. | |
| M(ultifetch) | I | returns the group of multifetched records in the record buffer and a description of these records in the caller's ISN buffer; no value is returned in the ISN lower limit field. |
| not I | places the first ISN of the last value multifetched in the ISN lower limit field. |
If Command Option 1 is set to "M" (multifetch option), you can set:
a non-zero value in the ISN lower limit field to limit the number of values to be multifetched.
zero in the ISN lower limit field to multifetch all values.
Refer to the section Using the Multifetch/Prefetch Feature for more information.
The ACBXISL field is a four-byte binary field embedded in the eight-byte ACBXISLG field, which is not yet used. Set the high-order part of the ACBXISLG field to binary zeros.
Except when the "return ISNs" (Command Option I) is specified, Adabas returns in this field the number of records containing the value returned in the record buffer.
If the prefetch option is specified, the count of prefetched values is in the header that precedes the value in the ISN buffer.
Specifying an M option in this field indicates that the (command-level) multifetch option is to be used. The multifetch option can improve performance reading several descriptor values at a time thereby eliminating the time needed for single-record fetches. For more information, see the section Using the Multifetch/Prefetch Feature.
| Option | Description |
|---|---|
| M (multifetching) | Multifetch processing is enabled.
In conjunction with this option, you can set:
|
If the M option is specified, the L9 command puts all multifetched descriptor values in the multifetch buffer, preceded by a 16-byte header. The multifetch buffer must be large enough to hold the largest descriptor value plus 16 bytes. The actual multifetch buffer area defined in the user program must be at least as large as the multifetch buffer length specified in the corresponding multifetch buffer ABD.
| Option | Description |
|---|---|
| I | returns the ISNs for each value in the record buffer. The L9 command reads the Associator inverted lists only; no Data Storage access is required. |
| A | the descriptor's entries are processed in ascending order. |
| D | the descriptor's entries are processed in descending order. |
If both the search and value buffer lengths are set to zero, a value in the Additions 1 field is the name of the descriptor for which values are to be returned. The name must be the same as the descriptor name specified in the format buffer.
In this case, L9 processes all values for the specified descriptor from the beginning of the file.
The descriptor name is specified in the first two positions of this field. The remaining positions must be set to blanks.
This field is used to provide an Adabas 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.
Use this field to specify a separate format ID that identifies the internal format buffer used for this command, or to provide a global format ID allowing use of the internal format buffer by all users.
As long as the leftmost bit of the Additions 5 field is set to 0, the value provided in the command ID field is used as the format ID as well.
If, however, this bit is set to 1, the fifth through eighth bytes of the Additions 5 field are 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'), all eight bytes of the Additions 5 field are 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, Format, and Global Format IDs for more information and examples.
If the command returns a nonzero response code, this field contains a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.
The following buffers apply to the L9 command:
Note:
Commas separate elements in the format buffer; a period terminates
the syntax statement. For more information about format buffer syntax, read
Format Buffers.
The format in which the values are to be returned must be specified in this buffer.
The syntax of the format buffer for L9 operation is:
name [ ,length ] [ ,format ] .
where:
| name | The name of the descriptor for which values are to be returned. A phonetic descriptor or hyperdescriptor may not be specified. A collation descriptor may only be specified if the decode option has been specified in its user exit: the value returned for it is not the index but the original field value. Subdescriptors, superdescriptors and descriptors defined as a multiple-value field may 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 standard length of the descriptor. |
| 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 no format is specified, the value will be returned using the standard format of the descriptor. |
The descriptor value for the descriptor specified in the search and value buffers is returned in this field. A different value is provided with each L9 call. If the descriptor is defined with the null value suppression option, no value for the descriptor will be returned. If the Command Option 2 field is set to "I", Adabas returns a list of ISNs containing the requested value as well as the value itself in this buffer. The ISNs are provided in ascending sequence.
The descriptor value is provided as follows:
length value count ISN-list
where:
| length | A one-byte binary value which is the length of the value being provided. If the value has a standard length according to the descriptor type, this field is zero. |
| value | A descriptor value. |
| count | The number of values present in the file for the specified descriptor. This number may be returned in one or two bytes. If in one byte, the format is X'cc' where "cc" is the count; if in two bytes, the format is X'8ccc' where "ccc" is the count. |
| ISN-list | If the Command Option 2 field
specified "I", the rest of the record buffer contains ISNs of the records
containing this value. One record buffer will contain only the ISNs from one NI
(normal index) block. Therefore:
|
Note:
Commas separate elements in the search buffer; a period terminates
the syntax statement. For more information about search buffer syntax, read
Search
Buffers.
If both the search and value buffer lengths are set to zero, a value in the Additions 1 field is the name of the descriptor for which values are to be returned. In this case, L9 processes all values for the specified descriptor from the beginning of the file. The search and value buffers are not used.
If a starting value, ending value, or both are specified in the value buffer, the search buffer is required in order to limit the number of descriptor entries retrieved.
The length and format of the descriptor value as provided in the value buffer must be specified in the search buffer if different from the standard length and/or format of the named descriptor.
When a single value is provided in the value buffer (that is, the starting value when Command Option 2 is set to 'A' or the ending value when Command Option 2 is set to 'D'), the syntax for the search buffer is
name [ i ] [ ,length ] [ ,format ] [ ,comparator ]
When two values are provided in the value buffer, the syntax for the search buffer is
name [ i ] [ ,length ] [ ,format ] ,S ,name [ ,length ] [ ,format]
The elements used in the search buffer syntax statements are as follows:
| name | The name of the descriptor for which values are to be returned. The name must be the same as that specified in the format buffer. | |||||||
|---|---|---|---|---|---|---|---|---|
| i | A one- to three-digit occurrence number subscript appended to the descriptor name if the descriptor is contained within a periodic group and only values within that particular occurrence are to be returned. | |||||||
| length | The length of the value provided in the value buffer. If the length is not specified, it is assumed that the value is being provided using the standard length of the descriptor. | |||||||
| format | The format of the value provided in the value buffer. If the format is not specified, it is assumed that the value is being provided using the standard format of the descriptor. | |||||||
| comparator | The scope of the read sequence: | |||||||
|
||||||||
| S | A FROM-TO range (inclusive) that involves two search expressions. The same descriptor must be used in both expressions: | |||||||
|
If both the search and value buffer lengths are set to binary zeros, a value in the Additions 1 field is the name of the descriptor for which values are to be returned. In this case, L9 processes all values for the specified descriptor in the sequence specified in the Command Option 2 field: from the beginning (A option) or end (D option) of the file. The search and value buffers are not used.
If a starting value, ending value, or both are specified in the value buffer, the search buffer is required in order to limit the number of descriptor entries retrieved.
If the search buffer comparator is GE or GT and a single value is provided in the value buffer, it represents the starting value when Command Option 2 is set to A or the ending value when Command Option 2 is set to D.
When two values are provided in the value buffer, the first specifies the lower limit of a range and the second specifies the upper limit. Each value is either the starting or ending value depending on the Command Option 2 setting of A or D.
If a value specified is not present in the file, Adabas finds the next higher or lower value, depending on the Command Option 2 setting of A or D. In this case, search buffer comparator LE is equivalent to LT and GE is equivalent to GT. If the value specified is not present and no higher (or lower) value is present, response code 3 is returned.
The ISN buffer is used only if the command-level multifetch option is used and if this command is issued using the ACB direct call interface. The information held in the ISN buffer following an L9 command results from specifying the M (multifetch) or P (prefetch) option in the Command Option 1 field. The format of the ISN buffer data depends on which option was specified.
See section READ (Lx) Multifetch Processing for the record descriptor data format.
Note:
The prefetch option is valid only for
ACB interface direct calls.
The ISN buffer holds the optionally prefetched descriptor values, each preceded by a 16-byte header. The 16-byte header preceding each value has the following format:
| Byte | Usage |
|---|---|
| 1-2 | length of descriptor (including this header) |
| 3-4 | nucleus response code |
| 5-8 | nucleus internal ID |
| 9-12 | periodic group occurrence (see the ISN field description) |
| 13-16 | record count (see the ISN quantity field description) |
The multifetch buffer is used only if the command-level multifetch option is used and if this command is issued using the ACBX direct call interface. See section READ (Lx) Multifetch Processing for the record descriptor data format. For more information, read Using the Multifetch/Prefetch Feature.
The following additional considerations are applicable for the L9 command:
The command ID used with the L9 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. Until it is released, the command ID may not be used for another command.
If another user is updating the file being read with an L9 command, it is possible that you will not receive one or more values in the file while reading with the L9 command.
Records can be updated in or deleted from a file being read by an L9 command. Adabas attempts to keep track of the last and the next value to be provided to the L9 command, and to provide the correct next value despite any interim update or deletion. However, if the record about to be accessed by the L9 command changes for some reason (it is updated or deleted by another user, for example), the L9 command continues processing as though no change occurred. In other words, a record deleted just before its inverted list entry is accessed by the L9 command is still considered a valid entry by the L9 command.
An internal format buffer used by an L9 command must have been created by a previous L9 command. Non-L9 commands cannot use internal format buffers created by L9 commands.
