Host variables with WSQL HLI

Part V. The SQL Anywhere Programming Interfaces

Chapter 38. The WSQL HLI Interface
Host variables with WSQL HLI

A host variable is a variable in an application which can be used (referenced) by WSQL HLI. Host variable support is an optional feature and requires the application to provide callback functions for host variable access. The Visual Basic interface does not provide host variable support. OS/2 REXX host variable support is provided by WSQL HLI (see "WSQL HLI and REXX").

Host variables provide a convenient way to use program variables in SQL commands that are sent to WSQL HLI. You can also use host variables to FETCH values directly into program variables rather than using the wsqlgetfield function.

For example, if you had an application variable myquery containing a SELECT statement that you wanted to execute, then you could prepare it like this:

     return_code = wsqlexec("PREPARE Stmt1 FROM :myquery");

The following rules should be noted:

Host variable names must be under 30 characters long.
To distinguish host variables from regular text, they must be prefixed with a colon. (See the example above.)

WSQL HLI needs some way to reference host variables, to both access and change their contents. To do this, a pair of callback functions must be supplied to WSQL HLI. When WSQL HLI encounters a host variable, it calls the appropriate callback function to either retrieve or set the variable's value. For this reason, it is necessary to call the function wsqlregisterfuncs before using any host variables. wsqlregisterfuncs takes two parameters, both pointers to callback functions. The first function, PutHostVar specifies a host variable name and the string to put in it. The second function, GetHostVar specifies a host variable name and the address of a string pointer to fill in with its value. See "wsqlregisterfuncs" for more information.

For example, the statement:

     wsqlexec( "FETCH Cursor1 INTO :host1" );

would call the function registered as PutHostVar with the name host1 and the value of the item fetched (converted to a string). Your application's callback function would then identify the host variable and save the new value.