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:
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), and the cursor was not left in a field defined in the map and named, or the map did not specify CURSLOC=YES.
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.
ABMO - An ABMO error means that the map name in the COBOL program does not match the map name in front of the DFHMDI assembler macro. This error can occur when executing either a SEND MAP or RECEIVE MAP command.
Ready to start your tutorial with us? That's great! Send us an email and we will get back to you as soon as possible!