Declaring the SQLCA

The SQL Communication Area (SQLCA) is an ALLBASE/SQL data structure that contains current information about a program's DBE session.

Every ALLBASE/SQL FORTRAN program unit that contains embedded SQL statements must contain an SQLCA declaration. When a main program unit or a subprogram unit starts a DBE session, the SQLCA declaration must be in its Type Declaration Section. If a subprogram unit is called by a main program and each contains SQL commands to be executed in the same DBE session, the SQLCA declaration must appear in both the main program and the subprogram units.

As shown in Figure 3-1 at 1, you declare the SQLCA by using the INCLUDE command:

     EXEC SQL INCLUDE SQLCA

When the FORTRAN preprocessor parses this command in the source file, it generates a complete FORTRAN declaration for this area. Some of the fields in the SQLCA are available for programmers to use:

   SQLCODE

   SQLERRD(3)

   SQLWARN(0)

   SQLWARN(1)

   SQLWARN(2)

   SQLWARN(6)

Some values ALLBASE/SQL places into these fields indicate warning and error conditions that resulted when the immediately preceding SQL command was executed. Other values simply provide information about normal command execution and are programmatically useful. For example, when you submit an UPDATE command, the number of rows updated is placed in SQLERRD(3). If this value is greater than 1, the program may want to advise the user of that condition and process a ROLLBACK WORK or COMMIT WORK command based on the user's response.

Examples discussed later in this chapter under "Implicit Status Checking" and "Explicit Status Checking" illustrate how the program in Figure 3-1 uses some of the SQLCA fields to determine the success or failure of SQL command execution.