Establishing a Session | CLI | Analytics Database (SQL Engine) - Establishing a Session - Call-Level Interface Version 2

Teradata® Call-Level Interface Version 2 Reference for Workstation-Attached Systems - 20.00

Call-Level Interface Version 2
Release Number
January 2024
English (United States)
Last Update
Product Category
Teradata Tools and Utilities
Before logging a session, check for entries of COPs in the following files:
  • /etc/hosts on UNIX systems
  • %windir%\system32\drivers\etc\hosts on Windows systems

If Distributed Name Service (DNS) is enabled, these files are resident on the appropriate DNS servers.

If the database has four COPs that can be connected to, the COP entries in the hosts file should look as follows:

[IP address of NODE1] NODENAMEcop1
[IP address of NODE2] NODENAMEcop2
[IP address of NODE3] NODENAMEcop3
[IP address of NODE4] NODENAMEcop4
NODENAME should be the same for all the nodes.

CLI assumes that the COP entries are serial, cop1, cop2, cop3..., cop100. If the environment variable is set, CLI keeps connecting the COPs until the value specified in the environment variable is reached.


[IP address of NODE1] NODENAMEcop1
[IP address of NODE2] NODENAMEcop2
[IP address of NODE5] NODENAMEcop5
[IP address of NODE6] NODENAMEcop6

In this example, CLI ignores NODE5 and NODE6 and connect all requested sessions to NODE1 and NODE2.The performance of the logon process can be improved by setting an environment variable with the name equal to the machine (NODENAME) name, and by specifying the number of COPs available for it. In the previous example, if an environment variable NODENAME with a value of 3 exists before initiating the first CONNECT request, CLI tries to connect to the first three nodes only. In the previous example, if an environment variable NODENAME with a value of 3 exists before initiating the first CONNECT request, CLI will try to connect to the first three nodes only. However, if an environment variable NODENAME with a value of 7 exists, CLI tries to connect all available notes, NODE1, NODE2, NODE5, and NODE6, in this case.

  • The NODENAME=x environmental variable must be upper-case.
  • The format of a COP name is dbcnameCOPn, where dbcname must begin with an alphabetic character. The remaining characters can be alphanumeric.
Before establishing a session, check for Teradata service entries in the following files:
  • /etc/services on UNIX systems

This file should contain the following entries:

tdmst 1025/tcp

If the gateway service on a NODE is configured to listen on a port other than 1025, these entries should be modified to reflect the port on which the gateway is listening. Another way of changing the default tdmst port (1025) is to set the environment variable TDMSTPORT to the appropriate port. CLI and the gateway must use the same port for communication.

In the DBCAREA, the application program provides a pointer to the logon string, its length, and, optionally, a pointer to the run string (partition name) and its length. The application program provides the maximum length of the Request Buffer and Response Buffer in the DBCAREA. Optionally, it modifies the processing options in the DBCAREA. It then sets the function code in the DBCAREA to DBFCON and calls DBCHCL.


DBCHCL obtains and initializes the CLI2SCB. If the application has specified that options values in the DBCAREA are to be used, the options are copied from the DBCAREA to the System Control Block (SCB); otherwise, options are copied from the System Parameter Block (SPB). A Request Control Block (RCB) is then allocated and initialized for the logon sequence. The application may provide token identifiers for its own use when starting a request or a session; the value of this DBCAREA field is copied to the logon RCB and will be returned whenever the logon request is referenced.

DBCHCL obtains and initializes request and response buffers. DBCHCL prepares a Logon parcel and a Run (or Connect) parcel in the Request Buffer. The request is sent to MTDP.


MTDP obtains from the database the address of the COP to which the session is assigned, connects to that COP, logs on to the database computer, and connects to the partition requested. MTDP then returns control to DBCHCL.


If the connection in MTDP is successful, and the wait for data options flag has been set to Y, MTDP is called again to wait until the logon response is received. In any event, an error or success message is generated in the message field of the DBCAREA and DBCHCL returns control to the application program.


If the return code in the DBCAREA is not normal, the application makes the appropriate changes and re-submits the DBCAREA to DBCHCL. If the application program plans to run multiple sessions concurrently, it saves the session id from the DBCAREA.

The interface is now ready to accept the execution of the startup request or the submission of regular Teradata SQL requests.