Library functions: DAO functions

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

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):

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:

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).

Start of page Next topic Previous topic Contents Index
Midnight Lake iPhone Case Black Women Shoes Black Flat Shoes Leather Flats Black Patent Ballerinas Black Ballet Shoes Casual Shoes Black Shoes Women Balle Record Player Cufflinks Best iPhone XR Clear Cases iPhone XS/XS Max Leather Cases Sale Best iPhone 8/8 Plus Silicone Cases iPhone 7/7 Plus Cases & Screen Protector New Cases For iPhone 6/6 Plus iPhone 8 Case Sale iPhone Xr Case Online iPhone 7 Case UK Online iPhone X Case UK Sale iPhone X Case Deals iPhone Xs Case New Case For iPhone Xr UK Online Case For iPhone 8 UK Outlet Fashion Silver Cufflinks For Men Best Mens Cufflinks Outlet Online The Gold Cufflinks Shop Online Cheap Shirt Cufflinks On Sale Nice Wedding Cufflinks UK Online Top Black Cufflinks UK Online Mens Cufflinks Online Silver Cufflinks For Men Men Cufflinks UK Sale Gold Cufflinks UK Online Gold Cufflinks UK Silver Cufflinks UK Shirt Cufflinks Discount Online Mens Cufflinks Deals & Sales Girls Shoes For Dance Fashion Ballet Dance Shoes Best Ballet Flats Shoes UK Online Cheap Ballet Pointe Shoes UK Online Best Ballet Shoes Outlet Best Dance Shoes Sale Cheap Ballet Flats Sale UK Best Pointe Shoes Online UK Ballet Dance Shoes UK Shoes For Dance UK Best Ballet Slippers Shop Best Yoga Shoes Hotsell