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 are generated by the server. They range in severity from informational messages to fatal errors.
For a list of messages, see the Mainframe Connect Client Option Installation and Administration Guide.
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 “Return value.”
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 “Return value.” 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 Installation and Administration Guide.
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 the reference page for the function CTBDIAG, as well as the topics “CLIENTMSG structure” and “SERVERMSG structure”.
The CS_EXTRA_INF property is used by an application to determine the number of rows affected by the most recent command. If you want this extra information, you must set this property before you call the function.
An application can determine the number of rows in two ways:
An application that is retrieving messages into a SQLCA or SQLCODE structure must set the property CS_EXTRA_INF to CS_TRUE, using CTBCONPROPS. This is necessary because the SQLCA structure needs to know the number of rows affected, information that functions do not customarily return. If CS_EXTRA_INF is not set, a loss of information occurs.
An application that is not using SQLCA or SQLCODE can also set CS_EXTRA_INF to CS_TRUE. In this case, the extra information is returned as standard Client-Library messages.
For further information on the use of the SQLCA and SQLCODE structures in Open ClientConnect, turn to “SQLCA structure” and “SQLCODE structure”.
For three-tier processing, requests directed to an Adaptive Server or an Open Server application are sent to Mainframe ClientConnect (MCC), supplied with the Sybase DirectConnect product.
For two-tier processing, requests are sent directly to an Adaptive Server.
MCC allows mainframe transactions to access the LAN-based environment in which Sybase servers operate. It logs in to the target server, passing along login information, does the necessary conversions, and forwards the request. When results are ready, it passes them from the server to the client, again performing any necessary conversions.
MCC is transparent to the mainframe application. You specify the name of the server in the SERVERNAME parameter of the CTBCONNECT call, and the MCC forwards the request to the specified server.
To learn how CICS or IMS TM determines the MCC and connections to use to connect to the target server, see the Mainframe Connect Server Option Installation and Administration Guide. The client program is not concerned with these details.
Requests to Open ServerConnect are sent
directly from one transaction processing station to another and
do not use Mainframe ClientConnect.
