Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / w3_apps / winsql.arj / SQL.DOC < prev next >

Wrap

Text File | 1991-12-06 | 119.1 KB | 3,164 lines

Quasar SQL API Page 1 of 51 Quasar SQL For Windows Release 2.0 - November 1991 QUASAR SQL APPLICATIONS PROGRAMMING INTERFACE (API) Copyright (c) 1991 by Stellar Industries All Rights Reserved Summary This manual is divided into six sections: Overview This section describes, in general terms, what the Quasar SQL API is and how you might use it to execute SQL statements within your program. Examples are available both in 'C' (EXAMPLEC.*) and 'Visual Basic' (EXAMPLEB.*). Functions This section includes a formal description of all functions which your program can import from the Quasar SQL API dynamic link library (SQL.LIB, SQL.DLL). Prototypes for all functions can be found in the Quasar SQL API include file for 'C' (SQL.H) and the global file for 'Visual Basic' (SQL.GBL). Constants This section includes a formal description of all constants defined in the Quasar SQL API include file for 'C' and the global file for 'Visual Basic'. Data Structures This section includes a formal description of all data structures which your program will use when it communicates with the Quasar SQL API. Typedefs for all these structures can be found in the Quasar SQL API include file for 'C'. Declarations can be found in the global file for 'Visual Basic'. Result Codes This section gives an explanation of all result codes returned by the Quasar SQL API. Macro definitions for all result codes can be found in the Quasar SQL API include file for 'C'. Global Const definitions can be found in the global file for 'Visual Basic'. Glossary This section defines specialized terms used in this document. Summary Quasar SQL API Page 2 of 51 Overview What is the Quasar SQL API? The Quasar SQL API is a powerful tool that enables you, the software developer, to have full access to a modern, highly optimized ANSI standard SQL database manager: the Quasar Database Administrator. Your programs written in any language which can access dynamic link libraries can also access the Quasar SQL API. These languages include 'C', 'C++', 'Visual Basic', 'Pascal' and most assemblers. In fact, any program which can access the Microsoft Windows environment can access the Quasar SQL API. Microsoft Windows itself is a dynamic link library. The Quasar SQL API is your gateway to modern database technology. With a little more than a dozen functions and only 4 data structures you can perform almost any database task. How does the Quasar SQL API work? "How is this done?" you might ask. Well, while the Quasar Database Administrator is sophisticated, complex and fully optimized for maximum performance: the Quasar SQL API is simple and straight forward. The Quasar SQL API effectively buffers you from all the complex tasks of parsing, query analysis, query optimization, query tree construction, etc. How do I link to the Quasar SQL API? When programming in 'C', you need to do only three things to include all the power of SQL in your application: 1) When you link your object modules, include the SQL.LIB import library along with LIBW.LIB. 2) Include the SQL.H file (e.g. "#include <SQL.H>") in your source code. 3) Put the Quasar Database Administrator (DBA.EXE) and Quasar SQL API (SQL.DLL) someplace where windows can find them (usually in your windows directory). When programming in 'Visual Basic', you need to do only two things to include all the power of SQL in your application: Overview Quasar SQL API Page 3 of 51 1) Be sure to use the SQL.GBL file included with the Quasar SQL API. Note that the 'C' style prefixes used with variable names (i.e. the 'n' in nResultCode, and the 'sz' in szErrorMessage) are not used with 'Visual Basic'. 2) Put the Quasar Database Administrator (DBA.EXE) and Quasar SQL API (SQL.DLL) someplace where windows can find them (usually in your windows directory). How do I use the Quasar SQL API? Your program can login to the Quasar Database Administrator (SqlLogin), open a cursor (SqlCursorOpen) and execute a query (SqlExecute). The query itself is passed to the Quasar SQL API as a simple text string. The Quasar SQL API does all the work for you. To get your answers back (from a SELECT statement, for example) you simply fetch them one at a time from the Quasar SQL API. You can fetch the first record (SqlFetchFirst), last record (SqlFetchLast), next record (SqlFetchNext), previous record (SqlFetchPrevious) or even a record at a position you specify (SqlFetchPositioned). You can have several cursors open at a time so that you can access your data the way you want. When you're all done, close your cursors (SqlCursorClose) and log out (SqlLogout). How can I check out my SQL statements? You can check out your SQL statements using the Quasar Query Editor (QE.EXE) included with the Quasar SQL API. The Quasar Query Editor allows you to type in the query your program is going to send to the Quasar SQL API and have it execute right there in front of you. You'll get all the results back on the screen where you can verify it's what you expected. In fact, the Quasar Query Editor uses the Quasar SQL API the same way your program does. Overview Quasar SQL API Page 4 of 51 Functions All Quasar SQL API functions utilize a common structure to maintain generic information : SQLCONTROL. All functions load descriptive error information into this structure should an error condition arise. The basic status condition is the nResultCode field of this data structure. All Quasar SQL API functions set this field to the appropriate result code in the event of an error. Note: All Quasar SQL API functions clear this field to 0 at entry. SqlCursorClose Closes a cursor when it is no longer needed SqlCursorOpen Opens a cursor in preparation for executing a query SqlDescribeColumn Describes an individual column in the result table SqlDescribeTable Describes the overall characteristics of the result table SqlExecute Causes the database administrator to execute a query and potentially create a result table SqlFetchFirst Retrieves the first record from the result table SqlFetchLast Retrieves the last record from the result table SqlFetchNext Retrieves the next record from the table SqlFetchPrevious Retrieves the previous record from the result table SqlFetchPositioned Retrieves a particular record from the result table. The record is identified by its absolute physical position in the table SqlGetStatus Gets status information concerning the last query executed SqlLogin Logs an user onto the database administrator SqlLogout Logs an user off the database administrator Functions Quasar SQL API Page 5 of 51 Functions: SqlCursorClose Syntax BOOL FAR PASCAL SqlCursorClose(hUser, hCursor, lpSqlControl) This function closes the cursor specified by the hCursor parameter and drops any result table associated with it. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor to be closed. The hCursor parameter must have been created with the SqlCursorOpen function. lpSqlControl LPSQLCONTROL Points to an SQL control structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. Return Value The return value is 1 if no errors occurred while closing the cursor, otherwise it is 0. Comments Cursors should be closed before logging off with SqlLogout. Functions: SqlCursorClose Quasar SQL API Page 6 of 51 Functions: SqlCursorOpen Syntax HANDLE FAR PASCAL SqlCursorOpen(hUser, lpSqlControl) This function creates a cursor. You must create a cursor after you have logged in (SqlLogin) and before you execute a query (SqlExecute). You can create as many cursors as you need for your application. Parameter Type/Description hUser HANDLE Identifies the user who will own the cursor. The hUser parameter must have been created with the SqlLogin function. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. Return Value The return value is a cursor handle if no errors occurred while opening the cursor, otherwise it is 0. Comments The cursors created by one user are not available to another. Once a cursor has been created and used in an SqlExecute, it may be reused in another SqlExecute by the same user. When a cursor is reused in this manner, the Quasar SQL API effectively closes the cursor and re-opens it with the same handle prior to executing the next query. Note that when a cursor is reused, any old result table associated with it is dropped. Cursors are closed with SqlCursorClose. Cursors should be closed before logging off with SqlLogout. Functions: SqlCursorOpen Quasar SQL API Page 7 of 51 Functions: SqlDescribeColumn Syntax BOOL FAR PASCAL SqlDescribeColumn(hUser, hCursor, lpSqlControl, nColumnSequenceNumber, lpSqlColumn) This function describes the characteristics of the specified column (nColumnSequenceNumber) in the result table associated with the hCursor parameter. The description is loaded into the SQLCOLUMN structure pointed to by the lpSqlColumn parameter. To describe a column you must have already logged in (SqlLogin), created a cursor (SqlCursorOpen) and executed a query (SqlExecute) which contained an SQL SELECT statement. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which owns the result table in which the column exists. The hCursor parameter must have been created with the SqlCursorOpen function. A result table must be associated with the cursor. A result table is created when a query containing an SQL SELECT statement is passed to SqlExecute. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. nColumnSequenceNumber unsigned Identifies the column to be described. Column numbers range from 1 to the number of columns in the result table. lpSqlColumn LPSQLCOLUMN Points to the target SQL Column Description Structure. Functions: SqlDescribeColumn Quasar SQL API Page 8 of 51 Return Value The return value is 1 if no errors occurred, otherwise it is 0. Comments If a result table is not associated with the cursor an error will be generated. Functions: SqlDescribeColumn Quasar SQL API Page 9 of 51 Functions: SqlDescribeTable Syntax BOOL FAR PASCAL SqlDescribeTable(hUser, hCursor, lpSqlControl, lpSqlTable) This function describes the characteristics of the result table associated with the hCursor parameter. The description is loaded into the SQLTABLE structure pointed to by the lpSqlTable parameter. To describe a table you must have already logged in (SqlLogin), created a cursor (SqlCursorOpen) and executed a query (SqlExecute) which contained an SQL SELECT statement. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which owns the result table. The hCursor parameter must have been created with the SqlCursorOpen function. A result table must be associated with the cursor. A result table is created when a query containing an SQL SELECT statement is passed to SqlExecute. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lpSqlTable LPSQLTABLE Points to the target SQL Table Description Structure. Return Value The return value is 1 if no errors occurred, otherwise it is 0. Comments If a result table is not associated with the cursor an error will be generated. Functions: SqlDescribeTable Quasar SQL API Page 10 of 51 Functions: SqlExecute Syntax BOOL FAR PASCAL SqlExecute(hUser, hCursor, lpSqlControl, lpstrQueryText) This function executes the query text pointed to by the lpstrQueryText parameter as a set of one or more SQL statements. If an SQL SELECT statement is included in the query text, a result table is created and associated with the hCursor parameter. To execute a query you must have already logged in (SqlLogin) and created a cursor (SqlCursorOpen). Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which will own the result table if one is created by the query. The hCursor parameter must have been created with the SqlCursorOpen function. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. Additionally, syntax errors detected by the query manager cause the nHiLiteOffset field to be loaded with the character position of the offending phrase within the query text. In this case, the nHiLiteLength field is loaded with the number of characters in the offending phrase. lpstrQueryText LPSTR Points to a null terminated string containing the SQL query. The SQL query may contain one or more SQL statements. Among the SQL statements there can be only 0 or 1 SQL SELECT statement. Functions: SqlExecute Quasar SQL API Page 11 of 51 Return Value The return value is 1 if no errors occurred, otherwise it is 0. Comments Simply calling SqlExecute does not commit your query. Queries are committed when you execute an SQL COMMIT WORK statement. Be sure to execute this vital statement whenever you want your program to permanently modify the database. Each user must close all cursors which have an associated result table before executing an SQL COMMIT WORK statement. This is to insure that your application has completed its access to the result table before permanently committing the transaction. A convenient way to do this is to use the same cursor for the COMMIT WORK as you did for the SELECT: the Quasar SQL API automatically drops any result table that may be associated with a cursor when the cursor is reused. Without the SQL COMMIT WORK statement, all your transactions will be rolled back when either an error occurs or when you log off (SqlLogout). The only exception to this is if you have the mSqlFlagAutoCommitOnLogout option flag set in the wFlags field of the lpSqlControl parameter when you log off. Only in this case are all your transactions automatically committed at logout, and then only if no errors have occurred. Functions: SqlExecute Quasar SQL API Page 12 of 51 Functions: SqlFetchFirst Syntax BOOL FAR PASCAL SqlFetchFirst(hUser, hCursor, lpSqlControl, lpRecordBuffer) This function reads the first record in the result table associated with the hCursor parameter. The data in this record is formatted and loaded into the buffer pointed to by the lpRecordBuffer parameter. To fetch this record you must have already logged in (SqlLogin), created a cursor (SqlCursorOpen) and executed a query (SqlExecute) which contained an SQL SELECT statement. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which owns the result table in which the record exists. The hCursor parameter must have been created with the SqlCursorOpen function. A result table must be associated with the cursor. A result table is created when a query containing an SQL SELECT statement is passed to SqlExecute. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lpRecordBuffer LPSTR Points to a buffer provided by the caller to receive the formatted record. This buffer must be at least as large as the nRecordSize field of SQLTABLE structure indicates. Return Value The return value is 1 if no errors occurred and the table had at least one record, otherwise it is 0. Functions: SqlFetchFirst Quasar SQL API Page 13 of 51 Comments The usual procedure for using the SqlFetchFirst function is as follows: 1) Set Data Format in the wFlags field of the lpSqlControl parameter to the option you intend to use. If you have selected the mSqlFlagFormatPadded option, set the nPadding field of the lpSqlControl parameter to the number of spaces you want between fields. 2) Call SqlExecute. 3) Call SqlDescribeTable to determine the characteristics of the result table. Of particular interest are the nRecordSize and lNumberOfRecords fields of the resultant SQLTABLE structure. 4) If SqlTable.lNumberOfRecords indicates that one or more result table records are available, allocate a buffer sufficiently large (at least as large as SqlTable.nRecordSize) to receive the record's data. Set the lpRecordBuffer parameter to point to this buffer and set the nRecordBufferSize field of the lpSqlControl parameter to the size of the buffer. 5) Call SqlFetchFirst. Once these steps are completed, you can make unlimited calls to any of the Quasar SQL API fetch functions without repeating steps (1) through (4). The same lpRecordBuffer can be reused for all fetches. Note, however, should you change the Data Format setting in the wFlags field of the lpSqlControl parameter, you must call SqlDescribeTable to calculate the new nRecordSize setting, reallocate the lpRecordBuffer and adjust the nRecordBufferSize field of the lpSqlControl parameter accordingly. Functions: SqlFetchFirst Quasar SQL API Page 14 of 51 Functions: SqlFetchLast Syntax BOOL FAR PASCAL SqlFetchLast(hUser, hCursor, lpSqlControl, lpRecordBuffer) This function reads the last record in the result table associated with the hCursor parameter. The data in this record is formatted and loaded into the buffer provided by the caller and pointed to by the lpRecordBuffer parameter. To fetch this record you must have already logged in (SqlLogin), created a cursor (SqlCursorOpen) and executed a query (SqlExecute) which contained an SQL SELECT statement. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which owns the result table in which the record exists. The hCursor parameter must have been created with the SqlCursorOpen function. A result table must be associated with the cursor. A result table is created when a query containing an SQL SELECT statement is passed to SqlExecute. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lpRecordBuffer LPSTR Points to a buffer provided by the caller to receive the formatted record. This buffer must be at least as large as the nRecordSize field of SQLTABLE structure indicates. Return Value The return value is 1 if no errors occurred and the table had at least one record, otherwise it is 0. Functions: SqlFetchLast Quasar SQL API Page 15 of 51 Comments The usual procedure for using the SqlFetchLast function is as follows: 1) Set Data Format in the wFlags field of the lpSqlControl parameter to the option you intend to use. If you have selected the mSqlFlagFormatPadded option, set the nPadding field of the lpSqlControl parameter to the number of spaces you want between fields. 2) Call SqlExecute. 3) Call SqlDescribeTable to determine the characteristics of the result table. Of particular interest are the nRecordSize and lNumberOfRecords fields of the resultant SQLTABLE structure. 4) If SqlTable.lNumberOfRecords indicates that one or more result table records are available, allocate a buffer sufficiently large (at least as large as SqlTable.nRecordSize) to receive the record's data. Set the lpRecordBuffer parameter to point to this buffer and set the nRecordBufferSize field of the lpSqlControl parameter to the size of the buffer. 5) Call SqlFetchLast. Once these steps are completed, you can make unlimited calls to any of the Quasar SQL API fetch functions without repeating steps (1) through (4). The same lpRecordBuffer can be reused for all fetches. Note, however, should you change the Data Format setting in the wFlags field of the lpSqlControl parameter, you must call SqlDescribeTable to calculate the new nRecordSize setting, reallocate the lpRecordBuffer and adjust the nRecordBufferSize field of the lpSqlControl parameter accordingly. Functions: SqlFetchLast Quasar SQL API Page 16 of 51 Functions: SqlFetchNext Syntax BOOL FAR PASCAL SqlFetchNext(hUser, hCursor, lpSqlControl, lpRecordBuffer) This function reads the next record in the result table associated with the hCursor parameter. The data in this record is formatted and loaded into the buffer provided by the caller and pointed to by the lpRecordBuffer parameter. To fetch this record you must have already preformed at least one SqlFetchFirst or SqlFetchLast or SqlFetchPositioned function. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which owns the result table in which the record exists. The hCursor parameter must have been created with the SqlCursorOpen function. A result table must be associated with the cursor. A result table is created when a query containing an SQL SELECT statement is passed to SqlExecute. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lpRecordBuffer LPSTR Points to a buffer provided by the caller to receive the formatted record. This buffer must be at least as large as the nRecordSize field of SQLTABLE structure indicates. Return Value The return value is 1 if no errors occurred and the cursor was not already positioned at the last record, otherwise it is 0. Functions: SqlFetchNext Quasar SQL API Page 17 of 51 Comments The same lpRecordBuffer can be reused for all fetches. Note, however, should you change the Data Format setting in the wFlags field of the lpSqlControl parameter, you must call SqlDescribeTable to calculate the new nRecordSize setting, reallocate the lpRecordBuffer and adjust the nRecordBufferSize field of the lpSqlControl parameter accordingly. Functions: SqlFetchNext Quasar SQL API Page 18 of 51 Functions: SqlFetchPositioned Syntax BOOL FAR PASCAL SqlFetchPositioned(hUser, hCursor, lpSqlControl, lRecordPosition, lpRecordBuffer) This function reads a record in the result table associated with the hCursor parameter. The lRecordPosition parameter indicates which record is to be read. When lRecordPosition is '1', the first physical record is read; when lRecordPosition is '2', the second physical record is read and so on and so forth. The data in this record is formatted and loaded into the buffer provided by the caller and pointed to by the lpRecordBuffer parameter. To fetch this record you must have already logged in (SqlLogin), created a cursor (SqlCursorOpen) and executed a query (SqlExecute) which contained an SQL SELECT statement. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which owns the result table in which the record exists. The hCursor parameter must have been created with the SqlCursorOpen function. A result table must be associated with the cursor. A result table is created when a query containing an SQL SELECT statement is passed to SqlExecute. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lRecordPosition unsigned long Indicates which record is to be read. lpRecordBuffer LPSTR Points to a buffer provided by the caller to Functions: SqlFetchPositioned Quasar SQL API Page 19 of 51 receive the formatted record. This buffer must be at least as large as the nRecordSize field of SQLTABLE structure indicates. Return Value The return value is 1 if no errors occurred and lRecordPosition is greater than zero and less then or equal to the number of records in the table, otherwise it is 0. Comments Physical position is the raw position of the record in the file. Physical order is not the same as the order you specify with the SQL ORDER BY clause. The usual procedure for using the SqlFetchPositioned function is as follows: 1) Set Data Format in the wFlags field of the lpSqlControl parameter to the option you intend to use. If you have selected the mSqlFlagFormatPadded option, set the nPadding field of the lpSqlControl parameter to the number of spaces you want between fields. 2) Call SqlExecute. 3) Call SqlDescribeTable to determine the characteristics of the result table. Of particular interest are the nRecordSize and lNumberOfRecords fields of the resultant SQLTABLE structure. 4) If SqlTable.lNumberOfRecords indicates that one or more result table records are available, allocate a buffer sufficiently large (at least as large as SqlTable.nRecordSize) to receive the record's data. Set the lpRecordBuffer parameter to point to this buffer and set the nRecordBufferSize field of the lpSqlControl parameter to the size of the buffer. 5) Call SqlFetchPositioned. Once these steps are completed, you can make unlimited calls to any of the Quasar SQL API fetch functions without repeating steps (1) through (4). The same lpRecordBuffer can be reused for all fetches. Note, however, should you change the Data Format setting in the wFlags field of the lpSqlControl parameter, you Functions: SqlFetchPositioned Quasar SQL API Page 20 of 51 must call SqlDescribeTable to calculate the new nRecordSize setting, reallocate the lpRecordBuffer and adjust the nRecordBufferSize field of the lpSqlControl parameter accordingly. Functions: SqlFetchPositioned Quasar SQL API Page 21 of 51 Functions: SqlFetchPrevious Syntax BOOL FAR PASCAL SqlFetchPrevious(hUser, hCursor, lpSqlControl, lpRecordBuffer) This function reads the previous record in the result table associated with the hCursor parameter. The data in this record is formatted and loaded into the buffer provided by the caller and pointed to by the lpRecordBuffer parameter. To fetch this record you must have already preformed at least one SqlFetchFirst or SqlFetchLast or SqlFetchPositioned function. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor which owns the result table in which the record exists. The hCursor parameter must have been created with the SqlCursorOpen function. A result table must be associated with the cursor. A result table is created when a query containing an SQL SELECT statement is passed to SqlExecute. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lpRecordBuffer LPSTR Points to a buffer provided by the caller to receive the formatted record. This buffer must be at least as large as the nRecordSize field of SQLTABLE structure indicates. Return Value The return value is 1 if no errors occurred and the cursor was not already positioned at the first record, otherwise it is 0. Functions: SqlFetchPrevious Quasar SQL API Page 22 of 51 Comments The same lpRecordBuffer can be reused for all fetches. Note, however, should you change the Data Format setting in the wFlags field of the lpSqlControl parameter, you must call SqlDescribeTable to calculate the new nRecordSize setting, reallocate the lpRecordBuffer and adjust the nRecordBufferSize field of the lpSqlControl parameter accordingly. Functions: SqlFetchPrevious Quasar SQL API Page 23 of 51 Functions: SqlGetStatus Syntax BOOL FAR PASCAL SqlGetStatus(hUser, hCursor, lpSqlControl, lpSqlStatus) This function returns status information about the most recent call to SqlExecute which used the cursor indicated by the hCursor parameter. Status information includes the number of database records deleted, inserted, selected or updated and the amount of time elapsed during query execution. If the hUser and hCursor parameters are set to 0, SqlGetStatus simply tests for the presence of an active running Quasar Database Administrator. A value of 1 is returned if and only if the database administrator is running. Parameter Type/Description hUser HANDLE Identifies the user who owns the cursor. The hUser parameter must have been created with the SqlLogin function. hCursor HANDLE Identifies the cursor for which the status is to be obtained. The hCursor parameter must have been created with the SqlCursorOpen function. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lpSqlStatus LPSQLSTATUS Points to the target SQL Status Structure. Return Value The return value is 1 if no errors occurred, otherwise it is 0. Comments Each cursor's status information is reset every time SqlExecute is called. Functions: SqlGetStatus Quasar SQL API Page 24 of 51 Functions: SqlLogin Syntax HANDLE FAR PASCAL SqlLogin(lpSqlControl, lpstrUserName, lpstrUserPassword) In order to access the SQL Database Administrator you must first identify yourself as an user with sufficient privilege to access the database. This is accomplished by calling the SqlLogin function with your user name and password. Once logged in, you can reference all your tables without specifying an user name. To reference another user's table you must prefix the table name with the other user's user name. For example for user "JohnDoe" to select all columns of the system tables he must use: SELECT * FROM SYSTEM.TABLES; For user "SYSTEM" to select the "PartNumber" column of user "JohnDoe"'s table "Inventory" use the form: SELECT JohnDoe.Inventory.PartNumber FROM JohnDoe.Inventory; Or, more simply: SELECT PartNumber FROM JohnDoe.Inventory; Parameter Type/Description lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. lpstrUserName LPSTR Points to a null terminated string containing the user name. lpstrUserPassword LPSTR Points to a null terminated string containing the user password. Return Value The return value is an user handle if no errors occurred while logging in, otherwise it is 0. You must use this user handle in all calls to the Quasar SQL API. Functions: SqlLogin Quasar SQL API Page 25 of 51 Comments Only those users recognized by the Quasar Database Administrator will be allowed to log in. When first installed, the Quasar Database Administrator only recognizes the user "SYSTEM" whose password is "QUASAR". You can create additional users by logging in as "SYSTEM" with password "QUASAR" and inserting records into the SYSTEM.USERS table. This table has three columns: USER_NAME, USER_PASSWORD and REMARK. To add user "JohnDoe" with password "IWantToRegisterNow" execute: INSERT INTO USERS VALUES ('JohnDoe', 'IWantToRegisterNow', NULL); John Doe can now login. Functions: SqlLogin Quasar SQL API Page 26 of 51 Functions: SqlLogout Syntax BOOL FAR PASCAL SqlLogout(hUser, lpSqlControl) This function logs the user off the system. If the Automatic Commit option flag is set in the wFlags field of the lpSqlControl parameter, any transaction still in progress is automatically committed; otherwise, all work performed by the user since logging in or since the last COMMIT WORK query (whichever occurred last) is rolled back. Parameter Type/Description hUser HANDLE Identifies the user who wishes to log off. The hUser parameter must have been created with the SqlLogin function. lpSqlControl LPSQLCONTROL Points to an SQL Control Structure. Any errors that may occur cause the szErrorDetail, szErrorMessage and nResultCode fields of this structure to be loaded with descriptive information. Return Value The return value is 1 if no errors occurred, otherwise it is 0. Comments While SqlLogout automatically closes all the user's cursor before logging the user off, we recommend explicitly closing cursor when they are no longer needed. Functions: SqlLogout Quasar SQL API Page 27 of 51 Constants This section includes a formal description of all constants defined in the Quasar SQL API include file for 'C' and the global file for 'Visual Basic'. Be sure to use the values by name as the numeric values may (and probably will) change in the next release of the Quasar SQL API. Data Class Identifies the general characteristics of a column in the result table Data Type Identifies the particular characteristics of a column in the result table Data Format Instructs the Quasar SQL API as to the format of the returned data in the result table Automatic Commit Instructs the Quasar SQL API whether to commit or roll back any pending transaction at user log out Name Length Defines the maximum length of user, table and column names Constants Quasar SQL API Page 28 of 51 Constants: Data Class The following constants identify the general characteristics of a column in the result table. The nDataClass field of the SQLCOLUMN data structure is set to one of these values as a result of an SqlDescribeColumn function call. mSqlDataClassAPPROXIMATE Indicates that the column is one of the approximate numeric data types mSqlDataClassBINARY Indicates that the column is of the binary data type mSqlDataClassCHAR Indicates that the column is one of the character string data types mSqlDataClassEXACT Indicates that the column is one of the exact numeric data types mSqlDataClassINVALID Indicates that the data type of the column is invalid Constants: Data Class Quasar SQL API Page 29 of 51 Constants: Data Type The following constants identify the particular characteristics of a column in the result table. The nDataType field of the SQLCOLUMN data structure is set to one of these values as a result of an SqlDescribeColumn function call. mSqlDataTypeBINARY Indicates that the data type of the column is BINARY: its length is given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeCHAR Indicates that the data type of the column is CHAR: its length is given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeDECIMAL Indicates that the data type of the column is DECIMAL: its precision and scale are given by the nPrecision and nScale fields of the SQLCOLUMN data structure mSqlDataTypeDOUBLE Indicates that the data type of the column is DOUBLE PRECISION: its precision is given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeFLOAT Indicates that the data type of the column is FLOAT: its precision is given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeINTEGER Indicates that the data type of the column is INTEGER: its precision is given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeNUMERIC Indicates that the data type of the column is NUMERIC: its precision and scale are given by the nPrecision and nScale fields of the SQLCOLUMN data structure mSqlDataTypeREAL Indicates that the data type of the column is REAL: its precision is given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeSMALLINT Indicates that the data type of the column is SMALLINT: its precision is Constants: Data Type Quasar SQL API Page 30 of 51 given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeVARCHAR Indicates that the data type of the column is VARCHAR: its maximum length is given by the nPrecision field of the SQLCOLUMN data structure mSqlDataTypeINVALID Indicates that the data type of the column is invalid Constants: Data Type Quasar SQL API Page 31 of 51 Constants: Data Format When a record is fetched from the result table by means of one of the SqlFetch functions, the Quasar SQL API loads the record into a buffer provided by the user. The record is returned in one of three optional formats. The user selects the format he wants by setting the wFlags field of the SQLCONTROL structure to one (and only one) of the following values: mSqlFlagFormatPadded The record is returned as a single null terminated character string. The data for each column is contained within this string separated by spaces. The number of spaces is set by the user in the nPadding field of the SQLCONTROL structure. The length of the string is constant across all records and is available to the user in the nRecordSize field of the SQLTABLE data structure. The length of each column's portion of the string is available to the user in the nFieldWidth field of the SQLCOLUMN data structure. mSqlFlagFormatString The record is returned as a set of null terminated character strings, one for each column. The first column's string is loaded into the first bytes of the record buffer. The second column's string immediately follows the first and so on. Each string contains only the minimum number of characters to represent the data. That is, the strings are not padded. mSqlFlagFormatStructure The record is returned as a packed 'C' data structure. This format is not recommended for 'Visual Basic' users. Fields appear in the 'C' data structure in the same order in which they appear in the result table. Character types are converted to null terminated character strings padded with spaces to bring them to the length of nFieldWidth as found in the SQLCOLUMN data structure. Approximate and exact numeric types are converted to their 'double' representation. A record containing three fields: CHAR (10), INTEGER, DECIMAL(7,2) would appear as: Constants: Data Format Quasar SQL API Page 32 of 51 struct { char szField1[11]; double dField2; double dField3; } Constants: Data Format Quasar SQL API Page 33 of 51 Constants: Automatic Commit & Name Length When a query is executed via an SqlExecute call, it is not committed and will be rolled back if the user should happen to log off. mSqlFlagAutoCommitOnLogout Setting this bit of the wFlags field of the SQLCONTROL structure tells the Quasar SQL API to issue a commit command to the database administrator prior to logging the user off. This flag may be set in combination (using the '|' operator) with any one of Data Format flags. While character string fields may be quite lengthy: names of users, tables and columns are limited. mSqlMaximumNameLength This is the maximum length (not including the null terminator) of names of users, tables and columns. Constants: Automatic Commit & Name Length Quasar SQL API Page 34 of 51 Data Structures This section includes a formal description of all data structures which your program will use when it communicates with the Quasar SQL API. Typedefs for all these structures can be found in the Quasar SQL API include file for 'C'. Declarations can be found in the global file for 'Visual Basic'. SQLCOLUMN The data structure which describes a column in the result table which was generated by execution of a query SQLCONTROL The data structure which contains information needed by the Quasar SQL API to perform its functions and which passes process information back to the user SQLSTATUS The data structure with gives the user access to operational information SQLTABLE The data structure which describes the result table which was generated by execution of a query Data Structures Quasar SQL API Page 35 of 51 Data Structures: SQLCOLUMN Result Table Column Description Record The SQLCOLUMN data structure describes the characteristics of a specified column of the result table. The SQLCOLUMN data structure is loaded as a result of an SqlDescribeColumn function call. typedef struct tagSQLCOLUMN { BOOL bRightJustified; char szColumnName[mSqlMaximumNameLength+1]; unsigned nColumnSequenceNumber; unsigned nDataClass; unsigned nDataType; unsigned nFieldWidth; unsigned nPrecision; unsigned nScale; } SQLCOLUMN; typedef SQLCOLUMN *PSQLCOLUMN; typedef SQLCOLUMN far *LPSQLCOLUMN; The SQLCOLUMN data structure has the following fields: bRightJustified Indicates whether the column, by default, is left or right justified. Right justification is indicated by a a non-zero value. szColumnName Gives the column heading as a null terminated text string. nColumnSequenceNumber Column numbers range from 1 to the number of columns in the result table. nDataClass Identifies the general characteristics of a column in the result table. Its value will be set to one of the Data Class constants. nDataType Identifies the particular characteristics of a column in the result table. Its value will be set to one of the Data Type constants. nFieldWidth The number of character positions guaranteed to hold the value of this column when the record is fetched. If Data Format in the wFlags field of the lpSqlControl is mSqlFlagFormatPadded: nFieldWidth is Data Structures: SQLCOLUMN Quasar SQL API Page 36 of 51 set to the size of the column. If Data Format is mSqlFlagFormatString: nFieldWidth is set to the size of the column plus one for the terminating null. If Data Format is mSqlFlagFormatStructure and the column is numeric: nFieldWidth is set to sizeof(double), if the column is a character string type: nFieldWidth is set to the size of the column plus one for the terminating null. nPrecision If a numeric column, nPrecision is set to the precision (as defined by ANSI SQL) of the result. If a character field, nPrecision is set to the length (as defined by ANSI SQL) of the result. nScale If a numeric column, nScale is set to the scale (as defined by ANSI SQL) of the result. If a character field, nScale is 0. Data Structures: SQLCOLUMN Quasar SQL API Page 37 of 51 Data Structures: SQLCONTROL Quasar SQL API Interface Control Structure The SQLCONTROL data structure contains the specifications necessary to provide an interface between the applications programmer and the Quasar SQL API. typedef struct tagSQLCONTROL { char szErrorDetail[65]; char szErrorMessage[257]; unsigned nHiLiteLength; unsigned nHiLiteOffset; unsigned nPadding; unsigned nRecordBufferSize; unsigned nResultCode; unsigned long lRecordPosition; unsigned long lReserved0 unsigned long lReserved1 unsigned long lReserved2 unsigned long lReserved3 unsigned long lReserved4 WORD wFlags; } SQLCONTROL; typedef SQLCONTROL *PSQLCONTROL; typedef SQLCONTROL far *LPSQLCONTROL; The SQLCONTROL data structure has the following fields: szErrorDetail Each time an Quasar SQL API function is called, any errors that may occur cause this field to be loaded with a descriptive string: "Error detected at line n of module.c". This information is useful if you need to call customer service. szErrorMessage Each time an Quasar SQL API function is called, any errors that may occur cause this field to be loaded with a descriptive string: "ERROR xxx: text." This provides a useful diagnostic while you are debugging your application. "xxx" is the ASCII representation (base 10) of the nResultCode. nHiLiteLength Each time the SqlExecute is called, any syntax errors within the query cause this field to be set to the length of the offending phrase within the query text. Data Structures: SQLCONTROL Quasar SQL API Page 38 of 51 nHiLiteOffset Each time the SqlExecute is called, any syntax errors within the query cause this field to be set to the offset of the offending phrase within the query text. nPadding The caller of the Quasar SQL API sets this field to the number of padding spaces to be inserted between columns when the wFlags field of the SQLCONTROL structure is set to mSqlFlagFormatPadded. nRecordBufferSize The caller of the Quasar SQL API sets this field to the size (in bytes) of the record buffer. This buffer must be at least as large as the value in the nRecordSize field of the SQLTABLE data structure. The SQLTABLE data structure is available by calling SqlDescribeTable. nResultCode Indicates the basic status condition after any call to an Quasar SQL API function. A value of 0 indicates no error. Other values are listed under Result Codes lRecordPosition Indicates the position within the result table of the most recent record fetched. lRecordPosition can range from 1 to the number of records in the result table. If lRecordPosition is 0 then no records have been fetched. lReserved0 Do not tamper with this field. lReserved1 Do not tamper with this field. lReserved2 Do not tamper with this field. lReserved3 Do not tamper with this field. lReserved4 Do not tamper with this field. wFlags The caller of the Quasar SQL API sets this field to the desired Data Format to be utilized during record fetch functions. The data format may be optionally combined using the '|' operator with the Automatic Commit flag. Data Structures: SQLCONTROL Quasar SQL API Page 39 of 51 Data Structures: SQLSTATUS Query Status Structure The SQLSTATUS data structure describes the overall outcome of the most recent SqlExecute operation for a given cursor. typedef struct tagSQLSTATUS { unsigned long lNumberOfRecordDeletes; unsigned long lNumberOfRecordInserts; unsigned long lNumberOfRecordSelects; unsigned long lNumberOfRecordUpdates; unsigned long lTimeElapsed; } SQLSTATUS; typedef SQLSTATUS *PSQLSTATUS; typedef SQLSTATUS far *LPSQLSTATUS; The SQLSTATUS data structure has the following fields: lNumberOfRecordDeletes Indicates the total number of records deleted by the most recent SqlExecute. lNumberOfRecordInserts Indicates the total number of records inserted by the most recent SqlExecute. lNumberOfRecordSelects Indicates the total number of records selected by the most recent SqlExecute. lNumberOfRecordUpdates Indicates the total number of records updated by the most recent SqlExecute. lTimeElapsed Indicates the time elapsed (in milliseconds) during the most recent SqlExecute. Data Structures: SQLSTATUS Quasar SQL API Page 40 of 51 Data Structures: SQLTABLE Result Table Description Record The SQLTABLE data structure describes the characteristics of the result table. The SQLTABLE data structure is loaded as a result of an SqlDescribeTable function call. typedef struct tagSQLTABLE { unsigned nNumberOfColumns; unsigned nRecordSize; unsigned long lNumberOfRecords; } SQLTABLE; typedef SQLTABLE *PSQLTABLE; typedef SQLTABLE far *LPSQLTABLE; The SQLTABLE data structure has the following fields: nNumberOfColumns Indicates the number of columns in the result table. nRecordSize Indicates the minimum size (in bytes) of a buffer large enough to hold a record fetched from the result table. lNumberOfRecords Indicates the number of records in the result table. Data Structures: SQLTABLE Quasar SQL API Page 41 of 51 Result Codes This section gives an explanation of all result codes returned by the Quasar SQL API. Macro definitions for all result codes can be found in the Quasar SQL API include file for 'C'. Global Const definitions can be found in the global file for 'Visual Basic'. mSqlErrorAmbiguousColumn When a column name can be found in more than one of several tables given in the "FROM" clause of a query, the database administrator cannot determine which of them you mean. To remove the ambiguity, use the "Tablename.ColumnName" or the "UserName.Tablename.ColumnName" syntax. mSqlErrorBadEnvironment The DatabasePath entry in the "win.ini" file is not properly specified: it must begin with a drive identifier followed by a ':' and a '\'. A typical entry is "c:\database". mSqlErrorBinaryNotAllowed When creating a table, the data type BINARY was specified, the BINARY data type is not allowed in this release. mSqlErrorCannotActivateFile An attempt has been made to access a file which is unrecognized by the b-tree file manager. This is an internal error which should never occur. Please contact customer service. mSqlErrorCannotCloseFile When the b-tree file manager attempted to close either a data file or an index file, _lclose() returned an error. This usually indicates a problem with the DOS directory structure, we recommend you run 'chkdsk'. mSqlErrorCannotCloseLog When the database manager attempted to close either the 'or_log.dat' or the 'or_log.idx' transaction journal file, _lclose() returned an error. This usually indicates a problem with the DOS directory structure, we recommend you run 'chkdsk'. Result Codes Quasar SQL API Page 42 of 51 mSqlErrorCannotCreateDataFile When the b-tree file manager attempted to create a data file, _lcreat() returned an error. This usually indicates your setting for 'FILES' in the 'config.sys' file should be increased. mSqlErrorCannotCreateDumpFile When the dump manager attempted to create a dump file, _lcreat() returned an error. This usually indicates your setting for 'FILES' in the 'config.sys' file should be increased. mSqlErrorCannotCreateFile This result code will not occur. mSqlErrorCannotCreateKeyFile When the b-tree file manager attempted to create a key file, _lcreat() returned an error. This usually indicates your setting for 'FILES' in the 'config.sys' file should be increased. mSqlErrorCannotCreateLog When the database manager attempted to create either the 'or_log.dat' or the 'or_log.idx' transaction journal file, _lcreat() returned an error. This usually indicates your setting for 'FILES' in the 'config.sys' file should be increased. mSqlErrorCannotDeleteFile When the b-tree file manager attempted to remove either a data file or a key file, remove() returned an error. This usually indicates someone has modified the file's attribute settings. Please be sure none of the database files are marked as 'read only', 'hidden' or 'system'. mSqlErrorCannotDropTable When the database manager attempted to drop a table, its 'use count' was greater than zero! This is an internal error which should never occur. Please contact customer service. mSqlErrorCannotOpenDataFile When the b-tree file manager attempted to open a data file, _lopen() returned an error. This usually indicates someone has modified the file's attribute settings or deleted the file. Please be sure none of the database files Result Codes Quasar SQL API Page 43 of 51 are marked as 'read only', 'hidden' or 'system'. Also, delete files only via SQL. mSqlErrorCannotOpenFile This result code will not occur. mSqlErrorCannotOpenKeyFile When the b-tree file manager attempted to open a key file, _lopen() returned an error. This usually indicates someone has modified the file's attribute settings or deleted the file. Please be sure none of the database files are marked as 'read only', 'hidden' or 'system'. Also, delete files only via SQL. mSqlErrorCannotOpenLog When the database manager attempted to open either the 'or_log.dat' or the 'or_log.idx' transaction journal file, _lopen() returned an error. This usually indicates your setting for 'FILES' in the 'config.sys' file should be increased. mSqlErrorCannotRemoveTable When the database manager attempted to delete a file during a 'Toolbox Remove' database operation, remove() returned an error. This usually indicates someone has modified the file's attribute settings. Please be sure none of the database files are marked as 'read only', 'hidden' or 'system'. mSqlErrorCharNotAllowed When the bind manager attempted to initialize an AVG() or SUM() set function, it discovered that the argument was a CHAR or VARCHAR column! mSqlErrorCheckpointDetected This result code will not occur. mSqlErrorDataFileCorrupted The b-tree file manager encountered illegal settings in the header portions of a data file. It is likely that your DOS files are corrupted. mSqlErrorDatabaseCorrupt The database manager encountered illegal settings in the header portions of the transaction journal file. It is likely that your DOS files are corrupted. Result Codes Quasar SQL API Page 44 of 51 mSqlErrorDbaNotAvailable The Quasar SQL API could not establish communication with the Quasar Database Administrator. Is the database administrator running? mSqlErrorDivideByZero During query execution a divide by zero error occurred. mSqlErrorDuplicateColumn During query execution a column is called out more than once in a list where it can appear only once. This can only occur in the CREATE TABLE statement and the INSERT statement. mSqlErrorDuplicateRecord The b-tree file manager detected an attempt to violate an UNIQUE constraint. mSqlErrorExistingDataFile When the b-tree file manager attempted to create a data file, it discovered the file already existed! Delete files only via SQL. mSqlErrorExistingKeyFile When the b-tree file manager attempted to create a key file, it discovered the file already existed! Delete files only via SQL. mSqlErrorFileReadFailed When the b-tree file manager attempted to read a file, _lread() returned an error. mSqlErrorFileSeekFailed When the b-tree file manager attempted to seek a position in a file, _llseek() returned an error. mSqlErrorFileWriteFailed When the b-tree file manager attempted to write a file, _lwrite() returned an error. mSqlErrorGlobalLockFailed When the query manager attempted to lock a global resource, GlobalLock() or LockResource() returned an error condition. mSqlErrorGlobalUnlockFailed When the query manager attempted to unlock a global resource, GlobalUnlock() or UnlockResource() returned an error condition. mSqlErrorImportParseError This result code will not occur. mSqlErrorIncompatibleTypes An attempt was made within the query to perform an operation between Result Codes Quasar SQL API Page 45 of 51 two arguments whose types conflict. An example is adding a text string to a number. mSqlErrorIndexExists An attempt was made within the query to create an index whose name is already used. mSqlErrorIndexUndoFailed When the b-tree file manager attempted to create an unique key value a duplicate was found. The attempt to undo the creation failed. This is an internal error which should never occur. Please contact customer service. mSqlErrorInitializationFailed When the b-tree file manager attempted to initialize its tables, a failure was detected. This is an internal error which should never occur. Please contact customer service. mSqlErrorInsufficientBuffer The record to be returned to the Quasar SQL API user will not fit in the buffer allocated by the user. That is, the value of the nRecordSize field of the SQLTABLE structure is larger than that supplied by the user as indicated by the nRecordBufferSize field of the SQLCONTROL structure. Please be sure to allocate buffers large enough to accommodate nRecordSize bytes. mSqlErrorInternalError This is an internal error which should never occur. Please contact customer service. mSqlErrorInvalidColumnSpec The arguments of an SQL LIKE predicate must be of a character string type. mSqlErrorInvalidColumnType This is an internal error which should never occur. Please contact customer service. mSqlErrorInvalidCursor A call was made to the Quasar SQL API where the pCursor field of the SQLCONTROL structure is set to a value which does not match any existing cursor. Result Codes Quasar SQL API Page 46 of 51 mSqlErrorInvalidData During the execution of a CREATE TABLE query, the scale of a numeric column exceeds its precision. mSqlErrorInvalidEscapeChar The data type of the escape character in a LIKE predicate is not a character string type. mSqlErrorInvalidPattern The pattern of an SQL LIKE predicate must not be NULL. mSqlErrorInvalidUser The SqlLogin function was called with an lpstrUserName or lpstrUserPassword argument whose length exceeded mSqlMaximumNameLength. mSqlErrorKeyFileCorrupted The b-tree file manager encountered illegal settings in the header portions of a key file. It is likely that your DOS files are corrupted. mSqlErrorListSizesUnequal The number of columns in the column list of an SQL INSERT query does not match the number of values in the value list or the number of fields selected in the subquery. mSqlErrorMultipleSelects Only one SELECT statement may occur within a query. mSqlErrorNoColumnExists The bind manager encountered a column specification which it could not match to a table defined within the current scope. mSqlErrorNoIndexExists A DROP INDEX was attempted when no index exists. mSqlErrorNoOldRecord When the b-tree file manager attempted to carry out an SqlFetchNext or SqlFetchPrevious function, it discovered there was no current record. You must first execute an SqlFetchFirst, SqlFetchLast or SqlFetchPositioned. mSqlErrorNoTableExists During execution of a query a table name was encountered which cannot be found in the database under the currently logged-on user name or under the explicitly declared user name. Result Codes Quasar SQL API Page 47 of 51 mSqlErrorNoUserExists During execution of a query an user name was encountered which cannot be found in the database. mSqlErrorNodeSizeTooSmall This is an internal error which should never occur. Please contact customer service. mSqlErrorNotAggregate While the select list of a SELECT statement started with aggregate types (i.e. SUM()), a select list element was later encountered which was a simple type (i.e. a column specification). Aggregate types and simple types cannot be mixed unless the simple type is a grouping column. mSqlErrorNotGroupingColumn A regular column specification was encountered where a grouping column was required. mSqlErrorNotInGroupedTable While the select list of a SELECT statement started with simple types (i.e. a column specification), a select list element was later encountered which was an aggregate type (i.e. SUM()). Simple types and aggregate types cannot be mixed unless the simple type is a grouping column. mSqlErrorNotSingleRecord A subquery returned more than one record. When a subquery is used as an argument to a comparison predicate it must return a single record. mSqlErrorNullInNotNullCol An attempt was made to insert a NULL value in a column which was declared as NOT NULL. mSqlErrorNullNotAllowed An attempt was made to use a NULL value where NULL values are not permitted. mSqlErrorParserSyntaxError There is a syntax error in the SQL statement. mSqlErrorParserStackOverflow This is an internal error which should never occur. Please contact customer service. mSqlErrorPrecisionConflict A mathematical operation was requested which would result in loss of precision. Result Codes Quasar SQL API Page 48 of 51 mSqlErrorResultTableExists An attempt was made to commit a transaction (COMMIT WORK) while a result table was still open. Users must close all cursors which have an associated result table before committing work. mSqlErrorScaleOverflow The scale of the result of a mathematical operation overflowed. mSqlErrorSecurityViolation SqlLogin was called with an invalid lpstrUserName or lpstrUserPassword. mSqlErrorSetFunctionsNested Set functions may not be nested. mSqlErrorStarNotAllowed The SELECT * syntax is illegal when used with the GROUP BY clause. mSqlErrorSubqueryNotOneColumn When a subquery is used as an argument to a predicate it must return a single field in the select list. mSqlErrorTableConflict The target table of an INSERT, DELETE or UPDATE query may not also appear in a 'from' clause of a subquery. mSqlErrorTableExists An attempt was made in a CREATE TABLE query to create a table which already exists. mSqlErrorTooManyColumnNames The list of column names in an INSERT statement exceeds the number of columns in the table. mSqlErrorTooManyTablesOpen An attempt was made to open more tables than the maximum number of tables which may be open at one time. mSqlErrorTrialSizeExceeded The number of events recorded in the log has exceeded the trial size allotment. Further operation will irrecoverably corrupt your data. mSqlErrorUserNotLoggedIn A call was made to the Quasar SQL API where hUser does not match an existing user. mSqlErrorVariableHeaderMark The b-tree file manager encountered illegal settings in the header portions of a data file. It is likely that your DOS files are corrupted. Result Codes Quasar SQL API Page 49 of 51 mSqlErrorVariableHeaderSize The b-tree file manager attempted to place a record in a position which was not large enough. This is an internal error which should never occur. Please contact customer service. mSqlErrorVariableHeaderWrong The b-tree file manager encountered illegal settings in the header portions of a data file. It is likely that your DOS files are corrupted. mSqlErrorVariableHeaderZero The b-tree file manager encountered illegal settings in the header portions of a data file. It is likely that your DOS files are corrupted. mSqlErrorWrongVersion The b-tree file manager has determined that your data and key files are stamped with a version which is incompatible with the current release. Result Codes Quasar SQL API Page 50 of 51 Glossary This section defines specialized terms used in this document. B-tree file manager The Quasar Database Administrator is made of several large function units. One of these is the b-tree file manager. It is responsible for carrying out low level data access and operates directly on the raw DOS files located in the database directory. Bind manager The Quasar Database Administrator is made of several large function units. One of these is the bind manager. It is responsible for associating the logical constructs in the query with actual users, tables and columns in the database. Cursor The Quasar SQL API keeps track of the result of a query by means of a cursor. The cursor may include status information, the table where the result of a SELECT may be found, the column descriptions for such a table, the current record position for fetch operations, etc. Database manager The Quasar Database Administrator is made of several large function units. One of these is the database manager. It is responsible for carrying out high level data access and operates on logical tables and columns. The database manager uses the b-tree file manager to access records in the raw DOS files located in the database directory. The database manager is also responsible for policing transactions and the transaction journal (or 'log'). Dump manager The Quasar Database Administrator is made of several large function units. One of these is the dump manager. It is responsible for creating the dump file. Physical position The raw position of the record in the file. Physical order is not the same Glossary Quasar SQL API Page 51 of 51 as the order you specify with the SQL ORDER BY clause. Query By query we mean any SQL statement. Query manager The Quasar Database Administrator is made of several large function units. One of these is the query manager. It is responsible for parsing the query into its component parts. Record buffer One of the arguments to the Quasar SQL API fetch functions is a pointer to a record buffer. This is the buffer which receives the formatted contents of a record. Result table All SELECT queries generate a table containing the chosen records. This is called the result table. Its contents are made available to you one at a time through one of the Quasar SQL API fetch functions. Transaction journal A transaction journal is a pair of files ('or_log.dat' and 'or_log.idx') written by the database manager. The transaction journal contains a record for every event which caused a change to the database. Glossary