Functions | |
int | mdlDB_buildLink (short *link, int *linkLength, int linkType, LinkProps *props, WCharCP tableName, UInt32 mslink, int dasType) |
Constructs a user data linkage according to the passed parameters. More... | |
int | mdlDB_closeCursor () |
Attempts to close an open cursor. More... | |
int | mdlDB_closeCursorByID (CursorID cursorID) |
This function operates exactly like mdlDB_closeCursor except that it allows the user to operate on more than one cursor at a time. More... | |
int | mdlDB_deleteRow (UInt32 mslinkKey, WCharCP tableName) |
Deletes the row from table tableName. More... | |
int | mdlDB_describeTable (MS_sqlda *sqlda, WCharCP table_name) |
Describes the structure of a table in the database. More... | |
int | mdlDB_fetchRow (MS_sqlda *sqlda) |
Retrieves the next row of the query for which the cursor has been opened. More... | |
int | mdlDB_fetchRowByID (MS_sqlda *sqlda, CursorID cursorID) |
Operates exactly like mdlDB_fetchRow except that it allows the user to fetch from more than one cursor at a time. More... | |
void | mdlDB_freeSQLDADescriptor (MS_sqlda *sqlda) |
Will free memory which has been allocated by MicroStation during mdlDB_openCursor, mdlDB_describeTable and mdlDB_describeColumn function calls. More... | |
int | mdlDB_getErrorText (WStringR message, int errorCode) |
Translates a database interface error code into a text message. More... | |
int | mdlDB_insertRowByForm (WCharCP table) |
Used to insert a new row into a database table using a screen form. More... | |
int | mdlDB_openCursor (WCharCP query) |
Opens a cursor for an SQL query. More... | |
int | mdlDB_openCursorWithID (CursorID *cursorID, WCharCP query) |
Operates exactly like mdlDB_openCursor except that it allows the user to open more than one cursor at a time. More... | |
int | mdlDB_processSQL (WCharCP sqlStatement) |
Submits general non-SELECT SQL statements to the database server. More... | |
int | mdlDB_readColumn (WCharP columnValue, WCharCP tableName, UInt32 mslinkKey, WCharCP columnName) |
Reads columns from table rows. More... | |
int | mdlDB_sqlQuery (WCharP column, WCharCP query) |
Designed for an SQL query that returns a single-column/single-row result. More... | |
int | mdlDB_writeColumn (WCharCP tableName, UInt32 mslinkKey, WCharCP columnName, WCharCP columnValue) |
Updates columns in table rows. More... | |
int | mdlDB_allocateDescriptor (MS_sqlda *sqlda) |
Allocates memory for the SQL data descriptor. More... | |
int | mdlDB_extractLinkages (DatabaseLink **link, int *linkCount, MSElementP element) |
Extracts an element's database linkages. More... | |
int | mdlDB_addRowWithMslink (UInt32 *mslink, WCharCP tableName, WCharCP insertStmt) |
Adds a new row to the indicated table and returns the new mslink number. More... | |
int | mdlDB_additionalRequest (void **returnData, int *returnLength, void *data, int length) |
Allows developers to define their own database request for the SQL Tool Kit. More... | |
int | mdlDB_copyTable (WCharCP tableName, WCharCP newTableName) |
Creates a new table with the same structure as an existing table. More... | |
int | mdlDB_databaseProfile (DatabaseProfile *profileP) |
Gets a description of the capabilities of the current database server. More... | |
int | mdlDB_describeColumn (MS_sqlda *sqlda, WCharCP tableName, WCharCP columnName) |
Returns a column descriptor for a column for a particular table in the database. More... | |
int | mdlDB_describeDatabase (StringListP *tableNames) |
Returns a string list containing the names of all of the tables to which the user has access. More... | |
void | mdlDB_disconnectDatabase () |
Used to break the connection between MicroStation and the database to which it is connected at the time of the function call. More... | |
void | mdlDB_getMscatalogName (WCharP mscatName) |
Gets the value of the MS_MSCATALOG environment variable. More... | |
int | mdlDB_getLastError (WStringR errorString, int *errorcode) |
Returns the error message for the given error code, or the last error that was returned. More... | |
int mdlDB_additionalRequest | ( | void ** | returnData, |
int * | returnLength, | ||
void * | data, | ||
int | length | ||
) |
Allows developers to define their own database request for the SQL Tool Kit.
[out] | returnData | Specifies a buffer that holds the return data. returndata is dynamically allocated in the function. The user is responsible for freeing returndata. |
[out] | returnLength | Specifies the size of the return data. |
[in] | data | Specifies the data making up the message. |
[in] | length | Specifies the length of the data in the message. |
int mdlDB_addRowWithMslink | ( | UInt32 * | mslink, |
WCharCP | tableName, | ||
WCharCP | insertStmt | ||
) |
Adds a new row to the indicated table and returns the new mslink number.
[out] | mslink | Specifies the new mslink for the added row. |
[in] | tableName | Specifies the table to which the row should be added. If an insert statement is provided this argument is not necessary. |
[in] | insertStmt | Specifies an insert statement to supply new values for the new row. Any columns but the MSLINK column can be specified. NOT NULL columns have to have specified values in the insert statement. The insert statement must have the form: insert into table (column list) values (value list) |
int mdlDB_allocateDescriptor | ( | MS_sqlda * | sqlda | ) |
Allocates memory for the SQL data descriptor.
[in,out] | sqlda | An MS_sqlda structure that specifies the number of columns to allocate memory for, and contains the pointers that are set to indicate the allocated memory areas. |
int mdlDB_buildLink | ( | short * | link, |
int * | linkLength, | ||
int | linkType, | ||
LinkProps * | props, | ||
WCharCP | tableName, | ||
UInt32 | mslink, | ||
int | dasType | ||
) |
Constructs a user data linkage according to the passed parameters.
The returned linkage link can be attached to an element using mdlElement_appendAttributes. The linkage length, in words, is returned in linkLength.
[out] | link | database linkage |
[in] | linkType | The linkage type linkType is one of the following values:
|
[out] | linkLength | Length (words) of the linkage. |
[in] | props | Properties word. |
[in] | tableName | Specifies the name of the database table to which the linkage will point. The table row's unique integer key is specified by mslink. The displayable attribute type is given by dasType. |
[in] | mslink | MSLK key. |
[in] | dasType | Displayable attribute type. |
int mdlDB_closeCursor | ( | ) |
Attempts to close an open cursor.
If a cursor is already open when mdlDB_openCursor is called, CURSOR_ALREADY_OPEN is returned and the cursor remains open. This is a change from Version 4. MicroStation will no longer close the cursor if it is already open; the decision of when or if to use mdlDB_closeCursor is left up to the developer. To use multiple cursors refer to mdlDB_openCursorWithID.
int mdlDB_closeCursorByID | ( | CursorID | cursorID | ) |
This function operates exactly like mdlDB_closeCursor except that it allows the user to operate on more than one cursor at a time.
A pool of cursors is available to the database server. Each time mdlDB_openCursorWithID is called one of these is allocated. The cursor is subsequently referenced using the identifier returned. When no more cursors are available mdlDB_openCursorWithID returns an error.
[in] | cursorID | ID of cursor to close. |
int mdlDB_copyTable | ( | WCharCP | tableName, |
WCharCP | newTableName | ||
) |
Creates a new table with the same structure as an existing table.
Rows from the existing table are not copied into the new table.
[in] | tableName | Specifies the name of an existing database table. |
[in] | newTableName | Specifies name for the new database table. |
int mdlDB_databaseProfile | ( | DatabaseProfile * | profileP | ) |
Gets a description of the capabilities of the current database server.
[out] | profileP | Specifies a DatabaseProfile structure to be filled in by this function. |
int mdlDB_deleteRow | ( | UInt32 | mslinkKey, |
WCharCP | tableName | ||
) |
Deletes the row from table tableName.
This table has the unique integer key mslink.
[in] | mslinkKey | MSLK key of row to delete. |
[in] | tableName | Table name. |
int mdlDB_describeColumn | ( | MS_sqlda * | sqlda, |
WCharCP | tableName, | ||
WCharCP | columnName | ||
) |
Returns a column descriptor for a column for a particular table in the database.
[out] | sqlda | Specifies the information about the column. Since only the information about one column is returned, just the first position of each array in sqlda is allocated and populated. The user is responsible for calling mdlDB_freeSQLDADescriptor on sqlda. |
[in] | tableName | Specifies the name of the table containing the column. |
[in] | columnName | Specifies the name of the column. |
int mdlDB_describeDatabase | ( | StringListP * | tableNames | ) |
Returns a string list containing the names of all of the tables to which the user has access.
[out] | tableNames | Specifies a string list pointer which will point to a string list of the database table names. The user is responsible for calling mdlStringList_destroy on tablenames. |
int mdlDB_describeTable | ( | MS_sqlda * | sqlda, |
WCharCP | table_name | ||
) |
Describes the structure of a table in the database.
An MS_sqlda structure, allocated by the caller, should be passed to the function.
[in,out] | sqlda | table structure |
[in] | table_name | name of database table |
void mdlDB_disconnectDatabase | ( | ) |
Used to break the connection between MicroStation and the database to which it is connected at the time of the function call.
int mdlDB_extractLinkages | ( | DatabaseLink ** | link, |
int * | linkCount, | ||
MSElementP | element | ||
) |
Extracts an element's database linkages.
Only the linkage types identified by MS_LINKTYPE will be recognized by this function. The user is responsible for freeing the memory allocated for the array of links.
[out] | link | Specifies a pointer to a DatabaseLink which is set to point to an array of the linkages found. This function allocates the memory needed by the DatabaseLink. |
[out] | linkCount | Specifies the number of linkages found on the element. |
[in] | element | Specifies the element from which to extract linkages. |
int mdlDB_fetchRow | ( | MS_sqlda * | sqlda | ) |
Retrieves the next row of the query for which the cursor has been opened.
It receives a pointer to an MS_sqlda structure. MS_sqlda is allocated by MicroStation.
[out] | sqlda | current row of query |
Operates exactly like mdlDB_fetchRow except that it allows the user to fetch from more than one cursor at a time.
A pool of cursors is available to the database server. Each time mdlDB_openCursorWithID is called one of these is allocated. The cursor is subsequently referenced using the identifier returned. When no more cursors are available mdlDB_openCursorWithID returns an error.
[out] | sqlda | Current row of query. |
[in] | cursorID | ID of cursor for fetch. |
void mdlDB_freeSQLDADescriptor | ( | MS_sqlda * | sqlda | ) |
Will free memory which has been allocated by MicroStation during mdlDB_openCursor, mdlDB_describeTable and mdlDB_describeColumn function calls.
The structure Ms_sqlda contains pointers to arrays of character pointers for column names, values and other attributes. When a database cursor is opened with mdlDB_openCursor MicroStation examines the query and allocates sufficient memory in the Ms_sqlda for the columns referenced in the query.
[in,out] | sqlda | Descriptor to free. |
int mdlDB_getErrorText | ( | WStringR | message, |
int | errorCode | ||
) |
Translates a database interface error code into a text message.
It is particularly useful for obtaining error messages for errors which occurred in the database (non-MicroStation) processing of an MDL function. In general, MicroStation error return codes are positive. Errors from the RDBMS are usually negative. mdlDB_getErrorText will process both positive and negative error codes.
[out] | message | The argument message is a WString that will receive the error message corresponding to error code errorCode. message should be the size of MAX_ERROR_LENGTH+1. |
[in] | errorCode | Error code. |
int mdlDB_getLastError | ( | WStringR | errorString, |
int * | errorcode | ||
) |
Returns the error message for the given error code, or the last error that was returned.
[out] | errorString | The error message for the given error code. |
[in,out] | errorcode | The error code to get the error message for, or LAST_ERROR to get the error code and message for the last returned error. |
void mdlDB_getMscatalogName | ( | WCharP | mscatName | ) |
Gets the value of the MS_MSCATALOG environment variable.
If no value is assigned, it returns the default control table name. For ODBC flat files, the default is `mscatlog' and for all other platforms it is `mscatalog.'
[out] | mscatName | Points to a buffer to receive the control table name. The buffer must be at least MAX_TABLE_LENGTH + 1 bytes. |
int mdlDB_insertRowByForm | ( | WCharCP | table | ) |
Used to insert a new row into a database table using a screen form.
The argument table specifies a table listed in MSCATALOG. MicroStation will display the screen form listed for table in the MSCATALOG column SCREENFORM. Completing the screen form will add a new row to the database table.
[in] | table | Table name in MSCATALOG. |
int mdlDB_openCursor | ( | WCharCP | query | ) |
Opens a cursor for an SQL query.
It places the cursor before the first row matching the specified query. After a cursor is opened, rows can be retrieved with the mdlDB_fetchRow function. The members of the MS_sqlda are described with the mdlDB_describeTable function. The lengths pointed to by the length member describe column lengths, not necessarily value lengths. For example, the value for a 40-character column with the last 20 characters blank will be a 40-character string.
[in] | query | Query for which the cursor is to be opened |
int mdlDB_openCursorWithID | ( | CursorID * | cursorID, |
WCharCP | query | ||
) |
Operates exactly like mdlDB_openCursor except that it allows the user to open more than one cursor at a time.
A pool of cursors is available to the database server. Each time mdlDB_openCursorWithID is called one of these is allocated. The cursor is subsequently referenced using the identifier returned. When no more cursors are available mdlDB_openCursorWithID returns an error.
[out] | cursorID | ID For cursor opened. |
[in] | query | Query for which the cursor is to be opened. |
int mdlDB_processSQL | ( | WCharCP | sqlStatement | ) |
Submits general non-SELECT SQL statements to the database server.
sqlStatement represents any character string (usually an SQL statement) that the database server can process. In MicroStation, these statements can be interactively submitted to the server when the statement is preceded with the vertical bar '|'. Note that SQL relational databases like Oracle frequently differ in their implementation of SQL by providing vendor-specific enhancements to ANSI SQL.
[in] | sqlStatement | Direct "pass-through" server keyin. |
int mdlDB_readColumn | ( | WCharP | columnValue, |
WCharCP | tableName, | ||
UInt32 | mslinkKey, | ||
WCharCP | columnName | ||
) |
Reads columns from table rows.
The row with an MSLINK key of mslink is read from table tableName. If using dBASE, tablename should be the alias.
[out] | columnValue | Column value. |
[in] | tableName | Database table to read. |
[in] | mslinkKey | MSLK key of column name. |
[in] | columnName | Column name of table to read. |
int mdlDB_sqlQuery | ( | WCharP | column, |
WCharCP | query | ||
) |
Designed for an SQL query that returns a single-column/single-row result.
It should be used only for queries that meet these criteria. If more than one column is required or if the query will return more than one row, a cursor must be used.
[out] | column | The argument column is a character array that receives the result of the SQL SELECT statement query. All values are returned as character data. Appropriate conversions may be done on the result if numeric data is required. |
[in] | query | SQL query. |
int mdlDB_writeColumn | ( | WCharCP | tableName, |
UInt32 | mslinkKey, | ||
WCharCP | columnName, | ||
WCharCP | columnValue | ||
) |
Updates columns in table rows.
The column columnName in the row with an MSLINK key of mslink is updated in table tableName. The column with the name columnName is updated with the value columnValue.
[in] | tableName | Database table to update. |
[in] | mslinkKey | MSLK key of column name. |
[in] | columnName | Column name of table to update. |
[in] | columnValue | New column value. |