I recently saw a SAS Knowledge Base article called "How to stop processing your code if a certain condition is met." The article discusses the use of the %RETURN macro statement to abort the execution of a SAS program if some condition occurs. The "condition" is usually an error that needs to be addressed by the SAS programmer.

Error handling is an important part of statistical programming. The SAS/IML language has several different statements that halt execution of the IML procedure. Each is useful in a different situation. The statements are the QUIT statement, the ABORT statement, the STOP statement, and the RETURN statement.

The QUIT statement

The QUIT statement is familiar to all SAS programmers. It is used to terminate interactive procedures such as PROC SQL, PROC GLM, and PROC IML. (Recall that you should never use a RUN statement to end a PROC IML program.) A QUIT statement exits the IML procedure, closes any open files, and frees all allocated memory.

The QUIT statement cannot be used as part of a logical statement such as an IF-THEN statement. Consequently, it is not helpful for error handling. It is like the cheese in the children's singing game, "The Farmer in the Dell": the QUIT stands alone!

The ABORT statement

The ABORT statement is the runtime equivalent of the QUIT statement. You can use the ABORT statement as part of logical statements such as IF-THEN/ELSE statements, as shown in the following statements:

proc iml;
x = {-1 0 1 2};
if any(x <= 0) then 
   abort;
else
   y = log(x);

You can use the ABORT statement to handle "catastrophic" errors. For example, as shown above, you can use the abort statement when the data are not suitable for a computation. You can also use the ABORT statement to end a program if there are insufficient variables of observations to perform an analysis.

The ABORT statement is most often used in the main scope of a SAS/IML program. It is considered "poor programming etiquette" for a module to call ABORT, since it results in the IML procedure exiting. If you are writing a SAS/IML module, it is better to use the STOP or RETURN statements to handle errors.

The STOP statement

The STOP statement is a less drastic alternative to the ABORT statement. The STOP statement does not cause PROC IML to exit. The STOP statement is not usually used in the main scope of a program; it is used inside modules to stop the module execution and to return from a module. In this regard, the STOP statement is similar to the RETURN statement.

The STOP statement differs from a RETURN statement because the STOP statement can be used to control the flow of a program that has stopped inside a module. A program stops inside a module if it encounters an error, or if it encounters a PAUSE statement.

For example, the following module defines a function that returns the value 1 with probability p, and the value 0 otherwise. The parameter to the module must have a value in the interval [0,1], but the module does not check the value of the argument. (Tsk, tsk!) Therefore, you can cause a runtime error inside the module by passing in an invalid value, as shown in the following statements:

proc iml;
start ranbern(p);
   b = rand("Bernoulli", p); /* 0 <= p <= 1 */
   return(b);
finish;
 
inMain = 1;    /* define variable at main scope */
b=ranbern(-1); /* intentionally cause error in module */

ERROR: (execution) Invalid argument to function.

<details about the error>

NOTE: Paused in module RANBERN.

The NOTE in the SAS log says that the execution is paused in the module. At this point, you have four options:

• SAS/IML is an interactive procedure. The program is currently paused inside of a module. You can use PRINT statements to interrogate the values of variables within the scope of the module. You can use assignment statements to re-assign values to local variables or to re-run module statements. When you understand the reason for the error, you can ABORT, STOP, or RESUME the program.
• You can use the ABORT statement to terminate the program and quit PROC IML.
• You can use the STOP statement to jump out of the module and return to the main scope of the program.
• You can use the RESUME statement to continue running the module, starting with the next statement after the error.

stop; /* leave module; return to calling environment */
print inMain; /* prints 1 */

The RETURN statement

The RETURN statement is different from the preceding statements because it does not stop a program or handle a program that is already stopped. However, the RETURN statement, which causes a module to exit and returns control to the calling environment, is great for handling conditions before they become errors. For example, you can avoid the error in the previous section if the first statement in the RANBERN module is as follows:

   if (p<0 | p>1) then return( . ); /* return missing if parameter out of range */

I try to handle as many error conditions as possible by using the RETURN statement, and save the STOP and ABORT statements for more severe errors.