This SA Function Reference contains information about using SA Interface. The SA Interface is a direct database engine API for applications that require extremely high throughput. The performance benefit is gained by avoiding the SQL Parsing and Optimization phase and by allowing the application to group several table-level operations into one network message.
Currently, this manual contains only the function reference part, describing the operation and parameters of each SA function.
This manual assumes:
• A working knowledge of the C programming language.
Function call parameters are categorized as one of three types:
|
Format |
Used for |
|
in |
input parameter for function |
|
out |
return parameter from function |
|
use |
parameter object that is manipulated by the function |
In addition, there may be the following qualifiers for the input parameter:
|
Qualifier |
Used for |
|
hold |
the pointer is a pointer, the value of which will be stored by SA Interface and used later. Therefore, the object referred to by the pointer may not be prematurely freed. |
|
Take |
the parameter is a pointer to an object that ceases to exist as the result of the function call and cannot be used thereafter. |
SOLID Server documentation is distributed both as printed material and as Windows Help or HTML files. Solid Online Services on our Web server offer the latest product and technical information free of charge. The service is located at:
http://www.solidtech.com/
• SOLID Server Administrator's Guide describes the administrative procedures and gives information about SOLID SQL functionality.
• SOLID Server Programmer’s Guide and Reference contains basic information about using the SOLID SQL API directly, e.g., from C language, and how to exploit the advanced features of SOLID Server. It also provides the SOLID SQL API function reference.
• Read Me contains installation instructions and additional information about the specific product version. This readme.txt file is typically on the first SOLID Server diskette.
• Release Notes contains additional information about the specific product version. This relnotes.txt file is typically on the SOLID Server diskettes and will be copied onto your system when you install the software.
• SOLID Remote ControlTM Help tells you how to use the SOLID Remote Control administration program to perform the easy steps to manage your SOLID Servers.
• SOLID SQL EditorTM Help tells you how to use the SOLID SQL Editor, a tool for executing SQL queries and commands.
• SOLID Server Administrator's Guide is available electronically in either Windows Help or HTML format.
• SOLID Server Programmer’s Guide and Reference is available electronically in either Windows Help and HTML format.
There is an example program, called saexampl.c, in the SA Interface package. It shows typical function call patterns.
SaRetT SA_EXPORT_C SaArrayFlush(SaConnectT* scon, SaRetT* rctab)
Flushes array operation buffer. This function does the actual array operations by sending them to the server.
scon use
Connection pointer.
rctab use
Array of return codes for each array operation. If this parameter is non-NULL, return code of each array operation is returned in rctab[i], where i is the order number of array operation since last SaArrayFlush.
SA_RC_SUCC or error code of first failed array operation.
SaRetT SA_EXPORT_C SaArrayInsert(SaCursorT* scur)
Function to insert an array of values on one network message. This function places the inserted value to the array insert buffer. The buffer can flushed using function SaArrayFlush.
scur use
Cursor pointer.
SA_RC_SUCC or error code
SaColSearchT* SA_EXPORT_C SaColSearchCreate(SaConnectT* scon, char* tablename)
Starts a column info search for a specified table.
scon in
Pointer to connection object.
tablename in
Table name.
Pointer to the column search object, or NULL if table does not exist.
void SA_EXPORT_C SaColSearchFree(SaColSearchT* colsearch)
Releases a column search object.
colsearch in, take
Column search pointer.
int SA_EXPORT_C SaColSearchNext(SaColSearchT* colsearch, char** p_colname,SaDataTypeT* p_coltype)
Returns information of the next column in the table.
colsearch in, take
Column search pointer.
p_colname out, ref
Pointer to the local copy of the column name is stored into *p_colname.
p_coltype out
Type of column is stored into *p_coltype.
TRUE Next column found, parameters updated.
FALSE No more columns, parameters not updated.
SaConnectT* SA_EXPORT_C SaConnect(char* servername, char* username, char* password)
Creates connection to the SOLID Server. Empty servername connects to the default server. Several connections can be active at the same time, but operations in different connections are executed in separate transactions.
servername in
Server name.
username in
User name.
password in
Password.
Connect pointer or NULL, if connection failed.
SaRetT SA_EXPORT_C SaCursorAscending(SaCursorT* scur, char* colname)
Specifies ascending ordering criterium for a column. If a proper key does not exist, the rows are sorted locally. If several criteria are given, they are solved in the given order.
scur use
Cursor pointer.
colname in
Column name.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorAtleast(SaCursorT* scur, char* colname)
Species atleast criterium for a column. Atleast criterium means that the column value must be greater that or equal to the atleast value.
The atleast value is taken from the user variable bind to the column.
scur use
Cursor pointer.
colname in
Column name.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorAtmost(SaCursorT* scur, char* colname)
Species atmost criterium for a column. Atmost criterium means that the column value must be less that or equal to the atleast value.
The atleast value is taken from the user variable bind to the column.
scur use
Cursor pointer.
colname in
Column name.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorBegin(SaCursorT* scur)
Positions the cursor to the beginning of the set. Following next call returns the first row.
scur use
Cursor pointer
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorColData(SaCursorT* scur, char* colname,char** dataptr, unsigned* lenptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
In search operations the value stored to the user variable is a pointer to a local copy of the column data. The data pointer is valid until the next SaCursorOpen or SaCursorFree call, after which the pointer should not be referenced.
scur use
Cursor pointer.
colname in
Column name.
dataptr in, hold
Pointer to the user variable.
lenptr in, hold
Pointer to variable used to hold length of data.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColDate(SaCursorT* scur, char* colname, SaDateT* dateptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
dateptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColDateFormat(SaCursorT* scur, char* colname, char* dtformat)
Binds date format string to a database column. Depending on the column data type, the format string should be data, time or timestamp format.
scur use
Cursor pointer.
colname in
Column name.
dtformat in
Date/time/timestamp format string.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColDfloat(SaCursorT* scur, char* colname, SaDfloatT* dfloatptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
dfloatptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColDouble(SaCursorT* scur, char* colname, double* doubleptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
doubleptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColDynData(SaCursorT* scur, char* colname, SaDynDataT* dd)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
In search operations the column data is stored to the SaDynDataT variable using function SaDynDataMove, which overwrites the old data. The user is responsible for releasing the SaDynDataT variable after the search ends using function SaDynDataFree.
scur use
Cursor pointer.
colname in
Column name.
dd in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColDynStr(SaCursorT* scur, char* colname, SaDynStrT* ds)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
In search operations the column data is stored to the SaDynStrT variable using function SaDynStrMove, which overwrites the old data. The user is responsible for releasing the SaDynStrT variable after the search ends using function SaDynStrFree.
scur use
Cursor pointer.
colname in
Column name.
ds in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColFixstr(SaCursorT* scur, char* colname, char* fixstr, unsigned size)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
A fixstr is a data type which always has a fixed length. If the given data area for fixstr is longer than column data, the end is padded with spaces. If the data area is shorter than column data, the column data is truncated. In insert and update trailing space characters are not stored to the database.
scur use
Cursor pointer.
colname in
Column name.
fixstr in, hold
Pointer to the user variable.
len in
Length of data area pointer by fixstr.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColFloat(SaCursorT* scur, char* colname, float* floatptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
floatptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColInt(SaCursorT* scur, char* colname, int* intptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
intptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColLong(SaCursorT* scur, char* colname, long* longptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
longptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColNullFlag(SaCursorT* scur, char* colname, int* p_isnullflag)
Binds a NULL value flag to a column. If the column value is NULL, *p_isnullflag has a value 1, otherwise the value is 0. The *p_isnullflag value is updated automatically during fetch operations. During insert and update, a NULL value is inserted to the database if *p_isnullflag is not zero.
scur use
Cursor pointer.
colname in
Column name.
p_isnullflag in, hold
Pointer to an integer variable into where the NULL status is stored during fetch operations, and from where the NULL status is taken during insert and update operations.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColStr(SaCursorT* scur, char* colname, char** strptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
In search operations the value stored to the user variable is a pointer to a local copy of the column data. The data pointer is valid until the next SaCursorOpen or SaCursorFree call, after which the pointer should not be referenced.
scur use
Cursor pointer.
colname in
Column name.
strptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColTime(SaCursorT* scur, char* colname, SaDateT* timeptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
timeptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaRetT SA_EXPORT_C SaCursorColTimestamp(SaCursorT* scur, char* colname, SaDateT* timestampptr)
Binds user variable to a database column. In search operations the user variable is updated to contain the value of the current row. In insert and update operations the new value for the column is taken from the user variable.
scur use
Cursor pointer.
colname in
Column name.
timestampptr in, hold
Pointer to the user variable.
SA_RC_SUCC or error code.
SaCursorT* SA_EXPORT_C SaCursorCreate(SaConnectT* scon, char* tablename)
Creates a cursor to a table specified by relname. Operation fails if table does not exist.
scon use
Connect pointer.
tablename in
Table name.
Pointer to the cursor object, or NULL if table does not exists.
SaRetT SA_EXPORT_C SaCursorDelete(SaCursorT* scur)
Deletes the current row in a cursor from the database. The cursor must be positioned to a row.
scur use
Cursor pointer.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorDescending(SaCursorT* scur, char* colname)
Specifies descending ordering criterium for a column. If a proper key does not exist, the rows are sorted locally. If several criteria are given, they are solved in the given order.
scur use
Cursor pointer.
colname in
Column name.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorEnd(SaCursorT* scur)
Positions the cursor to the end of the set. Following prev call returns the last row.
scur use
Cursor pointer
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorEqual(SaCursorT* scur, char* colname)
Specifies an equal criterium for a column.
The equal value is taken from the user variable bind to the column.
scur use
Cursor pointer.
colname in
Column name.
SA_RC_SUCC or error code
bool SA_EXPORT_C SaCursorErrorInfo(SaCursorT* scur, char** errstr, int* errcode)
Returns error info from the last operation in cursor.
scur use
Cursor pointer.
errstr out, ref
If non-NULL, pointer to a local copy of an error string is stored into *errstr.
errcode out
If non-NULL, error code is stored into *errcode.
TRUE There was and error, errstr and errcode updated.
FALSE No errors, errstr and errcode not updated.
void SA_EXPORT_C SaCursorFree(SaCursorT* scur)
Releases a cursor. After this call the cursor pointer is invalid.
scur in, take
Cursor pointer.
SaRetT SA_EXPORT_C SaCursorInsert(SaCursorT* scur)
Inserts a new row to the database. Column values for the new row are taken from the user variables bind to columns. The cursor must be opened before new rows can be inserted.
scur use
Cursor pointer.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorLike(SaCursorT* scur, char* colname, int likelen)
Specifies a like criterium for a column. The value cannot contain any wild card characters like '_' or '%' in SQL. If such characters exist in the column value, they are quoted with escape characters by the system. Thus, the like value is effective the same as the SQL like with no wild card characters ending with a '%' character.
The like value is taken from the user variable bind to the column.
scur use
Cursor pointer.
colname in
Column name.
likelen in
Length of like part.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorNext(SaCursorT* scur)
Fetches next row from the database. All user variables bind to columns are updated.
scur use
Cursor pointer.
SA_RC_SUCC Next row found
SA_RC_END End of search
SaRetT SA_EXPORT_C SaCursorOpen(SaCursorT* scur)
Opens a cursor. All SaCursorColXXX operations must be done before the cursor is opened. When cursor is opened, possible existing search is terminated. Also all criteria specified for the cursor are cleared.
After the cursor is opened, user can insert new rows to the cursor or specify search criteria. Cursor must be opened before a search can be started.
scur use
Cursor pointer.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorOrderby(SaCursorT* scur, char* colname)
Sets an ordering criterium for a column. There must a proper key for the ordering. Several ordering criteria can be set, they are solved in the given order. There is no initial value for the ordering column.
scur use
Cursor pointer.
colname in
Column name.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorPrev(SaCursorT* scur)
Fetches previous row from the database. All user variables bind to columns are updated.
scur use
Cursor pointer.
SA_RC_SUCC Previous row found
SA_RC_END Beginning of search
SaRetT SA_EXPORT_C SaCursorReSearch(SaCursorT* scur)
Starts a new search using old search criteria.
scur use
Cursor pointer.
SA_RC_SUCC, SA_RC_END or error code
SaRetT SA_EXPORT_C SaCursorSearch(SaCursorT* scur)
Starts a search in a cursor. After the search is started, the user can fetch rows from the database.
Every search is executed as a separate transaction and it does not see any changes made by the current user or any other user after the search is started.
scur use
Cursor pointer.
SA_RC_SUCC SA_RC_END or error code
SaRetT SA_EXPORT_C SaCursorSearchByRowid(SaCursorT* scur, void* rowid, int rowidlen)
Starts a new search where row specified by rowid belongs to the search set. Previous search constraints are not removed, and they become effective in the next SaCursorReSearch call.
scur use
Cursor pointer.
rowid in
Pointer to a data area containing rowid.
rowidlen in
Length of data pointed by rowid.
SA_RC_SUCC SA_RC_END or error code
SaRetT SA_EXPORT_C SaCursorSetLockMode(SaCursorT* scur, sa_lockmode_t lockmode)
Sets the cursor search mode. This setting affects the possible locking modes in the server. If a search is already active, the setting will affect only in the next search done in the same cursor. By default the search mode is SA_LOCK_SHARE.
scur use
Cursor pointer.
mode in
Search mode, one of SA_LOCK_SHARE, SA_LOCK_FORUPDATE or SA_LOCK_EXCLUSIVE.
SA_RC_SUCC
SA_ERR_ILLENUMVAL
SaRetT SA_EXPORT_C SaCursorSetPosition(SaCursorT* scur)
Positions the cursor to a row specified by a key value. The key value is taken from user bound column variables which has a constraint specification.
scur use
Cursor pointer.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaCursorSetRowsPerMessage(SaCursorT* scur, int rows_per_message)
Sets the number of rows to be sent in one network message from the server to the client. Note that the setting has no effect after the search has been started by function SaCursorSearch.
scur use
Cursor pointer.
rows_per_message in
Number of rows to send in one network message.
SA_RC_SUCC Success
SA_ERR_FAILED Error, rows_per_message < 1
SaRetT SA_EXPORT_C SaCursorUpdate(SaCursorT* scur)
Updated the current row in a cursor in the database. The cursor must be positioned to a row. Column values for the new row are taken from the user variables bound to columns.
scur use
Cursor pointer.
SA_RC_SUCC or error code
SaDateT* SA_EXPORT_C SaDateCreate(void)
Creates a new data object. The date stored in the data object is undefined.
give
A new date object.
void SA_EXPORT_C SaDateFree(SaDateT* date)
Releases a date object. After this call the date object is invalid and cannot be used.
date in, take
Date object.
SaRetT SA_EXPORT_C SaDateSetAsciiz(SaDateT* date, char* format, char* asciiz)
Sets ascii zero string date to a date object.
The following special characters are recognized in the format string:
YYYY - year including century
YY - year with default century 1900
MM - month
M - month
DD - day of month
D - day of month
HH - hours
H - hours
NN - minutes
N - minutes
SS - seconds
S - seconds
FFF - fractions of a second, 1/1000 seconds
All fields are optional. The fields are scanned from the format string, and when a match is found, the field is replaced with the proper value. All other characters in the format are treated literally.
Below are examples of the usage of date formats:
SaDateSetAsciiz(date, "YY-MM-DD", "94-09-13"); SaDateSetAsciiz(date, "MM/DD/YY HH.NN", "09/13/94 19.20");
The default date format is YYYY-MM-DD HH:NN:SS, where time fields are optional.
date use
Date object.
format in
Format of date in asciiz buffer, or NULL if default format is used.
asciiz in
Buffer containing the data in a ascii zero string format.
SA_RC_SUCC
SA_ERR_FAILED
SaRetT SA_EXPORT_C SaDateSetTimet(SaDateT* date, long timet)
Sets time_t date to a date object. The time_t date is the same value as returned by C-library function time().
date use
Date object.
timet in
New date value in time_t format.
SA_RC_SUCC
SA_ERR_FAILED
SaRetT SA_EXPORT_C SaDateToAsciiz(SaDateT* date, char* format, char* asciiz)
Stores the date in an ascii zero string format. For explanation of different formats, see function SaDateSetAsciiz.
date in
Date object.
format in
Format of date that is stored into buffer asciiz, or NULL if default format is used.
asciiz out
Buffer where date is stored.
SA_RC_SUCC
SA_ERR_FAILED
SaRetT SA_EXPORT_C SaDateToTimet(SaDateT* date, long* p_timet)
Stores the date in a time_t format. The time_t date is the same value as returned by C-library function time().
date in
Date object.
p_timet out
Pointer to a long variable into where the date is stored in time_t format.
SA_RC_SUCC
SA_ERR_FAILED
SaRetT SA_EXPORT_C SaDefineChSet(SaConnectT* scon, SaChSetT chset)
Defines client character set.
scon in out, use
pointer to connection object
chset in
enumerated charset specification. One of the following:
SA_CHSET_DEFAULT - Default character set,
SA_CHSET_NOCNV - No conversion,
SA_CHSET_ANSI - ISO Latin 1, e.g. MS Windows,
SA_CHSET_PCOEM - IBM PC, e.g. MS-DOS,
SA_CHSET_7BITSCAND - e.g. Unix
SA_RC_SUCC when OK or
SA_ERR_CHSETUNSUPP when specified character set is not supported
int SA_EXPORT_C SaDfloatCmp(SaDfloatT* p_dfl1, SaDfloatT* p_dfl2)
Compares two dfloat values.
p_dfl1 in
Pointer to dfloat variable.
p_dfl2 in
Pointer to dfloat variable.
< 0 - dfl1 < dfl2
= 0 - dfl1 = dfl2
> 0 - dfl1 > dfl2
SaRetT SA_EXPORT_C SaDfloatDiff(SaDfloatT* p_result_dfl, SaDfloatT* p_dfl1, SaDfloatT* p_dfl2)
Calculates the difference of two dfloat values. The result is stored into *p_result_dfl.
p_result_dfl out
Pointer to dfloat variable where the result is stored.
p_dfl1 in
Pointer to dfloat variable.
p_dfl2 in
Pointer to dfloat variable.
int SA_EXPORT_C SaDfloatOverflow(SaDfloatT* p_dfl)
Checks if the dfloat contains as overflow value.
p_dfl in
Pointer to dfloat variable.
1 dfloat value is an overflow value
0 not an overflow value
SaRetT SA_EXPORT_C SaDfloatProd(SaDfloatT* p_result_dfl, SaDfloatT* p_dfl1, SaDfloatT* p_dfl2)
Calculates the producr of two dfloat values. The result is stored into *p_result_dfl.
p_result_dfl out
Pointer to dfloat variable where the result is stored.
p_dfl1 in
Pointer to dfloat variable.
p_dfl2 in
Pointer to dfloat variable.
SaRetT SA_EXPORT_C SaDfloatQuot(SaDfloatT* p_result_dfl, SaDfloatT* p_dfl1, SaDfloatT* p_dfl2)
Calculates the quotient of two dfloat values. The result is stored into *p_result_dfl.
p_result_dfl out
Pointer to dfloat variable where the result is stored.
p_dfl1 in
Pointer to dfloat variable.
p_dfl2 in
Pointer to dfloat variable.
SaRetT SA_EXPORT_C SaDfloatSetAsciiz(SaDfloatT* p_dfl, char* asciiz)
Sets the value of the dfloat from as ascii zero string.
p_dfl out
Pointer to the dfloat variable.
asciiz in
Buffer where the dfloat value is read as an asciiz zero srting.
SA_RC_SUCC
SA_ERR_FAILED
SaRetT SA_EXPORT_C SaDfloatSum(SaDfloatT* p_result_dfl, SaDfloatT* p_dfl1, SaDfloatT* p_dfl2)
Calculates the sum of two dfloat values. The result is stored into *p_result_dfl.
p_result_dfl out
Pointer to dfloat variable where the result is stored.
p_dfl1 in
Pointer to dfloat variable.
p_dfl2 in
Pointer to dfloat variable.
SaRetT SA_EXPORT_C SaDfloatToAsciiz(SaDfloatT* p_dfl, char* asciiz)
Stores the dfloat value as an ascii zero string.
p_dfl1 in
Pointer to dfloat variable.
asciiz out
Buffer where the dfloat is stored in asciiz zero string format.
SA_RC_SUCC
SA_ERR_FAILED
int SA_EXPORT_C SaDfloatUnderflow(SaDfloatT* p_dfl)
Checks if the dfloat contains as underflow value.
p_dfl in
Pointer to dfloat variable.
1 dfloat value is an underflow value
0 not an underflow value
void SA_EXPORT_C SaDisconnect(SaConnectT* scon)
Disconnects user from the SOLID Server.
scon in, take
Connect pointer.
void SA_EXPORT_C SaDynDataAppend(SaDynDataT* dd, char* data, unsigned len)
Appends data to the dynamic data object.
dd use
Pointer to a dynamic data object.
data in
Data that is appended to the dd.
len in
Length of data.
void SA_EXPORT_C SaDynDataChLen(SaDynDataT* dd, unsigned len)
Changes the data area length of dynamic data object. If new length is smaller than current length, the data area is truncated. If new length is greater than current length, the new data area content is initialized with space characters.
dd use
Pointer to a dynamic data object.
len in
New data area length of dynamic data object.
void SA_EXPORT_C SaDynDataClear(SaDynDataT* dd)
Clears all allocations from a DynData object.
dd use
Pointer to a dynamic data object.
SaDynDataT* SA_EXPORT_C SaDynDataCreate(void)
Creates a new dynamic data object.
Pointer to a new empty dynamic data object.
void SA_EXPORT_C SaDynDataFree(SaDynDataT* dd)
Realeases a dynamic data object. Aftre this call the dynamic data object pointer is invalid and cannot be used.
dd in, take
Pointer to a dynamic data object that is released.
char* SA_EXPORT_C SaDynDataGetData(SaDynDataT* dd)
Returns pointer to the data area of dynamic data object.
dd in
Pointer to a dynamic data object.
Reference to the local data area of dynamic data object.
unsigned SA_EXPORT_C SaDynDataGetLen(SaDynDataT* dd)
Returns the length of the data area of dynamic data object.
dd in
Pointer to a dynamic data object.
Data area length.
void SA_EXPORT_C SaDynDataMove(SaDynDataT* dd, char* data, unsigned len)
Moves data to the dynamic data object. This function overrides possible existing data.
dd use
Pointer to a dynamic data object.
data in
New data.
len in
Length of data.
void SA_EXPORT_C SaDynDataMoveRef(SaDynDataT* dd, char* data, unsigned len)
Moves data reference to a dynamic data object. The caller should guarantee that input data is alive as long as the reference in the dynamic data object.
dd use
Pointer to a dynamic data object.
data in, hold
Pointer to the new data content of the dynamic data object.
len in
The length of the new data content.
void SA_EXPORT_C SaDynStrAppend(SaDynStrT* p_ds, char* str)
Appends another string at the end of dynamic string.
p_ds use
Pointer to dynamic string variable.
str in
String that is appended to p_ds.
SaDynStrT SA_EXPORT_C SaDynStrCreate(void)
Creates and initializes a new dynamic string object.
Pointer to dynamic string variable, initialized with empty data.
void SA_EXPORT_C SaDynStrFree(SaDynStrT* p_ds)
Realeases a dynamic string object. After this call the dynamic string object pointer is invalid and cannot be used.
p_ds in, take
Pointer to dynamic string variable.
void SA_EXPORT_C SaDynStrMove(SaDynStrT* p_ds, char* str)
This routine sets the value of a SaDynStrT. The SaDynStrT must have been initialized with SaDynStrCreate before setting it with SaDynStrMove.
ATTENTION! Do never copy a SaDynStrT to another SaDynStrT for example with memcpy. This would result into two SaDynStrT pointers pointing at the same allocated area.
p_ds use
Pointer to dynamic string variable.
str in
New value of dynamic string.
bool SA_EXPORT_C SaErrorInfo(SaConnectT* scon, char** errstr, int* errcode)
Returns error info from the last operation in server connection. Cursor errors cannot be checked with this function, instead function SaCursorErrorInfo must be used.
scon use
Connect pointer.
errstr out, ref
If non-NULL, pointer to a local copy of an error string is stored into *errstr.
errcode out
If non-NULL, error code is stored into *errcode.
TRUE There was and error, errstr and errcode updated.
FALSE No errors, errstr and errcode not updated.
void SA_EXPORT_C SaGlobalInit(void)
Does some global initializations in the SA system. This function should be called when other SA functions are called before SaConnect function.
SaRetT SA_EXPORT_C SaSetDateFormat(SaConnectT* scon, char* dateformat)
Defines default date format. For explanation of possible date formats see documentation of function SaDateSetAsciiz.
scon in out, use
pointer to connection object
dateformat in
Default date format for connection.
SA_RC_SUCC
SaRetT SA_EXPORT_C SaSetSortBufSize(SaConnectT* scon, unsigned long size)
Sets amount of memory that a connection uses for local sorts.
scon in out, use
pointer to connection object
size in
memory buffer size in bytes
SA_RC_SUCC when OK or
SA_ERR_FAILED when specified memory size was too small (< 10KB)
SaRetT SA_EXPORT_C SaSetSortMaxFiles(SaConnectT* scon, unsigned int nfiles)
Sets maximum number of files that the connection uses for local sorts
scon in out, use
pointer to connection object
nfiles in
max number of files
SA_RC_SUCC when OK or
SA_ERR_FAILED when specified number of files is was too small (< 3)
SaRetT SA_EXPORT_C SaSQLExecDirect(SaConnectT* scon, char* sqlstr)
Passes an SQL string to server for immediate execution. Does not allow returning any data. Typically this is used for passing administration statements, data definition language statements and statements affecting several rows at once, like "DELETE FROM mytable WHERE ...";
The passed statement is treated as one transaction that is committed immediately after successfull execution.
scon in out, use
Pointer to connection object
sqlstr in
SQL statement to be executed
SA_RC_SUCC when OK or errorcode.
SaRetT SA_EXPORT_C SaSetTimeFormat(SaConnectT* scon, char* timeformat)
Defines default time format. For explanation of possible date formats see documentation of function SaDateSetAsciiz.
scon in out, use
Pointer to connection object
timeformat in
Default time format for connection
SA_RC_SUCC
SaRetT SA_EXPORT_C SaSetTimestampFormat(SaConnectT* scon, char* timestampformat)
Defines default timestamp format. For explanation of possible date formats see documentation of function SaDateSetAsciiz.
scon in out, use
pointer to connection object
timestampformat in
Default timestamp format for connection.
SA_RC_SUCC
void SA_EXPORT_C SaTransBegin(SaConnectT* scon)
Starts a new transaction. By default each insert, update and delete operations are executed in separate transactions. After this call all insert, update and delete operations are executed in the same transaction, and the changes are not visible in the database until SaTransCommit is called.
The transaction is run in a mode where write operations are validated for lost updates and unique errors.
scon use
Pointer to connection object.
SaRetT SA_EXPORT_C SaTransCommit(SaConnectT* scon)
Commits the current transaction started by SaTransBegin. After this call all changes are made persistent in the database. Following insert, update and delete operations are run in autocommit mode until SaTransBegin is called.
scon use
Pointer to connection object.
SA_RC_SUCC or error code
SaRetT SA_EXPORT_C SaTransRollback(SaConnectT* scon)
Rolls back the current transaction started by SaTransBegin. No changes are made to the database. Following insert, update and delete operations are run in autocommit mode until SaTransBegin is called.
scon use
Pointer to connection object.
SA_RC_SUCC or error code