RUSH RENDER QUEUE - SUBMIT COMMANDS
(C) Copyright 1995,2000 Greg Ercolano. All rights reserved.
V 102.31m 03/12/02
Strikeout text indicates features not yet implemented


Submit Command Reference


Submit Commands
AutoDump 
Command
Cpus
Criteria 
DependOn 
DoneCommand 
DoneMail 
Frames
FrameFlags
ImgCommand 
LicPauseSecs
LogDir
LogFlags 
MaxTime
NeverCpus
Nice
Notes
Priority
Ram
State
Title
WaitFor
Dump job on completion
Render script to execute
Hosts (or hostgroups) to use for rendering
Criteria for matching hosts
Set inter-job frame dependencies
Command to run when job done
Send mail when job done
Frame ranges to render
Disables the automatic clearing of the framelist
Command used to display images (in irush)
Set number of seconds a job pauses with -licpause
Directory for log files
Controls logfile behavior
Set maximum time for renders
Cpus to never use for rendering
nice(2) value for running frames (Unix only)
Job notes
Default priority
Ram job expects to use (max)
Initial state for job
Title for job
Wait for other jobs to complete
    

AutoDump
(See Also: rush -autodump)

Optional.

Enables a job to automatically dump itself. Can be any of:

autodump off # Don't autodump; job remains when frames are DONE
autodump done # Job dumps itself when all frames are DONE
autodump donefail    # Job dumps itself if all frames are DONE or FAIL

In the case of 'autodump done', the job will not dump if there were any FAIL frames. If you want it to dump anyway, then use 'autodump donefail'.

Command
(See Also: rush -command)

Mandatory.

Sets the command (and optional arguments) that is executed on a per frame basis on all the remote machines.

Usually, this is always an absolute NFS path to the Render Script.

It can, however, be an absolute path to any executable or script, provided it returns rush exit codes (0,1,2), and knows how to access RUSH_FRAME to determine which frame it's working on.

    command /job/MARINER/DIVE/rush/render-script 640 480

Under Windows, if your render script is a non-native shell script (perl, csh..) you may need to specify the shell processor as part of your command, e.g.:

    command perl //tahoe/myshow/myrender.pl -z 2 -blur command csh //tahoe/myshow/render_me.csh 320 243

    WinNT Note - Use UNC paths for the absolute path to the render script. This prevents problems with inconsistently mapped drive letters. A UNC example:

      command //server-01/large6/rush/bin/myrender.bat 640 480

Cpus
(See Also: rush -rc)

Mandatory.

This command tells rush which remote machines are to be used during rendering. It is an error not to specify any cpus.

When specifying a cpu, your are telling rush at least three things:

  • The name of the host (or hosts when hostgroups are specified)
  • The number of cpus to use on that host (or hosts)
  • The job's priority to use when running on that host

The number of cpus defaults to 1 if unspecified.

If unspecified, the priority value defaults to the Priority value for the job.

Priority is a value between 1 and 999, with 999 being highest priority, 1 being lowest. Priority values can be followed by optional flags 'k' and/or 'a'. See Priority Description for a full description of how the priority mechanism works.

cpus pabst # 1 cpu on pabst, default priority
cpus pabst=4 # 4 cpus on pabst, default priority
cpus pabst=4@900 # 4 cpus at 900 priority
cpus pabst=4@900,2@500     # 4 cpus at 900 priority, 2 cpus at 500
cpus +any=10@1 # use up to 10 cpus on 'any available machine'
cpus +farm=50@1 # use up to 50 machines on the 'farm' hostgroup

Note that '+any' and '+farm' are hostgroup specifications which represent more than one hostname. "+any" is a special hostgroup that includes all machines on the network.

Hostgroups are configured by your sysadmin in the Hosts file.

Criteria
(See Also: rush -criteria)

Optional.

Criteria contains a list of words separated by logical operators (&) and (|). The strings are configured by your systems administrator, and are to be values in the Criteria column of the  'rush -lah' reports.

[erco@howland] % rush -lah
IP               Hostname   Ram  Cpus Pri Criteria
192.168.10.3     rotwang    100  2    0   +any,linux,linux6.0,intel,+dante
192.168.10.2     how        256  2    0   +any,sgi,irix,irix6.2
192.168.10.1     nt         256  1    0   +any,winnt,+dante
		

