Página Personal de Roberto Tejero

Selecciona español Pick english

Inicio

Presentación
   Detalles
   Investigacion
   Proyectos
   Publicaciones

Modelización
   Mecánica Molec.
   Dinámica Molec.
   Homología
   Análisis estruc.

Granjas PC
Hardware
Software

DQS 3 Reference Manual

Distributed Queueing System - 3.1.3

Reference Manual

March 31, 1996

Introduction

This manual is based on the draft POSIX Specification Part 2: Shell and Utilities -- Amendment: Batch Environment. DQS 3.1.3 possesses many extensions and refinements to that basic specification.

The daemons

The backbone of DQS is the operation of the qmaster and the dqs_execd daemons. Each host which will execute batch jobs will have a dqs_execd running as a background daemon. The qmaster runs as a background daemon on each host functioning as a DQS cell manager. The dqs_execd daemons communicate only with the qmaster and the DSH utility, which is invoked by a master process during parallel job startup. The qmaster handles all requests from DQS utilities and communicates with the dqs_execd daemons in its own cell and with other qmaster daemons.

The utilities

qalter - Alter a Batch Job
qconf - Queue configuration tasks
qdel - Delete on or more jobs from the system
qhold - Place a hold on one or more jobs to defer scheduling
qidle - X-Windows console monitor
qmod - Modify the state of a queue
qmove - Move jobs from one cell to another
qrls- Release hold(a) on one or more jobs
qstat - Display status of selected queues and jobs
qsub- Submit a job to the queuing system

qalter - Alter a Batch Job

qalter [-a date_time] [-A account_string] [-cell cell_name] [-clean ] [-cwd] [-C delimiter_pair] [-e path_name] [-hard] [-h hold_list] [-help ] [-j join_list] [-jid job_identifier] [-k keep_list] [-l resource_list] [-m mail_options] [-master destination_identifier...] [-M mail_list] [-N name] [-n notify ] [-o path_name] [-par paradigm] [-p priority] [-passwd] [-passwd_file filename] [-q destination_identifier_list] [-r y|n] [-rc] [-reauth seconds] [-soft] [-S path_name_list] [-u user_list] [-v variable_list] [-verify] [-V] [-z] [script file]

qalter changes the attributes of a job by sending a request to the qmaster.

The qalter utility alters the attributes of those jobs, and only those jobs, for which a job_identifier is presented to the utility. The qalter utility alters the attributes of jobs in the order in which the job-identifiers are presented to the utility. If the qalter utility fails to process a job_identifier successfully, the utility will proceed to process the remaining job_identifiers, if any.

For each job_identifier for which the qalter utility succeeds, each attribute of the identified job will be altered as indicated by all of the options presented to the utility.

For each identified job for which the qalter utility fails the utility will not alter any attribute of the job.

For each job that the qalter utility processes, the utility will not modify any attribute other than those required by the options and option-arguments presented to the utility.

The qalter utility alters jobs by sending a Modify Job Request to the qmaster. At the time the qalter utility exits, it will have modified the job corresponding to each successfully processed job_identifier.

Jobs in the RUNNING state cannot be modified by qalter except for the "-rc" (return consumable resource) option.

Options

-a date_time
Redefines the time at which the job becomes eligible for execution.
The date_time option-argument is of the form:
[[CC]YY]MMDDhhmm[.ss]
where :

CC
Specifies the first two digits of the year
YY
Specifies the last two digits of the year
MM
Specifies the month of the year (01 to 12)
DD
Specifies the day of the month (01 to 31)
hh
Specifies the hour of the day (00 to 23 )
mm
Specifies the minute of the hour (00 to 59 )
ss
Specifies the number of seconds in the hour (00 to 59 )
(note the decimal point must be present to flag the ss )
The qalter utility sets the Execution_Time attribute of the job to the number of seconds since Epoch that is equivalent to the local times expressed by the value of the date_time option-argument. Specifying a date_time option-argument that represents a time (number of seconds since Epoch) earlier than the time at which the utility exists will have the same effect on job execution as if the -a option had not been presented to the utility.
-A account_string
Redefines the account to which the resource consumption of the job should be charged. The account string contain list containing account_names as follows:
Account_Name[@cell}[,Account_Name[@cell],... ]

The Account_Name may be any arbitrary ASCII alphanumeric string of bytes but may contain no blanks or separator characters. The under-bar "_" is considered a non-separator.
-cell cell_name
The cell to which the qalter request is to be sent.
-clean
Causes all elements of the job to be reset to the initial default status prior to applying any modifications (if any) appearing in this specific qalter command.
-cwd
Redefines the current working directory to be used when the job begins execution
-C directive_prefix
The directive prefix consists of two ASCII characters which when appearing in the first two bytes of a script line indicate that what follows is a DQS command.
-e path_name
Redefines the path to be used for the standard error stream of the job.
If the path_name option-argument constitutes an absolute path name, the qalter utility will set the Error_Path attribute of the job to the value of the path_name option-argument including the hostname, if present.
If the path_name option-argument constitutes a relative path name and no hostname is specified, the qalter utility will set the Error_Path attribute of the job to the value of the absolute path name derived by expanding the path_name option-argument relative to the current directory of the process that executes the qalter utility.
If the path_name option-argument constitutes a relative path name and a hostname is specified, the qalter utility will set the Error_Path attribute of the job to the value of the option-argument without expansion.
If the path_name option-argument does not include a hostname, the qalter utility will prefix the path name in the Error_Path attribute with "hostname:", where hostname is the name of the host upon which the qalter utility is being executed.
The default file name for standard error output has the following form:
"job_name.e.sequence_number"

If the -e option possess no option-argument, the utility will clear the Error_Path attribute of the job so that the default standard error output will be used when the job is executed.
-h hold_list
Redefines the types of holds, if any, on the job. The qalter -h option will accept a value for the hold_list option-argument that is a string of alphanumeric characters in the portable character set.
The qalter utility will accept a value for the hold_list option-argument that is a string one or more characters 'u' 's', or 'o' or the single character 'n'.
For each unique character in the hold_list the qalter will add a value to the Hold_Type attributes of the job as follows, each representing a different hold type:

u USER
s SYSTEM
o OPERATOR
n NO_HOLD

