The exceptional conditions that can occur on a RECEIVE command are all described in the CICS® Application Programming Reference manual, and most are self-explanatory. One of them warrants discussion, however, because it can result from a simple operator error. This is MAPFAIL, which occurs when no usable data is transmitted from the terminal or when the data transmitted is unformatted (in the 3270 sense--see Unformatted mode). MAPFAIL 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 where:
Pressing ENTER prematurely or a "short read" key accidentally is an easy mistake for the operator to make. In the interest of user friendliness, you may want to refresh the screen after MAPFAIL instead of ending the transaction in error.
MAPFAIL 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 different from the one you sent. This might signal an error in logic, or it might simply mean that your transaction is in its startup phase. For instance, in our "quick update" example, we have not made any provision for getting started--that is, for getting an empty map onto the screen so that the operator can start using the transaction. We could use a separate transaction to do this, but we might as well take advantage of the code we need to refresh the screen after a MAPFAIL. What we need is:
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.
We are reminding the operator how to escape, because attempts to do this may have caused the MAPFAIL in the first place. If we had not wanted to send this message, or if it was the default in the map, we could have used 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 it is important to 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 other exception conditions. If you do, and you also have a HANDLE AID active for the AID you receive, however, control goes to the label specified for the AID and not that for MAPFAIL, as explained in Using the HANDLE AID command. In this situation you will be unaware of the MAPFAIL, even though you issued a HANDLE for it, unless you also test EIBRESP.
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 VTAM®. EOC does not indicate an error, and the BMS default action is to ignore this condition.
[[ Contents Previous Page | Next Page Index ]]