What is the difference between EXEC CICS SEND MAP and EXEC CICS SEND TEXT?

SEND MAP sends a structured BMS map to the terminal — it uses a pre-defined screen layout (a mapset loaded from a CICS MAPSET resource) and populates fields from the symbolic description map in WORKING-STORAGE. SEND TEXT sends unstructured text to the terminal without a pre-defined screen layout, formatting it as a simple text stream. SEND MAP is used for interactive data entry screens. SEND TEXT is used for reports, help text, or situations where dynamic content generation is more appropriate than a fixed map layout.

What does the ERASE option do on EXEC CICS SEND MAP?

ERASE clears the entire 3270 terminal screen before painting the new map. This sends an ERASE/WRITE command to the terminal, which sets all screen positions to null (blank with no attributes). Use ERASE on the very first SEND MAP of a transaction or whenever switching between completely different maps. Omit ERASE and use DATAONLY for subsequent sends on the same map to improve performance by only transmitting changed data fields.

How do I position the cursor to a specific field in CICS?

Three approaches: (1) In the BMS DFHMDF macro, specify ATTRB=(...,IC) to set the initial cursor position for that field — CICS will place the cursor there whenever the map is sent with CURSOR option. (2) On EXEC CICS SEND MAP, specify CURSOR(n) where n is the absolute screen position offset (row-1 * width + column-1). (3) At runtime, move the attribute byte for the target field to include the IC attribute before issuing SEND MAP with the CURSOR option — CICS places the cursor at the first field with the IC bit set.

When would I use EXEC CICS CONVERSE instead of separate SEND and RECEIVE?

EXEC CICS CONVERSE combines a SEND and a RECEIVE into one command — it sends data to the terminal and immediately waits for the user's response without releasing the task. This makes CONVERSE a conversational (not pseudo-conversational) command. It is rarely used in modern CICS applications because holding the task during user think time wastes resources. The only appropriate use is in automated test drivers or machine-to-machine scenarios where the 'user' responds immediately with no think time.

CICS SEND and RECEIVE Commands: Complete Terminal I/O Guide

Introduction: Terminal I/O in CICS

Every CICS transaction that interacts with a human user must send data to a terminal and receive data back. In a 3270 environment, this means painting screens, reading modified fields, and responding to AID keys. CICS provides a family of SEND and RECEIVE commands that handle this terminal I/O at different levels of abstraction — from the highly structured BMS SEND MAP to the low-level SEND with raw data streams.

Understanding all the SEND and RECEIVE variants — their options, their interaction with BMS attributes, and their performance implications — separates a competent CICS developer from one who can only copy-paste patterns from existing code.

EXEC CICS SEND MAP: The Standard Screen Painting Command

SEND MAP is the workhorse of CICS terminal I/O. It sends a BMS-defined map to the terminal, populating output fields from the symbolic description map structure in WORKING-STORAGE.

First Send: ERASE

The very first time a map is sent to a terminal screen, use ERASE to clear any previous content and paint the full map including static labels, field attributes, and data:

cobol

*── First-time send: clear screen and paint everything ───────────
SEND-INITIAL-MAP.
    INITIALIZE EMPIMAPO       *> Clear all output fields first
    MOVE 'ENTER EMPLOYEE NUMBER' TO MSGO

    EXEC CICS SEND MAP('EMPIMAP')
                   MAPSET('EMPIMAPS')
                   FROM(EMPIMAPO)
                   ERASE
                   CURSOR
                   RESP(WS-RESP)
    END-EXEC.

Subsequent Sends: DATAONLY

On re-sends of the same map (after processing user input, updating some fields, and redisplaying), use DATAONLY to transmit only the data fields — not the static labels and attribute bytes that haven't changed. This reduces 3270 datastream traffic significantly on loaded networks:

cobol

*── Re-send after processing — update changed fields only ────────
REDISPLAY-MAP.
    MOVE WS-EMP-NAME TO EMPNAMEO
    MOVE WS-ERR-MSG  TO MSGO
    MOVE DFHBMBRY    TO EMPNOA    *> Highlight EMPNO field in error

    EXEC CICS SEND MAP('EMPIMAP')
                   MAPSET('EMPIMAPS')
                   FROM(EMPIMAPO)
                   DATAONLY
                   CURSOR
                   RESP(WS-RESP)
    END-EXEC.

MAPONLY: Send Attributes Without Data