When you specify hosts to render, any Criteria you specify will limit which machines your renders will run on; if the criteria you specify don't match a particular host, even if the host is specifically requested by a Cpus command, frames will be turned away from rendering on that machine.

For instance, if your job depends on using only Linux machines or sgis running IRIX 6.2, you might submit your job with a criteria line that reads:

    criteria    ( linux | irix6.2 )

The above presumes your sysadmin uses 'linux' and 'irix6.2' as qualifiers in the host list. If you need new criteria strings configured, ask your sysadmin to add them to the rush system's hosts file.

Only one Criteria command should appear in a submit script; multiple instances of the command are not commutative.

Here are some more examples:

criteria ( linux | ( irix6 & octane ) )      # Use linux machines OR irix6 octanes.
criteria ( linux | irix6.2 ) # Only linux machines OR  irix6.2 machines.
criteria ( linux & !alpha ) # Use only linux machines that are NOT dec-alphas.
criteria ( linux & alpha & carrera ) # Use only carrera linux dec-alphas
criteria ( +any ) # Use all available machines
criteria ( !intel ) # Use all machines that are NOT intel based machines.

Caveat: There is currently no default precedence for logical operators at this time; operators are simply parsed from left to right. So be sure to use parens to imply any kind of precedence, as shown above.

DependOn
(See Also: rush -dependon)

Optional.

Make the current job's frames depend on the completion of frames in other jobs first. This lets one set up a dependency tree of jobs.

When a job is submitted with 'dependon', all the frames in the job enter the 'Hold' state. (Frames in the 'Hold' state will not be rendered until switched back to the 'Que' state.) As a particular frame in the jobs that are depended on enters the 'Done' state (i.e., finishes rendering successfully), it is then that the corresponding frame in the current job will switch from Hold to Que, allowing the frame to begin rendering, as resources become available.

You can have a job depend on several others, the only stipulations being that the dependon jobs:

  • Must already be in the queue
  • Must have been submitted from the same machine (i.e., jobids must have the same hostname)
  • Should have corresponding frames in the current job

Frames will *not* switch from Hold -> Que until *all* the jobs depended on have their corresponding frames in the Done state. Otherwise those frames will remain in the Hold state.

See Chaining Jobs for scripting techniques to do this. Example:

    dependon   radius.445 radius.446


DoneCommand
(See Also: rush -donecommand)

Optional.

When a job dumps, after the 'framelist' and 'jobinfo' files are saved in the LogDir, the optional DoneCommand script can be executed. This command can be used to compress logfiles, or parse them for errors, or yield customized web page reports, etc.

This command is executed only once, on the job server.

If the done command is set to '-', or if donecommand is not specified at all, it will be disabled.

For the DoneCommand to be executed, the job must dump. For automatic invocation, you will need to have the AutoDump command enabled, for the job to dump when all the frames are done. If AutoDump is disabled, the only way the DoneCommand will execute is if someone manually invokes 'rush -dump'.

DoneCommand scripts are passed the jobid in the RUSH_JOBID environment variable, so it's possible for the script to use rush(1) commands to query the job. Exit codes are currently ignored. The stdout and stderr output from the DoneCommand is written to a file called 'done.log' in the LogDir.

#!/bin/csh -f

# EXAMPLE 'DoneCommand' SCRIPT

set $wwwreport = /somewhere/MYPROJECT/html/`logname`/jobreport.html

# CREATE A CUSTOMIZED WEBPAGE REPORT
set logdir = `dirname $RUSH_LOGFILE`
cat $logdir/framelist | \
    my_report_generator > $wwwreport

# MAIL THE REPORT TO SOMEONE
Mail -s "$RUSH_JOBID Html Report" `logname` < $wwwreport
    

The DoneCommand should avoid doing anything to the job that might make it continue running. Though possible, this would confuse someone manually trying to dump the job, only to find it requeuing itself.

donecommand - # Disable done commands
donecommand $cwd/cleanup   # Setup script to run before job dumps itself

DoneMail
(See Also: rush -donemail)

