16.20 - SET SESSION ACCOUNT - 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

Changes the account string for the session or for the request.

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.

host_id SMALLINT

NOT NULL

ID of the host upon which the session was issued. host_id cannot exceed 1023. A host_id of zero identifies the database operator console. If you do not specify a valid host_id, an error message is returned to CLIv2. Use only if you have DBA privileges.
session_no INTEGER

NOT NULL

Number of the session. session_no combined with the host_idproduces a unique Session ID. If you do not specify a valid session_no, an error message is returned to CLIv2. Use only if you have DBA privileges.
account VARCHAR (512)

NOT NULL

Account string for the session or request.
sess_req VARCHAR (1) Indicator of how the new account or priority affects requests for a specified session.

If you specify Y or y, the change applies to all current and future requests for a specified session. If no requests or steps are executing, the new account/priority takes effect at the next request, and the DBC.SessionTbl table reflects the new account/priority for the current session.

If you specify NULL, blank, N, or n, the change applies to the current request for the specified session. If no request is executing, the next request for the specified session has the old account/priority.

Monitor Privileges

To use this request, you must have the ABORTSESSION or an equivalent 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 SESSION ACCOUNT

Before using this request, see Impact of Object Name Length on PM/API Requests.

The account or priority change is recorded in the DBC.SW_Event_Log table (accessible from the DBC.Software_Event_LogV view) with the following text in the TEXT column:

SESSION  session_no  HOSTID  host_id  CHANGED FROM ACCOUNT  account  TO ACCOUNT  account  ON  sess_req

The EVENT_TAG field contains an event number. THEDATE and THETIME fields, which make up the index of the DBC.SW_Event_Log table (accessible from the DBC.Software_Event_LogV view), contain the date and time of the account/priority change. All other fields of the table are blank.

When TASM Workloads are enabled, the SET SESSION ACCOUNT request will:
  • Fail and return an error.
  • Or succeed for a session, but the request in which it is running will continue to run the old (existing) account string. Future requests will run with the new account string.

For information on TASM rules, see Teradata® Viewpoint User Guide, B035-2206.

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
Success 8 18 to 273 StatementNo = 1

ActivityCount = 1

ActivityType = 108 (SET SESSION ACCOUNT)

DataInfo 71 6 to 64100 Optional; this parcel is present if request was IndicReq parcel.
Record 10
  • 5 to 64100 (record mode)
  • 6 to 64100 (indicator mode)
This record contains the old account and an error code.
EndStatement 11 6 StatementNo = 2-byte integer
EndRequest 12 4 None

The Data parcel sent from the host should be 39 bytes long for record mode or 40 bytes long for indicator mode.

Response

Each of the statement types described below correspond to a ResultSet returned by the Teradata JDBC Driver, and each statement type field corresponds to a ResultSet column. For more information on ResultSets, see Teradata JDBC Driver Reference, available at https://developer.teradata.com/connectivity/reference/jdbc-driver .

The statement response results in a Record parcel containing:

The Column Name and Column Contents field values are not returned in the Record parcel. These values are returned in an IDENTIFY request.
Field/Column Name Data Type Description
OldAccount VARCHAR (128)

CHARACTER SET UNICODE

NOT NULL

Existing account string.
ErrorCode INTEGER

NOT NULL

An error code.

The Error Code column can contain any of the following return codes:

Error-Name Code Text
ErrPFMNoAr 3250 No access right.
ErrPFMBadSes 3256 User entered invalid session x HostId.
ErrPFMBadAcc 3292 User entered invalid account.
ErrPFMUpdSesTbl 3293 Failed to update the session table with the new account.
ErrPFMBadSesReqInd 3294 Invalid session/request indicator value for set session account.
ErrPFMInvSes 3295 Invalid session.

Sample Input - CLIv2 Request

This is an example of the request parcels sent from a mainframe client. It shows how the parcels for a SET SESSION ACCOUNT request, built by CLIv2, look when sent to the Teradata Database server, where account is $Haccnt, sess_req is Y, host_id is 348, and session_no is 1000.

In this sample, the size of the response buffer is set 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 22 Request SET SESSION ACCOUNT
0003 Data 45 MonVerID 2
      HostId 348
      SessionNo 1000
      Account $Haccnt
      Session/Request Indicator Y
0004 Resp 6 BufferSize 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

This sample shows typical values returned in character text format for SET SESSION ACCOUNT. Your application may return values in a different format.

Success Parcel:
 Statement No: 1 Activity Count: 1 	 
 Activity Type: 108 FieldCount: 2
DataInfo Parcel: 
 Field Count: 2 
Record Parcel: 
 Parcel Flavor: 10 Parcel Body Length:32 
 OldAcct: "$MAcct", ErrorCode = 0
EndStatement.EndRequest.