Scripting
Overview
A script (a Sc or Pl tag) is a list of PTC ALD macros that can be presented for processing as either a document text stream or a string from one of PTC ALD's strings file, for example suser.3ad. It is run via the trun macro and usually combines macros with programmatic actions such as tests to carry out certain actions when a set of particular conditions is fulfilled:
• call other scripts or subscripts: the parent script contains its own trun macros
• call external files containing macros: the script contains a run macro
• create tags
• output content
Internal and external scripts are maintained separately in the string file for the purposes of clarity, with internal scripts being split further into those written in PTC ALD's proprietary scripting language and those done in Perl.
Scripts can be nested to an unlimited number of levels. Since PTC ALD processes the children of one tag before moving to the next one and always records its cursor position before it does so, it can process nested scripts without problem. Debugging is also much less problematic when code is processed in this way.
Script Types
Four types of script are supported in PTC ALD:
script_name .sc
This is the most common type of PTC ALD script, being any user named script that contains user-defined actions. A script of this type can be run from anywhere and at any time while the document to which it applies is open. Scripts can also be chained together with other scripts to create a series of actions.
Two special scripts are included in this category but deserve special mention since they control the opening and closing of document:
1. Autoexec.sc
This type of script is usually executed automatically when a document is opened, although this option can be deactivated if required. The autoexec is the type of script used by templates and specifies the set of macros that should be run to compose the document and, optionally, invokes a set of dialog boxes from which users can select pre-pagination options such as which text stream to load.
|
|
This type of script must only ever be named "autoexec" as PTC ALD searches for a script of this name when a document is opened.
|
2. Autoexit.sc
This type of script is executed automatically when the document is closed to allow various actions to be carried out, usually housekeeping tasks, for example:
▪ Save the content stream to an external file
▪ Clear or preserve variable values
▪ Restore original menu system if it has been changed with the execution of the template
mini_script_name.sc
A mini script is usually a smaller version of the script type detailed above, restricted only to running processing type operations and NOT macros. It is not run by a user but is used within showstrings and is called automatically every time the showstring is processed.
900 (string)
Strings are defined in a strings file such as suser.3ad or defined from within a script via the defstr or addstr macros. They can also be defined in add-on libraries. They are global in nature, which means that they are available throughout the PTC ALD session, rather than being tied to a particular document.
Perl_script_name.pl / Perl_mini_script_name.pl
Perl scripts are executed in the same ways as regular PTC ALD scripts, via the trun macro. PTC ALD recognizes the tag extension .pl and automatically processes these scripts using the Perl processor. If a Perl script has been saved with a .sc extension, however, users can still use the trun macro to run the script, but with the extended syntax trun p"perl_script_name. Perl scripts can call any aspect of Perl functionality to add to that provided by PTC ALD scripting.
Programming Language
PTC ALD contains its own very specific programming language and syntax which makes it easy to script exact macro functionality. It is possible, however, to write Perl scripts within PTC ALD that make full use of all available Perl functionality.
Common Scripting Macros
Although a full list of script macros is out of scope of this document, the list below describes some common tasks.
trun
Run a script: this can also be included in a script to call another one
trun 0
Exit all scripts by backing up through all levels of script hierarchy to leave no scripts running
trun -1
Back up one level in the script hierarchy
run
Run macros stored in an external file
}label_name
Jump forward in a script to a label called "label_name"
:label_name
A label called "label_name"
boxit ^testvar^
Display the contents of the variable testvar in a box on the screen (this function is useful when debugging a template since it allows you assign a test whose value you would expect to see at a given point in the template and ascertain the success of the template based on the value shown in the box)
<trace>
Process a script line by line for the purposes of debugging.
A full list of PTC ALD macros is contained in the Macro Language Reference. Please refer to the PTC ALD Help Center, accessed via the menu option.