SQL Abstraction Layer
[System]


Other constants

#define ALP_SAL_UTF8_COLLATOR   "alp_sal_utf8_collator"
 The ALP_SAL_UTF8_COLLATOR does locale-sensitive UTF8 collation (aka sorting). You 'add' it to a SAL session by calling alp_sal_install_utf8_collator() after calling alp_sal_database_open(); you tell SAL to use it by adding "COLLATE " ALP_SAL_UTF8_COLLATOR to your SQL, after an "ORDER BY" clause.

Error Codes

#define ALP_STATUS_SAL_ABORT   (ALP_CLASS_SAL | 0x00170000)
#define ALP_STATUS_SAL_AUTH   (ALP_CLASS_SAL | 0x000D0000)
#define ALP_STATUS_SAL_BADPARAM   (ALP_CLASS_SAL | 0x00190000)
#define ALP_STATUS_SAL_BUSY   (ALP_CLASS_SAL | 0x00010000)
#define ALP_STATUS_SAL_CANTOPEN   (ALP_CLASS_SAL | 0x00090000)
#define ALP_STATUS_SAL_CONSTRAINT   (ALP_CLASS_SAL | 0x000B0000)
#define ALP_STATUS_SAL_CORRUPT   (ALP_CLASS_SAL | 0x00070000)
#define ALP_STATUS_SAL_DMLEXISTS   (ALP_CLASS_SAL | 0x001B0000)
#define ALP_STATUS_SAL_EMPTY   (ALP_CLASS_SAL | 0x00120000)
#define ALP_STATUS_SAL_ERROR   (ALP_CLASS_SAL | 0x000E0000)
#define ALP_STATUS_SAL_FULL   (ALP_CLASS_SAL | 0x00080000)
#define ALP_STATUS_SAL_INTERNAL   (ALP_CLASS_SAL | 0x00150000)
#define ALP_STATUS_SAL_INTERRUPT   (ALP_CLASS_SAL | 0x00050000)
#define ALP_STATUS_SAL_IOERR   (ALP_CLASS_SAL | 0x00060000)
#define ALP_STATUS_SAL_LOCKED   (ALP_CLASS_SAL | 0x00020000)
#define ALP_STATUS_SAL_MISMATCH   (ALP_CLASS_SAL | 0x000C0000)
#define ALP_STATUS_SAL_MISUSE   (ALP_CLASS_SAL | 0x000F0000)
#define ALP_STATUS_SAL_NO_VALUE   (ALP_CLASS_SAL | 0x001C0000)
#define ALP_STATUS_SAL_NOLFS   (ALP_CLASS_SAL | 0x00100000)
#define ALP_STATUS_SAL_NOMEM   (ALP_CLASS_SAL | 0x00030000)
#define ALP_STATUS_SAL_NORECORDS   (ALP_CLASS_SAL | 0x001A0000)
#define ALP_STATUS_SAL_NOTFOUND   (ALP_CLASS_SAL | 0x00140000)
#define ALP_STATUS_SAL_PERM   (ALP_CLASS_SAL | 0x00160000)
#define ALP_STATUS_SAL_PROTOCOL   (ALP_CLASS_SAL | 0x00110000)
#define ALP_STATUS_SAL_READONLY   (ALP_CLASS_SAL | 0x00040000)
#define ALP_STATUS_SAL_SCHEMA   (ALP_CLASS_SAL | 0x00130000)
#define ALP_STATUS_SAL_TOOBIG   (ALP_CLASS_SAL | 0x000A0000)
#define ALP_STATUS_SAL_UNKNOWN   (ALP_CLASS_SAL | 0x00180000)

Typedefs

typedef int(* AlpSalCollator )(void *user_data, int length1, const void *string1, int length2, const void *string2)
 A Sqlite3 collation function.
typedef void * AlpSALHandle
 An AlpSALHandle is an opaque pointer that must be passed around as a reference to a database opened with alp_sal_database_open().
typedef void * AlpSALStatement
 An AlpSALStatement is an opaque structure used to bind host variables to a sql statement to be prepared for execution, and ultimately passed to other alp_sal_statement_* calls.

