MAPFAIL and other exception conditions

The MAPFAIL exception condition occurs when no usable data is transmitted from the terminal, or when the data transmitted is unformatted.

The MAPFAIL condition occurs on a RECEIVE MAP if the operator has used the CLEAR key or one of the PA keys. It also occurs if the operator uses ENTER or a PF key from a screen when both the following conditions apply:
  • No fields defined in the map have the modified data tag set on (this means the operator did not key anything and you did not send any fields with the tags already set, so that no data is returned on the read).
  • The cursor was not located in a field defined in the map and named, or the map did not specify CURSLOC=YES.
An operator might easily press ENTER too soon, or a short read key accidentally. To be user friendly, you might want to refresh the screen after a MAPFAIL condition, rather than ending the transaction in error.
A MAPFAIL condition also occurs if you issue a RECEIVE MAP without first formatting with a SEND MAP, or equivalent, in the current or a previous task, and can occur if you use a map that is different from the one you sent. This situation might signal an error in logic, or it might mean that your transaction is in its startup phase. For example, the quick update example does not allow for getting started; that is, for getting an empty map onto the screen so that the operator can start to use the transaction. You could use a separate transaction to do this, but you can take advantage of the code you need to refresh the screen after a MAPFAIL. The required code is as follows: 
       IF RCV-RC = DFHRESP(MAPFAIL)
           MOVE 'PRESS PF12 TO QUIT THIS TRANSACTION' TO MSGO
           EXEC CICS SEND MAP('QUPMAP') MAPSET('QUPSET')
                       FROM(QUPMAPO) END-EXEC.
This code reminds the operator how to escape, because attempts to do this might be the original cause of the MAPFAIL. If you do not want to send this message, or if it was the default in the map, you can use the MAPONLY option: 
       EXEC CICS SEND MAP('QUPMAP') MAPSET('QUPSET') MAPONLY END-EXEC.

When MAPFAIL occurs, the input map structure is not cleared to nulls, as it is otherwise, so you must test for this condition if your program logic depends on this clearing.

You can issue a HANDLE CONDITION command to intercept MAPFAIL, as you can for other exception conditions. However, if you issue a HANDLE CONDITION command and you also have a HANDLE AID active for the AID you receive, control goes to the label specified for the AID and not that for MAPFAIL. For further explanation, see Using the HANDLE AID command. In this situation, you will not be aware of the MAPFAIL, even though you issued a HANDLE for it, unless you also test EIBRESP.

EOC condition

EOC is another condition that you encounter frequently using BMS. It occurs when the end-of-chain (EOC) indicator is set in the request/response unit returned from z/OS® Communications Server. EOC does not indicate an error, and the BMS default action is to ignore this condition.