This section explains several concepts that are important to consider when programming calls.
Internal IDs can be specified to perform important functions during Adabas command execution. In the control block of an Adabas direct call command, the user can specify
a "command ID", a non-blank, non-zero value that acts as an internal ID for decoded record formats; and optionally
a "format ID", a separate four-byte internal ID for decoded record formats defined either as user-specific or globally available (a "global format ID") to other users running on the same Adabas nucleus.
The uses of these IDs is explored in detail in this section.
Also described in this section are
the procedures used to retrieve ISNs from the Adabas Work; and
the multifetch and prefetch options, which are used to reduce execution time for programs that process large amounts of data in sequential order by reducing the number of system commands needed to the complete the Adabas call.
This document covers the following topics:
The command ID, specified in the Adabas control block, performs important functions during Adabas command execution. The command ID is an automatically generated or user-specified nonblank, nonzero value that
prevents repetitive format buffer decoding by acting as an internal ID for decoded record formats;
tags ISN lists generated by the Sx command for later access, and saves ISN list overflow.
If desired, a separate internal format ID for decoded record buffer formats can be specified. This value is identified by a flag in the high-order (leftmost) two bits of the first byte of the additions 5 field. Depending on the flag value, the format ID can be user-specific (individual) or available to other users running on the same Adabas nucleus (global).
This section covers the following topics:
The read sequential commands (L2/L3, L5/L6, L9) require that a command ID be specified. The command ID is needed by Adabas to return the records to the user in the proper sequence. These command IDs are maintained by Adabas in the table of sequential commands.
The command ID value provided with these commands is also entered and maintained in the internal format buffer pool unless a separate format ID is provided as described in the section Using Separate Command and Format IDs. The command ID is released by Adabas when an end-of-file condition is detected during read sequential processing.
The read commands (L1-L6, L9) and update commands (A1/A4, N1/N2) require a format buffer that specifies the fields to be read or updated. This format buffer must be interpreted and converted into an internal format buffer by Adabas. Using a valid command ID avoids repeated interpretation and conversion by successive commands that use the same format buffer.
A read or update command with a valid command ID causes Adabas to check whether the command ID is in the internal format buffer pool. If the command ID is present, its internal format buffer is used, and no format buffer reinterpretation is required.
Note:
When reading or updating a series of records that use the same
format buffer, processing time can be significantly reduced by using a command
ID.
Internal format buffers (and the format IDs) resulting from L9 commands can only be used by other L9 commands. Moreover, L9 commands cannot use non-L9 internal format buffers / format IDs.
When reading and updating the same fields (for example, L5 followed by A1), Software AG also recommends that the same command ID be used for both commands (see the A1/A4 and N1/N2 commands for restrictions on using the same format buffer for reading and updating).
If the read-first-record option is used with an S1/S2/S4 command and a command ID is specified, the command ID and the resulting internal format buffer are also stored in the internal format buffer pool.
If the internal format buffer pool is full and a command is received with a command ID without an internal format in the pool, Adabas overwrites the longest unused entry in the pool with the new interpreted format ID. If a command is subsequently received that uses the deleted command ID, the reinterpreted format buffer for that command ID replaces the next-longest unused entry in the pool. For this reason, programs must not change the format buffer between successive read or update commands with the same command ID. Note, however, that use of a command ID does not guarantee that the format buffer is not reinterpreted.
It is possible to use separate values for command IDs and format IDs. As long as the high-order (leftmost) two bits of the additions 5 field are set to binary '00', the command ID is automatically used as the format ID. If, however, the additions 5 field's high-order two bits are binary '10', the fifth through eighth bytes (additions 5 + 4(4)) of the field are used as the format ID. Note that the ID may not start with X'FE' or X'FF'.
Note:
To identify the format ID as separate from the command ID,
non-mainframe Adabas environments expect the first byte of the additions 5
field to be any lowercase letter. When using separate format IDs in a
heterogeneous environment, it is important to identify them alike across all
platforms used in the system.
Particularly in an online environment, multiple users of the same program often read or update the same fields of a file and therefore use identical format buffers.
When you use the individual format ID option, Adabas must store the same internal format buffer for each user.
When you use the global format ID option, a single internal format buffer is shared by many users and the need for Adabas to overwrite internal format buffer pool entries is reduced. This option identifies the format buffer to each user by format ID only, rather than by both format ID and terminal ID. A command ID cannot be designated as a global format ID; in addition, the restriction of L9 formats and their IDs being valid only for use by other L9 commands also applies to global formats and IDs.
The global format ID option is activated by setting the high-order (leftmost) two bits of the first byte of the additions 5 field to binary '11' (see Example 3: Using a Global Format ID). This causes all eight bytes of additions 5 to be recognized as the global format ID.
Note:
To identify the format ID as global in non-mainframe Adabas
environments, the first byte of the additions 5 field must be set to be any
digit or uppercase letter. When using global format IDs in a heterogeneous
environment, it is important to identify them alike across all platforms used
in the system.
The first byte of the global format ID may be assigned in the hexadecimal range E2-E9; characters S-Z. All other ranges are reserved for use by Software AG.
The allowable range of values for global format IDs in non-mainframe Adabas environments is hexadecimal 51-5A; characters S-Z.
 |