Optional.

When a job completes, rush can be configured to send mail to a list of people using DoneMail. Only one DoneMail command should appear in a submit script; multiple instances of the command are not cumulative.

Arguments should all be valid email addresses. If more than one address needs to be specified, separate with commas. There should be no spaces in the list of addresses. Use '-' to disable sending completion mail (default).

Some possible settings for DoneMail:

donemail  -              # Mail disabled
donemail  erco@3dsite.com     # Send mail to erco@3dsite.com
donemail  fred,jack         # Send mail to Fred and Jack

Keep in mind that if LogDir is configured, framelist and jobinfo reports will be written into its directory, so sending mail might be redundant.

Frames
(See Also: rush -af/-rf)

Mandatory.

Defines the range(s) of frames to be rendered by this job. There can be several Frames commands in a submit script; they are cumulative.

    frames  1-10 # Frames 1 thru 10
    frames  100-150,2 # Frames  100 thru 150 on twos
    frames  500 507 615      # Frames  500, 507 and 615

Frame States. You can set the initial state for the frame on a per-frame basis. Possible frame state values are Done|Fail|Hold|Queue:

    frames  1-5=Done       # Frames 1 thru 5 in DONE state
    frames  6-10=Fail      # Frames 6 thru 10 in FAIL state
    frames  11-15=Hold     # Frames 11 thru 15 in HOLD state
    frames  16-20=Queue           # Frames 16 thru 20 in QUEUE state

Notes In Frames. On a per-frame basis, frames can contain notes, which show up in the last column of frame lists. Notes can be initialized to a particular string as part of the Frames command:

    frames  1-10:Black           # Notes for frames 1 thru 10  is "Black"
    frames  11:Fade_up_on_sc17    # Frame 11 has note "Fade_up_on_sc17"

The above example creates a frame list that looks like:

    [erco@howland]% rush -lf
    STAT FRAME TRY HOSTNAME PID   START          ELAPSED  NOTES
    Que  0001  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0002  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0003  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0004  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0005  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0006  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0007  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0008  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0009  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0010  0   -        0     00/00,00:00:00 00:00:00 Black
    Que  0011  0   -        0     00/00,00:00:00 00:00:00 Fade_up_on_sc17
		

Caveats:

  • Frame states and notes specifications can appear together, e.g.:

      frames 1-5=Done:This_is_a_test

  • In submit scripts, frame notes currently cannot contain spaces; use underbars instead.

  • Frame notes for each frame are normally cleared before the frame begins rendering. This is to prevent stale error messages when users utilize the notes field to advertise error messages via their render script. This 'auto clearing' can be disabled with FrameFlags.

FrameFlags
(New in rush 102.30b and up)

Optional.

Disables the automatic clearing of the framelist 'NOTES' field whenever a frame starts rendering.

By default, the NOTES field is automatically cleared before each frame is rendered. This prevents stale error messages from being left behind when a frame is requeued, since the notes field is usually utilized by TDs to advertise error conditions via their render script.

This default behavior can be disabled via the submit script command:

    frameflags keepnotes

This keeps the frame notes to whatever the user changes them to, regardless of frames being requeued, bumped, etc.

ImgCommand
(See Also: rush -imgcommand)

Optional.

This command enables IRUSH to display the rendered image when you double click on one of the frames in the 'Frames' report.

Normally, this should be an actual command that brings up one of your job's images in the background. The only difference being that you use %d or %04d in place of the frame number, e.g.:

    imgcommand ipaste -sx /job/MYSHOW/MYSHOT/images/foo.%04d.rgb

So if someone double clicks on frame 37 in an IRUSH report, IRUSH will invoke:

    ipaste -sx /job/MYSHOW/MYSHOT/images/foo.0037.rgb

..which will display frame 37 in the SGI 'ipaste' utility. All printf(3) style '%d' values are supported. Include any arguments you think are necessary in the imgcommand.

The image viewer command should background itself. If it doesn't, it will hang IRUSH until you exit the viewer. You can force the command to background itself in these platform specific ways:

  • Unix: Append an '&' to the command. This will make it run in the background.

  • Windows: Insert 'start /b ' before the image command. This will make the command run in the background. See the Windows DOS utility 'start /?' for more info.

