Version 8.2.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 RESET Resets the client commands trace area (only if runtime control Trace is active). API001UP / AVICLOG
- Traces client commands (only if runtime control Trace is active). Show results newest-to-oldest.
+ Traces client commands (only if runtime control Trace is active). Show results oldest-to-newest.
  “No option” has the same functionality as “+” .
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
PARTID NEXT Sub-option I:

For extreme files, sets the partition-id to use on the next command. Use when the next command supplies a single ISN that conflicts with the expectations of current.

Sub-option L:

As option I, except sets a list of partition ids. Use when the next command supplies a list of ISNs (S9 "sort ISN list").

API012UP
LATEST Sub-option I:

For extreme-partitioned files, retrieve the partition-id of the single ISN returned from the immediately preceding command.

Sub-option L:

As option I, except retrieve a list of partition-ids from the immediately preceding (ISN-list creating) command (e.g. Sx with IBL>0).

 
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.

CLOG Function

A client session may request tracing of commands using the CLOG API as long as the client runtime control TRACE is active.

For example, the results of the trace may be displayed oldest-to-newest:

 1 OP 00000000   135     0   135     0   0 40404040 40404040     00000000
 2 S1 00000000   135    77   135    77   0 000011BB 00000001     00000000
 3 L3 00000001   135    32   135    32   0 0000026E 00000000   V 24150201
 4 RC 00000001   135     0   135    32   0 00000000 00000000 S I 24150201  

or newest-to-oldest:

4 RC 00000001   135     0   135    32   0 00000000 00000000 S I 24150201
3 L3 00000001   135    32   135    32   0 0000026E 00000000   V 24150201
2 S1 00000000   135    77   135    77   0 000011BB 00000001     00000000
1 OP 00000000   135     0   135     0   0 40404040 40404040     00000000  

Furthermore, the whole log area can be cleared using the RESET option.

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.

PARTID Function

For use in conjunction with extreme partitions, this function can be used to extract the partition-id(s) from the immediately preceding command (single ISN or ISN list) or supply the partition-id(s) to use on the immediately subsequent command (single ISN or ISN list). Partition-ids from the preceding command are lost if not immediately retrieved using the LATEST sub-function. Partition-ids set using the NEXT sub-function are lost if not immediately required on the next command.

When supplying a single partition-id on a NEXT call sub-function "I", the API can specify either the partition name or a database id/file number and Vista will perform a lookup to obtain the id, or the application can supply the actual partition-id (unchanged, as returned from e.g. a previous command or PARTID LATEST API call).

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