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

The L3/L6 command is used to read afile in logical sequential order based on the sequence of the values for a given descriptor.

This document covers the following topics:

• Function and Use

• Command: L3 / L6

• Control Block

• Buffers

• Additional Considerations

• Examples

Function and Use

The user specifies the

• file to be read;

• search descriptor, whose values are to control the read sequence (phonetic descriptors and descriptors contained within or derived from a field within a periodic group may not be used);

• field or fields within each record for which values are to be returned.

Each L3/L6 command returns the requested values for one record's field or fields in the record buffer. Repeating the command returns the values of each field in order of the search descriptor values.

The ascending and descending options specify whether the records are read in ascending or descending order. The ascending, descending, and value start options may be used to position to a given value before sequential reading begins or to position to a given value during sequential reading. This allows the user to position to a specific record in the file without having to read each record.

The multifetch/prefetch option allows prior accessing of one or more sequential records, reducing overall operating time and eliminating the time needed for single-record fetches. Multi-/prefetching can be enabled by specifying "M", "O" (for multifetching) or "P" (for prefetching) in the command option 1 field. Refer to the section Using the Multifetch/Prefetch Feature for more information.

If the format buffer contains "C.", the field values for each record read are returned in compressed format; otherwise, in uncompressed format.

Processing for the L3 command uses an internal table (the table of sequential commands) to keep track of the most recently returned value and ISN. "Normal" and "expanded" files are operationally diverse and for performance reasons, the value and ISN for each are handled differently in the table.

Specifically, the entries for "normal" files keep the value and ISN that was returned on the last call. The entries for "expanded" files keep the value and ISN that must be returned to the application on the next call.

This means that for "normal" files where concurrent updates are taking place, the L3 command returns a newly inserted value/ISN combination as long as it is greater than or equal to the last value/ISN returned.

For "expanded" files where concurrent updates are taking place, the L3 command returns a newly inserted value/ISN combination as long as it is greater than or equal to the value/ISN that is kept in the table of sequential commands entry as the next value/ISN to be returned.

The L6 command performs the same function as the L3 command and, in addition, places each record read in hold status. If a record to be read and held is currently being held by another user, the read operation stops and the user is placed in wait status until the record becomes available or an operation timeout occurs. If the command option 1 field is set to either "O" or "R" and a requested record is already being held, the L6 command returns response code 145.

Repositioning to a Particular Value

See the section ISN: Optional Start ISN/Record Read ISN in section L3 / L6 Control Block for information about specifying a starting value for the sequence-controlling descriptor. The following procedure is used to reposition to a particular value during a sequential pass:

1. Set the last six positions of the additions 1 field (the descriptor controlling the read sequence) to blanks.

2. Insert in the value buffer the value to which the read sequence is to reposition.

3. Set the ISN field to zero.

4. Set the command option 2 field to "A", "D", or "V".

Changing the Direction of the Read

Within a logical read sequence, the direction of the read can be changed at any time from ascending to descending or back without repositioning by specifying "D" or "A" for command option 2.

This option is not supported with prefetch or multifetch.

Command: L3 / L6

User Control Block

User Buffer Areas

where:

Control Block

Command Code

L3/L6

Command ID

This field must be set to a non-blank, non-zero value. The value provided is used by Adabas to provide the records in the correct sequence and to avoid repetitive interpretation of the format buffer.

The first byte of this field may not be set to hexadecimal 'FF', and must not be changed during a given sequential pass of a file.

If the command ID value is X'FFFFFFFF', the command ID is automatically generated. The Adabas nucleus generates command ID values beginning with X'00000001', and increments the value by 1 for each L3/L6 call.

When specifying user-defined command IDs, the user must ensure that each command ID is unique.

See also the additions 5 field for separate format ID and/or global format ID usage.

File Number

Specify the binary number of the file to be read in this field. For the physical direct calls, specify the file number as follows:

• For a one-byte file number, enter the file number in the rightmost byte (10); the leftmost byte (9), should be set to binary zero (B'0000 0000').

• For a two-byte file number, use both bytes (9 and 10) of the field.

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.

