Commence V4.0 Vbscript Notes

Commence v4.0 VBScript Notes

Compiled by Glenn Krejci

Revised 99/06/21

Introduction

Scope of Commence VBScript

Example Applications

Glossary

Coding a Commence VBScript

Common Run-Time Errors

Commence VBScript Objects

Commence Fields

Sample Code

Bugs and Issues

Appendix A: WinEdit VBScript Syntax Coloring INI File

Introduction

These notes document Commence VBScript introduced in Commence v4.0 and offer some programming guidance. These notes do not document the Commence API introduced in Commence v4.1.

Microsoft VBScript is a full-featured programming language subset of Microsoft Visual Basic that has been incorporated into Commence to automate detail form data processing. This integration requires additional VBScript functionality specific to the Commence environment. This integration of Microsoft VBScript with Commence is referred to as Commence VBScript.

These notes were compiled to assist the use of Commence VBScript. They are not intended to document Microsoft VBScript for which Microsoft documentation is readily available at

Commence v4.0 shipped with Microsoft VBScript v1.0. The current Microsoft VBScript engine is v5.0. This VBScript engine is typically and automatically upgraded when a new version of Microsoft Internet Explorer is installed.

Additional assistance with using Commence VBScript can be found on the newsgroup commence.vbscript on the newsgroup server mail.csgroup.com.au, which is sponsored by the independent Commence Users Group,

While Commence VBScript allows VBScript routines to interact with a Commence detail form object, the Commence API is an automation interface (formerly OLE) that permits external applications to interact with the Commence database object model. For documentation on the Commence v4.1 API, see the document "Of Cursors and Rowsets" available in the technical notes section at And also see the document dbapi.hlp in your Commence Workgroup folder.

Scope of Commence VBScript

Commence (the application) defines the scope within which VBScript is allowed to operate. Commence tells VBScript which Commence objects it may operate on. Commence VBScript currently only supports these objects: Application, Form, Field, Connection, and Err (error).

Commence tells VBScript what Commence object PROPERTIES will be available to it.

Commence tells VBScript what Commence object METHODS will be available to it.

Commence tells VBScript what Commence object EVENTS it will respond to.

Commence VBScript is limited to operations that affect detail form navigation, data entry, and the saving of detail form items. That said, the full depth of the VBScript programming language is available to the programmer.

Typical detail form operations using Commence VBScript include:

Read/Write direct field values.
Read-Only indirect connected field values (one connection away only).
Count indirect connected items.
Calculate/Construct/Deconstruct field values.
Navigate tabs and fields.
Guide user data entry.
Request user data input.
Validate field values. Check entered data immediately prior to saving and workgroup synchronization.
Display messages.
Save/Cancel/Abort data entry.

Example Applications

Batch processing
VBScript can be used in conjunction with agents to achieve batch script processing of data.

Person name field parsing
VBScript can parse a Person name field into its component title, first name, middle name, last name, and suffix fields. Or in reverse, these component fields could be combined to create the Person name field.

Protect/Lock fields
VBScript can prohibit a field from being changed by the user.

Roll-Up summary reporting
VBScript can process connected item data and then deposit summary results in direct fields. A script could get cleverer by creating HTML report content for output via export, printing, or DDE.

Glossary

by value, ByVal - a way of passing the value, rather than the address, of an argument to a procedure so that the procedure can not change the actual variable's value.

direct vs. indirect field - this document considers a direct field to be a field belonging to the current item of the open detail form, and an indirect field is a field belonging to any item connected to the current item.

event - an instance of behavior of an object.

event procedure - a VBScript procedure that executes automatically in response to the specific object event for which it is defined. The actual body code of the procedure, what it does, is defined by the programmer respective of its scope of operation. VBScript-initiated object events do not generate subsequent event procedures to avoid indefinite looping. Commence user-initiated detail form event procedures are the base procedures around which a Commence VBScript is constructed.

keyword - a word or symbol recognized as part of the VBScript language.

method - an operation or function that is performed by VBScript. The methods available are dependent upon the object on which a script is operating.

object - an instance of an entity defined by its VBScript properties and methods.

property - a named attribute of an object that defines an object characteristic such as size, color, or state.

Coding a Commence VBScript

Coding conventions

Use mixed-case to improve readability.
Indent each code level two spaces or more.
Use verb-noun comments. Example: 'Set Person name field.
All VBScript parameters are case sensitive. Respect case when naming variables.
All executable code must be contained in procedures. A procedure is defined at script-level; it can not be defined within another procedure.

Object-Referencing syntax

object.property
object.method, where method returns a property
object.method.property, where method returns an object having property
item(argument list), where item can be a property, a method that returns an object or property, or a function. Arguments are typically listed as (1, 2, 3).

Commence data type and formatting

All Commence field values read and assigned to a VBScript variable exhibit the variant data subtype of String. Therefore, use an appropriate VBScript data type conversion function on these values to avoid data type mismatch errors in subsequent script execution.
The following expression uses the conversion function CSng to convert a Commence number field string to a single-precision, floating-point number in preparation for a numeric calculation and assigns it to the variable AH:
AH = CSng(Form.Field("Administrative Hours").Value)

