** SECOND DRAFT ** SECOND DRAFT ** SECOND DRAFT ** SECOND DRAFT ** SECOND DRAFT ** 3.0 BLAHP COMMANDS The following list of commands represents the set of commands required for interaction with the BLAHP server, interfacing to a given Local Resource Management system. This is based on the minimum set of commands used in the original GAHP (v1.0.0) specification removing commands that are specific to the operation of the GRAM protocol (INITIALIZE_FROM_FILE, GASS_SERVER_INIT, GRAM_CALLBACK_ALLOW, GRAM_JOB_CALLBACK_REGISTER, GRAM_PING). The JOB_SIGNAL command may be initially left unimplemented for some of the batch systems (and in that case will return an error -E- state and will not be returned by COMMANDS). BLAH_JOB_CANCEL BLAH_JOB_SIGNAL BLAH_JOB_STATUS BLAH_JOB_STATUS_ALL BLAH_JOB_SUBMIT COMMANDS QUIT RESULTS VERSION Optionally, the following two commands may also be implemented: ASYNC_MODE_ON ASYNC_MODE_OFF 3.1 CONVENTIONS AND TERMS USED IN SECTION 3.2 Below are definitions for the terms used in the sections to follow: The characters carriage return and line feed (in that order), _or_ solely the line feed character. The space character. line A sequence of ASCII characters ending with a . Request Line A request for action on the part of the BLAHP server. Return Line A line immediately returned by the BLAHP server upon receiving a Request Line. Result Line A line sent by the BLAHP server in response to a RESULTS request, which communicates the results of a previous asynchronous command Request. S: and R: In the Example sections for the commands below, the prefix "S: " is used to signify what the client sends to the BLAHP server. The prefix "R: " is used to signify what the client receives from the BLAHP server. Note that the "S: " or "R: " should not actually be sent or received. 3.2 BLAHP COMMAND STRUCTURE BLAHP commands consist of three parts: * Request Line * Return Line * Result Line Each of these "Lines" consists of a variable length character string ending with the character sequence . A Request Line is a request from the client for action on the part of the BLAHP server. Each Request Line consists of a command code followed by argument field(s). Command codes are a string of alphabetic characters. Upper and lower case alphabetic characters are to be treated identically with respect to command codes. Thus, any of the following may represent the blah_job_submit command: blah_job_submit Blah_Job_Submit blAh_joB_suBMit BLAH_JOB_SUBMIT In contrast, the argument fields of a Request Line are _case sensitive_. The Return Line is always generated by the server as an immediate response to a Request Line. The first character of a Return Line will contain one the following characters: S - for Success F - for Failure E - for a syntax or parse Error Any Request Line which contains an unrecognized or unsupported command, or a command with an insufficient number of arguments, will generate an "E" response. The Result Line is used to support commands that would otherwise block. Any BLAHP command which may require the implementation to block on network communication require a "request id" as part of the Request Line. For such commands, the Result Line just communicates if the request has been successfully parsed and queued for service by the BLAHP server. At this point, the BLAHP server would typically dispatch a new thread to actually service the request. Once the request has completed, the dispatched thread should create a Result Line and enqueue it until the client issues a RESULT command. 3.3 TRANSPARENCY Arguments on a particular Line (be it Request, Return, or Result) are typically separated by a . In the event that a string argument needs to contain a within the string itself, it may be escaped by placing a backslash ("\") in front of the character. Thus, the character sequence "\ " (no quotes) must not be treated as a separator between arguments, but instead as a space character within a string argument. 3.4 SEQUENCE OF EVENTS Upon startup, the BLAHP server should output to stdout a banner string which is identical to the output from the VERSION command without the beginning "S " sequence (see example below). Next, the BLAHP server should wait for a complete Request Line from the client (e.g. stdin). The server is to take no action until a Request Line sequence is received. Example: R: $GahpVersion: x.y.z Feb 31 2004 INFN\ Blahpd $ S: COMMANDS R: S COMMANDS BLAH_JOB_CANCEL BLAH_JOB_SIGNAL BLAH_JOB_STATUS BLAH_JOB_SUBMIT COMMANDS QUIT RESULTS VERSION S: VERSION R: S $GahpVersion: x.y.z Feb 31 2004 INFN\ Blahpd $ (other commands) S: QUIT R: S 3.4 COMMAND SYNTAX This section contains the syntax for the Request, Return, and Result line for each command. ----------------------------------------------- COMMANDS List all the commands from this protocol specification which are implemented by this BLAHP server. + Request Line: COMMANDS + Return Line: S ... + Result Line: None. ----------------------------------------------- VERSION Return the version string for this BLAHP. The version string follows a specified format (see below). Ideally, the version entire version string, including the starting and ending dollar sign ($) delimiters, should be a literal string in the text of the BLAHP server executable. This way, the Unix/RCS "ident" command can produce the version string. The version returned should correspond to the version of the protocol supported. + Request Line: VERSION + Return Line: S $GahpVesion: .. $ * major.minor.subminor = for this version of the protocol, use version 1.0.0. * build-month = string with the month abbreviation when this BLAHP server was built or released. Permitted values are: "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and "Dec". * build-day-of-month = day of the month when BLAHP server was built or released; an integer between 1 and 31 inclusive. * build-year = four digit integer specifying the year in which the BLAHP server was built or released. * general-descrip = a string identifying a particular BLAHP server implementation. + Result Line: None. + Example: S: VERSION R: S $GahpVersion: x.y.z Feb 31 2004 INFN\ Blahpd $ ----------------------------------------------- QUIT Free any/all system resources (close all sockets, etc) and terminate as quickly as possible. + Request Line: QUIT + Return Line: S Immediately afterwards, the command pipe should be closed and the BLAHP server should terminate. + Result Line: None. ----------------------------------------------- RESULTS Display all of the Result Lines which have been queued since the last RESULTS command was issued. Upon success, the first return line specifies the number of subsequent Result Lines which will be displayed. Then each result line appears (one per line) -- each starts with the request ID which corresponds to the request ID supplied when the corresponding command was submitted. The exact format of the Result Line varies based upon which corresponding Request command was issued. IMPORTANT: Result Lines must be displayed in the _exact order_ in which they were queued!!! In other words, the Result Lines displayed must be sorted in the order by which they were placed into the BLAHP's result line queue, from earliest to most recent. + Request Line: RESULTS + Return Line(s): S ... ... ... * reqid = integer Request ID, set to the value specified in the corresponding Request Line. + Result Line: None. + Example: S: RESULTS R: S 1 R: 100 0 ----------------------------------------------- ASYNC_MODE_ON Enable Asynchronous notification when the BLAHP server has results pending for a client. This is most useful for clients that do not want to periodically poll the BLAHP server with a RESULTS command. When asynchronous notification mode is active, the GAHP server will print out an 'R' (without the quotes) on column one when the 'RESULTS' command would return one or more lines. The 'R' is printed only once between successive 'RESULTS' commands. The 'R' is also guaranteed to only appear in between atomic return lines; the 'R' will not interrupt another command's output. If there are already pending results when the asynchronous results available mode is activated, no indication of the presence of those results will be given. A GAHP server is permitted to only consider changes to it's result queue for additions after the ASYNC_MODE_ON command has successfully completed. GAHP clients should issue a 'RESULTS' command immediately after enabling asynchronous notification, to ensure that any results that may have been added to the queue during the processing of the ASYNC_MODE_ON command are accounted for. + Request Line: ASYNC_MODE_ON + Return Line: S Immediately afterwards, the client should be prepared to handle an R appearing in the output of the GAHP server. + Result Line: None. + Example: S: ASYNC_MODE_ON R: S S: BLAH_JOB_CANCEL 00001 123.bbq.mi.infn.it R: S S: BLAH_JOB_CANCEL 00002 124.bbq.mi.infn.it R: S R: R S: RESULTS R: S 2 R: 00001 0 R: 00002 0 Note that you are NOT guaranteed that the 'R' will not appear between the dispatching of a command and the return line(s) of that command; the GAHP server only guarantees that the 'R' will not interrupt an in-progress return. The following is also a legal example: S: ASYNC_MODE_ON R: S S: BLAH_JOB_CANCEL 00001 123.bbq.mi.infn.it R: S S: BLAH_JOB_CANCEL 00002 124.bbq.mi.infn.it R: R R: S S: RESULTS R: S 2 R: 00001 0 R: 00002 0 (Note the reversal of the R and the S after BLAH_JOB_CANCEL 00002) ----------------------------------------------- ASYNC_MODE_OFF Disable asynchronous results-available notification. In this mode, the only way to discover available results is to poll with the RESULTS command. This mode is the default. Asynchronous mode can be enable with the ASYNC_MODE_ON command. + Request Line: ASYNC_MODE_OFF + Return Line: S + Results Line: None + Example: S: ASYNC_MODE_OFF R: S ----------------------------------------------- BLAH_JOB_SUBMIT Submit a job request to a specified queue (specified in the submit classad). This will cause the job to be submitted to the batch system. + Request Line: BLAH_JOB_SUBMIT * reqid = non-zero integer Request ID * submit classad = valid submit description for the job, in string representation. Here's a list of supported attributes with a brief description. "Cmd": Full path of the executable in the local filesystem "Args": List of individual arguments (no '/bin/sh' convention on argument separation, but separate arguments) for the executable "In": Full path in the local filesystem where the standard input for the executable is found "Out": Full path in the local filesystem where the standard output of the executable will be stored (at job completion). "Err": Full path in the local filesystem where the standard error of the executable will be stored (at job completion). "Env": Semicolon-separated list of environment variables of the form: = + Return Line: * result = the character "S" (no quotes) for successful submission of the request (meaning that the request is now pending), or an "E" for error on the parse of the request or its arguments (e.g. an unrecognized or unsupported command, or for missing or malformed arguments). + Result Lines: * reqid = integer Request ID, set to the value specified in the corresponding Request Line. * result-code = integer equal to 0 on success, or an error code * error-string = description of error * job_local_id = on success, a string representing a unique identifier for the job. This identifier must not be bound to this BLAHP server, but instead must be allowed to be used in subsequent BLAHP server instantiations. For instance, the job_local_id must be implemented in such a fashion that the following sequence of events by the caller must be permissible: a) issue a BLAH_JOB_SUBMIT command b) read the job_local_id in the result line c) store the job_local_id persistently d) subsequently kill and restart the BLAHP server process e) issue a BLAH_JOB_CANCEL command, passing it the stored job_local_id value obtained in step (b). ----------------------------------------------- BLAH_JOB_CANCEL This function removes an IDLE job request, or kill all processes associated with a RUNNING job, releasing any associated resources. + Request Line: BLAH_JOB_CANCEL * reqid = non-zero integer Request ID * job_local_id = job_local_id (as returned from BLAH_JOB_SUBMIT) of the job to be canceled. + Return Line: * result = the character "S" (no quotes) for successful submission of the request (meaning that the request is now pending), or an "E" for error on the parse of the request or its arguments (e.g. an unrecognized or unsupported command, or for missing or malformed arguments). + Result Line: * reqid = integer Request ID, set to the value specified in the corresponding Request Line. * result-code = integer equal to 0 on success, or an error code * error-string = description of error ----------------------------------------------- BLAH_JOB_STATUS Query and report the current status of a submitted job. + Request Line: BLAH_JOB_STATUS * reqid = non-zero integer Request ID * job_local_id = job_local_id (as returned from BLAH_JOB_SUBMIT) of the job whose status is desired. + Return Line: * result = the character "S" (no quotes) for successful submission of the request (meaning that the request is now pending), or an "E" for error on the parse of the request or its arguments (e.g. an unrecognized or unsupported command, or for missing or malformed arguments). + Result Line: * reqid = integer Request ID, set to the value specified in the corresponding Request Line. * result-code = integer equal to 0 on success, or an error code * error-string = description of error * job_status = if the result_code is 0 (success), then job_status is set to an integer based upon the status of the job as follows: 1 IDLE (job is waiting on the batch system queue) 2 RUNNING (job is executing on a worker node) 3 REMOVED (job was successfully cancelled) 4 COMPLETED (job completed its execution on the batch system) 5 HELD (job execution is suspended; job is still in the batch system queue) * result-classad = Aggregate information about the job status. At least the following attributes are defined: ********************************************* TO BE DEFINED ********************************************* ----------------------------------------------- BLAH_JOB_STATUS_ALL Query and report the current status of all jobs managed by the BLAH server. + Request Line: BLAH_JOB_STATUS_ALL * reqid = non-zero integer Request ID + Return Line: * result = the character "S" (no quotes) for successful submission of the request (meaning that the request is now pending), or an "E" for error on the parse of the request or its arguments (e.g. an unrecognized or unsupported command, or for missing or malformed arguments). + Result Line: * reqid = integer Request ID, set to the value specified in the corresponding Request Line. * result-code = integer equal to 0 on success, or an error code * error-string = description of error * result-classad = List of classads containing aggregate information about the job status. At least the following attributes are defined: ********************************************* TO BE DEFINED (has to include ********************************************* ----------------------------------------------- BLAH_JOB_SIGNAL Send a signal (if possible) to a specified job. This has to be in the RUNNING status. + Request Line: BLAH_JOB_SIGNAL * reqid = non-zero integer Request ID * job_local_id = job_local_id (as returned from BLAH_JOB_SUBMIT) of the job whose status is desired. * signal = an integer with the signal to send + Return Line: * result = the character "S" (no quotes) for successful submission of the request (meaning that the request is now pending), or an "E" for error on the parse of the request or its arguments (e.g. an unrecognized or unsupported command, or for missing or malformed arguments). + Result Line: * reqid = integer Request ID, set to the value specified in the corresponding Request Line. * result-code = integer equal to 0 on success, or an error code * error-string = description of error * job_status = if the result_code is 0 (success), then job_status is set to an integer based upon the status of the job as follows (compare above): 1 IDLE 2 RUNNING 3 REMOVED 4 COMPLETED 5 HELD ----------------------------------------------- ** SECOND DRAFT ** SECOND DRAFT ** SECOND DRAFT ** SECOND DRAFT ** SECOND DRAFT **