16.20 - SET RESOURCE RATE - Teradata Vantage NewSQL Engine

Teradata Vantage™ Application Programming Reference

prodname
Teradata Database
Teradata Vantage NewSQL Engine
vrm_release
16.20
created_date
March 2019
category
Programming Reference
featnum
B035-1090-162K

Purpose

Sets either the ResMonitor or ResLogging rate.

Input Data

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.

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.

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.

    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)
This field is obsolete.

Monitor Privileges

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:

Usage Notes - SET RESOURCE RATE

You can set the ResMonitor or ResLogging rates using the SET RESOURCE RATE request. For a description of these rates, see Data Collection.

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.

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.

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.

CLIv2 Response Parcels

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

Sample Input - CLIv2 Request

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

Sample Input - Teradata JDBC Driver Request

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, available at https://developer.teradata.com/connectivity/reference/jdbc-driver .

Sample Output

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.

Relationship Between SET RESOURCE RATE and MONITOR PHYSICAL RESOURCE or MONITOR VIRTUAL RESOURCE

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.

Relationship Between SET RESOURCE RATE and MONITOR PHYSICAL SUMMARY or MONITOR VIRTUAL SUMMARY

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.