ActiveX Method Reference
 
ActiveX Method Reference
This chapter describes each method of the ActiveX access method. The methods are presented in alphabetical order.
AboutBox
Applies to
VAccess, VACombo, VAList, VACommand, VAHScroll, VAVScroll, VAList, VAOption, VAText
Description
Displays copyright and version information about the ActiveX controls.
AddItem
Applies to
VACombo, VAList
Description
Adds an item to a VAList or VACombo control operating in field-bound mode.
Syntax
object.AddItem item, index
The AddItem method syntax has these parts:
 
Part
Description
object
Required. An object expression that evaluates to an object in the Applies To list.
item
Required. String expression specifying the item to add to the object.
index
Optional. Integer specifying the position within the object where the new item is placed. For the first item in a VAList or VACombo control, index is 0.
Remarks
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.
Example
Private Sub Command1_Click()
VAList1.AddItem (Text2.Text)
End Sub
Btrv
Applies to
VAccess
Description
Performs a PSQL operation on the file associated with the VAccess control and returns the status of the operation.
Syntax
object.Btrv opcode
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
opcode
Required. Specifies the PSQL operation to be performed.
Remarks
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:
 
Code
Global Constant
Description
0
BTO_Open
Open the PSQL table specified as the TableName of the VAccess control.
1
BTO_Close
Close the PSQL table.
2
BTO_Insert
Insert the current record in the memory into the PSQL table.
3
BTO_Update
Update the current record in the PSQL table with the data contained current record in memory.
4
BTO_Delete
Delete the current record from the file.
5
BTO_GetEqual
Retrieves the first record with an index value equal to the FieldValue specified.
6
BTO_GetNext
Retrieves the next record in the current index path.
7
BTO_GetPrevious
Retrieves the previous record in the current index path.
8
BTO_GetGreater
Retrieves the record with an index value that is greater than that of the FieldValue specified.
9
BTO_GetGreaterOrEqual
Retrieves the record with an index value that is greater than or equal to that of the FieldValue specified.
10
BTO_GetLess
Retrieves the record with an index value that is less than that of the FieldValue specified.
11
BTO_GetLessOrEqual
Retrieves the record with an index value that is less than or equal to that of the FieldValue specified.
12
BTO_GetFirst
Retrieves the first record in the current index path.
13
BTO_GetLast
Retrieves the last record in the current index path.
22
BTO_GetPosition
Places the physical position of the current record within the PSQL file into the Position property of the VAccess control.
23
BTO_GetDirect
Retrieves the record specified in the Position property of the VAccess control.
24
BTO_StepNext
Retrieves a record from the VAccess from the location physically following the current record.
30
BTO_ClearOwner
Clears the current Owner Name security for the file. Note: the file must first be opened with the existing owner name.
33
BTO_StepFirst
Retrieves the record in the first physical location of the file.
34
BTO_StepLast
Retrieves the record in the last physical location of the file.
35
BTO_StepPrevious
Retrieves a record from the VAccess from the location physically preceding the current record.
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.
Lock Bias
Global Constant
Description
200
BTO_SingleNoWait
Single Record No-Wait Lock. When the record is already locked, PSQL will return Status Code 84, Record In Use error to the application.
400
BTO_MultiNoWait
Multiple Record No-Wait Lock. When the record is already locked, PSQL will return a Status Code 84, Record In Use error to the application.
Example
If Check1.Value = 1 Then
stat = VAccess1.Btrv(5) 'GetEqual
Else
stat = VAccess1.Btrv(9) 'GetGreaterOrEqual
End If
Clear
Applies to
VAccess, VACombo, VAList
Description
Clears the contents of a VAList or VACombo, clears the contents of the data buffer and index buffer of a VAccess control.
Syntax
object.Clear
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
A VAList or VACombo control that is operating in record list mode (VARecordList property is set to True) does not support the Clear method.
Example
'Clear the data buffer and all bound controls
VAccess1.Clear
Close
Applies to
VAccess
Description
Closes the file associated with the control and returns the status of the close operation.
Syntax
object.Close
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example
If index > -1 Then 'selected from list
VAccess1.Close
VAccess1.FileName = Combo1.List(index)
VAccess1.Open
End If
DdfAddIndex
Applies to
VAccess
Description
Adds Indexes to the DDF file and to the corresponding PSQL file. Returns 0 if successful or PSQL status code if an error occurred.
Syntax
object.DdfAddIndex indexList
The DdfAddIndex method syntax has these parts:
 
 
Part
Description
object
Required. The name of a valid VAccess control.
indexList
Required. A two-dimensional array of index information as described in the reference for IndexList.
Return Value
DdfAddIndex returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
Note DdfAddIndex alters the index structure of the data file itself. Use with caution.
See Also
IndexList, RefreshLocations, DdfTransactionMode, DdfDropIndex
DdfAddTable
Applies to
VAccess
Description
Adds the current table defined by the values of the TableName, Location, FieldList and IndexList to the current DDF.
Syntax
object.DdfAddTable bOverwrite
The DdfAddTable method syntax has these parts:
 
 
Part
Description
object
Required. The name of a valid VAccess control.
bOverwrite
Required. Boolean specifying whether the VAccess control should overwrite an existing table definition if one exists.
Return Value
DdfAddTable returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
Example
'assume that fields, indexes, tableName and location 'are already set
VAEngine.FieldList = fields
VAEngine.IndexList = indexes
VAEngine.fileName = tableName
VAEngine.location = location
status = VAEngine.DDFAddTable(True)
See Also
DdfAddTableName, DdfCreateTable, DdfTransactionMode
DdfAddTableName
Applies to
VAccess
Description
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.
Syntax
object. DdfAddTableName tableName
The DdfAddTableName method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
tableName
Required. The name of the new table in the VAccess memory image. This cannot be the name of an existing table or the method will fail.
Return Value
DdfAddTableName returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
Example
VAEngine.RefreshLocations = False
VAEngine.DdfAddTableName tableName
VAEngine.DdfModifyLocation dataLocation
'set the Fields and indexes
VAEngine.FieldList = myFieldsVariant
VAEngine.IndexList = myIndexVariant
'write changes to DDF – do not need to
'reset RefreshLocations
VAEngine.DdfAddTable(True)
See Also
DdfAddTable, DdfModifyTableName
DdfClearFields
Applies to
VAccess
Description
Clears the field information in the VAccess memory image (and optionally in the DDF) for the current table.
Syntax
object. DdfClearFields
The DdfClearFields method syntax has this part:
 
