All Open ClientConnect functions return success or failure indications in their RETCODE arguments. It is highly recommended that applications check these return codes for each call.
In addition, Open ClientConnect applications must handle three types of error and informational messages:
Open ClientConnect messages, also known as “client messages,” are generated by the functions documented in this book. They range in severity from informational messages to fatal errors.
Operating system messages.
Server messages—messages generated by the server. Server messages also range in severity from informational messages to fatal errors.
For a list of messages, see the Mainframe Connect Client Option and Server Option Messages and Codes.
Client-Library return codes begin with “CS-”. The codes returned to each Client-Library function are listed on the reference pages for that function, under “Returns.”
Gateway-Library return codes all begin with “TDS-”. However, on the mainframe, a few TDS-XXX return codes are returned to Client-Library functions. Some are returned to both Gateway-Library and Client-Library functions.
TDS-XXX return codes that are returned to specific functions only are documented on the reference pages for those functions, under “Returns.” Programs using these functions should check for these codes.
Some TDS-XXX return codes can be returned to any function under certain circumstances.
You can find a list of all TDS-XXX codes in the Mainframe Connect Client Option and Server Option Messages and Codes.
A Client-Library application uses the function CTBDIAG to handle messages in line. CTBDIAG returns message information to two structures defined within the application: the CLIENTMSG structure for client messages, and the SERVERMSG structure for server messages.
An application calls CTBDIAG to initialize in-line message handling for a connection. CTBDIAG cannot be used at the context level.
Whenever a Client-Library function returns CS-FAIL,
you must run CTBDIAG to determine what the error
is.
An application can retrieve messages into SQLCA and SQLCODE structures. If the application uses these structures, it must set the property CS-EXTRA-INF to CS-TRUE, using CTBCONALLOC. This is because the SQL structures require information that Client-Library does not customarily return. If CS-EXTRA-INF is not set, a loss of information occurs. For more information, see “The CS-EXTRA-INF property”, and “SQLCA structure”.
For additional information on the in-line method of handling function and server messages, see CTBDIAG and the topics “CLIENTMSG structure” and “SERVERMSG structure”.