Data Access Functions

alp_status_t alp_sal_changes (AlpSALHandle sal, uint32_t *nRows)
 Returns the number of database rows that where changed (or inserted or deleted) by the most recently executed INSERT, UPDATE, or DELETE statement.
alp_status_t alp_sal_database_close (AlpSALHandle sal)
 Close given database handle, sal.
alp_status_t alp_sal_database_create (const char *dbFileName, const char *schemaFileName)
 Create a database and initializes its schema.
alp_status_t alp_sal_database_open (AlpSALHandle *sal, const char *dbName)
 Open a given database and return handle for it.
alp_status_t alp_sal_execute_sql_script (AlpSALHandle sal, FILE *fd)
 Read in and execute SQL commands from the given file descriptor.
const char * alp_sal_get_error_message (AlpSALHandle sal)
 Return string describing the last error generated by database.
alp_status_t alp_sal_install_collator (AlpSALHandle sal, const char *collate_name, AlpSalCollator collate_function, void *user_data)
 'Add' an arbitrary UTF8 collator (sort function) to a SAL session. (Use it by adding "COLLATE " COLLATE_NAME to your SQL, after an "ORDER BY" clause.)
alp_status_t alp_sal_install_utf8_collator (AlpSALHandle sal)
 'Add' a standard, locale-sensitive UTF8 collator (sort function) to a SAL session. (Use it by adding "COLLATE " ALP_SAL_UTF8_COLLATOR to your SQL, after an "ORDER BY" clause.)
alp_status_t alp_sal_last_insert_rowid (AlpSALHandle sal, uint32_t *rowID)
 Return rowID used as the last auto-generated primary key created by an SQL INSERT statement.
alp_status_t alp_sal_set_timeout (AlpSALHandle sal, int ms)
 Set the SQLite busy timeout.
alp_status_t alp_sal_sql_execute (AlpSALHandle sal, const char *sql,...)
 Execute a sql command given in a string buffer with a variable list of host parameter arguments.
alp_status_t alp_sal_sql_get_value (AlpSALHandle sal, int32_t *value, const char *sql,...)
 Execute a given SQL statement and return the value of the first column of the first row.
alp_status_t alp_sal_string_build (char **combined, const char *sql,...)
 Create a SQL string build up from the first parameter and the resulting substitution of supplied variables.
void alp_sal_string_destroy (char *s)
 Free the string created by alp_sal_string_build().
alp_status_t alp_sal_transaction_begin (AlpSALHandle sal, char exclusive)
 Execute "BEGIN TRANSACTION;" on the given database.
alp_status_t alp_sal_transaction_commit (AlpSALHandle sal)
 Execute "COMMIT TRANSACTION;" on the given database.
alp_status_t alp_sal_transaction_rollback (AlpSALHandle sal)
 Execute "ROLLBACK TRANSACTION;" on the given database.

Statement Functions

alp_status_t alp_sal_statement_destroy (AlpSALStatement *stmt)
 Destroys the AlpSALStatement stmt.
alp_status_t alp_sal_statement_execute (AlpSALStatement *stmt)
 Executes a AlpSALStatement that has been initalized with alp_sal_statement_initialize and which has had host parameters required by its SQL statement using AlpSALStatementSet commands.
void * alp_sal_statement_get_blob (AlpSALStatement *stmt, int pos, int32_t *size, bool copy)
 Retrieves blob value and size from the pos column of the current result set of the specified statement, stmt.
float alp_sal_statement_get_float (AlpSALStatement *stmt, int pos)
 Retrieve float value from the pos column of the current result set of the specified statement, stmt.
AlpSALHandle alp_sal_statement_get_handle (AlpSALStatement *stmt)
 Returns the AlpSALHandle bound to the statement, or NULL, if the stmt handle is invalid.
int32_t alp_sal_statement_get_int (AlpSALStatement *stmt, int pos)
 Retrieve integer value from the pos column of the current result set of the specified statement, stmt.
int64_t alp_sal_statement_get_int64 (AlpSALStatement *stmt, int pos)
 Retrieve 64 bit integer value from the pos column of the current result set of the specified statement, stmt.
