ACL – An Introduction

1. Accelerator Controls Seminar Series (Part Trois) ACL – An Introduction Brian Hendricks March 16, 2012

2. What Does ACL Stand For, Anyway? • originally, Accelerator Command Language • also, ACNET Command Language • sometimes, Accelerator or ACNET Control Language (not by me) • You can call it anything you like as long as you use it. 

3. What is ACL? • “simple” script language • borrows concepts from other languages • interpreted, not compiled • runtime compilation available • supports a superset of the ACNET DRF2 device notation • implemented in ASCII text files and database text files • accessible from the console programming environment as well as through the web

4. Why Was ACL Created? • needed to implement setting capability in Lex SA for the Antiproton Source • designed to empower nonprogrammers to implement sophisticated control of the accelerator • pseudo English language interface • immediately saw its value in extending the Sequencer

5. What is ACL Used For? • Sequencer • eliminates the need for most new commands • parameter page (also parameter window) • supports complicated settings and displays, etc. • command line interface (general use) • Lex SA (script object) • originally to provide control • also supports display scripts

6. What People Have Done with ACL • allowed more sophisticated control of the Recycler and supported quick changes to algorithms – Cons G. • improved Pbar tuning and transfer times and consistency and provided background monitoring processes – Dave V. • managed studies, prepared reports, and improved shot operations in the Tevatron – Jerry and Dean • improved the speed and efficiency of Booster studies – Meghan M. • used to stress test front ends and to demonstrate/diagnosis data acquisition problems • used by operators to perform miscellaneous tasks including report generation and device control – Chip, Brian S., etc.

7. How Can I Use ACL? • command line interface (type in ‘acl’) • parameter page and parameter window (acl>) • Sequencer (ACL command) • Program Tools “IDE” (‘ACL Edit/Run’) • web • http://www-ad.fnal.gov/cgi-bin/acl.pl?acl={insert ACL code here} • call it from your program using library interface (ul_acl)

8. Language Components • commands (nearly 200) • intrinsic functions (~500) • variables • expire when the current script ends • symbols • expire when the calling program ends • names start with a dollar sign • operators (including device specific ones) • labels

9. Simple Example if I:H100 is off if I:H100 has control reset I:H100 turn I:H100 on if I:H100 is off print ‘Failed to turn I:H100 on…’ endIf endIf endIf

10. ACL Variables • types • variable (destroyed when script ends) • symbol • name starts with a dollar sign • not destroyed until the calling program exits • related commands • declare (import) • resize • data types • double • string • other standard numeric types • date • node • error • event

11. ACL Variables (continued) • qualifiers • constant • dynamic • automatic creation and resizing of command and intrinsic function output variables • can be overridden by aclOption command • special initializers (device: and file:) • intrinsic symbols ($_xxx) • $_value • $_eof • $_error_count • $_error_status • $_error_device • $_error_line

12. ACL Program Control Commands • loop / endLoop • forever • eof • if / else / elseIf / endIf • while / endWhile • forever • doWhile / endDoWhile • continue • break • exit • onError / {label}

13. ACL Input/Output Commands • print • defaults to appending a new line (noNewLine) • output • select active default output destination • commands providing output can select their own output • input • used with “<{identifier}>” operator • mail • outputValue • used primarily to output binary values

14. ACL Device Reading Commands • read – reads live, data logger, save/restore, SDA data • readList – reads devices “simultaneously” • list – lists device attribute information • loggerGet / loggerGetArray – data logger data • saverestoreGet (srGet) – save/restore data • sdaGet – SDA data • ftpRead – Fast Time Plot data • snapRead – snapshot data • show – device database information • compare – compare two different device readings

15. ACL Device Setting Commands • set – sets one device at a time • setList – sets devices “simultaneously” • deltaSet – makes a delta setting • turn (on, off, onList, offList) – turns devices on or off • reset (resetList) – resets devices • digitalControl – sends digital control commands to devices • copy – copies one device to another • enable/bypass – enable/bypass alarms • dbSet – sets device setting records

16. ACL Miscellaneous Commands • run – runs another program • other ACL scripts • console applications (with or without scripts) • including remote methods • wait • time interval • clock event • state event • absolute time • device (in particular range or having particular status) • devices at the same value • user response • console program start / end • network message

17. ACL Special Device Commands • timerEvent – reads/sets timer trigger events • stepMotor – sets a stepper motor • tableDevice – handles all ramp cards • bpmData – reads supported BPM systems • blmData – reads supported BLM systems • gpib – sends commands to GPIB devices • camac – sends CAMAC commands

18. System Information Commands • settingLog – reads setting history • alarmLog – reads alarm history • errorLog – reads device error history • auditLog – reads the device edit history log • nodeAuditLog – reads the node edit history log • eventLog – reads clock event history • stateLog – reads state event history • programInfo – reads program/library information • nodeInfo – reads node information • consoleInfo – reads console information • userInfo – reads system user information • downtimeLog – reads downtime log entries

19. A Word About ACL Dates • supports different standard formats • default is “dd-MMM-yyyy hh:mm:ss” • also “Www Mmm dd hh:mm:ss yyyy” and “yyyy-mm-dd hh:mm:ss” and “Month dd, yyyy hh:mm:ss” • current time interval • today, thisHour, thisMinute, thisWeek, thisYear • last time interval • yesterday, lastHour, lastMinute, lastWeek • interval from now • 10minutesAgo, 1hourAgo, etc.

