DB2 10.5 for Linux, UNIX, and Windows

db2GetSnapshotSize API - Estimate the output buffer size required for the db2GetSnapshot API

Estimates the buffer size needed by the db2GetSnapshot API.

Scope

This API can either affect the database partition server on the instance, or all database partitions on the instance.

Authorization

One of the following authorities:

SYSADM
SYSCTRL
SYSMAINT
SYSMON

Required connection

Instance. If there is no instance attachment, a default instance attachment is created.

To obtain information from a remote instance (or a different local instance), it is necessary to first attach to that instance. If an attachment does not exist, an implicit instance attachment is made to the node specified by the DB2INSTANCE environment variable.

API include file

db2ApiDf.h

API and data structure syntax

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

typedef SQL_STRUCTURE db2GetSnapshotSizeData
{
   void *piSqlmaData;
   sqluint32 *poBufferSize;
   db2Uint32 iVersion;
   db2int32 iNodeNumber;
   db2Uint32 iSnapshotClass;
} db2GetSnapshotSizeData;

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

typedef SQL_STRUCTURE db2gGetSnapshotSizeData
{
   void *piSqlmaData;
   sqluint32 *poBufferSize;
   db2Uint32 iVersion;
   db2int32 iNodeNumber;
   db2Uint32 iSnapshotClass;
} db2gGetSnapshotSizeData;

db2GetSnapshotSize API parameters

versionNumber: Input. Specifies the version and release level of the structure passed as the second parameter pParmStruct. To use the structure as described previously, specify db2Version810 or newer. If you want to use a different version of this structure, check the db2ApiDf.h header file in the include directory for the complete list of supported versions. Ensure that you use the version of the db2GetSnapshotSizeStruct structure that corresponds to the version number that you specify.
pParmStruct: Input. A pointer to the db2GetSnapshotSizeStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2GetSnapshotSizeData data structure parameters

piSqlmaData

Input. Pointer to the user-allocated sqlma (monitor area) structure or request data structure, "poRequestData" constructed and returned by the db2AddSnapshotRequest API. The structure specifies the type or types of snapshot data to be collected. If a pointer to the sqlma structure is used, the version passed to the db2GetSnapshotSize API in the versionNumber parameter should be less than db2Version900 (for example, db2Version810, db2Version822). If a pointer to the request data structure returned by the db2AddSnapshotRequest API in poRequestData parameter is used then the value db2Version900 should be passed in the versionNumber parameter of the db2GetSnapshotSize API.

poBufferSize

Output. A pointer to the returned estimated buffer size needed by the GET SNAPSHOT API.

iVersion

Input. Version ID of the database monitor data to collect. The database monitor only returns data that was available for the requested version. Set this parameter to one of the following symbolic constants:

SQLM_DBMON_VERSION1
SQLM_DBMON_VERSION2
SQLM_DBMON_VERSION5
SQLM_DBMON_VERSION5_2
SQLM_DBMON_VERSION6
SQLM_DBMON_VERSION7
SQLM_DBMON_VERSION8
SQLM_DBMON_VERSION9
SQLM_DBMON_VERSION9_5

Note: Constants SQLM_DBMON_VERSION5_2, and earlier, are deprecated and may be removed in a future release of DB2®.

iNodeNumber

Input. The database partition server where the request is to be sent. Based on this value, the request will be processed for the current database partition server, all database partition servers, or a user specified database partition server. Valid values are:

SQLM_CURRENT_NODE
SQLM_ALL_NODES. Only allowed when iVersion is set to SQLM_DBMON_VERSION7 or newer.
node value

For stand-alone instances, the value, SQLM_CURRENT_NODE must be used.

iSnapshotClass

Input. The class qualifier for the snapshot. Valid values (defined in sqlmon header file, located in the include directory) are:

SQLM_CLASS_DEFAULT for a standard snapshot
SQLM_CLASS_HEALTH for a health snapshot
SQLM_CLASS_HEALTH_WITH_DETAIL for a health snapshot including additional details

Usage notes

This function generates a significant amount of additional processing usage. Allocating and freeing memory dynamically for each db2GetSnapshot API call is also expensive. If calling db2GetSnapshot repeatedly, for example, when sampling data over a period of time, it may be preferable to allocate a buffer of fixed size, rather than call db2GetSnapshotSize.

If the database system monitor finds no active databases or applications, it may return a buffer size of zero (if, for example, lock information related to a database that is not active is requested). Verify that the estimated buffer size returned by this API is non-zero before calling db2GetSnapshot. If an error is returned by db2GetSnapshot because of insufficient buffer space to hold the output, call this API again to determine the new size requirements.