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.