CICS Document Management

CICS document management covers how the system defines and handles documents: screen layouts (BMS maps), printed output (transient data and printers), and the configuration that ties programs to those resources. Programs use BMS to send and receive 3270 screens without hard-coding field positions; they use transient data and printer destinations to produce reports and printed documents. This page explains BMS map sets and maps, transient data queues, and how to produce document-style output from CICS transactions.

Explain Like I'm Five: What Is Document Management in CICS?

Think of CICS as an office. The "documents" are things people see or print: the forms on the screen (like a form you fill out) and the reports that come out of the printer. Document management is how the office decides what those forms look like (where the boxes and labels go) and where the printed pages go. The screen form is designed once (in BMS) and the program just says "put this value in that box" or "read what the user typed there." For printing, the program writes lines to a "destination" and CICS makes sure they end up on the right printer or file.

BMS: Basic Mapping Support and Screen Documents

BMS (Basic Mapping Support) is the CICS facility that separates screen layout from application logic. Instead of moving data to specific column and row positions in the program, you define a map: a set of fields with names, positions, lengths, and attributes. The map is built with BMS macros and assembled into a load module (a mapset). At run time the program receives a copy of the map (a symbolic map or physical map) and uses SEND MAP and RECEIVE MAP to display the screen and read user input. The "document" here is the screen layout itself—defined once, used by many transactions.

The Three BMS Macros: DFHMSD, DFHMDI, DFHMDF

BMS uses three macro types to define a mapset. DFHMSD (Map Set Definition) appears at the start and optionally at the end of the mapset. It defines the mapset name, the type of output (DSECT for symbolic map, MAP for physical map, or FINAL to end the mapset), the mode (IN for input-only fields, OUT for output-only, INOUT for both), the language (COBOL, PL/I, etc.), and control options such as FREEKB (unlock keyboard after send), FRSET (reset modified data tags), ALARM, and PRINT. TYPE=DSECT generates the copybook or structure your program uses; TYPE=MAP generates the physical map; TYPE=FINAL marks the end. LANG=COBOL (or equivalent) ensures the generated layout matches your program language.

DFHMDI (Map Definition Interface) defines one map within the mapset. Each map is one full screen. You specify the map name, the line and column of the map origin, and the size. All fields in this map are positioned relative to that origin. A mapset can contain multiple maps (e.g. a main menu map and several transaction-specific maps).

DFHMDF (Map Definition Field) defines a single field. You specify the line and column (relative to the map), the length, the initial value (literal or empty), and attributes. Attributes control protection (protected so the user cannot type, or unprotected for input), intensity (normal or bright), color, highlighting, and validation (e.g. numeric only). The program references the field by the name you give it in the macro. BMS generates a structure where each field has a value area and often a length and attribute area so the program can set or read the value and optionally change attributes before sending.

SEND MAP and RECEIVE MAP

After the mapset is assembled and the program is compiled with the generated copybook, the program uses EXEC CICS SEND MAP to display the screen and EXEC CICS RECEIVE MAP to read the user's input. SEND MAP sends the map (or a map from the mapset) to the terminal. You can send the whole map or only certain maps if the mapset has multiple. You specify MAP(mapset-name) MAPSET(mapset-name) and optionally ERASE to clear the screen first, or DATAONLY to send only the variable data (faster when layout is unchanged). The program moves data to the symbolic map fields before SEND MAP so the user sees the correct values.

RECEIVE MAP reads the screen content from the terminal into the symbolic map. The user has typed in unprotected fields; RECEIVE MAP brings that data into your program's map area. You then process the fields by name. You can check which fields were modified (if the map was built with modified data tags) to validate only what changed. After RECEIVE MAP, the map area contains the user input and you can validate and process it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
       *> Send the menu map with data
       MOVE 'Welcome' TO MENU-TITLE
       MOVE WS-USER-ID TO MENU-USER
       EXEC CICS SEND MAP('MENUMAP')
           MAPSET('MENUMAP')
           ERASE
           FREEKB
       END-EXEC
 
       *> Read user input
       EXEC CICS RECEIVE MAP('MENUMAP')
           MAPSET('MENUMAP')
           RESP(WS-RESP)
       END-EXEC
       IF WS-RESP NOT = DFHRESP(NORMAL)
           PERFORM INPUT-ERROR
       END-IF
       *> Process MENU-CHOICE and other fields from symbolic map

ERASE clears the screen before sending so you get a clean display. FREEKB unlocks the keyboard so the user can type. Always check the response (RESP) after RECEIVE MAP; conditions include NORMAL (success) and MAPFAIL (no data received, e.g. user pressed a key that did not send data).

