USER EVENT CONTROL Request | Application Programming Reference | Vantage - USER EVENT CONTROL - Advanced SQL Engine - Teradata Database

Application Programming Reference
Product
Advanced SQL Engine
Teradata Database
Release Number
17.05
17.00
Published
June 2020
Language
English (United States)
Last Update
2021-01-22
dita:mapPath
cpn1571792172880.ditamap
dita:ditavalPath
lze1555437562152.ditaval
dita:id
B035-1090
lifecycle
previous
Product Category
Teradata Vantage™

Purpose

Activates and deactivates a user event.

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 6 or later.

For a general explanation of monitor version choices, see MONITOR VERSION.
Request Type SMALLINT

NOT NULL

 Type of request specified:
  • 0 = Deactivate event identified in Event Name
  • 1 = Activate event identified in Event Name
Event Name VARCHAR (30) The name of the user event. The event name is a maximum of 30 characters and must be padded with blanks. It is also case sensitive.
Duration INTEGER

NOT NULL

 Time, in minutes, that this user event remains active. This field is valid for active requests only.

A value of zero means the event is true.

The evaluation of all events, including user events, is based on the System Event Timer defined in the Teradata Dynamic Workload Designer portlet. If the Duration value is not a multiple of the System Event timer, it is rounded to the next System Event timer value.

Monitor Privileges

To use this request, you must have the ABORTSESSION and MONSESSION privileges as part of your default role or both privileges must be granted directly to you.

For more information on roles and privileges, see:

Usage Notes

User Events are defined externally only by the name and the attribute of being either active or inactive. User Events also have an optional duration time that determines the length of time the Activate event persists. The event times out at the end of the duration time unless it is de-activated or re-activated. A Duration value of zero indicates the Activate (a Request Type value of 1) is persistent and lasts until explicitly made inactive by another User Event call. User Events persist across a TPA restart or system failure.

User Event names are global, or system wide and, therefore, you must make sure that no conflicting usages of User Event Control request calls occur.

CLIv2 Response Parcels

The following table lists information about the parcels for the USER EVENT CONTROL request.

Parcel Sequence Flavor Field Length Comments and Key Parcel Body Fields
Success 8 18 to 273 StatementNo=1

ActivityCount = 1

ActivityType = PCLUSEREVENTCONTROLSTMT (169)
DataInfo 71 6 to 64100 Optional: this parcel is present if request was IndicData parcel.
Record 10
  • 5 to 64100 (record mode)
  • 6 to 64100 (indicator mode)
 Depending on the request (Data or IndicData) data is returned in record or indicator mode. This is the only record returned.
EndStatement 11 6 StatementNo = 2-byte integer
EndRequest 12 4 None

For an example of how the PM/API request, built in Java, appears when sent to the database server, see Teradata JDBC Driver Reference, available at https://teradata-docs.s3.amazonaws.com/doc/connectivity/jdbc/reference/current/frameset.html .

Response

The statement described below corresponds to a ResultSet returned by the Teradata JDBC Driver, and each of the fields correspond to a ResultSet column returned by the Teradata JDBC Driver. For more information on ResultSets, see Teradata JDBC Driver Reference, available at https://teradata-docs.s3.amazonaws.com/doc/connectivity/jdbc/reference/current/frameset.html .

The response to the USER EVENT CONTROL request results in a single Record parcel containing the result of the request.

Field/Column Name Data Type Description
User-Defined Event Status INTEGER

NOT NULL

 Current status of the user-defined event:
  • 0 = Inactive
  • 1 = Active
Previous User-Defined Event Status INTEGER

NOT NULL

 Previous status of the user-defined event:
  • 0 = Previously inactive
  • 1 = Previously active
  • 2 = Previously not defined

The USER EVENT CONTROL request can be used to activate or inactivate a single, specific User Event.

The response indicates if the operation was successful. For successful operations, the result (Previous User-Defined Event Status) shows the previous value of this User Event. This allows the user to know if the User Event was previously active or not. For example, a successful operation, can return any of the following results:

The result.... indicates...
1,0 the current User Event is Active and it was previously Inactive.
1,0 the current User Event is Inactive and it was previously Active.
1,2 the current User Event is Active and it was previously not defined.
This table only describes some of the possible response combinations, there are others.