Scripting Operator Details

Synopsis

Alfred input scripts are composed of expressions using the following operators:

##AlfredToDo 3.0

Job [options]

Task {title} [options]

Cmd {launch_expr} [options]

RemoteCmd {launch_expr} [options]

Instance {task_title_to_reference}

Iterate varname -from n -to m -by i -template {script} [options]

Assign  varname {value_string}

Operator Details

Usage Note:
The options listed below have the form "-optionName optionValue" and all options must be on the same logical input line as the operator.   Backslash (\) can be used at the end of a line to explicitly escape the newline and continue input on the next line of the script file.   Newlines within (curly) braces are treated as blanks and can improve clarity, especially for nested tree structures.   For example:

   Task {frame.1} -subtasks {} -cmds {Cmd {/bin/date} -tags {simple}}

   Task {frame.1} -subtasks {
   } -cmds {
      Cmd {/bin/date} -tags {simple}
   }

Job [options]

-title {job title text}

this string is used as the label text in the job-queue window.

-after {date}

delays the start of job processing until the given time; the job is spooled and placed on the queue, but no processing occurs until after the date specified; dates are of the form {month day hour:minute} or for times later on the same day {hour:minute} (up until midnight). Hours should be given as for a 24-hour clock. For example to delay a job until June 23 at 1:45PM, use:  Job -after {6 23 13:45} ...

-init {initializations}

global state initializations, using the Assign operator, see the example.

-subtasks {Tasks or Instances}

the nested Tasks which define the structure of the job are defined here.

-cleanup {Cmd list}

a list of Cmds to execute on job termination.

-atleast min_servers

sets the default value for Cmds without an explicit -atleast option.

-atmost max_servers

sets the default value for Cmds without an explicit -atmost option.

-tags {tag tag ...}

limit-tags to be added to each Cmd's existing tag list.

-service {key expression}

additional service key expressions to be ANDed with each Cmd's existing service expression.

-pbias n

specifies a positive or negative offset value, n, which will be applied to the default per-Crew server priority defined in the alfred.schedule file. The resulting value is used by the maitre-d when deciding how to assign servers to competing jobs from different users. Each dispatcher will tend to get remote servers in proportion to their priority, relative to that of other users. Note that this priority value only affects remote server assignments in active jobs; the order in which jobs are processed is determined by their position in their dispatcher's job queue. See the Job Priorities discussion for more details.

-crews {crew name(s)}

specifies the list of Crews to be used when determining remote server access; applies to users who are members of multiple crews but who want a particular job to execute with a restricted set of server access permissions. Crews listed here but which don't apply to the user are ignored. If the list is empty, then the default list is derived from the schedule.

-huntgroup {service names...}

specify the subset of all available remote servers which should be used for this job. The Crew definitions in the alfred.schedule file determine the default set of servers available to each user. Note: use the schedule-defined service names here, not the hostnames on which the services are defined.

-avoid {service names...}

this is an alternate way to define the huntgroup (above); the avoid list specifies servers which should be excluded from consideration. If neither -huntgroup or -avoid is specified, or if the avoid list is empty, then the default list is derived from the crew definitions.

-etalevel n

specifies that level n of the Task tree should be used to compute the job's estimated time-to-completion value. The outermost level of Tasks in the job script are level zero, their subtasks are level one, etc. The default estimate is based on the number of remaining level 0 nodes multiplied by the average time required by each completed level 0 node (i.e. all its subtasks and its own Cmds).

-comment {text}

specifies an arbitrary string which is stored with the job, it is primarily used to include script-generator version information in Alfred scripts.  

-sqlset {field=val,field=val,...}

specifies initial values for specific fields in the "Job" table record associated with this job in the "BatCave" database, if database support is enabled. This option can be used to override the default values for columns defined in the out-of-box Job table definition, however it is more often intended to be used to populate columns which a site has added as extensions to the default table definition. The syntax and quoting conventions are dictated by the database; for MySQL, the given string is appended to an update query of the form:

