intro_acl_usage


	The Accelerator Command Language (ACL) is a simple scripting
	language for reading and setting ACNET devices.  It can also be
	used for simple general purpose programming.


	Using ACL from the command line:


	To use ACL from the command line, you simply type in "acl" and
	hit return.  You will then see a prompt of "ACL>".  At this
	prompt you can type in any valid ACL command or list of commands
	separated by semicolons.  You can execute an existing ACL script
	file by simply typing an "@" character followed by the name of
	the file and any arguments that the file might need separated
	by spaces.  If the script is contained in a text file and the
	extension of the file is ".acl", you do not have to explicitly
	enter it.  If you are executing an ACL script kept in the ACL
	script database, you should add a suffix of ".db".  Also, in
	this case, if the name of the script contains spaces, the entire
	name except the extension should be enclosed in quotes.

	Example of executing a script contained in a text file:

	ACL> @my_script argument_1 argument_2

	Example of executing a script contained in a text file
	with a different extension:

	ACL> @my_script.txt argument_1 argument_2

	Example of executing a script contained in a database file:

	ACL> @'my database script'.db argument_1 argument_2

	It is important to note that on the command line when you press
	return after entering a command, that is considered to be the
	execution of a script.  Any environment related commands such
	as "output", "data_source", or "data_event" will have no effect
	on subsequent commands that are entered.  An exception is the
	"keep_open" qualifier for the output command.  If that qualifier
	is specified, the corresponding output will be used for the
	remainder of that ACL session.

	The command line environment has some special commands that
	are unique to it.  Here is a brief listing of them.

	source [on|off] : turn source code display on or off
	verbose [on|off] : turn verbose output on or off
	batch mode [on|off] : turn batch mode on or off
	    (By default, as soon as you hit enter, the script is executed.
	     In batch mode, you can enter multiple lines of code which will
	     not be executed until type in "go" and press enter.)
	suppress_settings [on|off] : turn setting suppression on or off
	show symbols : display all active symbol names
	show symbol {symbol name} : display the value of a symbol
	set symbol{/qualifier} {symbol} {value} : set the value of a symbol
	(Qualifiers for the set symbol command include:
	 error -> value will be interpreted as an ACNET error string
	 error_int -> value will be interpreted as an ACNET error code (integer)
	 device -> value will be interpreted an an ACNET device name
	 device_index -> value will be interpreted as an ACNET device index
	 string -> value will be interpreted as a string
	 logical -> value will be interpreted as a logical
	 integer -> value will be interpreted as an integer
	 float -> value will be interpreted as a floating point value
	 double -> value will be interpreted as a double precision
		   floating point value)


	Using ACL from a parameter page or a parameter window:


	To use ACL in this environment, you must start the line with the
	string "ACL>".  There are two optional special characters that can
	follow this.  The first is a plus ('+') sign which indicates that
	the ACL output window should remain open until the user manually
	closes it.  The other special character is a greater than ('>')
	sign which indicates that the ACL command should be spawned off
	as a batch job.  As in the command line environment, an existing
	ACL script can be executed by preceding its name with an '@'
	character.  Scripts contained in the ACL script database and
	scripts in the MECCA utility_acl project can be executed.  You
	do not have to add the ".db" extension to the file name, but you
	still have to enclose the file name in quotes if it contains
	spaces.  The scripts must be created and modified using the
	application program D136.  If you have never used this program
	before, you must contact Brian Hendricks (hendricks@fnal.gov) to
	be authorized to edit scripts. utility_acl files can be created
	and modified using normal MECCA commands.  To execute an ACL
	command in this environment, you must click on the line containing
	the command.  You will then be presented with a decision window.
	If you click on the "OK" button the ACL command will be executed.
	When the parameter page is parsing the ACL command, it will first
	search for scripts in the database followed by those in utility_acl.

	For utility_acl scripts, you can run test versions out of your
	own area by utilizing the "Set ACL Dir" command under the
	Pgm_Tools menu. Scripts running out of a test directory will
	have their prompts displayed in magenta rather than the normal
	yellow.

	ACL scripts for the parameter page and parameter window
	(as well as acld, ACL Launch Service, and ACL Script Menu are
	stored in the MECCA project utility_acl. To edit an existing
	script or to create a new one, please follow these steps.

	    If you have never edited a utility ACL script before:
		1) like any other MECCA project, you need to create a directory
	 	   for it with the same name as the project (in this case,
		   utility_acl)
		2) fill the directory with the existing files in MECCA by
		   executing the command "mecca --copy utility_acl"

	    If you have an existing utility_acl directory:
		1) update your directory by executing the command "cvs update"

	    1) either edit an existing file or create a new one in your
	       utility_acl directory
	    2) test the file from the command line or by using the ACL
	       test directory option in the parameter page/window
	       (The ACL test directory option in the parameter page can
		be accessed via the Pgm_Tools menu.)
	    3) once you are satisfied with your changes, you can submit
	       them to MECCA using the command "mecca --commit"

	Example of executing a script whose name contains spaces:

	ACL> @'my spacey script' argument_1 argument_2

	Example of spawning off a script execution:

	ACL>> @my_spawned_script argument_1 argument_2

	Example of executing a script and retaining the output window
	for the user to view:

	ACL>+ @my_output_script argument_1 argument_2

	There is a command in both the index page as well as the parameter
	page itself named 'Find ACL Command' to search for occurrences of
	a particular ACL command in all of the parameter pages.

	If you perform a shift-click on an ACL command, you will receive
	help on that command. If the creator of the script has inserted a
	description in the script, you will get a menu giving you the
	choice of displaying the script description or the source code for
	the script. If there is no script description, the source code for
	the script will be displayed. If the command is not a script and
	is simply an ACL command, help for that ACL command will be displayed.


	ACL Expressions:


	There is also support for ACL expressions in the parameter page and
	parameter window. To specify an ACL expression, the line should
	begin with the string "ACL>#". Unlike ACL commands, ACL expressions
	are executed periodically as the page is updated to read, compute,
	and display values. These expressions can return either numeric or
	string values. Like ACL commands, ACL expressions can come from
	either the ACL script database or the MECCA utility_acl area.

	A minimum requirement for an ACL script that will be used in
	ACL expressions is that it must set the symbol "$paramPageValue".
	This symbol will return the value to be displayed by the parameter
	page. The symbol value can either be numeric or a string.

	There are three other symbols that the parameter page will look for
	from an ACL expression script.

	    $paramPageColor - This symbol can be used to specify the display
			      color.
	    $paramPageLength - This symbol can be used to specify the display
			       length.
	    $paramPageUnits - This symbol can be used to specify the units text.


	Using ACL from the simple IDE contained in the Pgm_Tools menu:


	To use the ACL interface contained in the Pgm_Tools menu, you click
	on "Pgm_Tools" in a console application and click on the entry
	named "ACL Edit/Run".  Once you've done this an empty window will
	be displayed that you can enter ACL code in.  The window acts as
	a simple text editor which supports some of the numeric keypad
	editing functions from EDT.  There are other special features such
	as command signature help.  This is enabled if the text to the left
	of the cursor is an ACL command name and you press control-e.  This
	will display possible arguments for this type of command.  Pressing
	control-h anywhere within the window will give you help on the editor
	itself.  You can also click on the field named "Action" and perform
	other operations such as reading in an existing script from either a
	text file or the script database.  If you choose either of these
	actions, any text entered in the window will be replaced by the script
	text.  You can then edit the text further if you wish.  You can
	execute the code presently in the editor window by clicking under
	"Action" followed by "Execute Script".  This will cause two windows
	to be displayed.  The top window displays the source lines as they
	are executed while the bottom window displays any output that the
	script generates.  Clicking on either of these windows will cause
	them both to close, and the editor window will once again be displayed.
	This interface also supports the writing of scripts to text files
	in the directory /usr/local/cbs_files/cns_write/acl.

	There are many other options in the "Action" menu of this interface.
	You can display detailed help about individual ACL commands.  You
	can display, read, and set ACL symbols.  You can suppress settings
	as well as stale errors.  You can request verbose output from all
	commands executed as well as many other things.


	Using ACL from the Sequencer:


	ACL scripts can be executed in the Sequencer by utilizing the
	"ACL" command.  This executes scripts which are text files located
	in the directory /usr/local/cbs_files/sequencer/acl.  These scripts
	can be created/modified using the MECCA project sequencer_acl.
	Use the standard MECCA commands to do this.  Scripts can either be
	executed inline or they can be spawned off as a batch file to
	execute in parallel.  Sequencer scripts are limited to a maximum
	of ten substitute devices and five substitute strings.

	If you perform a shift-click on an ACL command, you will receive
	help on that command. You will get a menu giving you the choice of
	displaying the script description, the source code for the script,
	or the specific arguments for that ACL command.

	ACL scripts for the Sequencer are stored in the MECCA project
	sequencer_acl. To edit an existing script or to create a new one,
	please follow these steps.

	    If you have never edited a Sequencer ACL script before:
		1) like any other MECCA project, you need to create a directory
	 	   for it with the same name as the project (in this case,
		   sequencer_acl)
		2) fill the directory with the existing files in MECCA by
		   executing the command "mecca --copy sequencer_acl"

	    If you have an existing sequencer_acl directory:
		1) update your directory by executing the command "cvs update"

	    1) either edit an existing file or create a new one in your
	       sequencer_acl directory
	    2) test the file from the command line or by using the ACL
	       test directory option in the Sequencer
	       (The ACL test directory option in the Sequencer can be
		accessed via the Pgm_Tools menu.)
	    3) once you are satisfied with your changes, you can submit
	       them to MECCA using the command "mecca --commit"


	Using ACL in a Lex SA:


	ACL scripts can be executed in Lex SA displays through the use
	of script objects.  These scripts must be contained in the script
	database just like the parameter page and parameter window
	environment.  There can be both a display script as well as an
	action script which is activated by clicking on the graphical
	object.  Lex SA scripts are limited to a single substitute string.

	For display scripts, display information is passed using special symbols.

	    $lexobject_current_value - value to be displayed
	    $lexobject_color - display color
	    $lexobject_min_value - minimum display value
	    $lexobject_max_value - maximum display value
	    $lexobject_display_length - display length
	    $lexobject_alarm_limit - alarm limit value
	    $lexobject_alarm_color - alarm color

	For text displays:

	    $lexobject_units_text - units text to display
	    $lexobject_text_size - display text size

	For Lex Object displays:

	    $lexobject_param_{n} (n=1-6) - Lex Object display parameters

		1) scaled value in common units (size)
		2) primary value / full scale x pixel length (size)
		3) 30 + (1 - primary value / full scale) x 120 (angle)
		4) pixel length (size)
		5) color (alarm color if above alarm limit)
		6) scaled value / max scaled value x pixel length (size)

	For buttons:

	    $lexobject_text - button label text


	Using ACL in a web browser:


	ACL commands and scripts can be executed in a web browser environment
	using the following command.

	http://www-ad.fnal.gov/cgi-bin/acl.pl?acl={your ACL code goes here}

	If there are any spaces in your command, they must be replaced
	by plus signs.
	(http://www-ad.fnal.gov/cgi-bin/acl.pl?acl=read+m:outtmp)

	If there are quotes in your command, they should be escaped with
	backslashes.
	(http://www-ad.fnal.gov/cgi-bin/acl.pl?str=\"this+is+a+string\"\;print+str) 

	As seen in the example above, any semicolons used to separate ACL
	commands should also be escaped by a backslash.

	If you want to execute an ACL script file, you need to enter the
	'@' symbol followed by the script file name enclosed in quotes.
	You can include any script arguments by appending them with '+'
	characters.

	http://www-ad.fnal.gov/cgi-bin/acl.pl?acl=@'your_path/your_file'

	ACL commands executed in a browser environment are by necessity
	very limited.  You can basically perform only reading type
	operations.


	Using ACL on an iPhone:


	There is also an ACL iPhone app. It presently supports executing
	simple ACL code and ACL scripts. It features a command history as
	well as ACL command help. This app has been developed by Charlie King.
	You can have it installed on your phone by either Charlie or
	Rich Neswold.

	If you are onsite, you can download this app on your iPhone by
	going to the web page http://www-bd.fnal.gov/controls/mobile and
	selecting "Download and Install" next to the ACL app.


	Using ACL in EDM:


	ACL commands and scripts can be executed in EDM by using the
	shell command widget.  Simply enter your ACL command in the
	"Shell Command" field as "acl @{your file name}".  The ACL
	file should be committed in the MECCA project that you are
	working on like hins_edm or nml_edm.


	Using ACL from the ACL daemon:


	ACL commands and scripts can be executed remotely using the
	ACL daemon.  This daemon accepts ACNET requests to execute
	ACL scripts and will return any requested data to the caller
	after the script completes.

	Any requested return data should be for values of ACL symbols
	that are set by the script.  The value of multiple symbols
	can be requested.  All values will be returned as strings
	regardless of their data type.  If the script fails, the
	returned data will be a single string which describes the
	error which caused the script failure.

	Any flat file scripts executed by the daemon should be kept
	in the MECCA project utility_acl.  The normal database scripts
	used by the parameter page, parameter window, and Lex SA can
	be used as well.

	ACNET requests to this daemon use the protocol defined in the
	user library ul_acld_protocol.


	Using ACL from Synoptic displays:


	You can add ACL widgets to Synoptic displays. These scripts are
	submitted to the ACLDEV OAC which subsequently sends them to acld
	to be executed. There is an editor to let you specify the arguments
	to the ACL script as well as some execution options.

	You can view a log of ACL script executions in Synoptic at
	http://www-bd.fnal.gov/AclViewer/.

	Note: ACL scripts executed by Synoptics displays are passed through
	the OAC ACLDEV to acld for execution.


	ACL Launch Service


	You can also register ACL scripts to executed periodically or on the
	occurrence of an accelerator event by using the ACL launch service.
	You can also launch a "persistent" script which is intended to run
	indefinitely. To register a script, simply go to page D129 and
	interrupt on the "Add Script" field. It will then prompt you for the
	script parameters including the launch "event".

	Periodic launch types:

	    Monthly - start of each month
	    Weekly - start of each week (midnight on Monday morning)
	    Daily - each day at midnight
	    Hourly - every hour
	    15 Minutes - every 15 minutes
	    Time of day - at a specified time of day each day
	    Shift - start of each operator shift

	Accelerator event types:

	    Clock event - launch on the occurrence of a clock event
	    State event - launch on the occurrence of a state event
	    Alarm event - launch on the occurrence of an alarm
	    Alarm bypass event - launch on the occurrence of enabling or
				 disabling an alarm
	    Setting event - launch on the setting of a device property
	    Dbnews event - launch on a device database modification through
			   DABBEL

	All ACL scripts launched by this service must be in one of the two
	MECCA repositories, utility_acl or sequencer_acl.

	Script launch parameters:

	    1) launch data event
	    2) script name (path is either utility_acl or sequencer_acl)
	       (default is utility_acl)
	    3) script arguments (separated by spaces)
	    4) script default data event
		(usually u which means to use the database default)
	    5) log file
	       (default is /usr/local/cbs_files/cns_write/acl/launch_log/{file name}.log)
	    6) holdoff time in seconds
	       (only used for accelerator event launch types)


	ACL Script Menu


	You can also register ACL scripts to be executed from a menu on
	page D29. To add a script to the menu, simply click on the
	Pgm_Tools menu and interrupt on the "Add Script" field. It will
	then prompt you for the script parameters. Scripts should be
	located in either the utility_acl or sequencer_acl MECCA projects.
	Script arguments can either be saved at the time that the script
	is added to the menu, or they can be entered by the user when
	they click on the menu to execute the script. This program is
	especially useful for executing scripts that can configure the
	console environment due to the fact that the script can be
	directed to execute outside of page D29.


	Canned ACL Script Execution via PA1881


	The Primary Application PA1881 can be configured to execute a
	previously specified ACL script upon program startup. The program
	also supports the user selecting and executing a script. An example
	of this program is S69.


	Accessing ACL through Python:


	Philippe Piot has written a simple module for accessing ACNET
	parameters from Python by using ACL. Please, contact him about
	the details if you are interested in using this interface.


	Controlling ACL Output


	In the case of the parameter page, the parameter window,
	the ACL IDE, the ACL Script Menu, and the Sequencer,
	ACL output format can be controlled by the use of the ACL
	host_request command.  This command works by passing an
	ASCII string to the process which is hosting the ACL script.
	In the case of output, these commands can control the screen
	output formating.  If the host application does not understand
	a request, it simply ignores it.  The ACL script is unaware of
	whether or not the request has been honored.

	Requests honored by the parameter page, parameter window, ACL IDE, and
	ACL Script Menu:

	window_height={size}	 -> set the height of the ACL output window
				    (default, large, or number of rows)
	window_width={size}	 -> set the width of the ACL output window
				    (default, large, or number of rows)
	suppress_scrollbar	 -> disable the scrollbar and scroll status
				    display for the ACL output window
	text_color={color}	 -> set the ACL output text color
	text_align={alignment}	 -> set the ACL output text alignment
				    (default, center, or right)
	scroll_text={yes|no}	 -> enable or disable scrolling of ACL output
	clear screen		 -> erases the ACL output window
	text_row={row}		 -> sets the output text row for nonscrolling
				    output
	text_column={column}	 -> sets the output text column for nonscrolling
				    output
	clear_text_field={len}	 -> erases a field in the ACL output window
	text_row_increment={inc} -> sets the output text row automatic increment
				    for nonscrolling output
	text_column_increment={} -> sets the output text column automatic
				    increment for nonscrolling output
	suppress_completion_message -> disable the script completion message

	Additional parameter page and parameter window supported requests:

	set_device_line={line}	-> sets the output line in the device window
				   (starts at 1)
	inc_device_line={num}	-> increments the output line in the device
				   window
	get_num_device_lines=?	-> retrieves the number of device lines
	set_device={device spec}-> sets the device at the current device line
	set_comment={comment}	-> sets a comment at the current device line
				   (parameter page only)
	get_acl_command_line=?	-> retrieves the line in the device window
				   where the currently executing ACL command
				   is located (starts at 1)
	get_current_device_line=?-> retrieves the line in the device window
				    that has most recently been accessed by
				    ACL (starts at 1)
	get_line_entry_type=?	-> retrieves the entry type for a given
				   device line (default is for the current line)
	get_line_device=?	-> retrieves the device for a given device
				   line (default is for the current line)
	get_line_comment=?	-> retrieves the comment for a given device
				   line (default is for the current line)
	get_line_expression=?	-> retrieves the expression for a given
				   device line (default is for the current line)
	get_line_acl_expression=?-> retrieves the ACL expression for a given
				    device line (default is for the current line)
	get_line_acl_command=?	-> retrieves the ACL command for a given device
				   line (default is for the current line)
	read_line_text=?	-> retrieves the text for a given device line
				   (default is for the current line)
	write_line_text={string}-> writes text to the current device line
	delete_all_devices	-> delete all entries in the device window
	clear_device_line	-> clears the current line in the device window

	Requests honored by the Sequencer:

	text_color={color}	 -> set the ACL output text color
	text_align={alignment}	 -> set the ACL output text alignment
				    (default, center, or right)
	scroll_text={yes|no}	 -> enable or disable scrolling of ACL output
	clear screen		 -> erases the ACL output window
	text_row={row}		 -> sets the output text row for nonscrolling
				    output
	text_column={column}	 -> sets the output text column for nonscrolling
				    output
	clear_text_field={len}	 -> erases a field in the ACL output window
	text_row_increment={inc} -> sets the output text row automatic increment
				    for nonscrolling output
	text_column_increment={} -> sets the output text column automatic
				    increment for nonscrolling output

-------------------------------------------------------------------------------

	Related functions:

	intro_acl, acl_compile_c, acl_execute_c, acl_file_execute_c,
	acl_file_read_c, acl_file_write_c, acl_free_c, acl_read_symbol_c,
	acl_read_symbol_info_c, acl_read_symbol_names, acl_set_symbol_c,
	acl_delete_symbol, acl_info_c, acl_cancel_requests_c, acl_get_devices_c,
	acl_close, acl_command_text, acl_log_file_c, acl_default_data_source_c,
	acl_default_script_path_c, spawn_acl_script_c, device_listing_c