Administrative API Reference

sqlmon - Get/Update Monitor Switches

Selectively turns on or off switches for groups of monitor data to be collected by the database manager. Returns the current state of these switches for the application issuing the call.

Scope

This API only returns information for the node on which it is executed.

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 display the settings for a remote instance, or for a different local instance, it is necessary to first attach to that instance.

Version

sqlmon.h

C API Syntax

/* File: sqlmon.h */ /* API: Get/Update Monitor Switches */ /* ... */ int SQL_API_FN sqlmon ( unsigned long version, _SQLOLDCHAR *reserved, sqlm_recording_group group_states[], struct sqlca *sqlca); /* ... */

Generic API Syntax

/* File: sqlmon.h */ /* API: Get/Update Monitor Switches */ /* ... */ int SQL_API_FN sqlgmon ( unsigned long reserved_lgth, struct sqlca *sqlca, sqlm_recording_group group_states[], _SQLOLDCHAR *reserved, unsigned long version); /* ... */

API Parameters

reserved_lgth

Reserved for future use. Users should set this value to zero.

sqlca

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

group_states

Input/Output. Pointer to an array of size SQLM_NUM_GROUPS (6). If the array size is less than six, an error message is returned. The user determines which element of the array corresponds to which switch by indexing it to the following symbolic statements (defined in sqlmon.h):

• SQLM_UOW_SW

• SQLM_STATEMENT_SW

• SQLM_TABLE_SW

• SQLM_BUFFER_POOL_SW

• SQLM_LOCK_SW

• SQLM_SORT_SW.

The array contains the following elements:

• An input_state element set to one of the following (defined in sqlmon.h):

  SQLM_ON

  Turns information group on.

  SQLM_OFF

  Turns information group off.

  SQLM_HOLD

  Leaves information group in its current state.

• An output_state element, containing current state information about the information group being monitored, is returned. SQLM_ON and SQLM_OFF indicate the state.

• A start_time element, indicating the time that the monitored group was turned on, is returned. If monitoring of this group is turned off, the time stamp is zero.

For more information about the sqlm_recording_group structure, see SQLM-RECORDING-GROUP, or the System Monitor Guide and Reference.

reserved

Reserved for future use. Users should set this value 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

If requesting data for a version higher than the current server, the database monitor only returns data for its level (see the server_version field in the "collected" portion of the data stream.

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

To obtain the status of the switches at the database manager level, call db2GetSnapshot - Get Snapshot, specifying SQMA_DB2 for OBJ_TYPE (get snapshot for database manager).

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

db2GetSnapshot - Get Snapshot

sqlmonsz - Estimate Size Required for sqlmonss() Output Buffer

sqlmrset - Reset Monitor.

[ DB2 List of Books | Search the DB2 Books ]