DB2 Version 10.1 for Linux, UNIX, and Windows

db2GetSnapshot API - Get a snapshot of the database manager operational status

Collects database manager monitor information and returns it to a user-allocated data buffer. The information returned represents a snapshot of the database manager operational status at the time the API was called.

Scope

This API can return information for 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 a snapshot from a remote instance (or a different local instance), it is necessary to first attach to that instance.

API include file

db2ApiDf.h

API and data structure syntax

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

typedef SQL_STRUCTURE db2GetSnapshotData
{
   void *piSqlmaData;
   struct sqlm_collected *poCollectedData;
   void *poBuffer;
   db2Uint32 iVersion;
   db2Uint32 iBufferSize;
   db2Uint32 iStoreResult;
   db2int32 iNodeNumber;
   db2Uint32 *poOutputFormat;
   db2Uint32 iSnapshotClass;
} db2GetSnapshotData;

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

typedef SQL_STRUCTURE db2gGetSnapshotData
{
   void *piSqlmaData;
   struct sqlm_collected *poCollectedData;
   void *poBuffer;
   db2Uint32 iVersion;
   db2Uint32 iBufferSize;
   db2Uint32 iStoreResult;
   db2int32 iNodeNumber;
   db2Uint32 *poOutputFormat;
   db2Uint32 iSnapshotClass;
} db2gGetSnapshotData;

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 db2GetSnapshotData structure that corresponds to the version number that you specify.
pParmStruct: Input/Output. A pointer to the db2GetSnapshotData structure.
pSqlca: Output. A pointer to the sqlca structure.

db2GetSnapshotData 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 db2GetSnapshot 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 db2GetSnapshot API.

poCollectedData

Output. A pointer to the sqlm_collected structure into which the database monitor delivers summary statistics and the number of each type of data structure returned in the buffer area.

Note: This structure is only used for pre-Version 6 data streams. However, if a snapshot call is made to an earlier remote server, this structure must be passed in for results to be processed. It is therefore recommended that this parameter always be passed in.

poBuffer

Output. Pointer to the user-defined data area into which the snapshot information will be returned.

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 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
SQLM_DBMON_VERSION9_7 (required for information about reclaiming MDC extents through a reorganization)
SQLM_DBMON_VERSION10 (required for information about reclaiming ITC extents through a reorganization)

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

iBufferSize

Input. The length of the data buffer. Use the db2GetSnapshotSize API to estimate the size of this buffer. If the buffer is not large enough, a warning is returned, along with the information that will fit in the assigned buffer. It may be necessary to resize the buffer and call the API again.

iStoreResult

Input. An indicator set to constant value TRUE or FALSE, depending on whether the snapshot results are to be stored at the DB2 server for viewing through SQL. This parameter should only be set to TRUE when the snapshot is being taken over a database connection, and when one of the snapshot types in the sqlma is SQLMA_DYNAMIC_SQL.

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. Only allowed when the iVersion parameter is set to SQLM_DBMON_VERSION7 or newer.
node value

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

poOutputFormat

The format of the stream returned by the server. It will be one of the following values:

SQLM_STREAM_STATIC_FORMAT
SQLM_STREAM_DYNAMIC_FORMAT

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

Note: SQLM_CLASS_HEALTH and SQLM_CLASS_HEALTH_WITH_DETAIL have been deprecated and might be removed in a future release because the health monitor was deprecated in Version 9.7.

Usage notes

If an alias for a database residing at a different instance is specified, an error message is returned.

To retrieve a health snapshot with full collection information, use the AGENT_ID field in the SQLMA data structure.