Version 7.4.4	SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

The S1 / S2 / S4 commands return a count of records and ISNs of records satisfying the search criterion.

This document covers the following topics:

• Function and Use

• Command: S1 / S2 / S4

• Control Block

• Buffers

• Examples

Function and Use

The S1/S2/S4 commands are used to select records that satisfy a given search criterion. They can be performed on Adabas expanded files as well.

The result of an S1/S2/S4 command is the number of records which satisfy the query and a list of the records' ISNs. The S1/S4 commands return the ISNs, sorted in ascending sequence, in the ISN buffer; the S2 command returns the ISNs according to a sort sequence specified in the additions 1 field.

Note:
ISN lists that are not in ascending sequence cannot be processed by a later S8 command.

The following types of searches are possible:

• Single file search. The search criterion consists of one or more fields contained in a single file.

• Multiple file search using physically coupled files. The search criterion consists of fields contained in two or more files that have been physically coupled using the ADAINV utility.

• Search using the soft coupling feature. This feature provides for a combination of search, read, and internal list matching.

A search criterion may contain one or more fields that are not defined as descriptors. If nondescriptors are used, Adabas performs read operations to determine which records to return to the user. If only descriptors are used within the search criterion, Adabas resolves the query by using the Associator inverted lists; no read operation is required.

If a valid command ID is specified, Adabas will store on Adabas Work any ISNs that could not be inserted in the ISN buffer on the initial S1/S2/S4 command. These overflow ISNs may be retrieved to the ISN buffer later with additional S1/S2/S4 commands that specify the same command ID.

Adabas releases an overflow ISN list when the last ISN in the list has been returned to the user. If the user needs to retain the entire ISN list indefinitely, the save-ISN-list option may be used. If this option is specified, the entire ISN list is stored on Adabas Work. The ISN list is not released until either an RC, CL, or Sx command with the release CID option is issued, or the Adabas session is terminated.

If the user intends to use the GET NEXT option of an L1 or L4 command to read the records identified by the ISNs, neither the ISN buffer entry nor the save-ISN-list option is required. In this case, the L1/L4 commands obtain the ISNs automatically from the ISN list stored by Adabas.

By placing field names in the format buffer, the user can read the field's contents from the record of the first ISN in the resulting ISN list. The field's contents are read into the record buffer. The S4 command also places the first ISN of the resulting ISN list in hold status.

Command: S1 / S2 / S4

User Control Block

User Buffer Areas

where:

Control Block

Command Code

S1/S2/S4

Command ID

This value identifies the resulting complete or overflow ISN list stored on Adabas Work, and identifies the format buffer for subsequent commands if the read-first-record option is in effect (see the section Format Buffer).

If the save-ISN-list option is to be used, or if overflow ISNs are to be stored, a non-blank, non-zero value must be provided in this field.

The first byte of this field may not be set to hexadecimal 'FF'.

See the section ISN List Processing for more information.

File Number

File number specifies the number of the file from which the ISNs are to be selected.

If a query using coupled files is to be performed, the file specified in this field will be considered the "primary" file. The file number of physically coupled files must be no greater than 255.

The search can also be performed on Adabas expanded files.

Note:
When using two-byte file numbers and database IDs, a X'30' must be coded in the first byte of the control block.

Response Code

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

ISN

Adabas returns the first ISN of the resulting ISN list in this field. If there were no resulting ISNs, this field is set to zeros.

ISN Lower Limit

Use this field in the first S1 or S4 call to specify a minimum ISN value for the resulting ISN list. The list will then contain only the ISNs greater than the ISN specified in this field. If this field is set to zeros, Adabas will return all qualifying ISNs.

Note:
Note this will not work for an S2 call. For sorted ISN lists (S2 commands), this field must be set either to zero or to a valid ISN.

This field is also used when a group of ISNs from a saved ISN list is being retrieved from Adabas Work.

ISN Quantity

This field defines the maximum number of seconds that can be used for Sx command execution.

As a result of an initial Sx call, Adabas returns the number of records that satisfy the search criterion in this field. If security-by-value is being used, response code 1 is returned in this field along with the value 0 (one record found) or 1 (more than one record found). For more information, see the Adabas Security Manual.

As a result of a subsequent Sx call used to retrieve ISNs from Adabas Work, Adabas provides the number of returned ISNs in this field. The ISNs themselves are returned in the ISN buffer.

Format Buffer Length

The format buffer length (in bytes). The format buffer area defined in the user program must be as large as (or larger than) the length specified.

Record Buffer Length

The record buffer length (in bytes). The record buffer area defined in the user program must be as large as (or larger than) the length specified.

Search Buffer Length

The search buffer length (in bytes). The search buffer area defined in the user program must be as large as (or larger than) the length specified.

Value Buffer Length

The value buffer length (in bytes). The value buffer area defined in the user program must be as large as (or larger than) the length specified.

ISN Buffer Length

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. This 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 will reduce the length to the next lower integer which is a multiple of 4.

Command Option 1

Option	Description
H	(save ISN list) stores the entire ISN list resulting from an Sx command on 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.
R	(return) for an S4 command, returns response code 145 if a record to be read and held is not available.

Command Option 2

Option	Description
D	(descending sequence) for an S2 command, sorts descriptor values in descending sequence.

If no command option 2 is specified for an S2 command, the descriptor values are sorted in ascending sequence.

Command Option 1/2: Release CID Option

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 as the first action taken during command 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: S2 Command, Descriptors Used for Sort Control

If the S2 command is being used, this field must specify the descriptor (or descriptors) to be used to control the sort sequence; if no sort argument is specified, the S2 command returns response code 28.

One to three descriptors, including subdescriptors and superdescriptors, can be specified. Phonetic descriptors or descriptors contained within a periodic group cannot be specified. A multiple-value field can be specified, in which case the ISNs will be sorted according to the lowest value present within a given record.

Any unused positions of this field must be set to blanks.

Example

XXYYbbbb

where:

XX	is the major sort descriptor; and
YY	is the minor sort descriptor

The number of ISNs that can be sorted depends on the size of the sort work area (ADARUN LS parameter) defined by the DBA. If the sort area is too small, no sort will be performed; response code 1 will be returned, and the ISNs will be returned in ascending sequence.

Additions 2: Length of Compressed and Decompressed Record

If the command is processed successfully, the following information is returned in this field:

• If the record buffer contains at least one valid field value, the leftmost two bytes contain the length (in binary form) of the compressed record accessed;

• The rightmost two bytes contain the length (in binary form) of the decompressed fields selected by the format buffer and accessed.

If the Sx command returns a non-zero response code, the rightmost two bytes may contain a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes documentation.

Additions 3: Password

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.

Additions 4: Cipher Code and Version/Nucleus ID

This field is used to provide a cipher code. If the file is ciphered, the user must provide a valid cipher code. If the file is not ciphered, this field should be set to blanks.

Adabas sets any cipher code to blanks during command processing, and returns a version code and the database ID in the rightmost (low-order) three bytes of this field. For more information, see the section Control Block Fields.

Additions 5: Format ID, Global Format ID

This field may be used to provide a separate format ID to identify the internal format buffer to be used for this command, or to provide a global format ID.

If the high-order bit of the additions 5 field is zero (0), the value provided in the command ID field is also used as the format ID.

If the leftmost (high-order) additions 5 field bit is one (1), the fifth through last bytes of the additions 5 field are used as the format ID.

If the two high-order (leftmost) bits of the first byte of additions 5 field are set to one (B'11'), the value in all eight bytes of the additions 5 field (additions 5 + 0(8)) is used as a global format ID (that is, the format ID can be used by several users at the same time).

For more information, refer to the section Command ID, Format ID, Global Format ID.

Buffers

Format Buffer

If the record identified by the first ISN in the resulting ISN list is to be read from Data Storage, the fields within the record for which values are to be returned must be specified in this buffer. The syntax and examples of format buffer construction are provided in the section Adabas Calling Procedure. User-specified fields for controlling the S2 command's ISN sort sequence must be specified in the additions 1 field.