Examples:

imgcommand imgworks /job/images/att.%04d.sgi # Unix: Invokes imgworks(1) to view the image.
# (imgworks backgrounds itself; no need for '&')
imgcommand xv /job/images/att.%04d.sgi & # Unix: Invokes 'xv' to view the image.
# ('&' assures 'flip' runs in the background.)
imgcommand start /b flip //ntserver/images/att.%04d.sgi # WINNT: Invokes 'flip' to view images.
# 'start /b' assures it runs in the background
imgcommand - # Disable image commands

LicPauseSecs
(See Also: rush -licpausesecs)

Optional.

Sets the license pause seconds to the value specified. When a license error is triggered from a render script with rush -licpause, the job enters a pause state (LicPause) for this number of seconds, then returns to the run state.

So this is the number of seconds the job remains paused after a license error occurs.

The default is 60 seconds.

For info on how to use 'rush -licpause' mechanism, see the 'How To' documentation on Render License Errors.

licpausesecs 60     # Sets the job pause time for license errors to 60

LogDir
(See Also: rush -logdir)

Recommended.

Sets the directory where logs containing the stdout/stderr of rendered frames are written to, one file per frame. The filenames are the four digit padded frame number for the rendered frame.

When a job is dumped, two other files appear in this directory:

  • framelist -- The job's frame list (i.e. 'rush -lf') at the time the job was dumped
  • jobinfo -- The 'rush -ljf' report

The directory must exist relative to both the job server and all machines participating in rendering, and the directory must be read/writable by the user submitting the job.

logdir /jobs/myjob/logs     # Logs are dumped in this directory
logdir - # Disable log files

WinNT Note - Use a UNC path for the absolute path to the logdir. This prevents problems with inconsistently mapped drive letters. A UNC example:

    logdir //server-01/large6/rush/soft/logs

LogFlags
(See Also: rush -logflags)

Optional.

Sets optional flags that control how log files are created.

The default behavior is to overwrite frame logfiles, each time a frame renders.

KeepLast tells the system to always keep the previous logfile, if there is one. It does this by renaming the previous log to an ".old" file, before creating the new log for a running frame, similar to running the command:

    mv logs/0055 logs/0055.old

KeepAll is similar to KeepLast, with the additional behavior that all 'previous' logs are kept; before a framelog is overwritten, it is concatenated to the .old file, similar to running:

    cat logs/0055 >> logs/0055.old

Beware: if your logfiles are long, KeepAll will cause significant use of disk space, since the logs will accumulate. A good reason to use KeepLast instead.

logflags - # Logs are overwritten (Default)
logflags keepall # Keep all logs; concatenate old logs in 0000.old
logflags keeplast    # Like 'keepall', but only keeps last log (don't concatenate)

MaxTime
(See Also: rush -maxtime)

(New in rush 102.30c and up)

Optional.

Sets a maximum time limit for rendering frames.

Useful for setting an upper limit for how long frames can take to render. If a frame is still busy rendering when the maxtime is exceeded, the frame is automatically requeued.

The time value is in HH:MM:SS.

NOTE: Time checks are at a resolution of approximately 30 seconds; don't expect time accuracy any more precise than that. Accuracy is also affected if the jobserver host is under load.

maxtime 00:00:00      # Disables maxtime (Default)
maxtime 01:30:00 # Frames requeue if elapsed time exceeds 1 hour 30 minutes

NeverCpus
(See Also: rush -an/-rn)

Optional.

New in rush 102.31f - hostgroups are now supported.

Sets hostnames or +hostgroups that should never be used for rendering. Overrides any Cpus specifications, ensuring hosts are not used even if specified by name in the Cpus list. More than one NeverCpus command can appear in a Submit Script; multiple instances of the command are cumulative.

nevercpus tahoe rotwang    # Never use tahoe or rotwang for rendering
nevercpus +eval # Never use any machine(s) in the '+eval' hostgroup

Nice
(See Also: rush -nice)

Optional.

Sets the default nice(2) value for the job. Higher values increase the 'niceness' to others, letting the rendering frames yield to other processes and interactive use. A value of '0' means the process runs as usual.

