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

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 PSQL server. This property is ignored if the VAccess control is not trying to access remote data via the IDS.

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.

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.

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.

Logon event

Affects: Location, Ddfpath

VAccess

Setting the AutoMode property to True will automatically execute PSQL 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.

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

Affects: GetNextExtended, GetPreviousExtended, StepNextExtended, StepPreviousExtended, Init, Row

Affected by: ExtendedOps

VAccess

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.

Affects: Location, DdfPath

VAccess

Sets or returns the contents of a control’s current record buffer. The record buffer is the raw record data retrieved by PSQL.

The Buffer property syntax has these parts:

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

Affected by: Clear, GetDirect, GetEqual, GetGreaterOrEqual, GetLessOrEqual, GetFirst, GetPrevious, GetNext, GetLast, StepFirst, StepPrevious, StepNext, StepLast, Percentage.

VAccess

This property corresponds to the maximum reject count parameter in the PSQL extended get operation structure (see the Get Next Extended documentation in the PSQL Programmer's Guide).

Specifying a value for the CacheRejectMax property limits the number of records which PSQL 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 PSQL 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.

Affects: GetPreviousExtended, GetNextExtended, StepPreviousExtended, StepNextExtended

Affected by: SelectedRecords, ExtendedOps

VAccess

The CacheRows property determines the maximum number of rows to return in any single PSQL extended fetch operation.

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

Affects: Rows

Affected by: ExtendedOps, MaxBufferSize, SelectedFields, Init

VAccess

If the AutoMode property is set to True, setting the CancelDialog property to True will 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.

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.

Affected by: ExtendedOps, Row, AutoMode

VAccess

This property specifies which column in an extended fetch record set is the current column for the FieldValue and ColumnName properties.

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.

Affects: ColumnName, FieldValue, RowColumnValue

Affected by: ExtendedOps

VAccess

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.

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.

Affected by: Column, SelectedFields, ExtendedOps

VAccess

The Columns property returns the number of columns defined in an extended fetch record set.

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.

Affected by: ExtendedOps, SelectedFields

VAList

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:

Affected by: VARecordList

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.

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.

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.

If security is enabled for the database, the user will be prompted for the user name and password by the MicroKernel Engine.

The default value is blank (empty string).

PSQL Programmer's Guide for more information on database URIs.

Affects: HostAddress, HostConnect

VAccess

Returns or sets the length in bytes of the record data buffer used for single-record operations on the file.

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.

Affected by: Buffer

VAccess

Specifies whether or not the VAccess should use the true indexes of the file or the indexes as specified in the DDF.

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.

Affects: IndexList

VAccess

Sets the drive and path on which the DDF files associated with this control reside.

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.

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)

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

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

UNC (\\server\path\datafile) can be used as a DdfPath entry as well, where the server can be either a PSQL 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 PSQL 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.

Affects: Location, GetTableList, IndexList, FieldList

Affected by: RefreshLocations, HostAddress, HostConnect, OnRemote event

VAccess

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.

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.

The default value is False.

PSQL Programmer's Guide.

Affects: GetTableList, FieldList, IndexList, DdfModifyTableName, DdfModifyLocation, DdfGetFieldComments, DdfAddTable, DdfDropTable, DdfAddIndex, DdfDropIndex, DdfDropIndexMaintain, DdfCreateTable, DdfCreateDictionary, DdfAddTableName, DdfClearIndexes, DdfClearFields, DdfSetOwner

Affected by: RefreshLocations

VAccess

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.

If this property is False (default), the VAccess control will navigate the PSQL data file and retrieve records using single record fetch operations.

Affected by: AutoMode, CacheRows, CancelDialog, Column, Columns, ColumnName, MaxBuffersize, Row, RowPosition, Position, Rows, SelectedFields, SelectedRecords, RowColumnValue, FieldValue, CacheRejectMax, Init, GetNext, GetPrevious, StepNext, StepPrevious, GetNextExtended, GetPreviousExtended, StepNextExtended, and StepPreviousExtended.

VAccess

Sets or returns a variant array containing information on the fields of the current table as specified by DdfPath and TableName.

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.

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

Affected by: DdfTransaction Mode, RefreshLocations

VAccess

Returns the total number of fields defined for the associated file.

Affects: FieldList, Join, FieldNumber

Affected by: FieldList

VAccess

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.

