Version 8.1.4
 —  Command Reference  —

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

The S8 command performs logical processing on two ISN lists that were previously created with Sx commands. Both ISN lists must be

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:

Top of page

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

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:

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

Top of page

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

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

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.

Top of page

Buffers

The following buffers apply to the S8 command:

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.

Top of page