The S9 command sorts an ISN list in ascending ISN or descriptor-specified sequence.
This document covers the following topics:
The S9 command sorts an ISN list provided by the user or created by a previous Sx command. The ISN list to be sorted may either be in the ISN buffer or on the Adabas Work dataset (if the command ID assigned to the list when it was created is specified in the additions 4 field).
The ISN list may be sorted in the order of
ISN values (ascending ISN sequence);
from one to three user-specified descriptors.
The user may specify from one to three 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 must contain ISNs in ascending sequence, which implies that the list was not created by an S2 or an S9 command that specified the descriptor sequence option.
The resulting ISN list is either returned in the ISN buffer, or optionally stored on the Adabas Work dataset.
The S9 command can also be performed on Adabas expanded files.
| 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 |
| 25-32 | -- | -- | -- | |
| 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 |
| 45-48 | -- | -- | -- | |
| ADDITIONS 3 | 49-56 | alphanumeric | F | A |
| ADDITIONS 4 | 57-64 | alphanumeric | F | A |
| 65-72 | -- | -- | -- | |
| COMMAND TIME | 73-76 | binary | -- | A |
| USER AREA | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| FORMAT BUFFER | * | -- |
| RECORD BUFFER | * | -- |
| SEARCH BUFFER | * | -- |
| VALUE BUFFER | * | -- |
| ISN BUFFER | F | A |
where:
| F | Filled in by user before Adabas Call |
| A | Filled in by Adabas |
| U | Unchanged after Adabas call |
| * | Not used but must be included in parameter list of call statement |
| -- | Not used |
S9
A non-blank, non-zero command ID may be specified in this field. This command ID applies only to the "I" (release command ID) or "H" (save-ISN-list) options; the command ID for obtaining an ISN list stored on Work must be specified in the additions 4 field.
The first byte of this field may not be set to a hexadecimal 'FF'.
The number of the file from which the ISN list to be sorted was obtained.
The S9 command 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 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 documentation.
Adabas returns the first ISN of the resulting ISN list in this field. If there are no resulting ISNs, this field is not modified. This applies to both the initial call and any subsequent calls that are used to retrieve ISNs from the Adabas Work dataset.
This field may be used in an initial Sx call to limit the resulting ISN list to those that are greater than the ISN specified in this field. If this field is set to zeros, Adabas returns all qualifying ISNs.
This field is also used when a group of overflow ISNs from a saved ISN list is being retrieved from the Adabas Work dataset.
If the ISN list to be sorted is being provided in the ISN buffer, this field must contain the number of ISNs that are to be sorted. If security-by-value is being used, a response code 1 is returned combined with the value 0 (one record found) or 1 (more than one record found) in this field. For more information, see the Adabas Security Manual.
For an initial S9 call, Adabas returns the number of records contained in the resulting ISN list. For any subsequent S9 call that retrieves ISNs from the Work dataset, Adabas returns the number of ISNs placed in the ISN buffer.
The ISN buffer length (in bytes) is used to determine the number of ISNs placed in the ISN buffer.
If this field is set to zeros, no ISNs are inserted in the ISN buffer. Set this field to zeros and specify "H" in the command option 1 field if the resulting ISN list is to be read with the GET NEXT option of the L1/L4 command. If the S9 command is being issued only to determine the number of qualifying records, specify zero in this field and no command ID to prevent a sorted ISN list from being returned or stored.
If a non-zero value is specified, it should be a multiple of 4. If it is not, Adabas reduces the length to the next lower integer that 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. ISN overflow is stored on Work, and can be retrieved by a later Sx command with a command ID matching that specified in the command ID field.
| Option | Description |
|---|---|
| H | (save-ISN-list) stores the entire ISN list resulting from an S9 command on the 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. If the resulting ISN list is to be read with the GET NEXT option of the L1/L4 command, use this option with the ISN buffer length field set to to zeros. If this option is specified, command option 2 cannot specify the "I" (release command ID) option. |
| Option | Description |
|---|---|
| D | (descending sequence) sorts the ISN list in descending sequence. This option may not be specified when sorting by ISN values. |
If no command option 2 is specified for an S9 command, the ISN list is 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 S9 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 "H" (save-ISN-list) option is specified as command option 1, this option cannot be specified as command option 2. |
The sort sequence to be used must be specified in this field.
The value "ISNbbbbb" indicates that the ISN values are to be used as the sorting sequence.
If the sort sequence is to be based on the values of one or more descriptors, the descriptors to be used must be specified in this field. One to three descriptors, subdescriptors, and/or superdescriptors may be specified. Phonetic descriptors and descriptors contained within a periodic group may not be specified. A multiple-value field may be specified, in which case the ISNs will be sorted according to the lowest value present within a given record. The descriptors are specified beginning with byte 1 (left justified). Any remaining positions must be set to blanks.
The number of ISNs that can be sorted depends on the size of the ADARUN parameters defined by the DBA. If this limit is exceeded, no sort is performed and response code 1 is returned.
This field is used to provide an Adabas security or ADAESI password. If the database, file, or fields are security-protected, the user must provide a valid security or ADAESI password. Adabas sets the additions 3 field to blanks during command processing to enhance password integrity.
If the ISN list to be sorted is contained on the Adabas Work dataset, 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 in the ISN buffer, this field must be set to blanks.
Adabas sets the additions 4 field to blanks during command processing, and returns a version code and database ID in the rightmost (low-order) three bytes of this field. For more information, see the section Control Block Fields.
The ISN list to be sorted may be provided by the user in this buffer.
Adabas places the list of resulting ISNs in this buffer. Each ISN is returned as a four-byte binary number. If the ISN sort option is in effect ("ISN" is entered in the additions 1 field), the ISNs are returned in ascending ISN sequence. Otherwise, the ISNs are returned in the order of the values of the user-specified descriptor(s).
If the ISN buffer length is neither zero nor large enough to contain all the resulting ISNs and a valid command ID was specified, Adabas stores the overflow ISNs on the Adabas Work. These ISNs may then be retrieved using further S9 calls in which the same command ID is specified in the additions 4 field. For more information refer to the section ISN List Processing.
Sort an ISN list contained in the ISN buffer in ISN sequence. Sort 622 ISNs.
| Command Code | S9 | |
|---|---|---|
| Command ID | S901 | a non-blank, non-zero command ID is required |
| File Number | 1 | derive the ISN list to be sorted from file 1 |
| ISN Quantity | 622 | sort 622 ISNs |
| ISN Lower Limit | 0 | select all ISNs |
| ISN Buffer Length | 2488 | or larger; each ISN to be sorted requires 4 bytes |
| Command Option 1 | H | use the save-ISN-list option |
| Command Option 2 | b | use ascending sequence |
| Additions 1 | ISNbbbbb | use the ISN values as the sorting sequence |
| Additions 3 | bbbbbbbb | file 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 4-byte binary number. |
|---|
Sort an ISN list stored on the Adabas Work. The command ID under which the ISN list is stored is "U066". Sort the list using the descriptors AA and AB as the major and minor sequence fields. Use the descending option.
| Command Code | S9 | |
|---|---|---|
| Command ID | S902 | a non-blank, non-zero command ID is required |
| File Number | 1 | derive the ISN list to be sorted from file 1 |
| ISN Lower Limit | 0 | select all ISNs |
| ISN Buffer Length | 0 | no ISNs are to be returned in the ISN buffer |
| Command Option 1 | H | use the save-ISN-list option |
| Command Option 2 | D | use the descending sequence |
| Additions 1 | AAABbbbb | use AA as the major sequence field and AB as the minor sequence field |
| Additions 3 | bbbbbbbb | file not security-protected |
| Additions 4 | U066bbbb | the ISN list to be sorted is stored on the Adabas Work under the command ID "U066" |