If unspecified, the default nice value is 10.

nice 0         # run with 'normal user' not-so-niceness
nice 10 # default niceness

Caveats

It has been noted under RedHat 6.1 Linux that nice values greater than zero will negatively affect render times considerably. Values above 10 are not recommended.

This value currently has no effect on Windows renders. To lower the priority of Windows renders, you can use the DOS 'start /LOW' command as part of your submit script's render Command, e.g.:

        # YOUR SUBMIT SCRIPT
	title       MYSHOT
	:
        command     cmd /C start /B /WAIT /LOW //tahoe/show/shot/render_script.pl
	:
    

Notes
(See Also: rush -notes)

Optional.

Each job has a free form 'notes' field, which can be used for various purposes, such as passing informational notes to other programs, or possibly to other users who will be taking over this job in a hand-off.

#!/bin/csh -f
### SUBMIT SCRIPT ###
rush -submit << EOF
priority 10
:
notes Please don't dump this job until you have visually
notes verified the matte transition at frames 205-219.
notes Call me at home if there are problems! -fred
EOF
		

When submitted, these notes appear in the 'rush -ljf' report for the job:

[erco@howland]% rush -ljf
  : 
 Elapsed: 00:47:58 
  Frames: 22 
    Cpus: rotwang=2@100k 
    Cpus: how=3@100k 
Notes[0]: Please don't dump this job until you have visually
Notes[1]: verified the matte transition at frames 205-219.
Notes[2]: Call me at home if there are problems! -fred
		

Priority
(See Also: rush -priority)

Optional.

The 'priority' value is used when cpus commands don't specify a priority value, i.e., 'cpus tahoe=4'. In such a case, the value set by 'priority' is used.

In the following example, the 'priority 10' affects the cpus that have no priority specification, shown in bold:

priority 10
:
:
cpus erie=2@100       
cpus tahoe=4
cpus +any=10
		

See Priority Description for a full description and scenarios that show how priority values work.

Ram
(See Also: rush -ram)

Mandatory.

All jobs must have a Ram value that tells the system how much memory each process is expected to use. Values are in MB, and are compared against the values shown in the Ram column of List All Cpus reports ('rush -lah').

While job is running, the configured Ram value is compared against the available ram on the remote processors. If the amount of ram your job wants is more than the remote machine has available, then the frame will not be started. This behavior prevents swapping the remote machines.

ram 128    # Only run on machines that have at least 128MB of ram available

State
(See Also: rush -pause/-cont)

Optional.

You can set the initial state for the job on submission. The only current option is to submit the job in the Pause state, to prevent the job from starting up right away.

:
state  Pause   # Submit job in paused state
:
		

After you submit the job, the job will be in the paused state:

[erco@howland]% rush -lj       # List Jobs to see job's 'Pause' state
STATUS JOBID       TITLE        OWNER    %DONE BUSY NOTES 
------ ----------- ------------ -------- ----- ---- -----------
Pause  how.857     THX/LOGO     erco     %0    0    Job paused.
		

For no good reason, arguments to 'state' are case sensitive; you have to use 'Pause', not 'pause'.

Title
(See Also: rush -title)

Mandatory.

Each job has a free form 'Title' which appears in the job reports, audit logs, etc. Some shops use this information for billing purposes.

    title THX/LOGO

Here's an example report showing where the title might show up:

[erco@howland]% rush -lj       # List Jobs to see title
STATUS JOBID       TITLE        OWNER    %DONE BUSY NOTES 
------ ----------- ------------ -------- ----- ---- -----------
Run    how.857     THX/LOGO     erco     %0    0    00:00:05
		

Titles cannot contain spaces, and should be short (<15 characters) to prevent reports from losing columnar formatting.

WaitFor
(See Also: rush -waitfor)

Optional.

Sets up the current job to wait for other jobs to dump. When the current job has 'waitfor' configured, it won't begin rendering frames until the jobids specified have dumped themselves. In this way, jobs can be chained together so that one waits for the other. See Chaining Jobs for scripting techniques to do this. Example usage:

waitfor   radius.445 radius.446

See also DependOn for making job dependencies at the frame level.