Special conventions also apply for the description of Automation Engine's scripting language. These conventions are used in combination with the general conventions whenever the scripting language is explained within the Automation Engine documentation.
Automic Script Lines
Script statements are Automation Engine Script elements that start with a colon (:) and are shown in blue in the Automic Web Interface. They are often used in combination with a value assignment.
The example below shows a :PRINT script statement:
:PRINT "Automation Engine"
Script functions are AE Script elements that supply return codes. Many functions supply values and also execute particular actions. Script functions must not be placed at the beginning of a line and can only be used in combination with script statements. Script elements are shown in red in the Automic Web Interface. A function's name is followed by parentheses ( ) that can include parameters.
The example below includes an ADD script function:
:SET &RESULT# = ADD(2,2)
The underscore character "_" may be used for extra long lines to indicate that the text continues in the next line. The last character of a line should therefore be an underscore. The proximate line should start with a colon.
You can get the syntax for Automic Script lines from Automic Scripting Guide or directly from the Process Pages where Automic Script is added to executable objects. To view the syntax of a script statement or script function from an object's process page in the Automic Web Interface, hold down Ctrl and Space. An auto-complete pop-up window will show you the syntax of the script statements and script functions that match the text you have entered. Use the Esc key to close this list.
Some script statements and functions can be written in long or short forms. When that is the case, the script statement or function is documented with the optional text for its long name in [ ] brackets. For example, the script statement :PRINT is documented as :P[RINT]. It can be written as :PRINT or :P, depending on your preference.
Documentation Syntax for Required Parameters, Optional Parameters, and Commas
Required parameters (and commas) are not enclosed in [ ] brackets. Optional parameters (and commas) are excluded in [ ] brackets.
Commas separate script element parameters. Script elements are evaluated in the order they are listed. In the example showing syntax below, commas separate the each of the CREATE_OBJECT script function's parameters.
CREATE_OBJECT (Object Type, Object Name, [Folder], [Title] )
When you don't want to specify a value for an optional parameter, you put nothing (or a space) between the commas. For example, to not specify a folder, you put nothing between the second and third commas as shown below.
:SET &RET# = CREATE_OBJECT("CALE","FIRM.CALENDAR2017",,"Firm calendar for 2017")
If you've specified values for all required parameters, and you don't want to include values for any remaining optional parameters, you don't need to include commas for the remaining optional parameters. For example, if you want to create an object without specifying a folder or title, you could place the closing parenthesis after the object name parameter as shown below.
:SET &RET# = CREATE_OBJECT("CALE","FIRM.CALENDAR2017")
Documentation Syntax for Keyword Parameters
The text for keyword parameters must be written exactly as specified. In the documentation, keyword parameters are written in bold; for example, VERSION in the SYS_INFO script function below.
SYS_INFO (component,VERSION, [ type ], [component name])
When they are optional, keyword parameters are also enclosed in [ ] brackets; for example, FORCED in the MODIFY_TASK script function below.
MODIFY_TASK (RunID, Status [, FORCED])
Some keyword parameters can be written in long or short forms. In this case, the keyword parameter is documented with the optional text for its long name in [ ] brackets. For example, the keyword parameter STR_SUBSTITUTE_VAR is documented as STR_SUB[STITUTE]_VAR. It can be written as STR_SUBSTITUTE_VAR or STR_SUB_VAR, depending on your preference.
Comment Lines
Each line starting with the exclamation mark character "!", is a comment. These lines are not considered as processing steps and skipped during script execution.
Example:
!Comment line
If the exclamation mark character is used within a line, however, this line is not considered a comment.
We recommend making ample use of comments so that you or other users may easily reproduce at a later point what the script lines do.
Data Lines
If a line neither starts with a "!" nor with a ":", it is considered a DATA line. DATA lines can only be used with "Job" objects. They contain the JCL (Job Control Language) of the target system. If a DATA line starts with a ":", it must explicitly be declared as such with the script element :DATA.
Example:
copy test.txt c:\temp
Jobs for Enterprise Business Solutions (SAP, PeopleSoft and Oracle Applications) show some special features. AE provides an extra JCL for those.
Script variables included in DATA lines are replaced by their values. Script variables start with the special character "&". If "&" is used in a DATA line and should remain there as it is, it needs to be doubled. If "&" is used without being followed by a valid variable name, the DATA line also remains unchanged.