|
|
Content | User documentation | Administrator documentation | Index of terms | Technical Support | Search on-line |
| fxODBC library |
This document tries to be instrumental to help FaxChange developers use it's database support. It shows how to deal with various data and structures operations, use them in applications, how to change the configuration settings or write own providers for specific data sources to manage FaxChange data in a very special way.
FaxChange as the communication system deals with a great amounts of data that should be processed rapidly. This makes a big reason to treat data managing carefully in a very optimal way.
The database support is based on Microsoft ADO technology offering easy to implement, relatively efficient and uniform access to various database engines. The differences in data-managing are bypassed thru so-called ADO providers - the most common ADO provider MSDASQL uses ODBC API services to ensure the data access to all engines providing ODBC support and it comes with standard ADO installation pack. However database companies are often developing their own ADO providers to get the maximum perfomance out of their products.
This ADO level data access is embraced in the main FaxChange API library named FxODBC40.dll. Library interface exports many services as is described later in section 'Data Manipulation'.
Another important piece of FaxChange database support is database-engine-dependent library called provider. This library takes a part in an environment initialization - it is responsible for physical and logical dbases and tables creating and for their proper structure and design configuration. And finally provider has another considerable feature - it enables to overload the standard FxODBC40.dll services with its own code allowing wide variety of provider's application. For more detailed information take a look at the section 'Providers'.
Any application initializes FaxChange Database API by calling fxInit or fxInitEx with the application identifier and the list of tables that gonna be used (and the server name running FaxChange respectively). This causes every table to be initialized, which means following: first the provider library is loaded and found out what services it exports, second InitProvider call is executed (if provider supports one) with table's name as argument, then the ADO provider is set to one selected (or MSDASQL as default) and finally connection to table is opened.
If no problem emerged while initializing then the client's application is allowed to use whatever services it needs on tables it asked for to be attached. If an error occures during any call, the function returns corresponding error code and more detailed description (if available) is sent to event log.
If the application is going to exit or the database supporting API is no longer need, fxClose should be called to close the connections opened, to CloseProvider be executed if provider supports one and to overhead data be freed.
The FaxChange data are organized into the following tables: tCsid, tFax, tFile, tPabx, tState and tUser. There's a special structure bound with every table representing the data the table holds except table tFile that keeps the data extracted out of fxFax structure for the sake of efficiency - each file is stored just once and read only when user asks for.
Table design:
Column Type fCsid char(32) primary key fFrom char(80) fUserid long primary key fNumber char(30) fCreated long fLastuse long
Base structure:
struct fxCsid
{
TCHAR csid[CSID_LENGTH];
TCHAR from[80];
long userid;
TCHAR number[30];
long created;
long lastused;
};
Mapping from fxCsid structure members to table columns is straightforward.
Table design:
Column Type fType char fStatus char fCoverid long fDataid long fOrigid long fPriorit char fId long primary key fLine short fSpeed short fTime long fOnline long fSubject char(128) fSpecial char(32) fName char(128) fGate char fEmail char(128) fGroup char(24) fCostcod char(24) fTofrom char(80) fToname char(80) fCompany char(80) fDept char(80) fNumbers char(100) fNumber char(30) fAttempt short fCost float fCsid char(32) fFromcsi char(32) fTopabx char(32) fFreetex varchar
Base structure:
struct fxFax
{
TCHAR type;
TCHAR status;
TCHAR cover[FILENAME_LENGTH];
int cover_id;
TCHAR data[FILENAME_LENGTH];
int data_id;
TCHAR original[FILENAME_LENGTH];
int orig_id;
TCHAR priorita;
long id;
int line;
int speed;
long time;
long online;
TCHAR subject[128];
TCHAR special_id[32];
TCHAR *freetext;
union x
{
struct snt
{
TCHAR from_name[USERNAME_LENGTH];
TCHAR from_gateway;
TCHAR from_email[EMAIL_LENGTH];
TCHAR from_group[GROUP_LENGTH];
TCHAR from_costcode[COSTCODE_LENGTH];
TCHAR to_to[80];
TCHAR to_name[80];
TCHAR to_company[80];
TCHAR to_dept[80];
TCHAR to_numbers[100];
TCHAR number[30];
int attempts;
float cost;
TCHAR csid[CSID_LENGTH];
};
struct rcvd
{
TCHAR to_name[USERNAME_LENGTH];
TCHAR to_gateway;
TCHAR to_email[EMAIL_LENGTH];
TCHAR from[80];
TCHAR from_csid[CSID_LENGTH];
TCHAR to_pabx[PABX_LENGTH];
};
};
};
All the members are mapped straight except the following:
freetext member allocated thru query services should always be freed using fxFree call.
Table design:
Column Type fId long primary key fName char(254) fCounter long fData varbinary
Base structure:
See fxFax structure.
Mapping from fxFax structure members to table columns:
Table design:
Column Type fPabx char(32) primary key fUserid long primary key
Base structure:
struct fxPabx
{
TCHAR pabx[PABX_LENGTH];
long userid;
};
Mapping from fxPabx structure members to table columns is straightforward.
Table design:
Column Type fType char primary key fName char(20) fPrefix char(10) primary key fLngcode char(16) fCost0 float fCost1 float fCost2 float fCost3 float fCost4 float fAds char(40)
Base structure:
struct fxState
{
TCHAR type;
TCHAR name[20];
TCHAR prefix[10];
TCHAR lngcode[16];
float cost[5];
TCHAR ads[40];
};
Mapping from fxState structure members to table columns is straightforward.
Table design:
Column Type fName char(128) index fGate char fEmail char(128) index fId long primary key fGroup char(24) fCostcod char(24) fFlags char(8) fControl short fCover char(32) fLng char(16) fFreetex varchar
Base structure:
struct fxUser
{
TCHAR name[USERNAME_LENGTH];
TCHAR gate;
TCHAR email[EMAIL_LENGTH];
long id;
TCHAR group[GROUP_LENGTH];
TCHAR costcode[COSTCODE_LENGTH];
TCHAR international;
TCHAR intercity;
TCHAR out;
TCHAR in;
TCHAR low;
TCHAR normal;
TCHAR high;
TCHAR scheduled;
int control;
TCHAR cover[32];
TCHAR lng[16];
TCHAR *freetext;
};
Mapping from fxUser structure members to table columns is transparent; members international, intercity, out, in, low, normal, high and scheduled are mapped into fFlags array items in this order. freetext member allocated thru query services should always be freed using fxFree call.
Remark: The 't' sign at the beginning of each table's name occures because of prevention of conflicting situation when e.g. creating a recordset based upon the SELECT query: FROM clause could be not parsed well due to considering table name as to be a keyword - this happens with most of the database engines on User or File table names. And this also is the reason why all the column names begin with 'f' character.
All the data are manipulated thru calls appropriate to tables, what is symbolized in each of the functions' name. There is one exception: when working with fxFax structure there are two tables touched - tFax and tFile, and corresponding functions hold Archive word in their prototypes. The '#' sign is a placeholder for this words representing tables the operation applies on - the possibilities are Archive, Csid, Pabx, State and User. Follow the 'Applicable' notice on each of the sections.
The operations on data could be divided into the following sections:
Out = fx#AddOpen(); { ... Out = fx#Add(&fx#Struct); ... } Out = fx#AddClose();
Important: It is eligible to process returning codes in some way. Always call fx#AddClose() to prevent from an eventual data-loss - even if an error occures.
Applicable: Archive, Csid, Pabx, State, User
The '#' sign is a placeholder for the table name which the operation applies on - the possibilities are Archive, Csid, Pabx, State and User. The fx#StructOld serves as a row identifier source, so there is no reason why to specify all the members except those holding primary key. If no accordant row is found then new row is appended.
Out = fx#ModifyOpen(); { ... Out = fx#Modify(&fx#StructOld, &fx#StructNew); ... } Out = fx#ModifyClose();
When using Archive: take care about file managing. It is a little bit curious. If you enter any file id in a fxFaxOld structure, then these files are deleted! Vice versa if you specify a file name in fxFaxNew structure then these files are added. So watch these members carefully to ensure proper file managing.
Note: Currently there is no way how to change certain structure members (table columns resp.) only.
Important: It is eligible to process returning codes in some way. Always call fx#ModifyClose() to prevent from an eventual data-loss - even if an error occures.
Applicable: Archive, Csid, Pabx, State, User
The '#' sign is a placeholder for the table name which the operation applies on - the possibilities are Archive, Csid, Pabx, State and User. There's not unique parameter passing - primary key or structure, this is table dependent. See the corresponding prototypes for actual information.
Out = fx#EraseOpen(); { ... Out = fx#Erase(?); ... } Out = fx#EraseClose();
When using Archive: if file ids specified, then corresponding files are deleted. Attention - if you not enter this members it is possible to have no-more-used files archived!
Important: It is eligible to process returning codes in some way. Always call fx#EraseClose() to prevent from an eventual data-loss - even if an error occures.
Applicable: Archive, Csid, Pabx, State, User
Use fx#GetRows calls to exploitage new version 4.0 approach. When opening for getting rows, supply SortColumns as a string containing comma separated column names to be sorted by GROUP BY clause and Filter as a string limiting the selection by WHERE clause. If you wish to get only certain columns do pass integers' array with column ids in ColumnIds and their number in Count parameters (default is to get all the columns except Freetext if present to lower the time consumption).
When getting rows you can explicitly determine where to start and how many rows read. Provide an initialized structure array pointer large enough to keep all the records you wish to obtain.
Here comes simple example code getting SIZE of rows starting at 100:
long Count = SIZE; fx# Buffer[SIZE]; Out = fx#GetRowsOpenDefault(NULL, NULL); { ... Out = fx#GetRows(100, &Count, Buffer); ... } Out = fx#GetRowsClose();
And now more sophisticated example getting SIZE of Freetext members from rows sorted by fSortColumn where id is lower than 1000 started at 100. Notice that finally Count holds the actual records count got into the buffer.
long Count = SIZE; fx# Buffer[SIZE]; int ColumnIds[] = {#Freetext}; Out = fx#GetRowsOpen("fSortColumn1 ASC, fSortColumn2", "(fId < 1000) AND (fId > 100)", ColumnIds, 1); { ... Out = fx#GetRows(100, &Count, Buffer); ... } Out = fx#GetRowsClose();
Applicable: Archive, Csid, Pabx, State, User
Another approach based on previous FaxChange Database API version allows fast table run-through. The prototype form is fx#QueryAll to get all the rows or fx#QueryColumn to get rows where Column has a explicit value. See the API index for possible services. Notice that this is not the case when Column specifies a primary key.
General form example for fx#QueryAll:
Here fx#Kill service is used to deallocate the buffer. This is the most recommanded way because it takes care about the specially allocated members freeing.
fx# *Buffer; Out = fx#QueryAll(Buffer); while(Buffer != NULL) { ... Out = fx#Kill(Buffer); ... Out = fx#QueryAll(Buffer); ... }
Another example for fx#QueryColumn is almost the same:
Here only rows where Column holds the "Column Value" are selected. Remark that the secondly used "Column Value" has no meaning at all since the recordset is already opened.
fx# *Buffer; Out = fx#QueryColumn(Buffer, "Column Value"); while(Buffer != NULL) { ... Out = fx#Kill(Buffer); ... Out = fx#QueryColumn(Buffer, "Column Value"); ... }
Important: Always call the fx#Query services until they return NULL as Buffer! This is very necessary because of correct recordset closing.
Applicable: Archive, Csid, Pabx, State, User
The last approach is similar to the preceding one, except the rowset opened by such a query has only one record. This is the case when Column presents a primary key. Here comes an example getting a row with an id equal to 24:
fx# *Buffer; Out = fx#QueryId(Buffer, 24); if(Buffer != NULL) { ... Out = fx#Kill(Buffer); }
Applicable: Archive, State, User
fx#Kill is used to safely free fx# structure pointers allocated by query services. For an example see above.
Applicable: Archive, Csid, Pabx, State, User
fx#Count makes possible read the actual recordset's number of rows. There are two options how it can be used. The first one gets the count directly without opening a recordset - it returns the according table's row count:
The second one gets number of rows on open recordset, as in this example - all available rows are read:
long Count = MAX_SIZE; fx# Buffer[MAX_SIZE]; int ColumnIds[] = {#Freetext}; Out = fx#GetRowsOpen("fSortColumn", "fId < 1000", ColumnIds, 1); { ... Out = fx#Count(&Count); ... Out = fx#GetRows(100, &Count, Buffer); ... } Out = fx#GetRowsClose();
Applicable: Archive, Csid, Pabx, State, User
fx#GetFreeText fills the freetext member of passed structure with a value of fFreetex column as is in table. This service is provided because Freetext could amount large size of memory and slow down the rows getting. The application should get it in this particular way only when it needs it.
Applicable: Archive, User
fx#SetFreeText sets the freetext member of passed structure with a value provided as the parameter. It also synchronize the appropriate table by updating fFreetex member on the right row.
Applicable: Archive, User
Warning: The above described behaviour is valid only if using genuine FaxChange Database API support. No warranty comes when using third-party providers overloading any of exports.
To enhance possibilities of data manipulation FaxChange DBase support introduces libraries called providers. Their role in the system is to mediate various database-engines intialization and close-up in a standard manner. Another ability making them a powerful tool is to overload origin FaxChange DBase API with a new code allowing to handle the data however is needed.
The initialization is processed through the following prototype:
The ServerName points out computer, where should the registry configuration data be retrieved from. The AppCode parameter transmits the name of the application, that is opening FaxChange DBase support. The Table holds the name of the table to be initialized (possible values are tCsid, tFax, tFile, tPabx, tState and tUser).
The call shoud return FX_OK if provider overrides all the API services on Table that the application is going to use. If it is FX_CALL_DEFAULT returned, the standard FaxChange DBase engine is assumed to be used and therefore ADO is initialized. Any other returning code makes initialization failed and is passed on to the application.
The close-up service has the following prototype:
Actually it does not matter what this call returns. It's just established to allow the provider make all necessary steps to exit.
For function prototypes to be overloaded by provider look at the section following.
FXEXPORT fxInit(TCHAR *AppCode, TCHAR *Tables);
FXEXPORT fxInitEx(TCHAR *Server, TCHAR *AppCode, TCHAR *Tables);
- Server - specifies the computer where to take the registry configuration data. This could be NULL if should initialize locally - default when using fxInit.
- AppCode - defines name identifier of the application causing this function to be called. Standard API and current providers don't use this member. It could be worthwhile for special providers to differ connections and mark messages.
- Tables - list of semicolon-separated table names as present in Structures and Tables without any dividing white-spaces. This has to contain all the table names the application is going to use thru FaxChange DBase API calls.
Initializes FaxChange Database Support by loading provider library, calling its InitProvider method if available. It also prepares ADO objects when provider asks for. It must be the first FaxChange DBase API call.
Returns FX_OK if initialization succeeded, FX_OLE_DISPATCH_EXCEPTION or FX_UNKNOWN_EXCEPTION if an exception raised, FX_ERROR otherwise.
Note: If your application calls archive services, always specify both tFax and tFile tables since they are bound together thru fxFax structure members.
Example:
Out = fxInit(_T("My Application"), _T("tUser;tState;tFax;tFile"));
Out = fxInitEx(_T("GLUM"), _T("Test"), _T("tCsid;"));
FXEXPORT fxClose();
Finishes the work with FaxChange DBase API. Calls CloseProvider if present.
Returns always FX_OK.
Example:
FXEXPORT fxUserAddOpen();
Opens a recordset on tUser table and prepares for user data adding.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxUserAdd(fxUser *NewUser);
- NewUser - fxUser structure pointer referencing data to be stored.
Adds a new record to an open recordset filled with data from NewUser structure. If primary key constraint fails on current record, the data are not stored and FX_OLE_DISPATCH_EXCEPTION is returned - you can omit this and continue adding another data and modify those causing primary key duplicate later.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxUserAddClose();
Synchronizes the recordset's contents with tUser table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxUserModifyOpen();
Opens a recordset on tUser table and prepares for user data modifying.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxUserModify(fxUser *OldUser, fxUser *NewUser);
- OldUser - fxUser structure pointer referencing primary key data to define the row to be updated. This actually means that only id member is used.
- NewUser - fxUser structure pointer referencing data to be stored. Note that the values of all the structure members are updated.
Next to respective record retrieval modifies this with new values. If origin record not found, the new one is added.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxUserModifyClose();
Synchronizes the recordset's contents with tUser table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxUserEraseOpen();
Opens a recordset on tUser table and prepares for user data erasing.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxUserErase(long Id);
- Id - primary key value determining the row to be deleted.
Deletes the record with primary key value of Id.
Returns FX_OK if operation succeeded, FX_NOT_FOUND if no record with specified primary key value exists or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxUserEraseClose();
Synchronizes the recordset's contents with tUser table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxUserKill(fxUser *User);
Frees the User pointed structure, including the possibly allocated freetext member.
Returns FX_OK.
Example: See Data Querying above.
FXEXPORT fxUserQueryName(fxUser **Result, TCHAR *Name);
Searches the tUser table for user called Name. Result points to fxUser structure filled with data found or is NULL if no more data is available.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxUserQueryId(fxUser **Result, long Id);
Searches the tUser table for user with identifier Id. Result points to fxUser structure filled with data found or is NULL if data not found.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxUserQueryEmail(fxUser **Result, TCHAR *Email);
Searches the tUser table for user with e-mail Email. Result points to fxUser structure filled with data found or is NULL if no more data is available.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxUserQueryAll (fxUser **Result);
Goes through all the records in tUser table. Result points to fxUser structure filled with data found or is NULL if reached the end of the table.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxUserGetRowsOpen(TCHAR *SortColumns, TCHAR *Filter, int *ColumnIds = FieldsUserIds, long Count = UserCount - 1);
FXEXPORT fxUserGetRowsOpenDefault(TCHAR *SortColumns, TCHAR *Filter);
Opens a recordset on tUser table. You can affect the recordset form by passing following arguments:
- SortColumns enumerates fields to sort the recordset by. These are the column names separated by commas. This string is SQL clause ORDER BY argument, so feel free to use clauses like ASC or DESC in field specification.
- Filter defines an expression that should be fulfilled. It complies the SQL language specification as WHERE clause argument.
- ColumnIds is an array of columns' integer identifiers as specified in FxAPI.h. Default is FieldsUserIds.
- Count specifies ColumnIds array size. Default is UserCount - 1 (omit the fFreetex member).
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxUserGetRows(long Start, long *Count, fxUser *Result);
- Start - number of row where to start retrieving data.
- Count - specifies recordset's row count. Returns real recordset size.
- Result - pointer to array of structures to be filled with data.
Retrieves Count of the records starting with row number Start. All the data is stored into an array pointed by Result.
Returns FX_OK if alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxUserGetRowsClose();
Closes the current recordset.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxUserGetFreeText(fxUser *User);
- User - structure with info on user to get freetext to. Note that only id member is necessary.
Retrieves the freetext member of fxUser structure from database. Remember to free this structure using fxUserKill call!
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example:
FXEXPORT fxUserSetFreeText(fxUser *User, TCHAR *Freetext);
- User - structure with info on user to get freetext to. Note that only id member is necessary.
- Freetext - new freetext to be stored with this user.
Sets the freetext member of fxUser structure and updates the database. Remember to free this structure using fxUserKill call!
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example:
fxUser *User; Out = fxUserQueryId(&User, 10); Out = fxUserSetFreeText(User, _T("Here comes whatever text you wish to save with this user."));
FXEXPORT fxUserCount(long *Result);
- Result - buffer to store the record count.
Returns the current recordset record count.
Returns FX_OK if everything is alright, FX_OLE_DISPATCH_EXCEPTION if an exception raised or FX_ERROR if another problem encountered.
Example: See Data Querying above.
FXEXPORT fxPabxAddOpen();
Opens a recordset on tPabx table and prepares for user data adding.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxPabxAdd(fxPabx *NewPabx);
- NewPabx - fxPabx structure pointer referencing data to be stored.
Adds a new record to an open recordset filled with data from NewPabx structure. If primary key constraint fails on current record, the data are not stored and FX_OLE_DISPATCH_EXCEPTION is returned - you can omit this and continue adding another data and modify those causing primary key duplicate later.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxPabxAddClose();
Synchronizes the recordset's contents with tPabx table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxPabxModifyOpen();
Opens a recordset on tPabx table and prepares for user data modifying.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxPabxModify(fxPabx *OldPabx, fxPabx *NewPabx);
- OldPabx - fxPabx structure pointer referencing primary key data to define the row to be updated. This actually means that only userid member is used.
- NewPabx - fxPabx structure pointer referencing data to be stored. Note that the values of all the structure members are updated.
Next to respective record retrieval modifies this with new values. If origin record not found, the new one is added.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxPabxModifyClose();
Synchronizes the recordset's contents with tPabx table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxPabxEraseOpen();
Opens a recordset on tPabx table and prepares for data erasing.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxPabxErase(fxPabx *Pabx);
- Pabx - Points to fxPabx structure with data of the row to be deleted.
Deletes the Pabx specified record.
Returns FX_OK if operation succeeded, FX_NOT_FOUND if no record with specified primary key value exists or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxPabxEraseClose();
Synchronizes the recordset's contents with tPabx table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxPabxKill(fxPabx *Pabx);
Frees the Pabx pointed structure.
Returns FX_OK.
Example: See Data Querying above.
FXEXPORT fxPabxQueryAll(fxPabx **Result);
Goes through all the records in tPabx table. Result points to fxPabx structure filled with data found or is NULL if reached the end of the table.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxPabxQueryPabx(fxPabx **Result, TCHAR *Pabx);
Searches the tPabx table for record with pabx Pabx. Result points to fxPabx structure filled with data found or is NULL if no more data is available.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxPabxGetRowsOpen(TCHAR *SortColumns, TCHAR *Filter, int *ColumnIds, long Count);
FXEXPORT fxPabxGetRowsOpenDefault(TCHAR *SortColumns, TCHAR *Filter);
Opens a recordset on tPabx table. You can affect the recordset form by passing following arguments:
- SortColumns - enumerates fields to sort the recordset by. These are the column names separated by commas. This string is SQL clause ORDER BY argument, so feel free to use clauses like ASC or DESC in field specification.
- Filter - defines an expression that should be fulfilled. It complies the SQL language specification as WHERE clause argument.
- ColumnIds is an array of columns' integer identifiers as specified in FxAPI.h. Default is FieldsPabxIds.
- Count specifies ColumnIds array size. Default is PabxCount.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxPabxGetRows(long Start, long *Count, fxPabx *Result);
- Start - number of row where to start retrieving data.
- Count - specifies recordset's row count. Returns real recordset size.
- Result - pointer to array of structures to be filled with data.
Retrieves Count of the records starting with row number Start. All the data is stored into an array pointed by Result.
Returns FX_OK if alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxPabxGetRowsClose();
Closes the current recordset.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxPabxCount(long *Result);
- Result - buffer to store the record count.
Returns the current recordset record count.
Returns FX_OK if everything is alright, FX_OLE_DISPATCH_EXCEPTION if an exception raised or FX_ERROR if another problem encountered.
Example: See Data Querying above.
FXEXPORT fxCsidAddOpen();
Opens a recordset on tCsid table and prepares for user data adding.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxCsidAdd(fxCsid *NewCsid);
- NewCsid - fxCsid structure pointer referencing data to be stored.
Adds a new record to an open recordset filled with data from NewCsid structure. If primary key constraint fails on current record, the data are not stored and FX_OLE_DISPATCH_EXCEPTION is returned - you can omit this and continue adding another data and modify those causing primary key duplicate later.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxCsidAddClose();
Synchronizes the recordset's contents with tCsid table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxCsidModifyOpen();
Opens a recordset on tCsid table and prepares for user data modifying.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxCsidModify(fxCsid *OldCsid, fxCsid *NewCsid);
- OldCsid - fxCsid structure pointer referencing primary key data to define the row to be updated. This actually means that only userid member is used.
- NewCsid - fxCsid structure pointer referencing data to be stored. Note that the values of all the structure members are updated.
Next to respective record retrieval modifies this with new values. If origin record not found, the new one is added.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxCsidModifyClose();
Synchronizes the recordset's contents with tCsid table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxCsidEraseOpen();
Opens a recordset on tCsid table and prepares for data erasing.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxCsidErase(fxCsid *Csid);
- Csid - pointer to fxCsid structure determining the row to be deleted.
Deletes the record with primary key values of Csid.
Returns FX_OK if operation succeeded, FX_NOT_FOUND if no record with specified primary key value exists or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxCsidEraseClose();
Synchronizes the recordset's contents with tCsid table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxCsidKill(fxCsid *Csid);
Frees the Csid pointed structure.
Returns FX_OK.
Example: See Data Querying above.
FXEXPORT fxCsidQueryAll(fxCsid **Result);
Goes through all the records in tCsid table. Result points to fxCsid structure filled with data found or is NULL if reached the end of the table.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxCsidQueryCsid(fxCsid **Result, TCHAR *Csid);
Searches the tCsid table for record with csid Csid. Result points to fxCsid structure filled with data found or is NULL if no more data is available.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxCsidGetRowsOpen(TCHAR *SortColumns, TCHAR *Filter, int *ColumnIds, long Count);
FXEXPORT fxCsidGetRowsOpenDefault(TCHAR *SortColumns, TCHAR *Filter);
Opens a recordset on tCsid table. You can affect the recordset form by passing following arguments:
- SortColumns - enumerates fields to sort the recordset by. These are the column names separated by commas. This string is SQL clause ORDER BY argument, so feel free to use clauses like ASC or DESC in field specification.
- Filter - defines an expression that should be fulfilled. It complies the SQL language specification as WHERE clause argument.
- ColumnIds - is an array of columns' integer identifiers as specified in FxAPI.h. Default is FieldsCsidIds.
- Count - specifies ColumnIds array size. Default is CsidCount.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxCsidGetRows(long Start, long *Count, fxCsid *Result);
- Start - number of row where to start retrieving data.
- Count - specifies recordset's row count. Returns real recordset size.
- Result - pointer to array of structures to be filled with data.
Retrieves Count of the records starting with row number Start. All the data is stored into an array pointed by Result.
Returns FX_OK if alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxCsidGetRowsClose();
Closes the current recordset.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxCsidCount(long *Result);
- Result - buffer to store the record count.
Returns the current recordset record count.
Returns FX_OK if everything is alright, FX_OLE_DISPATCH_EXCEPTION if an exception raised or FX_ERROR if another problem encountered.
Example: See Data Querying above.
FXEXPORT fxStateCreate (fxState **Result);
- Result - buffer to return pointer to the new allocated fxState structure.
Correctly allocates fxState structure.
Returns FX_OK.
FXEXPORT fxStateAddOpen();
Opens a recordset on tState table and prepares for user data adding.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxStateAdd(fxState *NewState);
- NewState - fxState structure pointer referencing data to be stored.
Adds a new record to an open recordset filled with data from NewState structure. If primary key constraint fails on current record, the data are not stored and FX_OLE_DISPATCH_EXCEPTION is returned - you can omit this and continue adding another data and modify those causing primary key duplicate later.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxStateAddClose();
Synchronizes the recordset's contents with tState table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxStateModifyOpen();
Opens a recordset on tState table and prepares for user data modifying.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxStateModify(fxState *OldState, fxState *NewState);
- OldState - fxState structure pointer referencing primary key data to define the row to be updated. This actually means that only prefix and type members are used.
- NewState - fxState structure pointer referencing data to be stored. Note that the values of all the structure members are updated.
Next to respective record retrieval modifies this with new values. If origin record not found, the new one is added.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxStateModifyClose();
Synchronizes the recordset's contents with tState table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxStateEraseOpen();
Opens a recordset on tState table and prepares for data erasing.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxStateErase(TCHAR *Prefix, TCHAR Type);
- Prefix - prefix value determining the row to be deleted.
- Type - prefix type value determining the row to be deleted.
Deletes the record with primary key values of Type and Prefix.
Returns FX_OK if operation succeeded, FX_NOT_FOUND if no record with specified primary key value exists or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxStateEraseClose();
Synchronizes the recordset's contents with tState table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxStateKill(fxState *State);
Frees the State pointed structure.
Returns FX_OK.
Example: See Data Querying above.
FXEXPORT fxStateQueryAll(fxState **Result);
Goes through all the records in tState table. Result points to fxState structure filled with data found or is NULL if reached the end of the table.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxStateQueryNumber(fxState **Result, TCHAR Type, TCHAR *Prefix);
Searches the tState table for record of type Type with prefix Prefix. Result points to fxState structure filled with data found or is NULL if data not found.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxStateGetRowsOpen(TCHAR *SortColumns, TCHAR *Filter, int *ColumnIds, long Count);
FXEXPORT fxStateGetRowsOpenDefault(TCHAR *SortColumns, TCHAR *Filter);
Opens a recordset on tState table. You can affect the recordset form by passing following arguments:
- SortColumns - enumerates fields to sort the recordset by. These are the column names separated by commas. This string is SQL clause ORDER BY argument, so feel free to use clauses like ASC or DESC in field specification.
- Filter - defines an expression that should be fulfilled. It complies the SQL language specification as WHERE clause argument.
- ColumnIds - is an array of columns' integer identifiers as specified in FxAPI.h. Default is FieldsStateIds.
- Count - specifies ColumnIds array size. Default is StateCount.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxStateGetRows(long Start, long *Count, fxState *Result);
- Start - number of row where to start retrieving data.
- Count - specifies recordset's row count. Returns real recordset size.
- Result - pointer to array of structures to be filled with data.
Retrieves Count of the records starting with row number Start. All the data is stored into an array pointed by Result.
Returns FX_OK if alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxStateGetRowsClose();
Closes the current recordset.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxStateCount(long *Result);
- Result - buffer to store the record count.
Returns the current recordset record count.
Returns FX_OK if everything is alright, FX_OLE_DISPATCH_EXCEPTION if an exception raised or FX_ERROR if another problem encountered.
Example: See Data Querying above.
FXEXPORT fxFileId(long *Result, TCHAR *Filename);
- Result - buffer to store the id found.
- Filename - name of the file to return id.
Returns the id of the file named Filename as stored in tFile table. Any path contained in Filename is cut off before searching. If file not found, *Result is set to 0 (notice that ids are one-based).
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
FXEXPORT fxFileName(long Id, TCHAR *Filename);
- Id - id of the file to look for.
- Filename - buffer where to store the name of the file.
Fills Filename buffer with the name of the file identified by Id as stored in tFile table. If file with Id not found, buffer stays unchanged.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
FXEXPORT fxFileFreeId(long *Result);
Fills Result buffer with the lowest id not used in tFile table.
FXEXPORT fxFileStore(long *Result, TCHAR *Filename);
- Result - buffer to pass the id of the file stored.
- Filename - name of the file to be stored.
Stores file specified by Filename into tFile table. Result holds the id attached to this file.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
FXEXPORT fxFileSave(TCHAR *Filename, TCHAR *DestDir);
- Filename - name of the file to be saved.
- DestDir - specifies the destination directory.
Saves file specified by Filename stored in tFile table in DestDir directory.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
FXEXPORT fxArchiveAddOpen();
Opens a recordset on tFax table and prepares for user data adding.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxArchiveAdd(fxFax *NewFax);
- NewFax - fxFax structure pointer referencing data to be stored.
Adds a new record to an open recordset filled with data from NewFax structure. If primary key constraint fails on current record, the data are not stored and FX_OLE_DISPATCH_EXCEPTION is returned - you can omit this and continue adding another data and modify those causing primary key duplicate later.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxArchiveAddClose();
Synchronizes the recordset's contents with tFax table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Adding above.
FXEXPORT fxArchiveModifyOpen();
Opens a recordset on tFax table and prepares for user data modifying.
Returns FX_OK if initialization succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxArchiveModify(fxFax *OldFax, fxFax *NewFax);
- OldFax - fxFax structure pointer referencing primary key data to define the row to be updated. This actually means that only id member is used.
- NewFax - fxFax structure pointer referencing data to be stored. Note that the values of all the structure members are updated.
Next to respective record retrieval modifies this with new values. If origin record not found, the new one is added.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxArchiveModifyClose();
Synchronizes the recordset's contents with tFax table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Modifying above.
FXEXPORT fxArchiveEraseOpen();
Opens a recordset on tFax table and prepares for data erasing.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxArchiveErase(fxFax *Fax);
- Fax - pointer to fxFax structure determining the row to be deleted.
Deletes the record with primary key value of Fax.
Returns FX_OK if operation succeeded, FX_NOT_FOUND if no record with specified primary key value exists or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxArchiveEraseClose();
Synchronizes the recordset's contents with tFax table and closes one.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Deleting above.
FXEXPORT fxArchiveItems(long *Result, TCHAR *Filter, TCHAR **Error);
- Result - buffer pointer where to store the record count.
- Filter - specifies the recordset items by SQL WHERE clause argument as mentioned in Data Querying above.
- Error - buffer pointer where to store possible error message. Currently not used.
Gets count of items in accordance with Filter returning error message in Error. This service is provided for backward compatibility only.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
FXEXPORT fxArchiveKill(fxFax *Fax);
Frees the Fax pointed structure, including the possibly allocated freetext member.
Returns FX_OK.
Example: See Data Querying above.
FXEXPORT fxArchiveQueryId(fxFax **Result, long Id);
Searches the tFax table for fax with identifier Id. Result points to fxFax structure filled with data found or is NULL if data not found.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxArchiveQueryAll(fxFax **Result);
Goes through all the records in tFax table. Result points to fxFax structure filled with data found or is NULL if reached the end of the table.
Note: This type of query demands repeated calling until NULL is returned in Result.
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an OLE exception was generated.
Example: See Data Querying above.
FXEXPORT fxArchiveQuerySet(fxFax *Result, int StartRow, long *Number, TCHAR *Filter, TCHAR **Error);
- Result - fxFax structure array where to store data retrieved.
- StartRow - specifies the recordset items by SQL WHERE clause argument as mentioned in Data Querying above.
- Number - record count to be read and real returned records count.
- Filter - specifies the recordset items by SQL WHERE clause argument as mentioned in Data Querying above.
- Error - buffer pointer where to store possible error message. Currently not used.
Gets the fax row set from StartRow record of *Number items in accordance with Filter returning error message in Error. This service is provided for backward compatibility only.
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
FXEXPORT fxArchiveGetRowsOpen(TCHAR *SortColumns, TCHAR *Filter, int *ColumnIds, long Count);
FXEXPORT fxArchiveGetRowsOpenDefault(TCHAR *SortColumns, TCHAR *Filter);
Opens a recordset on tFax table. You can affect the recordset form by passing following arguments:
- SortColumns - enumerates fields to sort the recordset by. These are the column names separated by commas. This string is SQL clause ORDER BY argument, so feel free to use clauses like ASC or DESC in field specification.
- Filter - defines an expression that should be fulfilled. It complies the SQL language specification as WHERE clause argument.
- ColumnIds - is an array of columns' integer identifiers as specified in FxAPI.h. Default is FieldsFaxIds.
- Count specifies ColumnIds array size. Default is FaxCount - 1 (omit the fFreetex member).
Returns FX_OK if operation succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxArchiveGetRows(long Start, long *Count, fxFax *Result);
- Start - number of row where to start retrieving data.
- Count - specifies recordset's row count. Returns real recordset size.
- Result - pointer to array of structures to be filled with data.
Retrieves Count of the records starting with row number Start. All the data is stored into an array pointed by Result.
Returns FX_OK if alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxArchiveGetRowsClose();
Closes the current recordset.
Returns FX_OK if close-up succeeded or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example: See Data Querying above.
FXEXPORT fxArchiveGetFreeText(fxFax *Fax);
- Fax - structure with info on fax to get freetext to. Note that only id member is necessary.
Retrieves the freetext member of fxFax structure from database. Remember to free this structure using fxArchiveKill call!
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example:
FXEXPORT fxArchiveSetFreeText(fxFax *Fax, TCHAR *Freetext);
- Fax - structure with info on fax to get freetext to. Note that only id member is necessary.
- Freetext - new freetext to be stored with this fax.
Sets the freetext member of fxFax structure and updates the database. Remember to free this structure using fxArchiveKill call!
Returns FX_OK if everything is alright or FX_OLE_DISPATCH_EXCEPTION if an exception raised.
Example:
fxFax *Fax; Out = fxArchiveQueryId(&Fax, 10); Out = fxArchiveSetFreeText(Fax, _T("Here comes whatever text you wish to save with this fax."));
FXEXPORT fxArchiveCount(long *Result);
- Result - buffer to store the record count.
Returns the current recordset record count.
Returns FX_OK if everything is alright, FX_OLE_DISPATCH_EXCEPTION if an exception raised or FX_ERROR if another problem encountered.
Example: See Data Querying above.
FXEXPORT fxFree (void *p);
Frees the data pointed by p. This is implemented for backward compatibility only. You should use appropriate fx#Kill service instead.
Returns FX_OK.