job submission user interface - istituto nazionale di...

DataGr id

J O B S U B M I S S I O N U S E R I N T E R F A C E M A N P A G E S

Document identifier: DataGrid-01-TEN-0101-0_2

Date: 08/10/2001

Work package: WP1

Partner: Datamat SpA

Document status DRAFT

Deliverable identifier:

Abstract: This note provides the man pages of the Job Submission User Interface commands

IST-2000-25182 PUBLIC 1 / 41

JOB SUBMISSION USER INTERFACE MAN PAGES

Doc. Identifier:

DataGrid-01-TEN-0101-0_2

Date: 07/10/2001

Delivery Slip

Name Partner Date Signature

From Fabrizio Pacini Datamat SpA 07/10/2001

Verified by Stefano Beco Datamat SpA 07/10/2001

Approved by

Document Log

Issue Date Comment Author

0_0 18/04/2001 First draft Fabrizio Pacini

0_1 28/05/2001 draft Fabrizio Pacini

0_2 07/10/2001 Updated to take into account last UI features added for PM9 release. Fabrizio Pacini

Document Change Record

Issue Item Reason for Change

0_1 General corrections Take into account comments from WP1 members and addition of new commands description.

0_2 General corrections

The UI session concept is deprecated. As a consequence the general setting of all commands is changed. New options added to UI commands are also described.

Files

Software Products User files

Word 97 document.doc

Acrobat Exchange 4.0 DataGrid-01-TEN-0101-0_2-Document.pdf

IST-2000-25182 PUBLIC 2 / 41


Doc. Identifier:


Date: 07/10/2001

Content

1. Introduction......................................................................................................................................... 4

1.1. OBJECTIVES OF THIS DOCUMENT........................................................................................................41.2. APPLICATION AREA............................................................................................................................ 41.3. APPLICABLE DOCUMENTS AND REFERENCE DOCUMENTS......................................................................41.4. DOCUMENT EVOLUTION PROCEDURE...................................................................................................51.5. TERMINOLOGY................................................................................................................................... 5

2. EXECUTIVE SUMMARY.................................................................................................................... 6

3. USER INTERFACE............................................................................................................................ 73.1. COMMANDS DESCRIPTION..................................................................................................................9

4. ANNEXES........................................................................................................................................ 374.1. JDL ATTRIBUTES............................................................................................................................. 374.2. JOB STATUS DIAGRAM..................................................................................................................... 384.3. WILDCARD PATTERNS....................................................................................................................... 39

IST-2000-25182 PUBLIC 3 / 41


Doc. Identifier:


Date: 07/10/2001

1. INTRODUCTIONThis note provides a description of the Job Submission User Interface commands in a Unix man-page style in order to explain the main functionality supplied to the user and to highlight the interactions with the other components of the DataGrid system. It has to be intended as a preliminary effort that will be subjected to iterated refinements according to the received comments and suggestions.In the commands synopsis the mandatory arguments are showed between angle brackets (<arg>) whilst the optional ones between square brackets ([arg]). The pipe character “¦” between options/arguments indicates mutually exclusive option/arguments.

1.1. OBJECTIVES OF THIS DOCUMENTAim of this note is to provide a starting basis for the understanding of the actual user needs from the point of view of the job submission interface and to help in the identification of the interactions between the Workload Management System (WP1) components.

1.2. APPLICATION AREAWP1 and WP8-9-10.

1.3. APPLICABLE DOCUMENTS AND REFERENCE DOCUMENTSApplicable documents[A1] Job Description Language HowTo – 13/09/2001

