SQL/MX 3.2 Programming Manual for C and COBOL (H06.25+, J06.14+)

Host Variables in C/C++ Programs
HP NonStop SQL/MX Release 3.2 Programming Manual for C and COBOL—663854-002
3-39
Creating C Host Variables Using INVOKE
:hv_salary ;
/* Process the row that contains the null salary. */
/* Branch back to FETCH the next row. */
...
EXEC SQL CLOSE get_null_salary ;
...
Creating C Host Variables Using INVOKE
The INVOKE preprocessor directive creates a structure with the names of the host
variables corresponding to columns in a table or view. INVOKE converts the column
names to C identifiers and generates a C declaration for each column. If a column
allows null, INVOKE also creates an indicator variable for the column.
You can declare host variables that correspond to the columns in an SQL table or view
without using an INVOKE statement. However, using an INVOKE statement to
generate host variables has these advantages:

Program independence: If you modify a table or view, the INVOKE statement re-
creates the host variables to correspond to the new table or view when you run the
SQL/MX C preprocessor. However, you must modify a program that refers to a
deleted column or accesses a new column.

Performance: The INVOKE statement maps SQL data types to the corresponding
host language data types, and usually no data conversion is required at run time.
For further information, see Example 3-1 on page 3-43 and Example 3-2 on
page 3-44.

Program readability and maintenance: The INVOKE statement creates host
variables using the same names as column names in the table or view.
Using the INVOKE Directive
To execute an INVOKE directive for a table or view, you must have SELECT privileges
on all applicable columns when you run the SQL/MX C preprocessor. The general
syntax for using an embedded INVOKE directive within an SQL Declare Section in a
C program is:
EXEC SQL INVOKE table-or-view [AS structure-name];
struct structure-name structure-instance ;
For complete syntax, see the INVOKE Directive in the SQL/MX Reference Manual.
The struct declaration declares structure-instance to be a structure of the type
named structure-name.You must declare a variable of the struct type so that
you can use that variable in your C language statements.
If you do not specify the AS clause in the INVOKE statement, the default structure
name is the simple name of the table or view with the suffix _type appended. For
example: mytable_type.