RUSH RENDER QUEUE - SUBMIT COMMANDS
(C) Copyright 1995,2000 Greg Ercolano. All rights reserved.
V 102.41 08/09/04
Strikeout text indicates features not yet implemented


Submit Command Reference


  AutoDump  
 Description
    Optional.

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

      Autodump Examples
      autodump off Don't autodump; job remains when frames are DONE (default)
      autodump done Job dumps itself when all frames are DONE
      autodump fail Job dumps itself if job finishes with any FAIL frames (New in 102.40)
      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'.

 See Also

  Command  
 Description
    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

    It is important that the 'command' executed returns an exit code to rush that indicates whether the command succeeded or failed. Example exit codes rush needs to see:

      Exit Codes
      exit 0 Succeeded; frame will show in framelist as 'Done'
      exit 1 Failed. Frame will show in framelist as 'Fail'
      exit 2 Retry. Frame will be requeued, showing up as 'Que'.

    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.:

      Specifying Shells
      command    perl //server/jobs/myshow/myrender.pl -z 2 -blur Runs a Perl script
      command    csh //server/jobs/myshow/render_me.csh 320 243 Runs a C-shell script

    WinNT Note - Use UNC paths for the absolute path to the render script. This prevents problems with inconsistently mapped drive letters. Both examples above are UNC style paths.

 See Also

  Cpus  
 Description
    Mandatory.

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

    More than one 'cpus' command can appear, and more than one specification can be made for each cpu command (separated by spaces), allowing you to make several cpu specifications on the same line, or on separate lines.

    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 Examples
      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
      cpus +any=10.1@100 (New in rush 102.40g)
      Use up to 10 cpus at 100 priority on the network,
      but no more than 1 cpu on each host.
      cpus +any=5@900k
      cpus +any=20@1
      Example of staircased priorities. Two specifications are used;
      one request of any 5 cpus on any available machines at 900k,
      and another 20 at a low priority of 1.

    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.

    Here's a diagram showing all possible special characters in a cpu specification:

                +host=4.1@200ka
                      | | |  |
                      | | |  |
                      | | |  |
                      | | |  flags (Kill, Almighty)
                      | | priority
                      | Max cpus per host
                      Max cpus across network (instances of Cpu)
    	
 See Also

  Criteria  
 Description
    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 cumulative.

    Here are some more examples:

      Criteria Examples
      criteria - Disabled; no criteria is used (default)
      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 - Use all available machines (no criteria)
      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.

 See Also

  DependOn  
 Description
    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

 See Also

  DoneCommand  
 Description

    PHASE OUT.

    Synonym for JobDumpCommand, which is what future programs should use in its place.

  DoneMail  
 Description
    Optional.

    Sets the email address(s) of people to receive mail as soon as the job finishes rendering the last frame, or when the job is dumped.

    This means one can receive several emails if the job runs to completion, then has its frames requeued. Each time the job renders the last frame, the system will send an email.

    If you want to receive only one email when the job is actually dumped, use DumpMail instead.

    Only one DoneMail command should appear in a submit script; multiple instances of the command are not cumulative, only the last will take effect.

    The email message will consist of the 'rush -ljf' (Jobs Full) and 'rush -lf' (Frames) reports, so one can see which machines rendered which frames, how long each frame took, etc.

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

    Some possible settings for DoneMail:

      DoneMail Examples
      donemail - Disabled; no mail is sent. (default)
      donemail fred@somedomain.com Send mail to fred@somedomain.com
      donemail fred,jack Send mail to Fred and Jack

    Keep in mind that if LogDir is configured, the Frame List and Jobs Full reports will also be written to disk in that directory, so receiving the emails just to keep track of this info may be redundant.

 Notes
    (behavior modified in 102.41)
    In releases before 102.41, there was only 'DoneMail', and it only sent mail when a job was dumped.

    Customers asked for a newer behavior that made more sense, which was to send mail whenever the last frame of a job completed (so that jobs could remain in the queue). Since this new behavior was more fitting for 'DoneMail' than the old behavior was, the old behavior was moved to DumpMail, a more appropriate name for that behavior.

 See Also

  DumpMail  
 Description
    Optional.

    Sets the email address(s) of people to receive mail when the job is dumped.

    This means only one email will be sent, when the job is either manually dumped, or when it is configured to AutoDump.

    If you want to receive email as soon as the last frame renders, use DoneMail instead.

    Only one DumpMail command should appear in a submit script; multiple instances of the command are not cumulative, only the last will take effect.

    The email message will consist of the 'rush -ljf' (Jobs Full) and 'rush -lf' (Frames) reports, so one can see which machines rendered which frames, how long each frame took, etc.

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

    Some possible settings for DumpMail:

      DumpMail Examples
      dumpmail - Disabled; no mail is sent. (default)
      dumpmail fred@somedomain.com Send mail to fred@somedomain.com
      dumpmail fred,jack Send mail to Fred and Jack

    Keep in mind that if LogDir is configured, the Frame List and Jobs Full reports will also be written to disk in that directory, so receiving the emails just to keep track of this info may be redundant.

 See Also
    DoneMail -- send email when last frame of job completes rush -donemail -- change the 'DoneMail' setting for a running job
    rush -dumpmail -- change the 'DumpMail' setting for a running job

  Frames  
 Description
    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 Examples
      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|Que:

      Frame States
      frames 1-5=Done Frames 1 thru 5 in DONE state
      frames 6-10=Fail Frames 6 thru 10 in FAIL state
      frames 16-20=Hold Frames 16 thru 20 in HOLD state

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

      Frame Notes
      frames 1-10:Black Notes for frames 1 thru 10 is "Black"
      frames 11:Fade_up_on_sc17 Notes for frame 11 is "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.
 See Also

  FrameFlags  
 Description
    Optional.

    Changes flags that affect frames.

      Frame Flags
      keepnotes Disables automatic clearing of 'NOTES" field in framelist
      when a frame starts rendering.
      - No flags. (Default)
      Default behavior is for NOTES field in framelist to be cleared
      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.

 See Also

  ImgCommand  
 Description
    Optional.

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

      ImgCommand Examples
      imgcommand - Disables; no image command defined (default)
      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.
      ('&' insures 'flip' runs in the background.)
      imgcommand start /b flip //server/imgs/att.%04d.sgi Windows: Invokes 'flip' to view images.
      'start /b' insures it runs in the background

    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.

 See Also

  JobStartCommand [-nolog]  
 Description
    Optional. (New in rush 102.40 and up)

    The job executes this command on the job server just before the job begins running frames. This command is executed ONLY ONCE, on the job server.

    Use this command to run preparation commands for the job, such as preparing network directories before rendering.

    If a job is submitted to WaitFor other jobs, the 'jobstartcommand' will not run until the job first changes into the RUN state, when the WaitFor criteria is met.

    If a job is submitted in the Pause or Wait state, the jobstartcommand will not be executed until the job enters the Run state.

    While the command is running, the job will show a status of 'StartCmd' in 'rush -lj' and 'rush -laj' reports. The command will be passed the jobid in the RUSH_JOBID environment variable, so it's possible for the script to use rush commands to query the job.

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

    Exit codes are currently ignored.

    The stdout and stderr output from the command is written to a file called 'jobstartcommand.log' in the LogDir. This can be disabled if LogDir is disabled, or (New in 102.40f) if the jobstartcommand's '-nolog' option is specified, eg. jobstartcommand -nolog <command..>.

    Here's a state diagram showing the various states the job status transitions through:


    Click on the image to see a larger version.

      JobStartCommand Examples
      jobstartcommand perl //server/share/bin/jobstart.pl Sets command to run a perl script
      jobstartcommand -nolog perl //server/share/bin/jobstart.pl 102.40f and up only
      Same as above, but 'jobstartcommand.log' isn't created.
      jobstartcommand - Disables the jobstartcommand (Default)

 See Also

  JobDoneCommand [-nolog]  
 Description
    Optional. (New in rush 102.40 and up)

    This command is executed on the jobserver whenever the job finishes the last frame. The command will be executed whether the job ends up in the Done or Fail state. The command can find out the status of the job using 'rush -lj'.

    The command can be executed more than once during the lifetime of a job; if a job finishes, and someone requeues the frames, when those frames finish rendering, the jobdonecommand will again be executed.

    Use this command to run commands that organize the data after all frames have finished rendering. (eg. make a QuickTime file out of a range of frames)

    While the command is running, the job will show a status of 'DoneCmd' in 'rush -lj' and 'rush -laj' reports. The command will be passed the jobid in the RUSH_JOBID environment variable, so it's possible for the script to use rush commands to query the job.

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

    The stdout and stderr output from the command is written to a file called 'jobdonecommand.log' in the LogDir. This can be disabled if LogDir is disabled, or (New in 102.40f) if the jobdonecommand's '-nolog' option is specified, eg. jobdonecommand -nolog <command..>.

    Here's a state diagram showing the various states the job status transitions through:


    Click on the image to see a larger version.

      JobDoneCommand Examples
      jobdonecommand perl //server/share/bin/jobdone.pl Sets command to run a perl script
      jobdonecommand -nolog perl //server/share/bin/jobdone.pl 102.40f and up only
      Same as above, but 'jobdonecommand.log' isn't created.
      jobdonecommand - Disables the jobdonecommand (Default)

 See Also

  JobDumpCommand [-nolog]  
 Description
    Optional.

    The job executes this command just before the job is removed. Rush guarantees no frames are still running.

    Use this command to run cleanup commands for the job.

      (New in rush 102.40f and up)
      The option -nolog can be specified to disable the creation of the 'jobdumpcommand.log' file. This is useful to prevent 'file in use' errors on Windows if you want the command to remove the entire logdir as part of a cleanup operation.

    While the command is running, the job will show a status of 'DumpCmd' in 'rush -lj' and 'rush -laj' reports. The command will be passed the jobid in the RUSH_JOBID environment variable, so it's possible for the script to use rush commands to query the job.

    The JobDumpCommand should not run any rush command that requeues frames, or re-starts the job, to avoid confusing the user. Otherwise you might make it seem impossible for the user to dump the job.

    The stdout and stderr output from the command is written to a file called 'jobdumpcommand.log' in the LogDir. This can be disabled if LogDir is disabled, or (New in 102.40f) if the jobdumpcommand's '-nolog' option is specified, eg. jobdumpcommand -nolog <command..>.

    Here's a state diagram showing the various states the job status transitions through:


    Click on the image to see a larger version.

      JobDumpCommand Examples
      jobdumpcommand perl //server/share/bin/jobdump.pl Sets command to run a perl script
      jobdumpcommand -nolog perl //server/share/bin/cleanup.pl 102.40f and up only
      Disables the logging to 'jobdumpcommand.log',
      so cleanup avoids Windows 'file in use' errors.
      jobdumpcommand - Disables the jobdumpcommand (Default)

    Here's an example JobDumpCommand script that pipes the framelist through a script that generates a web page report, and emails it to the job's owner.

    #!/bin/csh -f
    
    # EXAMPLE 'JobDumpCommand' 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 JobDumpCommand should avoid doing anything to the job that might make it continue running (eg. 'rush -cont'). Though possible, this would confuse someone manually trying to dump the job, only to find it restarting itself.

 See Also

  LicPauseSecs  
 Description
    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.

      ImgCommand Examples
      licpausesecs 60 Sets the job pause time for license errors to 60

 See Also

  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 log 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.