Response code 3 indicates that an end-of-file condition has been detected.

ISN: Optional Start ISN/Record Read ISN

For initial or subsequent positioning to a specific location in the logical read sequence when the last six bytes of the additions 1 field are set to blanks, the ISN field is used together with the starting descriptor value specified in the value buffer to determine the position where reading starts or restarts.

If an existing read sequence is to be continued without repositioning when the last six bytes of the additions 1 field are not changed from the most recent read command of the sequence, the ISN field is ignored.

Adabas returns in the ISN field the ISN of the record that was read.

When positioning or repositioning in the logical read sequence occurs, the ISN field is not used for positioning if the comparator for the starting descriptor value is set to

• GT (greater than) for an ascending read sequence; or

• LT (less than) for a descending read sequence.

Otherwise, the ISN field plays a role and the following rules apply:

Rules for Reading Forward (Ascending Option)

If the starting descriptor value specified in the value buffer is present in the logical read sequence, specifying

• an ISN of zero results in positioning to the first ( lowest ) ISN with that descriptor value;

• a non-zero ISN results in positioning to the lowest ISN greater than the specified ISN with that descriptor value, if such an ISN exists. Otherwise, positioning is to the first ISN of the next higher descriptor value.

If the starting descriptor value specified in the value buffer is not present in the logical read sequence, positioning is always to the first ISN of the next higher descriptor value, regardless of the specified ISN.

Rules for Reading Backward (Descending Option)

If the starting descriptor value specified in the value buffer is present in the logical read sequence, specifying

• an ISN of zero results in positioning to the last (highest) ISN with that descriptor value;

• a non-zero ISN results in positioning to the highest ISN less than the specified ISN with that descriptor value, if such an ISN exists. Otherwise, positioning is to the last ISN of the next lower descriptor value.

If the starting descriptor value specified in the value buffer is not present in the logical read sequence, positioning is always to the last ISN of the next lower descriptor value, regardless of the specified ISN.

ISN Lower Limit: Multifetch Record Count

If either "M" or "O" (multifetching option) is specified in the command option 1 field, a non-zero value in this field determines the maximum number of records to be multifetched. If this value is zero, the number of records to be multifetched is limited by the record and ISN buffer lengths. Refer to the section Using the Multifetch/Prefetch Feature for more information.

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

If the search buffer is used, the length of the search buffer must be set in this field. The search buffer is required if the value start option is used. If the search buffer is not used, the value zero (0) must be set in this field.

Value Buffer Length

If the value buffer is used, the length of the value buffer must be set in this field. The value buffer is required if the value start option is used. If the value buffer is not used, the value zero (0) must be set in this field.

ISN Buffer Length: Only with Command-Level Multi-/Prefetch Option

The ISN buffer length (in bytes). The ISN buffer area defined in the user program must be at least as large as the length specified.

Command Option 1

Option	Description
M	(multifetching)
O	(multifetching with the "R" option)
P	(prefetching)
	Specifying one of these options indicates that the (command-level) prefetch or multifetch option is to be used. The multifetch/prefetch option can improve performance by allowing prior access to one or more sequential records, reducing overall operating time and eliminating the time needed for single-record fetches. For more information, see the section Using the Multifetch/Prefetch Feature.
R	(return) returns response code 145 if the record to be read and held by an L6 command is not available.

Command Option 2

This option specifies the sequence in which the descriptor's entries are to be processed.

Option	Description
A	(ascending) processes entries for the descriptor in ascending sequence with an optional specification of a starting value. A starting descriptor value can be specified in the value buffer. In addition, a non-null value in the ISN field can be used to position within multiple matching descriptor value entries. If the search buffer and value buffer are omitted (SBL and VBL are set to zero (0)), all entries for the descriptor are processed.
D	(descending) processes entries for the descriptor in descending sequence with an optional specification of a starting value. A starting descriptor value can be specified in the value buffer. In addition, a non-null value in the ISN field can be used to position within multiple matching descriptor value entries. If the search buffer and value buffer are omitted (SBL and VBL are set to zero (0)), all entries for the descriptor are processed.
V	(value start) specifies an ascending sequential pass to begin (or continue) at a user-specified value rather than with the lowest (or next) value of the descriptor. The user-specified value must be in the value buffer, and the value's length and format must be specified in the search buffer. A non-null value specified in the ISN field can further qualify the read operation. This option was used in Adabas prior to version 6; it is maintained to support existing programs.
blank	specifies an ascending sequential pass without a starting value; all values present are processed. The search buffer and value buffer are ignored when present. This option was used in Adabas prior to version 6; it is maintained to support existing programs.