Part
Description
object
Required. The name of a valid VAccess control.
Return Value
DdfClearFields returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
See Also
FieldList, RefreshLocations, DdfTransactionMode
DdfClearIndexes
Applies to
VAccess
Description
Clears the index information in the VAccess memory image (and optionally in the DDF) for the current table.
Syntax
object. DdfClearIndexes
The DdfClearIndexes method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
Return Value
DdfClearIndexes returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
See Also
DdfClearIndexes, IndexList, RefreshLocations, DdfTransactionMode
DdfCreateDictionary
Applies to
VAccess
Description
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.
Syntax
object. DdfCreateDictionary bOverwrite
The DdfCreateDictionary method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
bOverwrite
Required. Boolean specifying whether the VAccess control should overwrite an existing dictionary if one exists.
Return Value
DdfCreateDictionary returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
See Also
DdfPath, DdfTransactionMode
DdfCreateTable
Applies to
VAccess
Description
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.
Syntax
object. DdfCreateTable bOverwrite
The DdfCreateTable method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
bOverwrite
Required. Boolean specifying whether the VAccess control should overwrite an existing table definition and table if one exists.
Return Value
DdfCreateTable returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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).
Example
'assume that fields, indexes, tableName and 'location are already set
VAEngine.RefreshLocations = False
VAEngine.FieldList = fields
VAEngine.IndexList = indexes
VAEngine.TableName = tableName
VAEngine.Location = location
status = VAEngine.DDFCreateTable(True)
See Also
DdfAddTable
DdfDropIndex
Applies to
VAccess
Description
Removes an index from the current PSQL data file, and, if RefreshLocations is True, also from the data dictionary definition for the current table.
Note DdfDropIndex 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.
Syntax
object. DdfDropIndex keynum
The DdfDropIndex method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
keynum
Required. Integer representing the ordinal number of the key to be dropped from the file.
Return Value
DdfDropIndex returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
Example
'kill all existing applications that use indexes
For i = 0 To VAEngine.TotalKeys – 1
'TotalKeys will be decremented each pass,
'so always kill key 0
status = VANew.DdfDropIndex(0)
If status > 0 Then
errorMsg = "Error occurred during Drop " _
+ "Index " + CStr(i) + _
" operation. Btrieve status " + _
CStr(status) + ". "
MsgBox errorMsg, vbExclamation
End If
Next i
See Also
IndexList, RefreshLocations , DdfAddIndex, DdfDropIndexMaintain
DdfDropIndexMaintain
Applies to
VAccess
Description
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.
Syntax
object. DdfDropIndexMaintain keynum
The DdfDropIndexMaintain method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
keynum
Required. Integer representing the ordinal number of the key to be dropped from the file.
Return Value
DdfDropIndexMaintain returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
Example
'kill only applications that use index #1
status = VANew.DdfDropIndexMaintain(1)
If status > 0 Then
errorMsg = "Error occurred during Drop Index " + _
CStr(i) + " operation. Btrieve status " + _
CStr(status) + ". "
MsgBox errorMsg, vbExclamation
End If
See Also
IndexList, RefreshLocations , DdfAddIndex, DdfDropIndex
DdfDropTable
Applies to
VAccess
Description
Drops the current table from the data dictionary as specified by TableName.
Syntax
object. DdfDropTable
The DdfDropTable method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
Return Value
DdfDropTable returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
See Also
DdfAddTable, DdfAddTableName, TableName
DdfGetFieldComments
Applies to
VAccess
Description
Reads field comments into the VAccess memory image from the COMMENT.DDF file.
Syntax
object.DdfGetFieldComments
The DdfGetFieldComments method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
Return Value
DdfGetFieldComments returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
Example
'getting fields
Dim fields as Variant
VAEngine.RefreshLocations = True
VAEngine.DdfGetFieldComments = True
VAEngine.TableName = tableName
fields = VAEngine.FieldList
VAEngine.RefreshLocations = False
If not IsEmpty(fields)
For i = 0 to ubound(fields, 2)
'put field names and comments in a list box
List.AddItem (fields(1,i) + fields(6, i))
Next i
End If
See Also
FieldList
DdfModifyLocation
Applies to
VAccess
Description
Changes the table location of the current table and optionally writes the new location to the DDF.
Syntax
object. DdfModifyLocation newLocation
The DdfModifyLocation method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
newLocation
Required. String containing the new location of the Table.
Return Value
DdfModifyLocation returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
Example
VAEngine.RefreshLocations = True
VAEngine.TableName = tableName
VAEngine.DdfModifyLocation(newLocation)
See Also
Location, RefreshLocations, DdfAddTable, DdfModifyTableName
DdfModifyTableName
Applies to
VAccess
Description
Changes the name of the current table and optionally writes the new name to the DDF.
Syntax
object. DdfModifyTableName newName
The DdfModifyTableName method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
newName
Required. String containing the new name of the Table.
Return Value
DdfModifyTableName returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
See Also
RefreshLocations, TableName, DdfAddTable, DdfAddTableName, DdfModifyLocation
DdfSetOwner
Applies to
VAccess
Description
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.
Syntax
object.DdfSetOwner(NewOwnerName, SecurityLevel)
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
newOwnerName
a string to assign an owner name to the table
SecurityLevel
integer representing a security level
Remarks
The following Security Level codes may be passed to DdfSetOwner in the SecurityLevel parameter:
 
