A BMS output example

This example shows how BMS creates a formatted screen. It takes a list of data items from a program and displays them on the screen according to a predefined format.

BMS creates a formatted screen by merging variable data supplied by the program with constant data in the format (titles, labels for variable fields, default values for these fields). It builds the data stream for the terminal to which you are writing, to show this merged data in the designated screen positions, with the proper attributes (color, highlighting, and so on). You do not have to know anything about the data stream, and you do not need to know much about the format to write the required CICS® commands.

Note: For simplicity, this section is concerned with display screens, but most of it applies equally to printers. Printing and spool files discusses differences between displays and printers and covers additional considerations that apply to printing. Furthermore, the examples and discussion assume a standard 3270 terminal because BMS is designed to support the features of the 3270. Other terminals are discussed in Support for non-3270 terminals.

You define the formats, called maps, separately from the programs that use them. Allowing you to reposition fields, change their attributes, and change the constant text without modifying your programs. If you add or remove variable data, you need to change the programs which use the affected fields.

The basics of how this works are explained by an atypically simple example. In real life, requirements are always more complex, but this gives you the essentials without too much confusing detail. There are more realistic and complete BMS examples among the CICS sample applications. These programs are included in source form on the CICS distribution tape. More information can be found in the Sample Applications Guide.

This example assumes that you need to write the code for a transaction used in a department store that checks a customer's balance before a charge sale is completed. The transaction is called a “quick check”, because all it does is check that the customer's account is open and that the current purchase is permissible, given the state of the account. The program for the output part of this transaction gets an account number, and produces the screen shown in Figure 1 in response:

Figure 1. Normal “quick check” output screen

  QCK                      Quick Customer Account Check
  Account:    0000005
  Name:       Thompson        Chris
  Max charge: $500.00

The program uses the entered account number to retrieve the customer's record from the account file. From the information in this record, it completes the account number and customer name in the map, and computes the maximum charge allowed from the credit limit, outstanding balance, and purchases posted after the last billing period. If the amount comes out negative, you are supposed to show a value of zero and add an explanatory message. You also need to alert the clerk if the charge card is listed as lost, stolen, or canceled with a message as shown in Figure 2:

Figure 2. “Quick check” output screen with warning message

  QCK                      Quick Customer Account Check
  Account:    0000005
  Name:       Thompson        Chris
  Max charge:    $0.00
  STOLEN CARD - SECURITY NOTIFIED

This message is to be highlighted, to draw the clerk's attention to it.

You must first define the screen. We explain how to do so for this particular map in Creating the map. For the moment, however, let us assume that one of the outputs of this process is a data structure like the one in Figure 3. (We show the COBOL-coded version of the structure, because we are using COBOL to code our examples. However, BMS produces the structure in any language that CICS supports.) The map creation process stores this source code in a library from which you copy it into your program.

Figure 3. Symbolic map for “quick check”

01  QCKMAPO.
    02  FILLER PIC X(12).
    02  FILLER PICTURE X(2).
    02  ACCTNOA    PICTURE X.
    02  ACCTNOO  PIC X(7).
    02  FILLER PICTURE X(2).
    02  SURNAMEA    PICTURE X.
    02  SURNAMEO  PIC X(15).
    02  FILLER PICTURE X(2).
    02  FNAMEA    PICTURE X.
    02  FNAMEO  PIC X(10).
    02  FILLER PICTURE X(2).
    02  CHGA    PICTURE X.
    02  CHGO  PIC $,$$0.00
    02  FILLER PICTURE X(2).
    02  MSGA    PICTURE X.
    02  MSGO  PIC X(30).

The data names in this structure come from the map definition. You assign names to the fields that the program may have to change in any way. For our example, this category includes the fields where you display the account number, last name, first name, maximum charge, and explanatory message. It does not include any of the field labels or screen titles that never change, such as “Quick Customer Account Check” and “Account”.

Each field that you name on the screen generates several fields in the data structure, which are distinguished by a 1-character suffix added to the name you assigned in the map. Two appear here, the “A” suffix for the field attributes byte and the “O” suffix for the output data. If we were creating a map to use special device features like color and highlighting, or were using the map for input as well as output, there would be many more. We tell you about these other fields in Setting the display characteristics and Receiving mapped data.

The key fields for this particular exercise are the ones suffixed with “O”. These are where you put the data that you want displayed on the screen. You use the “A” subfields if you want to change how the data is displayed. In our example, we use MSGA to highlight the message if our customer is using a dubious card.

Here is an outline of the code that is needed for the example. You have to copy in the data structure (Figure 3) produced by creating the map, and the COPY QCKSET statement in the third line does this. (Ordinarily, you would use a copy statement for the account record format too. We show it partly expanded here so that you can see its contents.)

Figure 4. BMS output example

   WORKING-STORAGE SECTION.
C COPY IN SYMBOLIC MAP STRUCTURE.
  01  COPY QCKSET.
  01  ACCTFILE-RECORD.
      02  ACCTFILE-ACCTNO                  PIC S9(7).
      02  ACCTFILE-SURNAME                 PIC X(15).
      02  ACCTFILE-FNAME                   PIC X(10).
      02  ACCTFILE-CREDIT-LIM              PIC S9(7) COMP-3.
      02  ACCTFILE-UNPAID-BAL              PIC S9(7) COMP-3.
      02  ACCTFILE-CUR-CHGS                PIC S9(7) COMP-3.
      02  ACCTFILE-WARNCODE                PIC X.

   PROCEDURE DIVISION.

      EXEC CICS READ FILE (ACCT) INTO (ACCTFILE-RECORD) RIDFLD (CKNO)
              ... END-EXEC.
      MOVE ACCTFILE-ACCTNO TO ACCTNOO.
      MOVE ACCTFILE-SURNAME TO SURNAMEO.
      MOVE ACCTFILE-FNAME TO FNAMEO.
      COMPUTE CHGO = ACCTFILE-CREDIT-LIM - ACCTFILE-UNPAID-BAL
              - ACCTFILE-CUR-CHGS.
      IF CHGO < ZERO, MOVE ZERO TO CHGO
          MOVE 'OVER CHARGE LIMIT' TO MSGO.
      IF ACCTFILE-WARNCODE = 'S', MOVE DFHBMBRY TO MSGA
          MOVE 'STOLEN CARD - SECURITY NOTIFIED' TO MSGO
          EXEC CICS LINK PROGRAM('NTFYCOPS') END-EXEC.
      EXEC CICS SEND MAP ('QCKMAP') MAPSET ('QCKSET') END-EXEC.
      EXEC CICS RETURN END-EXEC.