Additions 1: Descriptor Used for Sequence Control

The descriptor to be used to control the read sequence must be specified in this field. A descriptor, subdescriptor, or superdescriptor may be specified.

• Phonetic descriptors and descriptors contained within or derived from a field contained within a periodic group may not be specified.

• A descriptor which is a multiple-value field may be specified, in which case the same record may be read several times (once for each different value within a given record) during the sequential pass through the file.

• If the descriptor specified is defined with the null value suppression (NU) option, any records containing a null value for the descriptor will not be read.

• The descriptor name is specified in the first two positions of this field. All remaining positions must be set to blanks on the initial call.

The additions 1 field should not be modified between L3/L6 calls. The exception is when the user wishes to reposition to a particular value during a sequential pass. This is done by setting the last six positions of this field to blanks, inserting the value to which repositioning is to occur in the value buffer, setting the ISN field to zero, and setting the command option 2 field to "A", "D", or "V".

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.

Note:
This length information is not returned when the prefetch feature is being used.

If the L3 or L6 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 described 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

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

Use this field to specify a separate format ID that identifies the internal format buffer used for this command, or to provide a global format ID allowing use of the internal format buffer by all users.

As long as the leftmost bit of the additions 5 field is set to 0, the value provided in the command ID field is used as the format ID as well.

If the leftmost bit is set to 1, the contents of the fifth through eighth bytes of the additions 5 field (additions 5 + 4(4)) are interpreted 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).

See the section Command ID, Format ID, Global Format ID for more information and examples.

Buffers

Format Buffer

The fields for which values are to be returned must be specified in this buffer. The syntax and examples of format buffer construction are described in the Adabas Calling Procedure.

Specifying "C." in the first two positions indicates that the compressed option is in effect. This causes the record to be returned in compressed instead of decompressed format.

Record Buffer

Adabas returns the requested field values in this buffer. The field values are returned according to the standard format and length of each field, unless the user has requested a different format and/or length in the format buffer.

Search Buffer

Note:
Commas separate elements in the search buffer; a period terminates the syntax statement. For more information about search buffer syntax, see the discussion beginning on page .

The search buffer length (SBL) must be set in the control block. If the search buffer is not used, SBL must be set to zero (0).

If the value start (V) option is used for command option 2, the starting value of the descriptor used for sequence control must be specified in the value buffer and the value's length and format must be specified in the search buffer.

If the ascending (A) or descending (D) option is used for command option 2, a search buffer may be used but is not required. If either the search or value buffer is omitted, all values for a given descriptor are processed. If a starting value, ending value, or both are specified in the value buffer, the search buffer must be used to limit the number of descriptor entries retrieved.

The length and format of the descriptor value as provided in the value buffer must be specified in the search buffer if different from the standard length and/or format of the named descriptor.

When a single value is provided in the value buffer (that is, the starting value with option A or the ending value with option D), the syntax for the search buffer is

name [ ,length ] [ ,format ] [ ,comparator ]

When two values are provided in the value buffer (that is, a starting and an ending value), the syntax for the search buffer is

name [ ,length ] [ ,format ] ,S ,name [ ,length ] [ ,format ]

The elements used in the search buffer syntax statements are

See Example 3: Overview of Sequence Options for an overview of sequence options resulting from the choice of A or D for command option 2 and various search and value buffer options.

Value Buffer

The value buffer length (VBL) must be set in the control block. If the value buffer is not used, VBL must be set to zero (0).

