Macro language - commands

If the ` symbol is used at the beginning of a macro line, that line is ignored while the macro is played - so it can be used to insert Comments or ‘programming notes’ into the macro. In fact, any text that makes no sense is ignored by the playing process anyway, so the ` character is most useful as a way of temporarily disabling certain lines of macro that otherwise do make sense. Using the ` character will be slightly faster, as it means the playing process will not have to check against all Command possibilities.

Emulates the pressing of the [√] button or any other Accept-type button (eg [OK], [Find] or an bold button) by ‘pressing’ the Enter key.

This Command works as for the Confirm Command, but has only one button, and therefore is merely an alternative method to the Message Command of giving warnings or making comments for the benefit of macro users.

The first parameter is actually the only one required by the system, and specifies the text of the message to be passed to the user. Be sure to enclose your text in quotation marks.

Alert (variable) 

If you wish to use an Alert to illustrate the value of a variable, do not enclose the variable name in quotation marks.

Alert (string(non-alpha variable))

The second parameter, which is optional, changes the default button text setting of [OK] to any text required, up to a limit of approximately 10 characters.

Alert can also be used to display the value of a variable. This is useful if you want to test the value of a variable at a certain point in your macro. Also, you may have a single macro used for displaying Alerts which you call from other macros, in which case you will need to store the Alert message as a variable.  

Emulates pressing the key.

This produces a Beep sound.

The button Command can be used in place of the Click Command to emulate a Click on the buttons palette, assuming that the buttons palette is in its standard position.

It is useful because, unlike the Click command, the x and y coordinates are relative to the top left hand corner of the palette window. This makes it possible to use a relatively simple calculation to work out what x and y values to specify in order to click a specific button. The buttons are 26 pixels deep and 26 wide. The top ‘drag’ bar containing the close box is 10 pixels deep, and the cross-bars are 6 pixels deep. Therefore given that a suitable starting point for clicking the top left-most button (Cancel) is 15;25, one can work out that, for example, the Enterprise 6 button in the bottom right is 15+26 = 41; 25+(26*10)+(6*3) = 303.

The above method is used by the Recording process, but there are also easier commands to use to ‘press’ a button if you are creating a macro by text input. These commands, such as Accept, Cancel and New Record each emulate a button in the buttons palette.

Emulates the pressing of the [X] button or any other Cancel-type button (eg [Cancel], [Quit] or any non-bold button in which the only alternative is bold).

Case statements are a useful time and space-saving alternative to If Statements where a single course of action needs to be chosen from multiple alternatives. Each alternative should be enclosed in brackets and preceded by a colon.

For example:

mInput:=Request ("Please Specify Option 1, 2 or 3")

Case of  

:(mInput="1")      

macro ("Do this")  

:(mInput="2")      

macro ("Do that")  

:(mInput="3")      

macro ("Do the other")

Else  

Alert ("You didn’t specify 1, 2 or 3")

End case

Nested Case Statements can be used, as can intermixed Case and If Statements. 

The Click Command emulates single mouse clicks, and will optionally accompany it with a click sound.

The first two Parameters, for x and y cursor position, should be numbers that fall within the range of your screen size. For example a 13/14” Monitor has a screen size of 640 by 480 pixels. The third Parameter is a number defining any Modifier or control key to be emulated at the same time as the click. Its possible values are as per the table shown for the Key Command. NB: The Click position is ‘absolute’ within the whole Monitor space, which means that it is dependent upon screen size, and upon a window being where it is expected. See Limitations below for further details. 

This Command asks Enterprise 6 to bring up a dialogue box asking the user to answer a question before proceeding with the macro.

The window is in the same style as all normal Enterprise 6 two button Dialogues.

The first parameter is actually the only one required by the system, and specifies the text of the message to be passed to the user. Be sure to enclose your text in quotation marks.

Confirm (variable)

If you wish to use an Confirm to illustrate the value of a variable, do not enclose the variable name in quotation marks.

Confirm (string(non-alpha variable)) 

The second and third parameters are optional, and change the default button text settings of [OK] and [Cancel] to any text required, up to a limit of approximately 10 characters.

You should use the If statement to control the consequences of a Confirm in the following manner:

Confirm ("Do you want to?";"Yes";"No") 

If (OK=1)

Alert ("Thank you ...")

... rest of macro 

Else

Alert ("OK, quitting macro") 

End if

Confirm can also be used to display the value of a variable. This is useful if you want to test the value of a variable at a certain point in your macro. Also, you may have a single macro used for displaying Confirms which you call from other macros, in which case you will need to store the Confirm message as a variable. The second and third parameters are again optional in this situation.

works in the same way as Confirm and takes the same parameters. The difference is that it displays a larger window containing the Enterprise 6 logo and colour shading, rather than the standard 4D Confirm window.

In addition, it has a title area, which can be set by a fourth parameter, and an optional fifth parameter can specify the number of seconds before the window will automatically Accept itself and put itself away. Also, it does not play the Confirm sound.

In this example, the window stays on screen for 5 seconds before assuming that it is OK to continue:

ConfirmT ("Do you want to try it?";"Yes";"No";"MACRO CHAPTER HEADING";5)

An alternative example shows the window title contained in a variable and the ‘Confirm’ message loaded in using the macro Text command. This is useful if you have a single generic Confirm macro which needs to display different titles at different times.

Execute(mTitle:="MACRO CHAPTER HEADING") ConfirmT (Macro Text("Try It macro");"Yes";"No";mTitle;5)

It is a good idea to only use the Confirm command at the beginning of a macro because otherwise the window that appears (which requires user input) might easily be confused with one that appears and is then automatically answered by the processing of the macro itself.

Emulates the [Count] button.

Emulates the [Dial] button.

Emulates /<Alt>-clicking [Dial], which shows you all possible Telephone Numbers.

The Double Click Command works as for Click above, but emulates a mouse double-click.

The Evaluate Command can be used to run, by typing it into the Evaluate (◊CompCode) single Parameter slot, any 4th Dimension calculation or Enterprise 6 procedure that returns a String or character-format result. The result is then emulated as keystrokes in the same way as the Key Command.

Thus one could calculate 10*5, but would need to use the 4D Syntax of: String (10*5)

The Current Date function is one of many 4th Dimension functions available, and the 1 that follows it in the example above is a 4D Parameter of the String Command, which formats the date as required. See the 4D Manual for further details.

The ◊CompCode and ◊User Parameters  are two of the more useful of Enterprise 6’s own internal variables that can also be evaluated. They result in the last used Company’s Code being typed or the current user’s initials being typed. Only ‘interprocess’ variables are useful in this context because the process that runs the Playback is wholly independent of the process it is acting upon. For this reason, inserting field values here will not work.

NB: It is possible to cause 4D error messages to appear during the playback of a macro with Evaluate Commands if faulty logic is used.

Emulates the [Find] button.

Emulates /<Alt>-clicking [Find], which goes straight to More Choices.

Emulates the [First Record] button.

For ... End for loops are fully supported in the macro language. They are used to repeat a section of code a specified number of times.

The first parameter contains the counter variable, which will be incremented automatically. This is the main difference between a For loop and a While loop: in the latter, the counter variable is incremented by an explicit line within the loop.

The second parameter contains the initial value of the counter variable and the third parameter is the final value of the counter variable.

The fourth, optional, parameter, contains the size of the increment. If absent, this will be 1.

The following example will display the numbers 1-20 on screen individually:

For (mCounter;1;20)  

Message (String(mCounter))

End for

This next example features a negative increment. The counter variable (mCounter) initially has a value of 20. While it is greater than 5, the code within the loop will be followed. Each time this happens, mCounter is reduced by 5.

mStart:=20

mEnd:=5 mIncrement:=-5

For (mCounter;mStart;mEnd;mIncrement)      

mValue:=100*mCounter

…rest of macro 

End for

Note that there is a limit of five nested loops of all types (While, For, Repeat) within macros. This limit does not apply to If or Case of statements.

Assuming it does not exist already, this will create a Further Field for the File with the Field Name specified.

The third and fourth parameters are optional. If Type - which should be A, D, N or T - is not given then the new field will be assumed to be an A (alphanumeric).

Use of the command will be rare, however, because both the FurthFld Set and FurthFld Get Commands will create a Further Field if it does not exist. Since these Commands do not have parameters for Type or Format, though, they can only create Further Fields of Type A.

This command should be used to find records with a given Further Field value. The fourth parameter is optional.

The function also returns as a numeric variable the number of records found.

The first two parameters should contain the File Name and Further Field Name. The third is the search string, which must always be presented as a string even for Number or Date Further Fields. If the fourth parameter is specified the search will be carried out between the From and To values specified.

The following example is used to find and display Company records with a specific Further Field value. The ‘vNo’ variable is used throughout Enterprise 6 to display the number of records in the top right of listing windows:

Start Process `needed to initiate values for the display method below

