






BEACON Command Macro Guide




Version 0.5
February 15, 1986








Systems  Communications Group

Computing Services
School of Business Administration
University of Michigan
Contents





Introduction												2
Example 1: A Simple BEACON Command Macro												4
Example 2: Passing Parameters To BEACON Command Macros												5
Example 3: Error Checking				 In BEACON Command Macros								7
APPENDIX A: Creation of BEACON Submit Files												12
APPENDIX B: BEACON Command Macro Statements												13
	The University of Michigan's School of Business Administration has developed BEACON, a terminal emulation program for the Burroughs B25 workstation.  One powerful feature of BEACON allows users to write command macros which simplifies BEACONuser interaction.  This manual provides an introduction to writing userdefined BEACON macros.

	First, let's start with an overview of the operation of BEACON.  BEACON accepts quite a large number of local commands. For example, PORTLETTER is the local command which selects one of the serial ports.  Users enter local commands by first entering the <Move> key (which puts BEACON into local mode and displays a cursor in the Command: line of the lower screen).  Upon hitting the <Move> key, users must type a , then followed next by the name of the local command which they want, and then followed by any parameters needed for that command.  For example, if the user wants to select serial port A, they would enter the following keystroke sequence (without the double quote () characters).

	<Move>PORTLETTER=A<Return>

	Note that <Move> is the Move key and <Return> is the Return Key.
	Let's now discuss how BEACON interprets the keystrokes of the previous example (<Move>PORTLETTER=A<Return>).
	A) <Move>
This places BEACON in local command mode.  A cursor will appear in the Command: line in the lower portion of the screen.  In local command mode, BEACON will not echo each keystroke to the host.
	B) 
This instructs BEACON to interpret the current entry as a local BEACON command.  Actually, if users don't want the  character to designate local BEACON commands, they can change this character to any character using the PREFIX command.  Entries in the local command line which do not begin with  will not be interpreted as local BEACON commands and will be echoed to the host.
	C) PORTLETTER
This is the exact name of the local BEACON command to select a serial port.  Note that exact spellings are not required because BEACON only needs unambiguous abbreviations for all local commands.  (i.e.  PORT would be sufficient to designate this local command.)
	D) =
This is a delimiter which separates command names and parameters.  Note that =(equals), ,(comma) and  (space) are all delimiters and that one or more delimiters are used to separate entries in the local command line.
	E) A
This is a parameter needed by the PORTLETTER command.
	F) <Return>
This instructs BEACON to attempt to interpret this local command entry.  No interpretation is performed until the <Return> key is pressed.
	When an entry is made in local command mode which begins with  and is not a valid local BEACON command, then BEACON assumes that a userdefined macro is being invoke.  Upon issuing a macro, BEACON then looks for a file with the macro name (i.e. invalid BEACON command name) and then SUBMITs that file.  So, macros can be thought of as an automatic way of SUBMITing files.
	Actually, BEACON behaves slightly differently than what is described above.  The only difference is how BEACON searches for the macro file.  First, BEACON takes the macro name and appends the suffix .MAC to it.  Then, BEACON checks the current path for the file (macro name).MAC.  If the file exists, then BEACON will SUBMIT that file.  If the file does not exist, then BEACON will check for the file [Sys]<Sys>(macro name).MAC and SUBMITs that file if it exists.
Example 1:  A Simple BEACON Command Macro
	Let's start off with a simple example of a command macro.  In this example, we will give the alias LOGOUT to the BEACON command EXIT.  This will allow the user to enter either EXIT or LOGOUT to terminate BEACON.  Assume the following file exists on the current path.
	A) File Name				Logout.MAC
	B) File Contents
		<^Move>Exit<Return>
	Now, because the file Logout.MAC exists on the local path, the user automatically SUBMITs that file upon entry of the local command LOGOUT.  Note that in this example, entering LOGOUT is exactly the same as entering SUBMIT Logout.MAC which in turn behaves exactly like EXIT.  Refer to Appendix A for creation of BEACON SUBMIT files.


Passing Parameters to BEACON Command Macros
	So far, command macros appear to be equivalent to SUBMIT files.  One advantage command macros have over SUBMIT files is the ability to accept and manipulate parameters.  Within the command macro facility, there are 10 macro variables which are labeled 0 through 9.  This provides the capability for passing up to 9 parameters with each command macro.  When the user enters a valid command macro name with parameters, macro variable 0 is assigned to the number of parameters passed to the command macro, and macro variables 1 up through 9 are assigned to the parameters.  Note that macro variables are only assigned up through the number of parameters passed.  (i.e. If a command macro is passed 3 parameters then only macro variables 0 through 3 are reassigned).