UPDATE Job SET string WHERE jid=this_job's_id

So for example, if a site has added a column named "shotname" to the Job table, it could be initialized by the job script as follows:

Job ... -sqlset {shotname='c47_8a'}

 

-whendone {shell command}
-whenerror {shell command}

the given command is executed in the dispatcher's shell when the job has completed successfully (whendone), or whenever a Cmd in the job encounters an error (whenerror, i.e. when a launched executable exits with a non-zero exit status). These options override the equivalent user preferences, which are the defaults for all jobs. Typically these commands are used to play a sound or send mail to a render-wrangler, etc, when a job finishes or has an error. The text of the command can reference the following symbols which are substituted just before launch:
  %j = job title
  %t = task title (for errors only)
  %u = the user login name (dispatcher process owner)
  %U = user@host (dispatcher owner)
  %f = filename of a (temporary) status message
example:   /usr/sbin/Mail -s 'job done: %j' %u < %f

Task {title} [options]

title

this string is used both as label text in the user-interface and as the name by which Instance nodes refer to their targets.

-subtasks {Tasks or Instances}

tasks are arranged in a grouping hierarchy; child tasks are defined in the current task's subtask list, these are dependencies which must be completed before the current task can proceed.

-cmds {Cmd list}

Cmd operators associated with this Task node; they are launched in sequence (as resources become available) after all subtasks are completed successfully; if a Task is simply a grouping node it won't need to define any commands.

-cleanup {Cmd list}

clean-up Cmd operators for this node; these commands are executed after those in the -cmds section (if any), or during job deletion if this node was on an active path (some child had dispatched a command); they also run during task-restart if this task or one of its parents had a Task-level (shared) server checked out.  

-chaser {launch_expr}

an external application launched by users from the UI, typically to view a rendered frame; the UI activates the launching button only after the regular commands for this task have completed successfully. When a web browser is connected as an alfred UI there is special handling of chaser commands which have the form "sho imagefile" (this is the default for scripts generated by MTOR, sho(1) is the image display tool included with the RenderMan Artist Tools). Specifically, the dispatcher will make the named "imagefile" available for downloading to the browser. See the alfred.ini site configuration file for details on enabling this feature (httpImgRoot).  

-preview {launch_expr}

launches an external application in the same manner as -chaser, however this version activates the launching button before the commands have completed.

-service {server keys}

under certain circumstances it is useful to check-out a remote server for the duration of an entire Task (its subtasks and commands); a service specification as a Task option accomplishes this; the server is checked back in when the Task completes or when there are no more references to the Task's associated id.

-serialsubtasks 1

This option alters the parallel execution strategy applied to this task's dependent child tasks, i.e. those specified within this task's "-subtasks {...}" block. Under normal circumstances it is desirable to allow tasks which are siblings to execute in parallel; that is: a task and all of its subtasks are presumed to be independent of its siblings, and thus the sub-trees rooted in the siblings can be dispatched in parallel. The "-serialsubtasks" option allows this scheme to be changed such that the top-level sibling tasks in a "-subtasks {...}" block are treated in a chain-like sense: each task waits for its prior sibling to complete before evaluating its own deeper subtasks and commands. This scheduling variant can simplify the scripting of jobs which have distinct sequential "chapters" or phases of actions; such as "prepare," "render," and "clean-up" phases, each of which consists of several subtasks. This sort of thing can also be accomplished with elaborate Instance node references, or sometimes with deep linear nesting of single "phase" tasks with lots of Cmds. The serialsubtasks serialization is only applied to the immediate child tasks in this task's "-subtasks {...}" block; nested child tasks below them are scheduled in parallel as usual, unless another "-serialsubtasks" is specified farther down the hierarchy.

-id {name}

an identifier for a task; used by Cmds for runtime substitution of task-level (shared) remote server names; the id is valid in the scope of this Task (i.e. its subtasks and commands).

-sqlset {field=val,field=val,...}

