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