The functions in this class include wrappers to access DAOs (Data Access Objects) exposed by MFC; they are specific to the Windows™ version of Proteus. Note: the value of the predefined variable OS is 2 if the interpreter running the script is the Windows™ version; moreover, the directive WINDOWS is predefined (it is possible to conditionally execute part of the script by enclosing it between !ifdef WINDOWS and !endif).

Many functions described below require constant values for parameters, defined in the file daodefs.prt, that should be included whenever one of the functions in this class is used. In this file you will also find definitions of useful macros (e.g. DAORSEOF), which can be adopted to write scripts which are easier to understand.

The functions are divided in the following categories:

• workspace management
• database management
• recordset management
• TableDef management
• QueryDef management
• error management.

Workspace management

DAOBEGINTRANS(uDataBase)

begins a transaction on the database corresponding to the specified handle; at least one database must be opened. If the database or the recordset is closed without calling DAOCOMMITTRANS, all modifications are lost. This function returns 0 if it was possible to detect the workspace, -1 otherwise (or in case of error).

DAOCOMMITTRANS(uDataBase)

completes the current transaction; all modifications are written permanently. This function returns 0 if it was possible to detect the workspace, -1 otherwise (or in case of error).

DAOROLLBACK(uDataBase)

aborts changes submitted after the last call to DAOBEGINTRANS; all modifications are lost. This function returns 0 if it was possible to detect the workspace, -1 otherwise (or in case of error).

Database management

DAODBNEW()

creates a CDaoDatabase object and returns its handle (or -1 in case of error)

DAODBFREE(uDataBase)

destroys the CDaoDatabase object corresponding to the specified handle; uDataBase cannot be referenced anymore. This function returns -1 (invalid handle) or 0 (handle freed).

DAODBATTRIB(uDataBase, nAttribute[, exp])

returns the value of the attribute, or sets its current value (if specified). Only attributes including the word "Set" can be modified; the others are read-only. This function returns -1 in case of error.

The following values can be used for nAttribute (see daodefs.prt):

Value	Meaning
DAOATTCANTRANSACT	non-zero if transactions are supported
DAOATTCANUPDATE	non-zero if updates are possible (read/write object)
DAOATTGETCONNECT	returns the connection string used to connect the object to the database
DAOATTGETNAME	returns the name of the database in use
DAOATTGETSETQUERYTIMEOUT	returns or sets the timeout value (in seconds). All the following operations (open, add, update, execute) respect this value.
DAOATTGETRECORDSAFFECTED	returns the number of records affected by the last update or the last call to DAODBEXECUTE
DAOATTGETVERSION	returns the version of the database engine associated to the database
DAOATTISOPEN	non-zero if the object is connected to the database

DAODBCLOSE(uDataBase)

closes the connection to the database; returns -1 if uDataBase is invalid, 0 otherwise. Use the functions for error management (e.g. DAOERRCOUNT, etc.) to know if the operation was successfull.

DAODBCREATE(uDataBase, cPathName, cLocale, nOptions)

creates the database cPathName (MDB), using the settings specified by cLocale and nOptions. By default, cLocale is DAOCLangGeneral and nOptions is 0. This function returns 0 on success, -1 on error.

The following values can be used for cLocale (collating order for creating the database, see daodefs.prt):

• DAOCLangArabic
• DAOCLangCzech
• DAOCLangDutch
• DAOCLangGeneral (to be used for English, German, French, Portuguese, Italian and modern Spanish)
• DAOCLangGreek
• DAOCLangHebrew
• DAOCLangHungarian
• DAOCLangIcelandic
• DAOCLangNordic
• DAOCLangNorwDan
• DAOCLangPolish
• DAOCLangCyrillic
• DAOCLangSpanish
• DAOCLangSwedFin
• DAOCLangTurkish
• DAOCLangJapanese
• DAOCLangChineseSimplified
• DAOCLangChineseTraditional
• DAOCLangKorean
• DAOCLangThai
• DAOCLangSlovenian

The following values can be used for nOptions (sum all the required constants):

Value	Meaning
DAOCVersion10	create the database using Jet 1.0
DAOCEncrypt	save the database encrypted to disk
DAOCDecrypt	save the database not encrypted to disk
DAOCVersion11	create the database using Jet 1.1
DAOCVersion20	create the database using Jet 2.0
DAOCVersion30	create the database using Jet 3.0

DAODBCREATEREL(uDataBase, cName, cTable, cExtTable, nAttribute, cField, cExtField)

creates a relation in the specified database; returns 0 on success, -1 on error.

Parameters:

Value	Meaning
cName	name of the relation
cTable	primary table in the relation
cExtTable	external table in the relation
nAttribute	attributes of the relation
cField	name of the field in the primary table of the relation
cExtField	name of the fields in the external table of the relation

Values for nAttribute (sum all the required constants, see daodefs.prt):

Value	Meaning
DAOCRelationUnique	1 to 1 relation
DAOCRelationDontEnforce	no referential integrity
DAOCRelationInherited	relation exists in a non-concurrent database that includes both tables
DAOCRelationUpdateCascade	updates will be propagated
DAOCRelationDeleteCascade	deletions will be propagated

DAODBDELQUERYDEF(uDataBase, cName)

deletes the querydef cName. This function returns 0 on success, -1 on error.

DAODBDELREL(uDataBase, cName)

deletes the relation cName. This function returns 0 on success, -1 on error.

