The S8 command combines two ISN lists from the same file with an AND, OR, or NOT operation. For more information refer to the section ISN List Processing.
This document covers the following topics:
The S8 command performs logical processing on two ISN lists that were previously created with Sx commands. Both ISN lists must be
derived from the same file;
in ISN sequence;
stored on the Work data set; and
identified by command IDs assigned to the lists when they were created.
ISN lists resulting from an S2 or S9 command that are not in ascending ISN sequence cannot be used.
No activity (access or update) may be performed on the ISN lists to be processed between the time they are created and the time the S8 command is executed.
The S8 command may be used to perform the following logical operations:
| Operator | The resulting ISN list contains those ISNS that are present in . . . |
|---|---|
| AND | both ISN lists |
| OR | either of the ISN lists |
| NOT | the first ISN list but not the second ISN list |
The resulting ISNs are returned in the ISN buffer and/or stored on the Work data set in ascending ISN sequence, depending on the specified Command Option and the command ID field setting:
The resulting ISN list is saved in both the ISN buffer and on the Work data set when a non-blank, non-zero command ID is specified and the save-ISN-list option is also specified.
The resulting ISN list is saved in the ISN buffer but not on the Work data set when no (or an invalid) command ID is specified with the save-ISN-list option.
This section describes ACB interface direct calls for the S8 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 | -- | 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 |
| 57-72 | -- | -- | -- | |
| Command Time | 73-76 | binary | -- | A |
| User Area | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| Format | * | -- |
| Record | * | -- |
| Search | * | -- |
| Value | * | -- |
| ISN | -- | 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 |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
- Command Code (ACBCMD)
S8
- Command ID (ACBCID)
A nonblank, nonzero command ID must be specified in this field if a command option is specified in Command Option 1 field:
The i (release command ID) option releases the specified command ID and any related ISN list as the first action taken during the S8 execution.
With the H (save-ISN-list) option, the ISN list resulting from the S8 execution is stored under the specified command ID. 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.
For more information refer to the section ISN List Processing.
The first byte of this field may not be set to hexadecimal 'FF'.
- File Number (ACBFNR)
The number of the file from which both ISN lists to be processed were obtained.
- Response Code (ACBRSP)
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 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 were 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 ISNs 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 ISNs from a saved ISN list is being retrieved from the Adabas Work data set.
- ISN Quantity (ACBISQ)
As a result of an initial S8 call, this field returns the number of ISNs in the resulting ISN list.
As a result of a subsequent S8 call to retrieve ISNs from the Adabas Work data set, this field contains the number of ISNs returned in the ISN buffer.
- ISN Buffer Length (ACBIBL)
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 are 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 reduces the length to the next lower integer which is a multiple of 4.
- Command Option 1: Save ISN List Option, Release Command ID Option (ACBCOP1)
Option Description H (save ISN list) Stores the entire ISN list resulting from an S8 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. I Releases the command ID (CID) value specified in the command ID field and any related ISN list as the first action taken during the S8 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. - Command Option 2: Logical Operator (ACBCOP2)
The value entered in this field indicates the logical operation to be performed on the ISN lists:
Option Operation The resulting ISN list contains those ISNs that are present in ... D AND both ISN lists. O OR either ISN list. N NOT the first ISN list but not the second ISN list. - Additions 1: Command IDs (ACBADD1)
The command IDs that identify the ISN lists to be processed must be specified in this field (four bytes per command ID). Each ISN list must be currently stored on the Adabas Work data set and should contain ISNs from the same file.
- 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.
Perform a logical OR operation between two ISN lists to produce a third ISN list that contains ISNs present in either list. The ISN lists to be processed were stored on the Adabas Work data set under the command IDs "U020" and "U021". Store the resulting ISN list on the Adabas Work under the command ID "U999". Use the save-ISN-list option.
| Command Code | S8 | |
|---|---|---|
| Command ID | U999 | store the resulting ISN list under the command ID U999 |
| ISN Lower Limit | 0 | select all of the resulting 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 | O | perform an OR operation |
| Additions 1 | U020U021 | process the ISN lists identified by the command IDs U020 and U021 |
| Additions 3 | bbbbbbbb (blanks) | file not security-protected |
This section describes ACBX interface direct calls for the S8 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 | --- | 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 |
| 77-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 | --- | 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)
S8
- 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 nonblank, nonzero command ID must be specified in this field if a command option is specified in Command Option 1 field:
The "I" (release command ID) option releases the specified command ID and any related ISN list as the first action taken during the S8 execution.
With the "H" (save-ISN-list) option, the ISN list resulting from the S8 execution is stored under the specified command ID. 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.
For more information refer to the section ISN List Processing.
The first byte of this field may not be set to 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 both ISN lists to be processed were 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.
- ISN (ACBXISN)
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 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 ISNs 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 ISNs from a saved ISN list is being retrieved from the Adabas Work data set.
- ISN Quantity (ACBXISQ)
As a result of an initial S8 call, this field returns the number of ISNs in the resulting ISN list.
As a result of a subsequent S8 call to retrieve ISNs from the Adabas Work data set, this field contains the number of ISNs returned in the ISN buffer.
- Command Option 1: Save ISN List Option, Release Command ID Option (ACBXCOP1)
Option Description H (save ISN list) Stores the entire ISN list resulting from an S8 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. I Releases the command ID (CID) value specified in the command ID field and any related ISN list as the first action taken during the S8 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. - Command Option 2: Logical Operator (ACBXCOP2)
The value entered in this field indicates the logical operation to be performed on the ISN lists:
Option Operation The resulting ISN list contains those ISNs that are present in ... D AND both ISN lists. O OR either ISN list. N NOT the first ISN list but not the second ISN list. - Additions 1: Command IDs (ACBXADD1)
The command IDs that identify the ISN lists to be processed must be specified in this field (four bytes per command ID). Each ISN list must be currently stored on the Adabas Work data set and should contain ISNs from the same file.
- 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.
- 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 S8 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.
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 ISN sequence.
If the ISN buffer is too small to contain all the resulting ISNs and a non-blank, non-zero command ID was used, Adabas stores the overflow ISNs on the Work data set. These ISNs can be retrieved with further Sx calls using the same command ID. For more information refer to the section ISN List Processing.