The FieldValue property syntax has these parts:

Data is read from and written to the current record in memory. Changes made to the record are not saved in the PSQL 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.

Affected by: ExtendedOps, Row

VAccess

Returns the PSQL file version of the current table via a PSQL stat call.

This property indicates the PSQL feature set incorporated in the data file when the table was created. It corresponds to the earliest version of PSQL which can access the table.

VAccess

Enables or disables event firing for the VAccess control.

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.

VAText

When this property is set to True, the text in the VAText will be selected when the text box receives focus.

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.

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

Affects: DdfPath, Location

Affected by: HostConnect

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.

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.

Affected by: DdfPath, Location, HostAddress

VAccess

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.

Setting the value of this property to True will begin the next extended fetch operation at the current record position in the file (equivalent to setting the “UC” constant in a PSQL extended fetch API record request structure). Setting the value of this property to False will begin the next extended fetch operation at the subsequent record position in the file (equivalent to setting the “EG” constant in a PSQL extended fetch API record request structure). This property is automatically set to True after the Init method is invoked, and is automatically reset to False after 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.

Affects: GetNextExtended, GetPreviousExtended, StepNextExtended, StepPreviousExtended

Affected by: ExtendedOps, Init, GetNextExtended, GetPreviousExtended, StepNextExtended, StepPreviousExtended

VAccess

Sets or returns a variant array containing information on the indexes of the current table as specified by DdfPath and TableName.

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:

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.

Affected by: RefreshLocations, DdfPath, TableName, DdfTransactionMode

VAccess

Sets or Returns the current index number for the PSQL table associated with the VAccess control.

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 PSQL operation being performed. See the PSQL Programmer's Guide documentation for the values for specific operations.

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

In PSQL, 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 PSQL 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.

Affects: Join

Affected by: TableName

VACombo

Causes the VACombo to adjust its size to account for differences in font sizes.

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.

VAccess

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.

The Join property syntax has these parts:

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.

Suppose you have four tables:

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.

Affected by: TableName, IndexNumber

VAccess

Set to -1 in order to perform a no-currency-change Insert or Update operation.

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:

See PSQL Programmer's Guide for more information on no currency change (NCC) operations.

Affects: Insert, Update

VACombo, VAList

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.

The List property syntax has these parts:

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 True before 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.

VAccess

Sets or returns the drive, path, and file name of the PSQL file associated with this control.

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 PSQL Programmer's Guide.

Affected by: DdfPath, TableName, RefreshLocations, HostAddress, HostConnect, AutoOpen, OnRemote

VAText

Returns or sets a value indicating whether a control can be edited.

The Locked property syntax has these parts:

VAccess

This property limits the number of bytes which will be allocated by the control for data passed to a PSQL record manager operation.

The maximum size of the data buffer for an individual PSQL 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 PSQL 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 PSQL record manager.

Affects: Rows, CacheRows

Affected by: ExtendedOps

VAText

Determines the maximum number of characters which a user may type into the VAText. A value of 0 represents no maximum.

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.

VAccess

Setting this property True converts data stored in alphanumeric fields between ANSI and OEM character sets.

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 True converts 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.

VAccess

Sets or returns the open mode of the file associated with the control.

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

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.

Affects: Open

VAccess

The OwnerName property allows you to specify a PSQL owner name to be used when trying to open the file associated with the VAccess control.

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.

Affects: Open, SetOwner

VAccess

Sets or returns the page size of the PSQL data file.

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 PSQL data file:

Any operation which causes a new status buffer to be retrieved from the file will reset this value (see Stat).

Affects: DdfCreateTable

Affected by: Stat, TotalRecords

VAccess

Sets the record to retrieve at the specified relative position along the currently selected index path in the associated PSQL file, or returns the relative position of the current record.

The Percentage property syntax has these parts:

Setting this property at run time performs a PSQL 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 PSQL 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.

Affects: Buffer

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.

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.

VAccess

Returns the value of the physical position of the current record in the PSQL table associated with the VAccess control. Sets the physical position value to be used by the subsequent methods that require a physical position.

This property is not available at design time.

The Position property is a long integer which uniquely identifies an individual record in a PSQL 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.

Affects: GetDirect

