Using the Databridge API

This chapter explains how to use the Databridge ALGOL API and provides information about the entry points and values that the API contains.

Databridge API Overview

Using the API, you can write an Accessory that uses entry points to request information from DBEngine or DBSupport. This information is usually structural and layout information about a DMSII database and data from the database and the audit trail. In addition, the DBSupport entry points can filter and format the data you request. To see a list of entry points grouped by their functions, read Entry Point Procedure Values.

The ALGOL API file (SYMBOL/DATABRIDGE/INTERFACE) contains all of the definitions an Accessory needs to call entry points in DBEngine or DBSupport. This file is installed with the Databridge Host software, and it includes brief descriptions of the expected parameters and the constants specific to DBEngine and DBSupport.

Databridge must be installed on your host before you can use the Databridge API. (If it is not, see the Databridge Installation Guide for instructions on installing Databridge.) Locate where Databridge has been installed and make sure it is visible to your Accessory, based on standard host security.

Information about the library entry points is divided into two sections in this chapter—one for DBEngine entry points and one for DBSupport entry points. Each of these sections include the following:

Reference tables that list and briefly describe the DBEngine or DBSupport entry points as follows:
- DBEngine Entry Points
- DBSupport Entry Points
Separate sections describing each entry point in detail

Sample Accessories

For sample Accessories that illustrate the API, see the following files installed with the Host software. Each sample Accessory also has an associated WFL job, WFL/DATABRIDGE/SAMPLE/ programname for each sample Accessory that includes the necessary file equation.

SYMBOL/DATABRIDGE/SAMPLE/SQLGEN

This sample illustrates one way of generating structured query language (SQL) CREATE TABLE statements to build a relational database similar to a DMSII database. The DBSQLGen sample Accessory reads a DMSII database DESCRIPTION file and then generates SQL CREATE TABLE statements to build a relational database similar to the DMSII database.
SYMBOL/DATABRIDGE/SAMPLE/DASDLGEN

This sample generates a DASDL source for the data sets and sets in a given DESCRIPTION file. It does not provide the physical attributes, audit file attributes, parameters, etc.
SYMBOL/DATABRIDGE/SAMPLE/AUDITCLOSE

This sample causes an audit switch by closing the current audit file and switching to the next audit file. When you run this program, file-equate the DASDL to the title of the DESCRIPTION file. The following example shows how to do this for the BANKDB database description file:

RUN OBJECT/DATABRIDGE/SAMPLE/AUDITCLOSE; FILE DASDL = DESCRIPTION/BANKDB;
SYMBOL/DATABRIDGE/SAMPLE/COBOLGEN

This sample generates a COBOL source for the data sets in a given DESCRIPTION file.
SYMBOL/DATABRIDGE/SAMPLE/READDOC

This sample reports on the programs and database events contained in the audit trail. When you run this program, file-equate the DASDL to the title of the DESCRIPTION file. The following example shows how to do this for the BANKDB database description file:

RUN OBJECT/DATABRIDGE/SAMPLE/READDOC; FILE DASDL = DESCRIPTION/BANKDB;

Entry Point Procedure Values

All entry points are a specific type of procedure based on the kind of value returned. Procedure types can be one of the following:

Type	Description
BOOLEAN	BOOLEAN procedures return a value of TRUE or FALSE. See Boolean Callback Procedures for a description of BOOLEAN procedures and Callback Return Values for the meaning of these values.
DBMTYPE NOTE: The Databridge API defines DBMTYPE to be REAL.	DBMTYPE procedures return real numbers as their values, and the numbers correspond to the Databridge error and status messages. These numbers are listed in the API file. DBMTYPE values indicate the following: Success (for example, DBM_OK = 0) Action (for example, DBM_COMMIT = 1) Failure (for example, DBM_BAD_DSNAME = 5) Most of the entry points return DBMTYPE values. For a description of the messages associated with these values, see the Databridge Host Administrator's Guide. To retrieve a message that describes the DBMTYPE value, call the DBMESSAGE entry point in DBEngine. You can then display this message or write it to a log file.
EMATYPE	EMATYPE (error manager) procedures return EMATYPE values that indicate how a Databridge Accessory should handle errors. EMATYPE procedures use AIDTYPE values, which are ID numbers that identify Databridge Accessories. See Error Manager Types for a description of EMATYPE and AIDTYPE values.

Using the DBMTYPE Values

One way to use DBMTYPE values is to program your Accessory to respond based on the DBMTYPE value returned. Following is an example of how you can do this.

Note

You must include SYMBOL/DATABRIDGE/INTERFACE before you can use DBMTYPE values in your Accessory. See Accessing the DBEngine and DBSupport Libraries for a description of how to include this file.

DBMTYPE DBRESULT;
.
.
.
DBRESULT := engine_entry_point (parameter_1, . . . parameter_n);
IF DBRESULT NEQ DBM_OK THEN
.
.
.

Boolean Callback Procedures

Many of the Databridge API entry points return a list or series of items, such as a list of data sets or a series of records. To accommodate these returned lists, Databridge uses callback procedures. The purpose of the callback procedure technique is to allow your Accessory to manipulate data, item by item, as it is returned from an entry point.

A callback procedure is a Boolean procedure that you name, declare, and write in your program. The callback procedures are referenced in the Databridge API, but they exist in your Accessory. You name the callback procedures whatever you prefer, and you define what the callback procedure does (for example, print, display, and so on). However, the Databridge API file determines the types of parameters the callback procedure receives; the callback procedure in your Accessory determines what to do with the received data. Therefore, you must write your callback procedure to accommodate the parameter values returned to it from the DBEngine entry point.

The Databridge API entry points pass values to the callback procedure based on the type of data that the API entry point retrieved. The Databridge API references your callback procedure as a formal parameter called CALLBACK. The program you are writing must supply the actual parameter for CALLBACK as it is defined in your program.

How Callback Procedures Work

Before you can call a Databridge entry point that has a callback procedure as a parameter, you must declare a Boolean procedure with the same parameter list as the callback procedure. The types of the parameters must match what is in the API, but the parameter names can be whatever you want. This Boolean callback procedure returns TRUE if the entry point should continue to return more items from the list. It returns FALSE to discard the rest of the list.

For example, suppose you want to enumerate the keys of a set using the entry point DBKEYS. The second parameter to DBKEYS is a callback procedure, which the API defines as follows:

boolean procedure Callback (ItemNum, DESCENDING);
% Input: procedure to call back for each key item

        value    ItemNum,   DESCENDING;
        integer  ItemNum;
                 % Input: item number
                 %          (as in ITEM_INFO [II_ITEM_NUM])

   boolean DESCENDING;
     % Input: true if item is a descending key
   formal;

You would define a procedure matching that declaration, such as the following:

boolean procedure GetKey (KeyItemNbr, IsDescending);      value
KeyItemNbr, IsDescending;;
   integer KeyItemNbr; boolean IsDescending;
begin
   if IsDescending then
     display ("Key #" !! string (KeyItemNbr, *) !! " down")
   else
     display ("Key #" !! string (KeyItemNbr, *) !! " up");
GetKey := true;
end GetKey;

The program can then call the entry point, passing it the callback procedure. This example would use the following call:

if DBKEYS (SetStrNum, GetKey) NEQ DBM_OK then
   ... % an error occurred

This example callback procedure, GetKey, is called once for each of the key items of the set indicated by SetStrNum.

When you call an entry point with a callback procedure, the program follows this general sequence:

The program calls the entry point, passing it the callback procedure name as well as any other required parameters.
The entry point that your program calls then prepares the data it retrieves for a single item and calls the callback procedure in your program.
When your callback procedure exits (or finishes), control returns to the entry point.
The entry point retrieves and prepares the data for the next item and calls the callback procedure in your program.
StepsStep2 on page18–Step4 on page19 are repeated until there are no more items in the list. The entry point exits, and control returns to your program.

If the Databridge entry point retrieves 100 items, the callback procedure will be called 100 times.

Callback Return Values

Callback procedures return Boolean values as follows:

TRUE—Continue calling the callback procedure
FALSE—Stop calling the callback procedure. The entry point will typically return a DBM_CB_CANCEL result in this case.

DBEngine Entry Points That Use Callbacks

The following DBEngine entry points use the procedure callbacks:

DBDATASETINFO
DBDATASETS
DBDIRECTORYSEARCH
DBKEYINFO
DBKEYINFOREMAP
DBKEYS
DBKEYSREMAP
DBLAYOUT
DBLINKS
DBREAD
DBREADTRANGROUP
DBSETS
DBSETSINFO
DBSUBSETSINFO
DBWAIT

DBSupport Entry Points That Use Callbacks

The following DBSupport entry points use procedure callbacks:

DBFILTEREDDATASETS
DBFILTEREDLAYOUT
DBFILTEREDLINKS
DBFILTEREDSETS
DBFILTEREDSUBSETSINFO
DBFILTEREDSETSINFO
DBFILTEREDWRITE
DBFORMAT
DBPRIMARYKEY
DBTRANSFORM

Accessing the DBEngine and DBSupport Libraries

Different options exist for accessing the libraries, depending on whether you are using entry points from one library or both.

Requirements for Both Libraries

Each ALGOL Accessory you write to access the DBEngine or DBSupport library must do the following:

Set the appropriate $INCLUDE_ENGINE or $INCLUDE_SUPPORT options before including the interface. Be sure to include both if you are using entry points from both libraries.
Include SYMBOL/DATABRIDGE/INTERFACE using the ALGOL $INCLUDE statement.
Call the appropriate entry point to verify that your program was compiled against the same API file (SYMBOL/DATABRIDGE/INTERFACE) as DBEngine, and if applicable, DBSupport. See the table below for details.

If you are using Then use this entry point

DBEngine only DBINTERFACEVERSION or DBVERSION

DBEngine and DBSupport or DBSupport only DBSUPPORTINIT
Meet the requirements listed later in Additional DBEngine Requirements and, if applicable, in Additional DBSupport Requirements.

The following example shows the interface file $INCLUDE statement:

$SET INCLUDE_ENGINE
$INCLUDE "SYMBOL/DATABRIDGE/INTERFACE"

or

$SET INCLUDE_ENGINE INCLUDE_SUPPORT
$INCLUDE "SYMBOL/DATABRIDGE/INTERFACE"

Additional DBEngine Requirements

In addition to the requirements listed previously, you must also do the following to access DBEngine:

Invoke the DBLINKENGINE define to link to DBEngine.
If you are not using DBSupport, then call DBINTERFACEVERSION to verify that your program was compiled with the same version of the DBInterface as DBEngine was.
Call the DBEngine entry point DBINITIALIZE, passing the title of the DMSII DESCRIPTION file to use.

Additional DBSupport Requirements

In addition to the requirements listed previously, you must also do the following to access DBSupport:

Put the title of the DBSupport library in a string variable and call DBSupportTitle. For example:

DBMTYPE DMR; string SupportTitle; SupportTitle := "OBJECT/DATABRIDGE/SUPPORT/BANKDB"; DMR := DBSupportTitle (SupportTitle);
Call DBSupportInit to do the following:
- Verify your program was compiled with the same version of the DBInterface as DBEngine and DBSupport were
- Specify the names of the filter, format, and transform. For example:
if DBSupportInit (DBV_VERSION, "MyAccessory:", "MYFILTER", "COMMAFORMAT", "DBTRANSFORM") NEQ DBM_OK then begin display ("Interface version mismatch"); end;

These filter, format, and transform names can be ones you created or ones predeclared in DBSupport. Refer to the Databridge Host Administrator's Guide for more information about DBGenFormat.

Accessing DBEngine Only

The following example shows how to access DBEngine only (and not DBSupport). The declarations for many of the variables used in this example are not shown.

$ SET INCLUDE_ENGINE$
$ INCLUDE "SYMBOL/DATABRIDGE/INTERFACE"

BOOLEAN   PROCEDURE   INITIALIZE;
%                     ----------
      BEGIN
      FILE     DASDL  (DEPENDENTSPECS);  % for file-equating only
      FILE     DB;

      POINTER P;

      DBLINKENGINE;

      IF DBVERSION NEQ DBV_VERSION THEN
              BEGIN
              SetMsgParam1(DBVERSION, *);
              SetMsgParam2 (DBV_VERSION, *);
              DIE (DBM_VERSION_MISMATCH, MsgParam1c MsgParam2);
              END;

      REPLACE P:FILETITLE BY DASDL.TITLE;
      DASDLTITLE := STRING (FILETITLE, OFFSET (P) - 1);

      IF DB.FILEEQUATED THEN
             BEGIN
             REPLACE P:FILETITLE BY DB.FILENAME;
             DBNAME := STRING (FILETITLE, OFFSET (P) - 1);
             END;

   WRITE_IF_ERR (DBINITIALIZE (DASDLTITLE, DBNAME));

   INITIALIZE := NOT DONE; % no fatal errors

   END INITIALIZE;

DBEngine Entry Points

Use the DBEngine entry points to request information from DBEngine.

