[drmaa-wg] Cosmetic changes

[Peter Troeger]

Hi,

here is the promised proposal of "cosmetic" changes for the latest
version of the spec. Most of them fix an incorrect application of
RFC-2119 keywords. It is much more then expected, but nothing critical
regarding semantics or functionality.

Author list:
- Hrabri occurs twice, Dan is missing, Peter might get a star symbol
attached to his name

Section 1.2:
- Replace "Interface Definition Language (IDL) - like" with "C - like"

Section 2, second sentence:
- Replace "SHOULD" with "should"

Section 2.1:
- First sentence: Replace "COULD" with "could"
- Second sentence: Replace "COULD" with "MAY"
- Third sentence: Replace "COULD" with "SHOULD be able to"

Section 2.2:
- First sentence: Replace "it is RECOMMENDED a DRMAA library be
thread-safe" with "a DRMAA library SHOULD be thread-safe"
- Second sentence: Replace "It is RECOMMENDED that the DRMAA
implementers label" with "DRMAA implementers SHOULD label"

Section 2.3:
- Replace "Unix and Windows" with "operating system"

Section 2.4:
- Replace "MAY" with "may"

Section 2.4.1:
- 4. paragraph: Replace "MAY" with "may", replace "SHALL" with "can"

Section 2.4.2, last paragraph:
- Replace "is assumed" with "SHOULD"

Section 2.5.2:
- join_files attribute is missing in the list

Section 2.5.4:
- Remove "(this is a useful synchronization mechanism)"
- Replace "on all job Id's in the current process" with "on all job Id's
in the current session"
- The following sentence sounds very strange: "The Unix and Windows
signals are replaced with the job control routines that have
counterparts in DRMS." What does that mean ? The Win32 subsystem has no
signalling, but an exception concept. Signals are not really 'replaced'
by the control routines, do they ?
- We have no state expressing "System and user suspended simultaneously"

Section 3:
- Replace "IDL-like" with "C-like"

Section 3.1:
- Replace "drmaa." with "drmaa_".

Section 3.1.1:
- Remove "(except those that return already allocated sclar or vector
values and cannot fail)"
- Replace "Successful return is indicated" by "Successful return SHALL
be indicated"
- Replace "An invalid argument is flagged" by "An invalid argument SHALL
be flagged"
- Replace "The error code MAY be provided" with "The error code can be
provided"
- Replace "error string that MAY be used in addition" with "error string
that can be used in addition"

Section 3.1.2:
- Replace "NOT RECOMMENDED" by "SHOULD NOT be possible".
- Replace "It is RECOMMENDED that the DRMAA library SHALL free" with
"The DRMAA library SHOULD free"
- Replace "so it is RECOMMENDED that old session resources not be used
later" with "so old session resources SHOULD NOT be usable later by the
application."
- Replace "It is RECOMMENDED that restartable applications make" with
"Restartable applications SHOULD make"
- Replace "drmaa_synchronize" with "drmaa_synchronize()"
- Replace "calls will make them" with "calls will make job id's"

Section 3.1.4:
I am not able to catch what the first three sentences want to explain.
How can programmatically changed attrivutes be set at compile time ?

Section 3.1.5:
- Replace "The following are RECOMMENDED" with "The following are
recommended"

Section 3.2.1:
- Replace "drmaa_init() SHOULD be called by only one of the threads. The
main thread is RECOMMENDED." with "drmaa_init() SHOULD be called by only
one of the threads, which SHOULD be the main application thread."

Section 3.2.2, description of drmaa_get_attribute():
- Replace "otherwise, NULL is returned" with "otherwise, NULL MUST be
returned."

Section 3.2.2, description of drmaa_get_vector_attribute():
- Replace "the values of 'name' are returned; otherwise, NULL is
returned" with "the values of 'name' SHALL be returned; otherwise, NULL
MUST be returned"

Section 3.2.3, first paragraph:
- Replace "reserved attribute names" with "reserved attributes"

Section 3.2.3, description of job start time parameter:
- Replace "when the job MAY be eligible" with "when the job may be eligible"

Section 3.2.3, description of transfer files parameter:
- Replace "MAY be specified" with "can be specified".

Section 3.2.5, description of drmaa_synchronize:
- Second sentence: Replace "SHOULD" with "SHALL"
- Third sentence: Replace "then this routine waits for all" with "then
this routine SHALL wait for all"
- 4. sentence: Replace "the routine SHOULD immediately return" with "the
routine SHALL return"
- Replace "the caller MAY use timeout specifying" with "the caller can
use the timeout parameter specifying"

Section 3.2.5, description of drmaa_wait:
- Third sentence: Replace "SHOULD" with "MUST"
- 4. sentence: Replace "SHOULD" with "MUST"
- Replace "so any subsequent calls to drmaa_wait SHOULD fail" with "so
any subsequent calls to drmaa_wait SHALL fail"
- Replace "DRMAA_ERRNO_INVALID_ARGUMENT SHOULD be thrown" with
"DRMAA_ERRNO_INVALID_ARGUMENT SHALL be returned"

Section 3.2.5, description of drmaa_wifsignaled:
- Replace "returned in signaled indicates" with "returned in the
'signaled' parameter indicates"

Section 3.2.5, description of drmaa_job_ps:
- drmaa_context_error_buf must be flagged as "OUT" in the signature

Section 3.2.6, description of drmaa_strerror:
- Replace signature "error_string drmaa_strerror( errno )" with
"drmaa_strerror( IN errno, OUT error_string )"
- Replace "RETURNS" with "OUT error_string"

Section 3.2.6:
- Add "OUT" keyword to the parameters in the signature of the following
functions: drmaa_get_contact, drmaa_version, drmaa_get_DRM_system,
drmaa_get_DRMAA_implementation

Section 3.3, description of DRMAA_ERRNO_NO_DEFAULT_CONTACT_STRING_SELECTED:
- Replace "multiple DRMAA implementation contained in the binary module"
 with "multiple available DRMAA implementations"

Section 3.3, description of DRMAA_ERRNO_CONFLICTING_ATTRIBUTE_VALUES:
- Replace "attributes" with "attribute"

Section 5:
- Add Dan
- Write Peter's address in the following way (missing newline):
Peter Tröger
peter.troeger at hpi.uni-potsdam.de
Hasso-Plattner-Institute at University of Potsdam
Prof.-Dr.-Helmert-Str. 2-3
D-14482 Potsdam
Germany

Section 8+:
- List of references is missing (relates only to [RFC2119])

Do we want to thank some contributors at the end of the document ?

Best regards,
Peter.