(http://www.infn.it/workload-grid/docs/DataGrid-01-TEN-0102-Document.pdf)

[A2] DATAGRID WP1 Job Submission User Interface for PM9 (revised presentation) – 23/03/2001 (http://www.infn.it/workload-grid/docs/20010320-JS-UI-datamat.pdf)

[A3] WP1 meeting - CESNET presentation in Milan – 20-21/03/2001(http://www.infn.it/workload-grid/docs/20010320-L_B-matyska.pdf)

[A4] Logging and Bookkeeping Service – 0705/2001(http://www.infn.it/workload-grid/docs/20010508-lb_draft-ruda.pdf)

[A5] Results of Meeting on Workload Manager Components Interaction – 09/05/2001(http://www.infn.it/workload-grid/docs/20010508-WM-Interactions-pacini.pdf)

[A6] Resource Broker Architecture and APIs – 13/06/2001 (http://www.infn.it/workload-grid/docs/20010613-RBArch-2.doc)

[A7] JDL Attributes - DataGrid-01-NOT-0101-0_2 – 13/09/2001(http://www.infn.it/workload-grid/docs/DataGrid-01-NOT-0101-0_2.pdf)

Reference documents[R1]

IST-2000-25182 PUBLIC 4 / 41


Doc. Identifier:


Date: 07/10/2001

1.4. DOCUMENT EVOLUTION PROCEDUREThe content of this document will be subjected to modification according to the following events: comments received from WP1 and/or other WPs partners, changes/evolutions/additions to the Job Submission User Interface.

1.5. TERMINOLOGYDefinitionsCondor Condor is a High Throughput Computing (HTC) environment that can

manage very large collections of distributively owned workstationsGlobus The Globus Toolkit is a set of software tools and libraries aimed at the

building of computational grids and grid-based applications.

Glossaryclass-ad Classified advertisementCE Computing ElementDB Data BaseGIS Grid Information Service, aka MDSGSI Grid Security Infrastructurejob-ad class-ad describing a jobJDL Job Description LanguageJSS Job Submission ServiceLB Logging and Bookkeeping ServiceLRMS Local Resource Management SystemMDS Metacomputing Directory Service, aka GISMPI Message Passing Interface

PID Process Identifier

PM Project MonthRB Resource BrokerSMP Symmetric Multi ProcessorTBC To Be ConfirmedTBD To Be DefinedUI User InterfaceUID User IdentifierWMS Workload Management System

IST-2000-25182 PUBLIC 5 / 41


Doc. Identifier:


Date: 07/10/2001

WP Work Package

IST-2000-25182 PUBLIC 6 / 41


Doc. Identifier:


Date: 07/10/2001

2. EXECUTIVE SUMMARYThe purpose of the Job Submission User Interface is to provide easy access to grid scheduling and submission services for the DataGrid application users.In this document we describe syntax and behavior of the commands made available by the UI to allow job submission, monitoring and control.

IST-2000-25182 PUBLIC 7 / 41


Doc. Identifier:


Date: 07/10/2001

3. USER INTERFACE The Job Submission UI is the module of the WMS allowing the user to access main services made available by the components of the scheduling sub-layer. The user interaction with the system is assured for PM9 by means of a JDL and a command-driven user interface provid-ing commands to perform a certain set of basic operations. Main operations made possible by the UI are:

- Submit a job for execution on a remote Computing Element, also encompassing:o automatic resource discovery and selectiono staging of the application sandbox (input sandbox)

- Find the list of resources suitable to run a specific job- Cancel one or more submitted jobs- Retrieve the output files of a completed job (output sandbox)- Retrieve and display bookkeeping information about submitted jobs- Retrieve and display logging information about jobs.

To take advantage of UI commands the user has to possess a valid X.509 certificate issued by a DataGrid trusted CA. All commands, when started, check for the existence and expiration date of a user proxy certificate: if the proxy certificate does not exist or it is expired a new one is automatically created by the UI using the GSI services. The user proxy certificate is created as “$X509_USER_PROXY” if this environment variable is set, as “/tmp/x509up_u<UID>” otherwise. When running UI commands a user is identified by its certificate.A typical UI installation mainly consists of two directories UI_RUN and UI_CONF under the path: “<UI install_path>/UI_ROOT”. UI_RUN contains the commands executables and hence should be added to the user PATH environment variable to allow him to use UI. UI_CONF instead contains some UI configuration files. From the user point of view the relevant configuration file is UI_ConfigEnv.cfg (the only editable one) that contains the following information:

- address and port of accessible RBs,- address and port of accessible LBs,- default location of the local storage areas for the Input/Output sandbox files,- default values for the JDL mandatory attributes,- default number of retrials on fatal errors when connectiing to the LB.

Since a single installation of the UI can be used by several users on the same machine, people concurrently issuing UI commands share the same configuration files. Anyway for users (or groups of users) having particular needs it is possible to “customise” the UI configuration through the –config option supported by each UI command.Indeed every command launched specifying “–config group_name” reads its configuration settings in the file UI_ConfigEnv_<group_name>.cfg (always under $UI_INSTALL_PATH/UI_ROOT/UI_CONF path) instead of the default configuration file. Hence the user only needs to create such file according to his needs and to use the –config option to work under “special” settings.The following options are common to all commands:

- -config group_name- -noint- -debug

IST-2000-25182 PUBLIC 8 / 41


Doc. Identifier:


Date: 07/10/2001

- -version- -help

The –noint option skips all interactive questions to the user and goes ahead in the command execution. All warning messages and errors (if any) are written to the file <command_name>_<UID>_<PID>.log under the /tmp directory. It is important to note that when –noint is specified some check on “dangerous actions” are skipped too. For example if jobs cancellation is requested with this option, this action will be performed without requiring any confirmation to the user. The same is if the command output will overwrite an existing file, so it is recommended to use this option in a safe context.The –debug option is mainly thought for testing purposes indeed it make s the commands print additional information while running. Every time an external API function call is encountered during the command execution, values of parameters passed to the API is printed to the user.The info messages are displayed on the standard output and are also written to <command_name>_<UID>_<PID>.log file under the /tmp directory. An example of debug message format is as follows:#### Debug Api #### - The function job_submit has been called with the following parameters:>> par1>> par2>> par3#### End Debug ####If –noint option is specified together with –debug option the debug message will not be printed on standard output.The –version and –help options respectively make the commands display the UI current version and the detailed command usage.

IST-2000-25182 PUBLIC 9 / 41


Doc. Identifier:


Date: 07/10/2001

3.1. COMMANDS DESCRIPTION

– dg-job-submitAllows the user to submit a job for execution on remote resources in a grid.

SYNOPSISdg-job-submit [-help]dg-job-submit [-version]dg-job-submit [-template]dg-job-submit <job_description_file> [-input input_file | -resource res_id] [-notify e_mail_address] [-config group_name] [-output out_file] [-noint] [-debug]

DESCRIPTIONdg-job-submit It is the command for submitting jobs to the grid and hence allows the user to run a job at one or several remote resources. dg-job-submit requires as input a job description file in which job characteristics and requirements are expressed by means of Condor class-ad-like expressions. The job description file given in input to this command is syntactically checked and default values are assigned to some of the not provided mandatory attributes in order to create a meaningful class-ad. The resulting job-ad is sent to the Resource Broker that finds the job best matching resource (match-making) and submits the job to it.Upon successful completion this command returns to the user the submitted job identifier dg_jobId (a string that identifies unambiguously the job in the whole DataGrid), generated by the User Interface, that can be later used as a handle to perform monitor and control operations on the job (e.g. see dg-job-status described later in this document). The format of the dg_jobId is as follows:

<LBname>/<UIaddress>/<time><PID><RND>?<RBname>where:

- LBname is the LB server name and port- UIaddress is the UI machine IP address- time is the current UTC time on the submitting machine in hhmmss format - PID is the command process identifier- RND is a random number generated at each job submission- RBname is the RB server hostname and port

The structure of the dg_jobId that could appear in some way complex, has been conceived in order to assure uniqueness and the same time contain information that are needed by the components of the WMS to fulfil user requests.

IST-2000-25182 PUBLIC 10 / 41


Doc. Identifier:


Date: 07/10/2001

The -resource option can be used to target the job submission to a specific known resource identified by the provided resource identifier res_id (returned by dg-list-job-match described later in this document). For PM9 a resource will be either a queue of an underlying LRMS, assuming that this queue represents a set of “homogeneous” resources or a “single” node. The resource identifier is a string, assigned by WP4 and published in the GIS (the CEId field) that univocally identifies a resource belonging to the Grid. When the –resource option is specified, the Resource Broker skips the match making process and directly submits the job to the requested resource. It is also possible to specify the target resource to which submit the job using the –input option. With the -input option an input_file must be supplied containing a list of target resource ids. In this case the dg-job-submit command parses the input_file and displays on the standard output the list of resource Ids written in the input_file. The user is then asked to choose one resource between the listed ones. The command will then behave like already explained for the –resource option. The basic idea of this command is to use as input_file the output file generated by the dg-list-job-match command when used with the –output option (see dg-list-job-match) that contains the list of resource Ids (if any) matching the requirements specified in the jobad.jdl file. An example of a possible sequence of commands is:>$ dg-list-job-match jobad.jdl –output resource.out>$ dg-job-submit jobad.jdl –input resource.out When dg-job-submit is used with the –notify option, the following schema is used to notify the user of job status changes:- an e-mail notification is sent to e_mail_address when the match-making process has

finished and the job is ready to be submitted to JSS (READY status)- an e-mail notification is sent to e_mail_address when the job starts running on the CE

(RUNNING status)- an e-mail notification is sent to e_mail_address when the job has finished (ABORTED or

DONE status).The notification message will contain basic information on the job such as the job identifier, the assigned CE Id and a brief description of its status.It is possible to redirect the returned dg_jobId to an output file using the –output option. If the file already exists, a check is performed: if the file was previously created by the command dg-job-submit, the returned dg_jobId is appended to the existing file every time the command is launched. If the file wasn’t created by the command dg-job-submit the user will be prompted to choose if overwrite the file or not. If the answer is no the command will abort.The dg-job-submit command has a particular behaviour when the job description file contains the InputSandbox attribute whose value is a list of file paths on the UI machine local disk. The purpose of the introduction of the InputSandbox attribute is to stage from the UI to the CE files that are not available in any SE and are not published in any ReplicaCatalog.To better understand, let’s suppose to have a job that needs for the execution a certain set of files having a small size and available on the submitting machine. Let’s also suppose that for performance reasons it is preferable not going through the WP2 data transfer services for the staging of these files on the executing node. Then the user can use the InputSandbox attribute to specify the files that have to be staged from the submitting machine to the executing resource. All of them are indeed transferred at job submission time together with

IST-2000-25182 PUBLIC 11 / 41


Doc. Identifier:


Date: 07/10/2001

the job class-ad to the RB that will store them temporarily on its local disk. The JSS will then perform the staging of these files on the executing node. The size of files to be transferred to the RB should be small since overfull of RB local storage means that no more job of this type can be submitted. This mechanism can be also used to stage a job executable available locally on the UI machine to the executing CE. Indeed in this case the user has to include this file in the InputSandbox list (specifying its absolute path in the file system of the UI machine) and as Executable (see also Error: Reference source not found) has only to specify the file name. On the contrary, if the executable is already available in the file system of the executing machine, the user has to specify as Executable an absolute path name for this file (if necessary using environment variables). The same argument can be applied to the standard input file that is specified through the StdInput JDL attribute.For the standard output and error of the job the user shall instead always specify just file names (without any directory path) through the StdOutput and StdError JDL attributes. To have them staged on the UI machine it suffices to list them in the OutputSandbox and use aftre job completion the dg-get-job-output command described later in this document.The list of data specification JDL attributes is completed by the InputData attribute that refers to data used as input by the job that are not subjected to staging and are stored in one or more storage elements and published in replica catalogues. Due to this when the user specifies the InputData attribute then he/she also has to provide the name of the ReplicaCatalog where these data are published. The InputData attribute should normally contain a list of logical or physical file names.Since the InputSandbox expression can consist of a great number of file names, it is admitted the use of wildcards and environment variables to specify the value of this attribute. Syntax and allowed wildcards are described in Appendix 4.3.

JOB DESCRIPTION FILEA job description file contains a description of job characteristics and constraints in a class-ad style. Details on the class-ad language are reported in the document [A1] also available at the following URL:http://www.infn.it/workload-grid/docs/DataGrid-01-TEN-0102-Document.pdf.This file must be edited by the user to insert relevant information about the job that is later needed by the RB to perform the match-making. A template of the job description file, containing a basic set of attributes can be obtained by calling the dg-job-submit command with the -template option. Job description file entries are strings having the format attribute = expression and are terminated by the semicolon character. If the entry spans more than one line, the end of line has to be indicated with a “\” character. Comments must be preceded by a sharp character (#) at the beginning of each line.Being the class-ad an extensible language, it doesn’t exist a fixed set of admitted attributes, i.e. the user can insert in the job description file whatever attribute he believes meaningful to describe his jobs, anyway only the attributes that can be in some way related with the resource ones published in the GIS are taken into account by the Resource Broker for the match-making process. Unrelated attributes are simply ignored except when they are used to build the Requirements expression. In the latter case they are indeed evaluated and could affect the match-making result. The attributes taken into account by the RB together with their meaning are reported in Error: Reference source not found of Annexes.

IST-2000-25182 PUBLIC 12 / 41

http://www.infn.it/workload-grid/docs/classad-howto.pdf


Doc. Identifier:


Date: 07/10/2001

There is a small subset of class-ad attributes that are compulsory, i.e. that have to be present in a job class-ad before it is sent to the Resource Broker in order to make possible the performing of the match making process. They can be grouped in two categories: some of them must be provided by the user whilst some other, if not provided, are filled by the UI with configurable default values. The following Table 1 summarises what just stated.

Attribute Mandatory Mandatory with default value (default value)

Executable

Requirements (TRUE)

Rank (-EstimatedTraversalTime)

RetryCount (3)

ReplicaCatalog (only if the InputData attribute has

been specified)

DataAccessProtocol (only if the InputData attribute has

been specified)

Table 1 Mandatory Attributes

In Table 1 the default values for Requirements and Rank can be interpreted respectively as follows:- if the user has not provided job constraints then Requirements is set to TRUE, meaning

with this that there is no “physical” constraint on the resource where the job has to be executed and that the RB will take into account all sites where the user is authorised to run his application.

- Since in the JDL the greater is the value of Rank the better is considered the match, the value of the resource estimated traversal time is always subtracted to the Rank expression, i.e. resources where the jobs waits a short time to pass from the SCHEDULED to the RUNNING status are preferred. When this expression is not provided by the user, then –EstimatedTraversalTime becomes the Rank default value.

The RetryCount attribute reported in Table 1 can be used to specify the number of time the JSS must resubmit a job to a resource in case the submission fails (e.g. the resource is temporary unavailable) by means of the JDL attribute RetryCount. Only when all requested re-submissions fail the job is aborted. If the user does not provide the value of RetryCount it is assigned with a default value by the UI (this default value is currently set to 3). The default value of the RetryCount attribute can be set in the UI_ConfigEnv.cfg file.

IST-2000-25182 PUBLIC 13 / 41


Doc. Identifier:


Date: 07/10/2001

OPTIONS-help

displays command usage.

-versiondisplays UI version.

-resource res_id-r res_id

if the command is launched with this option, the job-ad sent to the RB contains a line of the type ResourceId = res_id and the job is submitted by the Resource Broker to the resource identified by res_id.

-input input_file-i input_file

if this option is specified the user will be asked to choose a resource id from a list of resources contained in the input_file. Once a res_id is selected the command behaves as explained for the -resource option. If this option is used together with the –noint and the input file contains more than one CEId, then the first CEId in the list will be taken into account for submitting the job.

-notify e_mail_address-n e_mail_address

when a job is submitted with this option an e-mail message containing basic information pertaining the job identification and status is sent to the specified e_mail_address when the job enters one of the following status:- READY- RUNNING- ABORTED or DONE

-config group_name-c group_name

if the command is launched with this option, the configuration file UI_ConfigEnv_<group_name>.cfg will be used instead of the standard configuration file UI_configEnv.cfg. If the file UI_ConfigEnv_<group_name>.cfg does not exist the user will be asked to choose whether to continue with the standard configuration file or to abort the command execution.

IST-2000-25182 PUBLIC 14 / 41


Doc. Identifier:


Date: 07/10/2001

-output out_file-o out_file

writes the generated dg_jobId in the file specified by out_file. out_file can be either a simple name or an absolute path (on the submitting machine). In the first case the file out_file is created in the current directory from which the command is launched.

-nointif this option is specified every interactive question to the user is skipped. All warning messages and errors (if occurred) are written to the file dg-job-submit_<UID>.log under the /tmp directory.

-debugwhen this option is specified, information about parameters used for the API functions calls inside the command are displayed on the standard output and are written to dg-job-submit_<UID>_<PID>.log file under the /tmp directory too.

EXIT STATUSdg-job-submit exits with a status value of 0 (zero) upon success, and 1 (one) upon failure.

IST-2000-25182 PUBLIC 15 / 41


Doc. Identifier:


Date: 07/10/2001

EXAMPLES1. $> dg-job-submit myjob1.jdl

where myjob1.jdl is as follows:

############################################## #

# -------- Job description file ----------# ############################################## Executable = "$(CMS)/fpacini/exe/sum.exe";InputData = "LF:testbed0-00019";ReplicaCatalog = "ldap://firefox.esrin.esa.it:2155/ReplicaCatalog1";DataAccessProtocol = "gridftp";RetryCount = 10;Rank = other.MaxCpuTime;Requirements = other.LRMSType == "Condor" && \ other.Architecture == "INTEL" && other.OpSys== "LINUX" && \

other.FreeCpus >= 4;

submits sum.exe to a resource (supposed to contain the executable file) whose LRMS is Condor. The command returns the following output to the user, containing the job handle (dg_jobid):

================= dg-job-submit Success ================================The job has been successfully submitted to the Resource Broker. Your job is identified by (dg_jobId): https://grid004f.cnaf.infn.it:7846/155.198.211.205/161251122764136?grid004f.cnaf.infn.it:7771

Use dg-job-status command to display current job status.===================================================================

2. $> dg-job-submit myjob2.jdl –notify [email protected] the job described by myjob2.jdl , returns the same output as above to the user and sends a notification by e-mail at well defined job status changes to [email protected].

SEE ALSO[A1], [A2], dg-list-job-match.

IST-2000-25182 PUBLIC 16 / 41

mailto:[email protected]


Doc. Identifier:


Date: 07/10/2001

– dg-get-job-outputThis command requests the RB for the job output files (specified by the OutputSandbox attribute of the job-ad) and stores them on the submitting machine local disk.

SYNOPSISdg-get-job-output [-help] dg-get-job-output [-version]dg-get-job-output < dg_jobId1 …. dg_jobIdn | -input input_file > [-dir directory_path] [-config group_name] [-noint] [-debug]

DESCRIPTION The dg-get-job-output command has to be used to retrieve the output files of a job that has been submitted through the dg-job-submit command with a job description file including the OutputSandbox attribute. After the submission, when the job has terminated its execution, the user can load the files generated by the job and temporarily stored on the RB machine as specified by the OutputSandbox attribute, issuing the dg-get-job-output with as input the dg_jobId returned by the dg-job-submit. It is also possible to specify a list of job identifiers when calling this command or an input file containing dg_jobIds by means of the –input option.The user can decide the local directory path on the UI machine where these files have to be stored by means of the –dir option, otherwise the retrieved files are put in a default location specified in the UI_ConfigENV.cfg configuration file. In both cases a sub directory will be added to the path supplied. The name of this sub-directory is the “<time><PID><RND>” unique number of the dg_jobId identifier (see command dg-job-submit for details on the dg_jobId structure).If the user wants to use his own configuration file this could be done using option –config group_name. As a consequence the dg-get-job-output command will look for the file UI_ConfigEnv_<group_name>.cfg instead of the standard configuration file. If this file does not exist the user will be notify and asked to choose if use the default configuration file or not. If the answer is no the command will abort.

OPTIONS-help



IST-2000-25182 PUBLIC 17 / 41


Doc. Identifier:


Date: 07/10/2001

-dir directory_pathretrieved files (previously listed by the user through the OutputSandbox attribute of the job description file) are stored in the location indicated by directory_path/<dg_jobId unique string>.



-nointif this option is specified every interactive question to the user is skipped. All warning messages and errors (if occurred) are written to the file dg-get-job-output_<UID>_<PID>.log under the /tmp directory.

-debugwhen this option is specified, information about parameters used for the API functions calls inside the command are displayed on the standard output and are written to dg-get_job_output_<UID>_<PID>.log file under the /tmp directory too.

dg_jobIdjob identifier returned by dg-job-submit. If a list of jobs identifiers is specified, dg_jobIds have to be separated by a blank.


this option makes the command return the OutputSandbox files for each dg_jobId contained in the input_files. This option can’t be used if one (or more) dg_jobIds have been already specified.

EXIT STATUSdg-get-job-output exits with a status value of 0 (zero) upon success, >0 upon failure and <0 upon partial failure. An example of partial failure is when more than one job identifiers has been specified and the OuputSandbox could be retrieved only for some of them.

IST-2000-25182 PUBLIC 18 / 41


Doc. Identifier:


Date: 07/10/2001

EXAMPLESLet us consider the following command:

$> dg-get-job-output https://grid004.it:2234/124.75.74.12/12354732109721?www.rb.com:4577 –dir /home/data

it retrieves the files listed in the OutputSandbox attribute from the RB and stores them locally in /home/data/12354732109721.

IST-2000-25182 PUBLIC 19 / 41


Doc. Identifier:


Date: 07/10/2001

– dg-list-job-match Returns the list of resources fulfilling job requirements.

SYNOPSISdg-list-job-match [-help] dg-list-job-match [-version]dg-list-job-match <job_description_file> [-verbose] [-config group_name] [-output output_file] [-noint] [-debug]

DESCRIPTION dg-list-job-match displays the list of identifiers of the resources accessible by the user and satisfying the job requirements included in the job description file. The resources identifiers are returned either on the standard output or in a file according to the chosen command option and are strings univocally identifying the resources published in the GIS. dg-list-job-match requires a job description file in which job characteristics and requirements are expressed by means of a Condor class-ad. The job description file is first syntactically checked and then used as the main command-line argument to dg-list-job-match. The Resource Broker is only contacted to find job compatible resources; the job is never submitted. See the dg-job-submit section and in particular Table 1 for general rules for building the job description file.If the user wants to use his own configuration file this could be done using option –config group_name. The option -verbose of the dg-list-job-match command can be used to obtain on the standard output the class-ad sent to the RB generated from the job description.The –output option makes the command save the list of compatible resources into the specified file.

JOB DESCRIPTION FILE

See dg-job-submit for details.

OPTIONS-help



IST-2000-25182 PUBLIC 20 / 41


Doc. Identifier:


Date: 07/10/2001

-verbose-v

displays on the standard output the job class-ad that is sent to the Resource Broker generated from the job description file.



-output output_file-o output_file

returns the queue identifiers list in the file specified by output_file. output_file can be either a simple name or an absolute path (on the submitting machine). In the first case the file output_file is created in the current directory from which the command is launched.

-nointif this option is specified every interactive question to the user is skipped. All warning messages and errors (if any) are written to the file dg-list-job-match <UID>_<PID>.log under the /tmp directory.

-debugwhen this option is specified, information about the API functions called inside the command are displayed on the standard output and are written to the file dg-list-job-match_<UID>_<PID>.log under the /tmp directory too.

EXIT STATUSdg-list-job-match exits with a status value of 0 (zero) upon success, and a non-zero value upon failure.

EXAMPLESLet us consider the following command:$> dg-list-job-match myjob.jdl

where the job description file myjob.jdl looks like:

IST-2000-25182 PUBLIC 21 / 41


Doc. Identifier:


Date: 07/10/2001

################################# # # Sample Job Description File # #################################

Executable = "sum.exe";StdInput = "data.in";InputSandbox = {"/home_firefox/fpacini/exe/sum.exe","/home1/data.in"};OutputSandbox = {"data.out","sum.err"};RetryCount = 4;Rank = other.MaxCpuTime;Requirements = other.LRMSType == "Condor" && other.Architecture == "INTEL" && other.OpSys== "LINUX" &&

other.FreeCpus >= 2;

In this case the job requires queues being Condor Pools of INTEL LINUX machines with at least 2 free Cpus. Moreover the Rank expression states that queues with higher maximum Cpu time allowed for jobs are preferred. The response of such a command is as follows:

******************************************************************************RESOURCE IDs LISTThe following resources matching your job requirements have been found:ResourceId1ResourceId2…***************************************************************************** $>

SEE ALSO[A1],[A2], dg-job-submit.

IST-2000-25182 PUBLIC 22 / 41


Doc. Identifier:


Date: 07/10/2001

– dg-job-cancel Cancels one or more submitted jobs.

SYNOPSISdg-job-cancel [-help] dg-job-cancel [-version]dg-job-cancel < dg_jobId1 …. dg_jobIdn | -input input_file | -all > [-notify e_mail_address] [-config group_name] [-output output_file] [-noint] [-debug]

DESCRIPTION This command cancels a job previously submitted using dg-job-submit. Before cancellation, it prompts the user for confirmation. The cancel request is sent to the Resource Broker that forwards it to the JSS that fulfils it.dg-job-cancel can remove one or more jobs: the jobs to be removed are identified by one or more job identifiers (dg_jobIds returned by dg-job-submit) provided as arguments to the command and separated by a blank space. The result of the cancel operation is reported to the user for each specified dg_jobId.If the -all option is specified, all the jobs owned by the user submitting the command are removed. When the command is launched with the -all option, no dg_jobId can be specified. It has to be remarked that for PM9 only the owner of the job can remove the job. When the –all option is specified the dg-job-cancel command contacts every Resource Broker listed in the UI_ConfigEnv.cfg file and looks for all jobs owned by the user. If the user wants to use his own configuration file this could be done using option –config group_nameThe –input option permits to specify a file (input_file) that contains the dg_jobIds to remove. The format of the file must be the following: one dg_jobId for each line. If the input_file does not represent an absolute path the file will be searched in the current working directory.The –notify option can be used to receive jobs cancellation notifications by e-mail. When this option is used the UI does not wait for the cancel notifications and returns control to the user immediately after the RB has accepted the cancellation request. This can be useful when a great number of jobs to cancel have been specified and the user wants to be able to perform other operations without waiting for the command results.Submitted jobs that have already entered the Done status can not be deleted, hence if cancellation of such jobs is requested an error message will be returned to the user.

IST-2000-25182 PUBLIC 23 / 41


Doc. Identifier:


Date: 07/10/2001

OPTIONS-help



-allcancels all job owned by the user submitting the command. This option can’t be used neither if one or more dg_jobIds have been specified nor with the –input option.


cancels dg_jobId contained in the input_files. This option can’t be used neither if one or more dg_jobIds have been specified nor with the –all option.

-notify e_mail_address-n e_mail_address

when a cancel request is submitted with this option, an e-mail message will be returned to the e_mail_address specified. The message will report on cancellation success/failure of the job specified in input. An e-mail is sent for each job to be cancelled.




writes the logging information in the file specified by output_file instead of the standard output. output_file can be either a simple name or an absolute path (on the submitting machine). In the first case the file output_file is created in the current directory from which the command is launched.

IST-2000-25182 PUBLIC 24 / 41


Doc. Identifier:


Date: 07/10/2001

-nointif this option is specified every interactive question to the user is skipped. All warning messages and errors (if occurred) are written to the file dg-job-cancel_<UID>_<PID>.log under the /tmp directory.

-debugwhen this option is specified, information about the API functions called inside the command are displayed on the standard output and are written to the file dg-job-cancel_<UID>_<PID>.log under the /tmp directory too.

dg_jobIdjob identifier returned by dg-job-submit.

EXIT STATUSdg-job-cancel exits with a status value 0 if all the specified jobs were cancelled successfully, >0 if any error occurred and <0 in case of partial failure. An example of partial failure is when more then one job has been specified: some jobs could be successfully removed and some others could be not removed.

EXAMPLES1. $> dg-job-cancel dg_jobId1 dg_jobId2

displays the following confirmation message:Are you sure you want to remove all jobs specified? [y/n]n: y

******************************************** JOBS CANCEL OUTCOME ******************************************** Cancel Success for job: - dg_jobId1Cancel Failure for job:

- dg_jobId2

$> In this case the exit code is –1.

2. $> dg-job-cancel –all

IST-2000-25182 PUBLIC 25 / 41


Doc. Identifier:


Date: 07/10/2001

displays the following confirmation message:Are you sure you want to remove all jobs owned by user fpacini? [y/n]n: y

*********************************************** JOBS CANCEL OUTCOME********************************************** Cancel Success for job: - dg_jobId1

Cancel Success for job: - dg_jobId2

$>The exit code in this case is 0

SEE ALSO[A2], dg-job-submit.

IST-2000-25182 PUBLIC 26 / 41


Doc. Identifier:


Date: 07/10/2001

– dg-job-statusDisplays bookkeeping information about submitted jobs.

SYNOPSISdg-job-status [-help] dg-job-status [-version]dg-job-status < dg_jobId1 …. dg_jobIdn | -input input_file | -all > [-full] [-config group_name] [-output output_file] [-noint] [-debug]

DESCRIPTION This command prints the status of a job previously submitted using dg-job-submit. The job status request is sent to the LB that provides the requested information.dg-job-status can monitor one or more jobs: the jobs to be checked are identified by one or more job identifiers (dg_jobIds returned by dg-job-submit) provided as arguments to the command and separated by a blank space. If the -all option is specified, information about all the jobs owned by the user submitting the command is printed on the standard output. When the command is launched with the –all option, no dg_jobId can be specified. If the user wants to use his own configuration file this could be done using option –config group_name. The –input option permits to specify a file (input_file) that contains the dg_jobIds to monitor. The format of the file must be the following: one dg_jobId for each line. If the input_file does not represent an absolute path, it will be searched in the current working directory.The job information displayed to the user encompasses (bookkeeping information):

- dg_jobId - Status (the job current status)- Job Owner (User Certificate Subject)- Location (Id of RB, JSS or CE)- Destination (CE where the job will be transferred to)- Status Enter Time (when the job entered actual state)- Last Update Time (last known event timestamp)- CpuTime (CPU time consumed until ‘LastUpdateTime’)- Status Reason (reason for being in this state)

If the -full option is specified, dg-job-status displays a long description of the queried jobs by printing in addition the following information:

- CE Node (id of cluster(s) node where the job is running)- JssId (job identifier in the JSS)- GlobusId (job identifier in the Globus job-manager)

IST-2000-25182 PUBLIC 27 / 41


Doc. Identifier:


Date: 07/10/2001

- LocalId (id in the CE queue (PBS, LSF, ..)) - Job Description (JDL) (complete JDL description of the job)- JSS Job Description (JDL) (complete JDL job description as sent to the JSS)- Rsl (RSL job description)- Moving (intermediate state: JobTransfer but neither JobAccepted nor JobRefused

has been logged yet; in this case ‘state’ and ‘location’ refer to the source of job transfer.)

Information fields that are not available (i.e. not returned by the LB are not printed).The job Status possible values are reported in Appendix 4.2. Details on the Job Status Diagram can be found in [A4].

OPTIONS-help



-alldisplays status information about all job owned by the user submitting the command. This option can’t be used neither if one or more dg_jobIds have been specified nor with the –input option.


displays bookkeeping info about all dg_jobIds contained in the input_files. This option can’t be used neither if one or more dg_jobIds have been specified nor with the –all option.

-fulldisplays a long description of the queried jobs



IST-2000-25182 PUBLIC 28 / 41


Doc. Identifier:


Date: 07/10/2001


writes the bookkeping information in the file specified by output_file instead of the standard output. output_file can be either a simple name or an absolute path (on the submitting machine). In the first case the file output_file is created in the current directory from which the command has been launched.

-nointif this option is specified every interactive question to the user is skipped. All warning messages and errors (if any) are written to the file dg-job-status_<UID>_<PID>.log under the /tmp directory.

-debugwhen this option is specified, information about the API functions called inside the command are displayed on the standard output and are written to the file dg-job-status_<UID>_<PID>.log under the /tmp directory too.

dg_jobIdjob identifier returned by dg-job-submit

EXIT STATUSdg-job-status exits with a value of 0 if the status of all the specified jobs is retrieved correctly, >0 if any error occurred and <0 in case of partial failure. An example of partial failure is when more then one job is specified: status info could be successfully retrieved for some jobs and not retrieved for some others.

EXAMPLES$> dg-job-status dg_jobId2

displays the following lines:

********************************************************************BOOKKEEPING INFORMATIONPrinting status for the job: dg_jobId2

---

IST-2000-25182 PUBLIC 29 / 41


Doc. Identifier:


Date: 07/10/2001

dg_JobId = firefox.esrin.esa.it__20010514_163007_21833_RB1_LB3Job Owner = /C=IT/O=ESA/OU=ESRIN/CN=Fabrizio Pacini/[email protected] = RUNNINGLocation = firefox.esa.it:2119/jobmanager-condorJob Destination = http://ramses.esrin.esa.it/rams/dataset1Status Enter Time = 10:24:32 05-06-2001 GMTLast Update Time = 10:25:45 05-06-2001 GMTCpuTime = 1

********************************************************************$>

SEE ALSO[A1], [A2], [A4], dg-job-submit.

IST-2000-25182 PUBLIC 30 / 41


Doc. Identifier:


Date: 07/10/2001

– dg-get-logging-infoDisplays logging information about submitted jobs.

SYNOPSISdg-get-logging-info [-help]dg-get-logging-info [-version]dg-get-logging-info < dg_jobId1 …. dg_jobIdn | -input input_file | -all > [-from T1] [-to T2] [-level logLevel] [-config group_name] [-output output_file] [-noint] [-debug]

DESCRIPTION This command queries the LB persistent DB for logging information about jobs previously submitted using dg-job-submit. The job logging information are stored permanently by the LB service and can be retrieved also after the job has terminated its life-cycle, differently from the bookkeeping information that are in some way “consumed” by the user during the job existence. The dg-get-logging-info request is sent to the LB service that queries the DB and returns the retrieved information. Contents of the logging information are:

- Event Type- dg_jobId - Logging Level- Date (UTC)- Job Destination- Host Name- Source Program- Job Owner- Job Description (JDL)

It is important to note that the format of the returned information depends on the LB model. Indeed it distinguishes between two types of collected information, namely cumulative (e. g. CPU time) and non-cumulative (e. g. memory consumption). For cumulative properties not all the values are stored in the database but the corresponding cell is overwritten with the most actual value (naturally time-stamped). Non-cumulative properties are instead stored as sent in order to allow e.g. creation of appropriate profiles.Data on several jobs can be queried by specifying a list of job identifiers separated by a blank space as arguments of the command. Moreover the –input option permits to specify a file (input_file) which contains the dg_jobId whose information are requested. The format of the file must be the following: one dg_jobId for each line. If the input_file does not represent an absolute path the file will be searched in the current working directory.

IST-2000-25182 PUBLIC 31 / 41


Doc. Identifier:


Date: 07/10/2001

If the -all option is used, logging information about all the jobs owned by the user submitting the command are printed on the standard output. When the command is launched with the -all option, neither one (or more) dg_jobId can be specified nor the –input option is allowed. To perform more complex queries, the user can specify a time range he is interested to by using the -from (T1) and -to (T2) options. These options take as input timestamps in the format hhmmssDDMMYYYY (GMT) and make the command retrieve job logging information only for the specified time interval. If these options are not specified the default values are: Unix Epoch Time (for T1) and current time, i.e. the time the command has been submitted (for T2).Another possibility (not mutually exclusive with the previous ones) is to select the log level, i.e the level of importance used for logging events by the WMS components. This could be done specifying the –level option. This option makes the command retrieve logging information only for the jobs with a logging level less or equal to the specified logLevel. The logLevel can assume one of the following values: a number from 0 to 9 a string:

- Emergency (0)- Alert (1)- Error (2)- Warning (3)- Auth (4)- Security (5)- Usage (6)- System (7)- Important (8)- Debug (9)

Each number corresponds to a string in the order specified above. Default value for logLevel is System.The -output option can be used to have the retrieved information written in the file identified by output_file instead of the standard output.If the user wants to use his own configuration file this could be done using option –config group_name.

OPTIONS-help



IST-2000-25182 PUBLIC 32 / 41


Doc. Identifier:


Date: 07/10/2001

-allretrieves logging information about all job owned by the user submitting the command.


retrieves logging info for all dg_jobIds contained in the input_files. This option can’t be used neither specifying one or more dg_jobIds nor with the –all option.

-from T1 gets job events logged since the specified date T1. T1 must be in the form hhmmss[DDMMYYYY]. If DDMMYYYY is not provided, input time is considered in the current day.

-to T2 gets job events logged up to the specified date T2. T2 must be in the form hhmmss [DDMMYYYY]. If DDMMYYYY is not provided, input time is considered in the current day.

-level logLevel-l logLevel

makes the command retrieve job’s information only for events having a log level less or equalt to the specified logLevel.




writes the logging information in the file specified by output_file instead of the standard output. output_file can be either a simple name or an absolute path (on the submitting machine). In the first case the file output_file is created in the current directory from which the command has been started.

IST-2000-25182 PUBLIC 33 / 41


Doc. Identifier:


Date: 07/10/2001

-nointif this option is specified every interactive question to the user is skipped. All warning messages and errors (if occurred) are written to the file dg-job-logging_<UID>_<PID>.log under the /tmp directory.

-debugwhen this option is specified, information about the API functions called inside the command are displayed on the standard output and are written to the file dg-job-logging_<UID>_<PID>.log under the /tmp directory too.


EXIT STATUSdg-get-logging-info exits with a value of 0 if the status of all the specified jobs is retrieved correctly, >0 if any error occurred and <0 in case of partial failure. An example of partial failure is when more then one job is specified: some job’s logging info could be successfully retrieved and some others could be not retrieved.

EXAMPLES1. $> dg-get-logging-info –all –from 12150005052001 –to 10000006052001 –output

mylog.txt

writes in file mylog.txt in the current working directory logging information about my jobs for the time since 12:15 on 5 May 2001 up to 10 o’clock on 6 May 2001.

2. $> dg-get-logging-info dg_jobId1 –from 113500

displays the following output:*******************************************************************LOGGING INFORMATION:

Printing info for the Job : "dg_jobId1"For the Event : "JobTransfer" ---Event Type = JobTransferdg_jobId = dg_jobId1 Logging Level = SystemDate(UTC) = Tue Sep 4 16:12:56 2001

IST-2000-25182 PUBLIC 34 / 41


Doc. Identifier:


Date: 07/10/2001

Job Destination = ResourceBroker/grid004f.cnaf.infn.it:7771Host Name = lx01Source Program = UserInterfaceJob Owner = /O=Grid/O=UKHEP/OU=hep.ph.ic.ac.uk/CN=Fabrizio PaciniJob Descr (JDL) = [ - InputSandboxPath = "/tmp/datamat_161251122764136" - CertificateSubject = "/O=Grid/O=UKHEP/OU=hep.ph.ic.ac.uk/ CN=Fabrizio Pacini" - rank = other.FreeCPUs * other.AverageSI00 – other.EstimatedTraversalTime - Executable = "WP1testA" - retrycount = 3 - UserContact = "[email protected]" - StdInput = "sim.dat" - InputSandbox = {"/home/datamat/HandsOn-0409/file*","/ home/datamat/DATA/*"} - StdOutput = "sim.out" - StdError = "sim.err" - requirements = other.OpSys == "Linux RH 6.1" || other.OpSys == "Linux RH 6.2" - OutputSandbox = {"/tmp/sim.err","/tmp/test.out"} - dg_jobId = "dg_jobId1" ]********************************************************************$>

SEE ALSO[A2], [A4], dg-job-submit.

IST-2000-25182 PUBLIC 35 / 41


Doc. Identifier:


Date: 07/10/2001

- dg-job-id-infoThis is a simple utility for the user; it just parses the dg-jobId string and displays formatted information contained in the job identifier. This is a “local” command since it does not need any interaction of the UI with the other WMS components.

SYNOPSISdg-job-id-info [-help]dg-job-id-info [-version]dg-job-id-info < dg_jobId1 …. dg_jobIdn | -input input_file> [-output output_file]

This command is used to display formatted information about the job from the dg_jobId of a job previously submitted. It is possible to supply one or more dg_jobIds as input to this command. Moreover it is possible to parse the dg_jobIds listed in a file using the –input option. The parsed information is printed on standard output; redirection of the output in a file can be done through the –output option.It is important to remark that since no interaction of the UI with other external components is foreseen for this command, it does no need any certificate to work.

OPTIONS-help




parses the dg_jobIds listed in the input_file. This option can’t be used specifying one (or more) dg_jobIds.


writes the formatted information in the file specified by output_file instead of the standard output. output_file can be either a simple name or an absolute path (on the

IST-2000-25182 PUBLIC 36 / 41


Doc. Identifier:


Date: 07/10/2001

submitting machine). In the first case the file output_file is created in the current directory from which the command is started.


EXIT STATUSdg-job-id-info exit with a value of 0 if no error occurs, >0 otherwise.

EXAMPLES$> dg-job-id-info https://grid001f.pd.infn.it:2234/124.75.74.12/134534534534234?http://grid004f.cnaf.infn.it:4577

displays the following output:********************************************************************JOB ID INFOPrinting info for the Job ID :https://grid004.it:2234/124.75.74.12/134534534534234?www.rb.com:4577

Logging and Bookkeeping Server Address = https://grid001f.pd.infn.itLogging and Bookkeeping Server Port = 2234 Resource Broker Server Address = http://grid004f.cnaf.infn.it Resource Broker Server Port = 4577 Submission Time (hh:mm:ss) = 13:45:34 (UTC) User Interface Machine IP Address = 124.75.74.12 User Interface Process Identifier = 53453 Randomly Generated Number (0000-9999) = 4234 ********************************************************************$>

IST-2000-25182 PUBLIC 37 / 41


Doc. Identifier:


Date: 07/10/2001

4. ANNEXES

4.1. JDL ATTRIBUTESThe JDL is a fully extensible language (i.e. it does not rely on a fixed schema), hence the user is allowed to use whatever attribute for the description of a job without incurring in er-rors. Anyway only a certain set of attributes (that we will refer to as “supported” attributes) can be taken into account by the WMS components for scheduling a submitted job. Indeed in order to be actually used for selecting a resource, an attribute used in a job class-ad needs to have a correlation with some characteristic of the resources that are published in the GIS (aka MDS).The “supported” attributes, their meaning and the way to use them to describe a job are dealt in detail in document [A7] also available at the following URL:http://www.infn.it/workload-grid/docs/DataGrid-01-NOT-0101-0_2.pdf

IST-2000-25182 PUBLIC 38 / 41

http://www.infn.it/workload-grid/docs/DataGrid-01-NOT-0101-0_2.pdf


Doc. Identifier:


Date: 07/10/2001

4.2. JOB STATUS DIAGRAMThe following Figure 1 reports the status that a job can assume during its life cycle.

Figure 1 Job Life Cycle

Job status in Figure 1 are briefly described hereafter (see [A4] for further details):

STATUS:

- SUBMITTED: job is submitted but not yet received by the RB (i.e. it is waiting in the UI).- WAITING: job is waiting in the queue in the RB for various reasons (e.g. no appropriate

CE (cluster) found; required dataset is not available, dependency on other job etc.).- READY: appropriate CE found; job is transferred to the CE.- SCHEDULED: job is waiting in the queue on the CE.- RUNNING: job is running.- CHKPT: job is check-pointed and is waiting for restart; this is a system checkpointing of

jobs running on a CE, independently from Application Checkpointing.- DONE: job successfully exited.- ABORTED: job was aborted for various reasons (e.g. waiting in the queue in RB, JSS or

CE for too long, over-use of quotas, expiration of user credentials, etc.).- CLEARED: output files were transferred to the user, job is removed from bookkeeping

database.

IST-2000-25182 PUBLIC 39 / 41


Doc. Identifier:


Date: 07/10/2001

4.3. WILDCARD PATTERNSThe wildcard patterns that can be included in the InputSandbox attribute expression are used by the UI to perform file name “globbing” in a fashion similar to the UNIX csh shell. The result of the “globbing” is a list of the files whose names match any of the specified patterns. The admitted special characters together with their meaning are listed hereafter:

- * wildcard for any string- ? wildcard for any single character- [chars ] delimits a wildcard matching any of the enclosed

characters. If chars contains a sequence of the form a-b then any character between a and b (inclusive) will match. Such an expression can be negated by means of the special character “!” ([!chars] matches any character not in chars).

EXAMPLESConsider a directory where “ls –F” gives:

1file a1.f apple.o bob.o h4374.f john.o2files ab apps/ foo.c h4374.o mydir/ABS ab.f bob foo.f john stuff/a1 apple.f bob.f gh john.f

That is to say some files and directories. The examples below show the way the mentioned wildcards are expanded (the notation => indicates the result of typing the command).

1) Every two letter file name:echo ?? => a1 ab gh

2) Every two character name starting with “a“:echo a? => a1 ab

3) Every file starting with j, o, h, or n:echo [john]* => h4374.f h4374.o john john.f john.o

4) Include a range, e.g. everything starting with an upper case letter or a digit: echo [A-Z0-9]* => 1file 2files ABS

5) Negate a range:echo [!john]*.f => a1.f ab.f apple.f bob.f foo.f

IST-2000-25182 PUBLIC 40 / 41


Doc. Identifier:


Date: 07/10/2001

6) Every file starting in “a” and ending in .f: echo a*.f => a1.f ab.f apple.f

IST-2000-25182 PUBLIC 41 / 41

job submission user interface - istituto nazionale di...

Documents