New features in rush 102.40 and up

Additional Logs

    In addition to the 'framelist' and 'jobinfo' files, these may also appear in the LogDir if the respective commands are set:

Jobid In Logdir Name

    '%s' can appear as the last component of the directory name, which is replaced with the job's jobid string. This is useful if wanting to make each job's log directory a unique name. Since you can't know what the jobid is until rush creates the job, when %s is specified, rush will create the directory for you.

      Using '%s' With Logdir
      logdir //server/share/logs/%s OK: "//server/share/tahoe.34" created
      logdir //server/share/%s-mylogs OK: "//server/share/tahoe.34-mylogs" created
      logdir //server/share/%s/mylogs BAD: '%s' is not in last component!

Caveats

  • The directory must exist relative to both the job server and all machines participating in rendering

  • The directory must be read/writable by the user submitting the job.

  • If '%s' is specified, the directory will be created with mkdir by the daemon, implying the first part of the path must already exist.

  • If '%s' is specified and the mkdir fails, the job submit will fail.
    New in 102.40h and up: it is no longer an error if the directory already exists.

  • Windows Users: Use UNC paths for the absolute path to the logdir. This prevents problems with inconsistently mapped drive letters. A UNC example:

      logdir //server/share/rush/soft/logs

      Logdir Examples
      logdir //server/share/logs Logs are dumped into /server/share/logs directory
      logdir //server/share/logs/%s Embeds jobid in path, does mkdir //server/share/logs/ for you
      logdir - Disables log files (Default)

     See Also

  LogFlags  
 Descriptions
    Optional.

    Sets optional flags that control how log files are created.

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

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

      LogFlags Options
      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
      Like 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.

 See Also

  MaxCpus  
 Description
    Optional.

    Sets the maximum number of cpus a job can use.

    Puts a cap on the entire job. If set to 0, there is no limit.

      MaxCpus
      maxcpus 0 No limit (Default)
      maxcpus 15 Limit job to no more than 15 cpus busy rendering

 See Also

  MaxTime  
 Description
    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 killed.

    By default the frame is requeued (Que), but can be set to Fail, Hold, or Done using MaxTimeState. It is common to want to have frames "Fail" instead, in which case be sure to specify 'maxtimestate fail'.

    The MaxTime 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 Examples
      maxtime 00:00:00 Disables maxtime (Default)
      maxtime 01:30:00 Frames requeue if elapsed time exceeds 1 hour 30 minutes
      maxtime 01:30:00
      maxtimestate fail
      Frames fail if elapsed time exceeds 1 hour 30 minutes

 See Also

  MaxTimeState  
 Description
    (New in rush 102.40 and up)

    Optional.

    Sets what happens when MaxTime timer expires.

    By default, rush requeues (Que) a frame when its MaxTime timer expires. You can change this to any of:

      MaxTimeState Values
      maxtimestate que Frames become "Que" when timer expires (Default)
      maxtimestate fail Frames become "Fail" when timer expires
      maxtimestate done Frames become "Done" when timer expires
      maxtimestate hold Frames become "Hold" when timer expires

     See Also

  NeverCpus  
 Description
    Optional.

    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.

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

 See Also

  Nice  
 Description
    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 Examples
      nice 10 Niceness of 10 (default)
      nice 0 run with 'normal user' not-so-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
    	:
    	
 See Also

  Notes  
 Description
    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
    	

 See Also

  Priority  
 Description
    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.

 See Also

  Ram  
