Setting system monitor switches from a client application

System monitor switches control the collection of data by the system monitor. By setting certain monitor switches to ON, you can collect specific types of monitor data.

Before you begin

The application performing any monitor switch updates must have an instance attachment. You must have SYSADM, SYSCTRL, SYSMAINT, or SYSMON authority to use the db2MonitorSwitches API.

Procedure

  1. Include the database libraries sqlutil.h and db2ApiDf.h, which are located in the include subdirectory under sqllib.
    #include <sqlutil.h>
    #include <db2ApiDf.h>
    #include <string.h>
    #include <sqlmon.h>
    
  2. Set switch lists buffer unit size to 1 KB.
    #define SWITCHES_BUFFER_UNIT_SZ 1024
  3. Initialize the sqlca, db2MonitorSwitches, and sqlm_recording_group structures. Also, initialize a pointer to contain the switch lists buffer, and establish the buffer's size.
    struct sqlca sqlca;
    memset (&sqlca, '\0', sizeof(struct sqlca));
    db2MonitorSwitchesData switchesData;
    memset (&switchesData, '\0', sizeof(switchesData));
    struct sqlm_recording_group switchesList[SQLM_NUM_GROUPS];
    memset(switchesList, '\0', sizeof(switchesList));
    sqluint32 outputFormat;
    static sqluint32 switchesBufferSize = SWITCHES_BUFFER_UNIT_SZ;
    char *switchesBuffer;
  4. Initialize the buffer, which is to hold the switch list output.
    switchesBuffer = (char *)malloc(switchesBufferSize);
    memset(switchesBuffer, '\0', switchesBufferSize));
  5. To alter the state of the local monitor switches, alter the elements in the sqlm_recording_group structure (named switchesList as indicated in the previous step). For a monitor switch to be turned on, the parameter input_state is to be set to SQLM_ON. For a monitor switch to be turned off, the parameter input_state must be set to SQLM_OFF.
    switchesList[SQLM_UOW_SW].input_state = SQLM_ON;
    switchesList[SQLM_STATEMENT_SW].input_state = SQLM_ON;
    switchesList[SQLM_TABLE_SW].input_state = SQLM_ON;
    switchesList[SQLM_BUFFER_POOL_SW].input_state = SQLM_OFF;
    switchesList[SQLM_LOCK_SW].input_state = SQLM_OFF;
    switchesList[SQLM_SORT_SW].input_state = SQLM_OFF;
    switchesList[SQLM_TIMESTAMP_SW].input_state = SQLM_OFF;
    switchesData.piGroupStates = switchesList;
    switchesData.poBuffer = switchesBuffer;
    switchesData.iVersion = SQLM_DBMON_VERSION9_5;
    switchesData.iBufferSize = switchesBufferSize;
    switchesData.iReturnData = 0;
    switchesData.iNodeNumber = SQLM_CURRENT_NODE;
    switchesData.poOutputFormat = &outputFormat;
    Note: SQLM_TIMESTAMP_SW is unavailable if iVersion is less than SQLM_DBMON_VERSION8.
  6. To submit the changes to switch settings, call the db2MonitorSwitches() function. Pass the db2MonitorSwitchesData structure (named switchesData in this example) as a parameter to the db2MonitorSwitches API. The switchesData contains the sqlm_recording_group structure as a parameter.
    db2MonitorSwitches(db2Version810, &switchesData, &sqlca);
  7. Process the switch list data stream from the switch list buffer.
  8. Clear the switch list buffer.
    free(switchesBuffer);
    free(pRequestedDataGroups);

Results

Now that you have set the required monitor switches and confirmed the switch settings, you are ready to capture and collect monitor data.