The qalter utility will consider it an error if any hold type other than 'n' is combined with hold type 'n'.
-hard
Signifies that all resource requirements following in the qalter command will be hard requirements and must be satisfied in full before a job can be scheduled.
-help
Prints a listing of all options for qalter.
-j join_list
Redefines which streams of the job are to be merged. The qalter -j option will accept a value for the join-list option-argument that is a string of alphanumeric characters in the portable character set.
The qalter utility will accept a join-list option-argument that consists of one or more characters 'e' and 'o' or the single character 'n'.
All of the other job output streams specified will be merged into the output stream represented by the character listed first in the join-list option-argument.
For each unique character in the join-list option-argument, the qalter will add a value to the Join_Path attribute of the job as follows, each representing a different of stream to join:

e The standard error of the batch job JOIN_STD_ERROR
o The standard output of the batch job JOIN_STD_OUTPUT
n Clear an existing Join_Path attribute NO_JOIN

If 'n' is specified, then no files are joined. The qalter utility will consider it an error if any type other than 'n' is combined with join type 'n'.
The only characters permitted in this implementation are 'y' or 'n'. and the meaning of the "-j" options is different from the standard:
The "-j" option specifies whether the standard error stream of the job is merged into the standard output steam.
If the value of the option-argument is 'y' the Join_Path attribute of the job is set to TRUE.
If the value for the option-argument id 'n' the Join_Path attribute of the job is set to FALSE.
if both the "-j y" and the -e options are specified, the batch server will set but ignore the Error_Path attribute.
if the "-j" option is not presented to the -qalter utility, the utility will set the value of the Join_Path attribute to FALSE.
-jid
Defines the job identifier on which the qalter command will act.
-l resource_list
Redefines the resources that are allowed or required by the job.
The resource_list option-argument will conform to the following:
resource[relational-op resource-field][logical-op resource[relational-op...]]

The resource_list should not contain ANY imbedded blanks, as the space character is used to delimit each of the option fields in a qalter command.
There are two character strings which act as "reserved words" as a resource in the resource_list:

qty
The quantity of a requested resource, default=1
-exec.eq.
Identifies special parallel resource definitions. See Parallel Job Submission in the User Guide.

Each relational-op may be selected from the FORTRAN or C list of operators which consists of .eq. .ne. .gt. .lt. .ge. .le. or '==' '!=' '>' '<' '>=' '<='
A special relationship is flagged when a single equal-sign is used '='. This indicates that a comparison of character strings will be used in the relational test rather than a numeric comparison.
Each logical-op may be selected from the FORTRAN or "C" list of operators which consists of .and. .or. .not. or '&&' '||' '!'
The logical-op may be preceded or followed by an opening or closing parenthesis to ease readability. i.e. "(mem.gt.32).and.(disk.gt.100)"
-m mail_options
Redefines the points in the execution of the job at which the server is to send mail about a change in the state of the job.
The qalter utility will accept a value for the mail-options option-argument that is a string one or more of the characters:

e MAIL_AT_EXIT
b MAIL_AT_BEGINNING
a MAIL_AT_ABORT
s MAIL_AT_SUSPENSION
n NO_MAIL

If any of these characters are duplicated in the mail_options option-argument, the duplicates will be ignored.
If 'n' is specified then mail is not sent. The qalter utility will consider it an error if any mail type other than 'n' is combined with mail type 'n'.
-master destination_identifier
Redefines the queue to serve as a master queue for a parallel job.
The destination_identifier option-argument will conform to the following:
queue[-exec .eq. exec_str]

The string "-exec.eq." is reserved for "generic" parallel job execution. At the moment of job initiation the optional execution string will be used to startup a user supplied program For example :
-master myqueue -exec.eq. "parallel N2 params "

This entry requests "myqueue" as the queue for the master process. DQS will execute the program "parallel" and pass to it the parameters "N2" and "params".
DQS attempts to assign the master host based on a first to last traversal of the destination_identifier list. If the destination_identifier list is specified as a "soft" request and DQS is unable to fill the master request based on the respective destination_identifier list, DQS will assign a master as available.
The exec_str may contain DQS reserved "wildcards" which will be expanded to provide dynamic information to the startup program. The reserved "wildcards" are:

%execer_id
Set to DQS
%master_host
Set to the master's hostname at random
%my_hostname
Set to my hostname at random
%my_nodenum
Set to my node number at random
%total_numnodes
Set to the total number of nodes at random
%remote_info
Set to remote exec_str at random

Using the previous example with a wildcard:
-master myqueue -exec.eq. "parallel %total_numnodes params"
-M mail_list
Redefines the list of users to which the server that executes the job is to send mail, if the server sends mail about the job. (Default---the login name of the user submitting the job)
mail_address[,mail_address,....]
The interpretation of mail_address is implementation defined.
-notify
Redefines the Notify attribute for a job. This attribute, when TRUE causes the batch server to send "warning" signals to a running job prior to sending the signals themselves. If a SIGSTOP is pending the job will receive a SIGUSR1 several seconds before the SIGSTOP. If a SIGKILL is pending the job will receive a SIGUSR2 several seconds before the SIGKILL. The amount of time delay is controlled by the "notify" parameter in each queue configuration.
-N name
Redefines the name of a job.
The qalter utility will set the Job_Name attribute of the job to the value of the name option, truncated to eight characters, if necessary.
If the -N option is not presented to the qalter utility, the utility will set the Job_Name attribute of the job to the name of the script -name argument after any directory path-name has been removed from the script-name.
If the -N option is not presented to the alter utility, and the script is read from standard input, the utility will set the job-name attribute of the job to the value STDIN.
-o path_name
Redefines the path for standard output of the job.
If the path_name option-argument constitutes an absolute path name, the qalter utility will set the Output_Path attribute of the job to the value of the path_name option-argument including the hostname, if present.
If the path_name option-argument constitutes a relative path name and no hostname is specified, the qalter utility will set the Output_Path attribute of the job to the value of the absolute path name derived by expanding the path_name option-argument relative to the current directory of the process that executes the qalter utility.
If the path_name option-argument constitutes a relative path name and a hostname is specified, the qalter utility will set the Output_Path attribute of the job to the value of the option-argument without expansion.
If the path_name option-argument does not include a hostname, the qalter utility will prefix the path name in the Output_Path attribute with "hostname:", where hostname is the name of the host upon which the qalter utility is being executed.
The default file name for standard output has the following form:
job_name.o.sequence_number

If the -o option possess no option-argument, the utility will clear the Output_Path attribute of the job so that the default standard error output will be used when the job is executed.
-par paradigm
the qsub utility can process, monitor and initiate parallel jobs for several parallel message passing system paradigms. The paradigm contains one of the following:

p4 support for ANL p4 language interface
mpi support for the standard MPI interface
GENERIC-ALL a simple parallel interface
PVM The ORNL PVM interface
TCGMSG The Argonne / PNL interface

