The S1, S2, and S4 commands return a count of records and ISNs of records satisfying the search criterion.
This document covers the following topics:
The S1, S2, and S4 commands are used to select records that satisfy a given search criterion. They can be performed on Adabas expanded files as well.
The result of an S1, S2, or S4 command is the number of records which satisfy the query and a list of the records' ISNs. The S1/S4 commands return the ISNs, sorted in ascending sequence; the S2 command returns the ISNs according to a sort sequence specified in the Additions 1 field. Regardless of sequence, the ISNs are returned to the ISN buffer.
Note:
ISN lists that are not in ascending sequence cannot be processed by
a later S8 command.
The following types of searches are possible:
Single file search. The search criterion consists of one or more fields contained in a single file.
Multiple file search using physically coupled files. The search criterion consists of fields contained in two or more files that have been physically coupled using the ADAINV utility.
Search using the soft coupling feature. This feature provides for a combination of search, read, and internal list matching.
A search criterion may contain one or more fields that are not defined as descriptors. If nondescriptors are used, Adabas performs read operations to determine which records to return to the user. If only descriptors are used within the search criterion, Adabas resolves the query by using the Associator inverted lists; no read operation is required.
Note:
The behavior of nondescriptor searches in Adabas databases differs
between mainframe and open systems in regards to null suppression in the
fields. In open systems, nondescriptor searches do not return records with null
values in a field if the field is null-suppressed (NU); on mainframe systems,
the null-suppression (NU) of fields is ignored during nondescriptor searches.
At this time, to resolve this problem, we recommend that you remove the null
suppression option (NU) for open systems fields, if the fields must be used for
a nondescriptor search.
If a valid command ID is specified, Adabas will store on Adabas Work any ISNs that could not be inserted in the ISN buffer on the initial S1, S2, or S4 command. These overflow ISNs may be retrieved to the ISN buffer later with additional S1, S2, or S4 commands that specify the same command ID.
Adabas releases 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 Adabas Work. The ISN list is not released until either an RC, CL, or Sx command with the release CID option is issued, or the Adabas session is terminated.
If the user intends to use the GET NEXT option of an L1 or L4 command to read the records identified by the ISNs, neither the ISN buffer entry nor the save-ISN-list option is required. In this case, the L1 and L4 commands obtain the ISNs automatically from the ISN list stored by Adabas.
By placing field names in the format buffer, the user can read the field's contents from the record of the first ISN in the resulting ISN list. The field's contents are read into the record buffer. The S4 command also places the first ISN of the resulting ISN list in hold status.
This section describes ACB interface direct calls for the S1, S2, and S4 commands. It covers the following topics:
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
| 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 | U |
| ISN Quantity | 21-24 | binary | F * | 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 / binary | -- | A |
| Additions 3 | 49-56 | alphanumeric | F | A |
| Additions 4 | 57-64 | alphanumeric | F | A |
| 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 |
| * | Optional timeout value, in seconds |
| -- | Not used |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
S1, S2, or S4
This value identifies the resulting complete or overflow ISN list stored on Adabas Work, and identifies the format buffer for subsequent commands if the read-first-record option is in effect (see the section Format Buffer).
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 first byte of this field may not be set to hexadecimal 'FF'.
See the section ISN List Processing for more information.
File number specifies the number of the file from which the ISNs are to be selected.
If a query using coupled files is to be performed, the file specified in this field will be considered the "primary" file. The file number of physically coupled files must be no greater than 255.
The search can also be performed on Adabas expanded files.
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.
Adabas returns the first ISN of the resulting ISN list in this field. If there were no resulting ISNs, this field is set to zeros.
Use this field in the first S1 or S4 call to specify a minimum ISN value for the resulting ISN list. The list will then contain only the ISNs greater than the ISN specified in this field. If this field is set to zeros, Adabas will return all qualifying ISNs.
Note:
Note this will not work for an S2 call. For sorted ISN lists (S2
commands), this field must be set either to zero or to a valid ISN.
This field is also used when a group of ISNs from a saved ISN list is being retrieved from Adabas Work.
This field defines the maximum number of seconds that can be used for Sx command execution.
As a result of an initial Sx call, Adabas returns the number of records that satisfy the search criterion in this field. If security-by-value is being used, response code 1 is returned in this field along with the value 0 (one record found) or 1 (more than one record found). For more information, see the Adabas Security Manual.
As a result of a subsequent Sx call used to retrieve ISNs from Adabas Work, Adabas provides the number of returned ISNs in this field. The ISNs themselves are returned in the ISN buffer.
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.
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.
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.
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.
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 or 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 lower integer which is a multiple of 4.
| Option | Description |
|---|---|
| H (save ISN list) | Stores the entire ISN list resulting from an Sx command on Adabas Work under the specified command ID. A valid command ID must be specified. If no command ID is specified, the ISN list is not stored on Work and any ISNs not saved in the ISN buffer are lost. |
| R (return) | For an S4 command, returns response code 145 if a record to be read and held is not available. |
| Option | Description |
|---|---|
| D (descending sequence) | For an S2 command, sorts descriptor values in descending sequence. |
If no Command Option 2 is specified for an S2 command, the descriptor values are sorted in ascending sequence.
The I option may be specified in either the Command Option 1 or Command Option 2 field:
| Option | Description |
|---|---|
| I | Releases the command ID (CID) value specified in the command ID field as the first action taken during command execution. The specified command ID is released only from the table of ISN lists. The same command ID is then reused to identify the resulting list of ISNs. |
If the S2 command is being used, this field must specify the descriptor (or descriptors) to be used to control the sort sequence; if no sort argument is specified, the S2 command returns response code 28.
One to three descriptors, including subdescriptors and superdescriptors, can be specified. Phonetic descriptors or descriptors contained within a periodic group cannot be specified. A multiple-value field can be specified, in which case the ISNs will be sorted according to the lowest value present within a given record.
Any unused positions of this field must be set to blanks. For example:
XXYYbbbb
where:
| XX | is the major sort descriptor; and |
| YY | is the minor sort descriptor |
| bbbb | blanks |
The number of ISNs that can be sorted depends on the size of the sort work area (ADARUN LS parameter) defined by the DBA. If the sort area is too small, no sort will be performed; response code 1 will be returned, and the ISNs will be returned in ascending sequence.
If the command is processed successfully, the following information is returned in this field:
If the record buffer contains at least one valid field value, the leftmost two bytes contain the length (in binary form) of the compressed record accessed;
The rightmost two bytes contain the length (in binary form) of the decompressed fields selected by the format buffer and accessed.
If the Sx command returns a non-zero response code, the rightmost two bytes 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.
This field is used to provide a cipher code. If the file is ciphered, the user must provide a valid cipher code. If the file is not ciphered, this field should be set to blanks.
Adabas sets any cipher code to blanks during command processing, and returns a version code and the database ID in the rightmost (low-order) three bytes of this field. For more information, see the section Control Block Fields.
This field may be used to provide a separate format ID to identify the internal format buffer to be used for this command, or to provide a global format ID.
If the high-order bit of the Additions 5 field is zero (0), the value provided in the command ID field is also used as the format ID.
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).
For more information, refer to the section Command, Format, and Global Format IDs.
For the Adabas file definitions used in all the examples in this section, see File Definitions Used in Examples.
Select the records in file 1 that contain a value in the range "A" to "J" for the descriptor AA.
| Command Code | S1 | |
|---|---|---|
| Command ID | bbbb (blanks) | no ISNs are to be stored on the Adabas Work |
| 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 (blank) | save-ISN-list option not used |
| Additions 3 | bbbbbbbb (blanks) | 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. Select the ISN of the record containing the value "ABCDEFGH" for the field AA in file 1. Also, read the record from Data Storage and return the value for the field AC.
| Command Code | S1 | |
|---|---|---|
| Command ID | bbbb (blanks) | no ISNs are to be stored on the Adabas Work |
| 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 one ISN is expected |
| Command Option 1 | b (blank) | save-ISN-list option not used |
| Additions 3 | bbbbbbbb (blanks) | file is not security-protected |
| Additions 4 | bbbbbbbb (blanks) | file is not ciphered |
| Format Buffer | AC. | the value for field AC is to be returned |
|---|---|---|
| Search Buffer | AA. | |
| Value Buffer | C'ABCDEFGH' X'C1C2C3C4C5C6C7C8' |
Find with ISN buffer overflow. Select the records that contain any value in the range "A" to "D" for field AA in file 1. Use ISN buffer overflow handling.
| 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 (blank) | save-ISN-list option not used |
| Additions 3 | bbbbbbbb (blanks) | file is not security-protected |
| Format Buffer | . | no read to be done |
|---|---|---|
| Search Buffer | AA,1,S,AA,1. | |
| Value Buffer | C'AD' X'C1C4' |
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 Adabas Work 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. Select all the records containing the value "+80" for the field XB in file 2. Store the entire resulting ISN list on the Adabas Work.
| Command Code | S1 | |
|---|---|---|
| Command ID | BCDE | a non-blank command ID 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 | X'080C' |
The user may retrieve any group of ISNs from the ISN list that 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 that is greater than the ISN specified in the ISN lower limit field.
Find with sort. Select all records containing a value in the range "A" to "F" for the field AA in file 1. Return the resulting ISN list in 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, where bbbbbb represents blanks. |
| Additions 3 | bbbbbbbb (blanks) | file is not security-protected |
| Format Buffer | . | no read is to be done |
|---|---|---|
| Search Buffer | AA,1,S,AA,1. | |
| Value Buffer | C'AF' X'C1C6' |
Find with hold. Select the record in file 1 containing the value "87654321" for field AA. Also, read the record and place it in hold status. Return the values for fields AB and AC.
| Command Code | S4 | |
|---|---|---|
| Command ID | bbbb (blanks) | 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 one ISN is expected |
| Command Option 1 | b (blank) | the save-ISN-list option is not to be used |
| Additions 3 | bbbbbbbb (blanks) | file is not security-protected |
| Additions 4 | bbbbbbbb (blanks) | file is not ciphered |
| Format Buffer | AB,AC. | the record identified by the first ISN is to be read, values for fields AB and AC are to be returned |
|---|---|---|
| Search Buffer | AA. | |
| Value Buffer | C'87654321' X'F8F7F6F5F4F3F2F1' |
Find using coupled files. Select the records in file 1 containing the value "+100" for the field AB that are coupled to records in file 2 containing the value 'ABCDE' for the field RB.
| Command Code | S1 | |
|---|---|---|
| Command ID | EFGH | a non-blank command ID is used since ISN overflow may occur |
| File Number | 1 | file 1 is the primary file |
| ISN Lower Limit | 0 | select all qualifying ISNs |
| Format Buffer Length | 1 | or larger |
| Record Buffer Length | 0 | or larger |
| Search Buffer Length | 14 | or larger |
| Value Buffer Length | 12 | or larger |
| ISN Buffer Length | 100 | return a maximum of 25 ISNs with each call |
| Command Option 1 | b | save-ISN-list option is not to be used |
| Additions 3 | password | file 2 is security-protected |
| Format Buffer | . | no read is to be done |
|---|---|---|
| Search Buffer | /1/AB,D,/2/RB. | |
| Value Buffer | X'100CC1C2C3C4C54040404040' |
Because file 1 was specified as the primary file, the resulting ISNs will be from file 1. If ISNs from file 2 are also desired, the find may be repeated with file number 2 specified in the file number field. The order of the search criteria in the search buffer need not be changed.
Find using multiple search criteria (complex search). Select 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.
| Command Code | S1 | |
|---|---|---|
| Command ID | GGGG | a non-blank command ID is used since the save-ISN-list option is to be used |
| File Number | 2 | |
| ISN Lower Limit | 0 | select all qualifying ISNs |
| 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' |
This section describes ACBX interface direct calls for the S1, S2, and S4 commands. It covers the following topics:
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
| 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 | U |
| 41-44 | --- | --- | --- | |
| ISN Quantity | 45-48 | binary | F* | 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 |
| Additions 2 | 65-68 | binary | --- | A |
| Additions 3 | 69-76 | alphanumeric/ binary | F | A |
| Additions 4 | 77-84 | alphanumeric | F | A |
| 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 |
| ISN | --- | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Optional timeout value, in seconds |
| --- | Not used |
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
F2
S1, S2, or S4
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.
This value identifies the resulting complete or overflow ISN list stored on Adabas Work, and identifies the format buffer for subsequent commands if the read-first-record option is in effect (see the section Format Buffer).
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 first byte of this field may not be set to hexadecimal 'FF'.
See the section ISN List Processing for more information.
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 from which the ISNs are to be selected.
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.
Note:
For commands that operate on a coupled file pair, this field
specifies the primary file from which ISNs or data are returned. The file
number of physically coupled files must be no greater than 255.
The search can also be performed on Adabas expanded files.
Adabas returns the first ISN of the resulting ISN list in this field. If there were no resulting ISNs, this field is set to zeros.
Use this field in the first S1 or S4 call to specify a minimum ISN value for the resulting ISN list. The list will then contain only the ISNs greater than the ISN specified in this field. If this field is set to zeros, Adabas will return all qualifying ISNs.
Note:
Note this will not work for an S2 call. For sorted ISN lists (S2
commands), this field must be set either to zero or to a valid ISN.
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.
This field is also used when a group of ISNs from a saved ISN list is being retrieved from Adabas Work.
This field defines the maximum number of seconds that can be used for Sx command execution.
The ACBXISQ field is a four-byte binary field embedded in the eight-byte ACBXISQG field, which is not yet used. Set the high-order part of the ACBXISQG field to binary zeros.
As a result of an initial Sx call, Adabas returns the number of records that satisfy the search criterion in this field. If security-by-value is being used, response code 1 is returned in this field along with the value 0 (one record found) or 1 (more than one record found). For more information, see the Adabas Security Manual.
As a result of a subsequent Sx call used to retrieve ISNs from Adabas Work, Adabas provides the number of returned ISNs in this field. The ISNs themselves are returned in the ISN buffer.
| Option | Description |
|---|---|
| H (save ISN list) | Stores the entire ISN list resulting from an Sx command on Adabas Work under the specified command ID. A valid command ID must be specified. If no command ID is specified, the ISN list is not stored on Work and any ISNs not saved in the ISN buffer are lost. |
| R (return) | For an S4 command, returns response code 145 if a record to be read and held is not available. |
| Option | Description |
|---|---|
| D (descending sequence) | For an S2 command, sorts descriptor values in descending sequence. |
If no Command Option 2 is specified for an S2 command, the descriptor values are sorted in ascending sequence.
The "I" option may be specified in either the Command Option 1 or Command Option 2 field:
| Option | Description |
|---|---|
| I | Releases the command ID (CID) value specified in the command ID field as the first action taken during command execution. The specified command ID is released only from the table of ISN lists. The same command ID is then reused to identify the resulting list of ISNs. |
If the S2 command is being used, this field must specify the descriptor (or descriptors) to be used to control the sort sequence; if no sort argument is specified, the S2 command returns response code 28.
One to three descriptors, including subdescriptors and superdescriptors, can be specified. Phonetic descriptors or descriptors contained within a periodic group cannot be specified. A multiple-value field can be specified, in which case the ISNs will be sorted according to the lowest value present within a given record.
Any unused positions of this field must be set to blanks. For example:
XXYYbbbb
where:
| XX | is the major sort descriptor; and |
| YY | is the minor sort descriptor |
| bbbb | blanks |
The number of ISNs that can be sorted depends on the size of the sort work area (ADARUN LS parameter) defined by the DBA. If the sort area is too small, no sort will be performed; response code 1 will be returned, and the ISNs will be returned in ascending sequence.
If the command is processed successfully, the following information is returned in this field:
If the record buffer contains at least one valid field value, the leftmost two bytes contain the length (in binary form) of the compressed record accessed;
The rightmost two bytes contain the length (in binary form) of the decompressed fields selected by the format buffer and accessed.
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.
This field is used to provide a cipher code. If the file is ciphered, the user must provide a valid cipher code. If the file is not ciphered, this field should be set to blanks.
Adabas sets any cipher code to blanks during command processing, and returns a version code and the database ID in the rightmost (low-order) three bytes of this field. For more information, see the section Control Block Fields.
This field may be used to provide a separate format ID to identify the internal format buffer to be used for this command, or to provide a global format ID.
If the high-order bit of the Additions 5 field is zero (0), the value provided in the command ID field is also used as the format ID.
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).
For more information, refer to the section Command, Format, and Global Format IDs.
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 should be specified with the S1, S2, and S4 commands:
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. Descriptions of the syntax and examples of format buffer construction are provided in Defining Buffers. User-specified fields for controlling the S2 command's ISN sort sequence must be specified in the Additions 1 field.
If no read is to be performed, the first non-blank character of this buffer must be a period (.).
If a valid command ID is specified, Adabas retains this decoded format buffer for use by later commands specifying the same command ID.
If the format buffer contains field definitions to enable the read option, 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 specifies a different length and/or format in the format buffer.
Search and value buffers are used to define the search criteria. 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.
Descriptions of the syntax and examples of format buffer construction are provided in Defining 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 query contains one or more file-coupling criteria, the resulting ISN list contains only those ISNs in the primary file (the file specified in the control block's file number field).
If the ISN buffer length field is set to less than 4, no ISNs are returned in the ISN buffer. If a valid command ID is specified, the ISN buffer length is not zero, but the ISN buffer is still too small to contain all the resulting ISNs, Adabas will store the overflow ISNs on Adabas Work. These ISNs may then be retrieved using further S1, S2, or S4 calls in which the same command ID is used.
See the section ISN List Processing for additional information.
