.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MNI::Batch 3" .TH MNI::Batch 3 "2001-10-29" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" MNI::Batch \- execute commands via the UCSF Batch Queuing System .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use MNI::Batch qw(:all); \& \& MNI::Batch::SetOptions( queue => \*(Aqlong\*(Aq, synchronize => \*(Aqfinish\*(Aq ); \& \& StartJob( job_name => \*(AqMake List\*(Aq, stdout => \*(Aqlogfile\*(Aq, merge_stderr => 1 ); \& QueueCommand( \*(Aqls \-lR\*(Aq ); \& QueueCommand( \*(Aqgzip *.ps\*(Aq ); \& FinishJob(); \& \& QueueCommands( [ \*(Aqmritotal this.mnc this.xfm\*(Aq, \*(Aqgzip this.mnc\*(Aq ] ); \& \& Synchronize( \*(Aqfinish\*(Aq, 3600, 60, 3600*9 ) \& or die "jobs took longer than nine hours!"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIMNI::Batch\fR provides a method to submit shell commands to the batch queuing system. Commands are sent to the batch system in small sets, termed \fIjobs\fR. The commands in a job are all executed sequentially, though many jobs may be running concurrently. The job is made up of all the commands submitted by \f(CW\*(C`QueueCommand\*(C'\fR or \f(CW\*(C`QueueCommands\*(C'\fR between \f(CW\*(C`StartJob\*(C'\fR and \f(CW\*(C`FinishJob\*(C'\fR. All commands are executed by /bin/sh, or other Bourne-compatible shell. .SH "OPTIONS" .IX Header "OPTIONS" The following options are used to modify the behaviour of the batch system. Once set (using \f(CW\*(C`MNI::Batch::SetOptions\*(C'\fR) the options apply to all subsequent \&\f(CW\*(C`StartJob\*(C'\fR invocations. .IP "verbose" 4 .IX Item "verbose" should we echo queue commands and other info? .IP "loghandle" 4 .IX Item "loghandle" where to echo queue commands and other info .IP "batch_reports" 4 .IX Item "batch_reports" should the underlying batch process run in verbose mode? .IP "execute" 4 .IX Item "execute" should we actually submit jobs? .IP "check_status" 4 .IX Item "check_status" check each submitted command for success? .IP "export_tmpdir" 4 .IX Item "export_tmpdir" name of temporary directory to create when job is running .IP "nuke_tmpdir" 4 .IX Item "nuke_tmpdir" \&\*(L"rm \-rf\*(R" the tmp dir when job finishes? .IP "synchronize" 4 .IX Item "synchronize" set to \*(L"start\*(R", \*(L"finish\*(R", \*(L"both\*(R", to create appropriate syncfiles; or set to undef (default) for no synchronization. .IP "syncdir" 4 .IX Item "syncdir" directory in which to put synchronization files. Must be accessible from all hosts! .IP "close_delay" 4 .IX Item "close_delay" number of seconds to sleep after submitting a job. Defaults to zero. .IP "job_name" 4 .IX Item "job_name" string to identify job, passed as \fB\-J\fR option to \f(CW\*(C`batch\*(C'\fR; the default is empty. This option is more usually passed in the call to \f(CW\*(C`StartJob\*(C'\fR. .IP "queue" 4 .IX Item "queue" which queue to run on .IP "start_after" 4 .IX Item "start_after" specifies that the job will wait for some event before starting \*(-- a certain time, e.g. \*(L"two hours\*(R", or a file creation. Passed as \fB\-a\fR option to \f(CW\*(C`batch\*(C'\fR. .IP "localhost" 4 .IX Item "localhost" force to run on local host (mutually exclusive to host option) .IP "host" 4 .IX Item "host" explicitly specified host(s) to run on. Multiple hosts can be specified using a space\-, comma\-, or semicolon-separated list of hostnames .IP "restartable" 4 .IX Item "restartable" should job be restarted on crash (\fB\-R\fR option)? Defaults to 1 .IP "shell" 4 .IX Item "shell" shell to run under \*(-- must be Bourne-shell compatible!! .IP "mail_conditions" 4 .IX Item "mail_conditions" code for \fB\-m\fR option; default: 'cr' (crash or resource overrun only) .IP "mail_address" 4 .IX Item "mail_address" address to mail to (\fB\-M\fR option) .IP "write_conditions" 4 .IX Item "write_conditions" code for \fB\-w\fR option; default '' (do not write) .IP "write_address" 4 .IX Item "write_address" address to mail to (\fB\-W\fR option) .IP "stdout" 4 .IX Item "stdout" file to which standard output is redirected; default is no redirection. .IP "stderr" 4 .IX Item "stderr" file to which standard error output is redirected; default is no redirection. .IP "merge_stderr" 4 .IX Item "merge_stderr" set to 1 to cause error stream to be merged with stdout; must not be used if stderr is set. .SH "METHODS" .IX Header "METHODS" .IP "MNI::Batch::SetOptions( option => value, ... )" 4 .IX Item "MNI::Batch::SetOptions( option => value, ... )" Set various batch-related options, documented in section \*(L"\s-1OPTIONS\s0\*(R". Dies if any bad options are found. .IP "StartJob( [options] )" 4 .IX Item "StartJob( [options] )" Start a new batch job. Commands for this job are then submitted by calling \&\f(CW\*(C`QueueCommand\*(C'\fR or \f(CW\*(C`QueueCommands\*(C'\fR. Once all commands are queued, you must call \f(CW\*(C`FinishJob\*(C'\fR. .Sp Options described in \*(L"options\*(R" may be overridden \fIfor this job only\fR by giving them here. .Sp If the \fIsynchronize\fR option is set to \*(L"start\*(R" or \*(L"both\*(R", the filename of the \fIstart\fR synchronizing file is returned. Otherwise, \f(CW\*(C`undef\*(C'\fR is returned. .IP "FinishJob( [delay] )" 4 .IX Item "FinishJob( [delay] )" Called after all commands have been queued for the currently-opened job. This function submits the list of commands to the batch queue. .Sp The program pauses for \fIclose_delay\fR seconds after submitting the job. The delay can be overridden by specifying the optional argument. .Sp Returns a two-element list, consisting of filenames that may be created for synchronization purposes. The first file is the \fIfinish\fR file, created when the job ends, if the \fIsynchronize\fR option is set to \*(L"finish\*(R" or to \*(L"both\*(R". The second file name is the \fIfail\fR file, created if the job fails and the \fIcheck_status\fR option is set and \&\fIsynchronize\fR is set to \*(L"finish\*(R" or to \*(L"both\*(R". .Sp For backwards compatibilty, in a scalar context, only the finish file is returned. .IP "\fIGetJobid()\fR" 4 .IX Item "GetJobid()" Returns the \s-1ID\s0 of the currently-opened job, if called after \f(CW\*(C`StartJob\*(C'\fR and before \f(CW\*(C`FinishJob\*(C'\fR. Otherwise, zero is returned. .IP "Synchronize( onwhat, delay )" 4 .IX Item "Synchronize( onwhat, delay )" .PD 0 .IP "Synchronize( onwhat, initial_delay, periodic_delay [,timeout] )" 4 .IX Item "Synchronize( onwhat, initial_delay, periodic_delay [,timeout] )" .PD Wait until either all pending jobs start, or all pending jobs finish (or fail). .Sp The parameter \fIonwhat\fR is either \f(CW\*(C`start\*(C'\fR, or \f(CW\*(C`finish\*(C'\fR. This function checks periodically for the existence of synchronization files. In the first form, \fIdelay\fR specifies, in seconds, how often to check for the synchronization files. If you are waiting for long jobs to finish, you can use the second form of the command, to specify separately the \fIinitial_delay\fR to sleep, after which the files are checked for at the frequency specified by the \fIperiodic_delay\fR. You can also specify a \fItimeout\fR parameter, after which time we give up waiting for the synchronization files. .Sp The return value is a list of array references. Make sure \f(CW\*(C`Synchronize\*(C'\fR is evaluated in array context. .Sp If synchronizing on \fIstart\fR, the return value is a reference to an array of job names that did indeed start. If synchronizing on \fIfinish\fR, then two array refs are returned. The first array holds the job names that finished, the second array contains job names that failed. The value zero is returned if we timed out waiting for the synchronization files to appear. This can happen only if \fItimeout\fR was specified. .Sp The commands to create sync files are automatically inserted into your job by StartJob and FinishJob, depending on the value of the synchronize option. .IP "QueueCommand( command [, options] )" 4 .IX Item "QueueCommand( command [, options] )" This is equivalent to \f(CW\*(C`QueueCommands( [ command ], options )\*(C'\fR. .IP "QueueCommands( commands [,options] )" 4 .IX Item "QueueCommands( commands [,options] )" Queues multiple commands to the same job. .Sp If a job is already open, the given commands are simply added to it. The return value is unspecified. .Sp If no job is currently open, a new job is created, the commands are added, and the job is closed. The return value is a three-element array of filenames, \fI(startfile, finishfile, failfile)\fR; i.e. the concatenation of return values of \f(CW\*(C`StartJob\*(C'\fR and \f(CW\*(C`FinishJob\*(C'\fR. .IP "JobStatus( jobid [,option => value ...] )" 4 .IX Item "JobStatus( jobid [,option => value ...] )" Attempt to get the status of specified job, using the command \f(CW\*(C`baq\*(C'\fR. Use \f(CW\*(C`queue =\*(C'\fR queuename> to check the non-default queue. .Sp If successful, one of the strings described in the \f(CW\*(C`baq\*(C'\fR manual page will be returned. If the status cannot be determined, \f(CW\*(C`undef\*(C'\fR is returned. .Sp Any MNI::Spawn options may be overridden, except \&\fIbatch\fR and \fIstdout\fR. If \fIstderr\fR is not specified, it is set to \f(CW\*(C`UNTOUCHED\*(C'\fR (see MNI::Spawn). .Sp To suppress output from \f(CW\*(C`MNI::Spawn\*(C'\fR and from \f(CW\*(C`baq\*(C'\fR, you need to specify \f(CW\*(C`verbose =\*(C'\fR 0, stderr => /dev/null>. .SH "AUTHOR" .IX Header "AUTHOR" Greg Ward, . With modifications by Chris Cocosco, Steve Robbins, possibly others. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1997\-1999 by Gregory P. Ward, McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. .PP This file is part of the \s-1MNI\s0 Perl Library. It is free software, and may be distributed under the same terms as Perl itself.