SPQL API Functions

spqlinit()

Initializes the SPQL library for operation.

int spqlinit(void)

Usage: Performs a one-time initialization which enables the SPQL library to function. For this reason, you must call spqlinit() at least once to activate an SPQL program. Do not make other SPQL API calls before calling this function. If you do, the results are unpredictable. When spqlinit() successfully completes, you can safely proceed to use the SPQL API in a multi-threaded context.

Note: Spqlinit()-is not a thread-safe function. Call it only within a single-threaded context in your application. Alternatively, call it within an application-controlled mutex region.

Parameters: None

Returns: 0 if successful; SPQL_INITFAILED if the initialization fails.

spqlterm()

Is the termination counterpart of the spqlinit() function.

int spqlterm(void)

Usage: Terminates the SPQL library session, disconnecting all active SPD Server SQL server connections and freeing up the memory resources associated with the SPQL run-time library executables.

Parameters: None

Returns: 0 if successful.

spqlconnect()

Establishes a connection to a specified SPD Server SQL server.

int spqlconnect(char *constr, void **contok)

Usage: Establishes a connection to the SPD Server SQL server. The constr parameter specifies all the connection information needed to establish the connection to an SPD Server SQL server. When a connection is made successfully, a connection, token (contok) is returned to the caller.

Parameters:

char *constr

A null-terminated string identifying the SPD Server SQL server to connect to for this session. The syntax for the string is identical to that used for the SAS PROC SQL Pass-Through CONNECT statement.

void **contok

Returns a connection token if the connection successfully completes. You must retain the token; use it in subsequent SPQL library operations that you perform using the connection.

Returns: 0 if successful; SPQL_NOMEM if unable to allocate memory for the connection token; SPQL_CONFAILED if unable to connect successfully to the SPD Server SQL server.

spqldisconnect()

Terminates a connection from the SPD Server SQL server specified with a spqlconnect().

int spqldisconnect(void *contok)

Usage: Disconnects from a specified SPD Server SQL server. The caller passes the connection token which was returned from an spqlconnect() call. Then, the SPD Server SQL server associated with the connection is disconnected from the caller, and the memory associated with connection token is returned to the system.

Parameters:

void *contok

Connection token previously obtained from spqlconnect().

Returns: 0 if successful.

spqlperform()

Submits an SQL statement for execution on a given connection.

   int spqlperform(void *contok, char *stmtbuf, int stmtlen,
                   int *actions, void **stmttok);

Usage: Performs specified SQL statement and informs caller of the results. The actions parameter returns a value of 0 if no additional action is required. If actions are required to complete the statement, one or more of the following bit flags are returned.

   Flag          Action
   ----------    ---------------
   SPQLDATA      Data is returned(see spqlfetch())
   SPQLCOLINFO   Column information is returned(see spqlcolinfo())

Parameters:

void *contok

The connection used to execute the SQL statement.

char *stmtbuf

A buffer that holds the SQL statement to perform.

int stmtlen

The length of the SQL statement in buffer; -1 if null-terminated.

int *actions

Returns post-processing notification bit flags.

void **stmttok

Returns a statement token to use in post-processing the SQL statement results. See post-processing action definitions for use of statement token.

Returns: 0 if the SQL statement is successfully prepared or executed; SPQL_BADSTMT if the SQL statement specified in the statement buffer is prepared incorrectly; SPQL_NOMEM if spqlperform cannot allocate memory for the statement token.

spqlfreestok()

Generates a free statement token from spqlperform().

int spqlfreestok(void *stmttok);

Usage: Free resources used for the statement token from spqlperform(). Call spqlfreestok() after the data or information from the statement token has been extracted. You can call this function before all selected rows from the spqlperform() are read. If you do, the remaining unread rows (from the previous select) are discarded.

Parameters:

void *stmttok

Statement token to free

Returns: 0 if successful.

spqltabinfo()

Gets table information from a statement token.

int spqltabinfo(void *stmttok, spqltinfo_t **tinfo)

Usage: Interrogates the statement token for table information. Upon return of the call, updates tinfo with the pointer to the spqltinfo_t structure in the statement.

Note: Treat the structure accessed by the returned pointer as read-only memory.

Parameters:

void *stmttok

The statement token to use to access table information from a 'select'.

spqltinfo **tinfo

Returns pointer to spqltinfo_t structure into the statement token memory.

Returns: 0 for successful completion.

spqlcolinfo()

Gets column information from a statement token.

int spqlcolinfo(void *stmttok, int *ncols, spqlcinfo_t **colvec)

Usage: Interrogates token for column information. Upon return of the call, updates ncols with the column count selected in the statement and updates colvec with the pointer to the vector of spqlcol_t structures in the statement.

Note: Treat structures accessed by the returned pointer as read-only memory.

Parameters:

void *stmttok

The statement token to use to access column information from 'select'.

int *ncols

Returns in the statement token the number of columns selected.

spqlcinfo **colvec

Returns in the statement token a pointer to the array of spqlcinfo_t structures.

Returns:0 if successful.

spqlfetch()

Gets row data from a statement token.

int spqlfetch(void *stmttok, void **bufptr, int *bufsize)

Usage: Fetches the rows returned from executing a statement. Each call to spqlfetch returns a row from a statement to the caller's buffer. If bufptr contains a NULL value, the routine returns a pointer to a buffer containing the next row. If the value is not NULL, it assumes that the buffer is owned by the caller and returns the data to the caller's buffer. In either case, bufsize is updated with the row length returned. Callers that use locate-mode spqlfetch semantics (that is, who specify bufptr as NULL), should NEVER FREE the memory pointer returned by spqlfetch. A call to spqlfetch(), after all rows for the statement are returned, returns a bufsize of 0.

Parameters:

void *stmttok

The statement token to use to access row data from 'select'.

void **bufptr

Contains a pointer to the caller's row buffer to fill with row data. If it is NULL on entry, it returns a pointer to the internal statement buffer.

int *bufsize

Returns the size of the row buffer that was returned to the caller.

Returns: 0 if successful; SPQL_ENDDATA if the statement has no more rows to return; SPQL_FETCHFAILED if there is an unexpected failure while fetching the next row buffer.

spqlgmsg()

Accesses thread-specific error or diagnostic message buffer contents.

int spqlgmsg(char **mbuf)

Usage: Returns a pointer to the threads error or diagnostic message buffer. Call spqlgmsg() to get any diagnostic messages if you encounter an error executing an SPQL function. If there is message information, spqlgmsg() returns the message pointer in the mbuf parameter as well as the length of the message (the function return value).

Parameters:

char **mbuf

Returns a pointer to the thread's error or diagnostic message buffer. If mbuf is NULL, there is no message information. The call also returns the length of the thread's error or diagnostic message buffer. A 0 indicates that no message exists.