This document covers the following topics:
The S1/S2/S4 commands are used to select a set of records which satisfy given search criteria.
The result of an S1/S2/S4 command is the set of records which satisfy the query along with a list of the ISNs of the records. If the S1/S4 command is used, the ISNs are returned in ascending sequence in the ISN buffer. If the S2 command is used, the ISNs are returned according to a user-specified sort sequence. The S4 command places the first ISN in the resulting ISN list in hold status, i.e. lock the record for other users. The S4 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 lock of a lower locking mode for the record the lock is upgraded to the locking mode requested. If the user already holds a higher locking mode for the re-cord, the locking mode remains unchanged.
Adabas will store (if requested) on the Adabas temporary working space any ISNs which could not be inserted in the ISN buffer on the initial S1/S2/S4 call. These overflow ISNs may be retrieved subsequently by using further S1/S2/S4 calls. See Programming Considerations, ISN List Processing for additional information.
Adabas will release an overflow ISN list when the last ISN in the list has been returned to the user. If the user needs to retain the entire ISN list indefinitely, the SAVE ISN LIST option may be used. If this option is specified, the entire ISN list is stored on the Adabas temporary working space and is not released until an RC or CL command is issued (or the Adabas session is terminated).
If the user intends to read the records identified by the ISNs in the list by using the GET NEXT option of the L1/L4 command, the ISN buffer is not required. ISNs are obtained automatically from the stored ISN list by Adabas when this option is used.
The record identified by the first ISN in the resulting ISN list may optionally be read from Data Storage with the S1/S2/S4 command by providing a format 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 |
| Command Option 3 (ACBX only) | 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 (1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.
- Command Code
S1/S2/S4
- Command ID
This field is used to provide a value to identify the resulting ISN list if it is to be stored on the Adabas temporary working space.
If the SAVE ISN LIST option is to be used, or if overflow ISNs are to be stored, a non-blank, non-zero value must be provided in this field.
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).
See Programming Considerations, ISN List Processing for additional information.
- File Number
The number of the file from which the ISNs are to be selected.
- Response Code
Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully.
- ISN
Adabas returns the first ISN of the resulting ISN list in this field. If there were no resulting ISNs, this field is not modified. This applies to both the initial call and any subsequent calls which are used to retrieve ISNs from the Adabas temporary working space.
- ISN Lower Limit
This field may be used in an initial Sx call to limit the resulting ISN list to those ISNs which are greater than the ISN specified in this field. If this field is set to zeros, Adabas will return all qualifying ISNs.
In a subsequent Sx call, this field is used when a group of ISNs from a saved ISN list is being retrieved from the Adabas temporary working space, in order to determine the first ISN to be used.
- ISN Quantity
Adabas returns, as a result of an initial Sx call, the number of records which satisfy the search criteria in this field.
Adabas returns, as a result of a subsequent Sx call used to retrieve ISNs from the Adabas temporary working space, the number of ISNs returned in the ISN buffer.
- 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). The search buffer area defined in the user program must be as large as (or larger than) the length specified.
- Value Buffer Length (ACB only)
The value buffer length (in bytes). The value 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). This length is used to determine the number of ISNs placed in the ISN buffer.
If this field is set to zeros, no ISNs will be inserted in the ISN buffer. This field should be set to zeros if the resulting ISN list is to be read with the GET NEXT option of the L1/L4 command, or if the command is being issued only to determine the number of qualifying records.
If a non-zero value is specified, it should be a multiple of 4. If it is not, Adabas will reduce the length to the next-lowest integer which is a multiple of 4.
- Command Option 1
An `H' in this field invokes the SAVE ISN LIST option. This option causes Adabas to store the entire resulting ISN list on the Adabas temporary working space.
An `R' in this field indicates that the return option is to be used. If an S4 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 place the user in hold status until the record becomes available.
- Command Option 2
If the S2 command is being used, this field is used to indicate whether the resulting ISNs are to be sorted in ascending or descending sequence.
A `D' indicates that descending sequence is to be used.
A 'T' indicates that the index truncation check is to be preformed. If this option is specified, the search buffer must contain a descriptor with the TR option, and the value buffer must contain the corresponding value. In this case, no search operation is performed, there is only a check made to see whether or not the specified descriptor value is truncated in the index: response code 0 indicates no truncation, response code 2 indicates truncation.
- Command Option 1/2
An `I' in either of these fields causes the release of the CID value specified in the command ID field as the first action taken during command execution.
- Command Option 3 (ACBX only)
The command option 3 is relevant only for an S4 command.
A ‘C’ in this field indicates that a shared lock is to be acquired for the first record found for 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 first record found 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 is allowed only for an S4 command with a command ID and ISN buffer length 4, and indicates that the first record found 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, which 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 only released 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).
Note:
If an S4 command finds only one record and the command option 1 is not equal to 'H', no ISN list entry is generated. Therefore you cannot perform a sequential read command for the command ID, which would release the record if it was read with the 'Q' option. This means that the record read with the 'Q' option remains in shared hold status until an event occurs that would also release a record that is read with the 'S' option.A blank in this field indicates that the record is locked exclusively.
- Additions 1
If the S2 command is being used, this field is used to specify the field name(s) to be used to control the sort sequence. From one to four names may be specified. Descriptor or non-descriptor field names may be used, but they must not be derived from a periodic group. Hyperdescriptors may be specified but not in combination with non-descriptor field names. Phonetic descriptors must not be specified. Subdescriptors and superdescriptors may be specified if they are not derived from a PE group. A multiple-value field may be specified, in which case the ISNs will be sorted corresponding to the highest value present within a given record.
The descriptors are specified beginning with byte 1 (left-justified) and any remaining positions must be set to blanks ("b" in the following example).
Example:
XXYYbbbbXX = major sort descriptor YY = minor sort descriptorIf using non-descriptor fields, all of their values must be within the standard FDT length if the length is not equal to zero, otherwise response 1 may be returned.
If a descriptor defined with the NU option and containing null values is used for the sort sequence, the null values appear at the beginning of the sorted list.
Example:
Sorted list with NU option : 0, -1, +1 Sorted list without NU option : -1, 0, +1- Additions 2
If at least one record is found, and at least one Adabas field is requested in the format buffer, Adabas will return the compressed record length of the record which has been read in this field. The length is provided in the first two bytes in binary format.
The last two bytes of this field contain the length of the decompressed fields selected by the Format buffer, in binary format.
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.
If the record identified by the first ISN in the resulting ISN list is to be read from Data Storage, the fields within the record 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.
If no read is to be performed, the first non-blank character in this buffer must be a period.
If a format buffer is provided, Adabas returns the requested field values in this buffer.
The values are returned according to the standard length and format of the field, unless the user has explicitly requested a different length and/or format in the format buffer.
These buffers are used to define the search criterion. The search expression (or expressions) is provided in the search buffer, and the values which correspond to the search expressions are provided in the value buffer.
The syntax and examples of search and value buffer construction are provided in Calling Adabas, Search and Value Buffers.
Adabas places the list of resulting ISNs in this buffer. Each ISN is returned as a four-byte binary number.
The ISNs are returned in ascending ISN sequence unless the S2 command is being used, in which case they are returned in the user-specified sort sequence.
If the ISN buffer length field is set to zeros, no ISNs will be returned in the ISN buffer.
If the ISN buffer length is not zero, the ISN buffer is not large enough to contain all the resulting ISNs and a non-blank, non-zero command ID was used, Adabas will store the overflow ISNs on the Adabas temporary working space. These ISNs may then be retrieved using further S1/S2/S4 calls in which the same command ID is used. See Programming Considerations, ISN List Processing for additional information.
Note:
All the examples in this section refer to the files in Appendix A.
The set of records in file 1 which contain a value in the range A to J for the descriptor AA is to be selected.
Command Code S1
Command ID bbbb (no ISNs are to be stored on the
Adabas temporary working space)
File Number 1
ISN Lower Limit 0 (all qualifying ISNs are to be returned)
Format Buffer Length 1 (or larger)
Search Buffer Length 12 (or larger)
Value Buffer Length 2 (or larger)
ISN Buffer Length 200 (no more than 50 ISNs are expected)
Command Option 1 b (SAVE ISN LIST option not used)
Additions 3 bbbbbbbb (the file is not security
protected)
Format Buffer . (no read to be done)
Search Buffer AA,1,S,AA,1.
Value Buffer C'AJ'
FIND with READ option. The ISN of the record containing the value ABCDEFGH for the field AA in file 1 is to be selected. The record is also to be read from Data Storage with the value for the field AC to be returned.
Command Code S1
Command ID bbbb (no ISNs are to be stored on the
Adabas temporary working space)
File Number 1
ISN Lower Limit 0 (all qualifying ISNs are to be returned)
Format Buffer Length 3 (or larger)
Record Buffer Length 20 (or larger)
Search Buffer Length 3 (or larger)
Value Buffer Length 8 (or larger)
ISN Buffer Length 4 (no more than 1 ISN expected)
Command Option 1 b (the Save ISN List option is not to be
used)
Additions 3 bbbbbbbb (file is not security protected)
Format Buffer AC. (the value for field AC is to be
returned)
Search Buffer AA.
Value Buffer "ABCDEFGH"
0x6162636465666768
(or ^X6162636465666768)
FIND with ISN buffer overflow. The set of records which contain any value in the range A to D for field AA in file 1 are to be selected. ISN buffer overflow handling is to be used.
Command Code S1
Command ID ABCD (a non blank Command ID is required)
File Number 1
ISN Lower Limit 0 (all qualifying ISNs are to be returned)
Format Buffer Length 1 (or larger)
Record Buffer Length 0 (or larger)
Search Buffer Length 12 (or larger)
Value Buffer Length 2 (or larger)
ISN Buffer Length 100 (up to 25 ISNs will be returned with
each call)
Command Option 1 b (SAVE ISN LIST option not used)
Additions 3 bbbbbbbb (file is not security protected)
Format Buffer . (no read to be performed)
Search Buffer AA,1,S,AA,1.
Value Buffer "AD"
0x6164
(or ^X6164)
Adabas will return, as a result of the initial S1 call, a maximum of 25 ISNs in the ISN buffer. If more than 25 ISNs resulted from the query, the remaining ISNs will be stored on the Adabas temporary working space under the command ID ABCD. These overflow ISNs may be retrieved by repeating the S1 call using the same command ID.
FIND with SAVE ISN LIST option. All the records containing the value +80 for the field XB in file 2 are to be selected. The entire resulting ISN list is to be stored on the Adabas temporary working space.
Command Code S1
Command ID BCDE (a non blank CID is required when
using the Save ISN List option)
File Number 2
ISN Lower Limit 0 (all qualifying ISNs are to be selected)
Format Buffer Length 1 (or larger)
Record Buffer Length 0 (or larger)
Search Buffer Length 3 (or larger)
Value Buffer Length 2 (or larger)
ISN Buffer Length 200 ( a maximum of 50 ISNs will be
returned on each call)
Command Option 1 H (Save ISN List option is to be used)
Additions 3 Password (file is security protected)
Format Buffer . (no read is to be done)
Search Buffer XB.
Value Buffer 0x080C
(or ^X080C)
The user may retrieve any group of ISNs from the ISN list which is stored as a result of this call by repeating the S1 command using the command ID BCDE. Adabas will insert as many ISNs as can be accommodated in the ISN buffer, starting with the first ISN which is greater than the ISN specified in the ISN Lower Limit field.
FIND with SORT. All records containing a value in the range A to F for the field AA in file 1 are to be selected. The resulting ISN list is to be returned in the ascending order of the values for field AB.
Command Code S2
Command ID CDEF (a non blank Command ID is required
when using the S2 command)
File Number 1
ISN Lower Limit 0 (all qualifying ISNs are to be selected)
Format Buffer Length 1 (or larger)
Record Buffer Length 0 (or larger)
Search Buffer Length 12 (or larger)
Value Buffer Length 2 (or larger)
ISN Buffer Length 100 ( a maximum of 25 ISNs will be
returned on each call)
Command Option 1 b (the Save ISN List option is not used)
Command Option 2 b (the descending sort option is not used)
Additions 1 ABbbbbbb (resulting ISNs are to be sorted
on the values of field AB)
Additions 3 bbbbbbbb (file is not security protected)
Format Buffer . (no read is to be done)
Search Buffer AA,1,S,AA,1.
Value Buffer "AF"
0x6166
(or ^X6166)
FIND with HOLD. The record in file 1 containing the value 87654321 for field AA is to be selected. The record is also to be read and placed in hold status. The values for fields AB and AC are to be returned.
Command Code S4
Command ID bbbb (blank Command ID may be used since
SAVE ISN LIST option is not to be used
and no overflow ISNs are expected)
File Number 1
ISN Lower Limit 0 (all qualifying ISNs are to be selected)
Format Buffer Length 6 (or larger)
Record Buffer Length 22 (or larger)
Search Buffer Length 3 (or larger)
Value Buffer Length 8 (or larger)
ISN Buffer Length 4 (only 1 ISN is expected)
Command Option 1 b (the Save ISN List option is not to be
used)
Additions 3 bbbbbbbb (file is not security protected)
Format Buffer AB,AC. (the record which is identified by
the first ISN is to be read, values for
fields AB and AC are to be returned)
Search Buffer AA.
Value Buffer "87654321"
0x6867666564636261
(or ^X6867666564636261)
Find using multiple search criteria (complex search). The set of records in file 2 containing a value of ABCD for subdescriptor SA, a value less than 80 for field XB and a value in the range MMMMM through ZZZZZ (but not Sbbbb through TZZZZ) for field XE is to be selected.
Command Code S1
Command ID GGGG (a non blank Command ID is used
since Save ISN List option is to be used)
File Number 2
ISN Lower Limit 0 (all qualifying ISNs are to be selected)
Format Buffer Length 1 (or larger)
Record Buffer Length 0 (or larger)
Search Buffer Length 35 (or larger)
Value Buffer Length 27 (or larger)
ISN Buffer Length 0 (No ISNs to be returned in the ISN
Buffer).
Command Option 1 H (Save ISN List option is to be used)
Additions 3 Password (file 2 is security protected)
Format Buffer . (no read is to be done)
Search Buffer SA,D,XB,3,U,LT,D,XE,S,XE,N,XE,S,XE.
Value Buffer C'ABCD080MMMMMZZZZZSbbbbTZZZZ'