DAODBDELTABLE(uDataBase, cName)

deletes the table cName. This function returns 0 on success, -1 on error.

DAODBEXECUTE(uDataBase, cSqlStatement, nOptions)

runs scSqlStatement with the specified options. This function returns 0 on success, -1 on error.

Values for nOptions (sum all the required constants, see daodefs.prt):

Value	Meaning
DAOCDenyWrite	deny write to other users
DAOCInconsistent	allow inconsistent updates (default)
DAOCConsistent	force inconsistent updates
DAOCSQLPassThrough	statement is passed verbatim to ODBC data source for processing
DAOCFailOnError	roll back all updates in case of error
DAOCSeeChanges	generate error if another user is changing the same data
DAOCDenyRead	deny read to other users
DAOCReadOnly	read only
DAOCAppendOnly	can only append
DAOCForwardOnly	open in forward scrolling mode only (unsupported)
DAOCRunAsync	run in asynchronous mode
DAOCExecDirect	execute directly

DAODBGETQUERYCOUNT(uDataBase)

returns the number of queries in the database, -1 on error.

DAODBGETQUERYINFO(uDataBase, cnIndex)

returns an array containing all the properties of the query cnIndex (if cnIndex is a string, it is used as the name of the query); returns -1 on error.
The numeric values for cnIndex go from 1 to DAODBGETQUERYCOUNT(uDataBase).
The array must be freed using VECFREE, as soon as it is no longer useful.
Contents of the array (see daodefs.prt):

Constant	Value	Description
DAOQI_NAME	1	query name
DAOQI_TYPE	2	query type; one of the following values: DAOCQSelect: query select records DAOCQAction: query moves or updates records, but returns none DAOCQCrosstab: query returns records in spreadsheet format DAOCQDelete: query deletes a set of rows DAOCQUpdate: query updates a set of records DAOCQAppend: query add new records at the end of the table/query DAOCQMakeTable: query creates a new table from a recordset DAOCQDDL: query changes table structure DAOCQSQLPassThrough: statement is passed directly to the engine DAOCQSetOperation: query creates a snapshot recordset with data coming from two or more tables, removing duplicates. To include duplicates, all keyword ALL to SQL statement DAOCQSPTBulk: used with DAOCQSQLPassThrough to specify a query that does not return records
DAOQI_CDATE	3	creation date
DAOQI_CTIME	4	creation time
DAOQI_UDATE	5	last update date
DAOQI_UTIME	6	last update time
DAOQI_UPDATE	7	query is updateable (1 or 0)
DAOQI_RECORDSET	8	return records (1 or 0); only for SQL-pass through queries
DAOQI_SQL	9	SQL string; statement underlying the query
DAOQI_SOURCE	10	source info used in a pass-through query
DAOQI_TIMEOUT	11	timeout for DB engine

DAODBGETRELCOUNT(uDataBase)

returns the number of relations insisting on the database, -1 on error.

DAODBGETRELINFO(uDataBase, cnIndex)

returns an array containing all the properties of the relation cnIndex (if cnIndex is a string, it is used as the name of the relation); returns -1 on error.
The numeric values for cnIndex go from 1 to DAODBGETRELCOUNT(uDataBase).
The array must be freed using VECFREE, as soon as it is no longer useful. The user must also free the fifth item in the array, before freeing its handle, as in this example:

VH = DAODBGETRELINFO(DAOH, 1)
; Use VH..
[..]
; Free handles
VECFREE(VECGET(VH, 5))
VECFREE(VH)

Contents of the array (see daodefs.prt):

Constant	Value	Description
DAORI_NAME	1	name of the relation
DAORI_TABLE	2	name of the primary table in the relation
DAORI_EXTTABLE	3	name of the external table in the relation
DAORI_TYPE	4	type of relation, one of the following: DAOCRelationUnique: 1 to 1 relation DAOCRelationDontEnforce: no referential integrity DAOCRelationInherited: relation exists in a non-concurrent database that includes both tables DAOCRelationUpdateCascade: updates will be propagated DAOCRelationDeleteCascade: deletions will be propagated DAOCRelationLeft: relation is a left join. An external left join includes all records from the first table (left part), even though there are no corresponding records in the second table (right join) DAOCRelationRight: relation is a right join. An external right join includes all records from the second table (right part), even though there are no corresponding records in the first table (left join)
DAORI_FIELDS	5	array of field couples; every item in the array has the form "field>external_field"; it is necessary to free this array with VECFREE before freeing the array which contains it.

DAODBGETTABCOUNT(uDataBase)

returns the number of tables in the database, -1 on error.

DAODBGETTABINFO(uDataBase, cnIndex)

returns an array containing all the properties of the table cnIndex (if cnIndex is a string, it is used as the name of the table); returns -1 on error (table does not exist or invalid handle).
The numeric values for cnIndex go from 1 to DAODBGETTABCOUNT(uDataBase).
The array must be freed using VECFREE, as soon as it is no longer useful.
Contents of the array (see daodefs.prt):