Example 2:  Passing Parameters to BEACON Command Macros
	In the next example, let's provide the alias SELECTPORT for the BEACON command PORTLETTER.  For this example, we want the user to specify 1 parameter which is the serial port letter (A or B).
	A) File Name				SelectPort.MAC
	B) File Contents
		<^Move>MacroBegin<Return>
		<^Move>PortLetter=1<Return>
		<^Move>MacroEnd<Return>

	Now, when the user enters the local command SELECTPORT A, the above file is SUBMITed.  Also, macro variable 0 is assigned to 1 (because one parameter is passed) and macro variable 1 is assigned to A.  Let's analyze BEACON's behavior of the execution of this command macro from start to finish.
	A) <Move>SelectPort A<Return>
When the user enters this line, BEACON enters local command mode.  Because this local command starts with  and is not a standard BEACON command, BEACON assumes it is a command macro.  Upon verifying that the file SelectPort.MAC exists on the local path, BEACON parses any parameters and saves them in an internal BEACON table.  Then, BEACON SUBMITs the file SelectPort.MAC.
	B) <^Move>MacroBegin<Return>
Now BEACON's macro mode takes over.  Since this is a first level macro (i.e. in this case, a macro has not called another macro) all macro variables are assigned to their previous macro variable values.  Internally, BEACON uses the DEFINEKEY facility to define strings to the keys 0 through 9.  Initially, all BEACON macro variables have the string equivalent to their integer value.  Upon all executions of MACROBEGIN, the internal BEACON table is checked for parameters and the corresponding macro variables are updated.  In this case, 0 gets assigned to 1 (because 1 parameter is passed) and 1 gets assigned to A (the passed parameter).  Then, the internal BEACON table is cleared of these parameters.  Note that if you need to refer to the integers 0 through 9 in a macro file, you must refer to these digits with use of the <F5> key. (Literal Input Mode)
	C) <^Move>PortLetter=1<Return>
This line actually generates the local command PortLetter=A because the <1> key has the string A DEFINEKEYed to it.  This executes the BEACON command PORTLETTER which selects the proper serial port.
	D) <^Move>MacroEnd<Return>
This line terminates BEACON's macro mode (since this was a level one macro.)  Upon termination of BEACON's macro mode, the current values of the macro variables are saved, and the keys 0 through 9 are unDEFINEKEYed so that they behave normally for user interaction.
Example 3:  Error Checking In BEACON Command Macros

	In the previous example we saw how macros have the ability to accept user specified parameters.  For this example, we will introduce the remaining capabilities that are available from macros.  These capabilities include conditional execution of SUBMIT file contents, outputing messages to the Status: portion of the screen, reading input from the user, and assigning string values to macro variables.
	For Example 3, let's augment Example 2 so that it prompts the user for a <serial port letter> if no parameters are passed, and prints an error message if too many parameters are passed.  In general, the logic of the macro looks something like this...

	IF	(number of parameters passed is zero)
		prompt the user for the correct port letter
		assign the user's response to the first parameter macro variable
		set number of parameters passed as one
	ENDIF
	IF	(number of parameters passed is one)
		issue the PORTLETTER command with the passed parameter
	ELSE
		print an error message of TOO MANY PARAMETERS
	ENDIF

	The above pseudolanguage description of the SELECTPORT macro can be implemented with the introduction of the remaining BEACON macro mode commands.  These macro mode commands are MacroIf, MacroElse, MacroEndIf, MacroWrite, MacroResponse, and MacroAssign.  The file listed below is the implementation of Example 3.
	A) File Name				SelectPort.MAC
	B) File Contents
		<^Move>MacroBegin
		<^Move>MacroIf 0 '=' <F5>0
		<^Move>MacroWrite 'Hit <Move> and enter the desired Port Letter'
		<^Move>MacroResponse <F5>1
		<^Move>MacroAssign <F5>0 <F5>1
		<^Move>MacroEndIf
		<^Move>MacroIf 0 '=' <F5>1
		<^Move>PortLetter=1		
		<^Move>MacroElse
		<^Move>MacroWrite 'Too many parameters.  SELECTPORT [A|B]'
		<^Move>MacroEndIf
		<^Move>MacroEnd

	Let's analyze BEACON's behavior of the execution of this command macro from start to finish.
	A) <^Move>MacroBegin