specifies initial values for specific fields in the "Task" table record associated with this job in the "BatCave" database, if database support is enabled. Syntax is as described for Job -sqlset, with the only difference being the table which is updated (Task vs Job).

Cmd {appname [app args]} [options]

appname

the name of an application to launch, and its arguments and invocation options; see the launch expression discussion for details on runtime substitution variables, and restrictions (especially with regard to shell-style command pipelines).

-msg {text_for_app_stdin}

command messages to be piped to stdin of the launched app; see the launch discussion for an example.

-service {server keys}

specifies a keyword search expression used to associate a remote server with this command; see the service keys discussion below for syntax. The server lookup is done by the maitre_d using the service and access definitions defined in the master schedule. Command launching blocks until an appropriate server becomes available and is checked out; the server is checked back in when the Cmd completes or when there are no more references to the Cmd's associated id.  

-tags {tag list}

specifies a list of (blank-delimited) words which will be tallied by the maitre-d; tag tallies are compared against the alfLimit values defined in the alfred.schedule file to determine whether the command can be launched or whether it must wait for the tallies to decrement (when another command with similar tags completes).

-metrics {metrics expression}

specifies a logical expression which will evaluated for each candidate remote server slot. The expression returns a non-zero numeric value when a given slot meets the desired criteria and should be bound to the command for launching. A return value of zero indicates that the given slot does not currently meet the required criteria. See the metrics discussion for examples and more details.

-id {name}

an identifier for a command; used by other Cmds for runtime substitution of remote server names and command result values; the id is valid in the scope of this Cmd's enclosing Task (i.e. the task's subtasks and commands).  

-expand 1/0

setting the option value to 1 indicates that this command produces additional Alfred script as its output. This is a mechanism for growing the job description during runtime. Everything printed to stdout by the launched app will be collected; when the command completes, the collected worklist will be processed to produce a new subtree of additional nodes (i.e. new Tasks containing Cmds) which will become new subtasks of the current Task. This feature is primarily used by mtor in batch mode, which can be configured to generate RIB files "on demand" in a distributed fashion as the job progresses, rather than pregenerating all of the RIB for a long sequence of frames before any rendering begins. This dynamic RIB generation, as well as the on-the-fly self-modification of the associated per-frame alfred instructions, can significantly reduce the total "disk footprint" of the job since only active frames are on disk. However, since RIB generation itself can sometimes be a lengthy process, a balance must be maintained between keeping the generated RIB footprint small and ensuring that enough RIB has been generated "ahead" to keep renderers busy. The alfred dispatcher employs a special tunable look-ahead gating heuristic to delay the execution of "-expand 1" nodes when all server resources are busy (this is known as "thwarting"). The default value is 0.

-refersto idref

commands which make a reference to an external runtime value must declare that fact using this option. For example, "-refersto bob" declares that a Cmd will reference the hostname or slotname values associated with another Cmd (or Task) which has previously checked-out a remote server; the referenced Cmd or Task must be given a name using the the option "-id bob" (see the substitution discussion).

-atleast {min_servers}

specifies that at least min_servers remote servers must be bound to this command before it can be launched (only meaningful if -service is specified); default is the job-wide minimum server count specified with the Alfred -n option, which in turn defaults to one remote server.

-atmost {max_servers}

specifies that at most max_servers remote servers should be bound to this command when it is launched (only meaningful if -service is specified); default is the job-wide maximum server count specified with the Alfred -n option, which in turn defaults to one remote server.

-samehost 1

Constrains a multislot checkout (using atleast/atmost) to slots which are all on the same physical host.   This is a requirement for multi-threaded applications, since threads are part of a single process.   See the "%n" substitution pattern for a useful mechanism for inserting the actual number of found slots into the application's argument list.

-envkey {key}

Specifies an arbitrary key (a name or number) which will be passed to the remote alfserver.   This option is meaningful for RemoteCmd only.   There is a procedure defined in alfserver.ini which can examine the envkey associated with each launch request, the procedure can then customize environment variables or other launch conditions, and even rewrite the command line itself, based on the envkey and other inputs such as the name of the requesting user.

