SQLCA Diagnostic Area
In multi-threaded applications, each thread is provided its own SQLCA diagnostic area. The global SQLCA data object should not be used due to contention between threads for the global resource. Two extensions are available in the ESQLC preprocessor for gaining access to a threads SQLCA diagnostic area.
The command line flag -multi may be used to prepare an ESQLC source file for multi-threaded execution without requiring any additional changes to the source file. The -multi flag changes the code generated by ESQLC for the include sqlca statement.
Normally, the following code is generated by ESQLC when the include sqlca statement is processed:
#include "eqsqlca.h"
extern IISQLCA sqlca;
When -multi is included on the command line, ESQLC generates the following when the INCLUDE SQLCA statement is processed:
#include "eqsqlca.h"
IISQLCA *IIsqlca();
#define sqlca (*(IIsqlca()))
Using the -multi flag defines a macro which translates all references to the global sqlca variable into a call to the ESQL function IIsqlca() which returns the address to the SQLCA diagnostic area for the current thread. No code changes are required to take advantage of multi-threaded features of the ESQLC pre-processor.
Minor changes may be made to ESQLC applications to reduce the number of calls to IIsqlca() generated as described above. The ESQLC preprocessor accepts declaration of hosts' variables whose type is IISQLCA. In addition, if the host variable is a pointer type, all subsequent SQLCA references generated by ESQLC will be using the host variable.
For example, the following variable declaration will declare a SQLCA pointer host variable and initialize it to the current threads SQLCA diagnostic area:
EXEC SQL BEGIN DECLARE SECTION;
IISQLCA*sqlca_ptr = IIsqlca();
EXEC SQL END DECLARE SECTION;
Subsequent references to the SQLCA diagnostic area may then be replaced with references to the host variable. Access to the previous error code would be coded as sqlca_ptr->sqlcode rather than sqlca.sqlcode. All subsequent SQLCA references generated by the ESQLC preprocessor use the application-declared host variable.
SQLCA variable declarations should not be global. Declarations are required in all functions containing ESQL statements.
ESQLC source files preprocessed with the –multi flag may be safely linked with files preprocessed without the -multi flag for single-threaded ESQL applications. The global SQLCA is assigned to the first (or only) thread to issue an ESQL statement.
It is recommended that applications issue an ESQL statement, such as inquire_sql or call IIsqlca() prior to starting multi-threaded execution so as to permit the ESQL runtime code to initialize safely.
Note: In multi-threaded applications, the SQLSTATE variable (or deprecated SQLCODE variable) should not be declared as a global variable. If used, SQLSTATE should be declared at the start of each function containing ESQL statements.
Last modified date: 01/30/2023