System Monitor Guide and Reference

sqlmonsz - 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 or database:

• If there is neither an attachment to an instance, nor a connection to a database, a default instance attachment is created.

• If there is both an attachment to an instance, and a database connection, the instance attachment is used.

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

sqlmon.h

C API Syntax

/* File: sqlmon.h */ /* API: Estimate Size Required for sqlmonss() Output Buffer */ /* ... */ int SQL_API_FN sqlmonsz ( unsigned long version, _SQLOLDCHAR *reserved, sqlma *sqlma_ptr, unsigned long *buff_size, struct sqlca *sqlca); /* ... */

Generic API Syntax

/* File: sqlmon.h */ /* API: Estimate Size Required for sqlmonss() Output Buffer */ /* ... */ int SQL_API_FN sqlgmnsz ( unsigned long reserved_lgth, struct sqlca *sqlca, unsigned long *buff_size, sqlma *sqlma_ptr, _SQLOLDCHAR *reserved, unsigned long version); /* ... */

API Parameters

reserved_lgth

Reserved for future use. This value should be set to zero.

sqlca

Output. A pointer to the sqlca structure.

buff_size

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

sqlma_ptr

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.

reserved

Reserved for future use. Must be set to NULL.

version

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

Note:

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

Sample Programs

C

\sqllib\samples\c\db2mon.c

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 sqlmonsz.

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.

See Also

sqlmon - Get/Update Monitor Switches

db2GetSnapshot - Get Snapshot

sqlmrset - Reset Monitor.

[ DB2 List of Books | Search the DB2 Books ]