(Click to open topic with navigation)
The following describes the XML format used with the msub command to submit a job to a Moab server. This information can be used to implement a filter and modify the XML normally generated by the msub command. The XML format described in what follows is based on a variant of the Scalable Systems Software Job Object Specification.
The overall format of an XML request to submit a job can be shown through the following example:
<job> **job attribute children** </job>
An example of a simple job element with all the required children for a job submission is as follows:
<job>
<Owner>user</Owner>
<UserId>user</UserId>
<GroupId>group</GroupId>
<InitialWorkingDirectory>/home/user/directory</InitialWorkingDirectory>
<UMask>18</UMask>
<Executable>/full/path/to/script/or/first/line/of/stdin</Executable>
<SubmitLanguage>Resource Manager Type</SubmitLanguage>
<SubmitString>\START\23!/usr/bin/ruby\0contents\20of\20script</SubmitString>
</job>
The section that follows entitled Job Element Format describes the possible attributes and their meanings in detail. In actuality, all that is needed to run a job in Moab is something similar to the following:
<job> <SubmitString>\START\23!/bin/sh\0asleep\201000</SubmitString> </job>
This piece of XML requests Moab to submit a job using the contents of the SubmitString tag as a script, which is in this case a simple sh script to sleep for 1000 seconds. The msub command will create default values for all other needed attributes.
The job element of the submission request contains a list of children and string values inside the children that represent the attribute/value pairs for the job. The earlier section, Overall XML Format, gives an example of this format. This section explains these attributes in detail.
Arguments — The arguments to be passed to the program are normally specified as arguments after the first argument specifying the script to be executed.
EligibleTime — The minimum time after which the job is eligible. This is the equivalent of the -a option in msub. Format: [[[[CC]YY]MM]DD]hhmm[.SS]
Environment — The semi-colon list of environment variables that are exported to the job (taken from the msub command environment). The -V msub flag, for example, adds all the environment variables present at the time msub is invoked. Environment variables are delimited by the ~rs; characters. Following is an example of the results of the msub -v arg1=1,arg2=2 command:
<Environment>arg1=1~rs;arg2=2~rs;</Environment>
ErrorFile — Defines the path to be used for the standard error stream of the batch job. This is equivalent to the -e flag in msub.
Executable — This is normally either the name of the script to be executed, or the first line of the script if it is passed to msub through standard input.
Extension — The resource manager extension string. This can be specified via the command line in a number of ways, including the -W x= directive. Some other requests, such as some extensions used in the -l flag, are also converted to an extension string. The element has the following format:
<Extension>x=extension</Extension>
See Using the Extension Element to Submit Triggers for additional information on the extension element.
GroupId — The string name of the group of the user submitting the job. This will correspond to the user's primary group on the operating system.
Hold — Specifies that a user hold be applied to the job at submission time. This is the equivalent to the msub flag -h. It will have the form:
<Hold>User</Hold>
InitialWorkingDirectory — Specifies in which directory the job should begin executing. This is equivalent to the -d flag in the msub command.
<InitialWorkingDirectory>/home/user/directory</InitialWorkingDirectory>
Interactive — Specifies that the job is to be interactive. This is the equivalent of the -I flag in msub.
<Interactive>TRUE</Interactive>
JobName — Specifies the user-specified job name attribute. This is equivalent to the -N flag in msub.
NotificationList — Specifies the job states after which an email should be sent and also specifies the users to be emailed. This is the equivalent of the -m and -M options in msub.
<NotificationList URI=user1:user2>JobFail,JobStart,JobEnd</NotificationList>
In this example, the command msub -m abe -M user1:user2 ran indicating that emails should be sent when a job fails, starts, or ends, and that they should be sent to user1 and user2.
OutputFile — Defines the path to be used for the standard output stream of the batch job. This is the equivalent of the -o flag in msub.
Priority — A user-requested priority value. This is the equivalent to the msub -p flag.
ProjectId — Defines the account associated with the job. This is equivalent to the -A msub flag.
QueueName — The requested class of the job. This is the equivalent of the msub -q flag.
Requested — Specifies resources and attributes the job specifically requests and has the following form:
<Requested>
<... requested attributes>
</Requested>
See the section dedicated to requestable attributes in this element.
RMFlags — Flags that will get passed directly to the resource manager on job submission. This is equivalent to any arguments listed after the -l msub flag.
<RMFlags>arg1 arg2 arg3</RMFlags>
ShellName — Declares the shell that interprets the job script. This is equivalent to the msub flag -S.
SubmitLanguage — Resource manager whose language the job is using. Use TORQUE to specify a TORQUE resource manager.
SubmitString — Contains the contents of the script to be run, retrieved either from an actual script or from standard input. This also includes all resource manager specific directives that may have been in the script already or added as a result of other command line arguments.
TaskGroup — Groups a set of requested resources together. It does so by encapsulating a Requested element. For example, the command msub -l nodes=2+nodes=3:ppn=2 generates the following XML:
<TaskGroup>
<Requested>
<Processors>2</Processors>
<TPN>2</TPN>
</Requested>
</TaskGroup>
<TaskGroup>
<Requested>
<Processors>2</Processors>
</Requested>
</TaskGroup>
UserId — The string value of the user ID of the job owner. This will correspond to the user's name on the operating system.
Use the Extension element to submit triggers. With the exception of certain characters, the syntax for trigger creation is the same for non-XML trigger submission. See About object triggers for more information on triggers. The ampersand (&) and less than sign (<) characters must be replaced for the XML to be valid. The following example shows how the Extension element is used to submit multiple triggers (separated by a semi-colon). Note that ampersand characters are replaced with & in the example:
<Job> <UserId>user1</UserId> <GroupId>user1</GroupId> <Arguments>60</Arguments> <Executable>/bin/sleep</Executable> <Extension>x=trig:AType=exec&Action="env"&EType=start;trig:AType=exec&Action="trig2.sh"&EType=end</Extension> <Processors>3</Processors> <Disk>500</Disk> <Memory>1024</Memory> <Swap>600</Swap> <WallclockDuration>300</WallclockDuration> <Environment>PERL5LIB=/perl5:</Environment> </Job>
The following describes the tags that can be found in the Requested sub-element of the job element in a job submission request.
Nodes — A list of nodes that the job requests to be run on. This is the equivalent of the -l hosts=<host-list> msub directive.
<Requested>
<Nodes>
<Node>n1:n2</Node>
</Nodes>
</Requested>
In this example, the users requested the hosts n1 and n2 with the command msub -l host=n1:n2.
Processors — The number of processors requested by the job. The following example was generated with the command msub -l nodes=5:
<Requested>
<Processors>5</Processors>
</Requested>
TPN — Tasks per node. This is generated using the ppn resource manager extensions. For example, from msub -l nodes=3:ppn=2, the following results:
<Requested>
<Processors>6</Processors>
<TPN>2</TPN>
</Requested>
WallclockDuration — The requested wallclock duration of the job. This attribute is specified in the Requested element.
<Requested> <WallclockDuration>3600</WallclockDuration>
</Requested>
Related topics