Script Creation

Scripts are an advanced feature intended to be used by experts--usually computer programmers. They allow you to add functionality to the standard CAPITAL system and implement special system behaviours and requirements.

There are two ways in which CAPITAL Business Script can be linked to CAPITAL Office:

Attaching Script To a Screen Field

The first method involves attaching a script to a field using CAPITAL Screen Builder. In order to do this you must:

Start INSTALLATION Workshop.
Load the screen into Screen Builder (found on the Build menu).
Double-click on the field you want to attach the script to.
Click on the Formula tab.

You will now be able to enter a script that will be associated with this field.

For more information on the details of entering scripts see: Screen Builder Formulas

Using this method, the script attached to the screen field is executed each time the record is displayed and each time its contents are changed.

Attaching Script To a Screen

Another way to link business script to a screen is to create a separate file containing your script code. This file must have the extension .MAC.

From within Screen Builder, select Files|Script... to create or access a screen script. If a screen script does not exist, CAPITAL will create an empty one for you.

The following table lists the names you must use:

Screen	File Name
Stock Control	STOCK.MAC
Customer Accounts	CUSTOMER.MAC
Supplier Accounts	SUPPLIER.MAC
Service Manager Jobs	JOBCARD.MAC
Hire Manager Jobs	HIRE.MAC
Card Files	The file name must match up to the first 8 characters of the name of the card file and end with the extension .MAC. So if the card file name was "Card0001" the file name of the script would be "Card0001.mac"

The .MAC file is normally placed in the appropriate company directory. For example, if your company data location is C:\CAPITAL\MYFIRM then the .MAC file should be placed in the directory C:\CAPITAL\MYFIRM.

Alternatively, you may place the .MAC file in your program directory. CAPITAL will then execute the same .MAC file for all companies in your system.

For example, if STOCK.MAC is placed in your program directory CAPITAL will execute STOCK.MAC for each company you run. However, if you then decided to place STOCK.MAC in your company data directory, it would always be executed in preference to the one found in your program directory.

Note: CAPITAL will place any .MAC file it creates via the Script... menu command in your main directory by default. You will have to manually move it to your company directory if you intend to run different .MAC files for different companies.

Script Event Handling

If CAPITAL detects a matching script file it will execute its contents in response to certain events called "modes". The event type or mode can be found in the variable Mode.

Value of Mode	Event Type
0	A record was added to the screen.
1	The record is being edited.
2	The record is about to be deleted. If you return FALSE in response to this event the record will not be deleted.
3	The record is about to be saved. If you return FALSE in response to this event the record will not be saved.
4	The user requested that the note pad be opened.
5	The user requested that the record be printed. If you return FALSE in response to this event the record will not be printed.
6	A transaction has been totalled. (This event does not apply to record entry or editing.)
7	The user is about to leave the screen.
8	A transaction is about to be totalled. (This event does not apply to record entry or editing.)
9	The user is above to move to another field. The name of the field the user was last on will be stored in the variable 'Focus'. Note: This event is only triggered if the user has changed the contents of the field.
10	A new page of information is being displayed on the screen.
11	The user has clicked on a picture object with the left-mouse button.
12	The record has been saved. (Check for event 3 if you want to prevent a record from being saved.)

By inspecting the contents of the Mode variable you can decide to process or ignore certain events. For example, if the following script is placed at the top of your .MAC file only the delete event would be handled by the script:

If Mode # 2

Return

Endif

* ...

Several modes allow you to control the behaviour of CAPITAL. These include the delete, save and print modes. If you return the value of FALSE, CAPITAL will not proceed with the event the user requested.

If you decide to cancel an event in a script, it is important that you explain why. The following script demonstrates one correct way to cancel the printing of a form:

If Empty(SCRRead("PCode"))

Echo("Sorry, cannot print until product code specified.")

Return FALSE

Endif

Standard Screen Script Variables

A number of predefined variables are created for you to access or assign values to when running scripts.

ButtonPress

This variable will hold the value of TRUE if the script to be executed was triggered in response to a button press event.

This event can only occur if the script is attached to a field and a look-up button has been assigned to that field. Keep in mind that pressing F12 on the field next to the button causes the same event as pressing on the button with the mouse.

Focus

The code name of the field that the user is currently focused on. This includes code names such as "PCODE", "TITLE", "DATE" and so on. If the user is not focused on any particular field then Focus will contain an empty string "".

Mode

The list of available modes (events) that a script can respond to are listed in the above table. When writing scripts it is usually important to determine which modes you will respond to and ignore the rest.

PicNumber

The number of the picture object that the user clicked on with the left mouse button. The first picture object on the screen is numbered 1, the second 2, and so on. This variable is associated with Mode 11 (see the above table).

The following script executes the Shell() function on the contents of the field PATH1 when the first picture on the screen is clicked with the left mouse button.

If Mode == 11

If PicNumber == 1

Shell(SCRRead("Path1"))

Endif

The Shell() function executes the contents of PATH1, which is assumed to be a reference to a file name and path, based on the file's extension. For example, if this field contained a bitmap path and file name, whichever application associated with displaying graphics on the end-user's PC, would be executed.

Picture Objects

The variables PictureLocation and PictureFileName are used in the management of picture files. For more information on this topic see: Screen Builder Picture Objects.

____________________________