db2DatabasePing API - Ping the database to test network response time

Tests the network response time of the underlying connectivity between a client and a database server. This API can be used by an application when a host database server is accessed via Db2 Connect either directly or through a gateway.

Authorization

None

Required connection

Database

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  db2DatabasePing (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2DatabasePingStruct
{
   char iDbAlias[SQL_ALIAS_SZ + 1];
   db2int32 RequestPacketSz;
   db2int32 ResponsePacketSz;
   db2Uint16 iNumIterations;
   db2Uint32 *poElapsedTime;
} db2DatabasePingStruct;

SQL_API_RC SQL_API_FN
  db2gDatabasePing (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2gDatabasePingStruct
{
   db2Uint16 iDbAliasLength;
   char iDbAlias[SQL_ALIAS_SZ + 1];
   db2int32 RequestPacketSz;
   db2int32 ResponsePacketSz;
   db2Uint16 iNumIterations;
   db2Uint32 *poElapsedTime;
} db2gDatabasePingStruct;

db2DatabasePing API parameters

versionNumber: Input. Specifies the version and release of the Db2® database or Db2 Connect product that the application is using.
pParmStruct: Input. A pointer to the db2DatabasePingStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2DatabasePingStruct data structure parameters

iDbAlias: Input. Database alias name. Reserved for future use. If a value is provided, it is ignored.
RequestPacketSz: Input. Size of the packet (in bytes) to be sent to the server. The size must be between 0 and 32767 inclusive. This parameter is only valid on servers running Db2 Version 8 or higher, or Db2 for z/OS® Version 8 or higher.
ResponsePacketSz: Input. Size of the packet (in bytes) to be returned back to client. The size must be between 0 and 32767 inclusive. This parameter is only valid on servers running Db2 Version 8 or higher, or Db2 for z/OS Version 8 or higher.
iNumIterations: Input. Number of test request iterations. The value must be between 1 and 32767 inclusive.
poElapsedTime: Output. A pointer to an array of 32-bit integers where the number of elements is equal to iNumIterations. Each element in the array will contain the elapsed time in microseconds for one test request iteration.
Note: The application is responsible for allocating the memory for this array before calling this API.

db2gDatabasePingStruct data structure specific parameters

iDbAliasLength: Input. Length of the database alias name. Reserved for future use.

Usage notes

This API will not work when it is used from a Db2 Version 7 client through a Db2 Connect Version 8 to a connected Db2 host database server.