CLIv2 Debug Facility and Wire Protocol

Connectivity covers the mechanisms for connecting to the Teradata Database, including driver connectivity via JDBC or ODBC.
Teradata Employee

CLIv2 Debug Facility and Wire Protocol

This article introduces CLIv2 debug facility and describes Client and Teradata DBS server wire protocol. There are two parts of this article. The first part is to cover how to setup CLIv2 debug facility. It includes the setting of many environment variables that activate different function of CLIv2 debug facility. The second part is to describe the contents generated by CLIv2 debug facility. It covers messages and parcels sent and received between Client and DBS servers.

CLIv2 has a well developed debug facility that allows user to view all trouble shooting logs as well as binary data dumps. CLIv2 debug facility can help on diagnosing CLIv2 itself, understanding Client/Server Wire protocols, and knowing what data are sent and received between CLIv2 and Gateway/DBS. CLIv2 debug facility can also help on revealing the behavior of CLIv2 application and Client utilities in some cases.

The following is the first part of this article:

In order to activate CLIv2 debug facility, users need to set the main, COPANOMLOG, environment variable in the command shell before running CLIv2 applications. There are other environment variables that can be set for different purposes. The following sections describe the usage of all environment variables related to CLIv2 debug facility:

COPANOMLOG - this is the main environment variable to activate CLIv2 debug facility. A file pathname of CLIv2 debug trace log file is defined in COPANOMLOG. CLIv2 debug trace log will be created in the file specified in COPANOMLOG. For example: “export COPANOMLOG=/tmp/coplog.txt”. The debug trace log file will be created at /tmp/coplog.txt after running a CLIv2 application.

NETRACE - this environment variable controls the level of details recorded in CLIv2 debug trace log file. Four bitmap values or bitmap combination values can be specified in the environment variable:

(a) Bitmap 1 (1) - it will turn on all debug trace log except for DBCAREA binary dump. The default of DBCAREA binary dump is off when bitmap 1 is set. Bitmap1 needs to be set for other bitmaps to be activated.

(b) Bitmap 2 (2) - it will turn off Time Stamp when this bit is set. The default of time stamp is on when bitmap 1 is set.

(c) Bitmap 3 (4) - it will turn off CLIv2 options binary dump when this bit is set. The default of CLIv2 option binary dump is on when bitmap 1 is set.

(d) Bitmap 4 (8) - it will turn on DBCAREA binary dump when this bit is set. The default of DBCAREA binary dump is off when bitmap 1 is on.

Please note that Bitmap 1 needs to be set to trigger the level of details for debug trace log. For example: If “export NETRACE=9 (bitmap 1 + bitmap 4)” is set, it will activate and record all debug trace log including DBCAREA binary dumps.

NETRACE_BUF_LEN - this environment variable can be used to control the number of bytes written to each binary dump. For example: If “export NETRACE_BUF_LEN=128” is set, it will only write the first 128 bytes of data to binary dump. This is useful to control the size of CLIv2 debug trace log file since the data can be as large as 1M byte for a 1M request of each binary dump.

COPANOMLOG_SIZE - this environment variable can be used to control the size of each CLIv2 debug trace log file. For example: If “export COPANOMLOG_SIZE=100” is set, it will limit each CLIv2 debug trace log file to approximate100M bytes in size. When the size is over 100M bytes, CLIv2 debug facility will create a new file. The name of new file will have an ascending number appended to trace log filename.

THREADLOGGING - this environment variable allows uses to turn on trace log for each thread in multithreaded CLIv2 applications. The value specified in this environment variable is irrelevant. CLIv2 debug facility just checks whether the environment variable is set. If it is set, each thread will log its own debug trace log to a separate file. The name of each file has the thread ID appended to it.

The following is the second part of this article:

The contents of CLIv2 debug trace log file include version number of CLIv2 modules, default option settings, function call traces, time stamps, message and parcel dumps, etc. This part of article describes messages and parcels used to communicate between CLIv2 and Gateway/DBS. So, readers will understand Client/Server wire protocol as well as the format of request/response messages and parcels recorded in the CLIv2 debug trace log file.