Use MAPONLY to send the map's static structure (labels, field definitions, attribute bytes) without sending any data values. This is useful for initialising a screen to its base state when data fields will be populated separately:

cobol

EXEC CICS SEND MAP('EMPIMAP')
               MAPSET('EMPIMAPS')
               MAPONLY
               ERASE
               RESP(WS-RESP)
END-EXEC.

SEND MAP Options Reference

Option	Purpose
MAP	Map name (1-7 chars, matches DFHMDI macro name)
MAPSET	Mapset name (1-8 chars, matches DFHMSD macro name)
FROM	Symbolic output map area in WORKING-STORAGE
ERASE	Erase full screen before write
DATAONLY	Send data fields only (no attributes or labels)
MAPONLY	Send attributes/labels only (no data)
CURSOR	Position cursor; use with IC attribute or CURSOR(n)
CURSOR(n)	Position cursor at absolute screen offset n
ALARM	Sound terminal audible alarm
FREEKB	Unlock keyboard after send
ACCUM	Accumulate (add) to a larger screen — for multi-map screens
PAGING	Use CICS-managed page overflow for large output
LAST	Mark this as the last page in a PAGING sequence
TERMINAL	Send to the current terminal (default)
RESP	Capture response code

EXEC CICS RECEIVE MAP: Reading User Input

RECEIVE MAP reads data that the user has typed into unprotected fields, along with the AID key pressed, from the terminal buffer:

cobol

RECEIVE-USER-INPUT.
    EXEC CICS RECEIVE MAP('EMPIMAP')
                      MAPSET('EMPIMAPS')
                      INTO(EMPIMAPI)
                      RESP(WS-RESP)
                      RESP2(WS-RESP2)
    END-EXEC

    IF WS-RESP NOT = DFHRESP(NORMAL)
        PERFORM HANDLE-RECEIVE-ERROR
        GO TO END-RECEIVE
    END-IF

    *── AID key is now in EIBAID ─────────────────────────────────
    EVALUATE TRUE
        WHEN EIBAID = DFHENTER
            PERFORM PROCESS-ENTER-INPUT
        WHEN EIBAID = DFHPF3
            PERFORM RETURN-TO-MENU
        WHEN OTHER
            MOVE 'INVALID KEY' TO MSGO
    END-EVALUATE.

END-RECEIVE.
    EXIT.

Only fields that the user actually modified (fields with the Modified Data Tag — MDT — set) are returned in the terminal data stream. Fields the user did not touch contain low-values (X'00') in the input map. Always check the length field (e.g., EMPNOL) or test for LOW-VALUES before using input field data.

EXEC CICS RECEIVE: Low-Level Terminal Read

RECEIVE (without MAP) reads raw data from the terminal into a data area, without using BMS map formatting. This is used for special-purpose programs that receive non-BMS data:

cobol

WORKING-STORAGE SECTION.
01  WS-RAW-DATA   PIC X(1920).
01  WS-DATA-LEN   PIC S9(4) COMP VALUE +1920.
01  WS-AID-KEY    PIC X.

PROCEDURE DIVISION.
    EXEC CICS RECEIVE INTO(WS-RAW-DATA)
                      LENGTH(WS-DATA-LEN)
                      ASIS
                      RESP(WS-RESP)
    END-EXEC.

The ASIS option tells CICS not to translate the incoming data stream — it arrives exactly as the terminal sent it, including 3270 control characters.

EXEC CICS SEND TEXT: Unstructured Text Output

SEND TEXT sends text to the terminal formatted as a free-form text stream rather than a BMS-defined map. CICS handles line wrapping, paging, and headers automatically based on terminal line width:

cobol

WORKING-STORAGE SECTION.
01  WS-TEXT-AREA.
    05  FILLER PIC X(60) VALUE 'EMPLOYEE LISTING REPORT'.
    05  FILLER PIC X(60) VALUE '========================'.
    05  WS-TEXT-LINE PIC X(60) VALUE SPACES.

PROCEDURE DIVISION.
    MOVE 'JOHN DOE       DEPT A001   SALARY 75000' TO WS-TEXT-LINE

    EXEC CICS SEND TEXT FROM(WS-TEXT-AREA)
                        LENGTH(LENGTH OF WS-TEXT-AREA)
                        ERASE
                        RESP(WS-RESP)
    END-EXEC.

SEND TEXT is appropriate for:

