API for Natural

Data Archiving for Adabas provides an application programming interface for Natural which enables two interfaces:

Batch Interface

This interface allows you to control, monitor and report archive and transfer activities directly from your own infrastructure.

To-Do List Interface

As an alternative to using Extraction Syntax for data selection, this interface allows you to select data to be archived or transferred using your own custom applications by maintaining business objects (collections of related Adabas ISNs) in a repository file. An Action can then be run which references these business objects and performs the appropriate archiving/transfer operations against the corresponding records. Please refer to Data Selection Mode for information on how to define an Action to run in To-Do List mode.

Installing the API

The application programming interface for Natural is included in the SYSADR Natural library provided as an INPL file and supplied as part of the standard installation.

Instructions for installing the INPL file can be found in the readme.txt file located in the product's sdk/nat directory.

Implementing the API

The application programming interface for Natural is implemented as a callable sub-program (ADRAPI) with an interface block passed to it as argument.

The interface block (ADRAPI-INTERFACE) is mapped by ADRAPIP1 and constant values used as flags are defined in ADRAPIL1. Both these data areas must be included in your program as LOCAL data. 

DEFINE DATA
  LOCAL USING ADRAPIL1
  LOCAL USING ADRAPIP1
LOCAL

Upon successful completion of an API function ADRAPI-ERROR-CODE will contain 0000. If an API function cannot execute successfully, ADRAPI-ERROR-CODE will contain an error number, whilst ADRAPI-ERROR-DESCRIPTION and ADRAPI-ERROR-DESCRIPTION2 will contain textual descriptions of the error. Refer to the Messages and Codes section for a full list of error codes and their meanings.

Note:
Further information about all the fields in the interface block and their particular use in each of the functions is provided in the README text member in library SYSADR.

API Functions

The application programming interface for Natural provides two interfaces that allow you to drive archiving and transfer operations.

Batch Interface

The batch interface allows your own custom application to perform the following functions:

Function Description
ACTIVITY-INFO Returns detailed information about a current Activity.
ACTIVITY-LIST Returns individual lists of Activity IDs, Databases, and Computers for all current Activities.
ARCHIVE Starts an Activity for a specified Action.
COMPUTER-STATUS Returns status-related counts for all current Activities processing on one or more specified computers.
DATABASE-STATUS Returns status-related counts for all current Activities processing on one or more specified databases.
PAUSE Pauses a current Activity.
RECALL Recalls a particular Archive for a specified Action.
RESTART Restarts a failed Activity.
RESUME Resumes a paused Activity.
STOP Stops a current or paused Activity.

To-Do List Interface

The To-Do list interface allows your own custom application to perform the following functions:

Function Description
CLOSE Closes the To-Do list, allowing the user to leave it in a state where it can be modified (INSERT, ERASE, REPLACE) or submits it ready for processing by the archiving service ready for when it’s next commanded to run.
CREATE Creates a new empty To-Do list for a specific Group, Plan, and Action.
ERASE Deletes an existing business object (collection of related ISNs) from an open To-Do list.
INSERT Inserts a new business object (collection of related ISNs) into an open To-Do list.
OPEN Opens an existing To-Do list for modification (INSERT, ERASE, REPLACE).
REMOVE Deletes an existing To-Do list regardless of its state.
REPLACE Replaces an existing business object (collection of related ISNs) in an open To-Do list.
TO_DO Status Return the status of a To-Do list.

Examples

For a working example of the Batch interface refer to the APICMD program in the SYSADR Natural library.

For a working example of the To-Do List interface refer to the TODOLIST program in the SYSADR Natural library.

Messages and Codes

Refer to the section API for Natural Error Codes.