Administrative API Reference

How the API Descriptions are Organized

A short description of each API precedes some or all of the following subsections.

Scope

The API's scope of operation within the instance. In a single-node system, the scope is that single node only. In a multi-node system, it is the collection of all logical nodes defined in the node configuration file, db2nodes.cfg.

Authorization

The authority required to successfully call the API.

Required Connection

One of the following: database, instance, none, or establishes a connection. Indicates whether the function requires a database connection, an instance attachment, or no connection to operate successfully. An explicit connection to the database or attachment to the instance may be required before a particular API can be called. APIs that require a database connection or an instance attachment can be executed either locally or remotely. Those that require neither cannot be executed remotely; when called at the client, they affect the client environment only. For information about database connections and instance attachments, see the Administration Guide.

Version

The name of the include file that contains the API prototype, and any necessary predefined constants and parameters.

C API Syntax

The C syntax of the API call.

Starting in Version 6, a new standard is being applied to the DB2 administrative APIs. Implementation of the new API definitions is being carried out in a staged manner. Following is a brief overview of the changes:

• The new API names contain the prefix "db2", followed by a meaningful mixed case string (for example, db2LoadQuery). Related APIs have names that allow them to be logically grouped. For example:

     db2HistoryCloseScan
     db2HistoryGetEntry
     db2HistoryOpenScan
     db2HistoryUpdate
  

• Generic APIs have names that contain the prefix "db2gen", followed by a string that matches the C API name.

• The first parameter into the function (db2VersionNumber) represents the version, release, or PTF level to which the code is to be compiled. This version number is used to specify the level of the structure that is passed in as the second parameter.

• The second parameter into the function is a void pointer to the primary interface structure for the API. Each element in the structure is either an atomic type (for example, db2Long32) or a pointer. Each parameter name adheres to the following naming conventions:

     piCamelCase  - pointer to input data
     poCamelCase  - pointer to output data
     pioCamelCase - pointer to input or output data 
     iCamelCase   - integral input data
     ioCamelCase  - integral input/output data
     oCamelCase   - integral output data area
  

• The third parameter is a pointer to the SQLCA, and is mandatory.

Generic API Syntax

The syntax of the API call for the COBOL and FORTRAN programming languages.

Attention: Provide one extra byte for every character string passed to an API. Failure to do so may cause unexpected errors. This extra byte is modified by the database manager.

API Parameters

A description of each API parameter and its values. Predefined values are listed with the appropriate symbolics. Actual values for symbolics can be obtained from the appropriate language include files. COBOL programmers should substitute a hyphen (-) for the underscore (_) in all symbolics. For more information about parameter data types in each host language, see the sample programs.

Note:

Applications calling database manager APIs must properly check for error conditions by examining return codes and the SQLCA structure. Most database manager APIs return a zero return code when successful. In general, a non-zero return code indicates that the secondary error handling mechanism, the SQLCA structure, may be corrupt. In this case, the called API is not executed. A possible cause for a corrupt SQLCA structure is passing an invalid address for the structure. Error information is returned in the SQLCODE and SQLSTATE fields of the SQLCA structure, which is updated after most database manager API calls. Source files calling database manager APIs can provide one or more SQLCA structures; their names are arbitrary. An SQLCODE value of zero means successful execution (with possible SQLWARN warning conditions). A positive value means that the statement was successfully executed but with a warning, as with truncation of a host variable. A negative value means that an error condition occurred. An additional field, SQLSTATE, contains a standardized error code that is consistent across other IBM database products, and across SQL92 compliant database managers. Use SQLSTATEs when concerned about portability, since SQLSTATEs are common across many database managers. The SQLWARN field contains an array of warning indicators, even if SQLCODE is zero.

REXX API Syntax

The REXX syntax of the API call, where appropriate.

A new interface, SQLDB2, has been added to support calling APIs from REXX. The SQLDB2 interface was created to provide support in REXX for new or previously unsupported APIs that do not have any output other than the SQLCA. Invoking a command through the SQLDB2 interface is syntactically the same as invoking the command through the command line processor (CLP), except that the token call db2 is replaced by CALL SQLDB2. Using the CALL SQLDB2 from REXX has the following advantages over calling the CLP directly:

• The compound REXX variable SQLCA is set

• By default, all CLP output messages are turned off.

For more information about the SQLDB2 interface, see the Application Development Guide.

REXX API Parameters

A description of each REXX API parameter and its values, where appropriate.

Sample Programs

The location and the names of sample programs illustrating the use of the API in one or more supported languages (C, COBOL, FORTRAN, and REXX).

Usage Notes

Other information.

See Also

A cross-reference to related information.

[ DB2 List of Books | Search the DB2 Books ]