Administrative API Reference

db2GetSnapshotSize - Estimate Size Required for db2GetSnapshot() Output Buffer

Estimates the buffer size needed by db2GetSnapshot - Get Snapshot.

Scope

This API only affects the instance to which the calling application is attached.

Authorization

One of the following:

• sysadm
• sysctrl
• sysmaint

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.

Version

db2ApiDf.h

C API Syntax

int db2GetSnapshotSize(db2Uint32	version,    	
			    void* 	pParamStruct,
			    struct sqlca* sqlca);
 
typedef struct
{
        struct sqlma                    *piSqlmaData;
        sqluint32                       *poBufferSize;
        db2Uint32                       iVersion;
        db2int32                        iNodeNumber;			
}db2GetSnapshotSizeData;
/* ...*/

API Parameters

version

Input. Specifies the version and release level of the structure passed as the second parameter pParamStruct.

pParamStruct

Input. A pointer to the db2GetSnapshotSizeStruct structure.

sqlca

Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

piSqlmaData

Input. Pointer to the user-allocated sqlma (monitor area) structure. This structure specifies the type(s) of snapshot data to be collected, and can be reused as input to db2GetSnapshot - Get Snapshot. For more information about this structure, see SQLMA.

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

Note:

If SQLM_DBMON_VERSION1 is specified as the version, the APIs cannot be run remotely.

iNodeNumber

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

• SQLM_CURRENT_NODE
• SQLM_ALL_NODES
• node value

Note:

For stand-alone instances SQLM_CURRENT_NODE must be used.

Usage Notes

This function generates a significant amount of overhead. Allocating and freeing memory dynamically for each db2GetSnapshot 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 - Get Snapshot. 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.

For detailed information about the use of the database monitor APIs, and for a summary of all database monitor data elements and monitoring groups, see the System Monitor Guide and Reference.

See Also

db2MonitorSwitches - Get/Update Monitor Switches

db2GetSnapshot - Get Snapshot

db2ResetMonitor - Reset Monitor.