#730 SysWaitEventSem timeout return code incorrectly documented

Mark Harsen

If SysWaitEventSem times out, it returns the value "258" instead of "121" as is documented on the REXXREF.PDF that was downloaded with 4.0 beta 4702, section "8.80. SysWaitEventSem" currently found on page 495. OOREXX 3.2 also returns "258" yet also documents "121", so I assume the documentation is wrong.

Thank you, -Mark


  • Mark Harsen

    Mark Harsen - 2009-06-11

    Show SysWaitEventSem returns 258 on timeout instead of the documented 121.

  • Mark Miesfeld

    Mark Miesfeld - 2009-06-14


    On Windows many of the RexxUtils return the operating system error code on error. It is not practical to try and document every possible error code that the OS might return.

    We have had comments about this in the past from users and I've tried to improve the situation by adding some commnent about the system error codes and how to look up their meaning.

    The SysWaitEventSem doc I am looking at says for return:


    No errors.

    An error occurred. On Windows, a Windows System Error code is returned. This may be one of the following, but could be others. ...

    The key wording here is: "may be one of the following"

    The system error code: 258 is: WAIT_TIMEOUT The wait operation timed out.

    The system error code: 121 is: ERROR_SEM_TIMEOUT The semaphore timeout period has expired.

    We of course have no control over what the operating system returns and there is no way that I know of to even find out all the possible returns from any given Windows API. Microsoft documentation for any given API usually says basically the same thing as we have, the return may be x or y but could be others.

    That being said, I'll change this, as Microsoft does explicitly state this for the underlying API used in SysWaitEventSem:

    WAIT_TIMEOUT 0x00000102L The time-out interval elapsed, and the object's state is nonsignaled.

    0x102 is of course 258.

  • Mark Miesfeld

    Mark Miesfeld - 2009-06-14

    Committed revision 4791.

  • Mark Harsen

    Mark Harsen - 2009-06-16

    Thank you for your excellent explanation. I now understand the difficulties here and I think your solution is perfect to document what Windows gives us, yet to explain that other codes could be returned. I think the important thing to understand is 0 is returned when the event was successfully triggered somewhere, 258 (which hopefully won't change) indicates a timeout occurred, and anything else is some other type of error. If Microsoft changes the code for a timeout again (as the apparently did from 121 to 258), then the statement regarding "other return codes could occur" is perfect and should alert programmers that timeout testing might be required again should some other code be received.

    We couldn't ask for more. Thank you for your excellent work!

    Sincerely, -Mark



Cancel  Add attachments