(See parallel job execution in the User Manual.)
-p priority
Redefines the priority of the job.
The qalter utility will accept a value for the priority option-argument that conforms to the syntax for signed decimal integers, and which is not less than -1024 and not greater than 1023.
-passwd
Specifies that a password list will be requested for AFS and/or DFS re-authentication. If given, DQS will utilize the password list to authenticate the process prior to executing the job, so that re-authentication will be unnecessary.
-Passwd filename
Redefines the name of the file containing the AFS passwords. (See AFS support in the User Guide.)
-q destination_identifier_list
The destination_identifier option-argument will conform to the following:
queue[-exec .eq. exec_str]

The string "-exec.eq." is reserved for "generic" parallel job execution. At the moment of job initiation the optional execution string will be used to startup a user supplied program For example :
-q myqueue -exec.eq. "parallel N2 params"

This entry requests "myqueue" as the queue for the process.
DQS attempts to assign the host based on a first to last traversal of the destination_identifier list. If the destination_identifier list is specified as a "soft" request and DQS is unable to fill the request based on the respective destination_identifier list, DQS will assign a host as available.
The exec_str may contain DQS reserved "wildcards" which will be expanded to provide dynamic information to the startup program. The reserved "wildcards" are:

%execer_id
Set to DQS
%master_host
Set to the master's hostname at random
%my_hostname
Set to my hostname at random
%my_nodenum
Set to my node number at random
%total_numnodes
Set to the total number of nodes at random
%remote_info
Set to remote exec_str at random
-r y|n
Redefines whether the job is Rerunable.
If the value of the option-argument is 'y' the qalter utility will set the Rerunable attribute of the job to TRUE.
If the value of the option-argument is 'n' the qalter utility will set the Rerunable attribute of the job to FALSE.
The qalter utility will consider it an error if any character other than 'y' or 'n' is specified in the option-argument.
-rc Consumable=amount
Returns the specified amount of the named consumable.
During job execution the qalter utility may be executed and modify one job attribute only, the amount of a named consumable resource.
-reauth seconds
Specifies the time interval for AFS/DFS re-authentication.
-soft
Signifies that all resource requirements following in the qalter command will be soft requirements and will be filled on a "as available" basis before a job can be scheduled.
-S path_name_list
Redefines the shell that interprets the script at the destination system.
The qalter utility will accept a path_name_list option-argument that conforms to the following syntax:
path-name[@host][,path-name[@host],...]

The qalter utility will accept only one path name that is missing a corresponding host name. The qalter utility will allow only one path name per named host.
The qalter utility will add a value to the Shell_Path_List attribute of the job for each entry in the path_name_list option-argument.
If the -S option has no arguments the utility will set the path-list attribute of the job to the null string.
-u User_List
Redefines the user name under which the job is to run at the designated system.
-v variable_list
Redefines the environment variables to be exported to the job to be executed.
A variable_list is a set of strings delimited by commas. A string will be of either of these forms:
- variable or
- variable=value (with no intervening spaces)
A variable will not be repeated in the environment variable_list option-argument.
If the -v option is presented to the qalter utility, the utility will also add to the environment variable-list attribute of the job every variable named in the variable_list option-argument and, optionally, values of specified variables.
-verify
This does not affect any job attributes. It causes the qalter utility to send the contents of the qalter command to standard out so that it may be verified by the user.
-V
Specifies that all environment active within the dqs_execd at the time it initiates the job be exported to the job.
-z
Specifies that the qalter utility will not write the job identifier to the standard output.
Script File
The path to the script of the job.

If the script is not presented to the utility, or if the specified operand is the single character '-' (minus), the utility will read the script from standard input.

If the script argument represents a partial path, the utility will expand the path relative to the current directory of the process executing the utility.

If the qalter utility is presented with a script file it will replace the job script file originally submitted with the qsub command. The qalter utility scans the script file interpreting lines flagged with the DQS_DELIMETER pair of characters. All command options in the qalter command line and the script file are processed and replace or modify job attributes for the job.

A script can contain directives to the qalter utility.

The qalter utility will scan the lines of the script for directives until the first line that begins with a string other than the directive string; if directives occur o subsequent lines, the utility will ignore those directives.

The qalter utility will process a line in the script as a directive if, and only, if, the string of characters from the first non-white space on the line until the first space or tab character on the line match the directive prefix.

The qalter utility will ignore any blank lines and shell comment lines prior to the first executable line.

The qalter utility will process the options and option-arguments contained on the directive prefix line using the same syntax as if the options were input on the qalter command line.

The qalter utility will continue to process a directive prefix line until after a <newline> or an non-quoted comment character of the shell that will interpret the script is encountered.

If an option is present in both a directive and arguments to the qalter utility, the utility will ignore the option and the corresponding option-argument, if any, in the directive.

if an option that is present in the directive is not present in the arguments to the qalter utility, the utility will process the option and the option-argument, if any.

In order of preference, the qalter utility will select the directive prefix from one of the following sources:

If the -C option is presented to the utility, the value of the directive_prefix option argument.
If the environment variable POSIX2_DPREFIX is defined, the value of that variable.

If the -C option is present in the script file, it will be ignored.

qconf - Queue configuration tasks

qconf [-ac complex_name] [-acons consumable_name] [-ah server_list] [-am user_list] [-ao user_list ] [-aq [queue_template] ] [-au user name_list] [-Aq filename ] [-cell cell_name] [-cq destination_id_list] [-dc complex_name] [-dcons consumable_name] [-dh server_list] [-dm user_list] [-do user_list] [-dq destination_id_list] [-du user_list name_list] [-help] [-mc complex_name] [-mcons consumable_name] [-sc complex_list] [-scl] [-sconf [cell] ] [-sconsl] [-scons consumable_name] [-sh] [-sm] [-so] [-sq destination_list] ] [-sql] [-su name] [-sul] [-srl]

The qconf utility provides the user interface for managing the queues which make up a DQS environment.

The qconf may be utilized by managers, operators and users with increasing levels of restrictions. the DQS manager has unrestricted control over queue management.

Options

