Rush Logo Rush Render Queue - Submit Commands
(C) Copyright 1995,2000 Greg Ercolano. All rights reserved.
V 102.42a9b08/31/09
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
      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; multiple instances of the command are cumulative. Also, multiple cpu specifications can appear on the same line (separated by spaces). Combinations can also be used.

    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 Use up to 10 cpus at 100 priority on the network,
      but no more than 1 cpu on each host.
      cpus +any=5@900k +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.

      All Hosts Report -- Criteria Field
      [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 [-i]  

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.

    More than one 'dependon' command can appear; multiple instances of the command are cumulative. Also, multiple jobid specifications can appear on the same line (separated by spaces). Combinations can also be used.

    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.

    When using dependon [jobid jobid..], it is an error to specify jobids that do not already exist.

    (New in 102.42) If '-i' is specified, jobids that do not already exist can be added without causing an error.

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

    • Must already be in the queue [unless -i is specified]
    • 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.

    You probably want the JobDoneCommand, which runs a command when the job finishes rendering the last frame.

    In very old versions of rush (pre 102.40, released in 2002), the older 'donecommand' did what the newer 'jobdumpcommand' does now; ran a command when the job was dumped.

    The old name became confusing when it was decided in 2002 to allow separate commands for done vs. dump, so the older command was simply made obsolete, replaced by the newer "jobXXXXcommand" commands with clearer names.

   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.

    (New in 102.42 and up) You can supply negative frame numbers, and floating point frame numbers. See examples below.

      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
      frames -10--1 (New in 102.42 and up)
      Negative frames -10 through -1 eg. -010, -009 ... -001
      frames 100.0-110.0,.1 (New in 102.42 and up)
      Floating point frames 100.0 through 110.0
      eg. 0100.0, 0100.1 ... 0109.9, 0110.0

    (New in 102.42 and up)
    Negative Frame Ranges. You can specify negative frame ranges as you expect; a negative frame range in ascending order will assume a step rate of +1, unless otherwise specified. To specify a descending order of negative numbers, use a negative step rate. Examples:

      Negative Frame Numbers
      frames -10--1 -10 through -1
      -010, -009, ... -001
      frames -5-5 -5 through 5
      -005, -004, ... -001, 0000, 0001, ... 0005
      frames -10--200,-1 -10 through -200
      -010, -011 ... -199, -200

    (New in 102.42 and up)
    Floating Point Frames. When you specify a floating point range of frames, the number of digits of precision used depends on how you specify the range. Examples:

      Floating Point Frame Numbers
      frames 100.0-110.0,.1 0100.0, 0100.1, 0100.2, 0100.3 ... 110.0
      frames 100.00-110.00,.10 Same as above, with two digit precision:
      0100.00, 0100.10, 0100.20, 0100.30 ... 110.00
      600.00-610.00,.28 0600.00, 0600.28, 0600.56, 0600.84, ... 609.80

    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:

      Frames Report Showing Custom Frame Notes
          [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
      frameflags keepnotes Disables automatic clearing of 'NOTES" field in framelist
      when a frame starts rendering.
      frameflags - 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 is the command IRUSH uses to display the rendered image when you middle-click on one of the frames in the irush 'Frames' report.

    The command can either be a program or a script. If the command is a script, the script can do things like determine which platform its running on, and which image display program best works on that platform. It can also interrogate the job to find out where the logs/images are being written.

    When the command is run, irush sets the RUSH_JOBID environment variable to be the job's jobid. This way, if the command is a script, it can run rush commands that know which job to work on.

      ImgCommand Examples
      imgcommand - Disables; no image command defined (default)
      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
      %04d will be replaced with a 4 digit padded version of the frame#.
      imgcommand perl /job/rushscripts/myscript.pl %s Platform independent.
      Invokes a perl script, passing the frame# as the first argument.
      '%s' is replaced with the frame number exactly as it appears
      in the irush 'Frames' report, so this will work even if the frame
      is floating point (eg. 0012.34).

    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 or %s in place of the frame number, e.g.:

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

    So if someone middle-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 (%d, %03d, %04d, etc). Also, when floating point frame numbers were introduced, '%s' is now allowed to specify all frame numbers, including floating point.

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

    Or, if your imgcommand is a script (eg. perl, python, etc), then you can use all the techniques those scripting languages support to run the image viewer.

See Also

   JobStartCommand [-nolog]  

Description

    Optional.

    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 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 python //server/share/bin/jobstart.py Sets command to run a python script
      jobstartcommand -nolog perl //server/share/bin/jobstart.pl Runs a perl script, but without creating 'jobstartcommand.log'
      jobstartcommand - Disables the jobstartcommand (Default)

See Also

   JobDoneCommand [-nolog] [-fail|-done|-donefail|-always]  

Description

    Optional.

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

    Option flags can be specified to indicate special behaviors for the jobdonecommand:

      JobDoneCommand Flags
      -nolog Prevents the 'jobdonecommand.log' from being created.

    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 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 -done perl //server/share/bin/jobdone.pl Same as above, but runs the script only if all frames are 'Done'
      (ie. if there were no 'Fail' frames)
      jobdonecommand -nolog perl //server/share/bin/jobdone.pl 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.

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

      JobDumpCommand Script Example
      #!/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

   JobRemarks  

Description

    (New in 102.42a9) Optional.

    Sets custom remarks to be shown in the REMARKS column of the Jobs and All Jobs reports.

    Historical Note: This feature was actually implemented in an earlier release, but fell out of subsequent releases up thru 102.42a8 due to a source code regression, and wasn't reinstated until 102.42a9.

      ImgCommand Examples
      jobremarks Please watch for bad frames Shows the comment "Please watch for bad frames"
      in the REMARKS column of the Job report

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 'rush -lf' frame list report at the time the job 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.


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.
    It is not 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

   LogExt  

Description

    Optional.

    Sets the (optional) filename extension used on all the frame log files for the job, including the 'framelist' and 'jobinfo' files.

    If unspecified, the default is determined by the 'framelog.ext' setting in the rush.conf file (which is normally '-', unless changed by the sysadmin).

    If 'logext' is specified, it takes precedence over the default in the rush.conf file.

      LogExt Examples
      logext - Disables any filename extensions for the log files. Examples:
      /some/path/logs/0001
      /some/path/logs/0001.old
      /some/path/logs/framelist
      /some/path/logs/jobinfo
      logext .txt Sets ".txt" to be appended to all log files for the job. Examples:
      /some/path/logs/0001.txt
      /some/path/logs/0001.old.txt
      /some/path/logs/framelist.txt
      /some/path/logs/jobinfo.txt

See Also

   LogFlags  

Description

    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

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

      Submit Job Notes Examples
      #!/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:

      'rush -ljf' Shows Job's Notes
      [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 Example
      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

   Priority.Range  

Description

    Optional.

    This sets the minimum and maximum allowable priority values, the default being 1-999.

      Priority.Range Examples
      priority.range 1 999 The default range 1 through 999
      priority.range 1 8000 Allows priorities to range from 1 to 8000

   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.

      Submit Job in Paused State
      :
      state  Pause   # Submit job in paused state
      :
              

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

      'rush -lj' Report Shows Paused Job
      [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

    Optional.

    A text string that describes the job, which will appear in job reports, audit logs, etc. Should be human-readable enough so that one can tell which show/shot the job is just by looking at it. Some shops use this value for billing and asset management.

    The title must not contain spaces; use "_" or "-" instead. Mainly this is to ensure columnar reports can be parsed correctly, since spaces are used to delimit columns.

    Titles should not be so long as to make it hard for users to read them in casual reports. If you need to associate very detailed information to jobs that users don't always need to see, the job's notes are better for this kind of info.

      title THX/LOGO

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

      'rush -lj' Shows Job Title
      [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
              

See Also

   User <uid> <gid> <username>   

Description

    Optional.

    Sets a different username for the submitted job; the uid/gid will be used by unix machines to determine the user the job should run as, and 'username' will show up as the job's owner.

    Use this command, for example, in a web server application that needs to be able to submit jobs owned by different users.

    If the job is being submitted from a Windows machine, if the job might also render on unix machines, then you should specify a <uid> and <gid> that is the ntrushuid and ntrushgid. If you're on a pure Windows network with no unix machines, you can just specify 100 for both the <uid> and <gid>.

      WaitForState Options
      user 501 20 fred Causes the job being submitted to be owned by 'fred'
      and the job will run as uid=501, gid=20 on unix machines.

    Caveats

      If forceuid/forcegid is configured in your rush.conf files, those values will override the <uid> <gid> specified in the 'user' command.

      The <uid> <gid> options specified must be within the value limits specified by the uidrange/gidrange commands in the rush.conf file.

    Security Caveats

    In the rush.conf file, the sysadmin can use the rush.conf file's permit command to control which user(s) is allowed to use this command; only users in the 'everything' section are allowed to use the 'user' submit command.

    (New in 102.42b and up) The new 'usercmd' option in the rush.conf 'permit' section allows the sysadmin to enable users specifically for being able to specify the submit 'user' command.

See Also

   WaitFor [-i]  

Description

    Optional.

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

    More than one 'waitfor' command can appear; multiple instances of the command are cumulative. Also, multiple jobid specifications can appear on the same line (separated by spaces). Combinations can also be used.

    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.

    When using waitfor [jobid jobid..], it is an error to specify jobids that do not already exist. (New in 102.42) If '-i' is specified, jobids that do not already exist can be added without causing an error.

    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       -i radius.445 radius.446  
       waitforstate  done
      (New in 102.42)
      Same as above, but '-i' ignores errors for jobids
      that don't already exist.
       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':

      WaitForState Example
      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