-grab {exclusion_token}

specifies the name of token which must be "free" before the command is allowed to execute.   If several commands issue a grab on the same token name, and they are all otherwise ready to launch in parallel, then they will block and execute one at a time as the token is acquired and released by each command in turn.

-if {boolean_expression}

a ready-to-execute command evaluates this expression, and if it returns non-zero it proceeds with its launch; if the expression result is zero then the command is skipped (converted immediately to “done”) without being launched. See the example for more information on the expression syntax.

-retryrc {integer_return_codes}

When specified, the value(s) specified will be compared to the the numeric exit status from the executed command.   If a match occurs, then the command will be retried, often in the very next dispatching pass.   The idea is provide a way to work around failures which are known to be transient. See the %r substitution variable for a way to alter the arguments of a restarted command.  These retries happen independently from the "auto-retry" user preference, and do not decrement the auto-retry count.  For RemoteCmd, the "auto-avoid server" count is applied, if the retries continually occur on the same remote host.

RemoteCmd {appname [app args]} [options]

This operator accepts exactly the same options as the Cmd operator. There are two important differences:

• The specified launch-expression is executed on the bound remote server, not on the local host as with Cmd. Whereas Cmd launches client applications which themselves to connect to the remote servers acquired by Alfred, RemoteCmd is used to launch "regular" applications on the remote host directly. RemoteCmd is similar to rsh(1) in this regard, although it provides additional features to Alfred users. Important: in order for RemoteCmd to operate, there must be a copy of alfserver running on the remote host.

• Typically the RemoteCmd launch-expression does not contain any reference to the name of the selected remote server, unlike command lines used by the Cmd operator which require a reference. For example:

    RemoteCmd {render /shared/rib/some.rib} -service pixarRender

  The render executable will be launched on a remote server which matches the pixarRender keyword in the master schedule. Alfred and alfserver work together to launch and track it. The render executable itself doesn't know about or accept remote host names as command arguments, so placing a %h or other server reference in the launch expression would be inappropriate. However, these run-time substitutions are still available for custom scripts that require them.

Instance {taskref}

taskref

the name by which an Instance node refers to its target. Instances are essentially pointers to Tasks elsewhere in the tree, and they function as Tasks in the dependency scheme, i.e. if a Task contains an Instance in its subtask list, it will block until the real Task pointed to by the Instance is complete. Instances are most often used to indicate a shared prerequisite, for example several independent/parallel frame renderings may depend on the prior creation of an environment map. The referenced Task is identified by its title string, which must exactly match the string given here.

Assign varname   {value_string}

varname

name of a job global variable which will be referenced in the job Tasks

value_string

the string which is assigned to the name specified by varname.
Assign statements go in the Job -init section, see the example.

Iterate varname   -from n   -to m   -by i   -template {script}   [options]

varname

the name of a variable which will be iterated during the course of the job.

-from nnn

initial value of the iterated variable. May be an integer or real number.

-to nnn

final value of the iterated variable (note: this is inclusive; the iterate will continue to run while the variable is less than, or equal to, this value. If the to is less than the from value then a decrementing iteration is expected and the termination test will "greater than or equal to". May be an integer or real number.

-by nnn

increment to be applied to the iterated variable, may be an integer or real number. The special notation   -by binary   causes the variable to cycle through its values using a non-linear, so-called "binary" sequence, which is useful for producing animation frames in progressive detail.

-subtasks {Tasks or Instances}

As with Tasks, the subtasks are dependencies which must be completed before the Iterate can proceed with its first cycle.

-template {Tasks or Instances}

Defines the a block of Alfred script which will be replicated every time the Iterate operator cycles. On every cycle the current value of varname will be substituted wherever $varname occurs in the template script, then the resulting subscript is inserted into the job tree just before the Iterate node's current position. See the example below.