DBFFET - Call-Level Interface Version 2

DBFFET

DBFFET is the Fetch function of DBCHCL.

DBFFET delivers a pointer to the next parcel of the response.

How It Works

DBFFET performs the following functions:

If request is still active, waits for completion

If the application has requested option updates, performs option set/validation logic

If this is the first FET call, examines first parcel

If double buffering is set and the current buffer is not the last, dispatches continue request on the second buffer

Returns the next output data

If in Buffer Mode, which is necessarily Locate Mode, returns pointer to next buffer

If in Parcel Mode, returns next parcel

If buffer is exhausted, sets return code to indicate this

Delivers a pointer to the next unit (parcel or buffer) of the response

If in Move Mode, moves the parcel from the Response buffer to a location specified by the application program

Submitting a Fetch

The sequence of operations to submit a fetch is:

1 Call DBCHCL for DBFFET

2 Check that return code is zero

Successful Fetch Operation

The sequence of operations for a successful fetch operation is:

1 Call DBCHCL for DBFFET

2 Check that return code is zero

3 If in Move Mode, check that Fetch Error Indicator is zero

If in Parcel Mode, check that parcel is not Error or Failure parcel and “consume” the information in the parcel

If in Buffer Mode, check that parcel is not Error or Failure parcel and “consume” the information in the parcel

4 Repeat check and “consume” steps for each parcel in buffer

Combination of Modes

There are four combinations of modes for working with the parcels in the response:

Locate Mode with Parcel Mode

The application program can leave the parcels in the response buffer (Locate Mode) and obtain the address of the next parcel (Parcel Mode) each time it calls DBCHCL for DBFFET.

Locate Mode with Buffer Mode

The application program can leave the parcels in the response buffer (Locate Mode) and obtain the address of the whole buffer (Buffer Mode) each time it calls DBCHCL for DBFFET. It is then the application program’s responsibility to separate the parcels, if required.

Move Mode with Parcel Mode

The application program can have the parcels copied (Move Mode) from the response buffer into the Move area, one parcel (Parcel Mode) each time DBCHCL is called for DBFFET. This method is very convenient for the application program, at the small cost of the extra space for the Move area and the extra time for DBCHCL to copy the parcel.

Move Mode with Buffer Mode

The application program can have the complete response buffer copied (Move Mode) into the Move area. DBCHCL is called for DBFFET. This method should only be used if the application program must have the complete response buffer copied into its process space. Expect performance to be taxed, because of the extra space for the Move area and the extra time for DBCHCL to copy the parcel.

Interface

The DBFFET interface is as follows:

Function:	DBFFET - Fetch
Purpose:	Fetch next parcel (analogous to SQL ‘FETCH‘)
Parms:

DBCAREA Parameters

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

Input Arguments

Change Options

Fetch Data Pointer (if Move Mode)

Fetch Maximum Data Length

Function

Input Request Id

Input Session Id

Return Time

Tell About Crash

Wait Across Crash

Wait For Response

Output Arguments

Current Response Buffer Length

Fetch Data Pointer (if Locate Mode)

Fetch Error Indicator (if Move Mode)

Fetch Parcel Flavor (if Parcel Mode)

Fetch Returned Data Length

Message Length

Message Text

MTDP Received

MTDP Sent

Output DBC Session Id (after associated connect)

Output DBCpath (after associated connect)

Output Host Id (after associated connect)

Return Code