vNo:=FurthFld Find("Companies";"Date of Audit";"1/1/98";"1/2/98") `Will find all Companies whose Date of Audit falls in January 1998

If(vNo>0)    

Companies File    

Open Pro Window("Very Important Companies")    

MODIFY SELECTION([COMPANIES];*)    

Close ProWin

End if

This command is used to obtain the value stored in a Further Field attached to a particular record.

The third parameter is optional: if used it should contain the unique Code of the relevant record, such as a Company Code. If left unspecified, the value of the relevant Further Field of the current record in the specified File will be taken: the command will be used in this fashion if working through a list of records.

returns a value in string format: if obtaining a value from a numeric or date field, it should be converted using Num or Date before being used in calculations. If reference is made to a Further Field that does not exist, it will be created and given a Field Type of A (alphanumeric).

This command is used to alter the value stored in a Further Field attached to a particular record.

The third parameter should contain the value to be saved, in a string format. Numeric or date information should first be converted using the String command.

The fourth parameter is optional: if used it should contain the unique Code of the relevant record, such as a Company Code. If left unspecified the relevant Further Field of the current record in the specified File will be altered: the command will be used in this fashion if working through a list of records.

FurthFld Set returns an error code, as follows:

The function returns an integer: 0 if the command was completed without a problem, 1 if the Value could not be set (perhaps because the record was locked by another user), or 2 if the parameters were invalid. If reference is made to a Further Field that does not exist, it will be created and given a Field Type of A (alphanumeric).

Emulates the [Global Change] button.

Emulates the [Graph] button.

Any number of levels of If statements can be included within a macro. Whatever is contained within brackets after the If command is evaluated by 4D and must return a value of either True or False - any other result is invalid.

Examples of If statements are as follows:

Statement  - Result

If (1=1)  - True If (mBoolean) True or False according to the value of the Boolean variable

If ((mText="@this@")& (mText#"that"))  - True if the mText variable contains ‘this’ and does not equal ‘that’

If (Screen width>640) - True if the user’s monitor has more than 640 pixels across. This and any other 4D function many be used within statements.

Note that is it not valid to attempt to access Field values within these Statements, since the macro that is doing the evaluating does not access any records.

The If statement must be complemented by a subsequent End if statement. An Else statement can optionally be used to specify what should be done if the result of the If statement is False.

The format of a single-level If, Else, End if is as follows:

If (i=1)

... Macro Text used if True

Else

... Macro Text used if False

End if

Multiple levels can be designed as follows:

If (i=1)

If (j=1)  

... Macro Text used if True & True

Else  

... Macro Text used if True & False

End if

Else

If (j=1)  

... Macro Text used if False & True

Else  

... Macro Text used if False & False

End if

End if

Note that the indented spacing displayed above is not automatically calculated by the macro Editor - spaces have been manually typed for clarity.

The usage of If statements, combined with other macro Commands discussed earlier can be further illustrated by the following useful example:

Execute (ProcessCalc)

Execute (mNo:=Find in array(◊aPN;"View Companies"))

If (mNo>0)

If (◊aPS{mNo}="Awaiting Event")  

Alert ("I’m waiting")  

Execute (BRING TO FRONT (mNo+3))

Else  

Alert ("I’m not waiting")

End if

Else

Alert ("You haven’t chosen ‘View Companies’")

End if

Alert ("The End")

The ‘ProcessCalc’procedure is used to update the Enterprise 6 arrays that contain the names and stati of current Processes, as used by the ‘Processes’ menu function. The result of the 4D ‘Find in array’ function is then assigned to the variable ‘mNo’, returning the Enterprise 6 process number of ‘View Companies’ if it exists, or -1 if it doesn’t. If it does exist, and then if the status array contains the text ‘Awaiting Event’, it tells you that it’s waiting, and uses a 4D command to bring the View Companies process to the front. The variable mNo happens to need 3 added to it in order to convert between Enterprise 6’s and 4D’s version of the Process number.

The Key Command emulates keystrokes, and takes one of the or (nAscii;nModifiers) two forms shown here.

While a macro is being Played, and if the ‘Don’t Play Volume Notes’ Preference is not set, sounds are generated that emulate the noise of typing.

The first Parameter can be either character(s) enclosed in quotes to be directly typed - eg "M" or "Enterprise 6" - or can be a single number, representing the Ascii code of a character - eg 13 or 65.

The second Parameter must be a number, and must be a multiple of 256. It represents the Modifiers or control keys that are to be emulated at the same time as the main character. Its value can only be one of the following, or a summation of them

Command/Control 256

Shift 512

Caps Lock 1024

Option/Alt 2048

Control 4096

Example summation: command-Shift 768

NB: The Modifiers are not applied if multiple characters are specified in the first parameter. There is also an easier way of ‘pressing’ certain keys, using commands such as Accept, Cancel and Tab.

Emulates the [Last Record] button.

This command allows you to nest your macros within each other, reducing the need to duplicate large chunks of macro text for different macros that perform similar functions.

The single parameter must be specified as the Code of a saved macro, either as text or using a variable to which the Code was assigned earlier. If the macro specified cannot be found, an error message will result. The number of nested levels is limited by memory as each creates a new process.

Note that a macro cannot call itself. Examples of this command are as follows:

Macro ("ANOTHER")

Macro (mMacro)

Macro ("~"+mMiddle+mEnd)

While macro simply calls and runs another macro, macro Result calls and runs the macro and accepts a numeric result back from the called macro. The result is of real number format.

The macro being called should load a numeric value into a variable called ‘vmResult’ (it must be exactly this name). If it does not, the result will always be zero.

The format is as follows:

Macro Result ("MacroCode") when used in the 4D Report Generator or Statistics View

SRVar:=Macro Result ("MacroCode") when used in SuperReport.

A Enterprise 6 procedure is available that can be used to load the text of a saved ‘Macro’ record into a variable or a Confirm window. This method saves time in constructing macros that use large volumes of text because it otherwise has to be done by means of many lines.

For example:

Execute (mText:=Macro Text ("CODE"))

or

ConfirmT (Macro Text ("CODE");"Yes";"No";"Title")

The Menu Command emulates the selection of menu options Menu ("Volume") within Enterprise 6.

Menu ("Macros palette")

Menu ("Macros palette Off")

This Command is one that it will be hard for the user to create without going through the Recording process, and actually choosing the relevant option from a menu. This is because it uses vital Parameters that are defined by the internal workings of Enterprise 6, which is not intuitive.

All of the possible options cannot be listed here, but could, perhaps, be Recorded in a library macro for future reference. In its first form above, three Parameters are used to launch new processes.

The first, "Proc", is the name of the Enterprise 6 procedure called by a menu item. The second, nBytes, contains the amount of memory that you wish to allocate to the new process. The third, "Name", contains the process name which is to be displayed in the 4D Server window (if running multi-user) and the Processes window.

This information could be collected in a library macro, Recorded as the user accessed each menu item. In its second form, the Command is used to switch volumes. The third and fourth forms of the Menu Command allow you to automatically turn on and off the macros palette, which is useful for Startup macros that may need to be Paused or Stopped by the user.

The other palettes - "Buttons palette", "Functions palette" and "Volumes palette" - may also be called in this way.

The Menu command can also record and play back menu choices from Layout Menus. When you make a menu choice it is recorded in the macro text using the Menu Command, but with ‘-1’ as the second parameter, showing that a Layout Menu is to be activated.

For example:

Menu ("Orders PPQtnF";-1;"Quotation Form") is the equivalent of selecting ‘Quotation Form’ from the Print menu at the Sales Orders screen.

Menu ("Sel CritSave";-1;"Save Criteria…") is the equivalent of selecting ‘Save Criteria…’ from the Functions menu of a More Choices screen.

Menu ("Comp SelLP";-1;"Menu Item 4") is the equivalent of selecting the fourth item from the Find Menu of the Companies More Choices screen. In this case, the third parameter cannot contain the menu item’s name. If you choose Layout Menu items using Command keys rather than the mouse when recording a macro, they will be recorded as the Keystroke involved. New process-launching Menu items, by contrast are always represented by the Menu Command.

Emulates the [Enterprise 6] button.

A Message Command placed anywhere in a macro causes a window to appear on screen during playback. It is a palette window, so stays on top of most other Enterprise 6 windows. It is updated each time the command is issued.

The first parameter of this Command can be used to type any amount of text that you would like to appear in the window, though it will be neater if broken up into small chunks. You cannot use Carriage Returns within this Parameter, so it may be necessary to create multiple Message lines one after another.

The second parameter is used to specify where on screen the message window is to appear. The available options are “R”, “L”, “T”, or “B” for Right, Left, Top or Bottom respectively. The second parameter only needs to be used the first time the command is used in a macro, and if the command is used after the Message End command. The Message End command must be used if you need to move the window.

An example of this command opening a message window at the bottom of the screen is— Message ("This is the message";"B")

The Left position obscures the buttons palette, and the Bottom and Top positions are the width of the Enterprise 6 splash screen, but less deep. The window is automatically closed when the macro ends, and can be closed using Message End.

The first parameter - the text for the window - is evaluated as elsewhere. This means that it can use variables, and "..."+char(13)+char(13)+"..." can be used to insert two Carriage Returns between separate paragraphs of message.

This simply closes the current message window, and means that the next time the Message Command is used, you can reposition it.

Emulates the pressing of the [+] button, whether for adding a new record from a list, or a new included list line within an entry screen.

Emulates the [Next Record] button.

More flexible in many ways to Wait on Event, this Command can also be used to ask the user for input. It automatically turns on the [Pause] button within the macros palette. If the latter is not being used, it will automatically appear. The user is expected to do the relevant input then turn off the [Pause] button in the palette. This function should really be used in conjunction with the Message Command, because otherwise a user would not know what the macro was waiting for.

This Command plays a Sound as named by the first Parameter. Macintosh users can store sounds either in the System or in the Enterprise 6 application. The latter will take precedence, but sounds installed there will be lost when updates are installed. Windows users should use sounds with a .wav extension, and should specify that extension in the Parameter: Play("sound.wav").

The second Parameter is optional. Without it, the sound is played ‘synchronously’, which means that everything else stops during playback. If a zero is passed as the ‘sound channel’, the sound will be asynchronous, meaning that it will be played in the background while other processing continues.

Emulates the [Previous Record] button.

Repeat ... Until loops are fully supported in the macro language.

Their operation is similar to that of the While loop: whatever is within the brackets (following Until) is evaluated, returning True or False. While the result of the evaluation is True, the macro section preceding Until is repeatedly operated. As soon as the result is False, the macro will continue from the Until command.

To ensure that the macro will drop out of the loop at the correct time, you must ensure that the variable used as the test for the Repeat … Until statement can be altered by the macro section within the loop. If not, the loop will repeat for ever, although clicking the [Stop] button in the macros palette will halt the macro.

Unlike While loops, Repeat …Until loops will always be run at least once because the test occurs after the loop has been run.

The following Repeat … Until loop will be executed until mBoolean is set to True.

mBoolean:=False

Repeat  

If ...      

mBoolean:=True  

End if

Until (mBoolean=True)

Note that there is a limit of five nested loops of all types (While, For, Repeat) within macros. This limit does not apply to If or Case of statements. Report Generator Emulates the [Report] button. Return Emulates the <Return> key.

Emulates /<Alt>-clicking [Select], which selects non-highlighted items in a list.

Emulates the [Sets] button.

Emulates the [Sort] button.

This command, if included in a ‘Same Process’ macro will print a specified SuperReport containing information from a specified File.

The first parameter contains the name of the File to be printed - in this example the Companies file. The second parameter is the Code of the SuperReport that you want to print. If either of these is specified incorrectly a warning will appear. The third parameter, if omitted altogether or if set to 1, means that an intelligent approach is taken to selecting the records to print.

If a macro containing this command is run from a listing screen the records printed will be those currently highlighted. If none are highlighted, all listed will be printed. When the macro is run from an entry screen only the record on screen will be printed. This means that the same macro can be employed to print in both scenarios without having to worry about coding changes. If the third parameter is set to 2 all the current records in selection (whether you’re in an entry or a listing screen) will be printed.

Emulates the <Tab> key.

This causes the Payback to wait for the specified number of seconds before continuing.

Wait (◊Speed*5)

It is important for many macros that they are paused in this way, because otherwise a new window may not have appeared before the macro tries to type into it. You can specify the number of seconds of the Wait using the first of the two alternative forms of syntax. Use the second syntax if you wish to use a variable or a calculation as the parameter.

The ◊Speed variable is calculated by Enterprise 6 when it starts up and is machine and network dependent. To test it for your machine, create a single line macro as follows: 

Alert(String(◊Speed)).  

places the macro into a waiting loop until the Process State of the Process it is controlling matches that of the single numeric parameter given.

The most useful parameter is 2, (‘Waiting for user event’), which specifies that the macro is to wait exactly as long as is necessary for the process it is controlling to be ready to receive the next command or keystroke. This method inherently adjusts itself for different Client and Network speeds, and eliminates the frustrating over-cautious waits inherent in the other Wait commands.

When a macro is being recorded, Wait for State is used if any pauses occur. Therefore, if you placed any deliberate pauses in the process, you will have to subsequently insert those Waits manually into the macro.

When recording, the macro recorded will never start with a Wait for State. If there is a reason for having a macro start in this way, the command will again have to be inserted manually. The Wait for State Command allows you to specify an ascii character referring to the various Process States available as its single parameter. These are:

Wait for state (0) - Executing

Wait for State (1) - Delayed

Wait for State (2) - User event

Wait for State (3) - Input/output (ie caching)

Wait for State (4) - Internal flag

Wait for State (5) - Paused

The Process Number of the Process controlled by the macro is held in a variable named ‘◊RecPlayProc’, which can be used within If statements in the macro. For example, the following checks that the Process exists at all before carrying out instructions:

If (Process State (◊RecPlayProc)>=0)  

...

End if

Wait for State should not be used in Startup Background processes unless they bring up windows on screen for user input.

This command forces the Playback to wait until the user performs the required action - ie he or she Clicks the mouse or presses the specified key. If the action is not done within the space of 2 minutes, the Playback is aborted.

This function should really be used in conjunction with the Message Command, because otherwise a user would not know what the macro was waiting for.

The Wait on Event Command allows you to specify an ascii character as the event it waits for. These are:

Wait On Event (5) Waits for

Wait On Event (1) Waits for

Wait On Event (27) Waits for

Wait On Event (4) Waits for

Wait On Event (96) Waits for <`>

