The S2 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.
| 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 BUFFER | * | -- |
| RECORD BUFFER | * | -- |
| SEARCH BUFFER | * | -- |
| VALUE BUFFER | * | -- |
| ISN BUFFER | -- | A |
where:
| F | Filled in by user before Adabas Call |
| A | Filled in by Adabas |
| U | Unchanged after Adabas call |
| * | Not used but must be included in parameter list of call statement |
| -- | Not used |
S5
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'.
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.
Adabas returns the response code for the command in this field. Response code 0 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 documentation.
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.
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.
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.
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/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.
| 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. |
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. |
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.
This field is used to provide an Adabas security or ADAESI password. If the database, file, or fields are security-protected, the user must provide a valid security or ADAESI password. Adabas sets the additions 3 field to blanks during command processing to enhance password integrity.
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.
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 |