The table below summarizes the DBEngine entry points and their functions, and each of these points is explained in detail later in this chapter. The Entry Point column in this table contains the name of the entry point, the Type column indicates what type of procedure the entry point is, and the Description column describes what the entry point does. See Entry Point Procedure Values for an explanation of the various procedure types and the values they return. DBMTYPE values are listed in the API file (SYMBOL/DATABRIDGE/INTERFACE) and the Databridge Host Administrator's Guide.

Entry Point	Type	Description
DBATTRIBUTE	DBMTYPE	Returns a specified file attribute value of a disk file
DBAUDITATTRIBUTE	DBMTYPE	Returns a specified file attribute value of an audit file
DBAUDITMEDIUM	DBMTYPE	Specifies where DBEngine looks for audit files
DBAUDITPACK	DBMTYPE	Specifies an alternate audit pack location
DBAUDITPREFIX	DBMTYPE	Specifies a non-standard file name prefix for audit files
DBAUDITSOURCE	DBMTYPE	Specifies where to access remote audit files
DBAUDITSOURCEX	DBMTYPE	Specifies how to access remote audit files
DBCANCELWAIT	DBMTYPE	Cancels the wait (set by DBWAIT) for audit files to become available
DBCLOSEDATASET	DBMTYPE	Closes a dataset previously opened with DBOpenDataset.
DBCOMMENT	DBMTYPE	Copies the DASDL comment associated with a structure or data item into the caller's array
DBCOMPILESUPPORT	DBMTYPE	Compiles the DBSupport library
DBDATABASEINFO	DBMTYPE	Returns information about the database, such as the update level and timestamp
DBDATASETINFO	DBMTYPE	Returns layout information about the data set or remap as described in the DATASET_INFO array
DBDATASETNAME	DBMTYPE	Returns the structure name for the specified structure index
DBDATASETNUMS	DBMTYPE	Returns an array containing the structure numbers of all the data sets and remaps in the logical database
DBDATASETS	DBMTYPE	Lists the data set names, structure numbers, and other information about each data set
DBDATASETVFINFO	DBMTYPE	Loads the DATASET_INFO array with information about the data set, remap, or set
DBDATETIME	DBMTYPE	Converts a timestamp from TIME (6) format to a binary format time and date
DBDESELECT	DBMTYPE	Deselects a data set previously selected with DBSELECT so that it is not processed by subsequent DBREADs or DBWAITs
DBDIRECTORYSEARCH	DBMTYPE	Returns the file names within a specified directory and its subdirectories
DBDISPLAYFAULT	DBMTYPE	Displays a message describing a program fault, such as INVALID INDEX
DBDISPLAYMSG	DBMTYPE	Displays the error message associated with the result code returned from the call to the previous entry point
DBENGINEMISSINGENTRYPOINT	STRING	Returns the name of the first entry point missing from the library code file that the Accessory expected to be present based on the interface file
DBFAMILYINFO	DBMTYPE	Returns the date, time, and system serial number when the family was created.
DBFILEATTRIBUTE	DBMTYPE	Allows an Accessory to retrieve file attribute information about any file
DBGETFIRSTQPT	DBMTYPE	Finds the first quiet point in the audit trail beginning with the Audit File Number and Audit Block Serial Number given in STATE_INFO. STATE_INFO is updated to reflect the audit location of the quiet point.
DBINITFILTER	DBMTYPE	(not used)
DBINITIALIZE	DBMTYPE	Initializes DBEngine by specifying the title of the database DESCRIPTION file
DBINTERFACEVERSION	DBMTYPE	Validates the Accessory's DBInterface version against DBEngine's DBInterface version and returns an error if they are incompatible
DBIOERRORTEXT	DBMTYPE	Copies the error text describing the READ/WRITE result value into the caller's array
DBIORESULTTEXT	DBMTYPE	Copies the error text describing the I/O result value into the caller's array NOTE: This entry point is now called DBOPENRESULTTEXT.
DBITEMINFO	DBMTYPE	Returns information for a data item in a data set
DBITEMNUMINFO	DBMTYPE	Retrieves information about a single data item
DBKEYDATAREMAP	DBMTYPE	Enumerates the items of the KEY DATA for a set using the item descriptions of the designated data set or remap
DBKEYINFO	DBMTYPE	Returns information for each key item in a set
DBKEYINFOREMAP	DBMTYPE	Enumerates key items in a set using item information in a remap
DBKEYS	DBMTYPE	Lists the key items in the specified set
DBKEYSREMAP	DBMTYPE	Enumerates key items in a set using the item numbers of the specified data set of a remap
DBLAYOUT	DBMTYPE	Lists the data items in the specified data set
DBLIMITTASKNAME	DBMTYPE	Sets the processing limit task name
DBLIMITTIMESTAMP	DBMTYPE	Sets the processing limit timestamp
DBLINKS	DBMTYPE	Enumerates LINK items in a data set
DBMAKETIMESTAMP	DBMTYPE	Converts a date and time to a timestamp in TIME (6) format
DBMAXRECORDS	DBMTYPE	Returns the estimated maximum number of records currently in a data set
DBMAXRECORDSVF	DBMTYPE	Returns the estimated maximum number of records currently in a data set
DBMESSAGE	DBMTYPE	Copies the error message associated with a DBMTYPE value to the caller's array
DBMODIFIES	DBMTYPE	Specifies whether data set record updates should be returned as a DELETE/CREATE pair or as an update
DBMODIFYTIMESTAMP	DBMTYPE	Increments or decrements a timestamp by days, hours, minutes, and/or seconds
DBNULL	DBMTYPE	Returns the NULL value for the specified data item
DBNULLRECORD	DBMTYPE	Returns a record with all data items NULL
DBOLDESTAUDITLOC	DBMTYPE	Finds the oldest audit location on disk
DBOPENAUDIT	DBMTYPE	Opens an audit file and returns audit file information
DBOPENRESULTTEXT	DBMTYPE	Copies the error text describing the OPEN/CLOSE/RESPOND result value into the caller's array
DBPARAMETERS	DBMTYPE	Specifies various run-time processing parameter values
DBPRIMARYSET	DBMTYPE	Returns the structure number of the NO DUPLICATES set having the fewest key items for the given data set
DBPRIVILEGED	BOOLEAN	Indicates whether or not the caller is a privileged program or running under a privileged usercode
DBPUTMESSAGE	DBMTYPE	Sets the DBMESSAGE parameter values
DBREAD	DBMTYPE	Receives a transaction group (up to the next quiet point) of changes to data set records from the audit trail
DBREADAUDITREGION	DBMTYPE	Reads the audit file region, starting with the indicated audit block serial number (ABSN) and block offset
DBREADERPARAMETER	DBMTYPE	Allows an Accessory to specify the title of the FileXtract Reader library and the parameter string that is passed to the Reader library
DBREADTRANGROUP	DBMTYPE	Receives a transaction group (up to the next quiet point) of changes to data set records from the audit trail. If a transaction group is not available, it waits for a specified number of seconds before retrying
DBRESETOPTION	DBMTYPE	Turns off DBEngine run-time options
DBSELECT	DBMTYPE	Selects a data set to be processed by a subsequent DBREAD or DBWAIT, and validates the client format level when a data set is selected for cloning
DBSELECTED	DBMTYPE	Checks to see if the specified data set has been selected
DBSETINFO	DBMTYPE	Returns information describing a set as given in the SET_INFO array
DBSETOPTION	DBMTYPE	Turns on DBEngine run-time options
DBSETS	DBMTYPE	Lists the names, structure numbers, and other information for the sets of the specified data set
DBSETSINFO	DBMTYPE	Returns information for each set of a given data set
DBSPLITTIMESTAMP	DBMTYPE	Converts a timestamp from TIME (6) format to a date and time in yyyy, mm, dd, hh, mn, ss form
DBSPLITTIME60	DBMTYPE	Splits a timestamp in TIME (60) format into separate components
DBSTATEINFOTODISPLAY	INTEGER	Converts state information into readable format
DBSTATISTICS	DBMTYPE	Returns statistics for the specified category NOTE: To accumulate statistics, DBEngine must be compiled with `$ SET STATS`, which is available as OBJECT/DATABRIDGE/ENGINE/STATS.
DBSTRIDX	DBMTYPE	Returns the structure index for a selected data set
DBSTRNUM	DBMTYPE	Returns the structure number for the specified structure name
DBSTRUCTURENAME	DBMTYPE	Returns a structure name for a DMSII structure
DBSUBSETSINFO	DBMTYPE	Enumerates information for each subset of a given data set
DBSWITCHAUDIT	DBMTYPE	Forces an audit file switch
DBTIMESTAMPMSG	DBMTYPE	Converts the timestamp from TIME (6) format to the following form: month, day, year @ hh:mm:ss
DBUPDATELEVEL	DBMTYPE	Returns the database update level and timestamp
DBVERSION	REAL	Returns the version number of the API file (SYMBOL/DATABRIDGE/INTERFACE) that DBEngine was compiled against.
DBWAIT	DBMTYPE	Receives the transaction group (up to the next quiet point) of changes to data set records from the audit trail If a transaction group is not available, it waits for a specified number of seconds before retrying.
DBWHEREDASDL	DBMTYPE	Returns the DASDL source expression associated with the WHERE clause of an automatic subset or the SELECT cause of a remap
DBWHERETEXT	DBMTYPE	Returns the ALGOL source code fragment associated with the WHERE clause of an automatic subset or the SELECT clause of a remap

DBATTRIBUTE

This entry point returns a specified file attribute value of a disk file. Contact Micro Focus Customer Care for additional information.

DBAUDITMEDIUM

This entry point allows an Accessory to specify where DBEngine looks for audit files and whether to look for primary, secondary, or both.

Declaration

DBMTYPE procedure DBAuditMedium (AuditMedium,AuditType);

Input	Type	Definition
AUDITMEDIUM	INTEGER	The medium on which to look for the audit file. Possible values are as follows: DBV_AM_ORIGPACK—Tells the Accessory to look on the original pack(s) DBV_AM_ALTERNATE—Tells the Accessory to look on the alternate pack as specified by DBAUDITPACK If this parameter is invalid, DBEngine returns a DBM_BAD_AUDMED (110) error
AUDITTYPE	INTEGER	The type of audit file for which to look, such as primary or secondary Possible values are as follows: DBV_AM_NEITHER—Tells the Accessory not to look for audit files on the source DBV_AM_PRIMARY—Tells the Accessory to look only for the primary audit file DBV_AM_SECONDARY—Tells the Accessory to look only for the secondary audit file DBV_AM_BOTH—Tells the Accessory to look for both the primary and secondary audit files See DBAUDITMEDIUM Parameters for more information about these values. If this parameter is invalid, DBEngine returns a DBM_BAD_AUDTYPE (111) error

DBAUDITATTRIBUTE

This entry point returns a specified file attribute value of an audit file, if the specified attribute number is VALUE (TITLE), VALUE (FILENAME), or VALUE (FAMILYNAME).

This function looks for the audit file first on the Alternate pack and then on the original audit pack. This allows DBEnterprise to access audit files in either location. Contact Micro Focus for additional information.

DBAUDITPACK

This entry point specifies where audit files may be located. DBEngine looks on the pack specified by the DMSII control file, the pack specified by DBAUDITPACK, or both, depending on DBAUDITMEDIUM.

Declaration

Input	Type	Definition
PACKNAME	STRING	The name of the pack where DBEngine should look for normal DMSII audit files

DBAUDITPREFIX

This entry point can specify a non-standard file name prefix for audit files. Normally, the prefix for audit files is:

(databaseusercode)databasename

Using the DBAuditPrefix entry point, the prefix can have a different usercode, different first node, and/or additional nodes.

This entry point specifies where audit files may be located. DBEngine looks on the pack specified by the DMSII control file, the pack specified by DBAUDITPACK, or both, depending on DBAUDITMEDIUM.

If the prefix is badly formed, the entry point will return DBM_BAD_PREFIX (137) (Invalid audit file prefix: ' prefix ')

DBAUDITSOURCE

This entry point specifies where to access remote audit files.

Declaration

Input	Type	Definition
HOST	STRING	The name or the IP address of the DBServer host where the audit files are located
SOURCENAME	STRING	A source identifier that is the name of a SOURCE in the DBServer parameter file
PROTOCOL	INTEGER	The network protocol value, such as TCPIP See Network Protocol Values for possible values.
PORT	INTEGER	The port number that matches PORT in the DBServer parameter file

DBAUDITSOURCEX

This entry point specifies how to access remote audit files. This entry point is identical to DBAUDITSOURCE except that the PORTNAME is a string rather than a number to allow names for BNA and HLCN ports.

Declaration

DBMTYPE procedure DBAuditSourceX (Host, SourceName, Protocol, PortName);

Input	Type	Definition
HOST	STRING	The name or the IP address of the DBServer host where the audit files are located
SOURCENAME	STRING	A source identifier that is the name of a SOURCE in the DBServer parameter file
PROTOCOL	INTEGER	The network protocol value, such as TCPIP See the DBV_NET_xxx values in Network Protocol Values for possible values.
PORTNAME	STRING	The port name, such as 3000 or BNA350 This value must match the PORT in the DBServer parameter file.