Recommended.

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.

The ram value is passed to the render script via the RUSH_RAM environment variable.

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

 See Also

  State  
 Description
    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'.

 See Also

  Title  
 Description
    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.

 See Also

  WaitFor  
 Description
    Optional.

    Sets up the current job to wait for a particular time, or for other jobs to complete.

    You can use WaitForState to define what state you want the other jobs to be in before this one starts.

    When the current job has 'waitfor' configured, it won't begin rendering frames until the time elapses (if any) and if the jobs specified have either entered the state specified with WaitForState, or have dumped.

    In this way, jobs can be chained together so that one waits for the other, or set up not to start until a specified time.

    See Chaining Jobs for scripting techniques to do this.

    (New in 102.40) WaitFor 'time values' can either be relative or absolute. Examples:

      WaitFor Time Values
      +8h 8 hours from now
      +60m 60 minutes from now
      +08:30:00 8 hours 30 minutes from now
      17:00 at 5pm
      5:30p at 5:30pm
      5:30pm at 5:30pm
      17:45,07/22/2002 at 5:45pm on 07/22/2002
      12:30p,07/22/2002 at 12:30pm on 07/22/2002

    The 'WaitFor' time value will show up in 'rush -ljf' reports in two places; once in the 'WaitForTime:' field as an absolute time in MM/DD/YY,HH:MM:SS format, the other in the 'WaitFor:' field as a relative time in +HH:MM:SS format if the time has not yet expired.

    Example WaitFor usage:

      WaitFor
       waitfor       radius.445 radius.446  
       waitforstate  done
      Wait for jobs radius.445 and radius.446 to both be
      either Done or dumped. If either job Fails (ie. has
      any Fail frames) we continue to wait.
       waitfor       7:30p Wait until 7:30pm before starting job.
       waitfor       +24h Start job in 24 hours from now
       waitfor       +24h radius.445
       waitforstate  done
      Start job no sooner than 24 hours from now,
      AND don't start until 'radius.445' is either Done
      or dumped.
       waitfor       radius.445 radius.446  
       waitforstate  donefail
      Wait for jobs radius.445 and radius.446 to both be
      either Done or Fail or dumped. In this way, once all
      the frames in the other two jobs have finished rendering,
      the current job starts.

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

 See Also

  WaitForState  
 Description
    Optional.

    Controls what circumstances cause the WaitFor trigger.

    For a tutorial on how to have one job wait for another, see Chaining Jobs.

      WaitForState Options
      waitforstate done WaitFor waits for other jobs to be Done;
      all frames must be Done (no Fail frames)
      waitforstate donefail WaitFor waits for other jobs to be Done, all frames must be Done or Fail.
      waitforstate fail WaitFor waits for other jobs to be Done, at least one frame must be Fail.
      Use this if you want a job to run if another job fails.
      waitforstate dump WaitFor waits for other jobs to dump (Default)

    In this example, the job is set up to wait for all frames to be Done in jobs 'radius.445' and 'radius.446':

    waitfor       radius.445 radius.446
    waitforstate  done

    CAVEATS: In all cases, dumping the jobs being 'waited for' will cause the waiting job to run. eg. if jobs A and B are being waited for by C, regardless of the setting of 'waitforstate', if A and B are dumped, C will start.

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

 See Also