DB2 Version 10.1 for Linux, UNIX, and Windows

db2MonitorSwitches API - Get or update the monitor switch settings

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 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 display the settings for 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
  db2MonitorSwitches (
   db2Uint32 versionNumber,
   void * pParmStruct,
   struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2MonitorSwitchesData
{
   struct sqlm_recording_group *piGroupStates;
   void *poBuffer;
   db2Uint32 iBufferSize;
   db2Uint32 iReturnData;
   db2Uint32 iVersion;
   db2int32 iNodeNumber;
   db2Uint32 *poOutputFormat;
} db2MonitorSwitchesData;

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

typedef SQL_STRUCTURE db2gMonitorSwitchesData
{
   struct sqlm_recording_group *piGroupStates;
   void *poBuffer;
   db2Uint32 iBufferSize;
   db2Uint32 iReturnData;
   db2Uint32 iVersion;
   db2int32 iNodeNumber;
   db2Uint32 *poOutputFormat;
} db2gMonitorSwitchesData;

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

db2MonitorSwitchesData data structure parameters

piGroupStates

Input. A pointer to the sqlm-recording-group structure (defined in sqlmon.h) containing a list of switches.

poBuffer

A pointer to a buffer where the switch state data will be written.

iBufferSize

Input. Specifies the size of the output buffer.

iReturnData

Input. A flag specifying whether or not the current switch states should be written to the data buffer pointed to by poBuffer.

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
SQLM_DBMON_VERSION8
SQLM_DBMON_VERSION9
SQLM_DBMON_VERSION9_5

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

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

iNodeNumber

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

SQLM_CURRENT_NODE
SQLM_ALL_NODES
node value

Note: For stand-alone instances SQLM_CURRENT_NODE 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: Indicates that the switch states are returned in static, pre-Version 7 switch structures.
SQLM_STREAM_DYNAMIC_FORMAT: Indicates that the switches are returned in a self-describing format, similar to the format returned for db2GetSnapshot.

Usage notes

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

The timestamp switch is unavailable if iVersion is less than SQLM_DBMON_VERSION8.