S8 Command: Process ISN Lists

#### Search Results

Search

# S8 Command: Process ISN Lists

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:

- Function and Use

- ACB Interface Direct Call: S8 Command

- ACBX Interface Direct Call: S8 Command

- Buffers

## Function and Use

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.

## ACB Interface Direct Call: S8 Command

This section describes ACB interface direct calls for the S8 command. It covers the following topics:

- Control Block and Buffer Information

- Control Block Field Descriptions

- ACB Example

### Control Block and Buffer Information

#### Control Block

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 Areas

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

### Control Block Field Descriptions

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.

### ACB Example

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.

#### Control Block

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

## ACBX Interface Direct Call: S8 Command

This section describes ACBX interface direct calls for the S8 command. It covers the following topics:

- Control Block and Buffer Information

- Control Block Field Descriptions

### Control Block and Buffer Information

#### Control Block

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 | --- | ---

#### ABDs and Buffers

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

### Control Block Field Descriptions

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.

## Buffers

The following buffers apply to the S8 command:

- Format Buffer

- Record Buffer

- Search Buffer

- Value Buffer

- ISN Buffer

### Format Buffer

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.

### Record Buffer

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.

### Search Buffer

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.

### Value Buffer

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.

### ISN Buffer

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.

### On this page

- Function and Use
- ACB Interface Direct Call: S8 Command
- ACBX Interface Direct Call: S8 Command
- Buffers