20. ACL Operators • arithmetic • +, -, *, /, ^, %, >>, <<, plus, minus, times • logical • &&, ||, and, or, not • comparison • <, >, <=, >=, =, ==, !=, equals • string • +, =, ==, like, notLike, concatenate • bitwise • &, |, bitwiseAnd, bitwiseOr

21. ACL Device Operators • is (isNot) – device status • on, off, ready, tripped, remote, local, positive, negative, ramping, dc, good, alarming, enabled, disabled, bypassed, active, inactive, defined, undefined • has (doesntHave) – database attribute • reading, setting, status, control, analogAlarm, digitalAlarm, resetControl, onControl, offControl, positiveControl, negativeControl, onStatus, readyStatus, remoteStatus, polarityStatus

22. Device Specifications • supports a superset of DRF2 specification • property specification • : and ? -> reading, _ -> setting, | -> basic status, & -> basic control, @ -> analog alarm, $ -> digital alarm • .{property name} • array notation [begin_index:end_index] • Z:ACLTST[0:3] or Z:ACLTST[] • length/offset notation {offset:length} • Z:ACLTST{0:16} • alarm block fields (eg. M:OUTTMP.minimum)

23. Device Modifiers • source – data source • accelerator (default), db, sr:{file}, sda:{file}:{case}:{set}, dl:{date}:{node} • scaling type • scaled (default), raw, primary • ftd=(FTD string} • @{data event}

24. Device List Specifiers • name={string} (uses standard SQL wildcards) (also fullName={string}) • description={string} (also fullDescription) • node={node name} • type={device type string or number} • ssdn=‘xxxx/xx42/xxxx/xxxx’/node=MI1 • family={family device} • file={file name} • Many more…

25. ACL’s Special Characters • comment • ‘#’ and the dreaded ‘!’ • ‘!’ can also be used in ‘!=‘ and ‘!exists(variable)’ • comments text to end of line • ‘!’ character can be disabled with the commentChar or aclOption commands • end of line – ‘;’ • allows multiple commands per line (useful for command line) • line continuation – ‘\’ • execute an ACL file – ‘@’

26. Script Arguments • substitute devices • G:DEV{n} • used anywhere a device expression can be used • substitute strings • string{n} • literal string substitution

27. Documenting Your Script • add script description • “#+description” marks beginning • “#-description” marks the end • deviceArg – documents device arguments • description • default value • stringArg – documents string arguments • description • default value

28. Script Repositories • MECCA project utility_acl • can be modified by anyone but maintains history • parameter page and parameter window • acld • MECCA project sequencer_acl • Sequencer • ACL database • only qualified people can edit but no history • parameter page and parameter window • command line • acld

29. Modifying Script Repositories • utility_acl and sequencer_acl • modified like any other MECCA project • mkdir {utility_acl or sequencer_acl} • cd {utility_acl or sequencer_acl} • mecca –copy {utility_acl or sequencer_acl} • edit your file • mecca –commit {utility_acl or sequencer_acl} • can test in the parameter page, parameter window, and the Sequencer before committing • database • modified with D136 or the Program Tools “IDE”

30. Help for ACL • command line interface • ‘help’ for general help • ‘help {command}’ for command help • ‘help function {function name}’ for function help • Program Tools interface • ‘ACL Help’ for general help • ‘ACL Command Help’ for command help • ‘ACL Function Help’ for function help • Control-e argument expansion • shift-click on ACL commands in the parameter page, parameter window, and Sequencer • web document • http://www-bd.fnal.gov/issues/wiki/ACL (on site only) • http://www-bd.fnal.gov/help/ul_acl/intro_acl.html (anywhere) • me

31. Other ACL Tools • ACL database file editor (D136) • place to edit database scripts • requires special permission to write files (see me) • spawned_acl (spawn_acl_script_c) • supports asynchronous execution of ACL scripts • ACL utlities (D132) • monitors spawned ACL scripts • acld daemon (acld_client) • supports nonconsole environment access to ACL • ACL file launcher (PA1881) • supports launching a predefined ACL script (S69)

32. Some Useful Commands • reading all devices on a node to find an error: • read node=OODA00 • list attributes for all devices on a node: • list node=MACALC ‘%nm %tx %expr’ • check if all operational nodes are responding: • node/ping/status=operational • to read M:OUTTMP for the last 10 minutes: • loggerGet/start=10minAgo/node=Mech M:OUTTMP • to read alarms from I: devices in the last hour: • alarmLog/start=1hourAgo I:%

33. ACL Gotchas • in the command line interface a script is executed when you press “Enter” • any variables that were created by the script have been destroyed • can execute multiple commands at once by separating them with a semicolon • values can be preserved by using symbols • device lists may need the “mutable” qualifier • use of synonyms • make it easy to come up with command and function names but can lead to conflicts with variable names • use of “!” for negation • can suppress with aclOption or commentChar commands • error handling

34. Future • support in FSMDEV finite state machine facility (through the use of acld and the ul_acld_protocol library) • Synoptic ACL objects • syntax highlighting in nedit • suggestions from users

35. Summary • utilized in many environments • Sequencer • parameter page and parameter window • testing (front end debugging) • examining the control system • empowers end users • has grown to meet the needs of those users

36. Error Handlers • established with the command onError • specifies label that begins the handler onError myErrorHandler {body of script} exit myErrorHandler: # beginning of error handler {error handling code} return

37. Always Block • established by the special label “always:” • will be executed regardless of how script exits • should be at the very end of the script exit always: # beginning of always block {always executed code}