Constant	Value	Description
DAOTI_NAME	1	name of the table
DAOTI_UPDATE	2	updatabale (1 or 0)
DAOTI_ATTRIB	3	attributes, combination of the following values: DAOCAttachExclusive: for tables using Jet, specify that the table is linked and open for exclusive usage DAOCAttachSavePWD: for tables using Jet, specify that User ID and password for the table are saved together with connection information DAOCSystemObject: specify that the table is of system type (read only) DAOCHiddenObject: specify that the table is hidden (for temporary usage, read only) DAOCAttachedTable: specify that the table is linked to a non-ODBC database, such as Paradox DAOCAttachedODBC: specify that the table is linked to an ODBC database, such as MS SQL Server
DAOTI_CDATE	4	creation date
DAOTI_CTIME	5	creation time
DAOTI_UDATE	6	last update (date)
DAOTI_UTIME	7	last update (time)
DAOTI_LINK	8	name of linked table, if any
DAOTI_SOURCE	9	source for opened database
DAOTI_VALIDATE	10	validation rule, used when data are updated; only for Jet
DAOTI_INVALID	11	message displayed if the validation rule is not satisfied
DAOTI_RECNUMBER	12	number of records accessed in the table

DAODBOPEN(uDataBase, cPathName, nExclusive, nReadOnly, cConnString)

establishes a connection to a database. This function returns 0 on success, -1 on error.