Printed reports displayed on screen
Help text pages
Dynamic content where BMS map layout is too rigid
Multi-page output using CICS automatic paging

EXEC CICS SEND CONTROL: Terminal Control Without Data

SEND CONTROL sends control functions to the terminal without any data — for example, to erase the screen, unlock the keyboard, or sound the alarm:

cobol

*── Erase the screen and unlock the keyboard ─────────────────────
EXEC CICS SEND CONTROL
               ERASE
               FREEKB
               RESP(WS-RESP)
END-EXEC.

*── Sound alarm without sending any new data ─────────────────────
EXEC CICS SEND CONTROL
               ALARM
               RESP(WS-RESP)
END-EXEC.

SEND CONTROL is efficient for clearing the screen between map displays or resetting the keyboard state without re-sending an entire map.

Colour and Extended Attributes on 3270 Screens

Modern 3270 terminals (3279-S2B and later) and terminal emulators support extended attributes including colour. These are set in BMS DFHMDF macros using the COLOR parameter or via extended attribute bytes at runtime:

assembler

*── BMS macro with colour ────────────────────────────────────────
EMPNO    DFHMDF POS=(5,19),
               ATTRB=(UNPROT,NORM,IC),
               LENGTH=6,
               COLOR=YELLOW,
               HILIGHT=UNDERLINE

In COBOL, extended attributes can be set via the DFHBMSCA copybook constants for extended highlighting and colour. The exact approach depends on the CICS release and terminal capabilities.

Multi-Page Output with CICS Paging

For reports that exceed one screen, CICS provides automatic paging support. Programs use ACCUM to build pages and LAST to signal the final page. Users navigate with PA1/PA2 keys:

cobol

*── First page ────────────────────────────────────────────────────
EXEC CICS SEND MAP('RPTMAP1')
               MAPSET('RPTMAPS')
               FROM(RPTMAP1O)
               ACCUM
               PAGING
               ERASE
               RESP(WS-RESP)
END-EXEC.

*── Middle pages ──────────────────────────────────────────────────
EXEC CICS SEND MAP('RPTMAP1')
               MAPSET('RPTMAPS')
               FROM(RPTMAP1O)
               ACCUM
               PAGING
               RESP(WS-RESP)
END-EXEC.

*── Final page ────────────────────────────────────────────────────
EXEC CICS SEND MAP('RPTMAP1')
               MAPSET('RPTMAPS')
               FROM(RPTMAP1O)
               ACCUM
               PAGING
               LAST
               RESP(WS-RESP)
END-EXEC.

The accumulated pages are held in CICS temporary storage. The user's PA1 key advances to the next page; PA2 goes back. This is the standard mechanism for transaction-generated reports in a 3270 environment.

Common SEND/RECEIVE Mistakes

Mistake 1: Using ERASE on every SEND MAP. Using ERASE on re-displays wastes bandwidth by re-transmitting all static labels and attribute bytes. Use ERASE only on first display; use DATAONLY on re-displays.

Mistake 2: Not initialising output map fields before SEND MAP. If WS-EMP-NAME from a previous search is still in EMPNAMEO and you send a new map without clearing it, stale data appears on screen. Always INITIALIZE or MOVE SPACES to the output map structure before populating it.

Mistake 3: Checking field values instead of EIBAID for key identification. Some developers check whether EMPNOI contains data to determine what the user did. The correct approach is to check EIBAID first — it unambiguously identifies the AID key pressed, independent of which fields were modified.

Mistake 4: Issuing RECEIVE MAP in a first-entry invocation. On first entry (EIBCALEN = 0), there is no data in the terminal buffer to receive. Issuing RECEIVE MAP returns MAPFAIL or unexpected data. Always send the initial map first, then return — only issue RECEIVE MAP on re-entry.

Key Takeaways

CICS terminal I/O revolves around SEND MAP and RECEIVE MAP for structured BMS-based screens, with SEND TEXT, SEND CONTROL, and raw RECEIVE available for special cases. The ERASE vs DATAONLY choice on SEND MAP is a performance consideration — ERASE on first display, DATAONLY on re-displays. Always check EIBAID immediately after RECEIVE MAP to determine what AID key the user pressed before reading field data. For paged reports, ACCUM and PAGING options let CICS manage multi-screen output transparently.

For understanding how to handle errors and exceptions in CICS programs, continue with CICS Error Handling. For the complete CICS reference, visit the CICS Mastery Course.