Code
Global Constant
Description
0
EXCLUSIVE
Does not allow the file to be opened unless the correct owner name is specified.
1
READONLY
Permits users who do not specify an owner name to view, but not to modify the table.
2
EXCLUSIVE_ENCRYPT
Does not allow the file to be opened unless the correct owner name is specified. Data is encrypted within the file.
3
READONLY_ENCRYPT
Permits users who do not specify an owner name to view, but not to modify the table. Data is encrypted within the file.
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.
Example
Private Function SetDDFOwner(newOwner as String, _
securityLevel as Integer) as Integer
'We must have confirmation to continue
VAEngine.RefreshLocations = True
'write this to 'DDF's
status = VAEngine.DdfSetOwner(newOwner, _
securityLevel)
If status = 0 Then
msg = "DDF Password has been successfully" _
& " changed."
MsgBox msg, vbInformation
Else
msg = " Btrieve returned status " + _
CStr(status) + "."
MsgBox msg, vbExclamation
End If
End Function
DdfTestOwnerName
Applies to
VAccess
Description
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.
Syntax
object. DdfTestOwnerName ownerName
The DdfTestOwnerName method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
ownerName
Required. The new owner name to test for the dictionary. If this is blank, DdfTestOwnerName will use the current dictionary owner name.
Return Value
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.
Remarks
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.
See Also
DdfSetOwnerName
Delete
Applies to
VAccess
Description
Deletes the current record and returns, as an Integer value, the PSQL status code.
Syntax
object.Delete
The syntax for this method has the following parts:
 
Part
Description
object
Required. Represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Note The ActiveX controls will attempt to do a GetNext operation following a Delete in order to maintain a valid currency.
Example
Dim stat As Integer
VAccess1.IndexNumber = 1 'msa_desc
VAccess1.FieldValue("msa_desc") = Text1.Text
stat = VAccess1.GetEqual
If stat = 0 Then
stat = VAccess1.Delete
If stat = 0 Then
MsgBox "Deleted!"
End If
Else
MsgBox "Could not locate requested city"
End If
FormatFieldValue
Applies to
VAccess
Description
Returns the value of a field in the current record formatted using the specified format string.
Syntax
object.FormatFieldValue (fieldname, formatstring)
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
fieldname
The name of any valid field in the file referenced by object.
formatstring
This parameter supports the same format strings and standard format names for number, date, and time values as the Visual Basic Format function.
Remarks
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.
Example
Label1.Caption = VAccess1.FieldValue("msa_desc")
Label2.Caption = _ VAccess1.FormatFieldValue("population", "##,###,###")
See Also
FieldValue, RowColumnValue, Column
GetDirect
Applies to
VAccess
Description
Attempts to retrieve a record using its physical position in the file and returns, as an Integer value, the PSQL status code.
Syntax
object.GetDirect [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
GetEqual
Applies to
VAccess
Description
Attempts to retrieve a record by an exact match to the current index and returns, as an Integer value, the PSQL status code.
Syntax
object.GetEqual [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
Example
If Check1.Value = 1 Then
stat = VAccess1.GetEqual
Else
stat = VAccess1.GetGreaterorEqual
End If
GetFirst
Applies to
VAccess
Description
Attempts to retrieve the first record in the current index path and returns, as an Integer value, the PSQL status code.
Syntax
object.GetFirst [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vvLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
Example
Orders.GetFirst
Orders.Init
Orders.GetNextExtended
GetGreater
Applies to
VAccess
Description
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.
Syntax
object.GetGreater [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
Example
'Retrieve the first record where the last
'name begins with S
Customers.IndexNumber = 1 'last name
Customers.FieldValue("last_name") = "S"
Customers.GetGreater
Select Case Customers.Status
Case 0
'we got a record, but we must test to see
'if it matches our criteria - GetGreater
'method does not do this. If there are no
'"S" records in the file, this record may
'be a "T", "U", "V", and so forth...
If Left$(Customers.FieldValue _
("last_name"), 1) = "S" Then
MsgBox "Found: " & Customers.FieldValue _
("last_name")
Else
MsgBox "No record was found."
End If
Case Else
MsgBox "No record was found."
End Select
GetGreaterOrEqual
Applies to
VAccess
Description
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.
Syntax
object.GetGreaterOrEqual [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
Example
If Check1.Value = 1 Then
stat = VAccess1.GetEqual
Else
stat = VAccess1.GetGreaterorEqual
End If
GetLast
Applies to
VAccess
Description
Attempts to retrieve the last record in the current index path and returns, as an Integer value, the PSQL status code.
Syntax
object.GetLast [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
Example
'Retrieve the record with the most recent date
Customers.IndexNumber = 3 'entry date
Customers.GetLast
GetLess
Applies to
VAccess
Description
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.
Syntax
object.GetLess [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
GetLessOrEqual
Applies to
VAccess
Description
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.
Syntax
object.GetLessOrEqual [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
GetNext
Applies to
VAccess
Description
Attempts to retrieve the next record in the current index path and returns, as an Integer value, the PSQL status code.
Syntax
object.GetNext [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
Example
'Delete all records where the date is a year
'or more old
Customers.IndexNumber = 0 'customer number
Customers.GetFirst
Do
If DateDiff("yyyy", Now, _
Customers.FieldValue("last_order_date")) > 0
Customers.Delete
End If
Customers.GetNext
Loop While Customers.Status = 0
GetNextExtended
Applies to
VAccess
Description
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.
Syntax
object.GetNextExtended
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example
'read and print the records in the orders file
Orders.GetFirst
Orders.Init
Do
Orders.GetNextExtended
For r = 1 to Orders.Rows
For c = 1 to Orders.Columns
Debug.Print Orders.RowColumnValue(r,c)
Next c
Debug.Print 'new line
Next r
Loop While Orders.Status = 0
GetPrevious
Applies to
VAccess
Description
Attempts to retrieve the previous record in the current index path and returns, as an Integer value, the PSQL status code.
Syntax
object.GetPrevious [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
GetPreviousExtended
Applies to
VAccess
Description
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.
Syntax
object.GetPreviousExtended
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
GetTableList
Applies to
VAccess
Description
Returns the list of tables defined in the current dictionary as a two-dimensional variant array.
Syntax
object. GetTableList
The syntax for this method has the following parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
Return Value
GetTableList returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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:
 
Subscript
Name
Variant Type
Description
0
tableID
VT_I2
Unique key for the file table dictionary entry.
1
tableName
VT_BSTR
The name of the table, 20 characters max storage limit.
2
tableLocation
VT_BSTR
The operating system or network path and file name of the data file referenced by the table, 64 characters max storage limit.
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.
Example
VAEngine.RefreshLocation = True
VAEngine.DDFPath = path
tables = VAEngine.GetTableList
See Also
FieldList, IndexList, RefreshLocations
GetTotalSegments
Applies to
VAccess
Description
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.
Syntax
object.GetTotalSegments(keynumber)
The GetTotalSegments method syntax has these parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
keynumber
Required. Contains the index number to be checked.
Example
NumSegments% = _ VAccess1.GetTotalSegments(VAccess1.KeyNumber)
Init
Applies to
VAccess
Description
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.
Syntax
object.Init
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example #1 - Automode = True
VAccess1.GetFirst
VAccess1.Init
Example #2 - Automode = False
Orders.GetFirst
Orders.Init
Orders.GetNextExtended
Insert
Applies to
VAccess
Description
Attempts to insert the current data buffer as a new record and returns, as an Integer value, the PSQL status code.
Syntax
object.Insert
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example
'Search for record, if it does not exist, insert it
'Set the search values
Customers.FieldValue("name") = "John Adams"
'Set the index and do the search
Customers.IndexNumber = 1 'customer name
Customers.GetEqual
'If the record does not exist, insert it
Select Case Customers.Status
Case 0
MsgBox "The customer entry already exists."
Case 4
Customers.Insert
Case Is > 0
MsgBox "Error. PSQL status = " + _
Customers.Status
End Select
Open
Applies to
VAccess
Description
Attempts to open the file associated with the control and returns, as an Integer value, the PSQL status code.
Syntax
object.Open
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example
If index > -1 Then 'selected from list
VAccess1.Close
VAccess1.TableName = Combo1.List(index)
VAccess1.Open
End If
Refresh
Applies to
VAccess, VACombo, VAList
Description
Forces an immediate update of the associated object.
Example
'Refresh bound controls with content of Data Buffer
VAccess1.Refresh
RemoveItem
Applies to
VACombo, VAList
Description
Removes an item from a VAList or VACombo control operating in field-bound mode.
Syntax
object.RemoveItem index
The RemoveItem method syntax has these parts:
 
Part
Description
object
Required. An object expression that evaluates to an object in the Applies To list.
index
Required. Integer representing the position within the object of the item to remove. For the first item in a VAList or VACombo, index = 0.
Remarks
A VAList or VACombo control that is operating in record list mode (VARecordList property is set to True) does not support the RemoveItem method.
RowColumnValue
Applies to
VAccess
Description
Returns a field value from a specified Row and Column in an extended fetch record set.
Syntax
object.RowColumnValue (row, column)
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
row
Required. Specifies a valid row in an extended fetch record set.
column
Required. Specifies a valid column in an extended fetch record set.
Remarks
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.
Example
'Print all rows in an extended fetch record set
For rowcount = 1 To Orders.Rows
For colcount = 1 To Orders.Columns
Debug.Print Orders.RowColumnValue(rowcount,
colcount)
Next colcount
Debug.Print "" 'new line
Next rowcount
SetFileFlag
Applies to
VAccess
Description
Sets the file flag specified before creating a Btrieve file with the Create method.
Syntax
object.SetFileFlag(flag, setting)
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
flag
Required. Contains the file flag to set
setting
Required. Specifies the setting for the flag. Can be True or False.
Remarks
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.
Example
Stat = VAccess1.SetFileFlag(BTF_fTruncate, False)
Stat = VAccess1.SetFileFlag(BTF_fDataCompression, False)
Stat = VAccess1.SetFileFlag(BTF_fKeyOnly, False)
Stat = VAccess1.SetFileFlag(BTF_fPreallocate, False)
VAccess1.PageSize = 0
Stat = VAccess1.DdfCreateTable(True)
SetOwner
Applies to
VAccess
Description
The SetOwner method is used to specify an owner name for a PSQL table to restrict access to the table.
Syntax
object.SetOwner(OwnerName, SecurityLevel)
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
OwnerName
the owner name to assign to the table
SecurityLevel
integer representing a security level
Remarks
The following Security Level codes may be passed to SetOwner in the SecurityLevel parameter:
 
Code
Global Constant
Description
0
EXCLUSIVE
Does not allow the file to be opened unless the correct owner name is specified.
1
READONLY
Permits users who do not specify an owner name to view, but not to modify the table.
2
EXCLUSIVE_ENCRYPT
Does not allow the file to be opened unless the correct owner name is specified. Data is encrypted within the file.
3
READONLY_ENCRYPT
Permits users who do not specify an owner name to view, but not to modify the table. Data is encrypted within the file.
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.
See Also
OwnerName, DdfSetOwner, DdfTestOwnerName
ShowSelectedFieldsDlg
Applies to
VAccess
Description
Invoking this method will display the Extended Query Field Selection dialog box, allowing the user to change the SelectedFields property at run time.
Syntax
object.ShowSelectedFieldsDlg
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example
'Allow the user to select the fields
'to be retrieved
Customers.ShowSelectedFieldsDlg "Field Selection"
 
're-establish current record positioning and
'initialize the extended operations buffers
'with the new field selections
Customers.GetFirst
Customers.Init
Customers.GetNextExtended
ShowSelectedRecordsDlg
Applies to
VAccess
Description
Invoking this method will display the Extended Query Record Selection dialog box, allowing the user to change the SelectedRecords property at run time.
Syntax
object.ShowSelectedRecordsDlg
The ShowSelectedRecordsDlg method syntax has these parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example
'Allow the user to set the record
'selection criteria
Customers.ShowSelectedRecordsDlg "Record Selection"
 
're-establish current record positioning and
'initialize the extended operations buffers
'with the new field selections
Customers.GetFirst
Customers.Init
Customers.GetNextExtended
Stat
Applies to
VAccess
Description
Forces a refresh of the status buffer from the current table.
Syntax
object.Stat
The Stat method syntax has these parts:
 
Part
Description
object
Required. The name of a valid VAccess control.
Return Value
Stat returns a two-byte integer that holds the status of the VAccess control. If this is zero, the operation completed successfully.
Remarks
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.
StatusDialog
Applies to
VAccess
Description
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.
Syntax
object.StatusDialog [status]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
status
Optional. Integer value. If no value is specified, the current value of the Status property is used.
Example
If stat = 0 Then
Text1.Text = VAccess1.FieldValue("msa_desc")
Text2.Text = _
VAccess1.GetFieldValue("population", "##,###,###")
Text3.Text = VAccess1.FieldValue(2)
Else
VAccess1.StatusDialog stat
End If
StepFirst
Applies to
VAccess
Description
Attempts to retrieve the first record in physical record storage order and returns, as an Integer value, the PSQL status code.
Syntax
object.StepFirst [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
StepLast
Applies to
VAccess
Description
Attempts to retrieve the last record in physical record storage order and returns, as an Integer value, the PSQL status code.
Syntax
object.StepLast [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
StepNext
Applies to
VAccess
Description
Attempts to retrieve the next record in physical record storage order and returns, as an Integer value, the PSQL status code.
Syntax
object.StepNext [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
StepNextExtended
Applies to
VAccess
Description
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.
Syntax
object.StepNextExtended
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
StepPrevious
Applies to
VAccess
Description
Attempts to retrieve the previous record in physical record storage order and returns, as an Integer value, the PSQL status code.
Syntax
object.StepPrevious [vLockBias]
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
vLockBias
Optional. Value representing the type of record lock to place on the record when it is retrieved. Default is 0, no lock. One of the following constants:
Const BTO_SingleNoWait = 200
Const BTO_MultiNoWait = 400
Remarks
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.
StepPreviousExtended
Applies to
VAccess
Description
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.
Syntax
object.StepPreviousExtended
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Transaction
Applies to
VAccess
Description
The Transaction function controls PSQL transaction processing within an application. It may be used to begin, end, or abort a PSQL transaction.
Syntax
object.Transaction iOperationCode
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Note: This placeholder is simply a requirement of ActiveX architecture, and does not limit the scope of the transaction to the file attached to object. Any inserts, updates, or deletes to any files nested between the begin and end transaction methods will be included in the transaction.
iOperationCode
Required. Specifies the transaction operation to perform.
Remarks
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.
 
Code
Constant
Description
19
BTO_BeginTransaction
Begins an exclusive transaction - no other processes may access the files involved in the transaction until the transaction completes.
20
BTO_EndTransaction
Ends the transaction and commits changes which have been made to files since the transaction was begun.
21
BTO_AbortTransaction
Aborts all changes to files made since the Begin Transaction operation and ends the transaction.
1019
BTO_BeginTransaction + 1000
Begins a concurrent transaction (Pervasive.SQL version 6 or above— previous versions will return Status Code 1) Other processes may access the files affected by the transaction.
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
'Begin a concurrent transaction
status% = Customers.Transaction(BTO_BeginTransaction + 1000)
 
If status% = 0 Then
'BeginTransaction succeeded,
'Add the order record
status% = status% + Orders.Insert
 
'Add the billing record
status% = status% + Invoices.Insert
 
'Get the customer record and modify it
Customers.IndexNumber = 1 'custID
Customers.FieldValue("custID") = _ Invoices.FieldValue("custID")
status% = status% + Customers.GetEqual
Customers.FieldValue("lastInvoiceDate") = _ Invoices.FieldValue("InvoiceDate")

balance = Customers.FieldValue("balance") + _ Invoice.FieldValue("amount")
Customers.FieldValue("balance") = balance
status% = status% + Customers.Update
End If
 
If status% = 0 Then
'All changes succeeded. Commit the transaction.
Customers.Transaction(BTO_EndTransaction)
Else
'One or more inserts failed. Abort the transaction.
Customers.Transaction(BTO_AbortTransaction)
End If
Unlock
Applies to
VAccess
Description
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.
Syntax
object.Unlock (iLockType)
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
iLockType
Required. The type of record lock to remove.
Remarks
The following lock type codes may be passed to the Unlock method.
 
Part
Constant
Description
0
UL_Single
Remove a Single Record lock from the current record.
-1
UL_CurrentMultiple
Remove a Multiple Record lock from the current record.
-2
UL_AllMultiple
Remove all Multiple Record locks from locked records in the table.
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.
Update
Applies to
VAccess
Description
Attempts to update the current record with the contents of the current data buffer, and returns, as an Integer value, the PSQL status code.
Syntax
object.Update
The syntax for this method has the following parts:
 
Part
Description
object
Required. The object placeholder represents an object expression that evaluates to an object in the Applies To list.
Remarks
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.
Example
'Find record, change company name, update record
'Set the search values
Customers.FieldValue("name") = "John Harbison"
 
'Set the index and do the search
Customers.IndexNumber = 1
Customers.GetEqual
 
'If the record exists, change the company name
'and update it
Select Case Customers.Status
Case 0
Customers.FieldValue("company_name") = _
"Harbison Consulting"
Customers.Update
Case 4
MsgBox "Record not found."
Case Else
MsgBox "Error. PSQL status = " + _
Customers.Status
End Select