Additional Programming-Related Topics

This section provides additional information related to programming applications for use with Adabas Vista:

Coupled Files

Adabas Vista does not support search criteria that include syntax for physically coupled files or softly coupled files.

Command Limit

An optional commaned limit can be defined for a translation rule. If a client exceeds this limit then a response code 249, subcode 129 is returned. A command limit of 0 (zero) means that use of this particular rule is unlimited.

Error Handling

Adabas Vista uses the default Adabas response code 249 to indicate that an Adabas Vista processing error has occurred. This response code can be modified using the runtime control Error Response Code.

To qualify the error, a non-zero binary value is placed in the subcode field (the low-order 2-bytes of the Adabas Control Block Additions 2 field). Possible values for this subcode are provided in section Messages and Codes.

The application programmer can convert the response subcodes to error message text using the ERRM function of the Adabas Vista API (see Application Programming Interface).

When using Natural, the subcode may be retrieved using the USR0610N subprogram in library SYSEXT. This enables the following construct for an ON ERROR block: 

0250   READ AVI1 LOGICAL BY NAME
0260       DISPLAY FIRST-NAME LAST-NAME SEX
0270   END-READ
0280   ON ERROR
0290   IF *ERROR-NR = 3249
0300       CALLNAT 'USR061ON' DB_ERR_STR
0310           WRITE 'AVI error, subcode:' DB_SUBCODE
0320   END-IF
0330   END-ERROR
0340   END

It is strongly recommended that error handling is implemented so that error conditions can be identified and handled immediately.

Refer to the runtime control Error Reporting for additional error reporting options.

Multiclient File Processing

Adabas Vista is able to process multiclient files. There are a few considerations that should be made when using this type of file with Adabas Vista:

  • Adabas Vista does not support superuser Owner IDs with distributed access. The sequence of records returned will not be the same as for a normal Adabas multiclient file. These superusers are most likely to be used for utilities, which are not normally run with Adabas Vista.

  • Adabas Vista cannot use the internal Owner ID as partition criteria. See the file parameter Partitioning Field for valid field types.

Shared Partitions

When processing Adabas Vista files that have some partitions shared, extra processing is required to determine the correct partition for a particular record, and to ensure that records are returned to the application in the most appropriate sequence for the command. This extra processing may have an adverse effect on performance for these command sequences.

For example, an L1 command sequence processes all records in a file that is defined to Adabas Vista with three partitions, the first and third partitions sharing a single file. Adabas Vista will scan through the first file and extract all records that logically belong to the first partition. The second file will be processed as normal, and Adabas Vista will then scan through the first file again to extract the records that logically belong to the third partition.

When issuing an L9 command against a shared partition where the descriptor used is not the partitioning field, although the count returned is correct, the ISN returned in the ISN Lower Limit field may indicate an incorrect partition. It is not possible to differentiate between the partitions in a shared file for an L9 command.

Single Partition Focus

The Single Partition Focus feature exists only for backwards compatibility. You should change use of this feature to the ONLY option of the Access file partitioning parameter. The Single Partition Focus feature will be removed from future releases.

Updating the Partitioning Field

Special consideration must be made if modifying the record’s partition criteria will result in the movement of the record from one partition to another. First, it is inevitable that the ISN will change – which is absolutely not a normal programming situation – and which may require some application design consideration. Second, moving from one partition to another may require a distributed transaction which will only be safe if you use Adabas Transaction Manager. Adabas Vista will allow such record movement but only using a specific exit that defines how the record movement is to take place. Please contact Software AG in order to proceed in this area.

If no such exit is in use, any attempt to modify a record’s partition criteria which would result in a cross partition move will return a response code. If such a modification is required, a DELETE and STORE operation must be performed.