diff options
Diffstat (limited to 'man1p/qsub.1p')
| -rw-r--r-- | man1p/qsub.1p | 1024 |
1 files changed, 1024 insertions, 0 deletions
diff --git a/man1p/qsub.1p b/man1p/qsub.1p new file mode 100644 index 000000000..dd50d9e04 --- /dev/null +++ b/man1p/qsub.1p @@ -0,0 +1,1024 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QSUB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qsub +.SH NAME +qsub \- submit a script +.SH SYNOPSIS +.LP +\fBqsub\fP \fB[\fP\fB-a\fP \fIdate_time\fP\fB][\fP\fB-A\fP +\fIaccount_string\fP\fB][\fP\fB-c\fP \fIinterval\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-C\fP \fIdirective_prefix\fP\fB][\fP\fB-e\fP +\fIpath_name\fP\fB][\fP\fB-h\fP\fB][\fP\fB-j\fP \fIjoin_list\fP\fB][\fP\fB-k\fP +\fIkeep_list\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-m\fP \fImail_options\fP\fB][\fP\fB-M\fP +\fImail_list\fP\fB][\fP\fB-N\fP \fIname\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-o\fP \fIpath_name\fP\fB][\fP\fB-p\fP +\fIpriority\fP\fB][\fP\fB-q\fP \fIdestination\fP\fB][\fP\fB-r\fP \fIy\fP\fB|\fP\fIn\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-S\fP \fIpath_name_list\fP\fB][\fP\fB-u\fP +\fIuser_list\fP\fB][\fP\fB-v\fP \fIvariable_list\fP\fB][\fP\fB-V\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-z\fP\fB][\fP\fIscript\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +To submit a script is to create a batch job that executes the script. +A script is submitted by a request to a batch server. The +\fIqsub\fP utility is a user-accessible batch client that submits +a script. +.LP +Upon successful completion, the \fIqsub\fP utility shall have created +a batch job that will execute the submitted script. +.LP +The \fIqsub\fP utility shall submit a script by sending a \fIQueue +Job Request\fP to a batch server. +.LP +The \fIqsub\fP utility shall place the value of the following environment +variables in the \fIVariable_List\fP attribute of +the batch job: \fIHOME ,\fP \fILANG ,\fP \fILOGNAME ,\fP \fIPATH ,\fP +\fIMAIL ,\fP \fISHELL ,\fP and \fITZ .\fP The name of +the environment variable shall be the current name prefixed with the +string PBS_O_. +.TP 7 +\fBNote:\fP +If the current value of the \fIHOME\fP variable in the environment +space of the \fIqsub\fP utility is \fB/aa/bb/cc\fP, then +\fIqsub\fP shall place \fIPBS_O_HOME =\fP \fB/aa/bb/cc\fP in the \fIVariable_List\fP +attribute of the batch job. +.sp +.LP +In addition to the variables described above, the \fIqsub\fP utility +shall add the following variables with the indicated +values to the variable list: +.TP 7 +\fIPBS_O_WORKDIR\fP +The absolute path of the current working directory of the \fIqsub\fP +utility process. +.TP 7 +\fIPBS_O_HOST\fP +The name of the host on which the \fIqsub\fP utility is running. +.sp +.SH OPTIONS +.LP +The \fIqsub\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-a\ \fP \fIdate_time\fP +Define the time at which a batch job becomes eligible for execution. +.LP +The \fIqsub\fP utility shall accept an option-argument that conforms +to the syntax of the \fItime\fP operand of the \fItouch\fP utility. +.br +.sp +.ce 1 +\fBTable: Environment Variable Values (Utilities)\fP +.TS C +center; l l. +\fBVariable Name\fP \fBValue at qsub Time\fP +\fIPBS_O_HOME\fP \fIHOME\fP +\fIPBS_O_HOST\fP \fIClient host name\fP +\fIPBS_O_LANG\fP \fILANG\fP +\fIPBS_O_LOGNAME\fP \fILOGNAME\fP +\fIPBS_O_PATH\fP \fIPATH\fP +\fIPBS_O_MAIL\fP \fIMAIL\fP +\fIPBS_O_SHELL\fP \fISHELL\fP +\fIPBS_O_TZ\fP \fITZ\fP +\fIPBS_O_WORKDIR\fP \fICurrent working directory\fP +.TE +.TP 7 +\fBNote:\fP +.RS +The server that initiates execution of the batch job will add other +variables to the batch job's environment; see \fIBatch Job Execution\fP +\&. +.RE +.sp +.LP +The \fIqsub\fP utility shall set the \fIExecution_Time\fP attribute +of the batch job to the number of seconds since the Epoch +that is equivalent to the local time expressed by the value of the +\fIdate_time\fP option-argument. The Epoch is defined in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.149, +Epoch. +.LP +If the \fB-a\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIExecution_Time\fP attribute +of the batch job to a time (number of seconds since the Epoch) that +is earlier than the time at which the utility exits. +.TP 7 +\fB-A\ \fP \fIaccount_string\fP +.sp +Define the account to which the resource consumption of the batch +job should be charged. +.LP +The syntax of the \fIaccount_string\fP option-argument is unspecified. +.LP +The \fIqsub\fP utility shall set the \fIAccount_Name\fP attribute +of the batch job to the value of the \fIaccount_string\fP +option-argument. +.LP +If the \fB-A\fP option is not presented to the \fIqsub\fP utility, +the utility shall omit the \fIAccount_Name\fP attribute +from the attributes of the batch job. +.TP 7 +\fB-c\ \fP \fIinterval\fP +Define whether the batch job should be checkpointed, and if so, how +often. +.LP +The \fIqsub\fP utility shall accept a value for the interval option-argument +that is one of the following: +.TP 7 +\fBn\fP +.RS +No checkpointing shall be performed on the batch job (NO_CHECKPOINT). +.RE +.TP 7 +\fBs\fP +.RS +Checkpointing shall be performed only when the batch server is shut +down (CHECKPOINT_AT_SHUTDOWN). +.RE +.TP 7 +\fBc\fP +.RS +Automatic periodic checkpointing shall be performed at the \fIMinimum_Cpu_Interval\fP +attribute of the batch queue, in units +of CPU minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL). +.RE +.TP 7 +\fBc\fP=\fIminutes\fP +.RS +Automatic periodic checkpointing shall be performed every \fIminutes\fP +of CPU time, or every \fIMinimum_Cpu_Interval\fP +minutes, whichever is greater. The \fIminutes\fP argument shall conform +to the syntax for unsigned integers and shall be greater +than zero. +.RE +.sp +.LP +The \fIqsub\fP utility shall set the \fICheckpoint\fP attribute of +the batch job to the value of the \fIinterval\fP +option-argument. +.LP +If the \fB-c\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fICheckpoint\fP attribute of +the batch job to the single character \fB'u'\fP (CHECKPOINT_UNSPECIFIED). +.TP 7 +\fB-C\ \fP \fIdirective_prefix\fP +.sp +Define the prefix that declares a directive to the \fIqsub\fP utility +within the script. +.LP +The \fIdirective_prefix\fP is not a batch job attribute; it affects +the behavior of the \fIqsub\fP utility. +.LP +If the \fB-C\fP option is presented to the \fIqsub\fP utility, and +the value of the \fIdirective_prefix\fP option-argument is +the null string, the utility shall not scan the script file for directives. +If the \fB-C\fP option is not presented to the +\fIqsub\fP utility, then the value of the \fIPBS_DPREFIX\fP environment +variable is used. If the environment variable is not +defined, then #PBS encoded in the portable character set is the default. +.TP 7 +\fB-e\ \fP \fIpath_name\fP +Define the path to be used for the standard error stream of the batch +job. +.LP +The \fIqsub\fP utility shall accept a \fIpath_name\fP option-argument +which can be preceded by a host name element of the form +\fIhostname\fP:. +.LP +If the \fIpath_name\fP option-argument constitutes an absolute pathname, +the \fIqsub\fP utility shall set the +\fIError_Path\fP attribute of the batch job to the value of the \fIpath_name\fP +option-argument. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and no host name element is specified, the \fIqsub\fP +utility shall set the \fIError_Path\fP attribute of the batch job +to the value of the absolute pathname derived by expanding the +\fIpath_name\fP option-argument relative to the current directory +of the process executing \fIqsub\fP. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and a host name element is specified, the \fIqsub\fP +utility shall set the \fIError_Path\fP attribute of the batch job +to the value of the \fIpath_name\fP option-argument without +expansion. The host name element shall be included. +.LP +If the \fIpath_name\fP option-argument does not include a host name +element, the \fIqsub\fP utility shall prefix the pathname +with \fIhostname\fP:, where \fIhostname\fP is the name of the host +upon which the \fIqsub\fP utility is being executed. +.LP +If the \fB-e\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIError_Path\fP attribute of +the batch job to the host name and path of the current directory of +the submitting process and the default filename. +.LP +The default filename for standard error has the following format: +.sp +.RS +.nf + +\fIjob_name\fP\fB.e\fP\fIsequence_number\fP +.fi +.RE +.TP 7 +\fB-h\fP +Specify that a USER hold is applied to the batch job. +.LP +The \fIqsub\fP utility shall set the value of the \fIHold_Types\fP +attribute of the batch job to the value USER. +.LP +If the \fB-h\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIHold_Types\fP attribute of +the batch job to the value NO_HOLD. +.TP 7 +\fB-j\ \fP \fIjoin_list\fP +Define which streams of the batch job are to be merged. The \fIqsub\fP +\fB-j\fP option shall accept a value for the +\fIjoin_list\fP option-argument that is a string of alphanumeric characters +in the portable character set (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set). +.LP +The \fIqsub\fP utility shall accept a \fIjoin_list\fP option-argument +that consists of one or more of the characters +\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP . +.LP +All of the other batch job output streams specified will be merged +into the output stream represented by the character listed +first in the \fIjoin_list\fP option-argument. +.LP +For each unique character in the \fIjoin_list\fP option-argument, +the \fIqsub\fP utility shall add a value to the +\fIJoin_Path\fP attribute of the batch job as follows, each representing +a different batch job stream to join: +.TP 7 +\fBe\fP +.RS +The standard error of the batch job (JOIN_STD_ERROR). +.RE +.TP 7 +\fBo\fP +.RS +The standard output of the batch job (JOIN_STD_OUTPUT). +.RE +.sp +.LP +An existing \fIJoin_Path\fP attribute can be cleared by the following +join type: +.TP 7 +\fBn\fP +.RS +NO_JOIN +.RE +.sp +.LP +If \fB'n'\fP is specified, then no files are joined. The \fIqsub\fP +utility shall consider it an error if any join type +other than \fB'n'\fP is combined with join type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the +\fIjoin_list\fP option-argument. The \fIqsub\fP utility shall permit +the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.LP +An implementation may define other join types. The conformance document +for an implementation shall describe any additional +batch job streams, how they are specified, their internal behavior, +and how they affect the behavior of the utility. +.LP +If the \fB-j\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the value of the \fIJoin_Path\fP +attribute of the batch job to NO_JOIN. +.TP 7 +\fB-k\ \fP \fIkeep_list\fP +Define which output of the batch job to retain on the execution host. +.LP +The \fIqsub\fP \fB-k\fP option shall accept a value for the \fIkeep_list\fP +option-argument that is a string of alphanumeric +characters in the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). +.LP +The \fIqsub\fP utility shall accept a \fIkeep_list\fP option-argument +that consists of one or more of the characters +\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP . +.LP +For each unique character in the \fIkeep_list\fP option-argument, +the \fIqsub\fP utility shall add a value to the +\fIKeep_Files\fP attribute of the batch job as follows, each representing +a different batch job stream to keep: +.TP 7 +\fBe\fP +.RS +The standard error of the batch job (KEEP_STD_ERROR). +.RE +.TP 7 +\fBo\fP +.RS +The standard output of the batch job (KEEP_STD_OUTPUT). +.RE +.sp +.LP +If both \fB'e'\fP and \fB'o'\fP are specified, then both files are +retained. An existing \fIKeep_Files\fP attribute can +be cleared by the following keep type: +.TP 7 +\fBn\fP +.RS +NO_KEEP +.RE +.sp +.LP +If \fB'n'\fP is specified, then no files are retained. The \fIqsub\fP +utility shall consider it an error if any keep type +other than \fB'n'\fP is combined with keep type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the +\fIkeep_list\fP option-argument. The \fIqsub\fP utility shall permit +the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.LP +An implementation may define other keep types. The conformance document +for an implementation shall describe any additional keep +types, how they are specified, their internal behavior, and how they +affect the behavior of the utility. If the \fB-k\fP option is +not presented to the \fIqsub\fP utility, the utility shall set the +\fIKeep_Files\fP attribute of the batch job to the value +NO_KEEP. +.TP 7 +\fB-m\ \fP \fImail_options\fP +.sp +Define the points in the execution of the batch job at which the batch +server that manages the batch job shall send mail about a +change in the state of the batch job. +.LP +The \fIqsub\fP \fB-m\fP option shall accept a value for the \fImail_options\fP +option-argument that is a string of +alphanumeric characters in the portable character set (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set). +.LP +The \fIqsub\fP utility shall accept a value for the \fImail_options\fP +option-argument that is a string of one or more of the +characters \fB'e'\fP , \fB'b'\fP , and \fB'a'\fP , or the single character +\fB'n'\fP . +.LP +For each unique character in the \fImail_options\fP option-argument, +the \fIqsub\fP utility shall add a value to the +\fIMail_Users\fP attribute of the batch job as follows, each representing +a different time during the life of a batch job at which +to send mail: +.TP 7 +\fBe\fP +.RS +MAIL_AT_EXIT +.RE +.TP 7 +\fBb\fP +.RS +MAIL_AT_BEGINNING +.RE +.TP 7 +\fBa\fP +.RS +MAIL_AT_ABORT +.RE +.sp +.LP +If any of these characters are duplicated in the \fImail_options\fP +option-argument, the duplicates shall be ignored. +.LP +An existing \fIMail_Points\fP attribute can be cleared by the following +mail type: +.TP 7 +\fBn\fP +.RS +NO_MAIL +.RE +.sp +.LP +If \fB'n'\fP is specified, then mail is not sent. The \fIqsub\fP utility +shall consider it an error if any mail type other +than \fB'n'\fP is combined with mail type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'b'\fP , \fB'a'\fP , or +\fB'n'\fP within the \fImail_options\fP option-argument. +.LP +The \fIqsub\fP utility shall permit the repetition of characters, +but shall not assign additional meaning to the repeated +characters. An implementation may define other mail types. The conformance +document for an implementation shall describe any +additional mail types, how they are specified, their internal behavior, +and how they affect the behavior of the utility. +.LP +If the \fB-m\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIMail_Points\fP attribute to +the value MAIL_AT_ABORT. +.TP 7 +\fB-M\ \fP \fImail_list\fP +Define the list of users to which a batch server that executes the +batch job shall send mail, if the server sends mail about +the batch job. +.LP +The syntax of the \fImail_list\fP option-argument is unspecified. +.LP +If the implementation of the \fIqsub\fP utility uses a name service +to locate users, the utility should accept the syntax used +by the name service. +.LP +If the implementation of the \fIqsub\fP utility does not use a name +service to locate users, the implementation should accept +the following syntax for user names: +.sp +.RS +.nf + +\fImail_address\fP\fB[\fP\fB,,\fP\fImail_address\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +The interpretation of \fImail_address\fP is implementation-defined. +.LP +The \fIqsub\fP utility shall set the \fIMail_Users\fP attribute of +the batch job to the value of the \fImail_list\fP +option-argument. +.LP +If the \fB-M\fP option is not presented to the \fIqsub\fP utility, +the utility shall place only the user name and host name +for the current process in the \fIMail_Users\fP attribute of the batch +job. +.TP 7 +\fB-N\ \fP \fIname\fP +Define the name of the batch job. +.LP +The \fIqsub\fP \fB-N\fP option shall accept a value for the \fIname\fP +option-argument that is a string of up to 15 +alphanumeric characters in the portable character set (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set) where the first character is alphabetic. +.LP +The \fIqsub\fP utility shall set the value of the \fIJob_Name\fP attribute +of the batch job to the value of the \fIname\fP +option-argument. +.LP +If the \fB-N\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIJob_Name\fP attribute of the +batch job to the name of the \fIscript\fP argument from which the +directory specification if any, has been removed. +.LP +If the \fB-N\fP option is not presented to the \fIqsub\fP utility, +and the script is read from standard input, the utility +shall set the \fIJob_Name\fP attribute of the batch job to the value +STDIN. +.TP 7 +\fB-o\ \fP \fIpath_name\fP +Define the path for the standard output of the batch job. +.LP +The \fIqsub\fP utility shall accept a \fIpath_name\fP option-argument +that conforms to the syntax of the \fIpath_name\fP +element defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +which can be preceded by a host name element of +the form \fIhostname\fP:. +.LP +If the \fIpath_name\fP option-argument constitutes an absolute pathname, +the \fIqsub\fP utility shall set the +\fIOutput_Path\fP attribute of the batch job to the value of the \fIpath_name\fP +option-argument without expansion. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and no host name element is specified, the \fIqsub\fP +utility shall set the \fIOutput_Path\fP attribute of the batch job +to the pathname derived by expanding the value of the +\fIpath_name\fP option-argument relative to the current directory +of the process executing the \fIqsub\fP. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and a host name element is specified, the \fIqsub\fP +utility shall set the \fIOutput_Path\fP attribute of the batch job +to the value of the \fIpath_name\fP option-argument without +expansion. +.LP +If the \fIpath_name\fP option-argument does not specify a host name +element, the \fIqsub\fP utility shall prefix the pathname +with \fIhostname\fP:, where \fIhostname\fP is the name of the host +upon which the \fIqsub\fP utility is executing. +.LP +If the \fB-o\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIOutput_Path\fP attribute of +the batch job to the host name and path of the current directory of +the submitting process and the default filename. +.LP +The default filename for standard output has the following format: +.sp +.RS +.nf + +\fIjob_name\fP\fB.o\fP\fIsequence_number\fP +.fi +.RE +.TP 7 +\fB-p\ \fP \fIpriority\fP +Define the priority the batch job should have relative to other batch +jobs owned by the batch server. +.LP +The \fIqsub\fP utility shall set the \fIPriority\fP attribute of the +batch job to the value of the \fIpriority\fP +option-argument. +.LP +If the \fB-p\fP option is not presented to the \fIqsub\fP utility, +the value of the \fIPriority\fP attribute is +implementation-defined. +.LP +The \fIqsub\fP utility shall accept a value for the \fIpriority\fP +option-argument that conforms to the syntax for signed +decimal integers, and which is not less than -1024 and not greater +than 1023. +.TP 7 +\fB-q\ \fP \fIdestination\fP +.sp +Define the destination of the batch job. +.LP +The destination is not a batch job attribute; it determines the batch +server, and possibly the batch queue, to which the +\fIqsub\fP utility batch queues the batch job. +.LP +The \fIqsub\fP utility shall submit the script to the batch server +named by the \fIdestination\fP option-argument or the +server that owns the batch queue named in the \fIdestination\fP option-argument. +.LP +The \fIqsub\fP utility shall accept an option-argument for the \fB-q\fP +option that conforms to the syntax for a destination +(see \fIDestination\fP ). +.LP +If the \fB-q\fP option is not presented to the \fIqsub\fP utility, +the \fIqsub\fP utility shall submit the batch job to the +default destination. The mechanism for determining the default destination +is implementation-defined. +.TP 7 +\fB-r\ \fP \fIy\fP|\fIn\fP +Define whether the batch job is rerunnable. +.LP +If the value of the option-argument is \fIy\fP, the \fIqsub\fP utility +shall set the \fIRerunable\fP attribute of the batch +job to TRUE. +.LP +If the value of the option-argument is \fIn\fP, the \fIqsub\fP utility +shall set the \fIRerunable\fP attribute of the batch +job to FALSE. +.LP +If the \fB-r\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIRerunable\fP attribute of the +batch job to TRUE. +.TP 7 +\fB-S\ \fP \fIpath_name_list\fP +.sp +Define the pathname to the shell under which the batch job is to execute. +.LP +The \fIqsub\fP utility shall accept a \fIpath_name_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fIpathname\fP\fB[\fP\fB@\fP\fIhost\fP\fB][\fP\fB,,\fP\fIpathname\fP\fB[\fP\fB@\fP\fIhost\fP\fB]\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +The \fIqsub\fP utility shall allow only one pathname for a given host +name. The \fIqsub\fP utility shall allow only one +pathname that is missing a corresponding host name. +.LP +The \fIqsub\fP utility shall add a value to the \fIShell_Path_List\fP +attribute of the batch job for each entry in the +\fIpath_name_list\fP option-argument. +.LP +If the \fB-S\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIShell_Path_List\fP attribute +of the batch job to the null string. +.LP +The conformance document for an implementation shall describe the +mechanism used to set the default shell and determine the +current value of the default shell. An implementation shall provide +a means for the installation to set the default shell to the +login shell of the user under which the batch job is to execute. See +\fIMultiple +Keyword-Value Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP +(and \fIvalue\fP@ \fIkeyword\fP) pairs and other +general rules for list-oriented batch job attributes. +.TP 7 +\fB-u\ \fP \fIuser_list\fP +Define the user name under which the batch job is to execute. +.LP +The \fIqsub\fP utility shall accept a \fIuser_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB][\fP\fB,,\fP\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB]\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +The \fIqsub\fP utility shall accept only one user name that is missing +a corresponding host name. The \fIqsub\fP utility shall +accept only one user name per named host. +.LP +The \fIqsub\fP utility shall add a value to the \fIUser_List\fP attribute +of the batch job for each entry in the +\fIuser_list\fP option-argument. +.LP +If the \fB-u\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIUser_List\fP attribute of the +batch job to the user name from which the utility is executing. See +\fIMultiple +Keyword-Value Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP +(and \fIvalue\fP@ \fIkeyword\fP) pairs and other +general rules for list-oriented batch job attributes. +.TP 7 +\fB-v\ \fP \fIvariable_list\fP +.sp +Add to the list of variables that are exported to the session leader +of the batch job. +.LP +A \fIvariable_list\fP is a set of strings of either the form < \fIvariable\fP> +or < \fIvariable\fP= +\fIvalue\fP>, delimited by commas. +.LP +If the \fB-v\fP option is presented to the \fIqsub\fP utility, the +utility shall also add, to the environment +\fIVariable_List\fP attribute of the batch job, every variable named +in the environment \fIvariable_list\fP option-argument and, +optionally, values of specified variables. +.LP +If a value is not provided on the command line, the \fIqsub\fP utility +shall set the value of each variable in the environment +\fIVariable_List\fP attribute of the batch job to the value of the +corresponding environment variable for the process in which the +utility is executing; see Environment Variable Values (Utilities) +\&. +.LP +A conforming application shall not repeat a variable in the environment +\fIvariable_list\fP option-argument. +.LP +The \fIqsub\fP utility shall not repeat a variable in the environment +\fIVariable_List\fP attribute of the batch job. See \fIMultiple Keyword-Value +Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP +(and \fIvalue\fP@ \fIkeyword\fP) pairs and other general rules for +list-oriented batch job attributes. +.TP 7 +\fB-V\fP +Specify that all of the environment variables of the process are exported +to the context of the batch job. +.LP +The \fIqsub\fP utility shall place every environment variable in the +process in which the utility is executing in the list and +shall set the value of each variable in the attribute to the value +of that variable in the process. +.TP 7 +\fB-z\fP +Specify that the utility does not write the batch \fIjob_identifier\fP +of the created batch job to standard output. +.LP +If the \fB-z\fP option is presented to the \fIqsub\fP utility, the +utility shall not write the batch \fIjob_identifier\fP of +the created batch job to standard output. +.LP +If the \fB-z\fP option is not presented to the \fIqsub\fP utility, +the utility shall write the identifier of the created batch +job to standard output. +.sp +.SH OPERANDS +.LP +The \fIqsub\fP utility shall accept a \fIscript\fP operand that indicates +the path to the script of the batch job. +.LP +If the \fIscript\fP operand is not presented to the \fIqsub\fP utility, +or if the operand is the single-character string +\fB'-'\fP , the utility shall read the script from standard input. +.LP +If the script represents a partial path, the \fIqsub\fP utility shall +expand the path relative to the current directory of the +process executing the utility. +.SH STDIN +.LP +The \fIqsub\fP utility reads the script of the batch job from standard +input if the script operand is omitted or is the single +character \fB'-'\fP . +.SH INPUT FILES +.LP +In addition to binding the file indicated by the \fIscript\fP operand +to the batch job, the \fIqsub\fP utility reads the +script file and acts on directives in the script. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqsub\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.TP 7 +\fIPBS_DPREFIX\fP +.sp +Determine the default prefix for directives within the script. +.TP 7 +\fISHELL\fP +Determine the pathname of the preferred command language interpreter +of the user. +.TP 7 +\fITZ\fP +Determine the timezone used to interpret the \fIdate-time\fP option-argument. +If \fITZ\fP is unset or null, an unspecified +default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Once created, a batch job exists until it exits, aborts, or is deleted. +.LP +After a batch job is created by the \fIqsub\fP utility, batch servers +might route, execute, modify, or delete the batch +job. +.SH STDOUT +.LP +The \fIqsub\fP utility writes the batch \fIjob_identifier\fP assigned +to the batch job to standard output, unless the +\fB-z\fP option is specified. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.SS Script Preservation +.LP +The \fIqsub\fP utility shall make the script available to the server +executing the batch job in such a way that the server +executes the script as it exists at the time of submission. +.LP +The \fIqsub\fP utility can send a copy of the script to the server +with the \fIQueue Job Request\fP or store a temporary copy +of the script in a location specified to the server. +.SS Option Specification +.LP +A script can contain directives to the \fIqsub\fP utility. +.LP +The \fIqsub\fP utility shall scan the lines of the script for directives, +skipping blank lines, until the first line that +begins with a string other than the directive string; if directives +occur on subsequent lines, the utility shall ignore those +directives. +.LP +Lines are separated by a <newline>. If the first line of the script +begins with \fB"#!"\fP or a colon ( \fB':'\fP ), +then it is skipped. The \fIqsub\fP utility shall process a line in +the script as a directive if and only if the string of +characters from the first non-white-space character on the line until +the first <space> or <tab> on the line match the +directive prefix. If a line in the script contains a directive and +the final characters of the line are backslash ( \fB'\\'\fP ) +and <newline>, then the next line shall be interpreted as a continuation +of that directive. +.LP +The \fIqsub\fP utility shall process the options and option-arguments +contained on the directive prefix line using the same +syntax as if the options were input on the \fIqsub\fP utility. +.LP +The \fIqsub\fP utility shall continue to process a directive prefix +line until after a <newline> is encountered. An +implementation may ignore lines which, according to the syntax of +the shell that will interpret the script, are comments. An +implementation shall describe in the conformance document the format +of any shell comments that it will recognize. +.LP +If an option is present in both a directive and the arguments to the +\fIqsub\fP utility, the utility shall ignore the option +and the corresponding option-argument, if any, in the directive. +.LP +If an option that is present in the directive is not present in the +arguments to the \fIqsub\fP utility, the utility shall +process the option and the option-argument, if any. +.LP +In order of preference, the \fIqsub\fP utility shall select the directive +prefix from one of the following sources: +.IP " *" 3 +If the \fB-C\fP option is presented to the utility, the value of the +\fIdirective_prefix\fP option-argument +.LP +.IP " *" 3 +If the environment variable \fIPBS_DPREFIX\fP is defined, the value +of that variable +.LP +.IP " *" 3 +The four-character string \fB"#PBS"\fP encoded in the portable character +set +.LP +.LP +If the \fB-C\fP option is present in the script file it shall be ignored. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqsub\fP utility allows users to create a batch job that will +process the script specified as the operand of the +utility. +.LP +The options of the \fIqsub\fP utility allow users to control many +aspects of the queuing and execution of a batch job. +.LP +The \fB-a\fP option allows users to designate the time after which +the batch job will become eligible to run. By specifying an +execution time, users can take advantage of resources at off-peak +hours, synchronize jobs with chronologically predictable events, +and perhaps take advantage of off-peak pricing of computing time. +For these reasons and others, a timing option is existing +practice on the part of almost every batch system, including NQS. +.LP +The \fB-A\fP option allows users to specify the account that will +be charged for the batch job. Support for account is not +mandatory for conforming batch servers. +.LP +The \fB-C\fP option allows users to prescribe the prefix for directives +within the script file. The default prefix +\fB"#PBS"\fP may be inappropriate if the script will be interpreted +with an alternate shell, as specified by the \fB-S\fP +option. +.LP +The \fB-c\fP option allows users to establish the checkpointing interval +for their jobs. A checkpointing system, which is not +defined by this volume of IEEE\ Std\ 1003.1-2001, allows recovery +of a batch job at the most recent checkpoint in the event +of a crash. Checkpointing is typically used for jobs that consume +expensive computing time or must meet a critical schedule. Users +should be allowed to make the tradeoff between the overhead of checkpointing +and the risk to the timely completion of the batch +job; therefore, this volume of IEEE\ Std\ 1003.1-2001 provides the +checkpointing interval option. Support for checkpointing +is optional for batch servers. +.LP +The \fB-e\fP option allows users to redirect the standard error streams +of their jobs to a non-default path. For example, if +the submitted script generally produces a great deal of useless error +output, a user might redirect the standard error output to +the null device. Or, if the file system holding the default location +(the home directory of the user) has too little free space, +the user might redirect the standard error stream to a file in another +file system. +.LP +The \fB-h\fP option allows users to create a batch job that is held +until explicitly released. The ability to create a held job +is useful when some external event must complete before the batch +job can execute. For example, the user might submit a held job +and release it when the system load has dropped. +.LP +The \fB-j\fP option allows users to merge the standard error of a +batch job into its standard output stream, which has the +advantage of showing the sequential relationship between output and +error messages. +.LP +The \fB-m\fP option allows users to designate those points in the +execution of a batch job at which mail will be sent to the +submitting user, or to the account(s) indicated by the \fB-M\fP option. +By requesting mail notification at points of interest in +the life of a job, the submitting user, or other designated users, +can track the progress of a batch job. +.LP +The \fB-N\fP option allows users to associate a name with the batch +job. The job name in no way affects the processing of the +batch job, but rather serves as a mnemonic handle for users. For example, +the batch job name can help the user distinguish between +multiple jobs listed by the \fIqstat\fP utility. +.LP +The \fB-o\fP option allows users to redirect the standard output stream. +A user might, for example, wish to redirect to the +null device the standard output stream of a job that produces copious +yet superfluous output. +.LP +The \fB-P\fP option allows users to designate the relative priority +of a batch job for selection from a queue. +.LP +The \fB-q\fP option allows users to specify an initial queue for the +batch job. If the user specifies a routing queue, the +batch server routes the batch job to another queue for execution or +further routing. If the user specifies a non-routing queue, the +batch server of the queue eventually executes the batch job. +.LP +The \fB-r\fP option allows users to control whether the submitted +job will be rerun if the controlling batch node fails during +execution of the batch job. The \fB-r\fP option likewise allows users +to indicate whether or not the batch job is eligible to be +rerun by the \fIqrerun\fP utility. Some jobs cannot be correctly rerun +because of changes +they make in the state of databases or other aspects of their environment. +This volume of IEEE\ Std\ 1003.1-2001 specifies +that the default, if the \fB-r\fP option is not presented to the utility, +will be that the batch job cannot be rerun, since the +result of rerunning a non-rerunnable job might be catastrophic. +.LP +The \fB-S\fP option allows users to specify the program (usually a +shell) that will be invoked to process the script of the +batch job. This option has been modified to allow a list of shell +names and locations associated with different hosts. +.LP +The \fB-u\fP option is useful when the submitting user is authorized +to use more than one account on a given host, in which +case the \fB-u\fP option allows the user to select from among those +accounts. The option-argument is a list of user-host pairs, so +that the submitting user can provide different user identifiers for +different nodes in the event the batch job is routed. The +\fB-u\fP option provides a lot of flexibility to accommodate sites +with complex account structures. Users that have the same user +identifier on all the hosts they are authorized to use will not need +to use the \fB-u\fP option. +.LP +The \fB-V\fP option allows users to export all their current environment +variables, as of the time the batch job is submitted, +to the context of the processes of the batch job. +.LP +The \fB-v\fP option allows users to export specific environment variables +from their current process to the processes of the +batch job. +.LP +The \fB-z\fP option allows users to suppress the writing of the batch +job identifier to standard output. The \fB-z\fP option +is an existing NQS practice that has been standardized. +.LP +Historically, the \fIqsub\fP utility has served the batch job-submission +function in the NQS system, the existing practice on +which it is based. Some changes and additions have been made to the +\fIqsub\fP utility in this volume of +IEEE\ Std\ 1003.1-2001, \fIvis-a-vis\fP NQS, as a result of the growing +pool of experience with distributed batch +systems. +.LP +The set of features of the \fIqsub\fP utility as defined in this volume +of IEEE\ Std\ 1003.1-2001 appears to +incorporate all the common existing practice on potentially conforming +platforms. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqrerun\fP , \fIqstat\fP , \fItouch\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |