17.10 - DBFIRQ - Call-Level Interface Version 2

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

Product
Call-Level Interface Version 2
Release Number
17.10
Release Date
October 2021
Content Type
Programming Reference
Publication ID
B035-2418-061K
Language
English (United States)

DBFIRQ is the Initiate Request function of DBCHCL; DBFIRQ sends a request to the database to be processed.

How It Works

DBFRIRQ performs the following functions:
  • If the session is active, awaits completion of the active request
  • If the active request was an IRQ, saves the ending status of the request internally
  • If the previous request was a CON and it was not successful, it receives a return error indicating “unable to initiate because session is not logged on”
  • Verifies the request buffer is large enough
  • Builds a request in request buffer, as follows:
    • The response should be in either Record, Field, Indicator or Multipart Mode, based on the setting of the Response Mode field
    • Input data should be in either Record or Indicator Mode based on the setting of the Use Presence Bits field, or neither based on setting of Using Data Length field
  • Appends a SETPOSITION position parcel and then a Resp or KeepResp parcel based on Keep Response field setting. If keep_resp is set to 'P', then a SETPOSITION parcel is appended with a KeepResp parcel.
  • If the session is not a Teradata SQL (that is, if the bypass flag is set to Y), disregards the SQL buffer pointer and uses the using data buffer as is to generate the request buffer, without any additional parcels added to the request buffer
  • Sends request to the MTDP
  • If not successful, cleanups and returns to the application
  • Sets Open Requests field, and so on, and returns to caller

Initiating a Request

The sequence of operations for initiating a request follows:
  1. Call DBCHCL for DBFIRQ.
  2. Check that return code is zero

A return code of zero does not imply that the Teradata SQL request was successful. It implies that the Teradata SQL request has been sent in to the database. That is, that the initial status is successful. If the request is successful on the client, the database processes it and sends the first portion (buffer-full) of the Teradata SQL response to the client.

Successful Request/Response Operation

The sequence of operations required for a successful request/response operation follows:
  1. Call DBCHCL for DBFIRQ.
  2. Check that return code is zero.
    See DBFFET for steps to take until response is “consumed” or no longer required. If rewind is required, see DBFREW and then DBFFET.
  3. Call DBCHCL for DBFERQ.
  4. Check that return code is zero.

If DBCHCL is called for DBFIRQ without having first called DBCHCL for DBFCON, DBCHCL returns with a return code, “first do a connect” (NOSESSION; 304).

The application program must provide Using Data Pointer and Using Data Length if the Teradata SQL request contains a USING modifier. CLI does not parse the Teradata SQL request, so it cannot coordinate the USING modifier and the using data. Similarly, it is the application program’s responsibility to set Using Data Length to zero if the Teradata SQL request does not contain a USING modifier.

If the call to DBCHCL for DBFIRQ results in a non-zero return code, the Initiate Request has failed for the reason indicated by the value of the return code. CLI internal structures for the non-existing request can (and should) be de-allocated by calling DBCHCL for the DBFERQ. The Output Request Id from DBFIRQ is the appropriate value to place in Input Request Id for the DBFERQ.

Interface

Function: DBFIRQ - Initiate ReQuest
Purpose: Initiate a request
Parms: