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

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 rush -autodump

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 rush -command

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 rush -rc

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 rush -criteria

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 rush -dependon

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 -- send email only when job is dumped rush -donemail -- change the 'DoneMail' setting for a running job rush -dumpmail -- change the 'DumpMail' setting for a running job

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 rush -af rush -rf

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 rush -frameflags

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 rush -imgcommand

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 LogDir -- jobstartcommand's output log is written here as 'jobstartcommand.log' rush -jobstartcommand -- command line equivalent

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 LogDir -- jobdonecommand's output log is written here as 'jobdonecommand.log' rush -jobdonecommand -- command line equivalent

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 LogDir -- jobdumpcommand's output log is written here as 'jobdumpcommand.log' rush -jobdumpcommand -- command line equivalent

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 rush -jobremarks

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 rush -licpausesecs

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: jobstartcommand.log -- the output of JobStartCommand jobdonecommand.log -- the output of JobDoneCommand jobdumpcommand.log -- the output of JobDumpCommand 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 rush -logdir JobStartCommand JobDoneCommand JobDumpCommand

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 FrameLog.Ext rush -logext

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 rush -logflags

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 rush -maxcpus

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 rush -maxtime rush -maxtimestate

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 MaxTime rush -maxtime rush -maxtimestate

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 rush -an rush -rn

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 rush -nice

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 rush -jobnotes

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 rush -priority

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 rush -ram

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 rush -pause rush -cont

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 rush -title

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 ForceUid ForceGid NtRushUid NtRushGid Permit

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 DependOn rush -waitfor

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 WaitFor DependOn rush -waitforstate