If the value start option is to be used, or if value repositioning is to be performed, the value with which reading is to start (or continue) must be specified in this buffer.

If the ascending (A) or descending (D) option is used for command option 2, a value buffer may be used but is not required. If either the search or value buffer is omitted, all values for a given descriptor are processed. If a starting value, ending value, or both are specified in the value buffer, the search buffer is required in order to limit the number of descriptor entries retrieved.

If the ascending (A) option is used for command option 2, reading starts (or continues) with the first record containing the value specified. If there are no records with keys equal to a start or reposition (continue) value, reading begins with the first record containing the next higher value.

When two values are provided in the value buffer, the first specifies the lower limit of a range and the second specifies the upper limit. Each value is either the starting or ending value depending on the command option 2 setting of A or D.

In addition, if the ISN field is set to a non-zero value, reading will start (or continue) or end with the first record whose ISN is present for the value specified, provided that the ISN is greater than the ISN in the ISN field. If no such ISN exists, the first record with the next higher (or lower) value is read.

Search and Value Buffer Examples

Example 1: ASCENDING Option with Optional Search and Value Buffer

Inverted list for the descriptor used for sequence control:

Initial L3/L6 command with command option 2 set to "A" (ascending option), or subsequent L3/L6 command with command option 2 set to "A" and the last six bytes of additions 1 reset to blanks:

Example 2: DESCENDING Option with Optional Search and Value Buffer

Inverted list for the descriptor used for sequence control:

Initial L3/L6 command with command option 2 set to "D" (descending option), ISN=0 for optional start, search buffer comparator set to "LT", and value buffer containing value "C". The start position is the highest ISN of the next lower descriptor value: in this example, ISN 21 of descriptor value "B".

Example 3: Overview of Sequence Options

The following table illustrates the possibilities for using the ascending/descending option in conjunction with various search buffer and value buffer contents. The following applies to the file being read and ISN=0 (no further positioning within matching start values):

Overview of Sequence Options

ISN Buffer

The ISN buffer is used only if the command-level multifetch or prefetch option is used. See the section Using the Multifetch/Prefetch Feature for more information.

Additional Considerations

The following additional considerations are applicable for the L3/L6 command:

1. The command ID used with the L3/L6 command is saved internally and used by Adabas. It is released by Adabas when an end-of-file condition is detected, an RC or CL command is issued, or the Adabas session is terminated. The same command ID may not be used by the user for another read sequential command until the command ID has been released.

2. The user is permitted to update and/or delete records from a file that is being read by the user with an L3/L6 command. If the inserted record or records are to be read, the user must reposition after having inserted the record or records.

3. If any user is updating the file being read with an L3/L6 command, it is possible that the user reading with the L3/L6 command either may not receive one or more records in the file, or may receive the same record more than once during a sequential pass of the file.

Note:
You should avoid updating any descriptor field that controls the read sequence with a value greater than that which it currently contains.

Examples

Example 1

File 2 is to be read in logical sequential order. The descriptor RB is to be used for sequence control. The values for the fields RA and RB are to be returned. The entire file is to be read.

Control Block

Buffer Areas

The L3 call is repeated to obtain each successive record. The CID and additions 1 field must not be modified between L3 calls. Response code 3 will be returned when all records have been read.

Example 2: Read Logical Sequential with Record Hold

File 1 is to be read in logical sequential order. The descriptor AA is to be used for sequence control. The values for fields AA and AB are to be returned. Each record read is to be placed in hold status.

Control Block

Buffer Areas

To complete logical transactions and release held records, ET logic users should issue an ET command. Non-ET users should release held records with an A4, E4, or RI command.

Example 3: ASCENDING Option

The same requirement as example 1 except that reading is to begin with the value "N".

Control Block

Buffer Areas

The initial L3 call will result in the return of the first record which contains the value "N" for the descriptor RB. If no records exist with this value, the first record which contains a value greater than "N" (such as "NA") will be returned.

Example 4: DESCENDING Option with Repositioning

The same requirement as example 3 except that a value repositioning is to be performed. The sequential read process is to continue with the value "Q".

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