Summary of CLIv2 Routine Parameters - Call-Level Interface Version 2

Summary of CLIv2 Routine Parameters

The following table lists the parameters for the routines in this chapter

Table 10: Parameters of CLIv2 Routines

Routine	Parameters
DBCHINI	ReturnCode Address ContextArea Address DBCAREA Address
DBCHCL	ReturnCode Address ContextArea Address DBCAREA Address
DBCHCLN	ReturnCode Address ContextArea Address

DBCHINI

Purpose  

Sets up the CLIv2 environment.

The application must provide the DBCAREA and then call DBCHINI to initialize it.

Note: The alternate six-character name for DBCHINI is DBCHIN.

Interface

This routine is called with the following parameters, stylistically presented (the actual syntax varies according to the programming language being used):

DBCHINI(ReturnCode,ContextArea,DBCAREA)

In high-level languages, the details of the parameter list are handled by the compiler. For Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit address of a parameter. The last address has the first bit set to one to indicate the end of the list.

The parameters for this routine are:

Argument	Content
ReturnCode	A 4 byte unsigned integer field into which the return code will be placed by CLIv2.
ContextArea	A 4 byte unsigned integer field for internal use by CLIv2.
DBCAREA	The DBCAREA structure.

Usage Notes  

The application must declare or allocate the DBCAREA and call DBCHINI to initialize the fields prior to using CLIv2 functions.

Total Length must be filled in by the application before calling DBCHINI. DBCHINI verifies this value prior to any initialization attempt. The length must be at least 384, the size of the smallest DBCAREA. If the length is at least 640, the Level 1 enlarged DBCAREA will be formatted. If the length is at least 1024, the Level 2 enlarged DBCAREA will be formatted. For lengths greater than 384 but less than 640, greater than 640 but less than 1024, or greater than 1024, the excess is assumed to be an application appendage to the DBCAREA: it will be zeroed by DBCHINI but is otherwise unused by CLIv2. When not appending fields to the DBCAREA, mnemonics should be used to set the Total‑length field to the largest DBCAREA. When appending fields to the DBCAREA, depending on the application development environment it may be better to use hardcoded values rather than mnemonics. For example, if the total size of the DBCAREA plus application fields must be less than some size, it might be unwise to allow the DBCAREA size to increase.

DBCHINI obtains default values from the HSHSPB currently available to the application.

The return code will either be 0 (if the initialization is completed successfully) or 126 if the Total Length value is insufficient for the smallest DBCAREA (384 bytes). After the call, the return code variable contains a return code.

After the call, CLIv2 changes ContextArea for its own purposes.

DBCHINI initializes the DBCAREA allocated by the application with the length specified in DBCSIZE. DBCHINI does not initialize any DBCAREA extensions addressed by the DBCAXP DBCAREA field.

DBCHCL

Purpose  

Calls the functions to be used by the application.

An overview of the functions relative to DBCHCL is given in the first table in the section “Summary of CLIv2 Routine Parameters” on page 249. Each function is described in detail later in this chapter.

Process

Before each call to DBCHCL, the application modifies the DBCAREA to specify the action requested and to fill in the input fields relevant to that action. DBCHCL carries out the function specified by the function code in the DBCAREA, then passes back to the caller the DBCAREA, which contains, among other things, a return code. The application checks the return code in the DBCAREA, which is where CLIv2 and TDP indicate any problem they find.

If the call results in a delivery of parcels to the response buffer, the program checks the first parcel, which may be one of the following:

Success

Error

StatementError

Failure

Interface

This routine is called with the following parameters, stylistically presented (the actual syntax varies according to the programming language being used):

DBCHCL(ReturnCode,ContextArea,DBCAREA)

In high-level languages, the details of the parameter list are handled by the compiler. For Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit address of a parameter. The last address has the first bit set to one to indicate the end of the list.

The parameters for this routine are:

Argument	Content
ReturnCode	A 4 byte unsigned integer field into which the return code will be placed by CLIv2.
ContextArea	A 4 byte unsigned integer field for internal use by CLIv2.
DBCAREA	The DBCAREA structure.

Usage Notes  

Before DBCHCL is called, the application must have called DBCHINI to initialize the DBCAREA to be used by DBCHCL.

After the call, CLIv2 will change ContextArea for its own purposes.

The DBCAREA address must always be passed to DBCHCL.

