DBCHINI sets up the CLI environment. Applications must allocate the DBCAREA and then call DBCHINI to initialize it.
How It Works
- Initializing the DBCAREA
- Resetting the DBCAREA length field
- Setting all options to either their default (in CLI2SPB) or application specified values (in clispb.dat)
- Initializing MTDP for the application
Parameters
The DBCHINI parameters are as follows:
| Int32 | DBCHINI (ReturnCode, ContextArea, DBCAREA) |
| Int32 | *ReturnCode; |
| char | *ContextArea; |
| struct | DBCAREA |
where the following is true:
| For the Return Code Address | |
| Length: | 4 bytes |
| Input: | address of a four-byte integer return code variable |
| Output: | unchanged |
After control returns from DBCHINI, the integer contains a code whose value represents success or failure to initialize. Return code zero indicates the DBCAREA is initialized. A non-zero return code indicates failure, and the value specifies the reason for the failure.
| For the Context Area Address | |
| Length: | 4 bytes |
| Input: | 0 |
| Output: | address of the internal CLI context area |
Context Area is provided to maintain compatibility with calls on mainframe-attached systems.
| For the DBCAREA Address | |
| Length: | 4 bytes |
| Input: | address of the DBCAREA structure |
| Output: | unchanged |
Applications and CLI share the DBCAREA and use it for input of values to CLI and output of values from CLI.
Usage Notes
Application must declare or allocate the DBCAREA and call DBCHINI to initialize the fields prior to using CLI functions. Total Length must be filled in by the application before calling DBCHINI.
DBCHINI obtains default values from the SPB currently available to the application.
Applications are able to use the same DBCAREA for all requests. If this is the case, one call to DBCHINI is sufficient regardless of the number of sessions, requests, and so on, used by the application program. If the DBCAREA is used this way, Input Session Id, Input Request Id, and Token, if used, must be checked before each call, to ensure that they are appropriate for that call.
But the application can allocate and then initialize a new DBCAREA for each session and even for each request within each session. This is done by another call to DBCHINI with the new location. Using multiple DBCAREAs requires additional space for the extra DBCAREAs and additional time to allocate and initialize the extra DBCAREAs. However, this may result in saving some CPU time after the application program is in progress.
In addition to initializing the DBCAREA, DBCHINI also allocates and initializes some internal data structures.