Home

	Expand Search

Adaptive Server Enterprise Monitor Client-Library Programmer's Guide

Chapter 1: Getting Started with Monitor Client Library

Writing a Basic Monitor Client Library Program

Writing a Basic Monitor Client Library Program

A basic Monitor Client Library application does the following:

1. Define error handling.

2. Connect to a server using the following steps.
   • Allocate a connection.
   • Set properties on a connection.
   • Connect to a server.
3. Create one or more views that define the performance data to be monitored.

4. Optionally, target specific performance data values with filters.

5. Optionally, set alarms on performance data values.

6. Request performance data values.

7. Process the results.

8. Close the connection to the server.

9. Deallocate the connection or reuse it by reconnecting.

   Note: You must have the System Administrator role on Adaptive Server or execute permission on the stored procedure mon_rpc_connect to perform monitoring.

Application Logic Flow

Most Monitor Client Library applications exhibit a logic flow similar to the following:

    allocate a connection
    set properties on the connection
    connect
    loop to create views on the connection
    loop to create filters (optional)
    loop to create alarms (optional)
    loop to refresh connection 
        for each view 
            get the row count
            for each row
                for each column
                    get the data
                    display the data
    loop to drop alarms (optional)
    loop to drop filters (optional)
    loop to drop views (optional)
    close monitor connection
    deallocate or reuse connection

where:

• An application can have any number of connections.
• A connection can have one or more views.
• A view must have one or more data items.
• A view can have one filter per data item.
• A view can have any number of alarms and can have multiple alarms per data item in the view.

The following sections describe the steps for a basic Monitor Client Library program.The steps are cross referenced to the sample program that follows them.

Step 1: Define error handling

An application uses one or more callback routines to handle Monitor Client Library and Server error and informational messages.

See the code sample at ** Callback functions.

Step 2: Connect to a Server

The Monitor Client Library functions require establishing an Adaptive Server Enterprise Monitor connection. The Adaptive Server Enterprise Monitor connection uses one or more Open Client connections depending upon the connection type.

The two types of Monitor connections are Live mode and Historical mode:

• Live mode connects to Monitor Server and Adaptive Server. It provides access to performance data.
• Historical mode connects to Historical Server and either records performance data for later access or plays back recorded data.

Connecting to a server is a three-step process. An application:

• Allocates a connection structure
• Sets properties for the connection, if necessary
• Logs into a server

Allocating a Connection Structure

An application calls smc_connect_alloc to allocate a connection structure.

See the code sample at ** Allocate first connection.

Setting Connection Structure Properties

An application calls smc_connect_props to set, retrieve, or clear connection structure properties.

Connection properties define various aspects of a connection's behavior. For example:

• The SMC_PROP_USERNAME property defines the username that a connection will use when logging into a server.
• The SMC_PROP_PASSWORD property specifies the password for the username.
• The SMC_PROP_SERVERNAME property defines the server for this connection.
• The SMC_PROP_IFILE property defines the INTERFACES FILE NAME for this connection. If you don't specify this property on a UNIX system, the default file interfaces in the SYBASE environment variable directory is used. On Windows NT, the default interfaces file is sql.ini.
• The SMC_PROP_SERVERMODE property defines the type of connection: live or historical.

Required Connection Properties

As a minimum, an application must set the connection properties that specify the connection's username (SMC_PROP_USERNAME) and allow the server to authenticate the user's identity by requiring a valid password. If the server requires a password, then the application must set the SMC_PROP_PASSWORD property to the value of the user's server password.

See the code sample at ** Set mandatory and some optional connection properties.

Connecting to a Server

An application calls smc_connect_ex to connect to a server. In the process of establishing a connection, smc_connect_ex sets up communication with the network, logs in to the server, and communicates any connection-specific property information to the server. A connection to Adaptive Server writes dbcc traceon messages to the Adaptive Server error log. You can ignore these messages.

For example, if the server supports network-based user authentication and the client application requests it, then Client Library and the server query the network's security system to see if the user (whose name is specified by SMC_PROP_USERNAME) is logged in to the network.

See the code sample at ** Connect to monitor server.

Step 3: Create a View

