Adabas Vista makes as much information as possible available to the application programmer through the Adabas Vista application programming interface (API).
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 programs that invoke each of the available API functions. These functions can be executed by the application for whom the information is relevant.
The necessary Natural objects must be installed according to the instructions provided in the section Installation.
Any API invoked changes only remain active for the duration of a user’s session.
In a Natural environment, if you log on to the Adabas Vista library to execute these API functions the change may be lost when you log back on to your application library. This is due to Natural’s session handling.
To avoid losing such changes, make the API example programs available without the need to log on to another library:
If Natural Security is in use, include the Adabas Vista library SYSMVvrs in the steplib of the application library.
If Natural Seurity is not in use, copy the appropriate API program to the Natural SYSTEM library along with the objects API0000P and API00nVP wheren is the API function number.
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.
The following table lists the available API functions:
| Function | Option | Description | Example |
|---|---|---|---|
| CATEGORY | UPDATE | Modifies the user's current target category. | API009UP |
| EXTRACT | Extracts the user's current target category. | ||
| CLOG | Traces user commands (only if job parameter Trace is active). | API001UP / AVICLOG | |
| CONTEXT | UPDATE | Modifies the user's current context. Also allows the temporary
suspension of the user's current context. Possible values:
S: single context |
API010UP |
| EXTRACT | Extracts the user's current context. Possible values:
' ': current context |
||
| DELETE | Deletes a specified suspended context, or all suspended contexts
for the user. Possible values:
' ': specified context |
||
| 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 | |
| PARTLIST | Lists all partitions for the specified partitioned file. | API006UP | |
| PARTOPTS | UPDATE | Modifies the user's current Access and
Critical parameter values for the specified partitioned
file and partition.
|
API004UP |
| EXTRACT | Extracts the user's current Access and
Critical parameter values for the specified partitioned
file and partition.
|
||
| PROFID | UPDATE | Modifies the user's current Profile ID. | API003UP |
| EXTRACT | Extracts the user's current Profile ID. | ||
| TRTARG | UPDATE | Modifies a specific translate rule for a user. | API008UP |
| EXTRACT | Extracts the details of a user's current translation rule for a given source profile. |
Note:
In a Natural environment, the use of multiple applications may mean
that Natural issues close (CL) commands. Therefore,
any API calls must be re-issued at each application logon.
During application logon, each client may identify its own target category to Adabas Vista using the CATEGORY function. Adabas Vista then uses this Target Category ID together with the Profile ID, source database, and file number to determine the appropriate target database and file number to which commands issued by the application are to be directed.
This function can be executed any number of times during a session to enable dynamic file translation.
The use of the update option of this function will cause an internal
backout of all access by this application. Adabas Vista will issue
BT and CL commands to all
relevant databases to effect this backout.
During application logon, the current context is defined by the Profile ID and Target Category parameters defined for the current job. Each parameter may be dynamically modified by use of the appropriate API function. The CONTEXT function extends this processing.
This function may be used to suspend temporarily the current context for the client and continue processing in a new context. The client application controls the use of such contexts and determines at which point a suspended context should be resumed.
The DELETE option enables the application to terminate any context that
is currently suspended. Adabas Vista will issue
RCcommands at this point.
The PARTOPTS function is used to update or extract the user'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 | Enable the single partition focus feature for this partition. |
| 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.
|
During application logon, each client may identify its own Profile ID to Adabas Vista using the PROFID function. Adabas Vista then matches this ID with the Profile ID of a translation rule or partition definition that uses the same source database and file number to re-direct commands issued by the client to the appropriate target database and file number.
This function can be executed any number of times during a session to enable dynamic file translation.
The use of the update option will cause an internal backout of all
access by this client. Adabas Vista will issue BT
and CL commands to all relevant databases to effect
this backout.
Note:
The CATEGORY and PROFID functions may be used in conjunction with
this function to enable dynamic file translation.
This function can be used to extract or update a specific target database and file number. The client application provides the source database and file number, which is combined with the client's current Profile ID. Using this source profile and the client's current target category, the appropriate details are extracted or updated as required. The update action is only available for translation rules.
The use of the update option will cause an internal backout of access
to the specified file. Adabas Vista will issue RC
command(s) to effect this backout.
Note:
This API can only be used to extract/update details for a 'file'
translation profile - it cannot be used to extract/update details for an
'all-files' profile.
