Administrative API Reference

db2GetSnapshot - Get Snapshot

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 returns information only for the node on which it is issued.

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

Version

db2ApiDf.h

C API Syntax

int db2GetSnapshot(	unsigned char		version;	
			db2GetSnapshotData *data,            
			struct sqlca 		*sqlca; 	
 
The parameters described in data are:
typedef struct db2GetSnapshotData{
  sqlma 		*piSqlmaData;
  sqlm_collected 	*poCollectedData
  void 			*poBuffer;
  db2uint32		iVersion;
  db2int32		iBufferSize;
  db2uint8		iStoreResult;
db2uint16		iNodeNumber;
db2uint32		*poOutputFormat;
 
}db2GetSnapshotData;

API Parameters

version

Input. Specifies the version and release level of the structure passed in as the second parameter, data.

data

Input/Output. A pointer to the db2GetSnapshotData structure.

pSqlca

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 data to be collected. For more information, see SQLMA.

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. For more information about this structure, see SQLM-COLLECTED.

Note:

This structure is only used for pre-Version 6 data streams. However, if a snapshot call is made to a back-level 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. For information about interpreting the data returned in this buffer, see the System Monitor Guide and Reference.

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.

iBufferSize

Input. The length of the data buffer. Use db2GetSnapshotSize - Estimate Size Required for db2GetSnapshot() Output Buffer 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 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
• node value

Note:

For standalone instances SQLM_CURRENT_NODE must be used.

poOutputFormat

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

• SQLM_STREAM_STATIC_FORMAT
• SQLM_STREAM_DYNAMIC_FORMAT

Usage Notes

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

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

db2ConvMonStream

db2MonitorSwitches - Get/Update Monitor Switches

db2GetSnapshotSize - Estimate Size Required for db2GetSnapshot() Output Buffer

db2ResetMonitor - Reset Monitor.