A NOTREADY condition happens when a stream function has a problem accessing some stream, such as LINEIN() not properly reading the next line from a stream. This may involve a failure on the part of the operating system's underlying file system. There are many reasons why there may be a problem accessing a stream.

The default handling for the NOTREADY condition is to ignore it. So for example, assume the following script, and let's also assume that there is a problem with LINEIN() such that it raises the NOTREADY condition: 

chars = LINEIN(,,1)
SAY chars
REXX ignores the NOTREADY condition since we are not trapping it. REXX therefore executes both instructions. What does SAY display? It displays an empty string, since that is what LINEIN() returns if there is a problem and your script is not trapping NOTREADY condition.

This is an important item to note. When any stream function has a problem, and you're not trapping NOTREADY, then the function returns an innocuous value that could indicate a successful operation. In other words, the stream function reports success but "fakes the operation". LINEIN() hasn't really read in an empty line. Because it has had a problem reading in another line, LINEIN() lies to you and tells you that it successfully read another line which happens to be empty.

Let's take another example. Assume we have the following script where we want to display Hello to the command prompt window. But let's also assume that LINEOUT() has a problem doing that: 

err = LINEOUT(, "Hello")
SAY err
Again, REXX ignores the NOTREADY condition since we are not trapping it. REXX therefore executes both instructions. What does SAY display? It displays a 0, since that is what LINEOUT() returns if there is a problem and your script is not trapping NOTREADY condition. In other words, LINEOUT() has also lied to us and told us that it successfully wrote the line.

The implication here is that, if you want to ensure that you are informed when your stream operations fail, you need to trap the NOTREADY condition.

Consider the following script, and again assume that LINEOUT() has a problem: 

/* Trap NOTREADY */
SIGNAL ON NOTREADY NAME MyHandler
err = LINEOUT(, "Hello")
SAY err
EXIT

MyHandler:
   SAY 'NOTREADY raised'
   RETURN
LINEOUT() raises the NOTREADY condition, and REXX sees that you have trapped NOTREADY, so instead of proceeding on to the SAY instruction, REXX instead jumps to the label MyHandler.

Your handler can use the CONDITION() built-in function's 'D' option to fetch the name of the stream which has a problem. For example: 

/* Trap NOTREADY */
SIGNAL ON NOTREADY NAME MyHandler
err = LINEOUT(, "Hello")
SAY err
EXIT

MyHandler:
   SAY 'The stream named "'|| CONDITION('D') ||'" had a problem at line' SIGL
   RETURN
Whenever a NOTREADY condition is raised, then an error number, and possibly a sub-error number as well, is associated with that instance of the condition being raised. Each one of the numerous reasons for NOTREADY being raised will produce a different combination of error/sub-error numbers. So, by checking the error/sub-error numbers, you can deduce exactly what went wrong in your script (ie, why the NOTREADY condition was raised).

Your handler can use CONDITION()'s 'E' option to fetch the error and sub-error numbers associated with a given instance of that condition. CONDITION('E') will return the two numbers separated by a dot. The error number will be 11 if NOTREADY has been raised as a result of a call to some stream function in your script. The sub-error number is set by the operating system, and can be any error number associated with its file system. You'll have to consult the documentation with your operating system to determine what a particular sub-error number means, or use the STREAM() built-in function's 'D' option to retrieve a more descriptive error message.

Note: Reginald's CONDITION() function has an additional option. CONDITION('M') will present a pop-up message box containing the name of the file in error as well as the operating system specific error message, the name of the script in which NOTREADY was raised, the source line and line number upon which NOTREADY was raised, and a Help button to bring up a help page for that error. This is preferable to trying to create your own message to present to the person running your script.

A NOTREADY condition can also be raised if you've issued an OPTIONS 'TRAP' instruction and are trapping NOTREADY, and then you call some other script in which NOTREADY is raised, but not trapped, in that child script. In this case, CONDITION('E') returns an error number of 65. (This is a Reginald-only feature). The sub-error number is set by the operating system. CONDITION('D') will return an error message that reports the name of the script in which NOTREADY was raised, the line number where it occurred, and the name of the stream that had the problem. Here is an example handler that would differentiate between NOTREADY raised in your script versus another script that you called: 

MyHandler:
   PARSE VALUE CONDITION('E') WITH error '.' sub
   IF error == '65' THEN DO
      PARSE VALUE CONDITION('D') WITH . '"' scriptname '"' . 'line ' linenum ': ' streamname
      SAY 'NOTREADY condition raised in "'|| scriptname ||'" at line' linenum ':' streamname
	  SAY STREAM(streamname, 'D')
   END
   ELSE DO
      SAY 'NOTREADY condition raised at line' SIGL ':' CONDITION('D')
	  SAY STREAM(CONDITION('D'), 'D')
   END
   RETURN