In addition, the function code must be supplied.

Other fields in the DBCAREA must be set as appropriate to the function requested.

If Wait for Response is set to N (set and used by the Connect, Initiate Request, Command, Initiate with Protocol, and RunStartUp functions; used by the Fetch, Abort, Rewind, End Request, and Disconnect functions) and CLIv2 is waiting for a response from the Teradata Database, the application will receive a return code of 150 (busy).

The application may handle the busy response by calling routine DBCHWAT and waiting for control to return to the application.

If the return code is 0, resubmit the DBCHCL function that initially returned the busy indication.

If Return Code is nonzero for any function, the Message Length and Message Text fields of the DBCAREA will be set.

DBCHCL Functions

This section describes the DBCHCL functions listed below.

Function Name	Description
CON	Connect
RSUP	RunStartUp Request
IRQ	Initiate Request
IWPF	Initiate With Protocol‑Function
CRQ	Continue Request
CMD	Command
ABT	Abort
FET	Fetch
REW	Rewind and Fetch
ERQ	End Request
DSC	Disconnect

General Notes

For each function, there is a list of the required and optional input and output arguments and a general description of how DBCHCL processes the function.

The interpretation of some of the arguments may depend on the setting of the DBCAREA options (for more information, see “Setting DBCAREA Options” on page 46.

For instance, input/output string pointers may be variable strings. For output strings, DBCHCL will provide an address and length if Locate mode is in effect; otherwise, DBCHCL expects that the application has set the address of the area to which DBCHCL is to move the string.

If DBCHCL detects an error while processing, various fields will be set to help the user interpret and handle the error.

DBCHCL CON Function

Purpose  

CON (Connect) logs on to the Teradata Database and arranges to have the specified services available for all requests on that session.

Connect also allocates internal control structures that CLIv2 uses to store session context.

Usage Notes  

If no Logon String is supplied or logon mechanism, a TDP logon exit must furnish the necessary information to complete the logon request. If a TDP logon exit does not exist or is disabled, the connect will be rejected by TDP.

The application should call the ERQ function after processing the CON function, regardless of the success or failure of the connect. This releases internal resources used during connect processing.

DSC must be performed for each CON request. If the CON results in a nonzero return code, DSC should be called immediately. Otherwise, DSC should be called when the application has completed all work for the session.

If Return Code is 0, the application must invoke the FET function to obtain the final status of the connect call.

If Connect Type was R, the FET call results in a Return Code of 33 if the connect was successful.

If Connect Type was C, the parcels must be processed to determine success or failure of the connect.

The FET returns three additional DBCAREA fields set only when CON is being processed. These fields are:

Output TDP Path

Output TDP Session Id

Output Host Id.

Additional fields will be set as normal by the FET call.

For a discussion of the call and the fields used, see “DBCHCL FET Function” on page 273.

DBCAREA Input Fields

Before using the Connect function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

Table 11: DBCAREA Input Fields Optional for the Connect Function 

DBCAREA Input Fields Optional for the Connect Function
2PC	Anticipated Number of Concurrent Sessions
Automatic‑redrive	Change Options
Character Set Pointer	Connect Type
Country Id	C2S Conversion
Data‑encryption	Date Form
Delegate‑user‑identity	Extended‑load
Input TDP Path	Keep Response
Language Conformance	Language Id
Locate Mode	Logon Length
Logon Pointer	Maximum Parcel
Mechanism‑data‑encoding	Mechanism‑data‑len
Mechanism‑data‑ptr	Mechanism‑name
Message Area Pointer	Message Area Length
Parcel Mode	Request Buffer Length
Request Mode	Request‑parcel‑format
Request Processing Option	Request‑token
Response Buffer Length	Response Mode
Return Time	Run Length
Run Pointer	Save Response Buffer
Session‑desc‑length	Session‑desc‑pointer
Set Character Set	Statement‑status
S2C Conversion	Tell‑if‑delay
Transaction Semantics	Two Response Buffers
Use‑default‑conn	Use Presence Bits
Utility‑workload	Variable Length Fetch
Variable Length Request	Wait‑during‑delay
Wait‑exclusion	Wait For Response
Workload‑length	Workload‑pointer

DBCAREA Output Fields

Upon completion of the Connect function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

Table 12: DBCAREA Output Fields Always Set for the Connect Functions 

DBCAREA Output Fields Always Set for the Connect Functions
Message Return Code	Message Length
Message Text	Message Text Length
Current Response Buffer Length	Output CLIv2 Request Id
Output CLIv2 Connection Id	Return Code

Table 13: DBCAREA Output Fields Set by Successful Connect Functions 

DBCAREA Output Fields Set by Successful Connect Functions
Current Request Buffer Length	Mechanism‑name
Open Requests	Session Status
TDP Request Number

DBCHCL RSUP Function

Purpose  

RSUP (RunStartUp) sends a request to the Teradata Database to execute the startup request stored on the Teradata Database.

Usage Notes

The application should call the ERQ function after processing RunStartUp, regardless of the success or failure of the startup. This will release internal resources used during startup processing.

If RunStartUp is called without first calling Connect, RunStartUp will perform the Connect. In this case, the information needed for a Connect call should be supplied when doing the RunStartUp call.

If Return Code is 0, the application must invoke the FET function to process the response.

DBCAREA Input Fields

Before using the Run Start‑up function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

Table 14: DBCAREA Input Fields Required for the RunStartup Function 

DBCAREA Input Fields Required for the RunStartup Function
Function	Input CLIv2 Connection Id

Table 15: DBCAREA Output Fields Optional for the RunStartup Function 

DBCAREA Output Fields Optional for the RunStartup Function
Anticipated Number of Concurrent Sessions	APH‑response‑OK
Array‑Transforms‑Off	Change Options
Column‑info	C2S Conversion
Continued‑character‑state	Data‑encryption
Input TDP Path	Keep Response
Locate Mode	Logon Length
Logon Pointer	Max‑decimal‑returned
Maximum Parcel	Multi‑statement‑errors
Parcel Mode	Period‑as‑Struct
Refresh‑cached‑data	Request Buffer Length
Request‑parcel‑format	Request Processing Option
Request‑token	Response Buffer Length
Response Mode	Return Time
Return‑identity‑data	Result‑sets‑OK
Return‑result‑to	Return‑statement‑info
Row‑count	Run Length
Run Pointer	Save Response Buffer
S2C Conversion	Tell‑if‑delay
Transforms‑off	Trusted‑request
Two Response Buffers	Use Presence Bits
Variable Length Request	Variable Length Fetch
Wait‑during‑delay	Wait‑exclusion
Wait For Response	XML‑response‑format

DBCAREA Output Fields

Upon completion of the Run Start‑up function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

Table 16: DBCAREA Output Fields Always Set by the RunStartup Function 

DBCAREA Output Fields Always Set by the RunStartup Function
Current Response Buffer Length	Message Return Code
Message Text	Message Text Length
Output CLIv2 Request Id	Return Code

Table 17: DBCAREA Output Fields Set by Successful RunStartup Functions 

DBCAREA Output Fields Set by Successful RunStartup Functions
Current Request Buffer Length	Message Return Code
Message Text	Message Text Length
Open Requests	TDP Request Number

DBCHCL IRQ Function

Purpose  

IRQ (Initiate Request) sends a request to the Teradata Database to be processed.

Usage Notes

If Initiate Request is called without first calling CON, Initiate Request performs the CON. In this case, the information needed for a CON call should be supplied when doing the Initiate Request call.

If Return Code is 0, the application must invoke the FET function to process the response. After the response has been totally processed, the application must invoke the ERQ function to release resources used by the Initiate Request.

When initiating a request in a 2PC session, Initiate Request will be rejected if the session has a 2PC vote or terminate activity in progress.

After they are started, activities such as vote and terminate must be completed by the coordinator.

The vote can result from a previous Initiate with Protocol‑Function (IWPF) function.

The terminate could have resulted from an Abort or Logoff or from any response that contained a Failure parcel.

If any of these occur, the coordinator must be requested to perform a syncpoint.

DBCAREA Input Fields

Before using the Initiate Request function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

Table 18: DBCAREA Input Fields Required for the Initiate Request Function 

DBCAREA Input Fields Required for the Initiate Request Function
Function	Input CLIv2 Connection Id
Request Length	Request Pointer

Table 19: DBCAREA Input Fields Optional for the Initiate Request Function 

DBCAREA Input Fields Optional for the Initiate Request Function
Anticipated Number of Concurrent Sessions	APH‑response‑OK
Array‑Transforms‑Off	Change Options
Character Set	C2S Conversion
Column‑info	Continued‑character‑state
Data‑encryption	Extension Pointer
Input TDP Path	Keep Response
Locate Mode	Logon Length
Logon Pointer	Max‑decimal‑returned
Maximum Parcel	Message Area Length
Message Area Pointer	Multi‑statement‑errors
Parcel Mode	Period‑as‑Struct
Pointer	Refresh‑cached‑data
Request Buffer Length	Request Mode
Request‑parcel‑format	Request Processing Option
Request‑token	Response Buffer Length
Response Mode	Result‑sets‑OK
Return‑identity‑data	Return‑result‑to
Return‑statement‑info	Return Time
Row‑count	Run Length
Run Pointer	Save Response Buffer
Session Id	Set Character Set
Statement‑status	S2C Conversion
Tell‑if‑delay	Transforms‑off
Trusted‑request	Two Response Buffers
Using Data Pointer	Using Data Length
Use Presence Bits	Variable Length Fetch
Variable Length Request	Wait‑during‑delay
Wait‑exclusion	Wait For Response
XML‑response‑format

DBCAREA Output Fields

Upon completion of the Initiate Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

DBCAREA Output Fields always set by the Initiate Request Function
Current Response Buffer Length	Message Return Code
Message Text	Message Text Length
Output CLIv2 Request Id	Return Code

DBCAREA Output Fields set by Successful Initiate Request Functions
Current Request Buffer Length	Open Requests
TDP Request Number

DBCHCL IWPF Function

Purpose  

IWPF (Initiate with Protocol‑Function) enables an application to send a request to the Teradata Database.

It contains additional protocol functions for 2PC sessions, for use in specialized applications.

Note: This function can not be used when ANSI transaction semantics are enabled.

Usage Notes  

A 2PC request can be initiated using the Initiate with Protocol‑Function.

The IWPF function is similar to the Initiate Request (Initiate Request) function, except for the following differences:

IWPF does not support the Locate mode.

When IWPF is used with 2PC sessions, the additional protocol functions of vote, and vote and terminate can be used to optimize syncpoint processing in specialized applications.

In IWPF, you can set the following:

Code	Meaning
N	No protocol function. This is the default.
V	Vote protocol function to be appended.
T	Vote & Terminate protocol function to be appended.

DBCAREA Input Fields

Before using the Initiate With Protocol‑function function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

Table 20: DBCAREA Input Fields Required for Initiate With Protocol‑function 

DBCAREA Input Fields Required for the Initiate With Protocol‑function Function
Function	Input CLIv2 Connection Id
Request Length	Request Pointer

Table 21: DBCAREA Input Fields Optional for Initiate With Protocol‑function 

DBCAREA Input Fields Optional for the Initiate With Protocol‑function Function
Anticipated Number of Concurrent Sessions	APH‑response‑OK
Array‑Transforms‑Off	Change Options
Character Set	C2S Conversion
Column‑info	Continued‑character‑state
Extension Pointer	Input TDP Path
Keep Response	Length
Logon Length	Logon Pointer
Max‑decimal‑returned	Maximum Parcel
Message Area Length	Message Area Pointer
Multi‑statement‑errors	Parcel Mode
Period‑as‑Struct	Pointer
Protocol Function	Refresh‑cached‑data
Request Buffer Length	Request Mode
Request‑parcel‑format	Request Processing Option
Request‑token	Response Buffer
Response Mode	Result‑sets‑OK
Return‑identity‑data	Return‑result‑to
Return‑statement‑info	Return Time
Row‑count	Run Length
Run Pointer	Save Response Buffer
Session Id	Set Character Set
Statement‑status	S2C Conversion
Tell‑if‑delay	Transforms‑off
Trusted‑request	Two Response Buffers
Using Data Length	Using Data Pointer
Use Presence Bits	Variable Length Fetch
Variable Length Request	Wait‑during‑delay
Wait‑exclusion	Wait For Response
XML‑response‑format

DBCAREA Output Fields

Upon completion of the Initiate With Protocol‑function function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

Table 22: DBCAREA Output Fields always set by Initiate With Protocol‑function 

DBCAREA Output Fields always set by the Initiate With Protocol‑function Function
Message Return Code	Current Response Buffer Length
Message Length	Message Text
Message Text Length	Output CLIv2 Request Id
Return Code

Table 23: DBCAREA Output Fields Set by Successful Initiate With Protocol‑function 

DBCAREA Output Fields set by Successful Initiate With Protocol‑function Functions
Current Request Buffer Length	Open Requests
TDP Request Number

DBCHCL CRQ Function

Purpose  

CRQ (Continue Request) sends data requested by the Teradata Database to complete an SQL request. The need for such completion must be indicated by one of the following SQL requests:

A USING row descriptor that specifies CLOB or BLOB AS DEFERRED. The result is one of the following:

An ElicitData parcel in the response that contains the token specified as the Using‑data for the AS DEFERRED field.

An ElicitDataByName parcel in the response which contains the name specified in the BY NAME phrase.

A CREATE or REPLACE for an executable item, such as FUNCTION, that specifies the EXTERNAL NAME clause. The result is an ElicitFile parcel that contains the filename specified by the EXTERNAL clause.

When either parcel is received, the application then sends data to complete the SQL request using the ContinueRequest function.

Usage Notes  

The application should call the CRQ function after processing an ElicitData or ElicitFile response parcel. If return Code is zero, the application must invoke the FET function to process the response. If more data exists, these steps are repeated as many times as necessary.

DBCAREA Input Fields

Before using the Continue Request function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

Table 24: DBCAREA Input Fields Required for the Continue Request Function 

DBCAREA Input Fields Required for the Continue Request Function
Continued‑data	Function
Input CLIv2 Connection Id	Input CLIv2 Request Id
Request Length	Request Pointer

When processing an ElicitData parcel, the Request‑pointer addresses data for the Large Object (LOB). The LOB begins with an 8‑byte unsigned integer that contains the length, in bytes, of the data. If the length is not known when the start of the LOB is sent, the length field might be zero.

When processing an executable item, the Request‑pointer addresses its statements, which do not begin with a length field.

Table 25: DBCAREA Input Fields Optional for the Continue Request Function 

DBCAREA Input Fields Optional for the Continue Request Function
Change Options	C2S Conversion
Fetch Buffer Length	Locate Mode
Maximum Parcel	Message Area Length
Message Area Pointer

DBCAREA Output Fields

Upon completion of the Continue Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

Table 26: DBCAREA Output Fields always set by the Continue Request Function 

DBCAREA Output Fields always set by the Continue Request Function
Message Length	Message Return Code
Message Return Code	Message Text
Message Text Length	Message Return Code
Return Code

Table 27: DBCAREA Output Fields set by Successful Continue Request Functions 

DBCAREA Output Fields set by Successful Continue Request Functions
Current Request Buffer Length	Current Response Buffer Length

DBCHCL CMD Function

Purpose  

CMD (Command) issues a TDP command within a CLIv2 program.

This function is used to send the TDP command, specifying a buffer and length that contain the command text.

Usage Notes

Use the CMD function to send a TDP command, specifying a buffer and length for the command text.

If the Return Code is 0, a pseudo‑connection number and a request number are returned.

To process the response, issue a FETch function with the returned pseudo‑connection number and request number.

The response data is composed of various parcels in the following order:

1 A Success parcel with an activity count that indicates the number of subsequent Record parcels

2 The Record parcels themselves (one Record parcel for each line of command output)

3 An End Statement parcel

4 An End Request parcel

After the response has been completely processed, the application must invoke the ERQ function to release the fetch buffer used by the CMD.

Since the application doesn‘t establish a connection, no DISCONN function may be used for the pseudo‑connection number. Rewind and Abort functions are not supported.

If the specified response buffer is too small for the entire response, a code of 535 is returned, either as a warning code in the Success parcel or as a return code from the CLIv2 call.

DBCAREA Input Fields

Before using the Command function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

Table 28: DBCAREA Input Fields Required for the Command Function 

DBCAREA Input Fields Required for the Command Function
Function

Table 29: DBCAREA Input Fields Optional for the Command Function 

DBCAREA Input Fields Optional for the Command Function
Anticipated Number of Concurrent Sessions	Change Options
Character Set	Input TDP Path
Length	Locate Mode
Maximum Parcel	Message Area Length
Message Area Pointer	Parcel Mode
Pointer	Request Buffer
Request Length	Request Mode
Request Pointer	Request Processing Option
Response Buffer Length	Response Mode
Return Time	Set Character Set
Tell‑if‑delay	Request‑token
Two Response Buffers	Use Presence Bits
Variable Length Fetch	Variable Length Request
Wait‑during‑delay	Wait‑exclusion
Wait For Response

DBCAREA Output Fields

Upon completion of the Command function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

Table 30: DBCAREA Output Fields always set by the Command Function 

DBCAREA Output Fields always set by the Command Function
Current Response Buffer Length	Message Length
Message Return Code	Message Text
Message Text Length	Output CLIv2 Request Id
Output CLIv2 Connection Id	Return Code

Table 31: DBCAREA Output Fields set by Successful Command Functions 

DBCAREA Output Fields set by Successful Command Functions
Current Request Buffer Length	Open Requests
TDP Request Number

DBCHCL ABT Function

Purpose  

ABT (Abort) attempts to abort a request and the transaction in which it is embedded. This is known as an asynchronous abort.

Abort may be used within an External Stored Procedure to indicate that the results of a request initiated with the DBCAREA Return‑result‑to option will not be reflected to the CALLer or the application.

Usage Notes  

If the Return Code is 0, the abort has been sent to the Teradata Database. However, 0 does not mean the request has been aborted. The application must perform FET to check the final disposition of the original request and ERQ to release the request context.

If the abort reaches the Teradata Database before it completes the request, the request will be aborted and the containing transaction rolled back. Storage associated with the request is kept until ERQ is issued for the request.

If the abort reaches the Teradata Database after the request has completed, the abort is ignored.

If the application has an active transaction and is between requests, issue Initiate Request with a ROLLBACK statement rather than calling ABT to perform the abort.

If the session is running in 2PC mode, ABT ensures that the current session is aborted at syncpoint. This occurs even if the abort had no effect (for example, if the request completed before ABT could abort it).

DBCAREA Input Fields

Before using the Abort function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

DBCAREA Input Fields Required for the Abort Function
Function	Input CLIv2 Request Id
Input CLIv2 Connection Id

DBCAREA Input Fields Optional for the Abort Function
Message Area Length	Message Area Pointer

DBCAREA Output Fields

Upon completion of the Abort function, CLIv2 will always set DBCAREA fields in the table.

DBCAREA Output Fields always set by the Abort Function
Message Return Code	Message Length
Message Text	Message Text Length
Return Code

DBCHCL FET Function

Purpose  

FET (Fetch) delivers a pointer to the next parcel of the response.

Usage Notes  

If Return Code is 0, the application may process the response from the Teradata Database. FET may be invoked repeatedly until the entire response has been processed.

For 2PC sessions, Fetch ensures that the current session is aborted at syncpoint if a failure parcel is received in response to a request.

In addition, the first FET after a CON call will return the following fields:

Output TDP Path

Output TDP Session Id

Output Host Id

DBCAREA Input Fields

Before using the Fetch function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

DBCAREA Input Fields Required for the Fetch Function
Function	Input CLIv2 Connection Id
Input CLIv2 Request Id

DBCAREA Input Fields Optional for the Fetch Function
Fetch Data Pointer	Fetch Maximum Data Length
Message Area Length	Message Area Pointer
Positioning‑action	Positioning‑statement‑number
Positioning‑value	Row‑count

DBCAREA Output Fields

Upon completion of the Fetch function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

Table 32: DBCAREA Output Fields always set by the Fetch Function 

DBCAREA Output Fields always set by the Fetch Function
Current Response	Return Code
Session Status	Message Length
Message Return Code	Message Text

Table 33: DBCAREA Output Fields set by Successful Fetch Functions 

DBCAREA Output Fields set by Successful Fetch Functions
Buffer Length	Data Length
Fetch Data Pointer	Fetch Parcel Flavor
Fetch Returned	Message Text Length
Output TDP	Output Host Id
TDP‑receipt‑timestamp	Time1
Time1‑status	Time2
Time2‑status	Time3
Time3‑status	Time4
Time4‑status	Time5
Time5‑status

DBCHCL ERQ Function

Purpose  

ERQ (End Request) explicitly closes a request, discard its response, and deallocated internal data structures related to the request.

Usage Notes  

If Return Code is 0, the ERQ has successfully completed.

CLIv2 will keep the response buffer if Save Response Buffer was Y when the request was submitted. This permits CLIv2 to reuse the response buffer for the next Initiate Request without allocating a new one.

DBCAREA Input Fields

Before using the End Request function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

Table 34: DBCAREA Input Fields Required for the EndRequest Function 

DBCAREA Input Fields Required for the EndRequest Function
Function	Input CLIv2 Request Id
Input CLIv2 Connection Id

Table 35: DBCAREA Input Fields Optional for the EndRequest Functions 

DBCAREA Input Fields Optional for the EndRequest Functions
Message Area Length	Message Area Pointer

DBCAREA Output Fields

Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

Table 36: DBCAREA Output Fields Always Set for the EndRequest Function 

DBCAREA Output Fields Always Set for the EndRequest Function
Message Text	Message Length
Message Text Length	Return Code

Table 37: DBCAREA Output Fields Set by Successful EndRequest Functions 

DBCAREA Output Fields Set by Successful EndRequest Functions
Open Requests	Message Return Code

DBCHCL REW Function

Purpose  

REW (Rewind) repositions to the beginning of the response from the Teradata Database.

Keep Response must have been set to Y at the time of the Initiate Request for the request. Since Keep‑response does not apply to Connect requests, the response to a Connect cannot be rewound.

Usage Notes  

If Return Code is 0, the application may use FET to process the response.

DBCAREA Input Fields

Before using the Rewind function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

DBCAREA Input Fields Required for the Rewind Function
Function	Input CLIv2 Request Id
Input CLIv2 Connection Id

DBCAREA Input Fields Optional for the Rewind Function
Message Area Length	Message Area Pointer

DBCAREA Output Fields

Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

DBCAREA Output Fields always set by the Rewind Function
Message Return Code	Message Text
Message Length	Message Text Length
Return Code

DBCHCL DSC Function

Purpose  

DSC (Disconnect) logs a session off the Teradata Database.

Usage Notes  

Check the Return Code; if zero, the disconnect was successfully completed.

If the session has a pending request, a return code of 336 (request may be aborted) is returned to the application. The session is still logged off but the response is lost.

If there is an active transaction at the time of the DSC, the Teradata Database rolls back all work performed within that transaction prior to completing the logoff.

DSC should be used to clean up session context even if the connect was not successful (initial or final status).

In 2PC mode, Disconnect ensures that the current session is aborted at syncpoint if the session has performed any uncommitted Teradata SQL requests.

DBCAREA Input Fields

Before using the Disconnect function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

DBCAREA Input Fields Required for the Disconnect Function
Function	Input CLIv2 Connection Id

DBCAREA Input Fields Optional for the Disconnect Function
Message Area Length	Message Area Pointer

DBCAREA Output Fields

Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the table.

DBCAREA Output Fields always set by the Disconnect Function
Message Return Code	Message Length
Message Text	Message Text Length

DBCHCLN

Purpose  

Logs off all sessions and free all internal memory and context information allocated by CLIv2.

Note: The alternate six-character name for DBCHCLN is DBCHCN.

Interface

This routine is called with the following parameters, stylistically presented (the actual syntax varies according to the programming language being used):

DBCHCLN(ReturnCode,ContextArea)

In high-level languages, the details of the parameter list are handled by the compiler. For Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit address of a parameter. The last address has the first bit set to one to indicate the end of the list.

The parameters for this routine are:

Argument	Content
ReturnCode	A 4 byte unsigned integer field into which the return code will be placed by CLIv2.
ContextArea	A 4 byte unsigned integer field for internal use by CLIv2.

Usage Notes  

The application invokes the DBCHCLN routine when all processing requiring interfacing with the Teradata Database is complete.

DBCHCLN does the following:

logs off any idle sessions

awaits completion of any active sessions and then logs them off

frees all internal memory and context information allocated by CLIv2.

DBCHCLN deallocates internal data structures that were allocated by DBCHINI.

DBCHCLN returns control to the application after all sessions have been logged off and all internal context has been cleaned up.

After control returns from DBCHCLN, the variable contains a code whose value represents success or failure to clean up.

A return code of zero indicates success.

A nonzero return code indicates failure, and the value specifies the reason for the failure.

After the call, the return code variable will contain a return code.

After the call, CLIv2 changes ContextArea for its own purposes.

The call to DBCHCLN does not deallocate the DBCAREA.

The application may itself deallocate the DBCAREA if the programming language provides that ability.

Termination of the application has the same effect as DBCHCLN, but it is good programming practice to call DBCHCLN for cleanup.