Wait On Event (31) Waits for

Of these, perhaps or are the most useful because they are rarely used in Enterprise 6, and are available on every keyboard. The other arrow keys are 28 to 30.

If waiting for <Return>, <Tab> or <Enter>, the following syntax can be used:

Wait On Event (Return) Waits for <Return>

Wait On Event (Tab) Waits for <Tab>

Wait On Event (Enter) Waits for <Enter>

Up to 5 nested While loops can be included in macros.

The While statement’s format is similar to that of an If statement: whatever is within the brackets is evaluated, returning True or False. While the result of the evaluation is True, the macro section preceding End while is repeatedly operated. As soon as the result is False, the macro will continue from the End while.

To ensure that the macro will drop out of the While loop at the correct time, you must ensure that the variable used as the test for the While statement can be altered by the macro section within the While loop. If not, the While loop will repeat for ever, although clicking the [Stop] button in the macros palette will halt the macro.

The following example of its use forces the user to choose ‘View Companies’, and then to put it away again:

Execute (ProcessCalc)

Execute (mNo:=Find in array(◊aPN;"View Companies"))

Alert ("Please choose 'View Companies then put it away")

Wait (5)

While (mNo=-1)

Alert ("You haven't chosen 'View Companies'")

Wait (5)

Execute (ProcessCalc)

Execute (mNo:=Find in array(◊aPN;"View Companies"))

End while

Wait (5)

While (mNo>0)

Alert ("I'm waiting for you to put it away again")

Execute (BRING TO FRONT (mNo+3))

Wait (5)

Execute (ProcessCalc)

Execute (mNo:=Find in array(◊aPN;"View Companies"))

End while

Alert ("Well done!")