Each sent and received message contains two portions, LAN header and data. The LAN header portion is a 52 byte memory block that contains information needed for Client and Server communications. The data portion contains a bundle of parcels.

The LAN header portion starts from byte zero and end at byte fifty-one. The definition and explanation of LAN header is described as follows:

struct LANHeaderType {
unsigned char Version;
/* Version is set to a constant of a value of 3. */
unsigned char Class;
/* Class contains the request or response message */
/* types. A value of 1 indicates a request message. */
/* A value of 2 indicates a response message. */
unsigned char Kind;
/* Message kinds are defined in the section below. */
unsigned short HighOrderMessageLength;
/* The size of this message is referenced here. */
unsigned char ByteVar;
unsigned short WordVar;
unsigned short LowOrderMessageLength;
/* The size of this message is referenced here. */
unsigned short ResForExpan[3];
unsigned short CorrelationTag[2];
unsigned int SessionNo;
/* SessionNo contains the session no for which a */
/* message applies for all messages except for the */
/* Assign Request which contains binary zeros in */
/* this field. */
unsigned char Authentication[8];
unsigned int RequestNo;
/* RequestNo contains the req number for which a */
/* Start, Continue or Abort message applies. */
/* All other ReqNo fields contain binary zeros. */
union {
unsigned char MustBeZero;
unsigned char Capabilities;
} gtw_byte;
unsigned char HostCharSet;
/* HostCharSet contains the code which identifies */
/* the current active character set in use by the */
/* host to interpret requests and represent resp. */
/* The default character set code is 255. */
unsigned char Spare[14];

All message kinds used between CLIv2 and Gateway/DBS are defined here:

CopKindAssign (1)
CopKindReAssign (2)
CopKindConnect (3)
CopKindReConnect (4)
CopKindStart (5)
CopKindContinue (6)
CopKindAbort (7)
CopKindLogoff (8)
CopKindTest (9)
CopKindCfg (10)
CopKindAuthMethods (11)
CopKindSsoReq (12)
CopKindElicitData (13)
CopKindDefaultConnect (254)
CopKindDirect (255)

The data portion starts from byte fifty-two till the end of a message. Data portion contains a bundle of parcels. The content of the first parcel starts at byte fifty-two. The next parcel is located right after the previous parcel in memory. Parcel size defined in the parcel can be used to locate the next parcel. The definition of Client and Server parcels are in Chapter 9 of CLIv2 user manual (B035-2418-088A). Please refer to the manual for all parcel definition details. Basically, there are two kinds of parcels, original parcels and APH parcels. The main difference is in the parcel length field. The original parcel is limited to 64k in size. There is only two bytes for the parcel length field. The APH parcel is to support 1M message. So, the parcel length field is four bytes.

Wire protocol for establishing a session includes many message exchanges between Client and Server. Here are the steps to logon a session in general:

- Client sends a CopKindCfg(10) request message with client config parcel(166) and config parcel(42) in the request message.

- Server responds to the CopKindCfg(10) message with config response parcel(43), gateway config parcel(165), and one auth mechanism parcel(167) for each mechanism in the response message.

- Client sends a CopKindAssign(1) request message with assign parcel(100) and SSO request parcel(132) in the request message.

- Server responds to the CopKindAssign(1) message with assign response parcel(101) and SSO response parcel (134) in the response message.

- Client sends a CopKindSsoReq(12) request message with SSO request parcel(132) in the request message.

- Server responds to the CopKindSsoReq(12) message with SSO response parcel(134) in the response message.

- The above CopKindSsoReq(12) message exchanges occur one or more times depending on the mechanism.

- Client sends a CopKindConnect(3) request message with logon parcel(36), session option parcel(114), connect parcel(88), data parcel(3) and/or client attribute parcel(189), and SSO username request parcel(136) for external authentication in the request message.

- Server responds to the CopKindConnect(3) message with success parcel(8), SSO username response parcel(137) for external authentication, and end request parcel(12) in the response message.

A session is established after the above message exchanges are accomplished. After the session is established, client application can start sending requests and receiving responses using CopKindStart(5) messages and/or CopKindDirect(255) messages.

As the job is completed, client application can logoff the session using CopKindLogoff(8) message. That concludes Client and Server communications.