char * alp_sal_statement_get_text (AlpSALStatement *stmt, int pos, bool copy)
 Retrieve text value from pos column of the current result set of the specified statement, stmt.
alp_status_t alp_sal_statement_initialize (AlpSALHandle sal, AlpSALStatement **stmt, const char *sql)
 Mallocs and initializes a AlpSALStatement pointed to by the AlpSALStatement handle parameter.
bool alp_sal_statement_is_null (AlpSALStatement *stmt, int pos)
 Check for NULL value in column of current result in stmt.
alp_status_t alp_sal_statement_next_result (AlpSALStatement *stmt)
 Get next result set of the specified statement, stmt.
alp_status_t alp_sal_statement_reset (AlpSALStatement *stmt)
 Reset a SQL query for specified statement, stmt, so it may be re-executed.
alp_status_t alp_sal_statement_set_blob (AlpSALStatement *stmt, int16_t pos, void *blob, int32_t size, bool copy)
 Bind a host blob variable to the specified position in the statement.
alp_status_t alp_sal_statement_set_float (AlpSALStatement *stmt, int16_t pos, float f)
 Bind a host float variable to the specified position in the statement.
alp_status_t alp_sal_statement_set_int (AlpSALStatement *stmt, int16_t pos, int32_t n)
 Bind a host integer variable to the specified position in statement.
alp_status_t alp_sal_statement_set_int64 (AlpSALStatement *stmt, int16_t pos, int64_t n)
 Bind a 64 bit host integer to the specified position in the statement.
alp_status_t alp_sal_statement_set_null (AlpSALStatement *stmt, int16_t pos)
 Bind a null to the specified position in the statement.
alp_status_t alp_sal_statement_set_text (AlpSALStatement *stmt, int16_t pos, const char *s, bool copy)
 Bind a host text variable to the specified position in the statement.

Define Documentation

#define ALP_SAL_UTF8_COLLATOR   "alp_sal_utf8_collator"
 

The ALP_SAL_UTF8_COLLATOR does locale-sensitive UTF8 collation (aka sorting). You 'add' it to a SAL session by calling alp_sal_install_utf8_collator() after calling alp_sal_database_open(); you tell SAL to use it by adding "COLLATE " ALP_SAL_UTF8_COLLATOR to your SQL, after an "ORDER BY" clause.

#define ALP_STATUS_SAL_ABORT   (ALP_CLASS_SAL | 0x00170000)
 

#define ALP_STATUS_SAL_AUTH   (ALP_CLASS_SAL | 0x000D0000)
 

#define ALP_STATUS_SAL_BADPARAM   (ALP_CLASS_SAL | 0x00190000)
 

#define ALP_STATUS_SAL_BUSY   (ALP_CLASS_SAL | 0x00010000)
 

#define ALP_STATUS_SAL_CANTOPEN   (ALP_CLASS_SAL | 0x00090000)
 

#define ALP_STATUS_SAL_CONSTRAINT   (ALP_CLASS_SAL | 0x000B0000)
 

#define ALP_STATUS_SAL_CORRUPT   (ALP_CLASS_SAL | 0x00070000)
 

#define ALP_STATUS_SAL_DMLEXISTS   (ALP_CLASS_SAL | 0x001B0000)
 

#define ALP_STATUS_SAL_EMPTY   (ALP_CLASS_SAL | 0x00120000)
 

#define ALP_STATUS_SAL_ERROR   (ALP_CLASS_SAL | 0x000E0000)
 

#define ALP_STATUS_SAL_FULL   (ALP_CLASS_SAL | 0x00080000)
 

#define ALP_STATUS_SAL_INTERNAL   (ALP_CLASS_SAL | 0x00150000)
 

#define ALP_STATUS_SAL_INTERRUPT   (ALP_CLASS_SAL | 0x00050000)
 

#define ALP_STATUS_SAL_IOERR   (ALP_CLASS_SAL | 0x00060000)
 

#define ALP_STATUS_SAL_LOCKED   (ALP_CLASS_SAL | 0x00020000)
 