If no read is to be performed, the first non-blank character of this buffer must be a period (.).

If a valid command ID is specified, Adabas retains this decoded format buffer for use by later commands specifying the same command ID.

Record Buffer

If the format buffer contains field definitions to enable the read option, Adabas returns the requested field values in this buffer.

The values are returned according to the standard length and format of the field, unless the user specifies a different length and/or format in the format buffer.

Search and Value Buffers

Search and value buffers are used to define the search criteria. The search expression (or expressions) is provided in the search buffer, and the values which correspond to the search expressions are provided in the value buffer.

The syntax and examples of search and value buffer construction are described in the Adabas Calling Procedure.

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 ascending ISN sequence unless the S2 command is being used, in which case they are returned in the user-specified sort sequence.

If the query contains one or more file-coupling criteria, the resulting ISN list contains only those ISNs in the primary file (the file specified in the control block's file number field).

If the ISN buffer length field is set to less than 4, no ISNs are returned in the ISN buffer. If a valid command ID is specified, the ISN buffer length is not zero, but the ISN buffer is still too small to contain all the resulting ISNs, Adabas will store the overflow ISNs on Adabas Work. These ISNs may then be retrieved using further S1/S2/S4 calls in which the same command ID is used.

See the section ISN List Processing for additional information.

Examples

For the Adabas file definitions used in all the examples in this section, see File Definitions Used in Examples.

Example 1

Select the records in file 1 that contain a value in the range "A" to "J" for the descriptor AA.

Control Block

Buffer Areas

Example 2

Find with read option. Select the ISN of the record containing the value "ABCDEFGH" for the field AA in file 1. Also, read the record from Data Storage and return the value for the field AC.

Control Block

Buffer Areas

Example 3

Find with ISN buffer overflow. Select the records that contain any value in the range "A" to "D" for field AA in file 1. Use ISN buffer overflow handling.

Control Block

Buffer Areas

Adabas will return, as a result of the initial S1 call, a maximum of 25 ISNs in the ISN buffer. If more than 25 ISNs resulted from the query, the remaining ISNs will be stored on Adabas Work under the command ID "ABCD". These overflow ISNs may be retrieved by repeating the S1 call using the same command ID.

Example 4

Find with save-ISN-list option. Select all the records containing the value "+80" for the field XB in file 2. Store the entire resulting ISN list on the Adabas Work.

Control Block

Buffer Areas

The user may retrieve any group of ISNs from the ISN list that is stored as a result of this call by repeating the S1 command using the command ID "BCDE". Adabas will insert as many ISNs as can be accommodated in the ISN buffer starting with the first ISN that is greater than the ISN specified in the ISN lower limit field.

Example 5

Find with sort. Select all records containing a value in the range "A" to "F" for the field AA in file 1. Return the resulting ISN list in ascending order of the values for field AB.

Control Block

Buffer Areas

Example 6

Find with hold. Select the record in file 1 containing the value "87654321" for field AA. Also, read the record and place it in hold status. Return the values for fields AB and AC.

Control Block

Buffer Areas

Example 7

Find using coupled files. Select the records in file 1 containing the value "+100" for the field AB that are coupled to records in file 2 containing the value 'ABCDE' for the field RB.

Control Block

Buffer Areas

Because file 1 was specified as the primary file, the resulting ISNs will be from file 1. If ISNs from file 2 are also desired, the find may be repeated with file number 2 specified in the file number field. The order of the search criteria in the search buffer need not be changed.

Example 8

Find using multiple search criteria (complex search). Select the set of records in file 2 containing a value of "ABCD" for subdescriptor SA, a value less than "80" for field XB, and a value in the range "MMMMM" through "ZZZZZ" (but not "Sbbbb" through "TZZZZ") for field XE.

Control Block

Buffer Areas

www.softwareag.com

Copyright © Software AG 1971-2009. All rights reserved.

SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT