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

• API Function Overview

• API Function Descriptions

---

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.

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

API Function Descriptions

• CATEGORY Function

• CLOG Function

• PAGE Function

• PARTOPTS Function

• TRTARG Function

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.

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.