#define ALP_STATUS_SAL_MISMATCH   (ALP_CLASS_SAL | 0x000C0000)
 

#define ALP_STATUS_SAL_MISUSE   (ALP_CLASS_SAL | 0x000F0000)
 

#define ALP_STATUS_SAL_NO_VALUE   (ALP_CLASS_SAL | 0x001C0000)
 

#define ALP_STATUS_SAL_NOLFS   (ALP_CLASS_SAL | 0x00100000)
 

#define ALP_STATUS_SAL_NOMEM   (ALP_CLASS_SAL | 0x00030000)
 

#define ALP_STATUS_SAL_NORECORDS   (ALP_CLASS_SAL | 0x001A0000)
 

#define ALP_STATUS_SAL_NOTFOUND   (ALP_CLASS_SAL | 0x00140000)
 

#define ALP_STATUS_SAL_PERM   (ALP_CLASS_SAL | 0x00160000)
 

#define ALP_STATUS_SAL_PROTOCOL   (ALP_CLASS_SAL | 0x00110000)
 

#define ALP_STATUS_SAL_READONLY   (ALP_CLASS_SAL | 0x00040000)
 

#define ALP_STATUS_SAL_SCHEMA   (ALP_CLASS_SAL | 0x00130000)
 

#define ALP_STATUS_SAL_TOOBIG   (ALP_CLASS_SAL | 0x000A0000)
 

#define ALP_STATUS_SAL_UNKNOWN   (ALP_CLASS_SAL | 0x00180000)
 

Typedef Documentation

typedef int(* AlpSalCollator)(void *user_data, int length1, const void *string1, int length2, const void *string2)
 

A Sqlite3 collation function.

Parameters:
[in] user_data Arbitrary 32-bit data, the 4th parameter to alp_sal_install_collator()
[in] length1 Length of the 'left' UTF8 string, in C chars (ie, NOT in glyphs)
[in] string1 Start of the 'left' UTF8 string
[in] length2 Length of the 'right' UTF8 string, in C chars (ie, NOT in glyphs)
[in] string2 Start of the 'right' UTF8 string
Returns:
Negative number iff string1 < string2, 0 iff string1 == string2, and positive number iff string1 > string2

typedef void* AlpSALHandle
 

An AlpSALHandle is an opaque pointer that must be passed around as a reference to a database opened with alp_sal_database_open().

typedef void* AlpSALStatement
 

An AlpSALStatement is an opaque structure used to bind host variables to a sql statement to be prepared for execution, and ultimately passed to other alp_sal_statement_* calls.

Function Documentation

alp_status_t alp_sal_changes (  AlpSALHandle  sal,
uint32_t *  nRows
) 
 

Returns the number of database rows that where changed (or inserted or deleted) by the most recently executed INSERT, UPDATE, or DELETE statement.

Only changes directly specified by the INSERT, UPDATE, or DELETE statements are counted. Auxiliary changes caused by triggers are not counted.

Note:
The command "DELETE FROM table" without a WHERE clause is implemented by dropping and recreating the table. (This is much faster than going through and deleting individual elements from the table.) Because of this optimization, the change count for "DELETE FROM table" will be zero regardless of the number of elements that were originally in the table. To get an accurate count of the number of rows deleted, use "DELETE FROM table WHERE 1" instead.
Parameters:
[in] sal AlpSALHandle of database
[out] nRows If not NULL, store number of rows changed
Returns:
ALP_STATUS_SAL_BADPARAM if sal or nRows are NULL ALP_STATUS_OK otherwise

alp_status_t alp_sal_database_close (  AlpSALHandle  sal  ) 
 

Close given database handle, sal.

Parameters:
[in] sal The AlpSALHandle to close
Returns:
alp_status_t
See also:
alp_sal_database_open

alp_status_t alp_sal_database_create (  const char *  dbFileName,
const char *  schemaFileName
) 
 

Create a database and initializes its schema.

Parameters:
[in] dbFileName Path to file to store the created database
[in] schemaFileName Path to file containing schema from which to create the database
Returns:
alp_status_t

