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 data set (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 order of:
ISN value (ascending ISN sequence);
one to three user-specified descriptors.
You can 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 data set.
The S9 command can also be performed on Adabas expanded files.
This section describes ACB interface direct calls for the S9 command. 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 |
| 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 | * | -- |
| Record | * | -- |
| Search | * | -- |
| Value | * | -- |
| ISN | F | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Not used but must be included in parameter list of call statement |
| -- | Not used |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
- Command Code (ACBCMD)
S9
- Command ID (ACBCID)
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'.
- File Number (ACBFNR)
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.- Response Code (ACBRSP)
Adabas returns the response code for the command in this field. Response code 0 (ADARSP000) 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 Manual documentation.
- ISN (ACBISN)
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 data set.
- ISN Lower Limit (ACBISL)
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 data set.
- ISN Quantity (ACBISQ)
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 (ADARSP001) 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 data set, Adabas returns the number of ISNs placed in the ISN buffer.
- ISN Buffer Length (ACBIBL)
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 or 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.
- Command Option 1: Save ISN List Option (ACBCOP1)
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 or L4 command, use this option with the ISN buffer length field set to zeros. If this option is specified, Command Option 2 cannot specify the "I" (release command ID) option. - Command Option 2: Descending Option (ACBCOP2)
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.
- Command Option 1 or 2: Release Command ID Option (ACBCOP1 or ACBCOP2)
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. - Additions 1: Sort Sequence (ACBADD1)
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 (where bbbbb represents blanks).
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, 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 (ADARSP001) is returned.
- Additions 3: Password (ACBADD3)
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.
- Additions 4: Command ID (ACBADD4)
If the ISN list to be sorted is contained on the Adabas Work data set, 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.
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 (blank) | use ascending sequence |
| Additions 1 | ISNbbbbb | use the ISN values as the sorting sequence, where bbbbb represents blanks. |
| Additions 3 | bbbbbbbb (blanks) | file not security-protected |
| Additions 4 | bbbbbbbb (blanks) | 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, where bbbb represents blanks. |
| Additions 3 | bbbbbbbb (blanks) | file not security-protected |
| Additions 4 | U066bbbb | the ISN list to be sorted is stored on the Adabas Work under the command ID "U066", where bbbb represents blanks. |
This section describes ACBX interface direct calls for the S9 command. 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 |
| 65-68 | --- | --- | --- | |
| Additions 3 | 69-76 | alphanumeric/ binary | F | A |
| Additions 4 | 77-84 | alphanumeric | F | A |
| 85-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 |
|---|---|---|
| ISN | F | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| --- | Not used |
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
- Version Indicator (ACBXVER)
F2
- Command Code (ACBXCMD)
S9
- Response Code (ACBXRSP)
Adabas returns the response code for the command in this field. Response code 0 (ADARSP000) 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.
- Command ID (ACBXCID)
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'.
- Database ID (ACBXDBID)
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.
- File Number (ACBXFNR)
Use this field to specify the number of the file from which the ISN list to be sorted is obtained.
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.
The S9 command can also be performed on Adabas expanded files.
- ISN (ACBXISN)
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 data set.
- ISN Lower Limit (ACBXISL)
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.
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 overflow ISNs from a saved ISN list is being retrieved from the Adabas Work data set.
- ISN Quantity (ACBXISQ)
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 (ADARSP001) 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.
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.
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 data set, Adabas returns the number of ISNs placed in the ISN buffer.
- Command Option 1: Save ISN List Option (ACBXCOP1)
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 or L4 command, use this option with the ISN buffer length field set to zeros. If this option is specified, Command Option 2 cannot specify the "I" (release command ID) option. - Command Option 2: Descending Option (ACBXCOP2)
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.
- Command Option 1 or 2: Release Command ID Option (ACBXCOP1 and ACBXCOP2)
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. - Additions 1: Sort Sequence (ACBXADD1)
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, where bbbbb represents blanks.
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, 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 (ADARSP001) is returned.
- Additions 3: Password (ACBXADD3)
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.
- Additions 4: Command ID (ACBXADD4)
If the ISN list to be sorted is contained on the Adabas Work data set, 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.
- Error Subcode (ACBXERRC)
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 S9 command:
If this is an ACB interface direct call and a format buffer is not specified, a processing error will occur; ACB interface direct calls expect buffers to be specified in a set sequence. If this is an ACBX interface direct call, a format buffer is not needed.
If this is an ACB interface direct call and a record buffer is not specified, a processing error will occur; ACB interface direct calls expect buffers to be specified in a set sequence. If this is an ACBX interface direct call, a record buffer is not needed.
If this is an ACB interface direct call and a search buffer is not specified, a processing error will occur; ACB interface direct calls expect buffers to be specified in a set sequence. If this is an ACBX interface direct call, a search buffer is not needed.
If this is an ACB interface direct call and a value buffer is not specified, a processing error will occur; ACB interface direct calls expect buffers to be specified in a set sequence. If this is an ACBX interface direct call, a value buffer is not needed.
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 ("ISNbbbbb" 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 descriptors.
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 data set. 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.