-ac complex_name
Adds a complex to the DQS environment. Complex entries contain one or more resources which may be requested by jobs submitted to the system. The entries will conform to the following three forms:
- string
- string=string
- string=integer quantity
There are no reserved words in complex lists. Thus the "string" may contain any combinations of alphanumeric characters and be up to 1023 bytes in length.
This option requires root/manager privileges.
-acons consumable_name
Add a consumable to the DQS environment Consumable list. Each consumable is described by a four line entry in an internal file with the consumable_name. An entry:
- Consumable consumable_name
- Available = the amount of resources available
- Consume_by quantum by which resource is reduced by a request
- Current = currently available resources
The Current value starts out with the Available value and is reduced or increased as resources are used and returned by executing jobs.
This option requires root/manager privileges.
-ah server_list
Adds one or more hosts to the DQS host list. A host must reside in the DQS list to process any other DQS commands. The host on which the qmaster is running is automatically added to the host list. In addition host names are added when they appear in a newly created queue configuration. The host-name_list will conform to the following:
hostname[,hostname,..]

This option requires root/manager privileges.
-am user_list
Adds one or more managers to the manager list.
The user_list option will conform to the following :
user[,user,....]

This option requires root/manager privileges.
-ao user_list
Adds one or more operators to the operator list
The user_list option will conform to the following :
user[,user,....]

This option requires root/manager privileges.
-aq [queue_template]
Retrieves a default queue configuration, or the optional queue-template and executes the editor specified by the EDITOR environment variable to permit the customization of the queue configuration. As a minimum the new queue must be assigned a unique queue name and a host.
Upon exit from the editor the queue is registered with the qmaster.
This option requires root/manager privileges.
-au user_list name_list
Adds one or more users to the DQS access list (ACL). The user is used for qusage authentication. The user_list option-argument will conform to the following:
user[,user,..]
or
name[,name,...]

This option requires root/manager privileges.
-Aq filename
Adds a new queue description to be added from an ASCII file. The default queue template may be found in the "common_dir" and used as a basis for preparation of the queue configuration file.
This option requires root/manager privileges.
-cell cell_name
Specifies the cell to which the qconf request will be sent.
-cq destination_id_list
Cleans out residual information from a queue where a job has been completed but for some reason the system has retained the job in the queue. This step is still necessary in DQS 3.1.2 due to some cases which the qmaster cannot verify job completion. It most often occurs when the DQS manager is starting and terminating the qmaster and dqs_execd processes with a kill -9 while doing system testing.
This option requires root/manager privileges.
-dc complex_name
Deletes the named complex.
This option requires root/manager privileges.
-dcons consumable_name
Deletes the named Consumable
This option requires root/manager privileges.
-dh server_list
Deletes one or more hosts from the DQS host list.
This option requires root/manager privileges.
-dm user_list
Deletes one or more managers from the manager list.
This option requires root/manager privileges.
-do user_list
Deletes one or more operators from the operator list.
This option requires root/manager privileges.
-dq destination_id_list
Removes the specified queue(s).
This option requires root/manager privileges.
-du user_list
Deletes one or more users from the DQS access list (ACL).
This option requires root/manager privileges.
-help
Sends a listing of the qsub options to standard output
-mc complex_name
Modify a complex. Invokes the DQS editor and displays the named complex. When the editor is closed the complex is updated by the qmaster.
This option requires root/manager privileges.
-mcons consumable_name
Invokes the editor which displays the entry for the named consumable. When the editor is closed the consumable values are updated. This action will be used by subsequent passes of the job scheduler however no RUNNING jobs will be affected.
This option requires root/manager privileges.
-sc complex_list
Show complex
-scl
Show Complex List Names
-sconf [cell]
Show master configuration for cell
-scons consumable_name
Show the named consumable entry
-sconsl
Show the consumable
-sh
Show Hosts
-sm
Show Managers
-so
Show Operators
-sq [destination_id_list]
Show queue configurations
-sql
Show list of destination identifiers (queue names)
-su name_list
Show users
-sul
Show User Lists
-srl
Show Resolve List

qdel - Delete on or more jobs from the system

qdel [-help] [-verify] job_identifier_list

A job is deleted by sending a request to the batch server that manages the job. A job that has been deleted is no longer subject to management by batch services. The qdel utility is user-accessible client of batch services that requests the deletion of one or more jobs.

A qdel utility requests a batch server to delete those jobs for which a job_identifier appears in the job_identifier list.

The qdel utility deletes jobs in the order in which their job_identifiers appear in the job_identifier list.

If the qdel utility fails to process any job_identifier successfully, the utility will proceed to process the remaining job_identifiers, if any.

The qdel utility deletes each job by sending a Delete Job Request to the qmaster.

The qdel utility will not exit until the job corresponding to each successfully processed job_identifier has been deleted.

Options

-help
Prints a listing of all options
-verify
Causes DQS to print the request to standard out. no action is taken.
job_identifier_list
Specifies the job number(s) assigned by the batch server to the jobs which are to be deleted. The form is:
sequence_number[@cell][,sequence_number[@cell],...]

If the application omits the cell portion of a job identifier, the utility will use either:
- the name of the cell specified on the command line, if any
- the name of the cell specified in the environment variable DQS_CELL, if it is set
- the name of the default cell

qhold - Place a hold on one or more jobs to defer scheduling

qhold [-h hold_list] [-help] [-verify] [job_identifier_list]

The qhold utility provides a means for a user to place on or more types of holds on identified job(s). A job that has one or more holds is not eligible for execution.

The qhold utility will place holds on jobs in the order in which their identifiers are presented to the utility.

If the qhold utility fails to process any identified job successfully, the utility will proceed to process the remaining job identifiers, if any.

The qhold utility will place holds on each job by sending a Hold Job Request to the batch server that manages the job.

The qhold utility will not exit until holds have been placed on the job corresponding to each successfully processed job identifier.

Options

-h hold_list
The qhold utility will accept a value for the hold_list option-argument that is a string one or more characters 'u' 's', or 'o' or the single character 'n'.
For each unique character in the hold_list the qhold will add a value to the Hold_Type attributes of the job as follows, each representing a different hold type:

u USER
s SYSTEM
o OPERATOR
n NO_HOLD

The hold utility will consider it an error if any hold type other than 'n' is combined with hold type 'n'.
-help
Prints a listing of all options
-verify
Causes DQS to print the request to standard out. no action is taken.
job_identifier_list
Specifies a list of one or more job sequence numbers that are created by the batch server for each job. The form is :
sequence_number[@cell][,sequence_number[@be;;],...]

If the application omits the cell portion of the identifier, the qhold utility will use either:
- the name of the cell specified on the command line, if any
- the name of the cell specified in the environment variable DQS_CELL, if it is set
- the name of the default cell
If the application presents the server portion of a job identifier to the qhold utility, the utility will send the Hold Job Request to the specified server.

qidle - X-Windows console monitor

qidle [-d display] [-s seconds ] [-g geometry ]