alp_status_t alp_sal_database_open (  AlpSALHandle *  sal,
const char *  dbName
) 
 

Open a given database and return handle for it.

The database should be closed when no longer needed with alp_sal_database_close()

Parameters:
[out] sal Address of a pointer to the AlpSALHandle
[in] dbName Filename of the SQL database
Returns:
alp_status_t
See also:
alp_sal_database_close

alp_status_t alp_sal_execute_sql_script (  AlpSALHandle  sal,
FILE *  fd
) 
 

Read in and execute SQL commands from the given file descriptor.

Once the file's contents are read into memory, they are executed and then the buffer is freed. This is useful for initializing a table or schema using a resource file.

Parameters:
[in] sal AlpSALHandle of database to execute against
[in] fd Open file descriptor of a text file containing SQL commands
Returns:
alp_status_t

const char* alp_sal_get_error_message (  AlpSALHandle  sal  ) 
 

Return string describing the last error generated by database.

Parameters:
[in] sal database to read error string from
Returns:
pointer to string owned by SQL engine representing last error message generated

alp_status_t alp_sal_install_collator (  AlpSALHandle  sal,
const char *  collate_name,
AlpSalCollator  collate_function,
void *  user_data
) 
 

'Add' an arbitrary UTF8 collator (sort function) to a SAL session. (Use it by adding "COLLATE " COLLATE_NAME to your SQL, after an "ORDER BY" clause.)

Parameters:
[in] sal The database handle with which to use the collator.
[in] collate_name The name to use in SQL queries
[in] collate_function The C function to call
[in] user_data Arbitrary 32-bit data, the 1st parameter to the collate_function
Returns:
alp_status_t

alp_status_t alp_sal_install_utf8_collator (  AlpSALHandle  sal  ) 
 

'Add' a standard, locale-sensitive UTF8 collator (sort function) to a SAL session. (Use it by adding "COLLATE " ALP_SAL_UTF8_COLLATOR to your SQL, after an "ORDER BY" clause.)

Parameters:
[in] sal The database handle with which to use the collator.
Returns:
alp_status_t

alp_status_t alp_sal_last_insert_rowid (  AlpSALHandle  sal,
uint32_t *  rowID
) 
 

Return rowID used as the last auto-generated primary key created by an SQL INSERT statement.

Parameters:
[in] sal AlpSALHandle of database to execute against
[out] rowID Primary Key generated by last INSERT statement
Returns:
alp_status_t

alp_status_t alp_sal_set_timeout (  AlpSALHandle  sal,
int  ms
) 
 

Set the SQLite busy timeout.

Parameters:
[in] sal database handle
[in] ms timeout in ms; 0 turns off busy timeout at the SQLite level
Returns:
alp_status_t

alp_status_t alp_sal_sql_execute (  AlpSALHandle  sal,
const char *  sql,
  ...
) 
 

Execute a sql command given in a string buffer with a variable list of host parameter arguments.

After plugging in the host variables to the sql string, the sql is executed and the buffer created by this routine is freed.

In addition to the subsitution variables supported by printf, this routine also supports the variable: "%Q". When using Q, the string passed will get single quote escaped, or will get "NULL" if the string is null. If the string contains a single quote, it will be escaped (doubled) to form ''

Parameters:
[in] sal AlpSALHandle of database to execute against
[in] sql SQL string
[in] ... va_list of host variables to plug into SQL string
Returns:
alp_status_t

alp_status_t alp_sal_sql_get_value (  AlpSALHandle  sal,
int32_t *  value,
const char *  sql,
  ...
) 
 

Execute a given SQL statement and return the value of the first column of the first row.

The SQL statements are usually of the form "SELECT COUNT(*) FROM..." from which a statement will be prepared using the given host variables, if any. Then the statement is executed and the first column of the first row of the result set is read back and returned in value. If there is no match for the select statement, the value will NOT be set, and the status returned will be ALP_STATUS_SAL_NORECORDS.

Parameters:
[in] sal The database to execute the selection statement against
[out] value Will obtain the result from the selection.
[in] sql SQL format string
[in] ... Parameters to be used with format string.
Returns:
alp_status_t

alp_status_t alp_sal_statement_destroy (  AlpSALStatement *  stmt  ) 
 

Destroys the AlpSALStatement stmt.

Should always be called after you are done using a AlpSALStatement.

Parameters:
[in] stmt The AlpSALStatement to destroy
Returns:
alp_status_t

alp_status_t alp_sal_statement_execute (  AlpSALStatement *  stmt  ) 
 

Executes a AlpSALStatement that has been initalized with alp_sal_statement_initialize and which has had host parameters required by its SQL statement using AlpSALStatementSet commands.

Parameters:
[in] stmt AlpSALStatement to execute.
Returns:
alp_status_t

void* alp_sal_statement_get_blob (  AlpSALStatement *  stmt,
int  pos,
int32_t *  size,
bool  copy
) 
 

Retrieves blob value and size from the pos column of the current result set of the specified statement, stmt.

Parameters:
[in] stmt AlpSALStatement handle for a query statement that has been properly prepared and stepped with SALStatementNextResult()
[in] pos column to retrieve from current row (0 is the first row). Passing -1 causes the statement to use and increment an internal counter; useful if you want to retrieve all column values in the order they were specified in the SQL statement
[out] size size of blob in number of bytes
[in] copy true if a copy of the blob should be made before assigning to the text parameter
Returns:
pointer to data in indicated column of current row of stmt, or NULL if statement parameter was invalid

float alp_sal_statement_get_float (  AlpSALStatement *  stmt,
int  pos
) 
 

Retrieve float value from the pos column of the current result set of the specified statement, stmt.

Parameters:
[in] stmt AlpSALStatement handle for a query statement that has been properly prepared and stepped with SALStatementNextResult()
[in] pos column to retrieve from current row (0 is the first row). Passing -1 causes the statement to use and increment an internal counter; useful if you want to retrieve all column values in the order they were specified in the SQL statement
Returns:
float in indicated column of current row of stmt

AlpSALHandle alp_sal_statement_get_handle (  AlpSALStatement *  stmt  ) 
 

Returns the AlpSALHandle bound to the statement, or NULL, if the stmt handle is invalid.

Parameters:
[in] stmt statement of which to return handle from
Returns:
AlpSALHanlde returns the SAL datebase handle associated with the statement. Returns NULL if statement is NULL.

int32_t alp_sal_statement_get_int (  AlpSALStatement *  stmt,
int  pos
) 
 

Retrieve integer value from the pos column of the current result set of the specified statement, stmt.

Parameters:
[in] stmt AlpSALStatement handle for a query statement that has been properly prepared and stepped with AlpSALStatementNextResult()
[in] pos column to retrieve from current row (0 is the first row). Passing -1 causes the statement to use and increment an internal counter; useful if you want to retrieve all column values in the order they were specified in the SQL statement
Returns:
integer in indicated column of current row of stmt

int64_t alp_sal_statement_get_int64 (  AlpSALStatement *  stmt,
int  pos
) 
 

Retrieve 64 bit integer value from the pos column of the current result set of the specified statement, stmt.

Parameters:
[in] stmt AlpSALStatement handle for a query statement that has been properly prepared and stepped with AlpSALStatementNextResult()
[in] pos column to retrieve from current row (0 is the first row). Passing -1 causes the statement to use and increment an internal counter; useful if you want to retrieve all column values in the order they were specified in the SQL statement
Returns:
integer in indicated column of current row of stmt

char* alp_sal_statement_get_text (  AlpSALStatement *  stmt,
int  pos,
bool  copy
) 
 

Retrieve text value from pos column of the current result set of the specified statement, stmt.

Parameters:
[in] stmt AlpSALStatement handle for a query statement that has been properly prepared and stepped with SALStatementNextResult()
[in] pos column to retrieve from current row (0 is the first row). Passing -1 causes the statement to use and increment an internal counter; useful if you want to retrieve all column values in the order they were specified in the SQL statement
[in] copy true if a copy of the string should be made before assigning to the text parameter
Returns:
string (or copy) in indicated column of current row of stmt

alp_status_t alp_sal_statement_initialize (  AlpSALHandle  sal,
AlpSALStatement **  stmt,
const char *  sql
) 
 

Mallocs and initializes a AlpSALStatement pointed to by the AlpSALStatement handle parameter.

The AlpSALStatement is only valid for the lifetime of the SALHandle. Once a SALHandle is closed or destroyed, or the AlpSALStatement is no longer, needed, it should be destroyed with alp_sal_statement_destroy().

After initializing a AlpSALStatement, the user should call the appropriate AlpSALStatementSet API's, in order, once for each host variable that needs to be bound to a variable in the given sql string (ie, variables of the form "FieldName = ?").

Parameters:
[in] sal Handle to datamodel statement will execute against
[out] stmt A newly allocated AlpSALStatement that will contain a copy of the given string.
[in] sql A sql statement possibly containing substitution variables ("X = ?")
Returns:
alp_status_t

bool alp_sal_statement_is_null (  AlpSALStatement *  stmt,
int  pos
) 
 

Check for NULL value in column of current result in stmt.

Parameters:
[in] stmt AlpSALStatement handle for a query statement that has been properly prepared and stepped with SALStatementNextResult()
[in] pos column to retrieve from current row (0 is the first row). Passing -1 causes the statement to use and increment an internal counter; useful if you want to retrieve all column values in the order they were specified in the SQL statement
Returns:
bool true if the value is NULL

alp_status_t alp_sal_statement_next_result (  AlpSALStatement *  stmt  ) 
 

Get next result set of the specified statement, stmt.

Given a prepared statement containing a single SELECT statement, any substitution variable it contains bound to the appropriate host variables, this routine will advance to the next result matching the query.

Although this function will execute any statement without producing an error, it is important for the caller to only use this function to advance to the next result in a selection statement to ensure that notifications are handled properly

Parameters:
[in] stmt containing SELECT statement with substitution variables bound to the appropriate host variables
Returns:
alp_status_t: ALP_STATUS_SAL_NORECORDS if no records match the select statement or the statement has already found the last matching record. ALP_STATUS_OK, if a matching row is found

alp_status_t alp_sal_statement_reset (  AlpSALStatement *  stmt  ) 
 

Reset a SQL query for specified statement, stmt, so it may be re-executed.

Any variables set in the statement retain their values, but SALStatementNextResult will return the first result in the query again.

Parameters:
[in] stmt AlpSALStatement handle for a query statement that has been properly
Returns:
alp_status_t

alp_status_t alp_sal_statement_set_blob (  AlpSALStatement *  stmt,
int16_t  pos,
void *  blob,
int32_t  size,
bool  copy
) 
 

Bind a host blob variable to the specified position in the statement.

Parameters:
[in] stmt statement to which to bind the host variable to.
[in] pos Position of the substitution variable in the AlpSALStatement's SQL command (ie "?"). Position indicies start at 1 for the first variable. Pass a -1 will cause the AlpSALStatement to use and increment an internal counter which is useful if you plan to set all substitution variables in order.
[in] blob A host varabile that will be bound into the statement
[in] size Number of bytes in blob
[in] copy true if the Data Model should make it's own copy of the data provided.
Returns:
alp_status_t

alp_status_t alp_sal_statement_set_float (  AlpSALStatement *  stmt,
int16_t  pos,
float  f
) 
 

Bind a host float variable to the specified position in the statement.

Parameters:
[in] stmt to bind the host variable to. of the given string.
[in] pos Position of the substitution variable in the AlpSALStatement's SQL command (ie "?"). Position indicies start at 1 for the first variable. Pass a -1 will cause the AlpSALStatement to use and increment an internal counter which is useful if you plan to set all substitution variables in order.
[in] f A host varabile that will be bound into the statement
Returns:
alp_status_t

alp_status_t alp_sal_statement_set_int (  AlpSALStatement *  stmt,
int16_t  pos,
int32_t  n
) 
 

Bind a host integer variable to the specified position in statement.

