Rush Logo Rush Render Queue - Submit Commands
V 103.07b 05/27/16
(C) Copyright 2008, 2016 Seriss Corporation. All rights reserved.
(C) Copyright 1995,2000 Greg Ercolano. All rights reserved.

Strikeout text indicates features not yet implemented

   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 a Render Script.

    It can, however, be an absolute path to any executable, be it binary 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, to avoid problems with stdout/stderr when running scripts (perl, python, csh..) you should specify the interpreter as part of your 'command'. So if running a perl script, include 'perl' in your command, eg:

      Specifying Scripts
      command    perl //server/jobs/myshow/myrender.pl -z 2 -blur Runs a Perl script
      command    python //server/jobs/myshow/render_me.py 320 243 Runs a python 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.

    (New in Rush 103.00)
    You can use 'CommandFlags' to affect how the 'command' is invoked, such as indicating whether to run the command in a native shell, whether to enable runtime environment variable expansions, handle quoting (to allow commands that contain spaces), character escaping, etc.

See Also

   CommandFlags  

Description

    (New in Rush 103.00)
    Optional.

    Sets optional flags that affect how the render command is executed.

    The following flags are supported:

      CommandFlags Options
      quote Honor double quotes in the render command.
      This can be used to protect spaces in command arguments.
      escape Honor escape characters (\) in the render command.
      Use this to escape certain characters (like '$' and '"').
      Use this to protect quotes-within-quotes (if 'quote' is specified)
      and to protect '$' (if 'expandvars' is specified)
      expandvars Expand environment variables in the render command
      before it's executed. Variables can be specified in the format ${VARNAME}
      across both platforms.
      useshell Run the render command in a native shell.
      Under windows this means a DOS "cmd" shell.
      Under unix this means a Bourne /bin/sh.
      off Disable all the above flags.
      This is the default behavior if commandflags aren't specified.

    Quote
    Use the 'quote' option if you intend to pass a command that includes quoted arguments to protect spaces. Use the 'escape' option if you are including escape characters to escape quotes.

    For instance, to get the desired results to run the command:

            perl -e "print \"Hello world!\\n\";"
            
    ..then you would use these two options. eg:
            rush -submit << EOF
            :
            commandflags   quote escape
            command        perl -e "print \"Hello world!\\n\";"
            :
            EOF
            

    ExpandVars
    Use the 'expandvars' option if you intend to have environment variables in your command, and want them expanded at runtime. This uses the ${VARNAME} syntax across platforms, so for instance ${RUSH_JOBID} will expand to the job's jobid on both unix and windows machines. eg:

            rush -submit << EOF
            :
            commandflags   expandvars
            command        /bin/echo Rush jobid=${RUSH_JOBID}, user=${USER}, frame=${RUSH_FRAME}.
            :
            EOF
            

    Escape
    If you find the need to escape some of the characters with '\', combine 'escape' with 'expandvars', eg:

            rush -submit << EOF
            :
            commandflags   expandvars escape
            command        /bin/echo The value of \${RUSH_FRAME} is ${RUSH_FRAME}.
            :
            EOF
            
    Note that enabling the 'escape' flag means that all backslashes will be interpreted as escape characters, so to have actual backslashes in the command or arguments, you'd need to double them up, eg:
            rush -submit << EOF
            :
            commandflags   expandvars escape
            command        cmd /c \\\\path\\to\foo.bat -arg1 -arg2
            :
            EOF
            

    UseShell
    Use the 'useshell' option to tell Rush to run the render command in the operating system's native shell at render time. Under unix this is '/bin/sh -c', and under windows this is "cmd /c". Use this option if you need access to shell features as part of your command. (For instance, redirection, wildcards, or native variable expansion).

    As an example, if you want to run DOS internal commands like DIR or ECHO, you can enable the 'useshell' option to access them, e.g.

            rush -submit << EOF
            :
            commandflags   useshell
            command        dir c:\temp
            :
            EOF
            
    If 'useshell' wasn't specified, the 'dir c:\temp' command would likely fail with a 'Command not found' error. This is because 'dir' is not really an executable, but is a DOS-specific internal command.

    Note: using shell-specific syntax may make your commands non-portable across platforms. If you need shell specific behavior, it's better to have your render script handle executing your commands in the shell you want, so you can include logic that checks which platform it's running on, and behaves as needed.

    Off
    'off' indicates no command flags; the default behavior is to be used. This is the same as not specifying the commandflags at all.

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@200kar
                      | | |  | 
                      | | |  | 
                      | | |  |
                      | | |  flags (Kill, Almighty, Randomize)
                      | | priority
                      | Max cpus per host
                      Max cpus across network (instances of Cpu)
    
                Flags
                -----
                k  - Kill flag. 
                     For the host(s) and priority specified, this cpu specification
                     will KILL lower priority jobs that are not 'almighty'. Use carefully!
    
                a  - Almighty flag.
                     Cpu requests with this flag set prevents other jobs with 'k'ill priority
                     from killing this job. Useful for jobs that really can't be killed, like
                     tape backups, film records and such. This flag is only useful when other
                     jobs use 'k'.. otherwise it has no effect. This flag has no effect on
                     requeuing frames or job dumping.
    
                r  - Randomize host distribution.
                     When a job is submitted, by default rush expands cpu requests like "+any"
                     in the order the hosts appear in the hosts file. This means hosts near the
                     top of the file are more likely to immediately start a render if those machines
                     have available processors. The 'r' flag randomizes this ordering to prevent
                     job starts from focusing on those machines higher in the rush hosts file.
    
            

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 of jobs that do not already exist in the queue.

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

    (New in Rush 103.00) You can use DependOnState to define what state you want the dependon job's frames to be in for frames in the current job to start rendering. The default is 'done', which means frames will start rendering when all the dependon job's frames become 'Done'.

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

      DependOn
       dependon  tahoe.445 tahoe.446   If the current job has frames in the "Hold" state, they will
      automatically transition to "Que" when the corresponding frames
      in jobs tahoe.445 and tahoe.446 transition to "Done".

      Jobs tahoe.445 and tahoe.446 must already exist in the queue,
      or an error will occur on submit. (See -i option below to make
      an exception for this)

      Once a frame transitions from "Hold" to "Que", it will
      immediately become available for rendering.

      Since "dependonstate" isn't specified, the default will be
      dependonstate done. So if frames in the other two
      jobs transition to anything other than "Done" (e.g. "Fail),
      the "Hold" frames in the current job will remain "Hold".
       dependon  -i tahoe.445 tahoe.446   Same as the first example, but it is not a fatal error if either
      jobs tahoe.445 or tahoe.446 do not currently exist.

      If one of the two jobs exist, the non-existing job will be ignored,
      a warning will be printed, and only the existing job will control
      frames in the current job.

      If both jobs don't exist, "Hold" frames in the current job
      will immediately change to "Que".
       dependon       tahoe.445 tahoe.446  
       dependonstate  donefail
      Same as the first example, except frames in the current job
      will transition from "Hold" to "Que" if corresponding frames
      in tahoe.445 and tahoe.446 transition to either "Done" or "Fail".

See Also

   DependOnState  

Description

    Optional.

    Controls what circumstances frames start running when a DependOn job's frames change.

    For a tutorial on how to use 'DependOn' jobs, see Chaining Jobs.

      DependOnState Options
      dependonstate done (default) Job's frames start running whenever the
      dependon job's frames change into the 'Done' state.
      dependonstate fail Job's frames start running whenever the
      dependon job's frames change into the 'Fail' state.
      dependonstate donefail Job's frames start running whenever the dependon job's
      frames change into EITHER the 'Done' or 'Fail' state.

    In this example, the job is set up so that all its frames begin in the 'Hold' state, and those frames won't being rendering until the same frames in the two jobs 'tahoe.71' and 'tahoe.72' change into either the 'Done' or 'Fail' states:

      DependOnState Example
      rush -submit << EOF
          title         COMP
          frames        1-10
          command       python //server/jobs/rushscripts/comper.py -render
          cpus          +any=10@100
          dependon      tahoe.71 tahoe.72
          dependonstate donefail
      EOF

See Also

   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.

Legacy Notes

    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 -- set/change the 'DoneMail' value for a running job
    rush -dumpmail -- set/change the 'DumpMail' value 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.

    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 Negative frames -10 through -1 eg. -010, -009 ... -001
      frames 100.0-110.0,.1 Floating point frames 100.0 through 110.0
      eg. 0100.0, 0100.1 ... 0109.9, 0110.0

    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

    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.

    Irush will also set the following variables, useful especially if more than one frame is selected and someone hits 'View Images':

      Environment Variables 'IRUSH_FRAMES' + 'IRUSH_JOBS'

      IRUSH_FRAMES
      Will be set to the jobids/frame numbers of frames the user has
      currently highlighted in the 'Frames' report. This variable
      can be read by external scripts (Hotkey, Cmd) to work on
      frames the user has highlighted. Examples:

      The following would be the value of IRUSH_FRAMES if
      someone had frames 100-104 and frames 107 and 108 selected
      in the single job tahoe.123:

        JOBID=tahoe.123 100-104 107 108

      The following would be the value of IRUSH_FRAMES if they
      selected various frames from two different jobs (i.e.
      if two or more jobids are 'current', and one then hit 'Frames'):
            JOBID=huron.3 1-10 18 42 JOBID=tahoe.123 100-104 107 108
            ------------- ---------- --------------- ---------------
                 |           /|\            |             /|\       
                 |____________|             |______________|        
                 Job huron.3                Job tahoe.123           
                 has frames 1-10            has frames 100-104      
                 and 18 and 42              and frames 107 and 108  
                 selected.                  selected.               

      IRUSH_JOBS
      Will be set to the jobids of jobs the user has highlighted in the
      'Jobs' or 'All Jobs' report. This variable can be read by external
      scripts (Hotkey, Cmd) to work on jobs the user has highlighted.

    Here are some imgcommand examples:

      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

   JobData  

Description

    Optional.

    Each job has a free form 'job data' field, which can be used for various purposes, such as passing commands to other programs, or database information. To prevent crosstalk of data, use a string prefix for each line identifying the type of data. Rush reserves these prefixes for itself: "IRUSH:", "RUSH:".

    Each line can be no longer than 2048 characters.

      Submit Job Data Examples
      #!/bin/csh -f
      ### SUBMIT SCRIPT ###
      rush -submit << EOF
      priority 10
      :
      jobdata OURCOMPANY: show: SS21
      jobdata OURCOMPANY: shot: FFB_A
      jobdata OURCOMPANY: format: HD 1080p
      jobdata IRUSH: graphcommand "/path/to/myscript.pl -graphcommand"
      EOF
              

    When submitted, the jobdata will appear in the 'rush -ljf' report for the job, eg:

      'rush -ljf' Shows Job Data
      [erco@howland]% rush -ljf
        : 
       Elapsed: 00:47:58 
        Frames: 22 
          Cpus: rotwang=2@100k 
          Cpus: how=3@100k 
      JobData[0]: OURCOMPANY: show: SS21
      JobData[1]: OURCOMPANY: shot: FFB_A
      JobData[2]: OURCOMPANY: format: HD 1080p
      JobData[3]: IRUSH: graphcommand "/path/to/myscript.pl -graphcommand"
              

See Also

   JobRestartCommand [-nolog]  

Description

    Optional.

    The job executes this command on the job server if a job had finished rendering, and is REstarted e.g. by requeing frames or adding more frames to the job.

    Use this command to, for instance, communicate with a database system to let it know a finished job has started running again.

    This command is different from the 'jobstartcommand' in that it is NOT executed when the job is first submitted, and can run more than once over the lifetime of a job if the job is restarted several times.

    While the command is running, the job will show a status of 'RestartCmd' 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 'jobrestartcommand' 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 'jobrestartcommand.log' in the LogDir. This can be disabled if LogDir is disabled, or if the jobrestartcommand's '-nolog' option is specified, eg. jobrestartcommand -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.

      JobRestartCommand Examples
      jobrestartcommand perl //server/share/bin/jobrestart.pl Sets command to run a perl script
      jobrestartcommand -nolog perl //server/share/bin/jobrestart.pl Same as above, but 'jobrestartcommand.log' isn't created.
      jobrestartcommand - Disables the jobrestartcommand (Default)

See Also

   JobRestartCommandFlags  

Description

    (New in Rush 103.00)
    Optional.

    Sets optional flags that affect how the jobrestartcommand is executed.

    The flags for this command work the same way as they do for the CommandFlags submit command; please refer to that documentation for info.

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. (To run a command when a job is restarted, such as when a job is done and frames are requeued, see JobRestartCommand)

    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 -nolog perl //server/share/bin/jobstart.pl Same as above, but 'jobstartcommand.log' isn't created.
      jobstartcommand - Disables the jobstartcommand (Default)

See Also

   JobStartCommandFlags  

Description

    (New in Rush 103.00)
    Optional.

    Sets optional flags that affect how the jobstartcommand is executed.

    The flags for this command work the same way as they do for the CommandFlags submit command; please refer to that documentation for info.

See Also

   JobDoneCommand [-nolog] 'command [args..]'  

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 -nolog perl //server/share/bin/jobdone.pl Same as above, but 'jobdonecommand.log' isn't created.
      jobdonecommand - Disables the jobdonecommand (Default)

See Also

   JobDoneCommandFlags  

Description

    (New in Rush 103.00)
    Optional.

    Sets optional flags that affect how the jobdonecommand is executed.

    The flags for this command work the same way as they do for the CommandFlags submit command; please refer to that documentation for info.

    There are some additional flags this command supports:

      JobDoneCommandFlags that control exexcution based on job state
      These flags are mutually exclusive.
      done Runs jobdonecommand only if all frames are "Done"
      fail Runs jobdonecommand only if *any* frames are "Fail" and rest are "Done"
      donefail Runs jobdonecommand only if all frames are either "Done" or "Fail"
      always Runs jobdonecommand when job is done, regardless of the state of the frames (Default)
      (If job is dumped while frames are still 'Que', command will still run)

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

   JobDumpCommandFlags  

Description

    (New in Rush 103.00)
    Optional.

    Sets optional flags that affect how the jobdumpcommand is executed.

    The flags for this command work the same way as they do for the CommandFlags submit command; please refer to that documentation for info.

See Also

   JobRemarks  

Description

    Optional.

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

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

Historical Notes

    This command was added in 102.42a9.

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.

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

The log filenames may optionally contain a filename extension if the 'logext' submit command has been specified, or if the sysadmin has configured 'framelog.ext' in the rush.conf file.

When a job is done (finished rendering the last frame), two other files will 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/logs/tahoe.34" is created
      logdir //server/share/%s-mylogs OK: "//server/share/tahoe.34-mylogs" is 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

Historical Notes

    This command was added in 102.42.

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.

    Each line can be no longer than 2048 characters.

      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

   Ram  
Recommended.

All jobs should 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 large jobs from swapping the machines by starting too many jobs at once, or running on machines lacking ram capability.

The job's ram value is passed to the render script via the RUSH_RAM environment variable which can optionally use this value to actually limit its ram use.

The default is 0, which allows the job to run without ram requirements.

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

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.

      User Command
      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.
      (See "Caveats" below)

Caveats

    The <uid> and <gid> must be for a valid account on the job server, and they will be verified. The "ownername" will not be checked, and will simply be included as the job owner string.

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

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

    The <uid> <gid> specified must be within the value limits specified by the uidrange and gidrange commands in the rush.conf file, which by default is 100 for both. Often these need to be adjusted, since the 'www' or 'apache' users that linux machines are often pre-configured with have uid values lower than 100.

    The "user" submit command is disabled by default for security reasons.

    To enable this feature, the user invoking the command must be a member of the "permit usercmd" security group on the job server. Typically this would be /very limited/ to only e.g. the apache user, and only on the webserver. Example: if the webserver hostname is 'tahoe' and Apache runs as the user "www", then to enable this feature for the "www" user, you would include these lines to the 'permit' section of the rush.conf file (shown in red):

    	permit
    	{
    	    everything:
    	    {
    		root            # UNIX
    		administrator   # WINDOWS
    	    }
    
    	    online,offline,getoff,kill,almighty,fifo-order:
    	    {
    		*
    	    }
                
                host=tahoe	usercmd:
                host=tahoe	{
                host=tahoe	    www
                host=tahoe	}
                
    	}
    	
    This would allow the "www" user on host 'tahoe' to use the 'user' submit command when submitting jobs.

Historical Notes

    In versions of rush 102.42a9b and older, the 'user' command would only be allowed to users configured for 'permit everything' in the rush.conf file. For example, to enable the 'www' user to use 'user', that older release of rush would have used:

      rush.conf -- 'permit everything'
       ..
       permit
       {
          ...
          everything:
          {
              root
              administrator
              www                           
          }
          ...
              

    In 102.42a9c, 'usercmd' was added to the 'permit' section, allowing more fine grained control of the 'user' command, e.g.

      rush.conf -- 'permit usercmd'
      (in 102.42a9c and up)
       ..
       permit
       {
          ..
          usercmd:
          {
              www                           
          }
          ...
              

See Also

    ForceUid -- force renders to run as a particular UID
    ForceGid -- force renders to run as a particular GID
    NtRushUid -- the uid that MS Windows submitted jobs should use
    NtRushGid -- the gid that MS Windows submitted jobs should use
    UidRange -- sets the range of valid UIDs that rush will allow
    GidRange -- sets the range of valid GIDs that rush will allow
    Permit -- controls who can do what in Rush

   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 of jobs that do not already exist in the queue. If '-i' is specified, jobids that do not already exist can be added without causing an error.

    You can have a job "waitfor" one or more other jobs, the only stipulations being those 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)

    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       tahoe.445 tahoe.446  
       waitforstate  done
      Wait for jobs tahoe.445 and tahoe.446 to both be
      either Done or dumped. If either job Fails (ie. has
      any Fail frames) we continue to wait.
       waitfor       -i tahoe.445 tahoe.446  
       waitforstate  done
      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 tahoe.445
       waitforstate  done
      Start job no sooner than 24 hours from now,
      AND don't start until 'tahoe.445' is either Done
      or dumped.
       waitfor       tahoe.445 tahoe.446  
       waitforstate  donefail
      Wait for jobs tahoe.445 and tahoe.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 'tahoe.445' and 'tahoe.446':

      WaitForState Example
      waitfor       tahoe.445 tahoe.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