qidle monitors the local X server for activity an, if a user is interactively using that host's console, the local DQS queue(s) is (are) automatically suspended. If the server is idle for a certain period of time, qidle re-enables the queue causing the suspended job to resume. The sleep button in the X-windows qidle icon allows the console user to modify the length of time for which the queue is suspended.

Options

-d display
Name of the local X display. qidle will use "unix:0" as a default display unless the environment variable "DISPLAY" is present. The "-d" option will override these choices fpr the display name.
-s seconds
Length of time that the queue is suspended before retrying an enable of the queue
-g geometry
X windows geometry for the qidle window, in the form used to describe location length and width of a window for X-windows applications.

qmod - Modify the state of a queue

qmod [-cell cell_name ] [-s or -us or -soc] [-d] [-e] [-f] [-help] [-verify] [-q destination_identifier_list] or [-l resource_list]

The qmod command enables users classified as owners of a workstation to modify the state of a DQS queue for their machine. A manager, operator or the super-user can execute qmod for any queue in their system.

Options

-cell cell_name
The cell to which the request is sent.
-d
Disables the queue
-e
Enables the queue
-f
Force a modification action for the queue despite the apparent current state of the queue. For example if a queue appears to be suspended but the job execution seems to be continuing the manager can force a Force the suspend operation which will send a SIGSTOP to the job.
-help
Send a list of all options to standard output.
-l resource_list
Redefines the resources that are allowed or required by the job.
The resource_list option-argument will conform to the following:
resource[relational-op resource-field][logical-op resource[relational-op...]]

The resource_list should not contain ANY imbedded blanks, as the space character is used to delimit each of the option fields in a command.
There are two character strings which act as "reserved words" as a resource in the resource_list:

qty
The quantity of a requested resource, default=1
-exec.eq.
Identifies special parallel resource definitions. See Parallel Job Submission in the User Guide.

Each relational-op may be selected from the FORTRAN or C list of operators which consists of .eq. .ne. .gt. .lt. .ge. .le. or '==' '!=' '>' '<' '>=' '<='
A special relationship is flagged when a single equal-sign is used '='. This indicates that a comparison of character strings will be used in the relational test rather than a numeric comparison.
Each logical-op may be selected from the FORTRAN or "C" list of operators which consists of .and. .or. .not. or '&&' '||' '!'
The logical-op may be preceded or followed by an opening or closing parenthesis to ease readability. i.e. "(mem.gt.32).and.(disk.gt.100)"
-q destination_identifier_list
Name of the queue to be modified
-s
Suspends the queue and any jobs in execution.
-soc
Suspends the queue on completion of currently executing job.
-us
Removes the suspend status from the queue and restarts any jobs which were running when the queue was suspended.
-verify
Send the contents of the qmod request to standard output. No actions are taken.
-xsoc
Remove the suspend on completion mandate from the queue.

qmove - Move jobs from one cell to another

qmove [-cell cell_name ] job_identifier_list

Move a job to <cell_name >. This function is a small subset of the POSIX qmove command. If a job must be moved from one queue to another within a cell, the qalter utility should be used.

Options

job_identifier_list
Specifies a list of one or more job sequence numbers that are created by the batch server for each job. The form is :
sequence_number[@cell][,sequence_number[@be;;],...]
-cell cell_name
If the application omits the cell portion of the identifier, the qhold utility will use either;
- the name of the cell specified on the command line, if any
- the name of the cell specified in the environment variable DQS_CELL, if it is set
- the name of the default cell
If the -cell option is absent the default cell which this utility is executing within will become the destination.
If this utility is invoked by a user they must be authenticated in both cells as well as being the owner of the jobs to be moved.

qrls- Release hold(a) on one or more jobs

qrls [-h hold_list] job_identifier

A job might have one or more holds which prevent the job from executing. A job from which all the holds have been removed becomes eligible for execution, and is said to have been released.

A job hold is removed by sending a request to the qmaster The qrls utility is a user-accessible client of a batch server that requests holds to be removed from one or more jobs.

The qrls utility will remove one or more holds from those jobs for which a job_identifiers are presented to the utility.

The qrls utility will remove one or more holds in the order in which the job_identifiers are presented to the utility.

If the qrls utility fails to process a job_identifier successfully, the utility will proceed to process the remaining job-identifiers, if any.

The qrls will remove holds on each job by sending a Release Job Request to the qmaster.

The qrls utility will not exit until the holds have been removed from the job corresponding to each successfully processed job_identifier.

Options

-h hold_list
Redefines the types of holds, if any, on the job. The qrls -h option will accept a value for the hold_list option-argument that is a string of alphanumeric characters in the portable character set.
The qrls utility will accept a value for the hold_list option-argument that is a string one or more characters 'u' 's', or 'o' or the single character 'n'.
For each unique character in the hold_list the qrls utility will add a value to the Hold_Type attributes of the job as follows, each representing a different hold type:

u USER
s SYSTEM
o OPERATOR
n NO_HOLD

The qrls utility will consider it an error if any hold type other than 'n' is combined with hold type 'n'.
job_identifier_list
Specifies a list of one or more job sequence numbers that are created by the qmaster for each job. The form is :
sequence_number[@cell][,sequence_number[@be;;],...]

If the application omits the cell portion of the identifier, the qrls utility will use either;
- the name of the cell specified on the command line, if any
- the name of the cell specified in the environment variable DQS_CELL, if it is set
- the name of the default cell
If the application presents the server portion of a job identifier to the qrls utility, the utility will send the Hold Job Request to the specified server.

qstat - Display status of selected queues and jobs

qstat [-cell cell_name] [-ext] [-f] [-help] [-l resource_list ] [-u user_list] [-verify] [-q queue-name]

The status of a job, queue, or batch server is obtained by a request to the qmaster. The qstat utility is a user accessible batch client that requests the status of one or more jobs, queues, or servers, and writes the status information to standard output.

For each successfully processed destination, the qstat utility will display information about the corresponding queue.

For each successfully processed server name, the qstat utility will display information about the corresponding server.

For each successfully processed resource request, the qstat utility will display information about the queues which possess resources which match the request.

For each successfully processed user id, the qstat utility will display information about the jobs owned by that user.

The qstat utility acquires all job and queue status information in a single request to the batch server/qmaster. Server information is displayed for each queue with one of the following status symbols

