[drmaa-wg] Cosmetic changes

[Rajic, Hrabri]

Hi Peter,

Excellent job.   I would like someone else to go over the proposed changes and provide comments if in disagreement so we have 3 persons' opinions and an easy way to break ties.

I will fix the author list - I am happy you have caught that Dan's name has not been added after the first changes were made.


Regards
	Hrabri

>-----Original Message-----
>From: owner-drmaa-wg at ggf.org [mailto:owner-drmaa-wg at ggf.org] On Behalf Of
>Peter Troeger
>Sent: Friday, April 21, 2006 3:18 AM
>To: DRMAA Working Group
>Subject: [drmaa-wg] Cosmetic changes
>
>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.