Version 8.1.2
 —  Adabas Vista Programming Guidelines  —

Adabas Vista Application Programming Interface

The following Adabas Vista interfaces are made available to the application programmer, some of which allow pre-defined configuration settings to be overridden. The programmer should be aware that the most efficient mode of operation for Adabas Vista is to use the pre-defined configuration settings and that any dynamic runtime changes by API may incur additional overhead.

All API functions are available for Natural and most API functions are also available for 3GL programs.


Executing APIs with Natural and 3GL Programs

The Adabas Vista installation INPL dataset includes example Natural programs for each of the available API functions. These Natural objects must be installed according to the instructions provided in the section Installation.

In a 3GL environment, the supplied AVIPAPI program enables a 3GL program to utilise these API functions. Each API function available for use by a 3GL program has an example program in the Adabas Vista source library. These programs are named APIASMnn, where nn corresponds to the Natural example program number in the table below. For example, APIASM09 is the sample 3GL API program for the CATEGORY function.

Note:
API usage changes the normal behavior of the software. Once an API is used to change a setting, the new setting is usually persistent until another API (or a change by some other means) is used to alter the setting again.

Top of page

API Function Overview

The following table lists the available API functions:

Function Option Description Example
CATEGORY   UPDATE Modifies the client's current target category. API009UP
EXTRACT Extracts the client's current target category.  
CLOG   Traces client commands (only if runtime control Trace is active). API001UP / AVICLOG
CONVISN   ADATOAVI Converts an ISN from Adabas format to Adabas Vista format (including Partition ID). API007UP
AVITOADA Converts an ISN from Adabas Vista format to Adabas format.  
CRITREP   Lists partitions identified as unavailable for the specified partition file. API005UP
ERRM   Translates a supplied Adabas Vista subcode into an error text message. API002UP
PAGE UPDATE Modifies the client's current Page list. API003UP
EXTRACT Extracts the client's current Page list.  
PARTLIST   Lists all partitions for the specified partitioned file. API006UP
PARTOPTS   UPDATE Modifies the client's current Access and Critical parameter values for the specified partitioned file and partition. API004UP
EXTRACT Extracts the client's current Access and Critical parameter values for the specified partitioned file and partition.  
TRTARG   UPDATE Modifies the target details of the client's translation rule identified by the supplied source database and file number. API008UP
EXTRACT Extracts the target details of the client's translation rule identified by the supplied source database and file number.  

Top of page

API Function Descriptions

CATEGORY Function

A client may identify a target category override to Adabas Vista using the CATEGORY function. This replaces the target category established for the client by the active runtime controls. Adabas Vista will use this new target category to direct application calls to the corresponding target database and file number.

The use of the UPDATE option of this function will cause a transparent tidy-up resulting in any active cursors, etc. being ended.

PAGE Function

A client may identify a page list override to Adabas Vista using the PAGE function. This replaces the page list established for the client by the active runtime controls. Adabas Vista will use this new page list to direct application calls to the corresponding target database and file number.

The use of the UPDATE option of this function will cause a transparent tidy-up resulting in any active cursors, etc. being ended.

PARTOPTS Function

The PARTOPTS function is used to update or extract the client's current Access and Critical partition parameter values for the specified partitioned file and partition.

The following Access values are available:

Value Description
F Set the Access partition parameter value to FULL.
R Set the Access partition parameter value to READ.
N Set the Access partition parameter value to NONE.
O Set the Access partition parameter value to ONLY.
X Reset all Access partition parameter values to the defaults.

The following Critical values are available:

Value Description
Y Set the Critical partition parameter value to YES.
N Set the Critical partition parameter value to NO.

TRTARG Function

This function can be used to extract or update the target details of a supplied source database and file number. This source database and file number is used in conjunction with the client’s current target category and page list to identify the corresponding translation target details. An update request will fail if the source file is currently involved in a transaction. This function is only available for individual file translation rules and not “all-files” translation rules.

Warning:
The use of the UPDATE option of this function means that the client session may be routing calls to a target database and file number which is different to that pre-defined in the configuration file.

Top of page