Affected by: ExtendedOps, Row, GetDirect, GetEqual, GetFirst, GetGreater, GetGreaterOrEqual, GetLast, GetLess, GetLessOrEqual, GetNext, GetNextExtended, GetPrevious, GetPreviousExtended, StepFirst, StepLast, StepNext, StepNextExtended, StepPrevious, StepPreviousExtended

VAccess

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.

To modify your DDF files:

Affects: FieldList, IndexList, DdfModifyTableName, DdfModifyLocation, DdfAddIndex, DdfDropIndex, DdfDropIndexMaintain, DdfClearIndexes, DdfClearFields, DdfSetOwner, DdfGetFieldComments, TableName, DdfPath, DataLength

VAccess

Setting this property at run time specifies the current row in an extended fetch record set for the FieldValue and RowPosition properties.

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.

Affects: FieldValue, RowColumnValue, Position, RowPosition, GetPrevious, GetNext, StepPrevious, StepNext

Affected by: ExtendedOps, AutoMode, GetPreviousExtended, GetNextExtended, StepPreviousExtended, StepNextExtended, Init

VAccess

This property returns the PSQL physical record position of the record corresponding to a Row in an extended fetch record set.

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.

Affected by: ExtendedOps, Row

VAccess

Returns the number of rows of data returned by an extended fetch operation.

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.

Affected by: ExtendedOps, CacheRows, GetPreviousExtended, GetNextExtended, StepPreviousExtended, StepNextExtended

VAccess

Lists the fields to be returned in an extended fetch record set.

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.

Affects: SelectedRecords, CacheRows, Columns, ColumnName

Affected by: SelectedRecords, ExtendedOps, Init

VAccess

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.

The SelectedRecords property syntax has these parts:

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:

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.

Affected by: SelectedFields, ExtendedOps, Init

VAccess

Sets or Returns the Session ID the client will use.

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.

Affects: All Btrv operations

VAccess

Returns the PSQL status from the last PSQL operation on the file associated with the VAccess control. For a list of PSQL status codes, see the Status Codes and Messages help installed with ActiveX Controls for PSQL.

Affected by: All Btrv operations

VAccess

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.

Affects: FieldList, IndexList, IndexNumber, Join

Affected by: DdfAddTableName, DdfAddTable, DdfModifyTableName

VAccess

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

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.

VAccess

Returns the number of records contained in the PSQL file associated with the VAccess control.

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.

Affects: PageSize

Affected by: Stat

VAText

Sets or returns the type of case formatting applied to the text of a VAText.

There are three possible settings:

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.

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

Specifies which data source object (VAccess control) to bind to the data aware control.

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.

VAList

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

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.

VACheck, VACombo, VAList, VAOption, VAText

Sets or returns the data storage type code of the field bound to a field control.

The VADataType property specifies the data storage type of the data field bound to the control.

This property is not available at design time.

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

Selects or disables Debug mode error checking for the controls.

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.

VACheck, VACombo, VAList, VAOption, VAText

Sets or returns the number of fixed decimal places for fixed decimal data type fields.

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.

VACommand

Determines whether a dialog box is presented to the user when a PSQL operation fails.

If this property is True, the application will display a dialog box to the user at run time if the PSQL 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.

VACheck, VACombo, VAList, VAOption, VAText

Sets or returns the field name for the field associated with the control.

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.

VACombo, VAList, VAText

This property permits you to specify format strings for the field values displayed by the control.

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.

Custom numeric formats can be used similar to the formats provided by Visual Basic, but not all options are supported.

When using day-of-the-week displays, rounding errors can result in the wrong day being shown for times close to midnight.

VACommand

Sets the lock bias for the PSQL operation specified in the VAOperation property of the VACommand control.

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

VACheck, VACombo, VAList, VAOption, VAText

Sets or returns the storage offset of the bound field in the record buffer.

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.

VACommand

Sets or returns the PSQL operation performed when the VACommand is pressed.

The following record operations are available to this property:

VACombo, VAList

Setting this property True changes the mode of the list box or combo box control from a field-bound control to a record browser.

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.

VAText

Allows the VAText to become a browsing text field.

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.

VACheck, VACombo, VAList, VAOption, VAText

Returns the size of the data associated with the currently selected field. The size comes from the DDF file associated with the VAccess control.

VACheck, VAOption

Sets or returns the storage value which indicate that the check box or option button is not selected.

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.

VACheck, VAOption

Sets or returns the storage value which indicate that the check box or option button is selected.

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.