Views are defined groups of data items. The data items specified determine how the data is summarized. Since you can specify multiple views, the application has full flexibility in the gathering of data. For example, a view consisting of two data items (device name, value for sample and device I/O, rate for sample) returns the device I/O rate for each database device.

For examples of view, refer to Appendix A, "Examples of Views".

Data Items

A data item is a particular piece of data that can be obtained from the Monitor Client Library, for example, page I/O, login name, device reads, and so on. For each data item in a view, you must specify a statistical type.

Statistical Types

The statistic type defines the duration of the data item (sample or session) and whether the server performs calculations on the data item.

The six statistic types are:

• SMC_STAT_VALUE_SAMPLE - This statistic type returns a count of activity or some type of information that applies to the most recent sample interval. No calculations are performed.
  • Activity Counts - For data items that represent activity counts, SMC_STAT_VALUE_SAMPLE returns the number of occurrences of an activity during the most recent sample interval. For example, SMC_STAT_VALUE_SAMPLE for SMC_NAME_PAGE_IO is the number of page I/Os that occurred during the most recent sample interval.
  • Other information - This is the only statistic type valid for data items that represent character strings. For example, SMC_STAT_VALUE_SAMPLE for SMC_NAME_OBJECT_NAME returns the name of a database object. This statistic type is also the only one valid for data items that represent values such as IDs and values for configured parameters, on which calculations are never performed.
• SMC_STAT_VALUE_SESSION - This statistic type returns a cumulative count of activity since the start of gathering the data (since the connection was opened). No calculations are performed. For example, SMC_STAT_VALUE_SESSION for SMC_NAME_PAGE_IO is the number of page I/Os that occurred since the session started.
• SMC_STAT_RATE_SAMPLE - This statistic type calculates a rate per second. It returns the average number of occurrences per second of an activity during the most recent sample interval. For example, SMC_STAT_RATE_SAMPLE for SMC_NAME_PAGE_IO is the average number of page I/Os that occurred each second during the most recent sample interval.

  The calculation is:

• SMC_STAT_RATE_SESSION - This statistic type calculates a rate per second. It returns the average number of occurrences per second of an activity during the current session. For example, SMC_STAT_RATE_SESSION for SMC_NAME_PAGE_IO is the average number of page I/Os that occurred per second since the session started.

  The calculation is:

• SMC_STAT_AVG_SAMPLE - This statistic type calculates an average value per occurrence of an activity over the most recent sample interval. Only a few data items can use this statistic type. The meaning of the returned value depends on the data item name. For example, SMC_STAT_AVG_SAMPLE for SMC_NAME_STP_ELAPSED_TIME is the average execution time per execution of a stored procedure during the most recent sample interval.
• SMC_STAT_AVG_SESSION - This statistic type calculates an average value per occurrence of an activity over the session. Only a few data items can use this statistic type. The meaning of the returned value depends on the data item name. For example, SMC_STAT_AVG_SESSION for SMC_NAME_STP_ELAPSED_TIME is the average execution time per execution of a stored procedure during the recording session.

Creating Views for a Connection

smc_create_view creates a view on a particular Monitor connection. A connection must have at least one view.

For details on valid combinations of data items and information about how data items are summarized, see Chapter 2, "Data Items and Statistical Types.".

You can think of a view as a table. The data items in a view are represented by the columns in that table. The number of rows returned for a particular view depend upon the particular data items in the view. For example, a view with server-wide data returns a single row, whereas a view with per-device data returns one row for each device.

For example:

A view consisting of two data items:

SMC_NAME_LOCK_TYPE, SMC_STAT_VALUE_SAMPLE

SMC_NAME_LOCK_COUNT, SMC_STAT_RATE_SAMPLE

returns the rate of requested locks for each lock type during the sample interval.

A view consisting of one data item:

SMC_NAME_LOCK_COUNT, SMC_STAT_RATE_SAMPLE

returns the rate of requested locks summarized for all lock types during the sample interval.

For complete details on valid combinations of data items and understanding of how data items are summarized, refer to Chapter 2, "Data Items and Statistical Types."

See the code sample at ** Define views.

Step 4: Create Filters

smc_create_filter creates a filter on a data item. Filters limit the number of rows of performance data returned by a view. A filter can be applied to any data item specified in a view. A view can contain one filter per data item. If you include more than one filter in a view, Monitor Client Library ANDs those filters.

The types of filters available are:

• Equal to
  • returns only values equal to one of the specified values (logical OR of each Equal comparison)
• Not Equal to
  • returns only values equal to none of the specified value (logical AND of each Not-Equal comparison)
• Greater than or equal to
  • returns values greater than or equal to the specified value
• Less than or equal to
  • returns values less than or equal to the specified value
• Range: bottom <= value <= top
  • returns values between the top and bottom values, inclusive
• Top N
  • returns the N highest values

A view may contain more than one filter, but any particular data item may only have one filter bound to it. When a view contains more than one filter, the filters are combined with an AND.

You can add or drop filters at any time. The change in filtering takes effect as of the next refresh.

See the code sample at ** Create a filter.

Step 5: Set Alarms

smc_create_alarm_ex sets an alarm on any numeric data item (except for IDs) in a view. When specifying an alarm for a particular data item in a live connection, an application supplies a callback function that is invoked when the alarm is triggered.

The Historical Server cannot call a callback function, but it can write to a log file or execute a procedure each time an alarm is triggered.

An example of the type of actions an application can execute upon the triggering of an alarm is to log a message, which is one of the features provided by Historical Server.

You can add or drop an alarm at any time. The change in alarm specification takes effect as of the next refresh.

Note: Monitor Client Library applies alarms after it applies filters.

See the code sample at ** Set alarms.

Step 6: Request Performance Data and Process Results

After all of the connections, views, alarms, and filters are created, an application requests values for performance data. Retrieving performance data is a three-step process:

• Refresh the data
• Check the row count
• Look at each data item in the view

When a Monitor Client Library application needs to retrieve data, it initiates a refresh. The refresh causes Monitor Client Library to obtain fresh data. After each refresh, the application retrieves the data in each view on an item-by-item basis (that is, for each column of a table).

After calling smc_refresh_ex on a given connection, the application retrieves the data. The user retrieves data on an item-by-item basis.

Depending on the number of events being collected, frequent refreshes might be necessary. A view that contains many keys needs more frequent refreshes than views with one or a few keys. The following symptoms might indicate an application that is not refreshing frequently enough:

• Very large numbers of lost events reported in the Monitor Server error log. The Sybase Adaptive Server Enterprise Monitor Server User's Guide discusses configuration changes that can also help to reduce event loss.
• The application appears to hang in a call to smc_refresh_ex. A large number of keys in a view can cause a condition in which Monitor Server can not keep up with the number of events being collected and does not return control. Because of this, Monitor Server begins to consume large amounts of CPU time.

smc_get_row_count determines how many rows of results are available for a view. A view returns results in what is essentially a table with potentially many "rows" of result data, but in some cases, possibly zero rows.

smc_get_dataitem_value retrieves performance data values for a single column of a single row of a view.

Filters and alarms are applied during the refresh of the data.

Polling for new performance data is client-driven and is limited only by the speed of the data-providing system and the data-gathering system.

See the code sample at ** Request data and process results.

Step 7: Close and Deallocate Connections

Before exiting, a Monitor Client Library application must:

• Close all open connections.
• Deallocate each connection.

Closing and Deallocating Connections

An application calls smc_close to close a connection and smc_connect_drop to deallocate a connection structure. It is an error to deallocate a connection that has not been closed. A call to smc_close results in the following implicit Monitor Client Library calls:

• one or more calls to smc_drop_alarm to remove alarms, if necessary.
• one or more calls to smc_drop_filter to remove filters, if necessary.
• one or more calls to smc_drop_view to remove views.

See the code sample at ** Close and deallocate the connection.

Reopening Connections

After an application closes a connection, but before it deallocates the connection structure, it can call smc_connect_ex to reopen the connection.

Playing Back Recorded Data

To retrieve recorded data from Historical Server, the steps are similar to the above, except:

• The application must connect to Historical Server. (Set smc_prop_servermode to SMC_SERVER_M_HISTORICAL before making the connection.)
• The application must call smc_create_playback_session after connecting, but before creating views.
• The application must call smc_initiate_playback after creating all views.
• Alarms are not allowed on playback of recorded historical data.
• Views and filters cannot be dropped.
• After the last refresh, the application must call smc_terminate_playback.