Transient Data: Queues and Destinations

Transient data (TD) is used for sequential output (and sometimes input) to named destinations. A destination is defined in the CICS destination control table (DCT) and can be intrapartition or extrapartition. Intrapartition destinations are queues within the CICS region. Programs write records with WRITEQ TD and can read them back with READQ TD (if the queue type allows). This is useful for building a "document" (a list of lines or records) that another task or program will process, or for spooling report data. Extrapartition destinations send data outside CICS—to a dataset or to a printer. From the program's view you WRITEQ TD; CICS routes the data according to the destination definition. For printing, the destination is typically defined to point to a printer or a print dataset, so the program does not open files directly; it just writes to the queue and CICS handles the rest.

WRITEQ TD adds a record to the queue. You specify the queue (destination) name, the data (FROM area), and the length. Records are appended. For intrapartition queues you can read with READQ TD; for extrapartition (e.g. printer) you usually only write. Destinations can have attributes such as trigger level (to start a task when a certain number of records arrive) and retention (whether the queue is cleared after read or kept). Document-style reports are often produced by writing formatted lines to an extrapartition destination that is configured as a printer.

Document Printing in CICS

Printing in CICS is typically done by defining a transient data (or similar) destination that is associated with a printer or print dataset. The program issues WRITEQ TD (or the appropriate command for the release) to that destination; CICS routes the output to the correct device or file. Terminal definitions can also be used for printer devices: the "terminal" is a printer, and the program sends output to it. The exact mechanism depends on your CICS version and installation (e.g. JES-based printing, local printers, or MVS writer). From an application perspective, you format your document (headers, lines, footers) in a buffer and write it to the destination; the system handles the physical print. Some installations use temporary storage or other facilities to stage report data before it is printed. Document management here means ensuring the right data goes to the right destination and that the format (line length, control characters for forms) matches what the printer or print file expects.

Document Definition Objects (DDO) and Resource Definitions

In some CICS documentation, "document" or "document definition" refers to resource definitions that describe how a document (screen or print output) is structured or routed. BMS mapsets are one kind of definable resource: they are installed (e.g. from the CSD) so CICS knows the mapset name and can load the physical and symbolic maps. Terminal and destination definitions (for printers) are another. The Program Properties Table (PPT) lists the mapset as a resource so that when a program does SEND MAP MAPSET(name), CICS can find the mapset. The Destination Control Table (DCT) defines transient data destinations. Keeping these definitions consistent with your programs (correct mapset names, destination names, and printer associations) is part of document management at the system level.

Step-by-Step: Sending a BMS Map

1. Ensure the mapset is defined and installed (PPT entry for the mapset). Compile your program with the BMS-generated copybook so the symbolic map layout is available.
2. In working storage, move the data you want to display into the symbolic map fields (e.g. MENU-TITLE, MENU-USER). Do not change field positions in the copybook; only set the value and length if your copybook has length fields.
3. Issue EXEC CICS SEND MAP(map-name) MAPSET(mapset-name) ERASE FREEKB (and other options as needed). ERASE clears the screen; FREEKB unlocks the keyboard. Omit ERASE if you want to overlay on the current screen.
4. Check the response if you specified RESP. On success, the user sees the map. The transaction may then RECEIVE MAP to get input or link to another program.

Step-by-Step: Producing a Printed Document via Transient Data

1. Identify the transient data destination name that is configured for your printer or report file (e.g. from the DCT). Use the name your system administrator provides.
2. Build the report line or document content in a working-storage or linkage section area. Format it according to the printer or file requirements (fixed length, control characters if needed).
3. Issue EXEC CICS WRITEQ TD QUEUE(destination-name) FROM(data-area) LENGTH(length) for each line or record. Repeat for all lines of the document.
4. CICS routes the data to the destination. For a printer destination, the output is printed or spooled. You do not need to close the queue; writing the last line completes your part. Optionally handle RESP for NOSPACE or other errors.

Best Practices

• Use BMS for all 3270 screens so layout changes do not require program changes. Keep map and mapset names consistent between the BMS source, PPT, and program.
• Always check RESP (or EIBRESP) after SEND MAP and RECEIVE MAP. Handle MAPFAIL and other conditions so the transaction does not assume data was received when it was not.
• For printed documents, use a single, well-defined transient data (or equivalent) destination per report type so routing and cleanup are predictable.
• Document which mapsets and destinations each transaction uses so operations and problem determination know what resources are involved.
• Use ERASE when you want a clean screen; use DATAONLY on SEND when only data changed to reduce data sent to the terminal.

Test Your Knowledge