This chapter describes each method of the ActiveX access method. The methods are presented in alphabetical order.

VAccess, VACombo, VAList, VACommand, VAHScroll, VAVScroll, VAList, VAOption, VAText

Displays copyright and version information about the ActiveX controls.

VACombo, VAList

Adds an item to a VAList or VACombo control operating in field-bound mode.

The AddItem method syntax has these parts:

If you supply a valid value for index, item is placed at that position within the object. If index is omitted, item is added at the proper sorted position (if the Sorted property is set to True) or to the end of the list (if Sorted is set to False).

A VAList or VACombo control that is operating in record list mode (VARecordList property is set to True) does not support the AddItem method.

VAccess

Performs a PSQL operation on the file associated with the VAccess control and returns the status of the operation.

The syntax for this method has the following parts:

Any PSQL function that can be performed by the VAccess control can be used by means of the Btrv method. The method takes a single parameter, the OpCode. OpCode constant declarations are included in the files GLOBAL.BAS (for Visual Basic),, GLOBAL.PAS (for Delphi), and GLOBAL.H (for Visual C++). Include one of these files (whichever is appropriate for your development environment) in your project to use the OpCode constants in your application.

Possible opcode settings are:

You may lock records in PSQL by adding a lock bias to the operation code. With Btrv, you may specify a lock on any Get or Step operation. Use the Unlock method to remove locks. The lock biases are shown in the following table.

VAccess, VACombo, VAList

Clears the contents of a VAList or VACombo, clears the contents of the data buffer and index buffer of a VAccess control.

The syntax for this method has the following parts:

A VAList or VACombo control that is operating in record list mode (VARecordList property is set to True) does not support the Clear method.

VAccess

Closes the file associated with the control and returns the status of the close operation.

The syntax for this method has the following parts:

This method attempts to close the file associated with object, and returns the PSQL status code from the operation. A return value of zero indicates success.

VAccess

Adds Indexes to the DDF file and to the corresponding PSQL file. Returns 0 if successful or PSQL status code if an error occurred.

object.DdfAddIndex indexList

The DdfAddIndex method syntax has these parts:

DdfAddIndex returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfAddIndex will add the index(es) in indexList to the actual data file itself. In addition, this function will add the index(es) in indexList to the metadata memory image of the VAccess control. If RefreshLocations is True, DdfAddIndex will then update the DDF files themselves to match the current memory image. If DdfTransactionMode is True, these actions will be performed inside a transaction.

IndexList, RefreshLocations, DdfTransactionMode, DdfDropIndex

VAccess

Adds the current table defined by the values of the TableName, Location, FieldList and IndexList to the current DDF.

object.DdfAddTable bOverwrite

The DdfAddTable method syntax has these parts:

DdfAddTable returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfAddTable writes the information in the current memory image of the VAccess control to the DDF file itself. If bOverwrite is True, the control will overwrite an existing table with the same name. Otherwise, this method will fail if a table with the same name is found to exist in the current DDF (as specified by the DdfPath property).

This function does not manipulate the VAccess memory image of the metadata or the data file itself in any way. To create a new, blank table in the VAccess memory image of the metadata, use the DdfAddTableName method. Use the DdfCreateTable method to create a new table in the DDF and corresponding empty data file in the location specified.