Once again, BEACON enters macro mode, reassigns all macro variables to their previous (or initial) values, and then checks the BEACON internal table for parameters.  Remember, the key 0 is DEFINEKEYed to the string which is the number of parameters passed, and for each of the nine parameters which are passed, the corresponding keys 1 through 9 are DEFINEKEYed to the parameter value.
	B) <^Move>MacroIf 0 '=' <F5>0
This is BEACON's macro facility IF statement.  The first parameter to the IF statement is the string defined to the macro variable 0 (which is the number of parameters passed to this macro).  The second parameter is binary operator '=' (which must be surrounded in quotes).  The third parameter is the literal string 0 (not the contents of the macro variable 0).  If this condition is TRUE (i.e. the macro variable 0 equals the literal string 0) then BEACON continues to SUBMIT the next line of the file.  If this condition is false, BEACON will skip the contents of the file until the corresponding MACROELSE or MACROENDIF is encountered.  In general, MACROIF checks for equality of any two strings (only '=' is supported at this time).

	C) <^Move>MacroWrite 'Hit <Move> and enter the desired Port Letter'
This is BEACON's macro facility for outputing a message to the user in the Status: line at the bottom of the screen.  In this particular example, this output to the user is only performed if the above IF condition was TRUE (i.e. the user did not provide any parameters to this command macro).
	D) <^Move>MacroResponse <F5>1
This is BEACON's macro facility for assigning user input to a BEACON command macro variable.  In this case, user input is assigned to BEACON's macro variable 1.  In this particular example, this assignment is only performed if the above IF condition was TRUE (i.e. the user did not provide any parameters to this command macro).
	E) <^Move>MacroAssign <F5>0 <F5>1
This is BEACON's macro facility for assigning BEACON command macro variable to a string value.  In this case, the string 1 is assigned to BEACON's macro variable 0.  In this particular example, this assignment is only performed if the above IF condition was TRUE (i.e. the user did not provide any parameters to this command macro).
	F) <^Move>MacroEndIf
This is BEACON's macro facility for designating the end of a macro IF statement.  In this particular example, the next statement is executed regardless of whether or not the previous IF condition was TRUE.
	G) <^Move>MacroIf 0 '=' <F5>1
Once again, this is BEACON's macro facility IF statement.  The first parameter to the IF statement is the string defined to the macro variable 0 (which is the number of parameters passed to this macro).  The second parameter is binary operator '=' (which must be surrounded in quotes).  The third parameter is the literal string 1 (not the contents of the macro variable 1).  If this condition is TRUE (i.e. the macro variable 0 equals the literal string 1) then BEACON continues to SUBMIT the next line of the file.  If this condition is false, BEACON will skip the contents of the file until the corresponding MACROELSE or MACROENDIF is encountered.  In general, MACROIF checks for equality of any two strings (only '=' is supported at this time).
	H) <^Move>PortLetter=1		
This line actually generates the local command PortLetter=parameter because the <1> key has the passed parameter DEFINEKEYed to it.  This executes the BEACON command PORTLETTER which selects the proper serial port.  This command is executed only if the above IF condition is TRUE.
	I) <^Move>MacroElse
This is BEACON's macro facility's ELSE statement.  If the previous IF condition is TRUE, then all statements between the IF statement and this ELSE statement are executed, and all statements between this ELSE statement and the corresponding ENDIF statement are skipped.  If the previous IF condition is FALSE, then all statements between the IF statement and this ELSE statement are skipped, and all statements between this ELSE statement and the corresponding ENDIF statement are executed.
	J) <^Move>MacroWrite 'Too many parameters.  SELECTPORT [A|B]'
This is BEACON's macro facility for outputing a message to the user in the Status: line at the bottom of the screen.  In this particular example, this output to the user is only performed if the above IF condition was FALSE (i.e. the user provided too many parameters to this command macro).
	K) <^Move>MacroEndIf
This is BEACON's macro facility for designating the end of a macro IF statement.  In this particular example, the next statement is executed regardless of whether or not the previous IF condition was TRUE.	
	L) <^Move>MacroEnd
