版本注意事項

37.3 db2DatabasePing (new API)

db2DatabasePing - Ping Database

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

C API Syntax

      /* File: db2ApiDf.h */
   /* API: Ping Database */
   /* ... */
 
 
   SQL_API_RC SQL_API_FN
     db2DatabasePing (
         db2Uint32     VersionNumber, 
         void         *pParmStruct,   
         struct sqlca *pSqlca);        
   /* ... */
 
   typedef SQL_STRUCTURE db2DatabasePingStruct
   {
     char          iDbAlias[SQL_ALIAS_SZ + 1];  
     db2Uint16     iNumIterations;    
     db2Uint32    *poElapsedTime;      
   }

Generic API Syntax

   /* File: db2ApiDf.h */
   /* API: Ping Database */
   /* ... */
   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]; 
     db2Uint16     iNumIterations;    
     db2Uint32    *poElapsedTime;      
   }

API Parameters

VersionNumber

Input. Version and release of the DB2 Universal Database or DB2 Connect product that the application is using.

Note:

Constant db2Version710 or higher should be used for DB2 Version 7.1 or higher.

|pParmStruct

Input. A pointer to the db2DatabasePingStruct Structure.

iDbAliasLength

Input. Length of the database alias name.

Note:

This parameter is not currently used. It is reserved for future use.

iDbAlias

Input. Database alias name.

Note:

This parameter is not currently used. It is reserved for future use.

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 prior to calling this API.

pSqlca

Output. A pointer to the sqlca structure. For more information about this structure, see the Administrative API Reference.

Usage Notes

A database connection must exist before invoking this API, otherwise an error will result.

This function can also be invoked using the PING command. For a description of this command, see the Command Reference.