RUNNING: The queue is in the running state or a job is RUNNING.
ENABLED: The queue is enabled for scheduling jobs.
DISABLED: The queue is disabled and will not be included in scheduling.
SUBORDINATED: The queue has been subordinated by a "superior" queue.
SUSPENDED: The queue any running jobs in that queue are suspended.
UNDEFINED: The queue's dqs_execd has not reported in to the qmaste
ALARM: The load average threshold for the queue has been exceeded

Options

-cell cell_name
The cell to which the qstat request is to be forwarded.
-ext
Specifies that an extended description of queues and jobs are to be sent to standard output
-f
Specifies that a "full format" output format is to be used. This format shows the full queue status and list of jobs in the queues, but not the queue and job descriptions provided with the "-ext" option.
-help
Sends a list of all qstat options to standard output
-l resource_list
Redefines the resources that are allowed or required by the job.
The resource_list option-argument will conform to the following:
resource[relational-op resource-field][logical-op resource[relational-op...]]

The resource_list should not contain ANY imbedded blanks, as the space character is used to delimit each of the option fields in a command.
There are two character strings which act as "reserved words" as a resource in the resource_list:

qty
The quantity of a requested resource, default=1
-exec.eq.
Identifies special parallel resource definitions. See Parallel Job Submission in the User Guide.

Each relational-op may be selected from the FORTRAN or C list of operators which consists of .eq. .ne. .gt. .lt. .ge. .le. or '==' '!=' '>' '<' '>=' '<='
A special relationship is flagged when a single equal-sign is used '='. This indicates that a comparison of character strings will be used in the relational test rather than a numeric comparison.
Each logical-op may be selected from the FORTRAN or "C" list of operators which consists of .and. .or. .not. or '&&' '||' '!'
The logical-op may be preceded or followed by an opening or closing parenthesis to ease readability. i.e. "(mem.gt.32).and.(disk.gt.100)"
-verify
Causes the contents of the qalter command to be sent to standard output, no status is requested or displayed.
-Q
If the -Q option is presented to the qstat utility, the utility will accept one or more operands that conform to the syntax for a destination identifier.
-B
If the -B options is presented to the qstat utility, the utility will accept one or more server-name operands.
If neither -B nor the -Q option is presented to the qstat utility, the utility will accept one or more operands that conform to the syntax for a job_identifier (see 13.3.1).

Standard Output

If the -f option is not specified, the utility will display the following items on a single line in the stated order, with white space separators, for each successfully processed operand:

queue name
job identifier
job name
job owner
job state
job location

If the -f option is specified, the utility will display the following items for each successfully processed operand:

queue name
type of queue (execution or routing )
maximum number of concurrent jobs permitted
total number of jobs in queue
enabled or disabled status of the queue
started or stopped status of the queue
job identifier
job name
job owner
job state
job location
why a pending job has not been scheduled

qsub- Submit a job to the queuing system

qsub [-a date_time] [-A account_string] [-cell cell_name] [-cwd] [-C delimiter_pair] [-e path_name] [-F] [-hard] [-h hold_list] [-help ] [-j join_list] [-jid job_identifier] [-k keep_list] [-l resource_list] [-m mail_options] [-master destination_identifier...] [-M mail_list] [-N name] [-n notify ] [-o path_name] [-par paradigm] [-p priority] [-passwd] [-passwd_file filename] [-q destination_identifier_list] [-r y|n] [-reauth seconds] [-soft] [-S path_name_list] [-u user_list] [-v variable_list] [-verify] [-V] [-z]] [script file]

To submit a script is to create a job that executes the script. A script is submitted by a request to a batch server. The qsub utility is a user accessible batch client that submits a script.

Upon successful completion, the qsub utility shall have created a job that will execute the submitted script.

The qsub utility shall submit a script by sending a Queue Job Request to a batch server.

The qsub utility shall place the value of the following environment variables in the Variable-List attributes of the job: HOME, LOGNAME, PATH, MAIL,SHELL and TZ. The name of the environment variable shall be the current name prefixed with the string "DQS_O_".

In addition to he variables described above, the qsub utility shall add the following variables with the indicated values to the variable list:

DQS_O_WORKDIR The absolute path of the current working directory of the qsub utility process.
DQS_O_HOST The name of the host on which the qsub utility is running.
DQS_O_HOME $HOME
DQS_O_HOST client host name
DQS_O_LOGNAME $LOGNAME
DQS_O_PATH $PATH
DQS_O_MAIL $MAIL
DQS_O_SHELL $SHELL
DQS_O_TZ $TZ
DQS_O_WORKDIR current working directory

Options

-a date_time
Redefines the time at which the job becomes eligible for execution.
The date_time option-argument is of the form:
[[CC]YY]MMDDhhmm[.ss]
where :

CC
Specifies the first two digits of the year
YY
Specifies the last two digits of the year
MM
Specifies the month of the year (01 to 12)
DD
Specifies the day of the month (01 to 31)
hh
Specifies the hour of the day (00 to 23 )
mm
Specifies the minute of the hour (00 to 59 )
ss
Specifies the number of seconds in the hour (00 to 59 )
(note the decimal point must be present to flag the ss )
The qalter utility sets the Execution_Time attribute of the job to the number of seconds since Epoch that is equivalent to the local times expressed by the value of the date_time option-argument. Specifying a date_time option-argument that represents a time (number of seconds since Epoch) earlier than the time at which the utility exists will have the same effect on job execution as if the -a option had not been presented to the utility.
-A account_string
Redefines the account to which the resource consumption of the job should be charged. The account string contain list containing account_names as follows:
Account_Name[@cell}[,Account_Name[@cell],... ]

The Account_Name may be any arbitrary ASCII alphanumeric string of bytes but may contain no blanks or separator characters. The under-bar "_" is considered a non-separator.
-cell cell_name
The cell to which the qalter request is to be sent.
-cwd
Redefines the current working directory to be used when the job begins execution
-C directive_prefix
The directive prefix consists of two ASCII characters which when appearing in the first two bytes of a script line indicate that what follows is a DQS command.
-e path_name
Redefines the path to be used for the standard error stream of the job.
If the path_name option-argument constitutes an absolute path name, the qalter utility will set the Error_Path attribute of the job to the value of the path_name option-argument including the hostname, if present.
If the path_name option-argument constitutes a relative path name and no hostname is specified, the qalter utility will set the Error_Path attribute of the job to the value of the absolute path name derived by expanding the path_name option-argument relative to the current directory of the process that executes the qalter utility.
If the path_name option-argument constitutes a relative path name and a hostname is specified, the qalter utility will set the Error_Path attribute of the job to the value of the option-argument without expansion.
If the path_name option-argument does not include a hostname, the qalter utility will prefix the path name in the Error_Path attribute with "hostname:", where hostname is the name of the host upon which the qalter utility is being executed.
The default file name for standard error output has the following form:
"job_name.e.sequence_number"