In general, field values read exactly as they appear on a detail form. Field values read prior to any field formatting imposed by Commence will not exhibit that formatting.

Installing a Commence VBScript

Create the VBScript source code in a text file using your favorite text editor.

Install (Check In) that VBScript file against a specific detail form in your Commence database. That VBScript code will automatically execute each time that specific detail form is opened.

Once installed, the source VBScript text file is not required by Commence. A good place to store these source files is in a subdirectory of the database directory such as c:\mydata\vbscript\ where they will be backed up and/or restored whenever a database backup or restore is performed.

Once uninstalled (Check Out), that VBScript code will no longer be executed. It will be saved to a text file where it can be modified using your favorite text editor. This step is only required if you need to reconstruct the source code from that within Commence. Typically you will just revise the original source code text file and reinstall.

You can have Commence automatically launch your default text editor by pressing the shift key while pressing the Check Out button. However, if you can adopt the FAST! method noted below, you will not use this function.

Installing/Editing a Commence VBScript FAST!

Here is an alternative method for installing a Commence VBScript quickly. If you can not meet the prerequisites, you may be able to modify this method to suite your needs.

Prerequisites:

All VBScript source files for a given database are stored in the same directory relative to the database directory. For instance, if your Commence database is in the directory c:\mydata\, you should store all of its VBScript source files in the directory c:\mydata\vbscript\.

Each VBScript source file must be named after its respective category. For instance, person.vbs, appointment.vbs, company.vbs, etc.

All eligible categories have one detail form each of the same name. For instance, each category in your database has only one detail form defined and it is named 'Initial Form'.

A report view for the category you wish to check in a script must be open, active, and must list one or more items.

Create this agent:

VBScript Check In

trigger is Menu Pick, VBScript Check In, VBScript Check In, (all), (all), Ctrl + Alt + C, action A is Send DDE, Trigger, file is (-programexe-), application is Commence, topic is (-databasename-), execute message is [CheckInFormScript((-category-), "Initial Form", (-databasepath-)\vbscript\(-category-).vbs)]

To check in a script:

Setup prerequisite 4) above to establish the (-category-) keyword. From Commence, select Tools/VBScript Check In or press Ctrl + Alt + C. The desired VBScript file will be checked in, no questions asked.

Similarly, if you use the text editor WinEdit, create this agent to edit a Commence VBScript quickly:

VBScript Edit

trigger is Menu Pick, VBScript Edit, VBScript Edit, (all), (all), Ctrl + Alt + E, action A is Application Launch, trigger, c:\winedit\winedit.exe, (-databasepath-)\vbscript\(-category-).vbs, maximized

To edit a script:

Setup prerequisite 4) above to establish the (-category-) keyword. From Commence, select Tools/VBScript Edit or press Ctrl + Alt + E. The desired VBScript file will be opened in WinEdit.

These FAST! methods will allow you to quickly go back and forth between editing and installing a Commence VBScript as you debug your code. Highly recommended.

Creating a Commence VBScript

Commence does not have a built-in text editor for creating VBScript code. You can use any text editor but a programmer's text editor offers many useful features.

A member of the Commence Users Group has created Scriptease, a shareware VBScript editor. It is available at

Another shareware programmer's text editor is WinEdit available from Wilson WindowWare at Read the readme before installation. There is/was a potential file (.dll) conflict that is easily resolved.

To configure WinEdit configuration files to color-code Commence VBScript syntax:

Edit the file \winedit\wechroma.ini to include the following lines:
[EXTENSIONS]
VBS=VBS
Create the text file \winedit\vbs.ini to contain the lines listed below in Appendix A: WinEdit VBScript Syntax Coloring INI File. These VBScript syntax color associations can be easily adjusted to taste using the reference list of RGB color values noted.

Common Run-Time Errors

Navigating to fields not displayed on the form

If a script attempts to navigate to a field that is not displayed on the form, the script will fail and generate a run-time error. A script can set values for fields that are not displayed on the form, but it can not navigate to those fields.

Operating on Commence connections

Commence VBScript commands do not support operations on connections and may yield unexpected results. Note: Commence v4.1 VBScript has additional methods for making/breaking connections.

Referencing invalid field names

If a script references an invalid field name, the script will fail and generate a run-time error that typically reads: Source:'' File:'Script' Line:1 Char:-1 Error:0 ''. Review your code for a mismatch between quoted field names and actual field names.

Referencing or navigating to invalid form tab name

If a script references or attempts to navigate to an invalid form tab name, the script will fail and generate a run-time error.

Setting object read-only properties

If a script attempts to set read-only object properties, the script will fail and generate a run-time error.

Commence VBScript Objects

VBScript command arguments shown in lower case are to be replaced by their actual program variable or value.

Command arguments shown in proper case are VBScript keywords, or they are variables assigned by VBScript. The programmer may rename these variables.

All values returned by Commence are of data subtype String unless noted otherwise.

All Commence VBScript object properties are read-only unless noted otherwise.

Application object

The Commence Application object allows access to settings that are global to the Commence application (and all detail forms).

Commence Application Object PROPERTIES
Property / Type / Description
Name() / string / name of application (Commence)
ProgramName() / string / filespec of application (c:\commence\commence.exe)
ProgramDirectory() / string / filepath of application directory (c:\commence\)
DatabaseName() / string / name of active Commence database (My Database)
DatabaseDirectory() / string / filepath of active Commence database directory (c:\mydata\)
DefaultScriptLevel() / number / maximum script level supported by this version of Commence
CurrentScriptLevel() / number / script level set by the script
To change the script level which controls the VBScript objects supported by Commence, assign the desired level to this property. The level must be greater than 0 and less than/equal to DefaultScriptLevel.
Commence Application Object METHODS
Method / Description
GetVersion() / returns Commence version number (4.0.x.y)
IsScriptLevelSupported(level) / returns 1 if the passed in script level is supported, else returns 0

Form object

The Commence Form object represents a detail form and allows access to the tabs and fields within a detail form. It is the default object referenced by Commence VBScript methods.

Commence Form Object PROPERTIES
Property / Type / Description
Name() / string / name of form
CategoryName() / string / name of category the form belongs to
ItemName() / string / name of current item (name field value)
TabName() / string / name of current tab
FieldName() / string / name of current field in focus
A connection field name includes both the connection name and the to-category name. For example, Related Date Appointment.
FieldValue() / variant / value of current field in focus
IsAdd() / Boolean / True if form is displaying a new/add item, else False
IsShared() / Boolean / True if form Share button is selected, else False (Workgroup product only)
Application() / object / contains the Application object
Use directly or copy to a variable and use in a script.
Commence Form Object METHODS
Method / Description
MoveToTab(tabname) / open tab whose name is passed as an argument
MoveToField(fieldname) / move cursor to field whose name is passed as an argument
This method can move the VBScript focus to a calculation field or sequence number field. The cursor will disappear but the detail form will scroll to the field. Although the user can not similarly tab into either of these fields, a calculation field can be entered with the mouse whereby its value is then accessible by VBScript, but the cursor will remain at its previous field position.
A connection field name includes both the connection name and the to-category name. For example, Related Date Appointment.
SetShared(numeric) / set state of Share button on form toolbar where numeric 1 is True/Shared and numeric 0 is False/Not Shared (Workgroup product only)
This method only applies to items not yet shared and will generate an error if executed on an existing shared item. This error can be avoided by using the expression: If Form.IsAdd Then Form.SetShared(0).
Save() / save item subject to errors detected by Commence
Does not generate a Form_OnSave event. Also, this command does not operate from within the Form_OnLoad or the Form_OnEnterTab event procedures.
Cancel() / cancel item and discard any changes
Does not generate a Form_OnCancel event.
Abort() / abort current event and return to preceding state
SetValue(variant) / set current field’s value to the passed in variant
Field(fieldname) / returns an OLE object (Idispatch interface) for the Field object representing the field whose name is passed as an argument
If error, the Err object will be set with error code ‘invalid arg’.
A connection field name includes both the connection name and the to-category name. For example, Related Date Appointment.
Connection(connectionname, tocategory) / returns an OLE object for the Connection object representing the connection whose name and to-category are passed as arguments
If error, the Err object will be set with error code ‘invalid arg’.
Commence Form Object EVENT PROCEDURES
Event Procedure / Description
Form_OnLoad() / called and executed immediately before detail form open
Commence item data is not yet accessible, including item shared status (Workgroup product only). Use this event procedure to initialize item-independent variables and state information such as loading form/entering tab for first time.
Form_OnSave() / called and executed immediately upon detail form close on save
Form_OnCancel() / called and executed immediately upon detail form close on cancel
Form_OnEnterTab(ByVal TabName) / called and executed immediately upon detail form tab enter
The variable argument TabName contains the name of the tab being entered and is passed to the procedure by Commence.
Form_OnLeaveTab(ByVal TabName) / called and executed immediately upon detail form tab exit
The variable argument TabName contains the name of the tab being exited and is passed to the procedure by Commence.
Form_OnEnterField(ByVal FieldName) / called and executed immediately upon detail form field enter
The variable argument FieldName contains the name of the field being entered and is passed to the procedure by Commence.
A connection field name includes both the connection name and the to-category name. For example, Related Date Appointment.
Form_OnLeaveField(ByVal FieldName) / called and executed immediately upon detail form field exit
The variable argument FieldName contains the name of the field being exited and is passed to the procedure by Commence.
A connection field name includes both the connection name and the to-category name. For example, Related Date Appointment.

Field object

The Commence Field object represents a single field from the item displayed by the Form object.

Commence V4.0 Vbscript Notes