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
15.10
Language
English (United States)
Last Update
2018-10-07
dita:id
B035-2418
lifecycle
previous
Product Category
Teradata Tools and Utilities

DBFIRQ

DBFIRQ is the Initiate Request function of DBCHCL; DBFIRQ sends a request to the Teradata 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, receives a return error indicating “unable to initiate because session is not logged on”
  • Ensures that 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 is:

    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 Teradata Database. That is, that the initial status is successful. If the request is successful on the client, the Teradata 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 is:

    1 Call DBCHCL for DBFIRQ

    2 Check that return code is zero

    Note: See “DBFFET” on page 212 for steps to take until response is “consumed” or no longer required. If rewind is required, see “DBFREW” on page 214 and then “DBFFET” on page 212.

    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).

    It is the application program’s responsibility to 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

     

    DBCAREA Parameters

    The following fields in the DBCAREA may be read or written to by DBCHCL’s DBFIRQ, depending on the application program’s environment.

    Input Arguments

  • Change Options
  • Character Set Pointer
  • Column Title and Format Information
  • Data Encryption
  • Extension Pointer
  • Keep Response
  • Input Session Id
  • Locate Mode
  • Maximum Parcel
  • Parcel Mode
  • Period-as-Struct
  • Request Buffer Length
  • Request Mode
  • Request Length
  • Request Pointer
  • Request Processing Option
  • Response Buffer Length
  • Response Mode
  • Return Identity Data
  • Return Time
  • Save Response Buffer
  • Set Character Set
  • Statement-status
  • Tell About Crash
  • Token
  • Transforms-off
  • Trusted-request
  • Two Response Buffers
  • Use Presence Bits
  • Using Data Length
  • Using Data Pointer
  • Variable Length Request
  • Variable Length Fetch
  • Wait Across Crash
  • Wait For Response
  • Output Arguments

  • Current Response Buffer Length
  • Current Request Buffer Length
  • Message Length
  • Message Text
  • MTDP Sent
  • Output Request Id
  • Return Code