15.10 - SET RESOURCE RATE - Teradata Database

Teradata Database Application Programming Reference

prodname
Teradata Database
vrm_release
15.10
category
Programming Reference
featnum
B035-1090-151K

Sets either the ResMonitor or ResLogging rate.

 

Element

Data Type

Description

IndByte

BYTE

Indicator bits that specify which fields to treat as NULL if you are using indicator mode.

Each bit in the byte corresponds to one field in the input data.

If data is supplied for that field, set the bit to zero.

If the data for that field is NULL (that is, there is no data supplied for that field), set the bit to 1.

Note: The IndByte field is only required if the CLIv2 request is submitted in indicator mode.

mon_ver_id

SMALLINT,
NOT NULL

MONITOR software version ID. This can be version 2 or later.

For a general explanation of monitor version choices, see “MONITOR VERSION” on page 162.

sample_rate

SMALLINT,
NOT NULL,
range 0-3600 secs

Value of the collection rate. This field is used either to collect resource data or to log resource data to the resource usage tables.

You can specify one of the following:

  • The ResMonitor rate value if you want to change the resource monitoring rate.
  • The ResLogging rate value if you want to change the resource logging rate.
  • Note: The value should be an integral divisor of 3600.

  • Zero to turn off the resource collection or logging.
  • log_change

    VARCHAR (1)

    Indicator of whether this rate applies to the ResLogging or ResMonitor rate:

  • Y or y = ResLogging rate
  • N, n, NULL, or blank = ResMonitor rate
  • virtual_change

    VARCHAR (1)

    Note: This field is obsolete.

    To use this request, you must have the SETRESRATE privilege as part of your default role or this privilege must be granted directly to you.

    For more information on roles and privileges, see:

  • Database Administration
  • Security Administration
  • Teradata JDBC Driver User Guide
  • You can set the ResMonitor or ResLogging rates using the SET RESOURCE RATE request. For a description of these rates, see “Data Collection” on page 39.

    ResMonitor and ResLogging are independent of each other because you can monitor without wanting to log to the resource usage tables, or you can log without monitoring.

    Note: You can set only one ResMonitor or ResLogging rate within one SET RESOURCE RATE request. For example, to set both the ResMonitor and ResLogging rates at the same time, you must issue two SET RESOURCE RATE requests and specify the USING Data String appropriately.

    Resource data is placed in a memory repository separate and independent from session usage data. Therefore, any changes in the ResMonitor rate does not impact session usage data.

    Remember that resource utilization data collected by the ResMonitor rate is collected and reported differently from session utilization data. Whereas session usage data is collected cumulatively, resource data is collected for a particular collection period. The data reported is based on the activity that occurred during that collection period and does not include any cumulative data over collection periods.

    There is a difference between saving statistics in the resource memory repository and returning the data for display. Resource data can be saved after a collection rate is set to a nonzero rate, but no return of data occurs until a MONITOR request is issued.

    The ResMonitor rate and the ResLogging rate are saved on disk in the Version Record when they are changed. For this reason, the SET RESOURCE RATE request can block if someone else is updating the GDO control record. If a block occurs, you must wait until the block clears.

    Note: When you execute the SET RESOURCE RATE request, the change is saved in the DBC.SW_Event_Log table (accessible from the DBC.Software_Event_LogV view) and written to the system console running Database Windows.

    The response returned from Teradata Database contains the following sequence of parcel types.

     

    Parcel Sequence

    Parcel Flavor

    Length

    (Bytes)

    Comments/Key Parcel Body Fields

    Success

    8

    18 to 273

    Activity Count = Contains previous rate.

    Activity Type = 87 (PCLSETRESSR)

    DataInfo

    71

    6 to 64100

    This parcel is present if request was IndicReq parcel; depends on the data type.

    EndStatement

    11

    6

    StatementNo: 2‑byte integer

    EndRequest

    12

    4

    None

    This example shows how the parcels for a SET RESOURCE RATE request, built by CLIv2, look when sent to the Teradata Database server using a sample_rate of 600 seconds and a logging_change of Y. The size of the response buffer is set in the example at the maximum (64,000 bytes), although you can set it to any size. However, a minimum response size is 32,000 bytes.

     

    Flavor

    Length

    Body

    Num

    Name

    Bytes

    Field

    Value

    0001

    Req

    21

    Request

    SET RESOURCE RATE

    0030

    Data

    11

    MonVerID

    SampleRate

    LoggingChg

    VirtualChg

    2

    600

    Y

    N

    0004

    Resp

    6

    Buffer Size

    64000

    For an example of how the PM/API request, built in Java, appears when sent to the Teradata Database server, see Teradata JDBC Driver Reference.

    With a sample_rate of 600 and a logging_change of y, this example shows the values returned in character text format for the SET RESOURCE RATE request. Your application program may display returned values in a different format.

    Success parcel:
     StatementNo: 1    ActivityCount: 60
     ActivityType: 87    FieldCount: 0
    DataInfo parcel:
     FieldCount: 0
    EndStatement.
    EndRequest.

    You must execute the SET RESOURCE RATE request to activate resource data collection before you execute a MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL RESOURCE request. This means that you must set the ResMonitor rate to nonzero. If the ResMonitor rate is set to zero, you will receive an error message.

    A change in the resource collection rate by User A, for example, may affect the data reported by MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL RESOURCE request made by User B. If the ResMonitor rate is altered, User B receives a warning message when executing a subsequent MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL RESOURCE request.

    The SET RESOURCE RATE request sets the ResMonitor and ResLogging rates, which are among the responses returned by the MONITOR PHYSICAL SUMMARY or MONITOR VIRTUAL SUMMARY request. Any change to either the ResMonitor or ResLogging rate results in changes in the corresponding response returned by the MONITOR VIRTUAL SUMMARY or MONITOR PHYSICAL SUMMARY request.

    You must set ResMonitor to a nonzero rate for MONITOR PHYSICAL SUMMARY or MONITOR VIRTUAL SUMMARY to return meaningful resource utilization data. A zero ResMonitor rate returns NULL for resource utilization information.