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@ggf.org [mailto:owner-drmaa-wg@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@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.