DBCANCELWAIT

This entry point cancels the wait for more audit files to become available via DBWAIT or DBREADTRANGROUP.

Declaration

DBMTYPE procedure DBCANCELWAIT;

DBCLOSEDATASET

This entry point closes a dataset previously opened with DBOpenDataset. Contact Micro Focus for additional information.

DBCOMMENT

This entry point copies the DASDL comment associated with a structure or data item into the caller's array. These comments must have been declared in the DASDL using the double-quote Declaration. For example:

ACCT-YTD-INT "year-to-date interest" NUMBER (11, 2);

Declaration

DBMTYPE procedure DBComment (StrNum, ItemNum, pText, Len);

Input	Type	Definition
STRNUM	REAL	The structure number of the structure you are requesting. Since no comment can be associated with the global record, a structure number of 1 is invalid.
ITEMNUM	REAL	The item number of the data item you are requesting. Use 0 to request the comment associated with a data set, set, or remap.
PTEXT	POINTER	Destination for the comment text

Output	Type	Definition
LEN	REAL	The length, in bytes, of the text copied into PTEXT Possible values are as follows: If the array is too short, no text is copied, but LEN is set to the needed length, and the procedure value is DBM_SHORT_ARRAY (23). If no text is associated with the structure, such as when the structure number is a data set, set, or manual subset, the procedure returns DBM_OK, and LEN is set to 0.

DBCOMPILESUPPORT

This entry point compiles the DBSupport library. If an Accessory determines that DBSupport needs to be compiled with the current DESCRIPTION file, it can call this entry point. Any local patches to DBSupport are ignored if they are not specified in the DBGenFormat parameter file.

If DBEngine determines that a DBSupport library already exists for the desired update level, it copies the new title of the DBSupport library into the caller's array and then returns immediately without actually compiling it.

Declaration

DBMTYPE procedure DBCompileSupport (pTitle);

Input	Type	Definition
PTITLE	POINTER	The pointer to the title of the DBSupport library

Output	Type	Definition
PTITLE	VALUE	The new title of the DBSupport library (the update level node to be appended to the file name)

DBDATABASEINFO

This entry point returns layout information about the database, such as the update level and update timestamp.

Declaration

DBMTYPE procedure DBDATABASEINFO (DATABASE_INFO);

Output	Type	Definition
DATABASE_INFO	ARRAY	An array of information that describes the database. For a description of the array, see DATABASE_INFO Layout.

DBDATASETINFO

This entry point returns layout information about a data set or remap. If the data set has any links, DBDATASETINFO sets the DATASET_INFO [DI_LINKS] = 1.

Declaration

DBMTYPE procedure DBDATASETINFO (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set or remap
CALLBACK	BOOLEAN	The procedure that receives the data set information

BOOLEAN PROCEDURE CALLBACK

This is the procedure that receives information about the data set. For fixed-format data sets, this procedure is called once. For variable-format data sets, this procedure is called once for each format type.

Declaration

boolean procedure Callback (pDatasetName, Len, DATASET_INFO);

Parameter	Type	Definition
P_DATASETNAME	POINTER	The pointer to a data set name The caller must copy the actual data set name into its own local memory.
LEN	REAL	The length of the data set name
DATASET_INFO	ARRAY	Information about the data set For a description of the array, see DATABASE_INFO Layout.

DBDATASETNAME

This entry point returns a data set name corresponding to the specified structure index.

Declaration

DBMTYPE procedure DBDATASETNAME (StrIdx, pDSName,Len);

Input	Type	Definition
STRIDX	REAL	The structure index from UPDATE_INFO [UI_STRIDX]
P_DSNAME	POINTER	The pointer to the array that is to receive the data set name

Output	Type	Definition
LEN	REAL	The length of the data set name in bytes

DBDATASETNUMS

This entry point returns an array that contains the structure numbers of all of the data sets (except virtual data sets) and remaps in the logical database.

Declaration

DBMTYPE procedure DBDatasetNums (DSNums, LastIdx);

Input	Type	Definition
DSNUMS	ARRAY	Contains the structure numbers of all data sets (except virtual data sets) and remaps in the (logical) database.
LASTIDX	REAL	The subscript of the last valid entry in the DSNUMS array (above). If the array is too small, it is automatically resized to the appropriate size.

DBDATASETS

This entry point provides data set names and their structure numbers. Use DBDATASETS to generate a pointer to a data set name, the data set name length, and an array that contains information about the data set, such as its structure number.

Declaration

DBMTYPE procedure DBDATASETS (Callback);

Input	Type	Definition
CALLBACK	BOOLEAN	The procedure that receives data set information

BOOLEAN PROCEDURE CALLBACK

For fixed-format data sets, DBDATASETS calls this procedure once. For variable-format data sets, DBDATASETS calls this procedure once for each format (record) type.

Declaration

boolean procedure Callback (pDatasetName, Len, DATASET_INFO);

Parameter	Type	Definition
P_DATASETNAME	POINTER	Points to a data set name The caller must copy the actual data set name into its own local memory
LEN	REAL	The length of the data set name
DATASET_INFO	ARRAY	Information about the data set For a description of the array, see DATABASE_INFO Layout.

DBDATASETVFINFO

This entry point loads the DATASET_INFO array with information about the data set or remap, according to the record type number.

Declaration

DBMTYPE procedure DBDatasetVFInfo (DSStrNum, RecType, DATASET_INFO);

Input	Type	Definition
DSSTRNUM	REAL	Structure number of the data set or remap
RECTYPE	REAL	Record type number (0 for fixed format)

Output	Type	Definition
DATASET_INFO	ARRAY	Information about the data set as contained in the DATASET_INFO array See DATABASE_INFO Layout for a description of the array.

DBDATETIME

This entry point converts the timestamp in TIME (6) format to a binary format date and time.

Declaration

DBMTYPE procedure DBDATETIME (Timestamp, YYYYMMDD, HHMMSS);

Input	Type	Definition
TIMESTAMP	REAL	TIME (6) timestamp

Output	Type	Definition
YYYYMMDD	INTEGER	The date in binary format
HHMMSS	INTEGER	The time in binary format

DBDESELECT

This entry point deselects a data set that was previously selected by DBSELECT so that it is not processed by subsequent DBREADs or DBWAITs.

Declaration

DBMTYPE procedure DBDESELECT (StrIdx);

DBDIRECTORYSEARCH

This entry point returns the file names within a specified directory and its subdirectories. DBEngine calls the Accessory-supplied callback procedure with the name of each file. This function will translate the filename or directory name to UPPERCASE, avoiding error DBM0125.

Declaration

DBMTYPE procedure DBDirectorySearch (pDirName, FilenameHandler);

Input	Type	Definition
PDIRNAME	POINTER	Pointer to the period-terminated directory name NOTE: Do not include /= in the name. For example, to get a list of files in SUMLOG/1234/= ON SYSTEM, use the following: `SUMLOG/1234`
`ON SYSTEM.`

BOOLEAN PROCEDURE CALLBACK

This procedure receives the name of a file in the specified directory and is called once for each file. If the procedure returns TRUE (no more file names are available), DBEngine aborts the search.

Declaration

boolean procedure FilenameHandler (pFilename, FilenameLen);

Parameter	Type	Definition
PFILENAME	POINTER	Pointer to a file name in the directory
FILENAMELEN	INTEGER	Length of the file name in bytes

DBDISPLAYFAULT

This entry point displays a message describing a program fault, such as INVALID INDEX, along with the line number in the application program that caused the fault.

The sample reformatting routine (SYMBOL/DATABRIDGE/SAMPLE/REFORMAT) captures and identifies errors and uses this entry point to help sites debug their reformatting routines.

Declaration

DBMTYPE procedure DBDisplayFault (Prefix, FaultNbr, pFaultHistory);

Input	Type	Definition
PREFIX	STRING	The prefix of the message to be displayed This prefix is usually the program name followed by a colon. Example: `DBSpan:`
FAULTNBR	REAL	The fault number returned by the ALGOL ON statement
PFAULTHISTORY	POINTER	The stack history returned by the ALGOL ON statement

DBDISPLAYMSG

This entry point displays the error message associated with the result code returned from the call to the previous entry point.

Declaration

DBMTYPE procedure DBDisplayMsg (DBMResult);

Input	Type	Definition
DBMRESULT	DBMTYPE	The procedure value from a prior call to a DBEngine or DBSupport entry point

DBENGINEMISSINGENTRYPOINT

This entry point returns the name of the first entry point missing from the library code file that the Accessory expected to be present based on the interface file.

Declaration

string procedure DBENGINEMissingEntryPoint;

Example

string MissingEP;
...
MissingEP := DBENGINEMissingEntryPoint;
if MissingEP NEQ empty then
      display ("Missing DBEngine entry point " !! MissingEP);

DBFAMILYINFO

This entry point returns the date, time, and system serial number when the family was created. Contact Micro Focus Customer Support for additional information.

DBFILEATTRIBUTE

This entry point allows an Accessory to retrieve file attribute information about any file. The caller supplies the file title and a mask of desired file attributes. For example, to request the creation date and time, use the following mask:

0 & 1 [CREATIONDATEB:1] & 1 [CREATIONTIMEB:1]

DBEngine returns the values in the Attributes array, indexed by the attribute bit number. For example, to reference the creation date value after calling this entry point, use the following:

Attributes [CREATIONDATEB]

Declaration

DBMTYPE procedure DBFileAttribute (pFileTitle, AttrMask, Attributes);

Input	Type	Definition
PFILETITLE	POINTER	The pointer to the period-terminated file name. This function will translate the filename or directory name to UPPERCASE, avoiding error DBM0125.
ATTRMASK	REAL	Mask of desired file attributes See File Attribute Mask Bits for a list of attributes and their corresponding bits.

Output	Type	Definition
ATTRIBUTES	ARRAY	An array containing file attribute values

DBGETFIRSTQPT

This entry point finds the first quiet point (QPT) in the audit trail beginning with the audit file number (AFN) and ABSN given in the STATE_INFO array layout. STATE_INFO is updated to reflect the audit location of the quiet point. For a description of the STATE_INFO array layout, see STATE_INFO Layout.

Declaration

DBMTYPE procedure DBGETFIRSTQPT (STATE_INFO);

Input	Type	Definition
STATEINFO [SI_AFN]	REAL	The starting AFN
STATEINFO [SI_ABSN]	REAL	The starting ABSN This ABSN does not have to exist in the specified audit file. It simply functions as a lower bound.

Output	Type	Definition
STATEINFO [SI_AFN]	REAL	The AFN of the quiet point
STATEINFO [SI_ABSN]	REAL	The ABSN of the quiet point
STATEINFO [SI_SEG]	REAL	The segment of the quiet point
STATEINFO [SI_INX]	REAL	The word index of the quiet point
STATEINFO [SI_TIME]	REAL	The timestamp of the quiet point

DBGETINFO

This entry point returns individual values corresponding to the Info_Enginexxxx values listed in DBInterface.

Declaration

DBMTYPE procedure DBGetInfo (InfoId, InfoSelection, InfoValue);

Input	Type	Definition
InfoId	INTEGER	One of the Info_Enginexxxx or Info_Sourcexxxx values in DBInterface
InfoSelection	INTEGER	Unused

Output	Type	Definition
InfoValue	STRING	Value of the requested information

DBGETOPTION

This entry point returns the value of a Boolean run-time option. The options are named DBV_OP_xxxx and listed in DBInterface.

Declaration

DBMTYPE procedure DBGetOption (Option, Setting);

Input	Type	Definition
Option	INTEGER	One of the DBV_OP_xxxx options in DBInterface

Output	Type	Definition
Setting	BOOLEAN	Value of option: true or false

DBINITFILTER

This entry point will be removed.

DBINITIALIZE

This entry point initializes DBEngine by specifying the title of the database DESCRIPTION file (without the DESCRIPTION node). You must initialize DBEngine by calling DBINITIALIZE before you can use any of the other DBEngine API entry points that access database information either directly or indirectly. See Accessing the DBEngine and DBSupport Libraries to see what else you must do before using the DBEngine entry points.

Declaration

DBMTYPE procedure DBINITIALIZE (DBDescTitle, DB);

Input	Type	Definition
DBDESCTITLE	STRING	The title of the database DESCRIPTION file (without the DESCRIPTION node) Example: `"(PROD)PAYROLLDB ON SYSPACK."`
DB	STRING	Optional. The name of the logical or physical database associated with the DESCRIPTION file (the database to which you want access) If a logical database is specified, the Accessory cannot retrieve layout or update information for any data sets or remaps outside of the specified logical database.

Output	Type	Definition
DB	STRING	If you leave this parameter empty on input, the program returns the name of the physical database. See the Input parameter definition for DB above.

DBINTERFACEVERSION

This entry point validates the Accessory's DBInterface version against DBEngine's DBInterface version and returns a DBM_VER_MISMATCH (115) error if they are incompatible.

Note

If you are using DBSupport, you do not need to call DBINTERFACEVERSION explicitly because your call to DBSupportInit automatically calls DBINTERFACEVERSION to validate the DBInterface version of the Accessory against DBEngine.

For related information, see DBINITIALIZESUPPORT.

Declaration

DBMTYPE procedure DBInterfaceVersion (AccessoryVersion, AccessoryID);

Input	Type	Definition
ACCESSORYVERSION	REAL	The version of DBInterface that was used to compile the Accessory
(DBV_VERSION)
ACCESSORYID	STRING	A descriptive string inserted in an error message that identifies the Accessory Example: `DBSpan:`

DBIOERRORTEXT

This entry point copies error text describing the READ/WRITE result value into the caller's array. The READ/WRITE result value is a Boolean value returned from a READ or WRITE function that was passed to the entry point by the calling program.

Declaration

procedure DBIOErrorText (IOResult, pText, TextLen);

Input	Type	Definition
IORESULT	BOOLEAN	Result value from the READ or WRITE
PTEXT	POINTER	Destination for error text

Output	Type	Definition
TEXTLEN	INTEGER	Length of the error text

DBIORESULTTEXT

This entry point is now called DBOPENRESULTTEXT (see DBOPENRESULTTEXT), and it is recommended that you use DBOPENRESULTTEXT. However, for compatibility, the name DBIORESULTTEXT still works.

DBITEMINFO

This entry point returns the ITEM_INFO array layout for a data item in a data set or remap. The only difference between this entry point and DBITEMNUMINFO is that DBITEMNUMINFO specifies the data item by name rather than number.

Declaration

DBMTYPE procedure DBITEMINFO (DSStrNum, RecType, ItemName, ITEM_INFO);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set or remap that contains the data item
RECTYPE	REAL	The record type number (0 for fixed format)
ITEMNAME	STRING	The name of the data item for which you are requesting the array

Output	Type	Definition
ITEM_INFO	ARRAY	The information about the data item For a description of the array, see ITEM_INFO Array Layout.

DBITEMNUMINFO

This entry point retrieves the ITEM_INFO array layout for a single data item. The only difference between this entry point and DBITEMINFO is that DBITEMINFO specifies the data item by number rather than name.

Declaration

DBMTYPE procedure DBITEMNUMINFO (DSStrNum, ItemNum, ITEM_INFO);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set or remap that contains the data item
ITEMNUM	INTEGER	The number of the data item for which you want information

Output	Type	Definition
ITEM_INFO	ARRAY	The information about the data item For a description of the array, see ITEM_INFO Array Layout.

DBKEYDATAREMAP

This entry point enumerates the items of the KEY DATA for a set using the item descriptions of the designated data set or remap. If the set does not have any KEY DATA, it returns the following DBM_NO_KEYDATA (122) message:

setname does not have key data

KEY DATA is not the same as the KEY of a set. The KEY determines the order of the set entries, while KEY DATA contains additional data items that are not part of the KEY.

Input	Type	Definition
SETSTRNUM	REAL	The structure number of the set whose key items are to be returned
REMAPSTRNUM	REAL	The structure number of the data set or remap that contains the KEY DATA items If REMAPSTRNUM = 0, the original data set is assumed. Item numbers can very depending on whether the data set or remap is used.
CALLBACK	BOOLEAN	The procedure that receives information for each KEY DATA item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the KEY DATA item.

Output	Type	Definition
ITEM_INFO	ARRAY	The information about the data item For a description of the array, see ITEM_INFO Array Layout.

DBKEYINFO

This entry point returns the key items in a set.

Declaration

DBMTYPE procedure DBKEYINFO (SetStrNum, Callback);

Input	Type	Definition
SETSTRNUM	REAL	The structure number of the set whose key items are to be returned
CALLBACK	BOOLEAN	The procedure that receives information for each key item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the key item.

Declaration

boolean procedure Callback (ITEM_INFO);

Parameter	Type	Definition
ITEM_INFO	ARRAY	An array of information that describes the key item ITEM_INFO Array Layout

DBKEYINFOREMAP

This entry point lists items in a set using item information in a remap. The key items have the item number, name, and so on, as they are known in the remap.

Declaration

DBMTYPE procedure DBKeyInfoRemap (SetStrNum, RemapStrNum, Callback);

Input	Type	Definition
SETSTRNUM	REAL	The structure number of the desired set
REMAPSTRNUM	REAL	The structure number of the remap (or data set) If this value is set to 0, the original data set is assumed.
CALLBACK	BOOLEAN	The procedure that receives information for each key item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the key item.

Declaration

boolean procedure Callback (ITEM_INFO);

Parameter	Type	Definition
ITEM_INFO	ARRAY	An array of information describing the key item For a description of the array, see ITEM_INFO Array Layout.

DBKEYS

This entry point returns the key items in a set.

Declaration

DBMTYPE procedure DBKEYS (SetStrNum, Callback);

Input	Type	Definition
SETSTRNUM	REAL	The structure number of the set whose keys are to be returned
CALLBACK	BOOLEAN	The procedure that receives information for each key item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the key item.

Declaration

boolean procedure Callback (ItemNum, DESCENDING);

Parameter	Type	Definition
ITEMNUM	INTEGER	The item number of the key, as in ITEM_INFO [II_ITEM_NUM]
DESCENDING	BOOLEAN	Returns a value of TRUE if the item is a descending key

DBKEYSREMAP

This entry point lists key items in a set using the item numbers of the specified data set or remap. If a key item is not found in the specified remap, the procedure returns the error DBM_BAD_ITEMNUM (31).

Declaration

DBMTYPE procedure DBKeysRemap (SetStrNum, RemapStrNum, Callback);

Input	Type	Definition
SETSTRNUM	REAL	The structure number of the desired set
REMAPSTRNUM	REAL	The structure number of the data set or remap containing the key items The item numbers can vary depending on whether the data set or the remap is used. If this value is set to 0, the original data set is assumed.
CALLBACK	BOOLEAN	The procedure that receives information for each key item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the key items.

Declaration

boolean procedure Callback (ItemNum, Descending);

Parameter	Type	Definition
ITEMNUM	INTEGER	The item number, as in ITEM_INFO [II_ITEM_NUM]
DESCENDING	BOOLEAN	TRUE if the item is a descending key

DBLAYOUT

This entry point returns the ITEM_INFO array layout for a data items in a data set.

Declaration

DBMTYPE procedure DBLAYOUT (DSStrNum, RecType, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the desired data set
RECTYPE	REAL	The record type number (0 for fixed format)
CALLBACK	BOOLEAN	The procedure that receives information for each data item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about each data item.

Declaration

boolean procedure Callback (ITEM_INFO);

Parameter	Type	Definition
ITEM_INFO	ARRAY	Information describing each data item For a description of the array, see ITEM_INFO Array Layout.

Example

The following example calls DBLAYOUT:

ARRAY ITEMSINFO [0:99, 0:II_ENTRY_SIZE - 1];
BOOLEAN PROCEDURE GETITEMINFO (DIINFO);
        ARRAY DIINFO [0];
        BEGIN
        REAL IDX;

        IDX := DIINFO [II_ITEM_NUM];
        REPLACE POINTER (ITEMSINFO [IDX, 0], 0) BY
            POINTER (DIINFO, 0) FOR II_ENTRY_SIZE_WORDS;
        GETITEMINFO := TRUE;
        END GETITEMINFO;

REAL DSSTRNUM;
DSSTRNUM := 2;
DBLAYOUT (DSSTRNUM, 0, GETITEMINFO);

DBLIMITTASKNAME

This entry point sets the processing limit task name. When DBREADTRANGROUP reaches the specified task name in the audit trail, it stops processing at the next quiet point after the task's database close (if the type is AFTER) or the quiet point before the task's database open (if the type is BEFORE).

Declaration

DBMTYPE procedure DBLIMITTASKNAME (TaskName, LimitType);

DBLIMITTIMESTAMP

This entry point sets the processing limit timestamp. When DBREADTRANGROUP reaches the specified time in the audit trail, it stops processing at the next quiet point (if the type is AFTER) or the previous quiet point (if the type is BEFORE).

Declaration

DBMTYPE procedure DBLIMITTIMESTAMP (Timestamp, LimitType);

Input	Type	Definition
TIMESTAMP	REAL	The limiting timestamp in TIME (6) format
LIMITTYPE	INTEGER	The type of limit, either BEFORE or AFTER the specified timestamp Possible values are as follows: DBV_LIMIT_UNSPECIFIED—Indicates that no limit type is specified DBV_LIMIT_BEFORE—Tells the Accessory to stop at the QPT before the limit DBV_LIMIT_AFTER—Tells the Accessory to stop at the QPT after the limit

DBLINKS

This entry point returns information about link items in a data set. The DBEngine option LINKS must be true, and the data set must be STANDARD, fixed-format, and unsectioned.

Declaration

DBMTYPE procedure DBLinks (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the data set. This procedure is called once for each link item.

Declaration

boolean procedure Callback (ITEM_INFO);

Parameter	Type	Definition
DSSTRNUM	BOOLEAN	The array of information describing the link item For a description of the array, see ITEM_INFO Array Layout.

DBMAKETIMESTAMP

This entry point converts a date and time to a timestamp in TIME(6) form.

Declaration

DBMTYPE procedure DBMAKETIMESTAMP (Year, MM, DD, HH, MN, SS, TS);

Input	Type	Definition
YEAR	INTEGER	The year in four digits, 1970–2035
MM	INTEGER	The month in two digits, 1–12
DD	INTEGER	The day in two digits, 1–31
HH	INTEGER	The hour in two digits, 0–23
MN	INTEGER	The minute in two digits, 0–59
SS	INTEGER	The second in two digits, 0–59

Output	Type	Definition
TS	REAL	The timestamp in TIME (6) form

DBMAXRECORDS

This entry point returns the estimated maximum number of records that are currently in the data set. The estimate is computed from the size of the file and the size of a fixed-format record. The actual number of records could be anywhere from 0 to the MAXRECORDS value.

Declaration

DBMTYPE procedure DBMAXRECORDS (DSStrNum, MaxRecords);

Input	Type	Definition
DSSTRNUM	INTEGER	The DMSII structure number of the data set

Output	Type	Definition
MAXRECORDS	INTEGER	The estimated maximum number of records in the data set

DBMAXRECORDSVF

This entry point estimates the maximum number of records (of a certain record type) a data set can potentially hold. When making this estimate, the procedure assumes that all of the records in the data set are the record type you specified.

If the data set contains only fixed-format records (record type 0), DBMAXRECORDSVF returns the same value that DBMAXRECORDS returns.

The estimates returned for data sets containing variable-format records are smaller than those for fixed-format data sets since variable-format records are larger.

Declaration

DBMTYPE procedure DBMaxRecordsVF (DSStrNum, RecType, MaxRecords);

Input	Type	Definition
DSSTRNUM	INTEGER	The data set structure number
RECTYPE	INTEGER	The record type number (0 for fixed format)

Output	Type	Definition
MAXRECORDS	INTEGER	The estimated maximum number of records of the specified record type in the data set

DBMESSAGE

This entry point copies the text that describes the error indicated in the DBM_RESULT code field to the caller's array.

Declaration

DBMTYPE procedure DBMESSAGE (DBMResult, pMessText, MessLen);

Input	Type	Definition
DBM_RESULT	DBMTYPE	The procedure value from a prior call to an entry point
P_MESSTEXT	POINTER	The pointer to the caller's array where the message text is copied NOTE: The caller must ensure that the array is large enough.

Output	Type	Definition
MESSLEN	REAL	The length of the output message in bytes

DBMODIFIES

This entry point specifies whether data set record modifications (updates) should be returned as a DELETE/CREATE pair instead of as an update. This is typically necessary for data sets that allow key changes.

The value of ALLOWED is the default value for all selected data sets. See DBSELECT and the SI_MODIFIES field in the STATE_INFO array (listed under STATE_INFO Layout for information on setting this option for a single data set. DBRESETOPTION can also be used to set this option.

Declaration

DBMTYPE procedure DBMODIFIES (Allowed);

Input	Type	Definition
ALLOWED	BOOLEAN	One of the following values: TRUE—Modifies (updates) are returned as modifies FALSE—Modifies (updates) are converted to a DELETE/CREATE pair

DBMODIFYTIMESTAMP

This entry point increments or decrements a timestamp by days, hours, minutes, and/or seconds. If the adjustment is negative (as indicated by a negative number, such as -3), the timestamp is decremented.

Declaration

DBMTYPE procedure DBMODIFYTIMESTAMP (Days, Hours, Minutes, Seconds, TS);

Input	Type	Definition
DAYS	INTEGER	The number of days adjustment
HOURS	INTEGER	The number of hours adjustment
MINUTES	INTEGER	The number of minutes adjustment
SECONDS	INTEGER	The number of seconds adjustment
TS	REAL	The original timestamp in TIME (6) format

Output	Type	Definition
TS	REAL	The modified timestamp in TIME (6) format

DBNULL

This entry point returns a NULL value for a given data item.

Declaration

DBMTYPE procedure DBNULL (DSStrNum, ItemNum, NullVal);

Input	Type	Definition
DSSTRNUM	REAL	The DMSII structure number of the data set or remap containing the data item
ITEMNUM	REAL	The DMSII data item number, as returned in ITEMINFO [II_ITEM_NUM] For a description of the array, see ITEM_INFO Array.

Output	Type	Definition
NULLVAL	ARRAY	The binary image of the data item's NULL value The caller must ensure that the array is large enough to hold the NULL value. If it is too short, DBEngine resizes it so that it is just large enough.

DBNULLRECORD

This entry point returns a record with all data items NULL.

Declaration

DBMTYPE procedure DBNULLRECORD (DSStrNum, RecType, NullRec);

Input	Type	Definition
DSSTRNUM	INTEGER	The DMSII structure number of the data set or remap
RECTYPE	INTEGER	The record type number (0 for fixed format)

Output	Type	Definition
NULLREC	ARRAY	The binary image of a data set record with all the data items set to NULL

DBOLDESTAUDITLOC

This entry point finds the oldest audit location on disk, searching among audit files that have the same update level as the current DESCRIPTION file. An audit location is a set of values that define a specific position in the audit trail. DBEngine starts with the current audit file and works backwards until it cannot find an earlier audit file. Then it retrieves the first audit location in that file. For example, suppose the current audit file is 100 and the following audit files are on disk: 89–92 and 96–100. DBOLDESTAUDITLOC returns the first audit location in audit file 96.

Declaration

DBMTYPE procedure DBOLDESTAUDITLOC (AFN, ABSN, Seg, Inx);

Output	Type	Definition
AFN	REAL	The audit file number
ABSN	REAL	The audit block serial number
SEG	REAL	The segment number
INX	REAL	The word index within the audit block

DBOPENAUDIT

This entry point opens an audit file and returns audit file information.

Declaration

DBMTYPE procedure DBOpenAudit (AFN, AUDIT_INFO);

Input	Type	Definition
AFN	REAL	The number of the audit file to be opened

Output	Type	Definition
AUDIT_INFO	ARRAY	Information about the audit file For a description of the array, see AUDIT_INFO Layout.

DBOPENRESULTTEXT

Note

This entry point replaces the DBIORESULTTEXT entry point; however, you can still use DBIORESULTTEXT.

This entry point returns the error or warning message associated with an I/O result code from an OPEN, CLOSE, or RESPOND, and it copies the text describing the I/O result value into the caller's array.

Declaration

procedure DBOpenResultText (OpenResult, pText, TextLen);

Input	Type	Definition
OPENRESULT	INTEGER	The I/O result value from the OPEN, CLOSE, or RESPOND
PTEXT	POINTER	The destination array for the error text

Output	Type	Definition
TEXTLEN	INTEGER	The length of the error text

DBPARAMETERS

This entry point allows the client to specify various run-time processing parameter values, such as the COMMIT frequency and maximum number of WORKER tasks during a clone.

Declaration

DBMTYPE procedure DBParameters (ParamType, ParamValue);

Input	Type	Definition
PARAMTYPE	REAL	The processing parameter type Possible values are as follows: DBV_CONCURR_EXTR—Specifies the number of maximum concurrent extracts DBV_TG_BLOCKS—Specifies the number of audit blocks per transaction group DBV_TG_UPDATES—Specifies the number of updates per transaction group DBV_TG_ELAPSED--Specifies the elapsed time per transaction group DBV_TG_TRANS--Specifies the number of transactions per transaction group DBV_THREADS--Specifies the maximum number of DBEnterprise threads to use during cloning For more information on these values, see DBPARAMETERS Processing Parameter Types.
PARAMVALUE	REAL	The processing parameter value If the value is less than 0, the entry point discards the change. Set the value to 0 to disable the processing parameter.

DBPRIMARYSET

This entry point returns the structure number of the NODUPLICATES set that does not allow key changes and has the fewest key items for the given data set.

Declaration

DBMTYPE procedure DBPRIMARYSET (DSStrNum, SetStrNum);

Input	Type	Definition
DSSTRNUM	INTEGER	The structure number of the data set or remap

Output	Type	Definition
SETSTRNUM	INTEGER	The structure number of the set

DBPRIVILEGED

This entry point returns true if the caller is a privileged program or running under a privileged usercode. Otherwise, it returns false.

Declaration

boolean procedure DBPrivileged;

DBPUTMESSAGE

This entry point sets the DBMESSAGE parameter values. Libraries that return standard DBMTYPE values can set the message parameter values so that DBMESSAGE fills in the parameter values correctly when an Accessory requests the message text. For related information, see DBMESSAGE.

Declaration

DBMTYPE procedure DBPUTMESSAGE (Subtype, Str1, Str2, Str3, Str4);

Input	Type	Definition
Subtype	STRING	This is the message subtype.
Str1	STRING	This is additional information supplied with the error. The information supplied varies with the type of error.
STR2	STRING	This is additional information supplied with the error. The information supplied varies with the type of error.
STR3	STRING	This is additional information supplied with the error. The information supplied varies with the type of error.
STR4	STRING	This is additional information supplied with the error. The information supplied varies with the type of error.

DBREAD

This entry point receives a transaction group (up to a quiet point or super quiet point) of changes to data set records from the audit trail.

Note

The DBREAD entry point is compatible with older Accessories. Using DBREADTRANGROUP is the preferred method.

You should also be aware that you must have selected at least one data set with DBSELECT in order to use this entry point.

DBREAD defaults to committing at the first QPT after the CHECKPOINT interval specified in the DBEngine parameter file. If you want DBREAD to commit at every QPT, call DBSETOPTION (DBV_OP_QPT_GROUP). The DBSETOPTION entry point is explained in DBSETOPTION. If the next transaction group is not available, DBREAD returns immediately with an error.

Declaration

DBMTYPE procedure DBREAD (Callback);

Input	Type	Definition
CALLBACK	BOOLEAN	The callback procedure that receives information about data set record updates found in the current transaction group

BOOLEAN PROCEDURE CALLBACK

The procedure is called back for each data set record update (CREATE, DELETE, CHANGE) found in the current transaction group.

Declaration

boolean procedure Callback (Image, UPDATE_INFO);

Parameter	Type	Definition
IMAGE	ARRAY	This array contains the record image, as determined by [UI_UPDATE_TYPE] in the UPDATE_INFO layout. The [UI_UPDATE_TYPE] will be one of the following values. For more information, see Record Change Types. DBV_CREATE, DBV_DELETE, and DBV_MODIFY indicate that it is a before- or after-image. DBV_STATE indicates that state information has changed. See STATE_INFO Layout for a description of the array layout. DBV_DOC indicates that it's a DB_DOC_TYPE. See Documentation Records for the DB_DOC_TYPE value.
UPDATE_INFO	ARRAY	This array contains the description of the modification. See UPDATE_INFO Layout.

DBREADAUDITREGION

The entry point reads the audit file region, starting with the indicated ABSN and block offset. The region contains an integer that is equal to the number of audit blocks. The actual word offset of the region can be computed from NEXTREGIONOFS minus REGIONSIZE.

Declaration

DBMTYPE procedure DBReadAuditRegion (RegionABSN, RegionOfs, RegionSize, Region, NextRegionABSN, NextRegionOfs);

Input	Type	Definition
REGIONABSN	INTEGER	The ABSN of the first block in the region
REGIONOFS	INTEGER	The file-relative word offset of the first block in the region A -1 indicates that the value is unknown.
REGIONSIZE	INTEGER	Maximum size (in words) of the region to be returned

Output	Type	Definition
REGION	ARRAY	The buffer containing the audit region
NEXTREGIONABSN	INTEGER	ASBN of the first block in the next region (that is, following the region returned in the REGION array)
NEXTREGIONOFS	INTEGER	The file-relative word offset of the next region (that is, following the region returned in the REGION array)
REGIONSIZE	INTEGER	The size (in words) of the region returned in the REGION array

DBREADERPARAMETER

This entry point allows an Accessory to specify the title of the FileXtract Reader library and the parameter string that is passed to the Reader library. The parameter string typically contains a file name or directory name, but the individual Reader library determines the format of the string.

The string values specified in DBREADERPARAMETER override the values specified in the logical database comment in the DASDL. However, if you leave either DBREADERPARAMETER string parameter empty, the Accessory Reader library ignores the empty parameter, and the DASDL comment prevails.

Declaration

DBMTYPE procedure DBReaderParameter (LibraryTitle, Param);

Input	Type	Definition
LIBRARYTITLE	STRING	The title of the FileXtract Reader library If this string is empty, the default title specified in the DASDL logical database comment is used instead.
PARAM	STRING	The character string passed to the FILEREAD entry point of the FileXtract Reader library in the FileInfo array. Refer to the Databridge FileXtract Administrator's Guide for more information about Reader libraries. If this string is empty, the default parameter specified in the DASDL logical database comment is used instead.

DBREADTRANGROUP

This entry point receives a transaction group (up to a quiet point) of changes to data set records from the audit trail.

Note

You must have selected at least one data set with DBSELECT in order to use this entry point.

By default, the CHECKPOINT interval specified in the DBEngine parameter file determines the size of the transaction group. If you want DBREADTRANGROUP to commit at every QPT, call DBSETOPTION (DBV_OP_QPT_GROUP). The DBSETOPTION entry point is explained in DBRESETOPTION. If a transaction group is not available, DBREADTRANGROUP waits up to the amount of time specified in MAXWAITSECS for the group to become available.

DBREADTRANGROUP responds if an Accessory's EXCEPTIONEVENT or ACCEPTEVENT is caused. This ensures that the AX command works immediately.

Declaration

DBMTYPE procedure DBReadTranGroup (Callback, RetrySecs, MaxWaitSecs);

Input	Type	Definition
CALLBACK	BOOLEAN	The callback procedure that receives each data set record update found in the current transaction group
RETRYSECS	REAL	The number of seconds between retries
MAXWAITSECS	REAL	The maximum number of seconds to wait for a transaction group to become available Values are as follows: DBV_WAIT_FOREVER—Retry for more audits indefinitely DBV_DONT_WAIT—Do not retry at all Positive integer—Specifies the number of seconds to wait

BOOLEAN PROCEDURE CALLBACK

This procedure receives each data set record update (CREATE, DELETE, or CHANGE), STATE_INFO update, or documentation record found in the current transaction group.

Declaration

boolean procedure Callback (UPDATE_INFO, BI, AI);

Parameter	Type	Definition
UPDATE_INFO	ARRAY	The UPDATE_INFO value describing the update For a description of the array, see UPDATE_INFO Layout.
BI	ARRAY	The before-image of the record This array is valid only for update types DBV_DELETE and DBV_MODIFY. See Record Change Types for a description of these types.
AI	ARRAY	The after-image of the record This array is not valid for update type DBV_DELETE. See Record Change Types for a description of this type.

DBRESETOPTION

This entry point resets (turns off) the DBEngine run-time options. To set run-time options, see DBSETOPTION.

Declaration

DBMTYPE procedure DBRESETOPTION (Option);

Input	Type	Definition
OPTION	INTEGER	This specifies the option to turn off. For a description of the options, see DBSETOPTION/DBRESETOPTION Run-Time Options.

DBSELECT

This entry point selects which data set(s) to process with subsequent DBREADTRANGROUPs, DBREADs, or DBWAITs.

Note

Since DBEngine returns data set records only for data sets that are specified here, you cannot able use DBREADTRANGROUP, DBREAD, or DBWAIT unless you specify a data set(s).

DBSELECT validates the data set's audit location (unless it is to be cloned) and the client format level, and it verifies that the filter allows the specified structure number and record type.

The parent of an embedded data set must be selected before selecting the embedded data set.

To deselect data sets, see DBDESELECT.

Declaration

DBMTYPE procedure DBSELECT (STATE_INFO, TableName, StrIdx);

Input	Type	Definition
STATE_INFO	ARRAY	The state of the client table, including the audit location The STATE_INFO array contains the DMSII structure number of the data set and the variable-format record type number. For a description of the array, STATE_INFO Layout.
TABLENAME	STRING	The name of the client table DBEngine uses this name in place of the data set name in any error messages. If TABLENAME is empty, Databridge updates it to the DMSII data set name implied by the structure number in the STATE_INFO array

Output	Type	Definition
STRIDX	INTEGER	Unique index for this data set-record type, suitable for an array index NOTE: Remember this STRIDX because any entry point that returns the UPDATE_INFO array uses it.

DBSELECTED

This entry point checks to see if the specified data set has been successfully selected. For related information, see DBSELECT.

The procedure returns the value DBM_OK, which equates to a value of 0, if the data set you specify has been selected with DBSELECT. If it has not been selected, the procedure returns DBM_DS_NOTFOUND (10).

Declaration

DBMTYPE procedure DBSELECTED (DSStrNum, RecType);

Input	Type	Definition
DSSTRNUM	REAL	DMSII structure number of the data set
RECTYPE	REAL	Record type number (0 for fixed format)

DBSETINFO

This entry point retrieves information about a set.

Declaration

DBMTYPE procedure DBSETINFO (SetStrNum, SET_INFO);

Input	Type	Definition
SETSTRNUM	REAL	The structure number of the set

Output	Type	Definition
SET_INFO	ARRAY	The information about the set For a description of the array, see SET_INFO Layout.

DBSETOPTION

This entry point sets (enables) the DBEngine run-time options. To reset these options, see DBRESETOPTION.

Declaration

DBMTYPE procedure DBSETOPTION (Option);

Input	Type	Definition
OPTION	INTEGER	This specifies the option to turn on
For a description of these options, see DBSETOPTION/DBRESETOPTION Run-Time Options.

DBSETS

This entry point returns set names and their structure numbers for a given data set or remap.

Declaration

DBMTYPE procedure DBSETS (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the target data set or remap for which the sets are to be returned
CALLBACK	BOOLEAN	The procedure that provides information for each set

BOOLEAN PROCEDURE CALLBACK

This procedure is called once for each set it finds.

Declaration

boolean procedure Callback (pSetName, Len, SetStrNum, DuplicatesAllowed, KeyChangeAllowed);

Parameter	Type	Definition
P_SETNAME	POINTER	The pointer to a set name The caller is expected to copy the actual set name into local memory.
LEN	REAL	The length of the set name
SETSTRNUM	REAL	The structure number of the set
DUPLICATESALLOWED	BOOLEAN	Set to TRUE if duplicates are allowed
KEYCHANGEALLOWED	BOOLEAN	Set to TRUE if key changes are allowed

DBSETSINFO

This entry point returns information for each set of a given data set or remap.

Declaration

DBMTYPE procedure DBSETSINFO (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	This is the structure number of the target data set or remap for which the sets are to be returned
CALLBACK	BOOLEAN	The procedure that receives information for each set

BOOLEAN PROCEDURE CALLBACK

This procedure is called once for each set it finds.

Declaration

boolean procedure Callback (SET_INFO);

Parameter	Type	Definition
SET_INFO	ARRAY	This is the information describing the set For a description of the array, see SET_INFO Layout.

DBSPLITTIMESTAMP

This entry point converts a timestamp from TIME (6) format to a date and time in yyyy,mm,dd,hh,mn,ss form. Each component is in binary format.

Declaration

DBMTYPE procedure DBSPLITTIMESTAMP (TS, YYYY, MM, DD, HH, MN, SS);

Input	Type	Definition
TS	REAL	The timestamp in TIME (6) form, such as from the UI_TIME field of UPDATE_INFO See UPDATE_INFO Layout for a description of the UI_TIME field.

Output	Type	Definition
YYYY	INTEGER	The year in four digits, 1970–2035
MM	INTEGER	The month in two digits, 1–12
DD	INTEGER	The day in two digits, 1–31
HH	INTEGER	The hour in two digits, 0–23
MN	INTEGER	The minute in two digits, 0–59
SS	INTEGER	The second in two digits, 0–59

DBSPLITTIME60

This entry point splits a timestamp in TIME (60) format into separate components similar to DBSPLITTIMESTAMP.

Declaration

DBMTYPE procedure DBSPLITTIME60 (TS, YYYY, MM, DD, HH, MN, SS);

Input	Type	Definition
TS	REAL	Timestamp in TIME (60) format

Output	Type	Definition
YYYY	INTEGER	The year in four digits, 1970–2035
MM	INTEGER	The month in two digits, 1–12
DD	INTEGER	The day in two digits, 1–31
HH	INTEGER	The hour in two digits, 0–23
MN	INTEGER	The minute in two digits, 0–59
SS	INTEGER	The second in two digits, 0–59

DBSTATEINFOTODISPLAY

This entry point converts the STATE_INFO array, which includes the audit location, to a readable format. The value of this entry point is the length of the resulting message.

Declaration

integer procedure DBSTATEINFOTODISPLAY (STATE_INFO, pOut);

Input	Type	Definition
STATE_INFO	ARRAY	The state information as it is received from DBEngine For a description of the array, see STATE_INFO Layout.
POUT	POINTER	The destination of the readable format state information

DBSTATISTICS

This entry point returns statistics for the specified category. DBEngine prints a report of the statistics collected (at EOJ) if DBEngine is compiled with $ SET STATS, which is available as OBJECT/DATABRIDGE/ENGINE/STATS.

Declaration

DBMTYPE procedure DBStatistics (StatCategory, StatDescription, STATISTICS_INFO);

Input	Type	Definition
StatCategory	INTEGER	The statistics category number For a description of these values, see Statistics Category Values.

DBSTRIDX

This entry point returns the structure index of the specified data set or remap.

Declaration

DBMTYPE procedure DBSTRIDX (DSStrNum, RecType, StrIdx);

Input	Type	Definition
DSSTRNUM	REAL	The DMSII structure number of the data set or remap
RECTYPE	REAL	The record type number (0 for fixed format)

Output	Type	Definition
STRIDX	REAL	The structure index of the specified data set or remap. This is the same value returned by DBSELECT.

DBSTRNUM

This entry point returns a structure number for the specified structure name.

Declaration

DBMTYPE procedure DBSTRNUM (pStrName, StrNum);

Input	Type	Definition
PSTRNAME	POINTER	The pointer to a structure name Any illegal character, such as a space, terminates the name.

Output	Type	Definition
STRNUM	REAL	The DMSII structure number

DBSTRUCTURENAME

This entry point returns a structure name for a DMSII structure number and always uses the physical database, even if the caller specifies a logical database. It also returns the name of a virtual data set when given the structure number specified in DBGenFormat.

Declaration

DBMTYPE procedure DBSTRUCTURENAME (StrNum, pName, Len);

Input	Type	Definition
STRNUM	REAL	The DMSII structure number (data set, set, remap) from UPDATE_INFO [UI_STRNUM]
PNAME	POINTER	The pointer to the array that is to receive the structure name

Output	Type	Definition
LEN	REAL	The length of the structure name in bytes Characters beyond this point in the array are unchanged.

DBSUBSETSINFO

This entry point returns information about each subset of a given data set.

Declaration

DBMTYPE procedure DBSubsetsInfo (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set containing the subset

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the subset. It is called once for each subset.

Declaration

boolean procedure Callback (SET_INFO);

Parameter	Type	Definition
SET_INFO	BOOLEAN	The array of information describing the subset For a description of the array, see SET_INFO Layout.

DBSWITCHAUDIT

This entry point forces an audit file switch. If you write your own utility for periodically closing the audit file, you can use this entry point to actually perform the audit switch without having to give the database stack number an SM command.

Note

You must call the DBINITIALIZE entry point before you call DBSWITCHAUDIT.

This entry point does not take any parameters.

When DBSWITCHAUDIT retries a failed switch (such as after "***VISIBLE DBS BUSY - TRY AGAIN"), it increases the delay between retries until it is successful or until the maximum delay retry rate (120 seconds) is exceeded. The DBM_AUDITSWITCH (109) message appears when you exceed the maximum delay retry rate.

DBSWITCHAUDIT also performs an AUDIT CLOSE FORCE, rather than a simple AUDIT CLOSE, which makes the closed audit file available immediately instead of having to wait until two control points are generated normally.

Declaration

DBMTYPE procedure DBSWITCHAUDIT;

DBTIMESTAMPMSG

This entry point converts the timestamp from TIME (6) format to a date and time message in displayable format.

Declaration

DBMTYPE procedure DBTIMESTAMPMSG (TS, TSString);

Input	Type	Definition
TS	REAL	The timestamp in TIME (6) form

Output	Type	Definition
TSSTRING	STRING	The timestamp in displayable form, as follows: `month day, year @ hh:mm:ss November 25, 2009 @ 11:27:45`

DBUPDATELEVEL

This entry point returns the database update level and update timestamp. These values correspond to the last DASDL compile.

Declaration

DBMTYPE procedure DBUpdateLevel (Updatelevel, UpdateTimestamp);

Output	Type	Definition
UPDATELEVEL	REAL	The update level of the database
UPDATETIMESTAMP	REAL	The timestamp of the update

DBVERSION

This entry point provides the version number of the Databridge API file (SYMBOL/DATABRIDGE/ INTERFACE) for which DBEngine was compiled. This number must match DBV_VERSION in the API file you include in your program, as in the following example:

IF DBVERSION NEQ DBV_VERSION THEN
    BEGIN
    DIE ("Databridge ENGINE software version
     mismatch");
    END;

Declaration

real procedure DBVERSION;

DBWAIT

This entry point receives a transaction group of changes to data set records from the audit trail. It waits up to the amount of time specified in MAXWAITSECS for the group to become available.

Note

The DBWAIT entry point is compatible with older Accessories. Using DBREADTRANGROUP is the preferred method.

You must have also selected at least one data set with DBSELECT in order to use this entry point.

DBWAIT responds if an Accessory's EXCEPTIONEVENT or ACCEPTEVENT is caused. This ensures that the AX command works immediately.

Declaration

DBMTYPE procedure DBWAIT (Callback, RetrySecs, MaxWaitSecs);

Input	Type	Definition
RETRYSECS	REAL	The number of seconds between retries For example, a value of five means to look for more available audits every five seconds.
MAXWAITSECS	REAL	The maximum number of seconds to wait for a transaction group to become available For example, a value of 100 means that this procedure waits a total of 100 seconds (which implies 20 retries when RETRYSECS is set to 5). Values are as follows: DBV_WAIT_FOREVER—Indicates to retry for more audits indefinitely DBV_DONT_WAIT—Indicates to not retry at all Positive integer—Indicates the numbers of seconds to wait
CALLBACK	BOOLEAN	The procedure to call back for each data set record update (CREATE, DELETE, CHANGE), STATE_INFO update, or documentation record found in the current transaction group

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the modification.

Declaration

boolean procedure Callback (Image, UPDATE_INFO);

Parameter	Type	Definition
IMAGE	ARRAY	This array contains the record image, as follows: Before-image if DELETE After-image if CREATE or MODIFY STATE_INFO image if the state (audit location) changes Documentation record for non-update information
UPDATE_INFO	ARRAY	This array contains the description of the modification For a description of the array, see UPDATE_INFO Layout.

DBWHEREDASDL

This entry point returns the DASDL source expression associated with the WHERE clause of an automatic subset or the SELECT cause of a remap.

Declaration

DBMTYPE procedure DBWhereDASDL (StrNum, pDASDLText, Len);

Input	Type	Definition
STRNUM	REAL	The structure number of the desired subset or remap
PDASDLTEXT	POINTER	Destination for the DASDL expression

Output	Type	Definition
PDASDLTEXT	POINTER	Destination for the DASDL expression
LEN	REAL	The length in bytes of the text copied into PDASDLTEXT Possible values are as follows: If the array is too short, no text is copied, but LEN is set to the needed length and the procedure value is DBM_SHORT_ARRAY (23). If no DASDL expression is associated with the structure, such as when the structure number is a data set, set, or manual subset, the procedure returns DBM_OK, and LEN is set to 0.

DBWHERETEXT

This entry point returns the ALGOL source code fragment associated with the WHERE clause of an automatic subset or the SELECT clause of a remap.

Declaration

DBMTYPE procedure DBWhereText (StrNum, pText, Len);

Input	Type	Definition
STRNUM	REAL	The structure number of the desired subset or remap
PTEXT	POINTER	The destination for the source code text

Output	Type	Definition
PTEXT	POINTER	Destination for the source code text
LEN	REAL	The length in bytes of the text copied into PTEXT Possible values are as follows: If the array is too short, no text is copied, but LEN is set to the needed length and the procedure value is DBM_SHORT_ARRAY (23). If no text is associated with the structure, such as when the structure number is a data set, set, or manual subset, the procedure returns DBM_OK, and LEN is set to 0.

DBSupport Entry Points

Use the DBSupport library to filter and format the data you receive from DBEngine.

Security Filtering

DBSupport provides the following levels of security through filtering:

Data set-level security—For more information, see DBVIEWABLE.
Record-level security—For more information, see DBFILTER.

Additional Filtering.

The DBGenFormat utility can generate additional filtering routines using brief text descriptions in a parameter file. Refer to the Databridge Host Administrator's Guide for information.

In a non-tailored support library, you cannot use any data set or data item names, nor can you use any SELECT statements. Therefore, you must create a tailored support library to create effective filters.

You have access to the source code for the DBSupport library (SYMBOL/DATABRIDGE/SUPPORT) and can modify it in order to implement data filtering, data security, and other functions. (For instance, using DBFILTER.) It is strongly recommended, however, that you use DBGenFormat to provide these features if at all possible.

CAUTION: If you patch DBSupport directly rather than using declarations in DBGenFormat, make sure you observe the comments in the source that indicate where user-written patches should go. These lines are preserved from release to release; all other lines are subject to change and resequencing.

DBSupport Formatting.

By default, the data records DBEngine returns to an Accessory are not formatted. In other words, they are the binary image of the corresponding record in the DMSII database as they would appear to a COBOL program. Often these records need to be reformatted into individual fields so that an Accessory can store the fields in a more suitable format.

The DBGenFormat utility generates additional formatting routines using brief text descriptions in a parameter file. Refer to the Databridge Host Administrator's Guide for description of all default formats.

Accessories can select a format routine by setting the ACTUALNAME of the DBFORMAT entry point to one of the defined formatting routines. For details, see DBFORMAT.

You have access to the source code for the DBSupport library (SYMBOL/DATABRIDGE/SUPPORT) and can modify it in order to implement custom formatting. We strongly recommend, however, that you use DBGenFormat to provide these features if at all possible.

Caution

If you patch DBSupport directly rather than using declarations in DBGenFormat, make sure you observe the comments in the source that indicate where user-written patches should go. These lines are preserved from release to release; all other lines are subject to change and resequencing.

Using the DBSupport Entry Points.

Before you can use the entry points in the DBSupport library, you must complete the items listed in Accessing the DBEngine and DBSupport Libraries. One of these tasks is to specify a filter using DBSUPPORTINIT. When a description of a DBSupport entry point refers to a filter, it is referring to the specified filter.

The table below summarizes the DBSupport entry points and their functions, and each of these entry points is explained in detail later in this chapter. The Entry Point column in this table contains the name of the entry point, the Type column indicates the type of ALGOL procedure, and the Description column describes what the entry point does. See Entry Point Procedure Values for an explanation of the various procedure types and the values they return. DBMTYPE values are listed in the API file (SYMBOL/DATABRIDGE/INTERFACE) and the Databridge Host Administrator's Guide.

Entry Point	Type	Description
DBCLIENTKEY	EMATYPE	Reports errors You can write your own error handling routine to analyze the error and take appropriate action. If no error handler is defined in the DBGenFormat parameter file, this entry point displays the error message and lets the Accessory decide what to do, such as whether to terminate, keep going, or do an ACCEPT.
DBEXTRACTKEY	DBMTYPE	Extracts the primary key of a data set record
DBFILTER	BOOLEAN	Filters records
DBFILTEREDDATASETS	DBMTYPE	Enumerates the data set names and other information about each data set as restricted by a filter
DBFILTEREDITEMNAME	DBMTYPE	Returns information for a data item in a data set and applies the current filter and any ALTERs
DBFILTEREDLAYOUT	DBMTYPE	Enumerates data items in a data set as restricted by a filter
DBFILTEREDLINKS	DBMTYPE	Returns the LINK items for a data set as allowed by the current filter
DBFILTEREDNULLRECORD	DBMTYPE	Returns a record with all data items set to NULL
DBFILTEREDSETS	DBMTYPE	Enumerates set names and their structure number for a data set as restricted by a filter
DBFILTEREDSETSINFO	DBMTYPE	Enumerates information for each set of a given data set available in the filter
DBFILTEREDSTRNUM	DBMTYPE	Returns the structure number for a data set name
DBFILTEREDSUBSETSINFO	DBMTYPE	Enumerates information for each subset of a given data set, provided it is available in the filter
DBFILTEREDWRITE	DBMTYPE	Performs all of the necessary filtering and formatting of an update received from DBReadTranGroup
DBFORMAT	BOOLEAN	Formats the data record for output
DBINITDATAERROR	DBMTYPE	Initializes data-error handling for the formatting routines
DBINITIALIZESUPPORT	DBMTYPE	NOTE: This entry point has been replaced by the DBINITIALIZESUPPORT entry point. Verifies that the Accessory is using the same version of DBInterface and allows the DBSupport library to link to DBEngine
DBPRIMARYKEY	DBMTYPE	Enumerates data items that form a unique key for a data set
DBSETUP	BOOLEAN	Verifies that the Accessory is using the same versions of the Databridge interface. This also allows the DBSupport library to initialize.
DBSUPPORTENGINE	DBMTYPE	Allows an Accessory to specify the title of the DBEngine library that DBSupport should link to
DBSUPPORTINIT	DBMTYPE	Required. Verifies that the Accessory is using the same version of DBInterface and allows the DBSupport library to link to DBEngine NOTE: This entry point replaces the DBINITIALIZESUPPORT entry point.
DBSUPPORTMISSINGENTRYPOINT	STRING	Returns the name of the first entry point missing from the DBSupport library code file that the Accessory expected to be present based on the interface file
DBUNREMAPITEMINFO	DBMTYPE	Takes a remap data item number and returns item information for the data item in the original data set
DBVIEWABLE	BOOLEAN	Determines whether a data set is viewable for userdefined data set filtering

DBCLIENTKEY

The client calls this entry point to indicate the primary key it is using for a structure. The formatting routines will then send both the BeforeImage and AfterImage of a modify if the key value changed.

Declaration

DBMTYPE procedure DBClientKey (StrIdx, KeyCount, KeyList);

Input	Type	Definition
StrIdx	INTEGER	Structure index of a selected data set
KeyCount	INTEGER	Number of key items in KeyList
KeyList	REAL ARRAY	LIst of item numbers of keys

DBERRORMANAGER

Accessories call this entry point to report errors. You can write your own error handling routine to analyze the error and take appropriate action. You must declare any error handler you create in the DBGenFormat parameter file (see Error Handling Routines for more information about error handling routines). If no error handler is defined in the DBGenFormat parameter file, this entry point displays the error message and lets the Accessory decide what to do, such as whether to terminate, keep going, or do an ACCEPT.

Declaration

EMATYPE procedure DBErrorManager (AccessoryID, ErrNbr, pErrMsg, ErrMsgLen);

Input	Type	Definition
ACCESSORYID	AIDTYPE	The ID number of the Accessory AIDTYPE values are listed in Types, Values, and Array Layouts.
ERRNBR	DBMTYPE	The error number Error numbers are listed in the Databridge Host Administrator's Guide.
PERRMSG	POINTER	The error message text Error messages are listed in the Databridge Host Administrator's Guide.
ERRMSGLEN	REAL	The length of the error message in bytes

Example

The following code shows how DBSpan calls DBErrorManager:

case DBErrorManager (DBV_Span, DMR, Msg, offset (pMsg)) of
    begin
    DBV_Default: % Accessory can decide
        ; 

    DBV_Fatal: % Accessory should terminate
        Fatal := true;

    DBV_Ignore: % Accessory should continue
        Fatal := false;
        DMR := DBM_OK;

DBV_Retry: % Accessory should retry the operation
    Fatal := false;
    end;

if DMR ^= DBM_OK then % still an error
    begin
    WriteMsg (MSG_ERROR);

    if Fatal then
       begin
       InsertErrNbr (DBM_FATAL_ERROR);
       MESSAGESEARCHER (MessText [DBM_FATAL_ERROR], pMsg, MsgLen);
       display (Msg);
       MYSELF.STATUS := value (TERMINATED);
       end;
    end;

DBEXTRACTKEY

This entry point extracts the primary key of a data set record.

Declaration

DBMTYPE procedure DBEXTRACTKEY (DSStrNum, Record, Key);

Input	Type	Definition
DSSTRNUM	INTEGER	The structure number of the data set whose primary key you want to extract
RECORD	ARRAY	Unformatted data set record from the audit trail from DBREADTRANGROUP, DBREAD, or DBWAIT

Output	Type	Definition
KEY	ARRAY	The primary key value for the record The caller must ensure that this array is large enough to hold the key value; otherwise, a SEG ARRAY ERROR may occur.

DBFILTER

This entry point allows you to apply user-defined record filtering. Use it for record security and selection.

The procedure value can be the following:

TRUE—The record meets the criteria, so the caller should continue to process the record.
FALSE—The caller should discard the record.
Boolean (DBV_WRONGLEVEL)—The record has a different format level than the filter. Recompile the DBSupport library.
Boolean (DBV_BAD_STRNUM)—The record is for an unknown data set. Recompile the DBSupport library.

Declaration

boolean procedure DBFILTER (UserRec, UI);

Input	Type	Definition
USERREC	ARRAY	Unformatted data set record from the audit trail
UI	ARRAY	Description of the modification For a description of the array, see UPDATE_INFO Layout.

You have access to the source code for the DBSupport library (SYMBOL/DATABRIDGE/SUPPORT) and can modify it in order to implement data filtering, data security, and other functions. We strongly recommend, however, that you use DBGenFormat to provide these features if at all possible. See the Databridge Host Administrator's Guide for more information on DBGenFormat.

Caution

Make sure you observe the comments in the source that indicate where user-written patches should go. These lines are preserved from release to release; all other lines are subject to change and resequencing.

DBFILTEREDDATASETS

This entry point returns data set names and other information about each data set in the filter. If the filter discards all records from a particular data set, that data set's information is not returned.

Declaration

DBMTYPE procedure DBFilteredDatasets (Callback);

Input	Type	Definition
CALLBACK	BOOLEAN	The procedure that receives information for each data set

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about each data set in the filter.

Declaration

boolean procedure Callback (pDSName, Len, DATASET_INFO);

Parameter	Type	Definition
PDSNAME	POINTER	The pointer to a data set name The calling program must copy this name into its local memory.
LEN	REAL	The length of the data set name
DATASET_INFO	ARRAY	Information about the data set For a description of the array, see DATABASE_INFO Layout.

DBFILTEREDITEMINFO

This entry point returns information for a data item in a data set or remap and applies the current filter and any ALTERs. See Altered Data Sets for more information on ALTERs.

This entry point supports virtual data sets. For more information on virtual data sets, see Virtual Data Sets.

Declaration

DBMTYPE procedure DBFilteredItemInfo (DSStrNum, RecType, ItemNum, ITEM_INFO);

DBFILTEREDITEMNAME

This entry point returns information for a data item in a data set as restricted by a filter and any ALTERs.

Declaration

DBMTYPE procedure DBFilteredItemName (DSStrNum, RecType, ItemName,ITEM_INFO);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the desired data set
RECTYPE	REAL	The record type of the desired data set
ITEMNAME	STRING	The name of the data item whose information is to be returned

Output	Type	Definition
ITEM_INFO	ARRAY	The information for the data item For a description of the array, see ITEM_INFO Array Layout.

DBFILTEREDLAYOUT

This entry point returns data items in a data set or remap as restricted by a filter and any ALTERs.

Declaration

DBMTYPE procedure DBFilteredLayout (DSStrNum, RecType, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set or remap that contains the data items you want to return
RECTYPE	REAL	The record type number (0 for fixed format)
CALLBACK	BOOLEAN	The procedure that receives information about each data item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about each data item in the data set or remap.

Declaration

boolean procedure Callback (ITEM_INFO);

Output	Type	Definition
ITEM_INFO	ARRAY	Information about the data item For a description of the array, see ITEM_INFO Array Layout.

DBFILTEREDLINKS

This entry point returns the link items for a data set as restricted by the filter.

Declaration

DBMTYPE procedure DBFilteredLinks (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the desired data set

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the link items in a data set. This procedure is called once for each link item.

Declaration

boolean procedure Callback (ITEM_INFO);

Parameter	Type	Definition
ITEM_INFO	ARRAY	The array of information describing a link item in the data set For a description of the array, see ITEM_INFO Array Layout.

DBFILTEREDNULLRECORD

This entry point returns a record with all data items set to NULL. The record layout reflects the filter and any ALTERs.

Declaration

DBMTYPE procedure DBFilteredNullRecord (DSStrNum, RecType, NullRec);

Input	Type	Definition
DSSTRNUM	INTEGER	The structure number of the data set or remap
RECTYPE	INTEGER	The record type number (0 for fixed format)

Output	Type	Definition
NULLREC	ARRAY	A binary image of a data set record with all data items set to NULL

DBFILTEREDSETS

This entry point returns set names and their structure numbers for a data set or remap as restricted by a filter. If a set contains a key that the filter does not allow, the set is not returned to the calling program.

Declaration

DBMTYPE procedure DBFilteredSets (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set or remap for which you want to return sets
CALLBACK	BOOLEAN	The procedure that receives information for each set

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about each set of the specified data set or remap in the filter.

Declaration

boolean procedure Callback (pSetName, Len, SetStrNum, DuplicatesAllowed, KeyChangeAllowed);

Parameter	Type	Definition
P_SETNAME	POINTER	The pointer to the set name The calling program must copy this name to its memory
LEN	REAL	The length of the set name
STRNUM	REAL	The structure number of the set
DUPLICATESALLOWED	BOOLEAN	One of the following: TRUE—The set allows duplicates. FALSE—The set does not allow duplicates.
KEYCHANGEALLOWED	BOOLEAN	One of the following: TRUE—The set allows an update to change the value of the key. FALSE—The set does not allow an update to change the value of the key.

DBFILTEREDSETSINFO

This entry point returns information for each set of a given data set or remap, as restricted by the filter. If a set contains a key that the filter does not allow, the set is not returned to the calling program.

Declaration

DBMTYPE procedure DBFilteredSetsInfo (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set or remap that is the target of the returned sets
CALLBACK	BOOLEAN	The procedure that receives information for each set

BOOLEAN PROCEDURE CALLBACK

This procedure receives information for each set of the data set or remap as restricted by the filter.

Declaration

boolean procedure Callback (SET_INFO);

Parameter	Type	Definition
SET_INFO	ARRAY	The information describing the set For a description of the array, see SET_INFO Layout.

DBFILTEREDSTRNUM

This entry point returns the structure number for a data set or remap name, including virtual data sets. If the filter does not allow the specified data set or remap, the entry point returns an error.

Declaration

DBMTYPE procedure DBFilteredStrNum (pDSName, DSStrNum);

Input	Type	Definition
PDSNAME	POINTER	The pointer to a data set name Any illegal character, such as a space, terminates the name.

Output	Type	Definition
DSSTRNUM	REAL	The structure number for the specified data set or remap

DBFILTEREDSUBSETSINFO

This entry point returns information about each subset of a given data set or remap, as restricted by the filter.

Declaration

DBMTYPE procedure DBFilteredSubsetsInfo (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	REAL	The structure number of the data set that is the target of the subsets
CALLBACK	BOOLEAN	The procedure that receives information for each subset

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the subset. This procedure is called once for each subset.

Declaration

boolean procedure Callback (SET_INFO);

Parameter	Type	Definition
SET_INFO	BOOLEAN	The array of information describing the subset For a description of the array, see SET_INFO Layout.

DBFILTEREDWRITE

This entry point performs all of the necessary filtering and formatting of an update received from DBREADTRANGROUP.

DBFILTEREDWRITE determines two things from UPDATE_INFO as follows:

Whether to send only the after-image or both the before- and after-images to be modified.
Whether or not a modify causes a change in the DBFILTER result and sends the appropriate update type. For example, if the update causes the DBFILTER result to change from FALSE to TRUE, DBFILTEREDWRITE sends the update as a CREATE. A change from TRUE to FALSE causes a DELETE.

Procedure values include:

DBM_OK (0)—The record was written.
DBM_FILTERED_OUT (104)—The record was not written because it did not satisfy the WHERE condition.
DBM_FORMAT_ERROR (91)—The formatting routine encountered an error.
DBM_COMP_SUPPORT (96)—DBSupport needs to be recompiled.

Declaration

DBMTYPE procedure DBFilteredWrite (UI, BI, AI, DBFormat, Writer)

Input	Type	Definition
UI	ARRAY	The UPDATE_INFO describing the update For a description of the array, see UPDATE_INFO Layout.
BI	ARRAY	The before-image of the record
AI	ARRAY	The after-image of the record
DBFORMAT	BOOLEAN	The formatting routine to call
WRITER	BOOLEAN	The procedure to call to return the formatted record

BOOLEAN PROCEDURE WRITER

This procedure receives information about the formatted record.

Declaration

boolean procedure writer (P, Chars);

Output	Type	Definition
P	POINTER	The pointer to the formatted record
CHARS	REAL	The length of the formatted record in bytes

DBFORMAT

This entry point formats a data record for output. This is the default format, which is a binary image of the corresponding record in the database as it would appear to a COBOL program. RAWFORMAT is an alias for this formatting routine.

The procedure value can be any DBMTYPE result code.

Declaration

DBMTYPE procedure DBFORMAT (UserRec, UI, Callback);

Input	Type	Definition
USERREC	ARRAY	An unformatted data set record from the audit trail
UI	ARRAY	A description of the modification For a description of the array, see UPDATE_INFO Layout.
CALLBACK	DBMTYPE	The procedure to call with the formatted record

DBMTYPE PROCEDURE CALLBACK

This procedure receives information about the formatted record.

Declaration

DBMTYPE procedure Callback (P, Chars);

Parameter	Type	Definition
P	POINTER	The pointer to the formatted record
CHARS	REAL	The length of the formatted record in bytes
UPDATE_INFO	ARRAY	A description of the modification. For a description of the array, see the UPDATE_INFO Layout.
RawImage	ARRAY	The original unformatted record

Additional Options

Databridge includes several other formats, which DBGenFormat produces from its parameter file. The release object code (executable program) for the DBSupport library contains predefined formatting routines corresponding to the format declarations in DATA/GENFORMAT/SAMPLE/ CONTROL.

For more information, see the Databridge Host Administrator's Guide.

An Accessory typically refers only to DBFORMAT. By changing the ACTUALNAME of DBFORMAT, however, you can redirect any calls to DBFORMAT to another formatting routine such as FIXEDFORMAT. This allows the Accessory to dynamically select the formatting routine while keeping a simple call to DBFORMAT.

Example

This example shows how to redirect calls from DBFORMAT to another formatting routine.

% get the format name
      FORMATNAME := YY_STRING (NAMELOC);

      REPLACE FILETITLE BY FORMATNAME, ".";

      IF SETACTUALNAME (DBFORMAT, FILETITLE) < 0 THEN
             BEGIN
             DIE (DBM_BAD_FORMATNAME, FORMATNAME);
             END;

Layout Information

The DBFORMAT routines in a non-tailored DBSupport library load new layout information as necessary. For example, if a data set is reorganized, DBFORMAT loads the new layout when it receives records with the new layout. The generic formatting routines check the DESCRIPTION file for layout information.

DBINITDATAERROR

This entry point initializes data-error handling for the formatting routines. When the formatting routines detect one of the specified error conditions during subsequent processing, they call the indicated procedure, DataError_Output. (The DBINITDATAERROR entry point itself does not call DataError_Output.)

Declaration

DBMTYPE procedure DBINITDATAERROR (DataError_Options, DataError_Output);

Input	Type	Definition
DATAERROR_OPTIONS	BOOLEAN	Each bit specifies the type of data error checking to perform For a description of these error types, see Data Error Types.
DATAERROR_OUTPUT	BOOLEAN	Procedure to call when a formatting routine detects a data error.

BOOLEAN PROCEDURE DataError_Output

This procedure receives information about the error message.

Declaration

boolean procedure DataError_Output (P, Chars);

Parameter	Type	Definition
P	POINTER	The pointer to the data error message
CHARS	REAL	The length of the data error message in bytes

DBINITIALIZESUPPORT

Note

You should use the DBSUPPORTINIT entry point instead of DBINITIALIZESUPPORT. This entry point is not the preferred method for initializing the DBSupport library.

If you use this entry point, you must first specify the filter and format names in the Accessory using the LIBPARAMETER attribute of DBSupport. (The Accessory cannot specify a transform using this entry point.) DBINITIALIZESUPPORT provides backward compatibility for existing Accessories. All new Accessories use DBSUPPORTINIT.

This entry point verifies that the DBInterface version of the Accessory, DBSupport, and DBEngine are all compatible. If the DBInterface versions used to compile DBEngine, DBSupport, or the Accessory do not match, it returns DBM_VER_MISMATCH (115). If the versions match, DBINITIALIZESUPPORT installs the designated filter and format and returns DBM_OK.

An Accessory must call this entry point (if not DBSUPPORTINIT) before calling any other DBSupport entry points. See Accessing the DBEngine and DBSupport Libraries for more information.

Before calling DBINITIALIZESUPPORT, the Accessory must specify the name of the filter and format DBSupport should use in all of its routines. To specify the filter and format names, set the LIBPARAMETER string library attribute of DBSupport to the filter name followed by a space and the format name as in the following example:

SUPPORT.LIBPARAMETER := "ONLYBANK1 BINARYFORMAT";

If you do not set LIBPARAMETER to the name of a filter, DBSupport defaults to the predefined DBFILTER, which allows everything.

Declaration

define DBInitializeSupport (AccessoryVersion, AccessoryID) = DBSupportInit
  (AccessoryVersion, AccessoryID, head (Support.LIBPARAMETER, not " "),
   tail (tail (Support.LIBPARAMETER, not " "), " "), empty) #;

Input	Type	Definition
ACCESSORYVERSION	REAL	The version of the Databridge Interface used to compile the Accessory
ACCESSORYID	STRING	A description of the Accessory to insert in the error message

DBPRIMARYKEY

This entry point returns data items that form a unique key for a data set. The key is either user- defined (in DBGenFormat) or is the key of the set with the fewest key items that does not allow duplicates.

Declaration

DBMTYPE procedure DBPRIMARYKEY (DSStrNum, Callback);

Input	Type	Definition
DSSTRNUM	INTEGER	The structure number of the data set or remap for which you want a primary key
CALLBACK	BOOLEAN	The procedure that receives information for each key item

BOOLEAN PROCEDURE CALLBACK

This procedure receives information about the data item that forms the unique key.

Declaration

boolean procedure Callback (ItemNum, Descending);

Input	Type	Definition
ITEMNUM	INTEGER	The item number of the data item, as in ITEM_INFO [II_ITEM_NUM]
DESCENDING	BOOLEAN	TRUE if the item is descending

DBSETUP

Note

Use the DBSUPPORTINIT entry point instead of DBSETUP. This entry point is not the preferred method for initializing the DBSupport library. If you use this entry point rather than DBSUPPORTINIT, you cannot specify a filter or format name. They default to DBFILTER and DBFORMAT respectively.

This entry point checks the versions of the Databridge API and initializes the DBSupport library. Your program must call this entry point, if not DBSUPPORTINIT, before calling any other entry points in DBSupport. The success of the procedure is reflected in the Boolean procedure value, as follows:

TRUE—The version number is correct, and the DBSupport library is initialized.
FALSE—The initialization failed.

Declaration

boolean procedure DBSETUP (Caller_Version);

Input	Type	Definition
CALLER_VERSION	REAL	The version of the API file you used to compile your program

DBSUPPORTENGINE

This entry point allows an Accessory to specify the title of the DBEngine library that DBSupport should link to. Contact Micro Focus for additional information.

DBSUPPORTINIT

Note

This entry point replaces the DBINITIALIZESUPPORT entry point; however, DBINITIALIZESUPPORT is provided for backward compatibility.

An Accessory must call this entry point first to verify that the DBInterface version of the Accessory, DBSupport, and DBEngine are all compatible and to allow the DBSupport library to link to DBEngine.

If the Accessory, DBEngine, and DBSupport are not all compiled against the same version of DBInterface, this entry point returns a DBM_VER_MISMATCH message.

Declaration

DBMTYPE procedure DBSupportInit (AccessoryVersion, AccessoryID,
FilterName,        FormatName,    TransformName);

Input	Type	Definition
ACCESSORYVERSION	REAL	The version of the API file you used to compile your program
ACCESSORYID	STRING	A string describing the Accessory that prefixes an error message
FILTERNAME	STRING	The name of the filter to use If you do not specify a filter, the default is DBFILTER.
FORMATNAME	STRING	The name of the format to use If you do not specify a format, the default is DBFORMAT.
TRANSFORMNAME	STRING	The name of the transform to use If you do not specify a transform, the default is DBTRANSFORM.

DBSUPPORTMISSINGENTRYPOINT

This entry point returns the name of the first entry point missing from the DBSupport library code file that the Accessory expected to be present based on the interface file.

Declaration

string procedure DBSUPPORTMissingEntryPoint;

Example

string MissingEP;

MissingEP := DBSUPPORTMissingEntryPoint;
if MissingEP NEQ empty then
    display ("Missing DBSupport entry point " !!
    MissingEP);

DBUNREMAPITEMINFO

This entry point takes a remap data item number and returns item information for the data item in the original data set.

In the following example, if R remaps D, and you pass this procedure the structure number of R and the item number of R2, it returns ITEMINFO for D1. The item name in ITEMINFO, for example, will be D1.

If the item number is for RVIRT, the routine zeros out the ITEMINFO because it is a VIRTUAL and, therefore, has no original data item information.

D DATASET         (
         D1 ALPHA (6);
         D2 NUMBER (12);
         );
R REMAPS D        (
         R2 = D1;
         RVIRT VIRTUAL NUMBER (2) = 99;
         );

Declaration

DBMTYPE procedure DBUnRemapItemInfo (RemapStrNum, RemapRecType,
    RemapItemNum, ITEM_INFO);

Input	Type	Definition
REMAPSTRNUM	INTEGER	The structure number of the remap
REMAPRECTYPE	INTEGER	The record type containing the remap item (0 for fixed-format)
REMAPITEMNUM	INTEGER	The number of the data item for which to return information

Ouput	Type	Definition
ITEM_INFO	ARRAY	The item information about the original data set item For a description of the array, see ITEM_INFO Array Layout.

DBVIEWABLE

This entry point determines if a structure is viewable (for user-defined data set filtering). The Boolean procedure values are as follows:

TRUE—The caller can see the data set.
FALSE—The caller cannot see the data set.

Declaration

boolean procedure DBVIEWABLE (DSStrNum);

Input	Type	Definition
DSSTRNUM	REAL	The DMSII structure number

If you are using	Then use this entry point
DBEngine only	DBINTERFACEVERSION or DBVERSION
DBEngine and DBSupport or DBSupport only	DBSUPPORTINIT