If the -e option possess no option-argument, the utility will clear the Error_Path attribute of the job so that the default standard error output will be used when the job is executed.
-F
Forces the submission of the job to the queuing system despite the fact that a requested resource (-l option) does not exist in any queue at the time of job submission. This is provided where the user anticipates a resource to be introduced into the system at a later time, and wishes to queue their job to wait for that resource.
-h hold_list
Redefines the types of holds, if any, on the job. The qalter -h option will accept a value for the hold_list option-argument that is a string of alphanumeric characters in the portable character set.
The qalter utility will accept a value for the hold_list option-argument that is a string one or more characters 'u' 's', or 'o' or the single character 'n'.
For each unique character in the hold_list the qalter will add a value to the Hold_Type attributes of the job as follows, each representing a different hold type:

u USER
s SYSTEM
o OPERATOR
n NO_HOLD

The qalter utility will consider it an error if any hold type other than 'n' is combined with hold type 'n'.
-hard
Signifies that all resource requirements following in the qalter command will be hard requirements and must be satisfied in full before a job can be scheduled.
-help
Prints a listing of all options for qalter.
-j join_list
Redefines which streams of the job are to be merged. The qalter -j option will accept a value for the join-list option-argument that is a string of alphanumeric characters in the portable character set.
The qalter utility will accept a join-list option-argument that consists of one or more characters 'e' and 'o' or the single character 'n'.
All of the other job output streams specified will be merged into the output stream represented by the character listed first in the join-list option-argument.
For each unique character in the join-list option-argument, the qalter will add a value to the Join_Path attribute of the job as follows, each representing a different of stream to join:

e The standard error of the batch job JOIN_STD_ERROR
o The standard output of the batch job JOIN_STD_OUTPUT
n Clear an existing Join_Path attribute NO_JOIN

If 'n' is specified, then no files are joined. The qalter utility will consider it an error if any type other than 'n' is combined with join type 'n'.
The only characters permitted in this implementation are 'y' or 'n'. and the meaning of the "-j" options is different from the standard:
The "-j" option specifies whether the standard error stream of the job is merged into the standard output steam.
If the value of the option-argument is 'y' the Join_Path attribute of the job is set to TRUE.
If the value for the option-argument id 'n' the Join_Path attribute of the job is set to FALSE.
if both the "-j y" and the -e options are specified, the batch server will set but ignore the Error_Path attribute.
if the "-j" option is not presented to the -qalter utility, the utility will set the value of the Join_Path attribute to FALSE.
-jid
Defines the job identifier on which the qalter command will act.
-l resource_list
Redefines the resources that are allowed or required by the job.
The resource_list option-argument will conform to the following:
resource[relational-op resource-field][logical-op resource[relational-op...]]

The resource_list should not contain ANY imbedded blanks, as the space character is used to delimit each of the option fields in a qalter command.
There are two character strings which act as "reserved words" as a resource in the resource_list:

qty
The quantity of a requested resource, default=1
-exec.eq.
Identifies special parallel resource definitions. See Parallel Job Submission in the User Guide.

Each relational-op may be selected from the FORTRAN or C list of operators which consists of .eq. .ne. .gt. .lt. .ge. .le. or '==' '!=' '>' '<' '>=' '<='
A special relationship is flagged when a single equal-sign is used '='. This indicates that a comparison of character strings will be used in the relational test rather than a numeric comparison.
Each logical-op may be selected from the FORTRAN or "C" list of operators which consists of .and. .or. .not. or '&&' '||' '!'
The logical-op may be preceded or followed by an opening or closing parenthesis to ease readability. i.e. "(mem.gt.32).and.(disk.gt.100)"
-m mail_options
Redefines the points in the execution of the job at which the server is to send mail about a change in the state of the job.
The qalter utility will accept a value for the mail-options option-argument that is a string one or more of the characters:

e MAIL_AT_EXIT
b MAIL_AT_BEGINNING
a MAIL_AT_ABORT
s MAIL_AT_SUSPENSION
n NO_MAIL

If any of these characters are duplicated in the mail_options option-argument, the duplicates will be ignored.
If 'n' is specified then mail is not sent. The qalter utility will consider it an error if any mail type other than 'n' is combined with mail type 'n'.
-master destination_identifier
Redefines the queue to serve as a master queue for a parallel job.
The destination_identifier option-argument will conform to the following:
queue[-exec .eq. exec_str]

The string "-exec.eq." is reserved for "generic" parallel job execution. At the moment of job initiation the optional execution string will be used to startup a user supplied program For example :
-master myqueue -exec.eq. "parallel N2 params "

This entry requests "myqueue" as the queue for the master process. DQS will execute the program "parallel" and pass to it the parameters "N2" and "params".
DQS attempts to assign the master host based on a first to last traversal of the destination_identifier list. If the destination_identifier list is specified as a "soft" request and DQS is unable to fill the master request based on the respective destination_identifier list, DQS will assign a master as available.
The exec_str may contain DQS reserved "wildcards" which will be expanded to provide dynamic information to the startup program. The reserved "wildcards" are:

%execer_id
Set to DQS
%master_host
Set to the master's hostname at random
%my_hostname
Set to my hostname at random
%my_nodenum
Set to my node number at random
%total_numnodes
Set to the total number of nodes at random
%remote_info
Set to remote exec_str at random

Using the previous example with a wildcard:
-master myqueue -exec.eq. "parallel %total_numnodes params"
-M mail_list
Redefines the list of users to which the server that executes the job is to send mail, if the server sends mail about the job. (Default---the login name of the user submitting the job)
mail_address[,mail_address,....]
The interpretation of mail_address is implementation defined.
-notify
Redefines the Notify attribute for a job. This attribute, when TRUE causes the batch server to send "warning" signals to a running job prior to sending the signals themselves. If a SIGSTOP is pending the job will receive a SIGUSR1 several seconds before the SIGSTOP. If a SIGKILL is pending the job will receive a SIGUSR2 several seconds before the SIGKILL. The amount of time delay is controlled by the "notify" parameter in each queue configuration.
-N name
Redefines the name of a job.
The qalter utility will set the Job_Name attribute of the job to the value of the name option, truncated to eight characters, if necessary.
If the -N option is not presented to the qalter utility, the utility will set the Job_Name attribute of the job to the name of the script -name argument after any directory path-name has been removed from the script-name.
If the -N option is not presented to the alter utility, and the script is read from standard input, the utility will set the job-name attribute of the job to the value STDIN.
-o path_name
Redefines the path for standard output of the job.
If the path_name option-argument constitutes an absolute path name, the qalter utility will set the Output_Path attribute of the job to the value of the path_name option-argument including the hostname, if present.
If the path_name option-argument constitutes a relative path name and no hostname is specified, the qalter utility will set the Output_Path attribute of the job to the value of the absolute path name derived by expanding the path_name option-argument relative to the current directory of the process that executes the qalter utility.
If the path_name option-argument constitutes a relative path name and a hostname is specified, the qalter utility will set the Output_Path attribute of the job to the value of the option-argument without expansion.
If the path_name option-argument does not include a hostname, the qalter utility will prefix the path name in the Output_Path attribute with "hostname:", where hostname is the name of the host upon which the qalter utility is being executed.
The default file name for standard output has the following form:
job_name.o.sequence_number

