This chapter describes the properties of the ActiveX access method. The properties are presented in alphabetical order.
AutoDialog
Applies to
VAccess
(DEPRECATED - former I*net Data Server only.) If this property is set True, the control will automatically display a dialog box to the user in the event of a communications error. This can occur if it cannot reach a Zen server. This property is ignored if the VAccess control is not trying to access remote data via the IDS.
Remarks
The AutoDialog property determines whether or not the ActiveX will automatically display a dialog box when there is a communications error via IDS. If reconnection is possible, it will contain a prompt allowing the reconnection attempt. The default value is False.
See Also
Zen Programmer’s Guide
AutoLogon
Applies to
VAccess
(DEPRECATED - former I*net Data Server only.) Setting this property True automatically presents the user with a logon dialog box when the application attempts to open a database at a secure IDS site. If this property is False, the application must handle the Logon event manually to provide security information This property is ignored if the VAccess control is not trying to access remote data via the IDS or if the target IDS is unsecured.
Remarks
The AutoLogon property serves two related functions. First, it determines whether or not the ActiveX will automatically display a logon dialog box to the user when a logon is requested by the IDS. If the IDS is set to Browseable, this dialog will present a list of IDS database names; otherwise it will require the user to enter a database name. Additionally, AutoLogon determines whether the Logon event will be fired when the IDS requests security information. If AutoLogon is set to True, the ActiveX will bring up the default logon dialog and the Logon event will not fire.
If this property is set to False, the default dialog will not appear and the Logon event will fire every time the IDS requests security information. You may then respond to the Logon event to provide security information or to implement a custom logon dialog box.
The default value is True.
See Also
Logon event
Zen Programmer’s Guide
Affects: Location, Ddfpath
AutoMode
Applies to
VAccess
Description
Setting the AutoMode property to Truewill automatically execute Zen extended fetch operations (GetNextExtended) to retrieve the data specified in the SelectedFields and SelectedRecords properties as soon as the Init method is called at run time. GetNextExtended operations require logical currency. You may establish logical currency by invoking any of the indexed record operations such as GetFirst, GetEqual, and so on.
Remarks
If AutoMode is set to True, then records which meet the selection criteria are fetched automatically and cached as a snapshot of the record set in memory as Row values are requested. Extended methods are disabled if AutoMode is set to True. If the CancelDialog property is True, then a Cancel dialog box will be displayed to the user during data access operations at run time, allowing the user to cancel the process.
When AutoMode is set to True, any attempt to use extended operations will return a -1 status at run time. See ExtendedOps.
If the AutoMode property is set to False, then data retrieval is your responsibility. Calling the Init method simply allocates the structures used by Zen for extended operations calls, but no data retrieval is performed. You can fetch data from the file by performing a GetNextExtended, GetPreviousExtended, StepNextExtended or StepPreviousExtended method at run time. Only one extended operations cache buffer is retained in memory, and is re-used for subsequent fetches.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
A replacement for the former RequireOpen property, the AutoOpen property determines whether or not the VAccess control will automatically try to open data files when appropriate. If this property is set to True, then the VAccess will attempt to open the requested data file at run-time instantiation and whenever the Location property is changed. If this property is set to False, you are responsible for making an Open call before attempting to perform any operations on the data file.
See Also
Affects: Location, DdfPath
Buffer
Applies to
VAccess
Description
Sets or returns the contents of a control’s current record buffer. The record buffer is the raw record data retrieved by Zen.
Syntax
object.Buffer(short alignment)
The Buffer property syntax has these parts:
Part
Description
object
Required. The name of the VAccess object represents an object expression that evaluates to an object in the Applies To list.
alignment
Required. Specifies byte alignment of data. The accepted values for alignment are 1, 2, 4, 8, and 16 bytes.
Remarks
Data is read from and written to the current record buffer. On a read operation, this property returns an OLE Variant containing a byte array representation of the current record buffer. On a write operation, it takes an OLE Variant which contains a byte array to be written to the current record buffer. Changes made to this property are not saved in the Btrieve file until a successful Update or Insert method is invoked.
The buffer that is returned is the single record buffer only; it will not contain the contents of the status buffer after a Stat call, nor will it contain an extended operations record buffer after an extended operations call. This information is available through other properties and methods (see Stat, RowColumnValue, and RowPosition). The Clear method will clear this buffer.
Certain programming environments allow or require specific byte alignment for structured variables. The alignment parameter enables you to specify the byte alignment to be used for individual fields within the record.
This property is not available at design time.
Example
Public Type SAFEARRAYBOUNDS
cElements As Long
lLbound As Long
End Type
Public Type SAFEARRAY
cDims As Integer
fFeatures As Integer
cbElements As Long
cLocks As Long
pvData As Long
Bounds(0) As SAFEARRAYBOUNDS
End Type
Public Type Buffer
msa_desc As String * 34
population As Long
prev_population As Long
End Type
Declare Sub CopyMemory Lib "KERNEL32" Alias _ "RtlMoveMemory" (pDest As Any, pSrc As Any, ByVal _ ByteLen As Long)
Declare Function VarPtrArray Lib "msvbvm50.dll" _ Alias "VarPtr" (Ptr() As Any) As Long
Public Sub ReadData()
Dim i as integer
Dim dataArray() as Buffer
Dim byteArray() as Byte
VAccess1.Open
VAccess1.GetFirst
Redim dataArray(VAccess1.TotalRecords)
For i = 0 to VAccess1.TotalRecords-1
ByteArray = VAccess1.Buffer(4)
DataArray(i) = GetBuffer(byteArray)
VAccess1.GetNext
Next i
End Sub
Public Function GetBuffer(bufferArray() As Byte) _ as Buffer
This property corresponds to the maximum reject count parameter in the Zen extended get operation structure (see the Get Next Extended documentation in the Zen Programmer’s Guide).
Remarks
Specifying a value for the CacheRejectMax property limits the number of records which Zen can skip while searching for records which meet the SelectedRecords property filter conditions. A zero value in this property will use a system-defined maximum. You can use this property to optimize read times for a given query. The valid range for this property is 0 (default) through 65,535 records. If no value is specified for the SelectedRecords property, setting this property has no effect.
This property may be used by GetNextExtended, GetPreviousExtended, StepNextExtended, or StepPreviousExtended methods, or by a VAccess control running in AutoMode, responding to a request for a specific Row value.
If Zen reaches the CacheRejectMax value while processing an extended fetch, the fetch operation will return the set of records encountered in processing the fetch operation which meet the record selection criteria and a status value of 64, indicating that filter limit for rejected records was reached.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
The CacheRows property determines the maximum number of rows to return in any single Zen extended fetch operation.
Remarks
The highest possible setting for this property will depend upon the byte length of the returned rows, which in turn is dependent upon the value of the SelectedFields property if there is one, or the defined data buffer length of the data file if there is not. This property corresponds to the “number of records to be retrieved” parameter in the fixed portion of the data extractor in the extended get operation structure (see the Get Next Extended documentation in the Zen Programmer’s Guide).
Setting this property to zero will automatically calculate and use the maximum value possible based on the length of the rows to be returned and the value of the MaxBufferSize property. You may set this property to a lower value to optimize read times for a given query.
Setting this value too high will result in a status 97, meaning that Zen has not been configured to handle a buffer large enough to hold the number of rows requested. To solve this problem, lower the setting of the CacheRows property, increase the Zen buffer size (if possible), or reduce the number of fields returned with the SelectedFields property.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
If the AutoMode property is set to True, setting the CancelDialog property to Truewill display a dialog box during multiple extended fetch operations, allowing the user to cancel the fetch request between operations. When AutoMode is True, extended fetch operations are performed as a result of changes to the Row property.
Remarks
The Cancel dialog box shows the current number of records retrieved. This number is updated every time a new block of records is returned by an extended fetch event. Canceling an AutoMode extended fetch event will retain the rows retrieved prior to the cancel in memory. This property has no effect if the AutoMode property is False.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
See Also
Affected by: ExtendedOps, Row, AutoMode
Column
Applies to
VAccess
Description
This property specifies which column in an extended fetch record set is the current column for the FieldValue and ColumnName properties.
Remarks
Each column in an extended fetch record set corresponds to a field in the database. If a value is specified in the SelectedFields property, the order of the column values corresponds to the order of the fields listed in the SelectedFields property. If no value is specified for the SelectedFields property, the order of column values corresponds to the order of fields in the database record.
The Column and Row properties together specify an individual field in a set of records returned by an extended fetch operation.
The valid range of values for the Column property is 1 (the first column) to the value of the Columns property (the last column). This property is not available at design time.
The Column property is paired with the ColumnName property. Setting one sets the other as well.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
RowColumnValue is usually simpler than Column for specifying and retrieving specific field values.
See Also
Affects: ColumnName, FieldValue, RowColumnValue
Affected by: ExtendedOps
ColumnName
Applies to
VAccess
Description
The ColumnName property contains the field name of the field assigned to the currently selected column for the record set returned by an extended fetch operation.
Remarks
The ColumnName property is paired with the Column property. Setting one sets the other as well. So the Column property specifies the current column for ColumnName.
The fields enumerated with successive calls to this property may be different or in a different order than that specified by FieldList. This is because FieldList contains the actual fields for the record in offset order, whereas the columns are dictated by the SelectedFields property.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
See Also
Affected by: Column, SelectedFields, ExtendedOps
Columns
Applies to
VAccess
Description
The Columns property returns the number of columns defined in an extended fetch record set.
Remarks
If a SelectedFields property has been specified for extended fetch operations, this value will correspond to the number of fields specified in the SelectedFields property. Otherwise, it will correspond to the total number of fields defined for a record in the data file (see Fields property).
This property is not available at design time, read-only at run time. It will contain valid data only after the extended operations Init method has been invoked at run time. The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
Example
'In this example we will fill up a list box
'with records from one extended op buffer
Dim line As String
Dim colcount, rowcount As Integer
Orders.GetFirst
Orders.ExtendedOps = True
Orders.Init
Orders.GetNextExtended
For rowcount = 1 To Orders.Rows
Orders.Row = rowcount
line = ""
For colcount = 1 To Orders.Columns
'FieldValue returns a variant
'that we expect to be a string
'check to make sure it is
If Not VarType(Orders.FieldValue(colcount)) = _ vbError Then
line = line + CStr(Orders.FieldValue(colcount))
End If
Next colcount
ListBox.Add line
Next rowcount
See Also
Affected by: ExtendedOps, SelectedFields
ColumnWidth
Applies to
VAList
Description
Set this property to assign tab stops to a multi-column record list implementation of a VAList object. If the VARecordList property is False, this property has no effect.
To assign tab stops to a multi-column record list, take these steps:
1 Make sure your list box is wide enough to hold all the column data.
2 Set the VARecordList check box to True.
3 If you have not already done so, select the columns to be displayed under the VAFieldName property. (To do this, right-click on the list box to access the Property Pages. Click on the ellipses beside VAFieldName and select the columns.)
4 In the VAFieldName property of the Property Pages, select the fields you want. You can double-click on an available field (column) to select it. Click OK.
5 Still in the Property Pages, click on the ellipses next to the ColumnWidth combo box to open the Multi-Column Tab Settings window. The first field you selected is displayed.
6 Double-click to the right of the first fieldto set the first tab stop. A hashed line appears. Drag this line to provide enough space for the data that will be displayed in this column. Continue double-clicking and dragging these lines until you have displayed and adjusted the tabs for the columns selected. See Figure 6.
Figure 6 Tab Settings in a Multi-Column List Box
7 Click OK in this window and in the Property Pages.
See Also
Affected by: VARecordList
CompressData
Applies to
VAccess
(DEPRECATED - former I*net Data Server only.) Enables or disables data compression when sending data to or receiving data from the IDS. This property is ignored if the VAccess control is not trying to access remote data via the IDS.
Remarks
The CompressData property determines whether or not compression will be used when communicating with the IDS. Since the IDS determines compression settings on the fly on a per-client basis, this property may be set either True or False at run time, even between record requests.
Since the VAccess control can be used to access IDS only over slower networks (using standard Btrieve requesters over a LAN), this property should be set to True most of the time.
The default value is True.
See Also
Zen Programmer’s Guide
DatabaseName
Applies to
VAccess
Specifies the database name to which you want to connect. This property is used in conjunction with HostAddress (page 6-93) and HostConnect (page 6-94) to specify a host and database name. ActiveX will attempt to connect to the database using a database URI.
If you want to connect to the database using local or mapped drives, or UNC paths, see the DdfPath (page 6-81) property instead.
Remarks
If security is enabled for the database, the user will be prompted for the user name and password by the MicroKernel Engine.
Note This property formerly was used to connect to databases using the I*net Data Server.
The default value is blank (empty string).
See Also
Zen Programmer’s Guide for more information on database URIs.
Affects: HostAddress, HostConnect
DataLength
Applies to
VAccess
Description
Returns or sets the length in bytes of the record data buffer used for single-record operations on the file.
Remarks
This property will be updated after each navigation call to contain the actual current record size. This will only be different from the initial (pre-call) value if the file being accessed contains a variable length field and the returned record is less than the maximum record length as defined in the DDF.
See Also
Affected by: Buffer
DdfKeyUseIndexDDFOnly
Applies to
VAccess
Specifies whether or not the VAccess should use the true indexes of the file or the indexes as specified in the DDF.
Remarks
If this property is False, the VAccess control will use the index information from the status buffer for all index information, using the DDF for information (such as IndexName) which is not contained in the status buffer. If True, the VAccess will use the DDF information exclusively; if the DDF is incorrect, setting this property to True will result in the failure of all key-based navigational calls.
The default value is False.
See Also
Affects: IndexList
DdfPath
Applies to
VAccess
Description
Sets the drive and path on which the DDF files associated with this control reside.
Remarks
This property attaches the VAccess control to a specific set of DDF data definition files. If you change this property, you must specify one of the Table Names in this DDF as the TableName property for the VAccess control.
Before changing this property at run time, you should close any currently open file associated with the VAccess control. You will then need to specify a new TableName property as one of the table names in the new DDF. You may also need to specify a new Location property before opening the new file.
Note If RefreshLocations is False, DdfPath cannot be changed.
OnRemote is called when DdfPath fails.
You can use this feature to resolve the path at run time or to inform the user that the connect failed.
DdfPath can take any of the following forms (discussed below)
•mapped drives
•URL
•UNC
Mapped Drives
Traditional driver-letter nomenclature (c:\path\datafile) are accepted by the DdfPath property, as in previous versions of the ActiveX. If the drive cannot be located, the VAccess will look for a file called IDSHOSTS using the path environment setting (this file may be used to map drive letters to network or IP addresses, much like LMHOSTS. For more information, see Zen Programmer’s Guide). If this file can be found, it will be searched for the requested path. If the requested path is mapped, the VAccess control will attempt to connect to an IDS at the specified location.
Uniform Resource Locator
A URL may also be used to specify location. The protocol-specific prefixes are pids for remote (IDS) calls and pmke for local. Thus, a local call would take the form pmke://{server}/[path/.../][tablename] and a remote call would appear pids://{server}/[path/.../][tablename].
Universal Naming Convention
UNC (\\server\path\datafile) can be used as a DdfPath entry as well, where the server can be either a Zen server on the LAN, an IDS server or a server mapped in IDSHOSTS to an IDS server. If the server is not a standard IP address or domain name, the VAccess will attempt to resolve the server name locally. If the location is not available locally, the VAccess will then try to resolve the server name using IDSHOSTS and if successful will re-route calls to the IDS.
As described above, DdfPath can be used to specify local or remote access (see also Zen Programmer’s Guide). However, if remote access is requested, the VAccess will not attempt to connect to the IDS unless HostConnect is set to True. Additionally, the DdfPath and Location properties cannot attempt to access two different IDS servers simultaneously.
Therefore, if Location is set to a remote location and DdfPath is set to a different remote location, the server name will be changed in the Location property to reflect the new remote location specified by DdfPath. If Location is set to a local directory, DdfPath will not affect Location.
If HostAddress is set to specify a server using URIs, DdfPath will be ignored.
Note When DdfPath is changed, the VAccess will attempt to read the DDF files at the new path and update the internal table list, FieldList, and IndexList.
The setting of DdfTransactionMode determines whether or not updates to the data dictionary tables will take place within a transaction. Accepts or returns a boolean value.
Remarks
DdfTransactionMode will wrap all DDF dictionary operations within a transaction, so it should be set to True when making changes to DDF files and False at other times.
Extended operation calls return a set of records which matches the selected fields and selected records on a single call. These operations are significantly faster than a number of single record operations which would accomplish the same thing.
If this property is True, the VAccess control can retrieve records using the extended fetch methods.
When the ExtendedOps property is False, or when the AutoMode property is set to True, methods that use extended operations, such as GetNextExtended, GetPreviousExtended, StepNextExtended, and StepPreviousExtended, will all return a status code of -1 indicating that extended operations are unavailable.
Remarks
If this property is False(default), the VAccess control will navigate the Zen data file and retrieve records using single record fetch operations.
Sets or returns a variant array containing information on the fields of the current table as specified by DdfPath and TableName.
Remarks
The FieldList property accepts and returns a variant encapsulating a two-dimensional variant array. The first subscript references one property of the field, and the second references the field ordinal. The properties referenced by the first subscript are given in the following table.
Subscript
Name
Variant Type
Description
0
fieldID
VT_I2
Unique key for field table dictionary entry.
1
fieldname
VT_BSTR
Name of the field, 20 characters max storage limit.
2
datatype
VT_I2
Data type code.
3
offset
VT_I2
Offset of field from start of record.
4
size
VT_I2
Size of field.
5
decimal
VT_I2
Number of fixed decimal places, or bit offset for BIT data type fields.
6
flags
VT_I2
Field flags. See the X$Field system table in SQL Engine Reference for a description of field flag settings.
7
comment
VT_BSTR
Field comments stored in COMMENT.DDF.
When setting field information, the variant array must contain a minimum amount of information for each field to be defined. Required information includes a field name which is unique within the definition of the table, a valid data type, and a valid size for data types which support more than one field length.
Note that the comment column of this array will be populated only if the DDFGetFieldComments method is called prior to reading the FieldList property.
If RefreshLocations is set to True, reading FieldList will cause the VAccess to re-read the DDF files and get the field information stored in the DDF. Changing FieldList with RefreshLocations set to True will no longer cause all changes to be immediately written to the DDF Files themselves. You must now call DdfAddTable, DdfModifyLocation, and so forth to actually write the changes to the DDFs. This is a change in behavior since the release of the Zen SDK. If RefreshLocations is False, FieldList operations will read and update the VAccess control’s memory image of the fields.
If DdfTransactionMode and RefreshLocations are both set to True, all manipulations of FieldList will occur within a transaction.
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 in a list box
List.AddItem fields(1, i)
Next i
End If
'setting
VAEngine.RefreshLocations = False
VAEngine.FieldList = fields
'write changes to DDF – do not need to reset RefreshLocations
Returns the total number of fields defined for the associated file.
See Also
Affects: FieldList, Join, FieldNumber
Affected by: FieldList
FieldValue
Applies to
VAccess
Description
Sets or returns the value of the field specified for the current record in memory or the current row of an extended fetch record set.
Syntax
object.FieldValue (field)
The FieldValue property 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.
field
Required. Either a string field name or an integer field index specifying a valid field in object.
Remarks
Data is read from and written to the current record in memory. Changes made to the record are not saved in the Zen file until a successful Update or Insert method is invoked.
If a column is formatted the value for the contents of that column will always be returned as a BStr, regardless of data type (the container may automatically translate this to a String, Variant, AnsiString, or other variety of character data). If a column is not formatted, the value will be returned as the variant that most closely approximates the data type of the column. Most control containers can manipulate, internationalize, and re-format this returned variant much more easily and quickly than a BStr. For this reason, we recommend that unformatted columns be retrieved whenever possible.
This property is not available at design time.
If the ExtendedOps property of the control is True, the field parameter should specify the column name or column index of the column in the current row, indicated by the value of the Row property. If no parameter is specified, the column returned will be the column specified in the Column property. The FieldValue property is read-only if the ExtendedOps property of the control is True.
You can also use the RowColumnValue method to return a value from any valid Row and Column coordinates in an extended fetch record set.
Example
Dim stat As Integer
VAccess1.FieldValue("msa_desc") = Text1.Text
If Check1.FieldValue = 1 Then
stat = VAccess1.GetEqual
Else
stat = VAccess1.GetGreaterOrEqual
End If
If stat = 0 Then
Text1.Text = VAccess1.FieldValue("msa_desc")
Text2.Text = VAccess1.FieldValue("population")
Text3.Text = VAccess1.FieldValue(2)
'the third field in the record
End If
See Also
Affected by: ExtendedOps, Row
FileVersion
Applies to
VAccess
Description
Returns the Zen file version of the current table via a Zen stat call.
Remarks
This property indicates the Zen feature set incorporated in the data file when the table was created. It corresponds to the earliest version of Zen which can access the table.
FireEvents
Applies to
VAccess
Description
Enables or disables event firing for the VAccess control.
Remarks
Setting this property True will enable the firing of the OnRemote, Validate, Reposition, and GotData events for the VAccess control. If you do not include code in these events in your application, you can disable them by setting this property False.
FocusSelText
Applies to
VAText
Description
When this property is set to True, the text in the VAText will be selected when the text box receives focus.
HostAddress
Applies to
VAccess
Specifies the IP address or domain name of the computer hosting the database to be accessed. The connection is made via a database URI.
Remarks
As is the case with any TCP/IP agent, a domain name can only be resolved if the computer has access to a DNS server. Likewise, use of a domain name results in somewhat slower connection time, as the domain name must be resolved before the connection can be established.
Specify only the IP address or server name. Do not attempt to specify the URI explicitly, or use URI parameters. The ActiveX controls will build the URI when HostAddress and DatabaseName are specified.
This property, like Location and DdfPath, is dependent on the HostConnect property. If HostConnect is True and the value of the HostAddress property is changed, the old connection (if any) will be closed and the new connection will be attempted. When the ActiveX attempts to connect to the server and fails, the HostConnect property is automatically set to False. To make another connection attempt, you must reset HostConnect to True.
HostAddress overrides any server settings in DdfPath and Location.
The default value is blank (empty string).
See Also
Zen Programmer’s Guide
Affects: DdfPath, Location
Affected by: HostConnect
HostConnect
Applies to
VAccess
Used in conjunction with the HostAddress property to initiate or terminate a connection using a database URI. It may also be queried at any time for the current connection status.
Remarks
This property affects ActiveX control when HostAddress is entered. If this is set to True and HostAddress is not empty, then the VAccess will attempt to connect to the requested server. If it is unable to resolve the server address or if there is a connection failure, the HostConnect property will be set to False automatically following the connection failure.
HostConnect does not affect VAccess interaction with local Btrieve requesters.
The default value is True.
See Also
Zen Programmer’s Guide
Affected by: DdfPath, Location, HostAddress
IncludeCurrent
Applies to
VAccess
Description
Setting this property at run time determines whether the record set results of the next extended fetch operation performed will include the current record or will begin with the subsequent record.
Remarks
Setting the value of this property to Truewill begin the next extended fetch operation at the current record position in the file (equivalent to setting the “UC” constant in a Zen extended fetch API record request structure). Setting the value of this property to Falsewill begin the next extended fetch operation at the subsequent record position in the file (equivalent to setting the “EG” constant in a Zen extended fetch API record request structure). This property is automatically set to True after the Init method is invoked, and is automatically reset to Falseafter the first extended fetch operation following the Init.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
Sets or returns a variant array containing information on the indexes of the current table as specified by DdfPath and TableName.
Remarks
The IndexList property accepts and returns a variant encapsulating a two-dimensional variant array. The first subscript references one property of the index segment, and the second references the index segment ordinal. The properties referenced by the first subscript are:
Subscript
Name
Variant Type
Description
0
IndexName
VT_BSTR
Unique name for the index, 20 characters max storage limit.
1
IndexNum
VT_I2
Index number (ordinal).
2
SegNum
VT_I2
Sequence number of this segment within the index.
3
FieldName
VT_BSTR
Name of the field indexed by this segment. 20 characters max.
4
Flags
VT_I2
Index attribute bit flags (follows Btrieve key flag specification).
Index attributes are also associated with a physical data file. Setting this property may be used to define indexes in the dictionary, but does not modify the index attributes of the physical data file. Index attributes of existing data files may be modified using DdfAddIndex, DdfDropIndex, and DdfDropIndexMaintain methods.
If RefreshLocations is set to True, reading IndexList will cause the VAccess to re-read the DDF files and get the field information stored in the DDF. Changing IndexList with RefreshLocations set to True will no longer cause all changes to be immediately written to the DDF Files themselves. You must now call DdfAddIndex, DdfDropIndex or DdfDropIndexMaintain to actually write the changes to the DDF files. This is a change in behavior since the release of Pervasive.SQL 2000 SDK. If RefreshLocations is False, IndexList operations will read and update the VAccess control’s memory image of the indexes.
If DdfTransactionMode and RefreshLocations are both set to True, all manipulations of IndexList will occur within a transaction.
If DdfKeyUseIndexDdfOnly is set to True, then the IndexList property will always reflect only what is in the DDF. If DdfKeyUseIndexDDFOnly is False, IndexList will get the correct index information from the status buffer each time the index information is refreshed and use the DDF for information not kept in the status buffer.
Sets or Returns the current index number for the Zen table associated with the VAccess control.
Remarks
Use this property to determine which index to use when retrieving records from the data file.
The valid range of index values for a data file is 0 through the value of the TotalKeys property minus one.
This property may have other meanings, depending upon the Zen operation being performed. See the Zen Programmer’s Guidedocumentation for the values for specific operations.
If you want to perform a no-currency-change operation, use the KeyNumber property.
In Zen, indices are maintained with the data file, and these are numbered sequentially, zero representing the first index. You may use any index defined in the Zen file by specifying the index number of that index in this property. The value of this property is undefined for a data-only file.
Because Joins are dependent on the current index, changing IndexNumber will blank out any Joins that are in place.
See Also
Affects: Join
Affected by: TableName
IntegralHeight
Applies to
VACombo
Description
Causes the VACombo to adjust its size to account for differences in font sizes.
Remarks
When the IntegralHeight property is set to True, the list portion of the VACombo will adjust its size to account for differences in font sizes. Use this property to remove gratuitous space at the bottom of the list.
Join
Applies to
VAccess
Description
Restricts the records available to the control, and maintains relational positioning in the associated table relative to field values of another VAccess control.
Changing the IndexNumber or TableName property will erase the current join.
Name of the VAccess control to join. Records available to this control will be a subset of all of the records in the file associated with the control, limited by the criteria in the Join property of the control.
VAccessName
Name of the VAccess control which will serve as the master control data source for linking object.
joinedField
Name of a field or fields in the control referenced by VAccessName. Separate the names of multiple fields with commas. Each field named must be of identical storage type and length to the corresponding index segment of the selected index for object, as specified in the IndexNumber property.
Remarks
The Join property may be used to automatically synchronize related data files in one-to-one or one-to-many relationships.
VAccess controls may be joined together hierarchically by referencing index segments from the current index of one file to fields within another file. The Join property accomplishes this quickly, and automatically keeps the relationships updated during record navigation on any of the joined files.
To join one VAccess control to another, simply specify which index to use in the IndexNumber property, specify the name of the master VAccess control in the Join property, followed by a colon, followed by the names of the fields in the master control which will correspond exactly to values in the selected index of the joined control.
Example
Suppose you have four tables:
1 A table called Customers containing information about your customers, their names, addresses, phone numbers, and company codes, indexed by company name,
2 A table called Orders containing order header information fields such as CompanyCode, OrderNumber, OrderDate, TotalAmount, ShippingDate, etc, indexed by CompanyCode by OrderDate,
3 A table called OrderLineItems containing fields such as OrderNumber, LineNumber, Quantity, and ProductCode, indexed by OrderNumber by LineNumber,
4 And a table called Products containing ProductCode, Description, and Price, indexed by ProductCode.
To get a snapshot of an order beginning with a company name, join Orders to Customers by CompanyCode, join OrderLineItems to Orders by OrderNumber, and Products to Items by ProductCode (see Figure 7). Getting a Customer by company name will fetch all of that customer’s orders, all line items for each order selected, and the correct product information for any selected line item. Choosing a different order or a different line item will re-synchronize the data sets of all of the subsequent joined controls.
Figure 7 Example of Join Tables
See Also
Affected by: TableName, IndexNumber
KeyNumber
Applies to
VAccess
Description
Set to -1 in order to perform a no-currency-change Insert or Update operation.
Remarks
This property is not available in the property sheet. However, you can use this property to specify that you want to perform a no-currency-change Insert or Update operation. For example:
.KeyNumber = -1 ' No currency change (NCC)
See Zen Programmer’s Guidefor more information on no currency change (NCC) operations.
See Also
Affects: Insert, Update
List
Applies to
VACombo, VAList
Description
Returns or sets the items contained in a control’s list portion. The list is a string array in which each element is a list item. Available at design time for VAList and VACombo controls through the property browser if the controls are operating in field-bound mode; read-only at run time if the controls are operating in record list mode.
Syntax
object.List(index) [= string]
The List property syntax has these parts:
Part
Description
object
An object expression that evaluates to an object in the Applies To list.
index
The number of a specific item in the list.
string
A string expression specifying the list item.
Remarks
Use this property to access list items. If empty, the index is -1. The first item in a list is 0 and the index of the last item is ListCount -1.
Initially, combo box and list box controls contain an empty list. For controls operating in record list mode (VARecordList property set True), the list is based on conditions that exist when the control is created at run time.
The List property works in conjunction with the ListCount and ListIndex properties. Enumerating a list from 0 to ListCount -1 returns all items in the list.
To specify items you want to display in a field-bound (VARecordList property False) VACombo or VAList control, use the AddItem method. To remove items, use the RemoveItem method. To keep items in alphabetic order, set the control’s Sorted property to Truebefore adding items to the list.
Using an Option Base = 1 statement in the Declarations section doesn’t affect the enumeration of elements in Visual Basic controls. The first element is always 0.
When the List index is outside the range of actual entries in the list box, a zero-length string (" ") is returned.
Example
'get the text of the most-recently-added list item
Text1.Text = VAList1.List(VAList1.ListIndex)
Location
Applies to
VAccess
Description
Sets or returns the drive, path, and file name of the Zen file associated with this control.
Remarks
At design time, the Location property defaults to the value of Table Location in the DDF definition of the file specified in the TableName property.
This property represents the operating system device, path, and file name of the database file associated with the control.
This property may contain a fully qualified path and file name, or a file name only. If it contains file name only, an Open method will attempt to open the file in the directory specified by the DdfPath property.
For more information on using the Location property, see the Zen Programmer’s Guide.
Returns or sets a value indicating whether a control can be edited.
Syntax
object.Locked [ = boolean]
The Locked property syntax has these parts:
Part
Description
object
An object expression that evaluates to an object in the Applies To list.
boolean
A Boolean expression that specifies whether the control can be edited. If True, the user can scroll and highlight the text in the control, but can't edit it. The program can still modify the text by changing the Text property; if False(default), user can edit the text in the control.
MaxBufferSize
Applies to
VAccess
Description
This property limits the number of bytes which will be allocated by the control for data passed to a Zen record manager operation.
Remarks
The maximum size of the data buffer for an individual Zen operation is 64 KB.
If ExtendedOps = True, the value of MaxBufferSize will determine the value of CacheRows if CacheRows is set to 0.
Setting this value too high for your current Zen configuration will result in status 97, data buffer length errors, being returned from record manager operations, especially on extended fetch operations where the entire data buffer is likely to be used in transferring data to and from the Zen record manager.
See Also
Affects: Rows, CacheRows
Affected by: ExtendedOps
MaxLength
Applies to
VAText
Description
Determines the maximum number of characters which a user may type into the VAText. A value of 0 represents no maximum.
Remarks
If the field associated with the control is an alphanumeric field, (Char, VarChar, LongVarChar data types) this property defaults to the field length stored in the VASize property. Otherwise, the default for the MaxLength property is 0, indicating no maximum.
OemString
Applies to
VAccess
Description
Setting this property True converts data stored in alphanumeric fields between ANSI and OEM character sets.
Remarks
Alphanumeric fields such as Char, VarChar, LongVarChar data types, may contain data stored in OEM character sets, generally extended DOS character sets for non-English-language data. This data will not display in Windows correctly unless it is converted to an ANSI character set.
The default value of this property is False. Setting this property Trueconverts from an OEM to an ANSI character set when the field data is read, and converts ANSI text to OEM text when the alphanumeric field information is used in index searches or is written back to the file.
OpenMode
Applies to
VAccess
Description
Sets or returns the open mode of the file associated with the control.
Remarks
This property determines the file open mode of the file associated with the VAccess control. Possible open modes are:
0 - normal 1 - accelerated access 2 - read only 3 - verify 4 - exclusive
Note Verify mode is deprecated. If you set OpenMode to Verify, the file opens in normal mode.
The default value for this property is zero (normal). For most purposes this is the mode of choice. Files may also be opened for exclusive access, which prohibits another process from opening the file, or in read-only mode, which prohibits the application from making changes to the file. The accelerated access and verify modes have no effect on database behavior.
The current value of OpenMode is used when a database is opened. To change the mode, you must close and reopen the database in question.
See Also
Affects: Open
OwnerName
Applies to
VAccess
Description
The OwnerName property allows you to specify a Zen owner name to be used when trying to open the file associated with the VAccess control.
Remarks
The owner name property may be supplied at design time, or, if the AutoOpen property is False, it may be set before the file is opened at run time.
If an incorrect owner name has been specified or if no owner name has been specified and the file’s owner name security does not allow the file to be opened in read-only mode, a dialog box will prompt the user to specify the correct owner name when the application attempts to open the file.
OwnerName is used by the method SetOwner.
Example
'Close the currently opened file
Customers.Close
'Set the location and owner name information
Customers.DdfPath = "v:\accounts"
Customers.TableName = "customer002"
Customers.Location = "cust002.dat"
Customers.OwnerName = "password"
'Open the file
Customers.Open
See Also
Affects: Open, SetOwner
PageSize
Applies to
VAccess
Description
Sets or returns the page size of the Zen data file.
Remarks
Setting this property prior to invoking the DdfCreateTable method determines the page size of the resulting data file.
For existing data files, this property returns the page size used by the file. Setting this property for an existing file has no effect.
The range of valid page sizes depends on the file version of the Zen data file:
•512 bytes to 4,096 bytes for file versions prior to 9.0 (a multiple of 512 bytes up to 4,096 bytes)
•512; 1,024; 1,536; 2,048; 2,560; 3,072; 3,584; 4,096; or 8,192 for file version 9.0 (values are in bytes)
•1,024; 2,048; 4,096; 8,192; or 16,384 for file versions 9.5 and newer (values are in bytes).
Any operation which causes a new status buffer to be retrieved from the file will reset this value (see Stat).
See Also
Affects: DdfCreateTable
Affected by: Stat, TotalRecords
Percentage
Applies to
VAccess
Description
Sets the record to retrieve at the specified relative position along the currently selected index path in the associated Zen file, or returns the relative position of the current record.
Syntax
object.Percentage [= value]
The Percentage property syntax has these parts:
Part
Description
object
An object expression that evaluates to an object in the Applies To list.
value
A long integer value in the range 0 to 10000, corresponding to a percentage between 0.00% and 100.00%. Setting this property at run time will retrieve the record at that approximate percentage along the current index path. Reading this property at run time returns a value in the same range representing the position of the current record.
Remarks
Setting this property at run time performs a Zen GetByPercentage operation on the associated file. The status of the operation is returned in the Status property of the control, a status of zero indicating success. Reading this property at run time performs a Zen FindPercentage operation and returns the result of the operation. The range of values is 0 to 10,000 (or 0 to 0xFFFFFFFF if you specify a granularity; see Get By Percentage (44) and Find Percentage (45) of Btrieve API Guide), representing 0.00 to 100.00 percent. The accuracy of the percentage operation is subject to various conditions.
If the ExtendedOps property is False, setting this property at run time performs a GetByPercentage operation on the associated file. If ExtendedOps is True, setting this property will move the current Row property value to the specified percentage within the current extended operations buffer.
If the ExtendedOps property is False, reading this property at run time performs a FindPercentage operation and returns the result of the operation as the property value. If ExtendedOps is True, the returned value will represent the percentage of the current row within the current extended operations buffer.
Example
'to establish positioning on a record half way
'through the current index path
Customer.Percentage = 5000
'to set the scroll box of a scroll bar to
'the current record's position
VScroll1.Max = 10000
VScroll1.Min = 0
VScroll1.FieldValue = Customer.Percentage
See Also
Affects: Buffer
Port
Applies to
VAccess
(DEPRECATED - former I*net Data Server only.) Sets or returns the port number the client will use to communicate with the IDS. This property is ignored if the VAccess control is not trying to access remote data via the IDS.
Remarks
The value of this property should only be changed if the IDS port number has been changed. If the client port and IDS port settings are different, the client will be unable to connect to the IDS.
The default value for all of the IDS client components is 2441.
If the port property is changed while the ActiveX is connected to an IDS host, the change will not take effect until the next connection is attempted.
►To force a port change to take effect
1 Set HostConnect to False.
2 Change the port number.
3 Reset HostConnect back to True to force the new connection to operate on the new port setting.
Position
Applies to
VAccess
Description
Returns the value of the physical position of the current record in the Zen table associated with the VAccess control. Sets the physical position value to be used by the subsequent methods that require a physical position.
Remarks
This property is not available at design time.
The Position property is a long integer which uniquely identifies an individual record in a Zen file. Setting this property prior to invoking a GetDirect method will retrieve the record identified by this property directly, without making an indexed search of the file.
You can use the value of this property to keep “bookmarks” to individual records in a data file as you retrieve them.
The data control keeps track of whether or not the Position property value is current. If the property value is read when it is not current, the control will make a GetPosition call to return the current value. Setting this property value in code marks the value as current internally, but does not change current positioning, which may be done by calling the GetDirect method.
Example
Dim bookmark As Long
'Get the first of a number of duplicate key entries,
RefreshLocations determines whether the VAccess control will use DDF files for meta data or whether it will use internal states and/or persisted properties for meta data. If RefreshLocations is True, then the VAccess control will act as a passthrough to the DDF files—all requests for meta data will be re-read directly from the DDF files.
Metadata manipulations will affect only the VAccess control’s memory image of the metadata. You must explicitly call DdfAddTable, and so forth, to persist your changes.
If this property is True, the table metadata associated with the ActiveX Data Source control will be read when the control is instantiated. This property prevents the ActiveX control from constantly refreshing the DDF information.
If RefreshLocations is set to False, you can redistribute applications that use ActiveX without the corresponding set of DDF files, assuming the DDF set never changes, because ActiveX can persist DDF information.
Remarks
To modify your DDF files:
1 Set RefreshLocations to True.
2 Retrieve the current DDF information (RefreshLocations = True, so it will be directly from the file).
3 Modify IndexList and FieldList as desired. The changes will be stored to the VAccess memory image)
4 Call DdfAddTable to commit the changes to the DDF files themselves.
Setting this property at run time specifies the current row in an extended fetch record set for the FieldValue and RowPosition properties.
Remarks
The Row property is used in conjunction with the Column property to specify which field value in an extended fetch record set the FieldValue property will reference. The range of the Row property is 1 to the index of the last row if AutoMode is False. If AutoMode is True, setting Row to a value higher than this range will cause the VAccess control to attempt to perform extended fetch operations until the request can be satisfied or a non-zero status is returned. The Rows property will be updated as a result.
This property is not available at design time.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
Example
Dim total As Currency
Dim count As Integer
'This example only adds up 1 GetNextExtended Op buffer
This property returns the Zen physical record position of the record corresponding to a Row in an extended fetch record set.
Remarks
This property is not available at design time, and is read-only at run time. It can be used to establish current positioning on or to lock a particular record retrieved by an extended fetch operation. It will contain valid data only after a successful extended fetch operation has been performed at run time, or, if the AutoMode property is True, after the extended operations Init method has been invoked at run time.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
See Also
Affected by: ExtendedOps, Row
Rows
Applies to
VAccess
Description
Returns the number of rows of data returned by an extended fetch operation.
Remarks
This property is not available at design time, and is read-only at run time. It will contain valid data only after a successful extended fetch operation has been performed at run time, or, if the AutoMode property is True, after the extended operations Init method has been invoked at run time.
If the AutoMode property is True, the Rows property will reflect the total number of rows cached since the last time the extended operations Init method was invoked for this control. Otherwise it will reflect the number of rows returned by the last extended fetch operation performed.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
Lists the fields to be returned in an extended fetch record set.
Remarks
Fields specified in the SelectedFields property correspond to Columns in the record set returned by an extended fetch operation.
Field names in the SelectedFields list must be valid field names for the table referenced by the VAccess control, and must be separated by commas.
Leaving this property blank will assign all of the fields defined for the data file to columns in the extended fetch record set. The columns will be ordered according to the offset of each field within the record (the same order in which the fields appear in the DDF definition for the file.)
If a value is specified for this property, the order of the columns returned will correspond to the order in which the fields are listed in the SelectedFields property, not necessarily in the order in which they occur in the DDF definition for the file.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
Example
Dim allnames as String
If OptionButton1 = True Then
allnames = "msa_desc, population"
else
allnames = "msa_desc, prev_population"
End If
VAccess1.SelectedFields = allnames
'we must call getFirst to establish valid position
The SelectedRecords property allows you to specify filter conditions to limit the range of records which will be returned in an extended fetch record set.
Syntax
object.SelectedRecords = fieldnameoperator (fieldname or "constant")[[conjunction fieldnameoperator (fieldname or "constant")]...]
The SelectedRecords property syntax has these parts:
Part
Description
fieldname
The name of a field to filter by value, may be any valid field in the file referenced by object. It does not necessarily have to be one of the fields specified in the SelectedFields property.
operator
One of the following logical operators: > (greater than), < (less than), = (equal to), <> (not equal to), >= (greater than or equal to), or <= (less than or equal to).
constant
A constant value. Constant values must be preceded and followed by quotation marks (Chr$(34)).
conjunction
If more than one filter comparison is required, comparisons must be joined by one of the following conjunction operators: & (and) or | (or).
Remarks
Leaving this property blank performs no filtering, i.e., returns all records in the order in which they occur the current index path.
Comparisons of string fields are case sensitive unless the fields were flagged as being case-insensitive when the table was defined. Parentheses are not supported; filter terms are resolved logically in the order in which they occur.
When comparing text fields to constant values, the SelectedRecords filter compares the lesser of the number of characters in the constant or the number of characters in the field. For example, consider the following filter:
city = "B"
This filter returns any records in which the first character in the city field is "B". For example, the cities Baltimore, Boise, Boston, and Butte would be included.
The ExtendedOps property must be set to True to enable the extended operations capabilities of the VAccess control.
The Init method must be invoked before SelectedRecords filter will take effect.
See Also
Affected by: SelectedFields, ExtendedOps, Init
SessionID
Applies to
VAccess
Description
Sets or Returns the Session ID the client will use.
Remarks
This sets the last two bytes of the client ID used for the BTRVID call. This should be set when transactions are going to be used with the control. In addition to providing thread-safe transactions, this will also provide application-safe transactions. Setting this will also increase the number of seats used on the server, however.
See Also
Affects: All Btrv operations
Status
Applies to
VAccess
Description
Returns the Zen status from the last Zen operation on the file associated with the VAccess control. For a list of Zen status codes, see the Status Codes and Messages help installed with ActiveX Controls for Zen.
See Also
Affected by: All Btrv operations
TableName
Applies to
VAccess
Description
TableName indicates which table, from the set of all tables defined in the DDF set specified by the DdfPath property, will be associated with the control.
When a valid TableName is set, the control will close the current file and try to open the requested table at the current location if AutoOpen = True. If TableName is invalid, the control will not be able to open the file or retrieve data successfully.
This property cannot be used to change the name of the current table. DdfModifyTableName can be used for this purpose.
Note In order to retrieve the dictionary information for a table, RefreshLocations must = True.
(DEPRECATED - former I*net Data Server only.) Sets or returns the time, in seconds, that the client will wait for a response from the IDS before reporting a connection time-out error. This property is ignored if the VAccess control is not trying to access remote data via the IDS.
Remarks
If this wait limit is exceeded, the control will fire the CommError event with a Winsock error of WSAETIMEDOUT. This limit applies only to a subset of possible Winsock operations, due to Winsock implementation issues. This value will likely only need to be changed if a time-out is occurring due to very low bandwidth or a number or recoverable errors.
The default value is 120.
TotalRecords
Applies to
VAccess
Description
Returns the number of records contained in the Zen file associated with the VAccess control.
Remarks
Since the total number of records may change due to other users, retrieving this value forces a Stat call in order to ensure an accurate record count. As a result, properties that reflect aspects of the status buffer will be overwritten by this property. Properties affected include PageSize, PercentFreeSpace, PreallocatedPages, and ReservedDupPointers. Additionally, performing this on a remote file will cause a stat request to be performed at the remote site, which may slow down the application.
Example
Dim NumRecords as Long
NumRecords = VAccess1.TotalRecords
See Also
Affects: PageSize
Affected by: Stat
Uppercase
Applies to
VAText
Description
Sets or returns the type of case formatting applied to the text of a VAText.
Remarks
There are three possible settings:
•0 - No Case Forcing
•1 - Uppercase
•2 - Lowercase
If this property value is 0, text in the text box will appear as typed. A value of 1 will force all text in the text box to uppercase. A value of 2 will force the text in the text box to lowercase.
Specifies which data source object (VAccess control) to bind to the data aware control.
Remarks
For record navigation controls, VACommand, VAHScroll, and VAVScroll, the VAccessName property defines the control’s binding.
Field bound controls, VACombo in field bound mode, VAList in field bound mode, VACheck, VAOption, and VAText, also require that a valid field name be supplied in the VAFieldName property in order to bind. At design time, setting the VAccessName properties makes the list of fields associated with the VAccess control available in the VAFieldName property.
VAAutoScroll
Applies to
VAList
Description
Setting this property False prevents the currently selected VAList item from automatically scrolling to the top of the list if the list is used as an auto-fill record list (VARecordList = True).
Remarks
The default behavior of the record list VAList (VARecordList = True) is to keep the current record as the first item in the listbox, whether or not the positioning was changed by the listbox or by other means, such as a scrollbar or a GetEqual command. If VAAutoScroll is False, this default behavior is defeated and the VAList moves the current record to the top of the list only when positioning is changed by a source other than the listbox itself; i.e., clicking on an item in the listbox will reposition the VAccess control, but will not change the items in the listbox.
VADataType
Applies to
VACheck, VACombo, VAList, VAOption, VAText
Description
Sets or returns the data storage type code of the field bound to a field control.
Remarks
The VADataType property specifies the data storage type of the data field bound to the control.
Selects or disables Debug mode error checking for the controls.
Remarks
This property can be useful when you are designing or debugging an application. Setting this property True will enable Debug level error checking. Setting VADebugMode False will disable error checking.
VADecimal
Applies to
VACheck, VACombo, VAList, VAOption, VAText
Description
Sets or returns the number of fixed decimal places for fixed decimal data type fields.
Remarks
For fixed decimal numeric storage fields such as the Numeric and Decimal data types, the VADecimal property returns the number of places which should display to the right of the decimal place for the field associated with the control. The number of decimal places comes from the DDF file associated with the VAccess control in the VAccessName property of the control.
Only certain fixed-decimal numeric storage data types use this property. It is also used by the Bit data type to specify bit position. Xtrieve also used this field in the DDF dictionary to specify the value of the delimiter character for a Note field.
This property is not available at design time.
VAErrorDialog
Applies to
VACommand
Description
Determines whether a dialog box is presented to the user when a Zen operation fails.
Remarks
If this property is True, the application will display a dialog box to the user at run time if the Zen operation performed by the command button fails.
If this property is False (default), the control will not post a dialog box at run time to inform the user if the operation performed by the command button has failed. Instead, the status code indicating the error condition will be available in the Status property of the VAccess control.
VAFieldName
Applies to
VACheck, VACombo, VAList, VAOption, VAText
Description
Sets or returns the field name for the field associated with the control.
Remarks
For field-bound controls, this property sets or returns the field name for the field to which the control is bound. Setting this field to a valid field name from the VAccess control specified in the VAccessName property of the bound control binds the control to the specified field within the current record.
If the VAccess control is in extended operations mode and field selection criteria have been specified in the SelectedFields property of the control, the valid field names to which a field bound control may bind are limited to the set of valid ColumnName values for the VAccess control (the fields listed in SelectedFields).
This property is also used with the VACombo control to implement a special index selection combo box. This allows the user to select the desired index path during program execution. To make the VACombo an Index Section box, choose [Index List] for the value of the VAFieldName property.
For VAList control in multi-column record list mode (VARecordList property is True), the VAFieldName property can contain a list of fields separated by semicolons.
VAFormat
Applies to
VACombo, VAList, VAText
Description
This property permits you to specify format strings for the field values displayed by the control.
Remarks
See the Visual Basic Language Reference documentation of the Format function for a list of valid format strings and their meanings.
For VAList control in multi-column record list mode (VARecordList property is True), the VAFormat property can contain a list of formats (one for each field specified in the VAFieldName property of the control) separated by semicolons.
The VAFormat property exists to arrange your data using format strings similar to those used in Visual Basic. The common Visual Basic format strings (see Table 32) are predefined and there is also support for custom formats for dates and numbers. See the Visual Basic Language Reference for information on how these work.
Table 32 Common Visual Basic Format Strings
Format String
Description
(Empty String)
Default format. Displays numbers using General Number format, currency amounts, using the Currency format, dates and times using the using the General Date format, logical fields using True/False format.
General Number
Display number as is, with no thousand separators.
Currency
Display number with thousand separator, if appropriate; display two digits to the right of the decimal separator. Note that output is based on system locale settings.
Percent
Display number multiplied by 100 with a percent sign (%) appended to the right; always display two digits to the right of the decimal separator.
True/False
Display False if number is 0; otherwise, display True.
General Date
Display a date and/or time. For real numbers, display a date and time (for example, 4/3/93 05:34 PM); if there is no fractional part, display only a date (for example, 4/3/93); if there is no integer part, display time only (for example, 05:34 PM). Date display is determined by your system settings.
Long Date
Display a date according to your system’s long date format.
Short Date
Display a date using your system’s short date format.
Long Time
Display a time using your system’s long time format: includes hours, minutes, seconds.
Short Time
Display a time using the 24-hour format (for example, 17:45).
Custom numeric formats can be used similar to the formats provided by Visual Basic, but not all options are supported.
•Embedded string literals - + ( ) $ can be used. This allows one to format a phone number, i.e. (000)000-0000
•Other embedded strings using '\' or "" will not work.
•Customized scientific notation will not work.
•'0' placeholders work correctly. Float values will display fractional digits unless explicitly restricted.
•'#' placeholders work for integers. Float values may be truncated unexpectedly and will display fractional digits unless restricted.
When using day-of-the-week displays, rounding errors can result in the wrong day being shown for times close to midnight.
Example
VAccess1.TableName = "Billing"
VAText1.FieldName = "Amount_Due"
VAText1.VAFormat = "Currency"
VAText2.FieldName = "Log"
VAText2.VAFormat = "mmm ddd yyyy"
VALockBias
Applies to
VACommand
Description
Sets the lock bias for the Zen operation specified in the VAOperation property of the VACommand control.
Remarks
Zen supports both single and multiple record locking. If record locking is used, a record is locked when it is read. The VALockBias property has no effect if Open, Close, Insert, Update, or Delete operations are specified in the VAOperation property.
Single record locks are released whenever another record is read, or a record is inserted, updated, or deleted. Multiple record locks may be released on individual records or on all locked records by invoking the Unlock method for the control.
Lock failure retries are your responsibility as programmer.
VAOffset
Applies to
VACheck, VACombo, VAList, VAOption, VAText
Description
Sets or returns the storage offset of the bound field in the record buffer.
Remarks
The offset comes from the DDF file associated with the VAccess control in the VAccessName property of the control. This property is not available at design time.
VAOperation
Applies to
VACommand
Description
Sets or returns the Zen operation performed when the VACommand is pressed.
Remarks
The following record operations are available to this property:
Table 33 Record Operations Available for VAOperation Property
0 - Open
Opens the associated Zen data file.
1 - Close
Closes the associated Zen data file.
2 - Insert
Inserts the contents of the current record buffer as a new record.
3 - Update
Updates the current record with the contents of the record buffer.
4 - Delete
Deletes the current record.
5 - Get Equal
Retrieves the first record in the current index path with a key value which exactly matches the key value specified.
6 - Get Next
Retrieves the next record in the current index path.
7 - Get Previous
Retrieves the previous record in the current index path.
8 - Get Greater
Retrieves first the record in the current index path with a key value greater than the key value specified.
9 - Get Greater or Equal
Retrieves the first record in the current index path with a key value greater than or equal to the key value specified.
10 - Get Less
Retrieves the last record in the current index path with a key value less than the key value specified.
11 - Get Less or Equal
Retrieves the last record in the current index path with a key value less than or equal to the key value specified.
12 - Get First
Retrieves the first record in the current index path.
13 - Get Last
Retrieves the last record in the current index path.
VARecordList
Applies to
VACombo, VAList
Description
Setting this property True changes the mode of the list box or combo box control from a field-bound control to a record browser.
Remarks
The VARecordList property causes the list control to be filled with as many records as it can hold. The top item of the list is the current record (unless the VAAutoScroll property is set to False, in which case the selected list item represents the current record).
When VARecordList = True, several added features are available and may be accessed at design time via buttons on the property page. The VAFieldName and VAFormat properties, which are limited to one entry when the control is in field-bound mode (when the VARecordList property is False), can contain a list of fields and formats, respectively, separated by semicolons. In addition, the VAAutoScroll and ColumnWidth properties become active.
VASearch
Applies to
VAText
Description
Allows the VAText to become a browsing text field.
Remarks
The VAFieldName property becomes invalid on that control, and all properties used to describe the current bound field become invalid. Instead, the textbox remains synchronized to the first segment of the current index in the VAccess to which it is bound. Any change by the user to the textbox’s contents will result in a GetGreaterOrEqual being performed on the VAccess control. The contents will change to reflect changes in the positioning of the VAccess caused by other controls (e.g., a scrollbar move or a GetEqual command), but the text will remain highlighted.
VASize
Applies to
VACheck, VACombo, VAList, VAOption, VAText
Description
Returns the size of the data associated with the currently selected field. The size comes from the DDF file associated with the VAccess control.
VAValueFalse
Applies to
VACheck, VAOption
Description
Sets or returns the storage value which indicate that the check box or option button is not selected.
Remarks
VACheck and VAOption controls will appear selected only if the VAValueTrue property value is found in the logical field. When a selected VACheck or VAOption is turned off, the VAValueFalse property is placed in the field associated with this control. Placing a 0 in this property will cause a character value of 0 to be written to a 1-byte logical field, or an integer value of 0 to be written to a 2-byte logical field. The numeric value range is dictated by the logical field size: 0 to 255 for 1-byte logical fields, -32768 to 32767 for 2-byte logical fields.
VAValueTrue
Applies to
VACheck, VAOption
Description
Sets or returns the storage value which indicate that the check box or option button is selected.
Remarks
VACheck and VAOption controls will appear selected only if the VAValueTrue property value is found in the logical field. When a selected VACheck or VAOption is turned on, the VAValueTrue property is placed in the field associated with this control. Placing a 1 in this property will cause a character value of 1 to be written to a 1-byte logical field, or an integer value of 1 to be written to a 2-byte logical field. The numeric value range is dictated by the logical field size: 0 to 255 for 1-byte logical fields, -32768 to 32767 for 2-byte logical fields.
