How the API descriptions are organized

This section provides information about 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-partition database environment, the scope is that single database partition only. In a partitioned database environment, the scope can be the collection of all logical database partition servers defined in the node configuration file (db2nodes.cfg) or the database partition from which the API is called.

Authorization

The authority required to successfully call the API.

Required connection

One of the following requirements: database, instance, none, or establishes a connection. Indicates whether the function requires a database connection, an instance attachment, or no connection to operate successfully.

None means that no database connection is required in order for the API to work successfully. Establishes a connection means that the API will establish a connection to the database when the API is called.

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.

API include file

The name of the include file that contains the API prototype, and any necessary predefined constants and parameters.
Note: Include file extensions vary with programming language. C/C++ include files have a file extension of .h. COBOL include files have a file extension of .cbl. The include files can be found in the following directories:
C/C++ (UNIX):
sqllib/include
C/C++ (Windows):
sqllib\include
COBOL (UNIX):
sqllib/include/cobol_a

sqllib/include/cobol_i

sqllib/include/cobol_mf

COBOL (Windows):
sqllib\include\cobol_a

sqllib\include\cobol_i

sqllib\include\cobol_mf

C API syntax

The C syntax of the API call.

Since Version 6, a new standard has been 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 "db2g", followed by a string that matches the C API name. Data structures used by generic APIs have names that also contain the prefix "db2g".
  • The first parameter into the function (versionNumber) 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   - input data
   ioCamelCase  - input/output data
   oCamelCase   - output data
  • 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.

The SQLDB2 interface supports 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.

REXX API parameters

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