If the -o option possess no option-argument, the utility will clear the Output_Path attribute of the job so that the default standard error output will be used when the job is executed.
-par paradigm
the qsub utility can process, monitor and initiate parallel jobs for several parallel message passing system paradigms. The paradigm contains one of the following:

p4 support for ANL p4 language interface
mpi support for the standard MPI interface
GENERIC-ALL a simple parallel interface
PVM The ORNL PVM interface
TCGMSG The Argonne / PNL interface

(See parallel job execution in the User Manual.)
-p priority
Redefines the priority of the job.
The qalter utility will accept a value for the priority option-argument that conforms to the syntax for signed decimal integers, and which is not less than -1024 and not greater than 1023.
-passwd
Specifies that a password list will be requested for AFS and/or DFS re-authentication. If given, DQS will utilize the password list to authenticate the process prior to executing the job, so that re-authentication will be unnecessary.
-Passwd filename
Redefines the name of the file containing the AFS passwords. (See AFS support in the User Guide.)
-q destination_identifier_list
The destination_identifier option-argument will conform to the following:
queue[-exec .eq. exec_str]

The string "-exec.eq." is reserved for "generic" parallel job execution. At the moment of job initiation the optional execution string will be used to startup a user supplied program For example :
-q myqueue -exec.eq. "parallel N2 params"

This entry requests "myqueue" as the queue for the process.
DQS attempts to assign the host based on a first to last traversal of the destination_identifier list. If the destination_identifier list is specified as a "soft" request and DQS is unable to fill the request based on the respective destination_identifier list, DQS will assign a host as available.
The exec_str may contain DQS reserved "wildcards" which will be expanded to provide dynamic information to the startup program. The reserved "wildcards" are:

%execer_id
Set to DQS
%master_host
Set to the master's hostname at random
%my_hostname
Set to my hostname at random
%my_nodenum
Set to my node number at random
%total_numnodes
Set to the total number of nodes at random
%remote_info
Set to remote exec_str at random
-r y|n
Redefines whether the job is Rerunable.
If the value of the option-argument is 'y' the qalter utility will set the Rerunable attribute of the job to TRUE.
If the value of the option-argument is 'n' the qalter utility will set the Rerunable attribute of the job to FALSE.
The qalter utility will consider it an error if any character other than 'y' or 'n' is specified in the option-argument.
-rc Consumable=amount
Returns the specified amount of the named consumable.
During job execution the qalter utility may be executed and modify one job attribute only, the amount of a named consumable resource.
-reauth seconds
Specifies the time interval for AFS/DFS re-authentication.
-soft
Signifies that all resource requirements following in the qalter command will be soft requirements and will be filled on a "as available" basis before a job can be scheduled.
-S path_name_list
Redefines the shell that interprets the script at the destination system.
The qalter utility will accept a path_name_list option-argument that conforms to the following syntax:
path-name[@host][,path-name[@host],...]

The qalter utility will accept only one path name that is missing a corresponding host name. The qalter utility will allow only one path name per named host.
The qalter utility will add a value to the Shell_Path_List attribute of the job for each entry in the path_name_list option-argument.
If the -S option has no arguments the utility will set the path-list attribute of the job to the null string.
-u User_List
Redefines the user name under which the job is to run at the designated system.
-v variable_list
Redefines the environment variables to be exported to the job to be executed.
A variable_list is a set of strings delimited by commas. A string will be of either of these forms:
- variable or
- variable=value (with no intervening spaces)
A variable will not be repeated in the environment variable_list option-argument.
If the -v option is presented to the qalter utility, the utility will also add to the environment variable-list attribute of the job every variable named in the variable_list option-argument and, optionally, values of specified variables.
-verify
This does not affect any job attributes. It causes the qalter utility to send the contents of the qalter command to standard out so that it may be verified by the user.
-V
Specifies that all environment active within the dqs_execd at the time it initiates the job be exported to the job.
-z
Specifies that the qalter utility will not write the job identifier to the standard output.
script file
The path to the script of the job.

If the script is not presented to the utility, or if the specified operand is the single character '-' (minus), the utility will read the script from standard input.

If the script argument represents a partial path, the utility will expand the path relative to the current directory of the process executing the utility.

If the qsub utility is presented with a script file it will replace the job script file originally submitted with the qsub command. The qsub utility scans the script file interpreting lines flagged with the DQS_DELIMETER pair of characters. All command options in the qsub command line and the script file are processed and replace or modify job attributes for the job.

A script can contain directives to the qsub utility.

The qsub utility will scan the lines of the script for directives until the first line that begins with a string other than the directive string; if directives occur o subsequent lines, the utility will ignore those directives.

The qsub utility will process a line in the script as a directive if, and only, if, the string of characters from the first non-white space on the line until the first space or tab character on the line match the directive prefix.

The qsub utility will ignore any blank lines and shell comment lines prior to the first executable line.

The qsub utility will process the options and option-arguments contained on the directive prefix line using the same syntax as if the options were input on the qsub command line.

The qsub utility will continue to process a directive prefix line until after a <newline> or an non-quoted comment character of the shell that will interpret the script is encountered.

If an option is present in both a directive and arguments to the qsub utility, the utility will ignore the option and the corresponding option-argument, if any, in the directive.

if an option that is present in the directive is not present in the arguments to the qsub utility, the utility will process the option and the option-argument, if any.

In order of preference, the qsub utility will select the directive prefix from one of the following sources:

If the -C option is presented to the utility, the value of the directive_prefix option argument.
If the environment variable POSIX2_DPREFIX is defined, the value of that variable.

If the -C option is present in the script file, it will be ignored.