The S5 command returns or saves a list of coupled ISNs for the specified file.
This document covers the following topics:
The S5 command is used to determine the records in one file that are coupled to a given record in another file.
The user specifies the file number and a given ISN within the file, plus the file number from which the coupled ISNs are to be returned. An optional ISN value above which ISNs are to be returned can also be specified.
Adabas determines which records are coupled to the specified record by using the Associator coupling lists. No access to Data Storage is required.
Adabas returns the resulting ISNs in the ISN buffer.
This section describes ACB interface direct calls for the S5 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 | F | 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 |
| -- | Not used |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
- Command Code (ACBCMD)
S5
- Command ID (ACBCID)
A non-blank, non-zero value can be specified in this field if the Save ISN List option is to be used, or if overflow ISNs are to be stored on and then later read from the Adabas Work.
The first byte of this field may not be set to hexadecimal 'FF'.
- File Number (ACBFNR)
The number of the file from which the coupled ISNs are to be selected. This file, called the primary file, must be coupled to the file specified in the Additions 1 field, and cannot be an Adabas expanded file. The file number of physically coupled files must be no greater than 255.
- 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. Nonzero 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)
The ISN of the record for which the coupled ISNs are to be returned. The ISN must be present in the file specified in the Additions 1 field. Adabas will return the first ISN of the resulting coupled ISN list in this field.
- ISN Lower Limit (ACBISL)
This field may be used in an initial Sx call to limit the resulting ISN list to those ISNs which 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.
- ISN Quantity (ACBISQ)
An initial S5 call returns the number of records in the specified file that satisfy the search criteria.
In subsequent Sx calls used to retrieve ISNs from the Adabas Work, this field contains the number of ISNs placed 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 will be inserted in the ISN buffer.
To save the ISN list on Work for later processing, specify "H" in the Command Option 1 field and a valid command ID. The ISN buffer length 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 (ACBCOP1)
Option Description H (save ISN list) Stores the entire ISN list resulting from an S5 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. - 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. This is the first action taken during S5 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. - Additions 1: File Number (ACBADD1)
The number of the file which contains the ISN specified in the ISN field. The file number must be entered in the first two bytes of this field. The number must be provided in binary format. The remaining positions of this field must be set to blanks. This field must not be changed between successive S5 calls.
- 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.
Select the records in file 2 that are coupled to the record in file 1 identified with ISN 5. Use the save-ISN-list option.
| Command Code | S5 | |
|---|---|---|
| Command ID | S501 | a non-blank command ID is required if the save-ISN-list option is to be used |
| File Number | 2 | records to be selected from file 2 |
| ISN | 5 | ISN 5 identifies the record for which the coupled records are to be selected |
| ISN Lower Limit | 0 | all qualifying ISNs are to be selected |
| ISN Buffer Length | 0 | no ISNs are to be returned in the ISN buffer |
| Command Option 1 | H | save-ISN-list option to be used |
| Additions 1 | X'0001404040404040' | the record for which the coupled records are to be selected is contained in file 1 |
| Additions 3 | password | file is security-protected |
This section describes ACBX interface direct calls for the S5 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 | F | 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)
S5
- 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 value can be specified in this field if the Save ISN List option is to be used, or if overflow ISNs are to be stored on and then later read from the Adabas Work.
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 DDDDCARD 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 coupled ISNs are to be selected. This file, called the primary file, must be coupled to the file specified in the Additions 1 field, and cannot be an Adabas expanded file. The file number of physically coupled files must be no greater than 255.
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)
The ISN of the record for which the coupled ISNs are to be returned. The ISN must be present in the file specified in the Additions 1 field. Adabas will return the first ISN of the resulting coupled ISN list in this field.
The ACBXISN field is a four-byte binary field embedded in the eight-byte ACBXISNG field, which is not yet used. Set the high-order part of the ACBXISNG field to binary zeros.
- ISN Lower Limit (ACBXISL)
This field may be used in an initial Sx call to limit the resulting ISN list to those ISNs which 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.
- ISN Quantity (ACBXISQ)
An initial S5 call returns the number of records in the specified file that satisfy the search criteria.
In subsequent Sx calls used to retrieve ISNs from the Adabas Work, this field contains 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 S5 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. - Command Option 1 or 2: Release Command ID Option (ACBXCOP1 or 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. This is the first action taken during S5 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. - Additions 1: File Number (ACBXADD1)
The number of the file which contains the ISN specified in the ISN field. The file number must be entered in the first two bytes of this field. The number must be provided in binary format. The remaining positions of this field must be set to blanks. This field must not be changed between successive S5 calls.
- 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 S5 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 the ISN buffer. Each ISN is returned as a four-byte binary number. The first ISN in the list is also returned in the control block's ISN field.
The ISNs are returned in ascending ISN sequence.
If the ISN buffer length is neither zero nor large enough to contain all the resulting ISNs, and a valid command ID was used, Adabas will store the overflow ISNs on the Adabas Work. These ISNs may then be retrieved using additional S5 calls that specify the same command ID. See the section ISN List Processing for additional information.