Warning: Adabas does not verify the assignment of global format IDs. It is the user's responsibility to ensure that only global format IDs in the allowable range are assigned. Software AG can neither enlarge the range of global format IDs available to users nor make any changes to its products to resolve a global format ID assignment problem. |
A global format ID can be deleted using the RC command and specifying the global format ID in the additions 5 field, as described.
This section covers the following topics:
When B'00' is set in the high-order (leftmost) two bits of the first byte of the additions 5 field, the command ID is automatically used as the format ID.
When B'10' is set in the high-order (leftmost) two bits of the first byte of the additions 5 field, separate values are used for the command ID and the format ID, and the fifth through eighth bytes of the additions 5 field are used as the format ID.
When B'11' is set in the high-order (leftmost) two bits of the first byte of the additions 5 field, all eight bytes of the field are used as the global format ID.
If a command ID is specified for any command which results in an ISN list (S1,S2,S4,S5,S8,S9), the command ID value may be used to identify the list at a later time.
If the save-ISN-list option is used for an Sx command, a command ID must be provided. The save-ISN-list option causes the entire ISN list to be stored on the Adabas Work. ISNs from the list may subsequently be retrieved by an Sx command or by using the GET NEXT option of the L1/L4 command.
If the save-ISN-list option is not used and an ISN buffer overflow condition occurs (the entire ISN list cannot be inserted in the ISN buffer), the overflow ISNs will be stored on the Adabas Work only if a command ID value was used. In this case, the command ID and the ISN list it identifies will be released by Adabas when all the ISNs have been returned to the user.
Automatic command ID generation may be invoked by specifying a command ID value of X'FFFFFFFF'. This causes the Adabas nucleus to generate command IDs automatically, beginning with X'00000001' and incrementing by 1 for each new command ID. Automatic command ID generation may not be desirable in all cases; refer to the section Command/Format IDs for Read, Update, and Find Commands.
The user may release a command ID and its associated entries (or ISN list) with a RC command, a CL command, or by using the release-CID option of any Sx command (S1, S2, S4, S5, S8, S9).
The RC command contains options that allow the user to release only those command IDs contained in the internal format buffer pool, the table of sequential commands, or the table of ISN lists.
The CL command causes all the command IDs currently active for the user to be released.
The release-CID option of an Sx command causes the CID specified to be released as the first action taken by the command.
Each command ID entry is identified by Adabas using an internal user ID together with the command ID value. As a result, one user need not be concerned with the command ID values in use by another. However, a user should avoid using the same command ID value for different commands, particularly if the command ID is used for sequential read (L2/L5, L3/L6, L9) commands and Sx commands.
This section covers the following topics:
A set of records is to be selected and read. The same format buffer is to be used for each record being read.
FIND (S1) CID=EX1A READ (L1) CID=EX1B READ (L1) CID=EX1B
A set of records is to be selected and read using the GET NEXT option of the L1/L4 command.
FIND (S1) CID=EX2A READ (L1) CID=EX2A READ (L1) CID=EX2A READ (L1) CID=EX2A
A file is to be read and updated in sequential order. The same format buffer is to be used for reading and updating.
READ PHYS SEQ (L5) CID=EX3A UPDATE (A4) CID=EX3A READ PHYS SEQ (L5) CID=EX3A UPDATE (A4) CID=EX3A
A file is to be read in logical sequence. A find command is to be issued to a second file using the value of a field read from the first file, and the records that result from the find command are then to be read using the GET NEXT option.
READ LOG SEQ (L3) CID=EX4A FIND (S1) CID=EX4B READ (L1) CID=EX4B READ (L1) CID=EX4B READ LOG SEQ (L3) CID=EX4A FIND (S1) CID=EX4B READ (L1) CID=EX4B
This section discusses the procedures used to retrieve ISNs from the Adabas Work dataset. If the GET NEXT option of the L1/L4 command is used to read the records that correspond to the ISNs contained in the ISN list, ISN handling as discussed in this section is performed automatically by Adabas, and the user need not make use of these procedures.
The notation Sx command as used in this section refers to any command that may result in an ISN list (S1/S2/S4/S5/S8/S9).
This section covers the following topics:
Adabas stores ISNs on the Work dataset under either of the following conditions:
An Sx command is issued, a nonblank nonzero command ID is specified, and the save-ISN-list option is specified. The entire resulting ISN list is stored;
An Sx command is issued, a non-blank non-zero command ID is specified, the save-ISN-list option is not specified, and the resulting ISN list contains more ISNs than can be inserted in the ISN buffer. Only the overflow ISNs are stored in this case.
If an Sx command is issued with blanks or binary zeros in the command ID field, Adabas does not store any ISNs on the Adabas Work.
The user can retrieve ISNs stored on the Adabas Work dataset by issuing an Sx command in which the same command ID value is used as was used for the initial Sx command. When an Sx command with an active command ID value is issued, Adabas uses this as an indicator that the user is requesting ISNs from an existing ISN list. Adabas locates the ISN list identified by the specified command ID and inserts the next group of ISNs in the ISN buffer. As many ISNs are returned as can fit in the ISN buffer.
This section covers the following topics:
If the save-ISN-list option was specified with the Sx command used to create the ISN list, Adabas uses the ISN specified in the ISN lower limit field to determine the next group of ISNs to be returned.
The next group begins with the first ISN that is greater than the ISN specified in ISN lower limit.
If binary zeros are specified, the next group begins with the first ISN in the list.
If a value is specified which is greater than any ISN in the list, response code 25 is returned.
If the ISN list was created using an S2 command, the ISN specified must be present in the ISN list. Use of the save-ISN-list option thus permits the user to skip forward and backward within an ISN list. This is useful for programs that must perform forward and backward screen paging.
If the save-ISN-list option was not specified with the Sx command used to create the ISN list, Adabas returns the ISNs in the order in which they are positioned in the list, and deletes each group from the Work when it has been inserted in the user's ISN buffer. The command ID used to identify the list is released when the last group of ISNs has been returned to the user. The ISN lower limit field is not used in this case, unless processing is to begin above a specified ISN range.
The user can determine when all of the ISNs in a list have been retrieved by using the ISN quantity field of the control block. In this field
the first Sx command returns the total number of records that satisfy the search criteria.
each subsequent Sx command used to retrieve ISNs from the Adabas Work returns the number of ISNs that were inserted in the ISN buffer.
This section covers the following topics:
Sx command L1/L4 command with 'GET NEXT' option L1/L4 command with 'GET NEXT' option L1/L4 command with 'GET NEXT' option
The following examples show various results according to the size of the ISN buffer. Positioning for ISN list is defined by ISN lower limit.
ISN Buffer Length = 0 read the ISN list to the work area
L1/L4 with GET NEXT result: first ISN's record
ISN Buffer Length = 4 read first ISN with S1
L1/L4 with GET NEXT result: second ISN's record
ISN Buffer Length = 12 read first ISN with S1 first 3 ISNs are returned in ISN buffer
L1/L4 with GET NEXT result: read fourth/fifth/sixth ISNs' records
Initial Sx call using save-ISN-list option:
Command = Sx Command ID = SX01 (save-ISN-list option) Command Option 1 = H ISN Lower Limit = 0 ISN Buffer Length = 20 CALL ADABAS ...
Resulting ISN quantity = 7 (total matching ISNs in stored list)
Resulting ISN list: (all ISNs are stored on Work):
8 12 14 15 24 31 33
Resulting ISN buffer:
8 12 14 15 24
Subsequent Sx call:
Command = Sx Command ID = SX01 ISN Lower Limit = 24 (limit ISN choice to 24, +) ISN Buffer Length = 20 (space for 5 ISNs from ISN list) CALL ADABAS ...
Resulting ISN quantity = 2 (total ISNs returned in ISN buffer)
Resulting ISN buffer:
31 33 14 15 24.... remainder of ISN buffer unchanged....
Subsequent Sx call:
Command = Sx Command ID = SX01 ISN Lower Limit = 0 ISN Buffer Length = 20 CALL ADABAS ...
Resulting ISN quantity = 7
Resulting ISN buffer:
8 12 14 15 24
Initial Sx call (save-ISN-list option not used):
Command = Sx Command ID = SX02 Command Option 1 = blank (no option) ISN Lower Limit = 0 ISN Buffer Length = 20 CALL ADABAS ...
Resulting ISN quantity = 7 (total ISNs returned in ISN buffer and stored on Work)
Resulting ISN list: (only ISNs 31 and 33 are stored on Work)
8 12 14 15 24 31 33
Resulting ISN buffer:
8 12 14 15 24
Subsequent Sx call:
Command = Sx Command ID = SX02 ISN Lower Limit (not used) ISN Buffer Length = 20 CALL ADABAS ...
Resulting ISN quantity = 2
Resulting ISN buffer:
31 33 14 15 24
ISNs 31 and 33 are deleted from the Adabas Work, and command ID SX02 is released. A subsequent Sx call with command ID 'SX02' will be processed as an initial Sx call since 'SX02' was released after the last ISNs were returned to the user.
Although the ISN lower limit is not specified in this example, a non-zero value would also return only those ISNs greater than the specified value in the ISN buffer, just as in example 2.
Initial Sx call with blank or zero command ID:
Command = Sx Command ID = blanks or binary zeros Command Option 1 = blank (no option) ISN Lower Limit = 0 (no lower limit specified) ISN Buffer Length = 20 CALL ADABAS ...
Resulting ISN quantity = 7 (total matching ISNs)
Resulting ISN list: none are stored on Work
8 12 14 15 24 31 33
Resulting ISN buffer:
8 12 14 15 24
A subsequent Sx call with command ID equal to blanks or binary zeros and ISN lower limit equal to 0 will result in a reexecution of the same find command with the same result as the initial call. A subsequent call with command ID equal to blanks or binary zeros and ISN lower limit = 24 causes reexecution of the Sx command. The result will be ISN quantity of 2 with ISNs 31 and 33 in the ISN buffer.
Programs that process large amounts of data in sequential order require frequent storage access, causing long execution times. The Adabas multifetch and prefetch options significantly reduce the execution times of such programs by reducing the number of system commands needed to complete Adabas calls.
The multifetch and prefetch options reduce execution time in almost all normal applications; however, the specific advantage depends on the type of application program.
Multifetch and prefetch can be invoked with ADARUN parameters or at command level. The ADARUN PREFETCH, PREFTBL, and other related parameters provide control for batch jobs, and the command options M/O (multifetch) and P (prefetch) provide control at the command level. See the Adabas Operations documentation for information about the ADARUN PREFETCH multifetch/prefetch control parameter.
This section covers the following topics:
The multifetch feature reduces the communication overhead between the application program and the Adabas nucleus. Multifetch buffers multiple record results from a single call, and then transfers the records to the user. Without multifetch, multiple Adabas calls would be necessary to obtain the same result.
Multifetch operation is similar to prefetch; multifetch comprises prefetch functions and more. Adabas 5.3.2 and above support both prefetch and multifetch; however, new programs should call the multifetch (M) option, which is common across all Adabas platforms.
There are two ways to invoke the prefetch option. How it is invoked determines where the preread records are held for processing and therefore what buffer space must be allocated.
The first method, specifying the PREFETCH=YES or OLD parameter on the ADARUN statement, is the most efficient and requires no application programming changes.
When PREFETCH=YES or OLD, Adabas uses a double buffering technique that allows processing of one group of records while the following group is being fetched.
A prefetch buffer must first be defined with the PREFSBL and PREFTBL ADARUN parameters. For more information on specifying these and other ADARUN PREFETCH parameters, refer to the Adabas Operations documentation.
The second method is to specify the M or O option (for multifetch) in the L1/L4, L2/L5, L3/L6, L9, BT or ET commands; or the P option (for prefetch) in the L1/L4, L2/L5, L3/L6 or L9 commands. See the section Prefetch Operation Processing for more information.
This section covers the following topics:
Multifetch operation is compatible with the corresponding operation on non-mainframe platforms, and can be used across platforms in heterogeneous environments.
Multifetching applies to the following Adabas commands:
L1/L4 with I or N option (read by ISN, find with GET NEXT)
L2/L5 (read physical)
L3/L6 (read logical by descriptor)
L9 (histogram)
BT (backout transaction)
ET (end of transaction)
For all read calls (Lx), multifetch returns a group of records in the record buffer and a description of these records in the caller's ISN buffer. The maximum number of records is limited by the following values, which are specified in the Adabas control block:
user-defined maximum as input to the call;
record buffer length;
ISN buffer length.
Prior to the Adabas call, certain fields of the Adabas control block must be set as follows:
| Command code | Supported command type and options (see the command list in section Multifetch Operation Processing) |
| ISN lower limit (ISL) | Maximum number of values to return, or "0" to multifetch all values. |
| Command option 1 | Set to "M" or "O" (see note 1 below) |
| Record buffer length | length of the record buffer |
| ISN buffer length | length of the ISN buffer |
Notes:
The contents of the returned record buffer and ISN buffer are as follows:
Record Buffer: record1,record2, ... ,recordn
Records are returned in the record buffer as usual. If more than one record is returned, all records are placed adjoining in the record buffer.
Descriptive elements for these records are returned in the ISN buffer. The first (leftmost) fullword of the ISN buffer contains the number of elements that follow (signed integer, four bytes). Following this count are the record descriptor elements, each 16 bytes long:
ISN Buffer: Record descriptor element count{record descriptor element }...
A record descriptor element has the structure shown in the following Multifetch Record Descriptor Element (in ISN Buffer) table.
| Format | Length | Content |
|---|---|---|
| All fields unsigned integer, right aligned | 4 bytes | Length of this record in record buffer. Records may have different lengths. |
| 4 bytes | Adabas response for this record. If a nonzero response is given, no record is stored in the record buffer. | |
| 4 bytes | ISN for this record. | |
| 4 bytes | (L9 only) ISN quantity: value count for this descriptor. |
If an error is detected while the first record is being processed, the error response is returned in the response code field of the Adabas control block.
If an error is detected while a record other than the first is being processed, the response code is returned in the corresponding record descriptor element in the ISN buffer.
By default, Adabas releases all currently held ISNs for the user issuing a BT/ET command. With the multifetch option, only a subset of the records held by the current transaction is released. The records to be released from hold status are specified in the ISN buffer. The first fullword in the ISN buffer specified the number of 8-byte elements following.
You can activate the command-level multifetch feature for the ET/BT command call by setting the following fields of the Adabas control block as indicated:
| Command code | BT or ET |
| Command option 1 | M |
| ISN buffer length | The length of the ISN descriptor element count and all descriptor elements, minimum |
Note:
If multifetch is set with ADARUN PREFETCH=YES, the "P" option is
automatically used for ET/BT commands (the "M" option is automatically used for
all other commands).
The ISN buffer must contain the following values:
ISN Buffer: ISN descriptor element count {ISN descriptor element (See table below)} ...
where a file number/ISN element has the format shown in the following Multifetch ISN Descriptor Element for BT/ET Command table.
| Format | Length | Content |
|---|---|---|
| Binary, right aligned | 4 bytes | Adabas file number |
| 4 bytes | ISN |
Prefetch is effective for programs that use sequential commands (L1/L4 with GET NEXT, L2/L5, L3/L6, L9). When using prefetch, a series of sequential read commands requires only one Adabas call. This single call causes several records to be read at a time from the database. This results in a significant reduction in interregion communication overhead and also permits the overlapped operation of the user program and the Adabas nucleus.
Note:
If the hold option is used (L4/5/6 commands), Adabas places records
in hold status when they are read into the prefetch buffer area. This means
that if an ET command is issued before all records have been processed, all
records (including those not yet processed) are released. The hold ISN option
of the ET or HI command can be used to place any such records back into hold
status.
Specific commands and/or files can be excluded from prefetch option processing by specifying the files or commands to be excluded with the respective ADARUN PREFXFIL or PREFXCMD parameters.
When enabling prefetch with the command-specific "P" option, Adabas uses the ISN buffer defined within the user program as the intermediate storage area for the pre-read records. Each record in the ISN buffer is preceded by a 16-byte header:
| Byte | Use |
|---|---|
| 1-2 | Length of record (including length definition). A length of zero indicates the end of data. |
| 3-4 | Nucleus response code |
| 5-8 | Nucleus internal ID (if the response code is neither zero nor 3, a subcode is returned in the rightmost 2 bytes) |
| 9-12 | ISN of the record |
| 13-16 | ISN quantity (L9 command only) |
The first record is provided by Adabas in the record buffer (without the 16-byte header). The user must then process additional records from the ISN buffer. When end-of-file occurs, the header of the last record in the ISN buffer contains Adabas response code 3, and the two-byte end character contains binary zeros.
The following are points to consider when using the prefetch option:
The record buffer size should be set just large enough to contain the largest expected decompressed record.
If the sequential pass of a file is not to be continued until end-of-file condition is detected, be sure to issue an "RC" command to release the command ID used whenever file processing has been completed.
The command ID should not be changed during file processing.
When using a command option "P" to invoke prefetch operation, the ISN buffer size must be a multiple of the total of the record buffer length plus 16, and a final two bytes for an end character:
