15.10 - USER EVENT CONTROL - Teradata Database

Teradata Database Application Programming Reference

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

Activates and deactivates a user event.

 

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

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

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.

    Note: 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.

    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:

  • Database Administration
  • Security Administration
  • Teradata JDBC Driver User Guide
  • 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.

    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

    Note: 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.

    Note: 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.

    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.

    Note: This table only describes some of the possible response combinations, there are others.