Script OpeningsThe opening of scripts should include several standard commands/functions. The script should include the following:
1) COMMENTS
The first thing that should appear in all scripts, is the COMMENTS section. A fully documented script will include the following pieces of material (at a minimum):
- Name of the Script
- Purpose of the Script
- Who originally wrote the code.
- When the code was originally written
- Who modified the code
- When was it modified
- Why was it modified
- Any changes that have to be made within the script to make it work.
2) SET SAFETY OFF
SET SAFETY OFF will tell ACL to go ahead and overwrite existing .fil files without asking the user for permission. Best practice is to turn the safety off at the start of the master script, but turn it back on at the end of the master script. The reason why one would do so only at the start and stop of the master code is because sometimes codes will call other scripts. If the subscript turns the Safety back on, then ACL may require the user to grant permission to overright each file every time.
3) DELETE ALL OK
DELETE ALL OK is not a command that everybody uses. Some people believe in using global variables, eg variables that ACL preserves from session to session. I do not, I believe it is a best practice to delete all variables at the start of the code. The reason why I believe this is because I've written codes wherein I obtained false results due to legacy variables. In other words, I wrote code A using variables. Then I wrote code B, using the same variable names, but I forgot to define the variables in code B. The results were thus skewed due to using the respective values from code A, not code B. I believe is
preserving variables via a table.
4) SET SUPPRESSXML ON
ACL will process commands with SUPPRESSXML on or off. If SUPPRESSXML is off, then ACL will use XML code in the .log file. It will also provide links in various commands that are displayed to the screen. While I like to have the drill downs created this way, others (namely David Coderre) do not. That being said, both Dave and I agree that when running a script, it is best to SET SUPRESSXML OFF. We believe this for two reasons. First, the LOG file is easier to read. Second, XML slows the system down. Since the primary advantage of having XML is for the drill down functionality, this is not necessary in a code.
5) CLOSE PRIMARY
CLOSE PRIMARY will close any tables that are open as primary. Occassionally, the code that you are using will want to save or extract information to a table. If ACL is trying to perform a command to the open table, then it might cause errors.
6) CLOSE SECONDARY
CLOSE SECONDARY will close any tables that are open as secondary.
CLOSE SECONDARY is more important than CLOSE PRIMARY because generally one will OPEN tables or otherwise dictate the file that is being used as a primary file. Often times, secondary files will remain open as secondary unless something specific happens. This will cause problems with a number of fields. (NOTE: Tables are open as secondary when when using a JOIN command.)
7) DELETE LOG XXX/SET LOG XXXX/SET LOG
When ACL is open, it creates a log that has the same name as the project. This will preserve every command executed in the project and can lead to very large log files. This is impractical as a work paper as one does not know what was done to obtain the final results. A better practice is to use a log with a different name that is executed during the run the code. The first thing that has to be done is to delete the LOG, then set the log with a new log name. When the code is over, the script then executes a "SET LOG" command. When the SET LOG command doesn't have a specific name, it closes any specially named logs and opens the default log (the one with the same name as the project.) This will preserve the actions of the script only and becomes a solid foundation for one's work paper.
8) SET EXACT ON/OFF (optional)
Depending on what you are attempting to do, you might want to have EXACT set on or off. Best practice is to have it on unless you explicitly want it off. What EXACT does is it tells ACL whether or not records have to be identical when making comparisons. For example, with EXACT turned off ACL will recognize the following as matches:
- "Paul" and "Paula"
- "A123" and "A1234567y"
In most cases, you will want to have EXACT ON, but there are certain advanced functions where turning it off is preferred.
NOTE: On the ACL User Forum, there are some who argue that it is better to SET EXACT OFF. Ultimately, it is a matter of preference, but whichever way you choose to go, you should consider using the SET EXACT command to ensure consistent results.
9) SET ORDER (optional)
SET ORDER is a command that allows you to establish a specific order for items/events to be sorted in. For example, you might want to set the order of the months to Jan, Feb, Mar, Apr, etc. Or perhaps the order of the planets to the distance from the sun? Or perhaps an arbitrary order that business units should appear. Order will create the way that ACL will interpret the field when using a SORT command.
10) SET LOOP (optional)
SET LOOP will control the number of times that a LOOP command will be executed before terminating. This is generally a way to prevent endless loops from occurring. If you SET LOOP 0 then this control is turned off and the LOOPS will continue indefinitely.