|
OA4QRY.DLL API Dokumentation & Beispiele
Liste der Anhänge anzeigen (Anzahl: 1)
Für diejenigen die nun an die Windows Entwicklung denken hier einmal eine kurze API Dokumentation .
Weiters hier im Anschluß auch einige Programmbeispiele als SDK Paket.
PHP-Code:
***********************************************************
* Open Access IV database driver *
* *
* (C) by Dipl.-Ing. (FH) Ludwig Ertl 2006-2008 *
* *
*************************************************************
* Module: API definition header file *
* File: oa4api.h *
* Description: Function declaration and description of the *
* API of the OA4 database driver. *
*************************************************************/
// Some type definitions
#ifndef EXPORT
#define EXPORT
#endif
#ifndef BOOL
typedef int BOOL;
#endif
#ifndef TRUE
#define TRUE 1
#endif
#ifndef FALSE
#define FALSE 0
#endif
#ifndef HANDLE
typedef void* HANDLE;
#endif
/* SetDBPath
*
* Sets the path where the Library should search for database files. This is a global setting that should
* never be changed after it is set once! Per default, the search path is the current directory upon module
* initialisation.
*
* Generally, you can specify the search path in the Select function, but for convenience you can set the
* search path here so that you just need the table name in Select()
*
* Parameters:
* pszDBpath - [IN] String that contains the search path
*/
EXPORT void SetDBPath (char *pszDBpath);
/* GetErrorCode
*
* Get the errorcode of the last error that occured when opening a database failed.
*
* You can get the description of the last operating system error that occured when the
* operation failed via a call to the GetLastErrorMsg() function
*
* Returns:
* Last error that occured in module:
* 0 - No error
* -1 - Parameter mismatch
* -2 - Error opening file for read access
* -3 - Error reading FCB from file
* -4 - Memory allocation for header failed.
* -5 - Reading header bytes failed.
*/
EXPORT int GetErrorCode (void);
/* GetLastErrorMsg
*
* Return textual description of last OS error that occured when opening the database failed
* (see GetErrorCode)
*
* Parameters:
* pszBuf - [OUT] Buffer that is filled with last error message
* cbBuf - [IN] Size of the buffer
*
* Returns:
* On success: Number of bytes written to pszBuf
* On failure: 0
*/
EXPORT unsigned long GetLastErrorMsg (char *pszBuf, unsigned long cbBuf);
/* Select
*
* Select a table (database file) for operation and returns an instance handle to it.
* You need a handle for every query that you do on the table. After you are done, close the handle with
* CloseSearchHandle function, otherwise you will leak memory!!
*
* Parameters:
* pszTable - Name of table (database file) to select. It is allowed to include a path here
* but never supply a file extension.
*
* Returns:
* On success: Instance handle for search that you can use for your querys.
* On failure: NULL
*/
EXPORT HANDLE Select (char *pszTable);
/* GetFileVersion
*
* Get the version of the file specified by the instance handle hSearchHandle
* This returns the OpenAccess Version the file was created with (i.e. 2, 3 or 4)
*
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*
* Returns:
* Open Access version number of file: 2, 3 or 4
*/
EXPORT unsigned int GetFileVersion (HANDLE hSearchHandle);
/* OpenBracket
*
* Adds an opening bracket to your query (like a ( bracket in SQL)
* Don't forget to close the bracket again with CloseBracket() function!
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*/
EXPORT void OpenBracket (HANDLE hSearchHandle);
/* AddOperand
*
* Adds an operand to your query. The following operands are possible:
* +---------+----------------+
* | Operand | SQL equivalent |
* +---------+----------------+
* | & | AND |
* | | | OR |
* +---------+----------------+
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* oper - [IN] Operand to add (see table above)
*
* Returns:
* On success: TRUE
* On failure: FALSE
*/
EXPORT BOOL AddOperand (HANDLE hSearchHandle, char oper);
/* AddConstraint
*
* Adds a constraint to your query. The following actions are possible:
* +---------+----------------+
* | Action | SQL equivalent |
* +---------+----------------+
* | < | < |
* | > | > |
* | = | = |
* | ! | NOT |
* | [ | <= |
* | ] | >= |
* | ~ | LIKE |
* | # | NOT LIKE |
* +---------+----------------+
*
* If there was no operand specified between last and this constraint, we add an AND-constraint.
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* pszColumn - [IN] Name of column to compare with pszValue
* iMode - [IN] Coversion mode for pValue (see Bind() documentation)
* pValue - [IN] Value to compare with
* cAction - [IN] Comparison action (see table above)
*
* Returns:
* On success: TRUE
* On failure: FALSE
*/
EXPORT BOOL AddConstraint (HANDLE hSearchHandle, char *pszColumn, int iMode, void *pValue, char cAction);
/* CloseBracket
*
* Close a bracket formerly opened with OpenBracket()
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*
* Returns:
* On success: TRUE
* On failure: FALSE
*/
EXPORT BOOL CloseBracket (HANDLE hSearchHandle);
/* CloseSearchHandle
*
* Close a search handle opened by Select() after you used it. Don't forget to do this to
* avoid memory leaks!
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*/
EXPORT void CloseSearchHandle (HANDLE hSearchHandle);
/* Compare
*
* Compares value in row, col with pszValue
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* row - [IN] Row number (cursor) of row to compare. This can be the row number
* returned by FindRow or just a row number >0 && < GetNumRows()
* col - [IN] Column index of column to compare. Get it with GetColumn().
* iMode - [IN] Coversion mode for pValue (see Bind() documentation)
* pValue - [IN] Value to compare with
* cAction - [IN] Comparison action (see table from AddConstraint() documentation)
* Returns:
* If identical: 1 (=TRUE)
* If different: 0 (=FALSE)
* On error: -1 Cannot convert pszValue to dataset value
*/
EXPORT int Compare (HANDLE hSearchHandle, unsigned long row, short col, int iMode, void *pValue, char cAction);
/* FindRow
*
* Searches for the next row that matches the query specified by the
* constraints set on hSearchHandle (see AddConstraint, ...). If no constraints
* were set, all datasets are returned.
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*
* Returns:
* >0 - row was found, the returned value is the row number.
* 0 - No dataset was found matching the specified query.
*/
EXPORT unsigned long FindRow (HANDLE hSearchHandle);
/* GetColumn
*
* Gets the column index for the column with name specified in pszCol
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* pszCol - [IN] Name of column to search
*
* Returns:
* >=0 - column number of column found
* -1 - No column found with that name
*/
EXPORT short GetColumn(HANDLE hSearchHandle, char *pszCol);
/* GetNumColumns
*
* Gets the number of columns of the selected table
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*
* Returns:
* Number of columns. Column numbers start with 0!
*/
EXPORT short GetNumColumns(HANDLE hSearchHandle);
/* GetNumRows
*
* Gets the number of rows of the selected table
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*
* Returns:
* Number of rows. Row numbers start with 1!
*/
EXPORT unsigned long GetNumRows(HANDLE hSearchHandle);
/* GetColHeader
*
* Gets the name of the column with index col
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* col - [IN] Column index of column to find the name for.
* pszColName - [OUT] Output buffer that receives the name of the column
* (max. 10 chars + \0 = 11 bytes)
* cbLength - [IN] sizeof(pszColName)
*
* Returns:
* On success: TRUE
* On failure: FALSE
*/
EXPORT BOOL GetColHeader (HANDLE hSearchHandle, short col, char *pszColName, unsigned long cbLength);
#define E(x) x
/* GetDataType
*
* Gets the data type of the column with index col. The data type can be one of the following:
*/
#ifndef __OA4DB_H__
#define __DATA_TYPE \
E(Text),
E(Number),
E(ScientificNotation),
E(Bool),
E(Untyped),
E(Decimal),
E(Date),
E(Time),
E(Memo)
typedef enum _DATA_TYPE { __DATA_TYPE } DATA_TYPE;
#endif
/*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* col - [IN] Column index of column to find the name for. Get it with GetColumn().
*
* Returns:
* Data type of column as defined by enum DATA_TYPE
*/
EXPORT int GetDataType (HANDLE hSearchHandle, short col);
/* G_DATA_TYPE_STR
*
* String list of type names for DATA_TYPE.
* For example G_DATA_TYPE_STR[Bool] (= G_DATA_TYPE_STR[3]) returns "Bool"
*/
#ifndef __OA4DB_H__
#undef E
#define E(x) #x
const char *G_DATA_TYPE_STR[] = { __DATA_TYPE };
#undef E
#endif
/* GetColSize
*
* Gets the size of the column with index col (max. 255). Don't use for MEMOs.
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* col - [IN] Column index of column to find the column size for. Get it with GetColumn().
*
* Returns:
* Size of the column (max. 255)
*/
EXPORT int GetColSize (HANDLE hSearchHandle, short col);
/* HasPassword
*
* Returns TRUE, if this file is password protected, FALSE if not.
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*
* Returns:
* TRUE if protected, FALSE if not.
*/
EXPORT BOOL HasPassword (HANDLE hSearchHandle);
/* Bind
*
* Binds a column for the Insert/Update/Fetch operation with the current handle so that
* the module knows where to put the data.
*
* ATTENTION: You have to bind the columns in ascending order!!
* i.E. binding col 1 before col 0 is not valid and will lead to invalid results!
*
*
* Parameters:
* col - [IN] Column index of column to fetch.
* iMode - [IN] Fetching mode. The mode specifies the format of pData and can be
* one of the following:
* OA4_BIND_TYPE - Bind pData to the appropriate data type shown in
* the table below (faster).
* OA4_BIND_STRING - Always return a string representation of the data.
* pData - [OUT] Output buffer that receives the data found.
*
* Notes for iMode = OA4_BIND_TYPE:
* --------------------------------
* The following table shows which data type is expected for the appropriate
* field type:
* +---------------------+----------------------+--------------------------+
* | Field type | C data type | Additional info |
* +---------------------+----------------------+--------------------------+
* | Text | char[255] | |
* | Number | unsigned long | |
* | ScientificNotation | double | |
* | Bool | BOOL (int) | TRUE = 1, FALSE = 0 |
* | Untyped | - Not supported - | |
* | Decimal | double | |
* | Date | unsigned long | Divided into YYYYDDMM |
* | | | Cast to struct OADATE |
* | Time | unsigned long | Seconds since midnight |
* | Memo | char[] | Better use FetchMemo() |
* +---------------------+----------------------+--------------------------+
*
* Notes for iMode = OA4_BIND_STRING:
* ----------------------------------
* - The char buffer should be 256 bytes in size so that it can receive data
* of all data types except Memos.
* - All numbers use a decimal point (.), not a comma (,)!
* - Bool values can be either TRUE or FALSE (not WAHR, FALSCH or other language dependant representations)
* - Date values must be formatted as MM.DD.YYYY
* - Don't use this on memos, use the function FetchMemo()
*
* cbLength - [IN] sizeof(pData)
*
* Returns:
* TRUE - Binding successful
* FALSE - Binding failed (invalid col)
*/
#define OA4_BIND_TYPE 0
#define OA4_BIND_STRING 1
#pragma pack(1)
typedef struct
{
unsigned short wYear;
unsigned char cDay;
unsigned char cMonth;
} OADATE;
#pragma pack()
EXPORT BOOL Bind (HANDLE hSearchHandle, short col, int iMode, void *pData, unsigned long cbLength);
/* BindReset
*
* Resets all bindings previously made with Bind() command
*/
EXPORT void BindReset (HANDLE hSearchHandle);
/* FetchRow
*
* Fetches row with index row and puts data into output buffer that was previously bound with the
* Bind() command.
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* row - [IN] Row number (cursor) of row to fetch. This can be the row number
* returned by FindRow or just a row number >0 && < GetNumRows()
*
* Note:
* -----
* If you want to fetch a Memo field, the size can vary, therefore you don't know
* the size of the buffer to reserve. Therefore you should use the
* special Memo functions FetchMemo() and FreeMemo() that return a DLL-allocated buffer.
*
* Returns:
* 1 - Success
* 0 - Failure (cannot fetch row)
* <0 - Failure: The absolute value is the number of the column whose buffer is too small
*/
EXPORT BOOL FetchRow (HANDLE hSearchHandle, unsigned long row);
/* FetchMemo
*
* Special function to fetch a memo.
* Returns a DLL-allocated buffer that contains the Memo.
* Don't forget to free it with FreeMemo()!
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* row - [IN] Row number (cursor) of row to fetch. This can be the row number
* returned by FindRow or just a row number >0 && < GetNumRows()
* col - [IN] Column index of column to fetch. Must point to a Memo column!
*
* Returns:
* On success: Buffer that contains the Memo data. Don't forget to FreeMemo() !
* On failure: NULL
*/
EXPORT char *FetchMemo (HANDLE hSearchHandle, unsigned long row, short col);
/* FreeMemo
*
* Frees a memo buffer allocated by FetchMemo()
*
* Parameters:
* pszMemo - [IN] Pointer to the memo that has to be freed
*
*/
EXPORT void FreeMemo (char *pszMemo);
/* UpdateRow
*
* Updates the dataset in row from columns bound with Bind()
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* row - [IN] Row number (cursor) of row to update. This can be the row number
* returned by FindRow or just a row number >0 && < GetNumRows()
* Returns:
* On success: Row number of updated row (=row)
* On failure: 0
*/
EXPORT unsigned long UpdateRow (HANDLE hSearchHandle, unsigned long row);
/* InsertRow
*
* Inserts a dataset with data from buffers previously defined with Bind().
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
*
* Returns:
* On success: Row number of new row
* On failure: 0
*/
EXPORT unsigned long InsertRow (HANDLE hSearchHandle);
/* DeleteRow
*
* Deletes a row from the table
*
* Parameters:
* hSearchHandle - [IN] Search handle returned by Select()
* row - [IN] Row number (cursor) of row to delete. This can be the row number
* returned by FindRow or just a row number >0 && < GetNumRows()
* Returns:
* On success: TRUE
* On failure: FALSE
*/
EXPORT BOOL DeleteRow (HANDLE hSearchHandle, unsigned long row);
|