Parameters:
[in] stmt statement to which to bind the host variable to.
[in] pos position of the substitution variable in the AlpSALStatement's SQL command (ie "?"). Position indicies start at 1 for the first variable. Pass a -1 will cause the AlpSALStatement to use and increment an internal counter which is useful if you plan to set all substitution variables in order.
[in] n A host varabiale that will be bound into the statement
Returns:
alp_status_t

alp_status_t alp_sal_statement_set_int64 (  AlpSALStatement *  stmt,
int16_t  pos,
int64_t  n
) 
 

Bind a 64 bit host integer to the specified position in the statement.

Parameters:
[in] stmt statement to which to bind the host variable to.
[in] pos position of the substitution variable in the AlpSALStatement's SQL command (ie "?"). Position indicies start at 1 for the first variable. Pass a -1 will cause the AlpSALStatement to use and increment an internal counter which is useful if you plan to set all substitution variables in order.
[in] n A host varabiale that will be bound into the statement
Returns:
alp_status_t

alp_status_t alp_sal_statement_set_null (  AlpSALStatement *  stmt,
int16_t  pos
) 
 

Bind a null to the specified position in the statement.

Parameters:
[in] stmt statement to which to bind the host variable to.
[in] pos position of the substitution variable in the AlpSALStatement's SQL command (ie "?"). Position indicies start at 1 for the first variable. Pass a -1 will cause the AlpSALStatement to use and increment an internal counter which is useful if you plan to set all substitution variables in order.
Returns:
alp_status_t

alp_status_t alp_sal_statement_set_text (  AlpSALStatement *  stmt,
int16_t  pos,
const char *  s,
bool  copy
) 
 

Bind a host text variable to the specified position in the statement.

Parameters:
[in] stmt statement to which to bind the host variable to.
[in] pos position of the substitution variable in the AlpSALStatement's SQL command (ie "?"). Position indicies start at 1 for the first variable. Pass a -1 will cause the AlpSALStatement to use and increment an internal counter which is useful if you plan to set all substitution variables in order.
[in] s a text host variable that will be bound into the statement
[in] copy true if the should make it's own copy of the data provided.
Returns:
alp_status_t

alp_status_t alp_sal_string_build (  char **  combined,
const char *  sql,
  ...
) 
 

Create a SQL string build up from the first parameter and the resulting substitution of supplied variables.

The SQL string can embed any of the standard C variable types (ie, "%d", "%s", etc) and it also provides a new variable type: "%q" that should be used for any string substitution which may have a single quotation mark. Single quotation marks are escaped (doubled) when substitution is performed on them.

The caller should free the string returned in the first parameter, combined, by calling alp_sal_string_destroy

Parameters:
[out] combined The resulting SQL statement with all variables substituted in.
[in] sql Any string (usually a SQL statement) that has substitution variables such as "%d", "%s" and the special "%q" described above
[in] ... Host variables that will be substituted into the sql string.
See also:
SALStringDestroy
Returns:
alp_status_t

void alp_sal_string_destroy (  char *  s  ) 
 

Free the string created by alp_sal_string_build().

On most platforms (except notably Windows) it should be safe to just call "free" instead of SALStringDestroy(), so this API may be depricated

Parameters:
[in] s String to free
See also:
SALBuildString

alp_status_t alp_sal_transaction_begin (  AlpSALHandle  sal,
char  exclusive
) 
 

Execute "BEGIN TRANSACTION;" on the given database.

Parameters:
[in] sal Database to execute against.
[in] exclusive flag indicating whether to use "BEGIN EXCLUSIVE TRANSACTION;"
Returns:
alp_status_t

alp_status_t alp_sal_transaction_commit (  AlpSALHandle  sal  ) 
 

Execute "COMMIT TRANSACTION;" on the given database.

Parameters:
[in] sal Database to execute against.
Returns:
alp_status_t

alp_status_t alp_sal_transaction_rollback (  AlpSALHandle  sal  ) 
 

Execute "ROLLBACK TRANSACTION;" on the given database.

Parameters:
[in] sal Database to execute against.
Returns:
alp_status_t

Generated on Wed Jul 30 07:06:44 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation

Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.