This document covers the following topics:
The S9 command is used to sort an ISN list which was created using an Sx command, or to sort a list of ISNs provided by the user.
Two types of sorting may be done:
In the order of ISN values (ascending ISN sequence);
In the order of the values of a user-specified descriptor (or descriptors). The user may specify from one to four descriptors which are to be used to control the sort sequence. Either ascending or descending sequence may be specified.
The ISN list to be sorted may either be stored on the Adabas temporary working space or may be provided in the ISN buffer.
The resulting ISN list is returned to the ISN 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 | F/A |
| 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 4 | A | F/A |
| Command Time | B | -/A |
| User Area | F/U |
| Buffer | |
|---|---|
| Format Buffer | * |
| Record Buffer | * |
| Search Buffer | * |
| Value Buffer | * |
| ISN Buffer | F/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 * Not used but must be included in parameter list of CALL statement (1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.
- Command Code
S9
- Command ID
A non-blank, non-zero value may be specified in this field.
The high-order byte of this field must not be set to a hexadecimal 'FF' except when automatic command ID generation is used (see Programming Considerations, Using Command IDs for additional information).
- File Number
The number of the file from which the ISN list to be sorted was obtained.
- 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 S9 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.
This field is also used when a group of ISNs from a saved ISN list is being retrieved from the Adabas temporary working space. See Programming Considerations, ISN List Retrieval for additional information.
- ISN Quantity
As a result of an initial S9 call, Adabas returns the number of records which are contained in the resulting ISN list in this field.
As a result of a subsequent S9 call used to retrieve ISNs from the Adabas temporary working space, Adabas returns the number of ISNs returned in the ISN Buffer.
If the ISN list which is to be sorted is being provided in the ISN buffer, this field must contain the number of ISNs that are to be sorted - if you specify a value larger than the number of ISNs provided in the ISN buffer, it is reduced to the number of these ISNs.
- 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.
If the ISNs to be sorted are contained in the ISN buffer, this field must contain a value equal to or larger than the number of ISNs to be sorted multiplied by 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 ‘S’ in this field tells ADABAS that the ISN list is already sorted. The ‘S’ option includes the SAVE ISN LIST option. If you specify the ‘S’ option, but the ISN list is not sorted, you get a response code 24. The ‘S’ option is only allowed if the ISN list is provided in the ISN buffer - Additions 4 must be set to blanks.
- Command Option 2
This field may be used to invoke the descending sort option. A 'D' indicates that the ISN list is to be sorted in descending order. The descending option may not be specified when sorting by ISN values.
- 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.
- Additions 1
The value ISNbbbbb indicates that the ISN values are to be used as the sorting sequence.
This field may also contain the name(s) that is/are to be used to control the sort sequence.
From one to four names may be specified. These may be descriptors or non descriptor field names, but they must not be derived from a periodic group. Hyperdescriptors may be specified, but not in conjunction 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
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 4
If the ISN list to be sorted is contained on the Adabas temporary working space, the command ID under which the list is stored must be specified in the first 4 bytes of this field.
If the ISN list to be sorted is being provided in the ISN buffer, this field must be set to blanks.
The ISN list that is to be sorted may be provided by the user in this buffer. If the ISNs that are to be sorted are being provided in this buffer, it must be large enough to initially contain all ISNs to be sorted.
Adabas places the list of resulting ISNs in this buffer. Each ISN is returned as a four-byte binary number.
If the ISN buffer length is not zero, and the ISN buffer is not large enough to contain all the resulting ISNs, and a non-blank command ID was used, Adabas will store the overflow ISNs on the Adabas temporary working space. These ISNs may then be retrieved using further S9 calls in which the same command ID is used. See Programming Considerations, ISN List Processing for additional information.
An ISN list contained in the ISN buffer is to be sorted in ISN sequence. 622 ISNs are to be sorted.
Command Code S9
Command ID S901 (a non blank, non zero command ID is
required)
File Number 1 (the ISN list to be sorted is derived
from file 1)
ISN Quantity 622 (622 ISNs are to be sorted)
ISN Lower Limit 0 (all ISNs are to be selected)
ISN Buffer Length 2488 (or larger) (each ISN to be sorted
requires 4 bytes)
Command Option 1 H (the Save ISN List option is to be used)
Command Option 2 b (ascending sequence is to be used)
Additions 1 ISNbbbbb (the ISN values are to be used
as the sorting sequence)
Additions 3 bbbbbbbb (file is not security protected)
Additions 4 bbbbbbbb (the ISN list to be sorted is
contained in the ISN Buffer)
ISN Buffer The ISNs to be sorted are provided in
this buffer. Each ISN must be provided as
a four byte binary number.
An ISN list that is stored on the Adabas temporary working space is to be sorted. The command ID under which the ISN list is stored is U066. The list is to be sorted using the descriptors AA and AB as the major and minor sequence fields. The descending option is to be used.
Command Code S9
Command ID S902 (a non blank command ID is required)
File Number 1 (the ISN list was derived from file 1)
ISN Lower Limit 0 (All ISNs are to be selected)
ISN Buffer Length 0 (no ISNs are to be returned in the ISN
Buffer)
Command Option 1 H (the Save ISN List option is to be used)
Command Option 2 D (the descending option is to be used)
Additions 1 AAABbbbb (AA is to be used as the major
sequence field; AB is to be used as the
minor sequence field)
Additions 3 bbbbbbbb (file is not security protected)
Additions 4 U066bbbb (the ISN list to be sorted is
stored on the Adabas temporary working
space under the command ID U066)