User's Guide Part V. The SQL Anywhere Programming Interfaces Chapter 38. The WSQL HLI InterfaceWSQL HLI has six functions:
| Ordinal | Function Name | Comments |
| 3 | wsqlexec | execute a command |
| 4 | wsqlgetfield | get a result column value |
| 5 | wsqlgetcolumnname | get a result column name |
| 6 | wsqlquerytomem | retrieve results in one piece of memory |
| 7 | wsqllasterror | get error string for last error |
| 8 | wsqlregisterfuncs | register host variable callback functions |
The Windows DLL entry points are all FAR PASCAL functions and all pointers are far pointers. The OS/2 DLL entry points are all _System functions. The Windows NT entry points are all __stdcall functions.
All functions return a long integer containing a SQL error code indicating the success or failure of the function. The wsqllasterror function can be called to get a meaningful message about the last error. See "SQL Anywhere Database Error Messages" for a complete list of error codes. The following sections describe these functions in detail.
The wsqlexec function is used to process all SQL requests, such as PREPAREing statements or OPENing cursors. In OS/2, the wsqlexecrexx function can be used from a REXX program (see "WSQL HLI and REXX").
The C prototype for this function is:
extern long _entry wsqlexec(char *command);
The command must be one of the following:
These commands are described fully in "wsqlexec command strings".
The wsqlgetfield function is used to retrieve the data value from one column of the most recently FETCHed row of a query result set.
The C prototype for this function is:
extern long _entry wsqlgetfield(char * cname,int offset,short * ind,char * result,int len);
cname name of a cursor which is opened and positioned at the row of the query result set that you want to examine.
offset the column number which you wish to examine. Columns are numbered from left to right starting at 0.
ind indicator variable. If the result buffer is too small, then the required length is put in the indicator variable. If the requested item is null, then the indicator is set to -1, and if there is a conversion error, then the indicator is set to -2. Otherwise, it is set to zero.
result string buffer which will be filled in with the requested column name. The result buffer should be allocated and freed by the calling application.
len maximum number of characters that can be placed in the result buffer.
The wsqlgetcolumnname function is used to get one column name of a query result set.
The C prototype for this function is:
extern long _entry wsqlgetcolumnname(char * cname,int offset,short * ind,char * result,int len);
cname name of a cursor that has been opened.
offset the column number whose name you want. Columns are numbered from left to right starting at 0.
ind indicator variable. If the result buffer is too small, then the required length is put in the indicator variable. Otherwise, it is set to zero.
result string buffer that will be filled in with the requested column name. The result buffer should be allocated and freed by the calling application.
len maximum number of characters that can be placed in the result buffer.
The wsqlquerytomemdelim function is used to place a portion of a query result set into a memory buffer.
If column names are requested, then the resulting buffer will start with a list of column names.
If data is requested, then the buffer will contain all of the rows of the query result set from the current cursor position to the end of the result set. If the supplied buffer is not large enough, then as many rows as will fit will be placed in the result buffer, and the cursor will be positioned on the row following the last one placed in the buffer. If this occurs, then the return code will be SQLE_HLI_MORE_DATA_AVAILABLE.
Each row will end with the specified rowdelim and the data in the row will be separated by coldelim.
The C prototype for this function is:
extern long _entry wsqlquerytomemdelim(char * cursor,char * result,int len,bool data,bool names,char * coldelim,char * rowdelim);
cursor name of a cursor that is opened and (if you want data) positioned at the first row of data to be returned.
result character buffer, allocated by the calling application. It will be filled in with as many rows as possible from the result set, starting at the current cursor position.
len maximum number of characters that should be placed in the result buffer.
data flag indicating that you want the buffer to contain query results. If data is zero, then no query results will be returned. Otherwise, query results will be returned, starting from the current cursor position.
names flag indicating that you want a list of column names. If it is zero, then column names will not be included. Otherwise, a list of column names will be placed at the beginning of the returned buffer.
coldelim A string that will be placed between each column name and each column value.
coldelim A string that will be placed at the end of the column names and at the end of each data row.
The wsqlquerytomem is similar to the wsqlquerytomemdelim function except the column delimiter is fixed as the tab character and the row delimiter is a carriage return - linefeed pair.
The C definition for this function is:
extern long _entry wsqlquerytomem(char * cursor,char * result,int len,bool data,bool names,){return( wsqlquerytomemdelim( cursor, result,len, data, names, ".t", ".r.n" ) );}
The parameters are the same as those for wsqlquerytomemdelim.
The wsqllasterror function is used to provide a meaningful message explaining the last error condition. :note.The return code will be the number of the last error condition.
The C prototype for this function is:
extern long _entry wsqllasterror(char * buffer,int len);
buffer string buffer which will be filled in with an error message. It should be allocated and freed by the calling application.
len maximum number of characters that can be placed in buffer. For a complete description of SQL Anywhere errors, see "SQL Anywhere Database Error Messages".
The wsqlregisterfuncs function is used to register callback functions for host variables (see "Host variables with WSQL HLI"). Host variable use is optional. It is best used when your application system has the concept of variables and you can provide a callback function to access them. It is not necessary to register callback functions in order to use host variables from REXX.
The C prototype for this function is:
extern long _entry wsqlregisterfuncs(p_callback PutHostVar,p_callback GetHostVar);
The Windows callbacks are FAR PASCAL functions that are exported and all pointers are far pointers. The OS/2 callbacks are _System functions. The Windows NT callbacks are __stdcall functions.
PutHostVar pointer to a callback function with the following prototype:
extern long _callback PutHostVar(char * name,short ind,char * value,int len);
name name of the host variable whose value WSQL HLI wishes to change.
ind indicator variable for the value of the host variable. See "Indicator variables" for details.
value new value for the host variable. It is always a null terminated string.
len number of characters in value.
return value a SQL error code indicating the success or failure of the operation. If the host variable or its value are invalid, then the return value should be the SQLE_HLI_BAD_HOST_VAR_VALUE or SQLE_HLI_BAD_HOST_VAR_NAME codes.
GetHostVar pointer to a callback function with the following prototype:
extern long _callback GetHostVar(char * name,short * ind,char * * value,int * len);
name name of the host variable whose value is needed by WSQL HLI.
ind place to put an indicator value, if one exists, for the host variable.
value pointer to a string buffer pointer. The GetHostVar function should fill in value with a pointer to a buffer containing the value of the host variable.
len number of characters placed in value by the function.
return value a SQL error code indicating the success or failure of the operation. If the host variable is invalid, then the return value should be the SQLE_HLI_BAD_HOST_VAR_NAME code.