Parameter	Description
cPathName	name of the database, including path; if empty and cConnString is "ODBC;" a dialogue appears for selecting a database. UNC paths can also be used, e.g. "\\\\MYSERVER\\MYSHARE\\MYDIR\\MYDB.MDB" (the double backslash is necessary because "\" is the escape character)
nExclusive	0 if the database is shared, non-zero for exclusive access
nReadOnly	0 for reading/writing, non-zero for read-only
cConnString	if an MDB file is being opened, specify the path in cPathName and leave this string empty (or specify the password using ";PWD=password"); if an ODBC data source is being opened, leave cPathName empty and specify the DSN in cConnString

Recordset management

DAORSNEW(uDataBase)

creates a CDaoRecordset object from the database handle uDataBase. This function returns the handle of the new recordset on success, -1 on error.

DAORSFREE(zHandle)

destroys the object CDaoRecordset; zHandle cannot be referenced anymore. This functions returns 0 on success, -1 on error.

DAORSATTRIB(zHandle, cAttribute[, exp])

returns the value of the requested attribute; only the attributes followed by "*" require the parameter exp (note that "*" is not to be specified). This function returns -1 on error.

Values for cAttribute (see daodefs.prt):

Parameter	Description
DAORSATTCANAPPEND	returns not-zero if records can be appended
DAORSATTCANBOOKMARK	returns not-zero if recordset supports bookmark
DAORSATTCANRESTART	returns not-zero if query can be repeated
DAORSATTCANSCROLL	returns not-zero if it is possible to move between records
DAORSATTCANTRANSACT	returns not-zero if the data source supports transactions
DAORSATTCANUPDATE	returns not-zero if the recordset can be updated
DAORSATTGETDATECREATED	returns creation date for the base table in the recordset
DAORSATTGETTIMECREATED	returns creation time for the base table in the recordset
DAORSATTGETDATELASTUPDATED	returns last update date for the base table in the recordset
DAORSATTGETTIMELASTUPDATED	return last update time for the base table in the recordset
DAORSATTGETNAME	returns the name of the recordset
DAORSATTGETSQL	returns SQL string used to calculate recordset
DAORSATTGETVALIDATIONRULE	returns validation string for data introduced in the record
DAORSATTGETVALIDATIONTEXT	returns message displayed when validation fails
DAORSATTGETEDITMODE	return editing mode for current record
DAORSATTGETCURRENTINDEX	returns the name of the current index in a table-type recordset
DAORSATTGETRECORDCOUNT	returns number of records accessed in a recordset
DAORSATTISBOF	returns not-zero if the recordset was positioned before the first record; no current record exists
DAORSATTISDELETED	returns not-zero if the recordset is positioned on a deleted record
DAORSATTISEOF	returns not-zero if the recordset was positioned after the last record; no current record exists
DAORSATTISOPEN	returns not-zero if the recordset is open
DAORSATTGETTYPE	returns recordset type: table, dynaset, snapshot
DAORSATTGETLASTMODBMARK	returns a bookmark handle for the most recently added or modified record; the bookmark must be freed by calling DAORSFREEBMARK
DAORSATTSETCURRENTINDEX*	sets index to be used in a table-type recordset
DAORSATTGETPARAMVALUE*	returns the value of the specified parameter (if numeric, consider the position; if string, consider the name)
DAORSATTSETPARAMVALUENULL*	sets current value for the specified parameter to Null (no value)

DAORSPARCOUNT(zHandle)

returns the number of parameters in the query used to build the recordset, -1 on error.

DAORSPARSET(zHandle, cnParameter, exp[, nType])

sets the value of the specifed parameter to exp; cnParameter can be a number (index in the list) or a string (parameter name).
The numeric values for cnParameter go from 1 to DAORSPARCOUNT(zHandle). This function returns -1 on error, 0 on success.
The optional parameter nType specifies how exp is to be interpreted; if omitted, the type is determined according to the last assignment.
The allowed values are (see daodefs.prt):

Constant	Description
DAOCBoolean	the integer value is interpreted as True (not zero) or False (zero)
DAOCByte	the integer value is interpreted as a byte (it the variable is a string, uses the first character)
DAOCInteger	integer value
DAOCLong	long integer value
DAOCCurrency	integer or floating point, according to the value
DAOCSingle	floating point, single precision
DAOCDouble	floating point, double precision
DAOCDate	the string is interpreted as a date
DAOCDateTime	the string is interpreted as date + time (the two values are separated by a space)
DAOCTime	the string is interpreted as a time
DAOCText	string
DAOCMemo	string
DAOCLongBinary	string
DAOCNull	ignore value and set to NULL

DAORSOPEN(zHandle, nOpenType, cSqlStatement, nOptions)

opens the recordset, by using cSqlStatement and the options specified. This function returns 0 on success, -1 on error.

The possible values for the parameters are specified in the following table (see daodefs.prt):

Parameter	Description
nOpenType	can be one of the following values: DAOCOpenTable: table type with bidirectional scrolling DAOCOpenDynaset: dynaset type with bidirectional scrolling. This is the default DAOCOpenSnapshot: snapshot type with bidirectional scrolling DAOCOpenForwardOnly: forward-only type (unsupported) DAOCOpenDynamic: dynamic type
cSqlStatement	is a string which can include: the name of one or more tables/queries, separated by commas; a SQL SELECT expression (including WHERE and ORDER BY clauses, if necessary); a pass-through query.
nOptions	can be a combination of the following values (default is 0): DAOCAppendOnly: can only append records (only for dynaset records) DAOCForwardOnly: the recordset is a snapshot which can only scroll forward DAOCSeeChanges: generate error if another user is changing the same data DAOCDenyWrite: deny write to other users DAOCDenyRead: deny read to other users (only for table type recordsets) DAOCReadOnly: records can only be read, not modified DAOCInconsistent: allow inconsistent updates (default, only for dynasets) DAOCConsistent: force consistent updates (only for dynasets)

DAORSOPENTD(zHandle, nOpenType, tHandle, nOptions)

opens the recordset, by using the table handle tHandle and the options specified. This function returns 0 on success, -1 on error. The possible values for the parameters are explained in the following table (see daodefs.prt):

Parameter	Description
nOpenType	can be one of the following values: DAOCOpenTable: table type with bidirectional scrolling DAOCOpenDynaset: dynaset type with bidirectional scrolling. This is the default DAOCOpenSnapshot: snapshot type with bidirectional scrolling DAOCOpenForwardOnly: forward-only type (unsupported) DAOCOpenDynamic: dynamic type
tHandle	handle to the TableDef
nOptions	can be a combination of the following values (default is 0): DAOCAppendOnly: can only append records (only for dynaset records) DAOCForwardOnly: the recordset is a snapshot which can only scroll forward DAOCSeeChanges: generate error if another user is changing the same data DAOCDenyWrite: deny write to other users DAOCDenyRead: deny read to other users (only for table type recordsets) DAOCReadOnly: records can only be read, not modified DAOCInconsistent: allow inconsistent updates (default, only for dynasets) DAOCConsistent: force consistent updates (only for dynasets)

DAORSOPENQD(zHandle, nOpenType, qHandle, nOptions)

opens the recordset, by running the query qHandle using the options specified. This function returns 0 on success, -1 on error. The possible values for the parameters are explained in the following table (see daodefs.prt):

Parameter	Description
nOpenType	can be one of the following values: DAOCOpenTable: table type with bidirectional scrolling DAOCOpenDynaset: dynaset type with bidirectional scrolling. This is the default DAOCOpenSnapshot: snapshot type with bidirectional scrolling DAOCOpenForwardOnly: forward-only type (unsupported) DAOCOpenDynamic: dynamic type
qHandle	handle to the QueryDef
nOptions	can be a combination of the following values (default is 0): DAOCAppendOnly: can only append records (only for dynaset records) DAOCForwardOnly: the recordset is a snapshot which can only scroll forward DAOCSeeChanges: generate error if another user is changing the same data DAOCDenyWrite: deny write to other users DAOCDenyRead: deny read to other users (only for table type recordsets) DAOCReadOnly: records can only be read, not modified DAOCInconsistent: allow inconsistent updates (default, only for dynasets) DAOCConsistent: force consistent updates (only for dynasets)

DAORSCLOSE(zHandle)

closes the recordset previously opened; use DAORSFREE to destroy the CDaoRecordset object. This function returns 0 on success, -1 on error.

DAORSADDNEW(zHandle)

prepares for adding a new record; use DAORSUPDATE to write the record, after setting the various fields to the required values. This function returns 0 on success, -1 on error.

DAORSEDIT(zHandle)

prepares for modifying the current record; use DAORSUPDATE to write the record, after changing the various fields to the required values. This function returns 0 on success, -1 on error.

DAORSUPDATE(zHandle)

writes the new/updated record. This function returns 0 on success, -1 on error.

DAORSCANCELUPD(zHandle)

aborts changes to the record (DAORSEDIT or DAORSADDNEW). This function returns 0 on success, -1 on error.

DAORSDELETE(zHandle)

deletes the current record; it is necessary to explicitly move the pointer to the next record. This function returns 0 on success, -1 on error.

DAORSFINDFIRST(zHandle, cCondition)

finds the first record meeting the specified condition; returns 1 if found, 0 otherwise (in this case, there is no current record). This function returns -1 on error. Use DAORSSEEK for table type recordsets, because this function is slower (records are evaluated one after the other). It is not possible to do a search on forward-only table type recordset. When searching dates, specify the values in american format: month/day/year and enclose the string between "#".

DAORSFINDNEXT(zHandle, cCondition)

finds the next record meeting the specified condition. This function returns 1 if found, 0 if not found (in this case, there is no current record), -1 on error. See also DAORSFINDFIRST.

DAORSFINDPREV(zHandle, cCondition)

finds the previous record meeting the specified condition. This function returns 1 if found, 0 if not found (in this case, there is no current record), -1 on error. See also DAORSFINDFIRST.

DAORSFINDLAST(zHandle, cCondition)

finds the last record meeting the specified condition. This function returns 1 if found, 0 if not found (in this case, there is no current record), -1 on error. See also DAORSFINDFIRST. The completion of this call could take a lot of time, because the recordset is completely populated before returning.

DAORSGETPERCPOS(zHandle)

returns the current position in the database, expressed as a percentage between 0 and 100. In dynaset or snapshot recordsets, the percentage is calculated on the number of records accessed before the call. It is not possible to call this function on forward-only snapshots or on pass-through queries on external databases. This function returns -1 on error.

DAORSSETPERCPOS(zHandle, fPercentage)

moves the pointer to the position approximately corresponding to the specified percentage (0-100). Use DAORSGETPERCPOS to get the current position as a percentage. Keep in mind that this function always refers to the number of records accessed before the calling, not to the whole recordset. This function returns 0 on success, -1 on error.

DAORSGETABSPOS(zHandle)

returns the absolute position of the current record. This function returns -1 if there is no current record, otherwise a value between 0 and n-1, if n is the total number of records in the recordset. This function can be used only on dynasets or snapshots.

DAORSSETABSPOS(zHandle, nPosition)

moves the pointer to nPosition (between 1 and n, if n is the number of records already accessed). Only for dynasets or snapshots. This function returns 0 on success, -1 on error.

DAORSGETBMARK(zHandle)

returns a bookmark handle for the current record, -1 if there is no current record. Use DAORSSETBMARK later to return to the same record. 
Use DAORSFREEBMARK to free the bookmark.

DAORSSETBMARK(zHandle, gHandle)

moves the pointer to the bookmark corresponding to gHandle. Use DAORSFREEBMARK to delete the bookmark. This function returns 0 on success, -1 on error.

DAORSFREEBMARK(zHandle, gHandle)

deletes the bookmark corresponding to gHandle. This function returns 0 on success, -1 on error.

DAORSMOVE(zHandle, nOffset)

moves forward or backward by nOffset records; this function returns 1 on success, 0 if the pointer could not be moved the number of records specified, -1 on error. See also DAORSMOVEFIRST.

DAORSMOVEFIRST(zHandle)

moves the pointer to the first record in the recordset; returns 1 if found, 0 otherwise (in this case, there is no current record). The return value is -1 on error. It is not possible to move the pointer on forward-only snapshots. An error happens if the recordset is empty; test the conditions DAORSBOF and DAORSEOF before calling the function. If a record is being changed, the modifications are lost.

DAORSMOVENEXT(zHandle)

moves the pointer to the following record; returns 1 if found, 0 otherwise (in this case, there is no current record). The return value is -1 on error. See also DAORSMOVEFIRST.

DAORSMOVEPREV(zHandle)

moves the pointer to the previous record; returns 1 if found, 0 otherwise (in this case, there is no current record). The return value is -1 on error. See also DAORSMOVEFIRST.

DAORSMOVELAST(zHandle)

moves the pointer to the last record; returns 1 if found, 0 otherwise (in this case, there is no current record). The return value is -1 on error. See also DAORSMOVEFIRST. The call to this function could take a lot of time, because the recordset is completely populated.

DAORSSEEK(zHandle, cOperator, exp1[, exp2..])

seeks the specified values in the recordset. The current index is set by calling DAORSATTRIB(zHandle, DAORSATTSETCURRENTINDEX, cnIndex). Only for table-type recordsets. This function returns 1 if a record was found, 0 otherwise (in this case, there is no current record). The return value is -1 on error.

Parameters:

• cOperator: is one of the following strings: "<", "<=", "=",  ">=", ">"
• exp1..expn: values of keys in the index; if the index is based on more than one keys, it is possible to specify more than one values

DAORSFILLCACHE(zHandle, nSize[, gHandle])

fills the cache with nSize records, starting from bookmark gHandle (optional). Filling the cache speeds up the operations on the recordsets based on ODBC data sources. The records modified concurrently by other users are not updated in the cache. Cache size is determined using DAORSSETCACHESIZE. This function returns 0 on success, -1 on error.

DAORSGETCACHESIZE(zHandle)

returns the number of records allowed in the cache, -1 on error.

DAORSSETCACHESIZE(zHandle, nSize)

sets the cache size for the recordset. This is useful only for recordset from ODBC data sources. Set nSize to 0 to avoid using the cache. To completely update the cache, call this function with nSize = 0 and then repeat the call with the requested cache size. This function returns 0 on success, -1 on error.

DAORSGETCACHESTART(zHandle)

returns the bookmark handle for the record from which the cache is populated, -1 on error. Only for dynasets. Use DAORSFREEBMARK to delete the bookmark.

DAORSSETCACHESTART(zHandle, gHandle)

sets the bookmark handle for the record from which the cache is populated. Only for dynasets. Use this function to avoid specifying the third parameter in the call to DAORSFILLCACHE. This function returns 0 on success, -1 on error.

DAORSGETFIELDCOUNT(zHandle)

returns the number of fields in the recordset, -1 on error.

DAORSGETFIELDINFO(zHandle, cnIndex)

returns an array containing information about the field cnIndex, -1 if the field does not exist or the handle is invalid. The array must be freed using VECFREE as soon as it is no longer useful. The values for cnIndex (if numeric) go from 1 to DAORSGETFIELDCOUNT(zHandle); cnIndex can be a number or a string (specifying the name of the field).

Contents of the array (see daodefs.prt):

Constant	Value	Description
DAOFI_NAME	1	field name
DAOFI_TYPE	2	field type; can be one of the following: DAOCBoolean DAOCByte DAOCInteger DAOCLong DAOCCurrency DAOCSingle DAOCDouble DAOCDate DAOCText DAOCLongBinary DAOCMemo DAOCGUID DAOCBinary DAOCBigInt DAOCVarBinary DAOCChar DAOCNumeric DAOCDecimal DAOCFloat DAOCTime DAOCTimeStamp
DAOFI_SIZE	3	maximum size, in bytes, for the original DAO field; Proteus converts all values to strings or integer/floating point numbers, so this information is not useful. Date/time is converted to date + time, separated by a blank.
DAOFI_ATTRIB	4	attributes; sum of the following constants: DAOCFixedField: fixed length field (default for numeric fields) DAOCVariableField: variable length field (only for text fields) DAOCAutoIncrField: the value for the new records is automatically increased to a new long value that can not be modified; supported only for Microsoft® Jet tables DAOCUpdatableField: field value can be updated DAOCDescending: field is sorted in decreasing order (Z-A or 100-0); applies only to index fields
DAOFI_POSITION	5	ordinal position; this represents the order of the field with respect to others
DAOFI_REQUIRED	6	required (1/0); if 0, the field can be Null
DAOFI_ALLOWZL	7	allow zero length (1/0); if 0, empty string is not allowed
DAOFI_COLLATE	8	collating order; see DAODBCREATE
DAOFI_EXTNAME	9	external name; name of the field in the external table corresponding to this field
DAOFI_EXTFIELD	10	source field; original field name in the data source
DAOFI_EXTTABLE	11	source table; original table name in the data source
DAOFI_VALIDATE	12	validation rule; describes the condition for accepting updates
DAOFI_INVALID	13	validation text; text displayed if validation fails
DAOFI_DEFAULT	14	default value; value taken by new records, if the user does not specify a value for the field

DAORSGETINDEXCOUNT(zHandle)

returns the number of indexes available in a table-type recordset, -1 on error.

DAORSGETINDEXINFO(zHandle, cnIndex)

returns an array containing information about the index cnIndex,  -1 if the index does not exist; cnIndex can be a number or a string (index name). The values for cnIndex (if numeric) go from 1 to DAORSGETINDEXCOUNT(zHandle). The array must be freed using VECFREE as soon as it is no longer useful, after having freed its second item, as in this example:

VH = DAORSGETINDEXINFO(RSH, 1)
; Use the array VH..
[..]
; Free the arrays
VECFREE(VECGET(RSH, 2))
VECFREE(RSH)

Contents of the array (see daodefs.prt):
 

Constant	Value	Description
DAOII_NAME	1	index name
DAOII_FIELDS	2	field array; every item begins with 0 (ascending) or 1 (descending), followed by field name
DAOII_PRIMARY	3	primary (1 or 0); a primary index includes fields that, taken together, are a primary key. There can be at most one primary index in a table
DAOII_UNIQUE	4	unique (1 or 0); a unique index includes fields that, considered together, are unique for each record
DAOII_CLUSTERED	5	clustered (1 or 0); with a clustered index, data in the table are stored in the order specified by the index. A clustered index represents an efficient way to access data in the required order (not supported by Microsoft® Jet databases)
DAOII_NULLIGNORE	6	ignore Null (1 or 0); if 1, the records having Null as a key (according to this index) are not considered; this reduces the space needed to store the index
DAOII_REQUIRED	7	required (1 or 0); if true (1), records having Null as a key are not allowed
DAOII_EXTERN	8	external (1 or 0); if true (1), the index is an external key in a table; used for referential integrity
DAOII_KEYS	9	number of distinct keys in the index for the corresponding table

DAORSGETLOCKMODE(zHandle)

returns locking mode for updates: optimistic (0) or pessimistic (1). This function returns -1 on error. In pessimistic mode, the page including the record is locked during all the update (from DAORSEDIT to DAORSUPDATE); in optimistic mode, only when changes are committed.

DAORSSETLOCKMODE(zHandle, nPessimistic)

sets locking mode for updates according to the parameter nPessimistic: optimistic (0) or pessimistic (1). This function returns -1 on error. In pessimistic mode, the page including the record is locked during all the update (from DAORSEDIT to DAORSUPDATE); in optimistic mode, only when changes are committed.

DAORSREQUERY(zHandle)

repeats the query underlying the recordset, to update its contents reflecting the modifications that occurred in the meanwhile. This function return 0 on success, -1 on error.

DAORSGETFIELDVAL(zHandle, cnIndex)

returns the value of the field cnIndex (if cnIndex is a string, it is used as the name of the field); returns an empty string on error (field does not exist or invalid handle). Proteus converts any type to string or integer/floating point number. The values allowed for the numeric parameter go from 1 to DAORSGETFIELDCOUNT(zHandle).

DAORSSETFIELDVAL(zHandle, cnIndex, exp)

sets the value of the field cnIndex; cnIndex can be a number or a string specifying the name of the field. This function returns 0 on success, -1 on error. The values allowed for the numeric parameter go from 1 to DAORSGETFIELDCOUNT(zHandle).

DAORSSETFIELDNULL(zHandle, cnIndex)

sets the value of the field cnIndex to Null; cnIndex can be a number or a string specifying the name of the field. This function returns 0 on success, -1 on error. The values allowed for the numeric parameter go from 1 to DAORSGETFIELDCOUNT(zHandle).

TableDef management

DAOTDCREATE(uDatabase, cName, nAttributes, cSourceTable, cConnect)

creates a TableDef and returns its handle; this function returns -1 on error; the parameters are explained in the following table (see daodefs.prt):

Parameter	Description
uDatabase	handle for the database where the tabledef will be created
cName	name of the table to be created
nAttributes	NOR of the following values: DAOCAttachExclusive: for tables using Jet, specify that the table is linked and open for exclusive usage DAOCAttachSavePWD: for tables using Jet, specify that User ID and password for the table are saved together with connection information DAOCSystemObject: specify that the table is of system type (read only) DAOCHiddenObject: specify that the table is hidden (for temporary usage, read only)
cSourceTable	name of a table to be copied (ignored if empty)
cConnect	default connection string (ignored if empty)

DAOTDAPPEND(tHandle)

saves the TableDef in the database. This function returns 0 on success, -1 on error.

DAOTDOPEN(uDatabase, cTableName)

opens the TableDef corresponding to cTableName in the database uDatabase. This function returns the handle to the TableDef opened, -1 on error.

DAOTDCLOSE(tHandle)

closes the TableDef. This function returns 0 on success, -1 on error.

DAOTDATTRIB(tHandle, nAttribute[, exp])

returns or sets the value for the specified attribute. Only attributes including the word "Set" can be modified; the others are read-only. The following values can be used for nAttribute (see daodefs.prt):

Value	Description
DAOTDCANUPDATE	returns not-zero if the table can be updated (it is possible to modify field definitions or table properties)
DAOTDATTRIBUTES	returns table attributes
DAOTDCONNECT	returns a value that gives information about table source
DAOTDCREATDATE	returns creation date for the table
DAOTDCREATTIME	returns creation time for the table
DAOTDLASTUPDATE	returns last update date
DAOTDLASTUPDTIME	returns last update time
DAOTDNUMFIELDS	returns number of fields in the table
DAOTDFIELDINFO	returns information about field exp (if numeric, consider position; if string, consider name); returns an array with 14 elements, see DAORSGETFIELDINFO
DAOTDINDEXCOUNT	returns number of indexes
DAOTDINDEXINFO	returns information about index exp (if numeric, consider position; if string, consider name); returns an array with 9 elements, see DAORSGETINDEXINFO
DAOTDNAME	returns table name
DAOTDRECCOUNT	returns number of records accessed in the table
DAOTDSOURCE	returns the name of the source table
DAOTDVALRULE	returns validation rule
DAOTDVALTEXT	returns text displayed when validation fails
DAOTDISOPEN	returns non-zero if the table is open
DAOTDSETATTR	sets to exp the value of table attributes
DAOTDSETCONN	sets to exp the value of connection string
DAOTDSETNAME	sets to exp the name of the table
DAOTDSETSOURCE	sets to exp the name of the source table
DAOTDSETVALRULE	sets to exp the validation rule
DAOTDSETVALTEXT	sets to exp the text displayed when validation fails

This function returns 0 on success, -1 (SET) or an empty string on error.

DAOTDCREATFIELD(tHandle, cName, nType, nSize, nAttributes)

creates a field in the table, with the specified name, type, size and attributes. This function returns 0 on success, -1 on error. The possible values for parameters are:

Parameter	Description
nType	seei DAOFI_TYPE in DAORSGETFIELDINFO
nSize	size in bytes
nAttributes	NOR of the following values: DAOCFixedField: fixed length field (default for numeric fields) DAOCVariableField: variable length field (only for text fields) DAOCAutoIncrField: the value for the new records is automatically increased to a new long value that can not be modified; supported only for Microsoft® Jet tables DAOCUpdatableField: field value can be updated DAOCDescending: field is sorted in decreasing order (Z-A or 100-0); applies only to index fields

DAOTDEXTCREATFIELD(tHandle, nFieldVec)

creates a field, using the array of 14 items nFieldVec (see DAORSGETFIELDINFO). This function returns 0 on success, -1 on error.

DAOTDCREATEINDEX(tHandle, nIndexVec)

creates an index, using the array of 9 items nIndexVec (see DAORSGETINDEXINFO). This function returns 0 on success, -1 on error.

DAOTDDELFIELD(tHandle, cnField)

deletes the field cnField; cnField can be a number or a string specifying the name of the field. This function returns 0 on success, -1 on error.

DAOTDDELINDEX(tHandle, cnIndex)

deletes the index cnIndex; cnIndex can be a number or a string specifying the name of the index. This function returns 0 on success, -1 on error.

DAOTDREFRESHLINK(tHandle)

updates connection information for the linked table. This function returns 0 on success, -1 on error. 

QueryDef management

DAOQDCREATE(uDatabase, cQueryName, cSQL)

creates a QueryDef, returning its handle; this function returns -1 on error; the parameters are explained below:

Parameter	Description
cQueryName	name of the querydef to be created (temporary, if empty)
cSQL	SQL string defining the query (if empty, it must be set subsequently by using DAOQDSETSQL in DAOQDATTRIB).

DAOQDAPPEND(qHandle)

saves the QueryDef in the database. This function returns 0 on success, -1 on error. 

DAOQDOPEN(uDatabase, cQueryName)

opens the QueryDef corresponding to cQueryName from the database uDatabase. This function returns the handle of the opened querydef, -1 on error.

DAOQDCLOSE(qHandle)

closes the QueryDef. This function returns 0 on success, -1 on error. 

DAOQDATTRIB(qHandle, nAttribute[, exp])

returns the value of the specified attribute, or sets its current value (if specified). Only attributes including the word "Set" can be modified; the others are read-only. The following values are allowed (see daodefs.prt):

nAttribute	Description
DAOQDCANUPDATE	returns non-zero if the query can update the database
DAOQDCONNECT	returns the connection string connected to the QueryDef
DAOQDCREATDATE	returns the creation date for QueryDef
DAOQDCREATTIME	returns the creation time for QueryDef
DAOQDLASTUPDATE	returns last update date
DAOQDLASTUPDTIME	returns last update time
DAOQDNAME	returns the name of the QueryDef
DAOQDODBCTOUT	returns the timeout used by ODBCS when the query is run
DAOQDRECAFFECT	returns number of records influenced by the query
DAOQDRETURNREC	returns non-zero if the query returns records
DAOQDSQL	returns the SQL string that defines the query
DAOQDTYPE	returns query type: delete, update, append, create table, etc.
DAOQDISOPEN	returns non-zero if the query is open
DAOQDSETCONN	sets connection string for a SQL pass-through query over an open ODBC data source
DAOQDSETNAME	sets the name of the saved query, replacing the name assigned when it was created
DAOQDSETODBCTO	sets the timeout value used by ODBC when the query will be run
DAOQDSETRETREC	specifies if the query returns records; valid only for SQL pass-through queries
DAOQDSETSQL	sets the SQL string that defines the query

Returns 0 on success, -1 on error (SET); returns an empty string on error.

DAOQDEXECUTE(qHandle, nOptions)

opens the query qHandle, according to nOptions; does not work with queries returning records. The possible values for nOptions, which can be combined by using NOR, are the following (see daodefs.prt):

Constant	Description
DAOCDenyWrite	deny write to other users
DAOCInconsistent	allow inconsistent updates (default)
DAOCConsistent	force consistent updates
DAOCSQLPassThrough	statement is passed verbatim to ODBC data source for processing
DAOCFailOnError	roll back all updates in case of error
DAOCSeeChanges	generate error if another user is changing the same data

This function returns 0 on success, -1 on error.

DAOQDFIELDCOUNT(qHandle)

returns the number of fields defined in the query, -1 on error.

DAOQDGETFIELDINFO(qHandle, cnIndex)

returns an array containing information about the field cnIndex, -1 if it does not exist or the specified handle is invalid. The array must be freed using VECFREE as soon as it is no longer useful. The numeric values allowed for cnIndex go from 1 to DAOQDFIELDCOUNT(qHandle); cnIndex can be a number or a string specifying the name of the field. See DAORSGETFIELDINFO for information about the contents of the array.

DAOQDPARAMCOUNT(qHandle)

returns the number of parameters defined in the query, -1 on error.

DAOQDPARAMINFO(qHandle, cnIndex)

returns an array of three items, containing information about parameter cnIndex, -1 if it does not exist or the specified handle is invalid. The array must be freed using VECFREE as soon as it is no longer useful. The numeric values for cnIndex go from 1 to DAOQDPARAMCOUNT(qHandle); cnIndex can be a number or a string specifying the name of the parameter. The items returned are the following (see daodefs.prt):

Constant	Description
DAOQDPNAME	parameter name
DAOQDPTYPE	parameter type
DAOQDPVALUE	parameter value

DAOQDGETPARVALUE(qHandle, cnIndex)

returns the value for the parameter cnIndex in the query qHandle. The numeric values for cnIndex go from 1 to DAOQDPARAMCOUNT(qHandle); cnIndex can be a number or a string specifying the name of the parameter. This function returns an empty string on error.

DAOQDSETPARVALUE(qHandle, cnIndex, exp)

sets the value for the parameter cnIndex in the query qHandle. The numeric values for cnIndex go from 1 to DAOQDPARAMCOUNT(qHandle); cnIndex can be a number or a string specifying the name of the parameter. This function returns 0 on success, -1 on error.

Error management

DAOERRCOUNT(uDataBase)

returns the number of errors in the collection Errors from the database engine (corresponding to CDaoException.GetErrorcount), -1 on error.
After each DAO call, it is advisable to verify that the number of errors returned by this function is 0; if it is not, you can use the following functions to learn what produced the error. In any case, the number of errors is reset to 0 before each DAO call.

DAOGETERRORNUM(uDataBase, nIndex)

returns the error nIndex, -1 on error. The values admitted go from 1 to DAOERRCOUNT(uDataBase).

DAOGETERRORDESC(uDataBase, nIndex)

returns a string containing the description for the error nIndex, an empty string on error. The values admitted go from 1 to DAOERRCOUNT(uDataBase).

DAOGETERRORSRC(uDataBase, nIndex)

returns a string containing the source for the error nIndex, an empty string on error. The values admitted go from 1 to DAOERRCOUNT(uDataBase).