Unlike many of the other dictionary methods and properties, DdfAddTable does not check RefreshLocations. Since its only purpose is to write DDF information, it assumes that it should write directly to the DDF. This behavior means that you do not have to switch RefreshLocations if you plan to use the VAccess memory image to store DDF changes and write them to the DDF in one pass (see PSQL Programmer's Guide).

If DdfTransactionMode is True, the DDF writing will be performed inside a transaction.

DdfAddTableName, DdfCreateTable, DdfTransactionMode

VAccess

Adds a new table to the current VAccess control memory image, and initializes the associated Location, FieldList, and IndexList so that a new table definition can be added to the dictionary.

object. DdfAddTableName tableName

The DdfAddTableName method syntax has these parts:

DdfAddTableName returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfAddTableName is the first step in defining a new table’s metadata. It affects only the VAccess control’s memory image, and therefore is unaffected by the current value of RefreshLocations or DdfTransactionMode.

DdfAddTable, DdfModifyTableName

VAccess

Clears the field information in the VAccess memory image (and optionally in the DDF) for the current table.

object. DdfClearFields

The DdfClearFields method syntax has this part:

DdfClearFields returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfClearFields always destroys the current field information in the VAccess memory image. If RefreshLocations is True, it will also delete all field information for the current table in FIELD.DDF. A by-product of this will be that INDEX.DDF will no longer be able to get correct field information, so for practical purposes, all of the metadata for the table will be destroyed if this occurs. It is highly recommended that RefreshLocations be set to False before invoking this method.

FieldList, RefreshLocations, DdfTransactionMode

VAccess

Clears the index information in the VAccess memory image (and optionally in the DDF) for the current table.

object. DdfClearIndexes

The DdfClearIndexes method syntax has these parts:

DdfClearIndexes returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfClearIndexes always destroys the current index information in the VAccess memory image. If RefreshLocations is True, it will also delete all index information for the current table in INDEX.DDF. It is highly recommended that RefreshLocations be set to False before invoking this method.

DdfClearIndexes, IndexList, RefreshLocations, DdfTransactionMode

VAccess

Creates a new, empty set of DDF files in the location specified by the DdfPath property. It creates this data dictionary without tables, indexes, or fields for your data. You must add these, using DdfCreateTable, DdfAddTableName, DdfAddTable, and DdfAddIndex.

object. DdfCreateDictionary bOverwrite

The DdfCreateDictionary method syntax has these parts:

DdfCreateDictionary returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfCreateDictionary creates FILE.DDF, FIELD.DDF, and INDEX.DDF system files, populates them with self-referential system table definition records, and also creates FIELDEXT.DDF and COMMENT.DDF extended dictionary files.

If a dictionary currently exists in the specified DdfPath, the control will check bOverwrite to determine if it should delete the current dictionary and rewrite it. If bOverwrite is True, the existing dictionary will be irreversibly destroyed.

DdfPath, DdfTransactionMode

VAccess

Adds a table definition to the dictionary and creates an empty data file using the path and file information specified in the Location property and the attributes defined by FieldList and IndexList.

object. DdfCreateTable bOverwrite

The DdfCreateTable method syntax has these parts:

DdfCreateTable returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

This method first calls DdfAddTable to add the table definition to the dictionary. If this call fails for any reason, i.e. the table definition already exists and overwrite is False, DdfCreateTable will also fail. If DdfAddTable succeeds, this method will attempt to create a new, empty data file using Location. The bOverwrite parameter also controls whether or not an existing data file at the same Location will be overwritten.

Unlike many of the other dictionary methods and properties, DdfCreateTable does not check RefreshLocations. Since it does not affect the VAccess memory image, it assumes that it should write directly to the DDF. This behavior means that you do not have to switch RefreshLocations if you plan to use the VAccess memory image to store DDF changes, write them to the DDF, and create the table in one pass (see PSQL Programmer's Guide).

DdfAddTable

VAccess

Removes an index from the current PSQL data file, and, if RefreshLocations is True, also from the data dictionary definition for the current table.

object. DdfDropIndex keynum

The DdfDropIndex method syntax has these parts:

DdfDropIndex returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfDropIndex will drop the specified index from the actual data file itself. In addition, this function will remove the index from the metadata memory image of the VAccess control. If RefreshLocations is True, DdfDropIndex will then update the DDF files themselves to match the current memory image. If DdfTransactionMode is True, these actions will be performed inside a transaction.

As a result of dropping an index other than the last index in the file, all indexes will be renumbered. For example, if the third key of a table with five indexes is dropped, key #3 will be moved to key #2 and key #4 will become key #3. DdfDropIndexMaintain can be used to drop an index without disrupting other keys of the table.

IndexList, RefreshLocations , DdfAddIndex, DdfDropIndexMaintain

VAccess

Removes an index from the current PSQL data file. If RefreshLocations is True, it removes it from the data dictionary definition for the current table without re-ordering the existing indexes.

object. DdfDropIndexMaintain keynum

The DdfDropIndexMaintain method syntax has these parts:

DdfDropIndexMaintain returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfDropIndexMaintain will drop the specified index from the actual data file itself. In addition, this function will remove the index from the metadata memory image of the VAccess control. If RefreshLocations is True, DdfDropIndex will then update the DDF files themselves to match the current memory image. If DdfTransactionMode is True, these actions will be performed inside a transaction.

Unlike DdfDropIndex, DdfDropIndexMaintain will not change the ordinal values of any other existing keys. Only applications which might use the dropped key will be adversely affected.

DdfDropIndexMaintain can be very dangerous if used incorrectly, since it alters the index structure of the data file itself. Existing programs which use the data file may no longer work after this operation is performed. Use with extreme caution.

IndexList, RefreshLocations , DdfAddIndex, DdfDropIndex

VAccess

Drops the current table from the data dictionary as specified by TableName.

object. DdfDropTable

The DdfDropTable method syntax has these parts:

DdfDropTable returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfDropTable removes all references to the current table from the current data dictionary. It does not affect the data file in any way.

Unlike many of the other dictionary methods and properties, DdfDropTable does not check RefreshLocations. Since its only purpose is to delete DDF information, it assumes that it should write directly to the DDF.

DdfAddTable, DdfAddTableName, TableName

VAccess

Reads field comments into the VAccess memory image from the COMMENT.DDF file.

object.DdfGetFieldComments

The DdfGetFieldComments method syntax has these parts:

DdfGetFieldComments returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfGetFieldComments forces a refresh of the field comment information in the VAccess memory image. This will very rarely be needed, as any memory image update from the DDF will automatically refresh this information as well. It would only be needed when RefreshLocations has been set to false and the DDF information has been persisted; comment information is not persisted with other DDF information.

Unlike many of the other dictionary methods and properties, DdfGetFieldComments does not check RefreshLocations. Since its only purpose is to update information from the DDF, it assumes that it should read directly from the DDF.

FieldList

VAccess

Changes the table location of the current table and optionally writes the new location to the DDF.

object. DdfModifyLocation newLocation

The DdfModifyLocation method syntax has these parts:

DdfModifyLocation returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

If RefreshLocations is True, the new table location also is updated in the FILE.DDF record of the data dictionary. If False, the change is made only to the VAccess memory image. It could be changed later with DdfAddTable.

This method also causes the value of the Location property of the control to change to reflect the new location.

Because DdfModifyLocation automatically changes the Location property, if DdfKeyUseIndexDDFOnly is set to False, it clears the contents of the current IndexList and replaces it from the index information of the new location (or clears the contents if the file does not yet exist). When you are creating a new file, set the IndexList property after calling DdfModifyLocation rather than before this method is invoked.

Location, RefreshLocations, DdfAddTable, DdfModifyTableName

VAccess

Changes the name of the current table and optionally writes the new name to the DDF.

object. DdfModifyTableName newName

The DdfModifyTableName method syntax has these parts:

DdfModifyTableName returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

DdfModifyTableName will not change the current table, and will fail if a table already exists with the requested name. The TableName property can be used to change the current table. DdfAddTableName can be used to add a new, blank table to the current list of tables.

If RefreshLocations is True, the new table name is also updated in the FILE.DDF record of the data dictionary. If False, the change will only be made to the VAccess memory image. It could be changed later with DdfAddTable.

This method will also cause the value of the TableName property of the control to change to reflect the new name.

RefreshLocations, TableName, DdfAddTable, DdfAddTableName, DdfModifyLocation

VAccess

Can be used to set the Btrieve owner name for the dictionary files to something other than the default owner name and security level (allow read-only access). Owner name and security level parameters follow Btrieve conventions.

The syntax for this method has the following parts:

The following Security Level codes may be passed to DdfSetOwner in the SecurityLevel parameter:

Constant declarations are included in the files GLOBAL.BAS (for 16 bit Visual Basic), GLOBAL.BAS (for Visual Basic), GLOBAL.PAS (for Delphi), and GLOBAL.H (for Visual C++). Include one of these files (whichever is appropriate for your development environment) in your project to use the Security Level constants in your application.

VAccess

Sets the owner name used for opening dictionary files and determines whether or not a dictionary can be successfully opened and updated using the given owner name.

object. DdfTestOwnerName ownerName

The DdfTestOwnerName method syntax has these parts:

DdfTestOwnerName returns a two-byte integer that holds the status of the VAccess control. If this is zero, the dictionaries can be opened and updated with the current dictionary owner name.

The default dictionary owner name used by the VAccess control will usually open DDF files to reads and updates. However, some dictionary files may have an owner name other than the default. In this case, you may use DdfTestOwnerName to set the dictionary owner name and test it against the current dictionary as specified by DdfPath.

DdfTestOwnerName first tries to open the dictionary. If it is successful, it attempts to update the first record to see whether the owner name allows updates or only allows read attempts. The returned status will indicate whether the owner name can open the file, modify the file, or neither.

DdfSetOwnerName

VAccess

Deletes the current record and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to delete the current record from the file associated with object, and returns the PSQL status code from the operation. A return value of zero indicates success.

VAccess

Returns the value of a field in the current record formatted using the specified format string.

The syntax for this method has the following parts:

If a field is formatted, the value for the contents of that field will always be returned as a String, regardless of data type (the container may automatically translate this to a String, Variant, AnsiString, or other variety of character data). If a field is not formatted, the value will be returned as the Variant that most closely approximates the data type of the field. Most control containers can manipulate, internationalize, and re-format this returned variant much more easily and quickly than a String. For this reason, we recommend that unformatted fields be retrieved whenever possible.

FieldValue, RowColumnValue, Column

VAccess

Attempts to retrieve a record using its physical position in the file and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve a record by physical position from the file associated with object, and returns the PSQL status code from the operation. A return value of zero indicates success.

VAccess

Attempts to retrieve a record by an exact match to the current index and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

Attempts to retrieve the first record in the file which contains a value in the currently selected index field or fields which exactly matches the value specified for the field or fields prior to the operation.

Before invoking this method, set the value of the field or fields which make up the index specified by the IndexNumber property. If the key fields are bound to VA field controls, their value will be set by modifying the contents of the bound controls.

To set these values from code, use the FieldValue property. The status code for the operation will be returned by the method and also set in the Status property of the control, a value of zero indicating success.

For the operation to succeed, all bytes of all fields in all segments of the key must be equivalent. A Status Code 4 indicates that the value set in the key field(s) prior to the operation was not found in the current index path. A string key with an alternate collating sequence will return a record if the key value, when translated through the alternate collating sequence, has a byte-for-byte equivalent in the file. This is also true of case-insensitive string keys.

VAccess

Attempts to retrieve the first record in the current index path and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the first record in the currently selected index path, set through the IndexNumber property, from the file associated with object. The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A status of 9 indicates that there are no records in the current index path.

In Visual Basic, a GetFirst is required to populate a listbox or combo box.

VAccess

Attempts to retrieve the first record that is the greater than the key in the current index path and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the first record which contains a value in the currently selected index field(s) which is greater than the value specified for the field(s) prior to the operation, from the file associated with the control. Before executing this operation, you must set the value of the field or fields which make up the index specified in the IndexNumber property.

If the key fields are bound to field controls, their value will be set by modifying the contents of the bound controls. To set these values from code, use the FieldValue property.

The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A Status Code 9 indicates that no records in the file have a key value greater than that specified prior to the operation.

VAccess

Attempts to retrieve the first record that is greater than or equal to the key in the current index path and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the first record which contains a value in the currently selected key field(s) which is greater than or equal to the value specified for the field(s) prior to the operation, from the file associated with the control.

Before invoking this method, set the value of the field or fields which make up the index specified in the IndexNumber property.

If the key fields are bound to field controls, their value will be set by modifying the contents of the bound controls. To set these values from code, use the FieldValue property.

The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A Status Code 9 indicates that no records in the file have a key value greater than or equal to that specified prior to the operation.

VAccess

Attempts to retrieve the last record in the current index path and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the last record in the currently selected index path, set through the IndexNumber property, from the file associated with object. The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A Status Code 9 indicates that there are no records in the current index path.

VAccess

Attempts to retrieve the last record in the current index path containing a value less than the value specified for the key fields, and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the last record which contains a value in the currently selected key field(s) which is less than the value specified for the field(s) prior to the operation, from the file associated with the control.

Before invoking this method, set the value of the field or fields which make up the index specified in the IndexNumber property. If the key fields are bound to field controls, their value will be set by modifying the contents of the bound controls. To set these values from code, use the FieldValue property.

The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A Status Code 9 indicates that no records in the file have a key value less than that specified prior to the operation.

VAccess

Attempts to retrieve the last record in the current index path containing a value less than or equal to the value specified for the key fields, and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the last record which contains a value in the currently selected key field(s) which is less than or equal to the value specified for the field(s) prior to the operation, from the file associated with the control.

Before invoking this method, set the value of the field or fields which make up the index specified in the IndexNumber property. If the key fields are bound to field controls, their value will be set by modifying the contents of the bound controls. To set these values from code, use the FieldValue property.

The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A Status Code 9 indicates that no records in the file have a key value less than or equal to that specified prior to the operation.

VAccess

Attempts to retrieve the next record in the current index path and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the next record in the currently selected index path, set through the IndexNumber property, from the file associated with the control.

Before invoking this method, you must have established current positioning in the index path.

The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A Status Code 9 indicates that there is no record following the current record in the current index path. A Status Code 8 indicates that positioning was not established on a current record prior to invoking the method.

VAccess

Attempts to retrieve the next records in the current index path as an extended fetch record set, and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method has no effect if the ExtendedOps property of the control is False or AutoMode is set to True.

This method performs a PSQL Get Next Extended operation, using the current record and index selections in the control to establish positioning, and using the selection criteria contained in the SelectedRecords and SelectedFields properties.

If the IncludeCurrent property of the control is True, the extended fetch operation will begin with the current record. If this property is False, the extended fetch operation will begin with the next record in the record sequence. The Init method automatically sets the IncludeCurrent property True. The GetNextExtended method sets the IncludeCurrent property False after the method is invoked.

If the operation is successful, the resulting record set values will be available through the Row and Column properties. The number of rows and columns returned by the operation are available in the Rows and Columns properties, and the PSQL status code is returned by the method and is available in the Status property. A non-zero status code does not necessarily indicate that no records were returned—check the value of the Rows property to determine the number of rows returned.

Before invoking this method, you must first configure the control for extended fetch operations by setting the desired record selection and field selection criteria in the SelectedRecords and SelectedFields properties, and then invoking the Init method to allocate the necessary request buffer structures. You can also optimize the extended fetch operation by first establishing current record positioning in the index path using an indexed record fetch method such as GetFirst or GetGreaterOrEqual.

The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.

VAccess

Attempts to retrieve the previous record in the current index path and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the previous record in the currently selected index path, set through the IndexNumber property, from the file associated with the control.

Before invoking this method, you must have established current positioning in the index path.

The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A Status Code 9 indicates that there is no record following the current record in the current index path. A Status Code 8 indicates that positioning was not established on a current record prior to invoking the method.

VAccess

Attempts to retrieve the previous records in the current index path as an extended fetch record set, and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method performs a PSQL Get Previous Extended operation, using the current record and index selections in the control to establish positioning, and using the selection criteria contained in the SelectedRecords and SelectedFields properties.

If the IncludeCurrent property of the control is True, the extended fetch operation will begin with the current record. If this property is False, the extended fetch operation will begin with the next record in the record sequence.

If the operation is successful, the resulting record set values will be available through the Row and Column properties. The number of Rows and Columns returned by the operation are available in the Rows and Columns properties, and the PSQL status code is returned by the method and is available in the Status property.

Before invoking this method, you must first configure the control for extended fetch operations by setting the desired record selection and field selection criteria in the SelectedRecords and SelectedFields properties, and then invoking the Init method to allocate the necessary request buffer structures. You can also optimize the extended fetch operation by first establishing current record positioning in the index path using an indexed record fetch method such as GetLast or GetLessOrEqual.

This method has no effect if the ExtendedOps property of the control is False or if AutoMode is set to True.

VAccess

Returns the list of tables defined in the current dictionary as a two-dimensional variant array.

object. GetTableList

The syntax for this method has the following parts:

GetTableList returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

The FieldList property accepts and returns a variant encapsulating a two-dimensional variant array. The first subscript references the field ordinal, and the second references one property of the field. The properties referenced by the second subscript are:

If the RefreshLocations property is False, the last table list cached in memory is returned. If RefreshLocations is True, the current table list will be re-read from the dictionary. This method only allows read operations and not updates as opposed to FieldList and IndexList.

FieldList, IndexList, RefreshLocations

VAccess

Returns the total number of segments contained in the specified index of the file associated with the VAccess control.

GetTotalSegments has been maintained for backwards compatibility. Index properties can usually be more quickly and easily manipulated using the IndexList property.

The GetTotalSegments method syntax has these parts:

VAccess

Forces an initialization of the structures used in performing PSQL extended fetch record set operations based on the parameters supplied in the CacheRows, CacheRejectMax, SelectedFields, and SelectedRecords properties.

Init must be performed prior to making extended operations calls upon initialization and whenever SelectedRecords, SelectedFields, CacheRows, or CacheRejectMax are changed.

The syntax for this method has the following parts:

If the AutoMode is set to True, setting the Init property will also perform the initial extended record set fetch operation (GetNextExtended), which requires logical currency. You may establish logical currency by invoking any of the indexed record operations such as GetFirst, GetEqual, and so on.

The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.

VAccess

Attempts to insert the current data buffer as a new record and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to insert the current data buffer as a new record in the file associated with object, and returns the PSQL status code from the operation. A return value of zero indicates success. A return value of 5 indicates that the record could not be inserted because a field or fields in the data buffer used in a key or keys defined for the file which do not allow duplicate values, contain values of another record already in the file.

If you want to perform a no-currency-change operation, use the KeyNumber property.

VAccess

Attempts to open the file associated with the control and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to open the file associated with object. If the file is already open, it is closed before it is opened again. The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success.

VAccess, VACombo, VAList

Forces an immediate update of the associated object.

VACombo, VAList

Removes an item from a VAList or VACombo control operating in field-bound mode.

The RemoveItem method syntax has these parts:

A VAList or VACombo control that is operating in record list mode (VARecordList property is set to True) does not support the RemoveItem method.

VAccess

Returns a field value from a specified Row and Column in an extended fetch record set.

The syntax for this method has the following parts:

Use this method as a shortcut to using the Row and Column properties to retrieve field data from an extended fetch record set.

The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.

VAccess

Sets the file flag specified before creating a Btrieve file with the Create method.

The syntax for this method has the following parts:

Constant declarations are included in the files GLOBAL.BAS (for Visual Basic), GLOBAL.PAS (for Delphi), and GLOBAL.H (for Visual C++). Include one of these files (whichever is appropriate for your development environment) in your project to use the file flag constants in your application.

VAccess

The SetOwner method is used to specify an owner name for a PSQL table to restrict access to the table.

The syntax for this method has the following parts:

The following Security Level codes may be passed to SetOwner in the SecurityLevel parameter:

Constant declarations are included in the files GLOBAL.BAS (for 16 bit Visual Basic), GLOBAL.BAS (for Visual Basic), GLOBAL.PAS (for Delphi), and GLOBAL.H (for Visual C++). Include one of these files (whichever is appropriate for your development environment) in your project to use the Security Level constants in your application.

To remove the owner name from a PSQL table, first open the table with the owner name, then issue a BTO_ClearOwner operation to the Btrv method.

This value will not affect the owner name used to access dictionary files. Use DdfSetOwner to change the owner name of a set of dictionary files.

OwnerName, DdfSetOwner, DdfTestOwnerName

VAccess

Invoking this method will display the Extended Query Field Selection dialog box, allowing the user to change the SelectedFields property at run time.

The syntax for this method has the following parts:

You must invoke the Init method after any changes to the extended fetch record or field selection criteria before invoking an extended fetch method such as GetNextExtended.

The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.

VAccess

Invoking this method will display the Extended Query Record Selection dialog box, allowing the user to change the SelectedRecords property at run time.

The ShowSelectedRecordsDlg method syntax has these parts:

You must invoke the Init method after any changes to the extended fetch record or field selection criteria before invoking an extended fetch method such as GetNextExtended.

The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.

VAccess

Forces a refresh of the status buffer from the current table.

object.Stat

The Stat method syntax has these parts:

Stat returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.

Stat will force an update of the status buffer, which will update the file parameters such as PageSize, TotalKeys, PercentFreeSpace, PreallocatedPages, ReservedDupPointers, ACSName, CollatingSequence, FileVersion, and the file flags. Stat will also update the index information from the status buffer if DdfKeyUseIndexDDFOnly if set to False. A Stat call is not needed prior to getting the TotalRecords property; TotalRecords performs a Stat call when requested.

VAccess

Invoking this method will display a task-modal message box at run time if set to a non-zero number. Common PSQL status codes are explained, less common or unrecognized status codes are simply reported.

The syntax for this method has the following parts:

VAccess

Attempts to retrieve the first record in physical record storage order and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the first record in physical record storage order from the file associated with object. The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A status of 9 indicates that there are no records in the file.

VAccess

Attempts to retrieve the last record in physical record storage order and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the last record in physical record storage order from the file associated with object. The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A status of 9 indicates that there are no records in the file.

VAccess

Attempts to retrieve the next record in physical record storage order and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the next record in physical record storage order from the file associated with object. The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A return value of 9 indicates end of file has been reached. A return value of 8 indicates that no current record positioning was established before the method was invoked.

VAccess

Attempts to retrieve the next records from the file in physical record storage order as an extended fetch record set, and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method performs a PSQL Step Next Extended operation, using the current record to establish initial positioning, and using the selection criteria contained in the SelectedRecords and SelectedFields properties.

If the IncludeCurrent property of the control is True, the extended fetch operation will begin with the current record. If this property is False, the extended fetch operation will begin with the next record in the record sequence.

If the operation is successful, the resulting record set values will be available through the Row and Column properties. The number of Rows and Columns returned by the operation are available in the Rows and Columns properties, and the PSQL status is returned by the method and is available in the Status property.

Before invoking this method, you must first configure the control for extended fetch operations by setting the desired record selection and field selection criteria in the SelectedRecords and SelectedFields properties, and then invoking the Init method to allocate the necessary request buffer structures. You can also first establish current record positioning in the file using a single record fetch method such as StepFirst.

This method has no effect if the ExtendedOps property of the control is False or AutoMode is set to True.

VAccess

Attempts to retrieve the previous record in physical record storage order and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to retrieve the previous record in physical record storage order from the file associated with object. The status code for the operation will be returned by the method and set in the Status property of the control, a value of zero indicating success. A return value of 9 indicates that beginning of file has been reached. A return value of 8 indicates that no current record positioning was established before the method was invoked.

VAccess

Attempts to retrieve the previous records from the file in physical record storage order as an extended fetch record set, and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method performs a PSQL Step Previous Extended operation, using the current record to establish initial positioning, and using the selection criteria contained in the SelectedRecords and SelectedFields properties.

If the IncludeCurrent property of the control is True, the extended fetch operation will begin with the current record. If this property is False, the extended fetch operation will begin with the next record in the record sequence.

If the operation is successful, the resulting record set values will be available through the Row and Column properties. The number of Rows and Columns returned by the operation are available in the Rows and Columns properties, and the PSQL status is returned by the method and is available in the Status property.

Before invoking this method, you must first configure the control for extended fetch operations by setting the desired record selection and field selection criteria in the SelectedRecords and SelectedFields properties, and then invoking the Init method to allocate the necessary request buffer structures. You can also first establish current record positioning in the file using a single record fetch method such as StepLast.

This method has no effect if the ExtendedOps property of the control is False or AutoMode is set to True.

VAccess

The Transaction function controls PSQL transaction processing within an application. It may be used to begin, end, or abort a PSQL transaction.

The syntax for this method has the following parts:

Transaction processing is a data integrity feature of the PSQL record manager. Its purpose is to insure that, in a set of related updates to different tables, either all of the updates succeed, or all of them are rolled back so that relational integrity is maintained.

The following operations are supported by the Transaction method. Any operation codes not listed here will return a Status Code 1, invalid operation.

Constant declarations are included in the files GLOBAL.BAS (for 16 bit Visual Basic), GLOBAL.BAS (for Visual Basic), GLOBAL.PAS (for Delphi), and GLOBAL.H (for Visual C++). Include one of these files (whichever is appropriate for your development environment) in your project to use the Transaction constants in your application.

Example

VAccess

Unlocks single and multiple record locks placed on records in a PSQL table by lock bias codes added to Get or Step operation codes passed to the Btrv method.

The syntax for this method has the following parts:

The following lock type codes may be passed to the Unlock method.

Constant declarations are included in the files GLOBAL.BAS (for 16 bit Visual Basic), GLOBAL.BAS (for Visual Basic), GLOBAL.PAS (for Delphi), and GLOBAL.H (for Visual C++). Include one of these files (whichever is appropriate for your development environment) in your project to use the Unlock constants in your application.

VAccess

Attempts to update the current record with the contents of the current data buffer, and returns, as an Integer value, the PSQL status code.

The syntax for this method has the following parts:

This method attempts to update the current record with the contents of the current data buffer in the file associated with object, and returns the PSQL status code from the operation. A return value of zero indicates success.

A return value of 5 indicates that the record could not be updated because a field or fields in the data buffer used in a key or keys defined for the file which do not allow duplicate values, contain values of another record already in the file. A return value of 80 indicates that a conflict has occurred, i.e. that the record has been updated by another process between the time it was read and the time the Update method was invoked.

If you want to perform a no-currency-change operation, use the KeyNumber property.