DBCHCL calls the functions requested by the application program.
For an overview of the functions relative to DBCHCL (see the table under Use of CLIv2 Routines: Tabular Summary). Each function is described in detail later in the sections that follow.
How It Works
Before each call to DBCHCL, the application program 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 and then passes back to the caller the DBCAREA, which contains, among other things, a return code.
The application program checks the return code in the DBCAREA, which is where CLI and MTDP indicate any problem they find. If the call resulted in a delivery of parcels to the response buffer, the program checks the first parcel, which is the Error and Failure parcel.
Parameters
The DBCHCL parameters are as follows:
Int32 | DBCHCL (ReturnCode, ContextArea, DBCAREA) |
Int32 | *ReturnCode; |
char | *ContextArea; |
struct | dbcarea_struct *dbcarea; |
where the following is true:
The parameter . .buffer-full | Is the... |
---|---|
ReturnCode | Four-byte address of an area allocated by the application program for storage of a four-byte signed integer. After control returns from DBCHCL, the integer contains a code whose value represents success or failure of the function as seen by CLI and MTDP. A return code of zero indicates success. A non-zero return code indicates failure, and the value specifies the reason. The return code covers only the work done on the client, it does not cover any work that may have been done on the database.
|
ContextArea | Four-byte field that may contain any value because it is not used by CLI or the application program. It is provided to maintain compatibility with calls on mainframe-attached systems. |
DBCAREA | Four-byte address of the area allocated by the application program for use as DBCAREA. The application program and CLI share the DBCAREA and use it for input of values to CLI and output of values from CLI. |
Usage Notes
- The application program must call DBCHINI to initialize the DBCAREA to be used by DBCHCL.
- The application program must provide input in the DBCAREA whose address is provided to DBCHCL. The function code must always be provided. The other input that must be provided is determined by the function code chosen.
- If the application program is running with Wait For Response set to 'Y', a return code of busy (EM_NODATA 211) will not be encountered.
- If the application program is running with Wait For Response set to 'N', a return code of busy may be encountered.
What Busy Means
- If the return code from DBCHCL is busy, call DBCHCL for the same function, repeat.
- If the return code from DBCHCL is busy, call DBCHWAT, check for a DBCHWAT return code of zero, call DBCHCL for the same function, repeat.
The second method is strongly preferred because it does not tie up the system during the wait period.