This line terminates BEACON's macro mode (since this was a level one macro.)  Upon termination of BEACON's macro mode, the current values of the macro variables are saved, and the keys 0 through 9 are unDEFINEKEYed so that they behave normally for user interaction.
Appendix A:  Creation of BEACON Submit Files
	Files that are intended to be input to BEACON through the SUBMIT facility must somehow be created.  Probably the easiest way to create these files is by using the BTOS Editor although some users may prefer to use WRITEOne.  For this discussion, we will assume the use of the BTOS Editor.
	To invoke the BTOS Editor, issue the following command from the executive (without the double quotes <>).
	EDIT<Return>(filename)<Go>
	Note that (filename) is the name of the file to be submitted (i.e. (macro name).MAC for creation of macros.
	Files that are going to be used as input to BEACON through the SUBMIT facility must contain BTOS key values for each keystroke.  While most of the keystrokes may just be typed by hitting the appropriate key, some of the keystrokes will need to be entered by using the editor's literal insert <Code>I facility.
	The following is a list of most of the common keys needed in SUBMIT files and their corresponding BTOS key values.  For a complete description of BTOS key values, refer to Appendix A of the BEACON Reference Manual or Appendix A of the BTOS Operating System Reference Manual (Volume 2).

				BTOS Key Value
	KEY			(DecimalHex)					Function

	<Move>			15	0F				Local command mode toggle.
	<^Move>			143	8F				Enter local command mode.
	<F5>			25	19				Enter literal input mode.
	<Bound>			13	0D				Enter local input blank mode.
	<Left Arrow>			14	0E				BTOS <Left Arrow> key.
	<Right Arrow>			18	12				BTOS <Right Arrow> key.

	Upon completion of the editing session, use the <Finish> key to exit editor.

Appendix B:  BEACON Command Macro Statements

	The following is a list of BEACON's command macro statements along with the appropriate syntax.  Refer to BEACON Reference Manual for a complete list of BEACON commands.
MacroAssign
	The purpose of this command is to define a string to a Macro variable that is active only in the Macro mode.  This command is only acceptable in Macro mode.  This command expects two parameters: the first one being the Macro variable in the range from 0 to 9 and the second to be the defined string.  If a string is not specified then the Macro variable is set to null.  The use of the Literal function key (F5) may be required to correctly designate the Macro variable.  The syntax of this command is as follows:
MacroAssign <Macro variable> [string]
MacroBegin
	The purpose of this command is to enter the Macro mode in BEACON program.  This is a sophisticated mode that allows for conditional execution of commands, prompt the user for various inputs, display status messages etc.  All the commands that start with the word Macro are also enabled upon the execution of this command and are disabled at the execution of MacroEnd command.  This command does not accept any parameters.  The syntax of this command is as follows:
MacroBegin
MacroElse
	The purpose of this command is to define the Else part of a conditional execution block.  This command is only acceptable in Macro mode.  If the condition specified by the MacroIf statement is FALSE then the instructions starting from the MacroElse to MacroEndIf are executed, otherwise this blocked is skipped.  The syntax of this command is as follows:
MacroElse
MacroEnd
	The purpose of this command is to exit the Macro mode.  Once out of the Macro mode all the Macro variable assignments made are lost and the Macro commands are no longer accepted.  This command is only acceptable in Macro mode.  This command does not accept any parameters.  The syntax of this command is as follows:
MacroEnd
MacroEndIf
	The purpose of this command is to terminate the MacroIf command.  This command does not accept any parameters.  This command is only acceptable in Macro mode.  The syntax of this command is as follows:
MacroEndIf
MacroIf
	The purpose of this command is to allow for conditional execution of commands.  This command accepts three string parameters of which the second string is an conditional operator.  The first and third parameters are the operands.  If the assertion is valid or TRUE, then all commands following the MacroIf are executed until a MacroEndIf, MacroElse, or MacroEnd is encountered.  If the assertion is false, then all commands following the MacroIf are skipped until a MacroEndIf, MacroElse, or MacroEnd is encountered.  Currently, only the operator = is supported.  The syntax of this command is as follows:
MacroIf  <first operand> <operator> <second operand>
MacroLog
	The purpose of this command is to establish a log file for Macro processing.  This is very useful when trying to debug userwritten macros.  This command accepts optional parameter which is the file name of the log file.  Entering this command with no parameters terminates the logging of macro commands.  The syntax of this command is as follows:
MacroIf  [filename]
MacroResponse
	The purpose of this commands is to allow for user assignment of Macro variables.  This command accepts one integer parameter between 0 and 9 which designates a Macro variable.  This command is only acceptable in Macro mode.  The user is then prompted in the command line to input a string value.  This value is then assigned to the Macro variable.  The syntax of this command is as follows:
MacroResponse  <Macro variable number>
MacroWrite
	The purpose of this commands is to write a message in the status line on the screen.  This command accepts a string parameter.  This command is only acceptable in Macro mode.  This command can be used to prompt for user inputs using MacroResponse command.  The syntax of this command is as follows:
MacroWrite <message string>