Unit 1: CICS Program Design

Taking the time to design your CICS programs is the key to creating programs that are easier to code, test, debug, and maintain. This unit starts by comparing the two major ways you can design an application program and explains how the theory of pseudo-conversational programming is the basis for both. Then, it gives you a recommended development procedure to follow and describes the various components that make up a complete set of program specifications. After that, it shows you how to use event/response charts and structure charts to plan the processing your programs will do based on user actions. And finally, it shows how a structure listing can be used to document the program design. Traditional program design vs. modular program design Today, there are two ways to design and code CICS programs, as shown in figures 1-1 and 1-2. Traditional program design describes the way CICS programs have typically been developed over the years, with the logic for presenting the user interface and the logic for processing user input all in a single program. So if youre maintaining older programs, youre almost certain to work with programs that are designed this way. You may also use this technique for new program development, depending on your shop standards and the types of programs youre creating. However, more and more programs are being developed using modular program design because that approach makes it possible to separate the business logic from the presentation logic in an application. That, in turn, allows you more flexibility when it comes to providing user interfaces for your applications, including using HTML and GUI frontends. Traditional program design

Traditional CICS programs consist of a single program module that handles both the interaction with the user at a terminal (the presentation logic) and the processing of data (the business logic). Both the presentation logic and the business logic are implemented using COBOL in conjunction with CICS commands, and the user interface is implemented using Basic Mapping Support (BMS). Although programs designed using this technique are easy to implement, they can only be run in a CICS environment. In addition, BMS doesnt provide all the features for creating user-friendly interfaces that are available in other languages.

Figure 1-1

Modular program design

Modular CICS programs separate the presentation logic from the business logic. With this technique, only the presentation logic can perform terminal I/O, and only the business logic can perform file I/O. Because the business logic is independent of the presentation logic, it can be used with presentation logic thats written in any language and that can run on any platform. In other words, you dont have to implement the presentation logic using COBOL and CICS and the user interface using BMS. Instead, you can use tools like Java or Visual Basic that allow you to create a user interface that handles the presentation logic itself. You can also create more than one user interface for the same business logic. For modular programs to work, the appropriate interface must be provided between the presentation and business logic. If the presentation logic is developed using COBOL/CICS, the interface with the business logic is implemented using a LINK command and the communication area. If the presentation logic is on a different platform or in another language, more sophisticated facilities are required. Separating the presentation and business logic facilitates the development of client/server and distributed applications and is critical to the development of web-based applications.

Figure 1-2 Pseudo-conversational programming Pseudo-conversational programming is a CICS programming technique that you should use for all your interactive programs. In a pseudo-conversational program, every SEND or SEND MAP command must be followed by a RETURN command. In other words, the program must end after it sends data to the terminal. On the RETURN command, the program specifies a trans-id so that when the user presses an attention key (such as the Enter key), the transaction is automatically restarted. Then, the program issues a RECEIVE or RECEIVE MAP command to receive the input data. The program can then process the data, issue another SEND or SEND MAP command, and end again. This is illustrated by the diagram in figure 1-3.

The advantage of pseudo-conversational programming is that the program doesnt sit idle while the user keys in data at the terminal. In contrast, a conversational program (one that doesnt terminate itself after it sends data to the terminal) sits idle while it waits for the user to enter input data. And thats inefficient because even though the program is idle, valuable CICS resources (such as main storage) are assigned to it. The drawback of pseudo-conversational programming is that it requires a different type of design and logic than what youre used to using in COBOL programming. Thats because a pseudo-conversational program must be able to figure out what to do each time its restarted. A pseudo-conversational program that knows what to do each time its restarted is one that can interpret the event that caused it to restart. It can then process a response thats appropriate for that event. For example, suppose a user presses the PF3 key in a program to exit to the main menu. In that case, the event is the user pressing the PF3 key, and the programs response is to issue an XCTL command to transfer control to the menu program. When you design a program using eventdriven program design, you identify each user input event that can trigger the execution of the pseudo-conversational program, and you design an appropriate response to each event. Pseudo-conversational processing

Figure 1-3 A program development procedure Figure 1-4 shows the preferred sequence for CICS program development. Although practical considerations may force a slightly different development sequence upon you, you should try to follow this sequence as closely as possible. At the least, you

should make sure you obtain a complete set of specifications before you design the program, and you should design the program before you code it.

Figure 1-4 To define the format of the screens that will be displayed by a program, you code a BMS mapset (see Units 9 and 10). To prepare a program for execution, you translate, compile, and link-edit it using IBM-supplied procedures (see Unit 3). The CICS resources that must be defined for most programs include the transid, the program itself, the mapset, and each file used by the program. To define these resources, you usually use an interactive facility called Resource Definition Online, or RDO (see Unit 12). At one time, resources like these were always referred to as table entries and were defined using special assembler macro instructions. As a result, youll see terms like File Control Table used in the CICS manuals and in some of the explanations of command options and error conditions given in Unit 8 in this book. Although coding and testing are shown as separate steps in this procedure, we recommend you use top-down coding and testing (or just top-down testing) to code and test your programs in phases (see Unit 4). The documentation for a program varies from shop to shop, so be sure to follow your shop standards. Program specifications

The first step in CICS program development is developing a complete set of program specifications. If you forge ahead with design and coding before you have a clear idea of what the program is supposed to do, youll pay for it later by having to redo your work. In some cases, you may be given a detailed set of program specifications developed by an analyst. In other cases, the specifications youre given may be quite sketchy. If thats the case, youll have to fill in the missing details yourself. At the minimum, your program specifications should include the items shown in figure 1-5: a program overview listing the input, output, and processing requirements of the program a screen layout for each map used by the program a listing of the COPY member for each file used by the program

In addition, the specifications may include decision tables, editing rules, and so on. Try to look beyond the obvious to make sure you have all the information you need to develop your program.

Figure 1-5 Event/response charts When you use event-driven program design for a pseudo-conversational program, you identify each user input event that can trigger the execution of the program, and then specify an appropriate program response. In most programs, the appropriate response to a particular event depends on the context in which that event occurs. For example, the maintenance programs response to the Enter key depends on whether the key map or the data map is displayed. And if the data map is displayed, the response depends on whether the user is adding, changing, or deleting a customer. Thus, there are four contexts for the customer maintenance program: (1) Get key, (2) Add customer, (3) Change customer, and (4) Delete customer. To design the programs response to each input event and context, you can create an event/response chart like the one shown in figure 1-6. As you can see, the leftmost column in this chart simply lists each input event that the program must respond to. Then, the second column lists the contexts that are significant for each event. For example, the program must respond differently to the Enter key for each context, but the context doesnt matter for the PF3 key. The third column summarizes the programs response to each event/context combination. Finally, the fourth column lists the new context that results from each response. For example, this program uses the PF12 key to cancel out of the current operation. So if the user presses PF12 when the context is Add customer, the program will set the context for the next program execution to Get key.

Keep in mind that an event/response chart like this is nothing more than a planning tool. As you gain experience developing CICS programs, youll find it unnecessary to include the amount of detail shown here. Also be aware that this is a design tool; its not meant to be maintained as part of the documentation for the final version of the program. An event/response chart for the customer maintenance program

Figure 1-6 Structure charts Regardless of whether youre designing a traditional or modular program, youll use your event/response chart to create a program structure chart like the one for the traditional maintenance program shown in figure 1-7. The structure chart, in turn, will serve as a basis for your program code. Each box on the structure chart represents one program module, which can be easily implemented as a single paragraph in your COBOL program. The COBOL paragraph for a module invokes the modules subordinate to it by issuing PERFORM statements.

A general procedure for designing the first two levels of a structure chart

Draw the top-level module and give it a name that represents the entire program. It manages the event processing specified in the event/response chart. Decide what event processing should be implemented as separate modules, and draw a box subordinate to the top-level module for each one.

How to determine what modules should make up the second level of a structure chart

If the programs response to an event includes receiving data from the terminal, processing it, and sending data back to the terminal, you should create a separate module for the event. If the programs response to an event doesnt include receiving data from the terminal, you should consider creating a separate module only if the response requires more than a few COBOL statements to implement. If the COBOL statements for implementing the top-level module require more than a page or two, you should consider creating additional second-level modules to simplify the coding in the top-level module. Note The design that results from following these guidelines will vary from program to program depending on whether youre designing a traditional or modular program. Some programs will have second-level modules that correspond to the programs contexts. Others will have modules that correspond to particular function keys. Still others will have a combination of the two. Later in this unit, youll find some additional guidelines for designing modular programs.

The structure chart for the customer maintenance program (traditional design)

Figure 1-7

A general procedure for designing one leg of a structure chart

Draw one subordinate module (or called module) for each function that the control module (or calling module) at the top of the leg needs to do. To process the key map, for example, the process-key-map module needs to receive the key map, edit the data in the map, send the customer map if the entry is valid, and resend the key map if the entry is invalid. Use the same thought process for the next level of modules. If any of them require more than one function, draw one subordinate module for each function. Continue this process as needed until each of the lowest-level modules consists of just one function.

Guidelines for designing the legs of a structure chart

Each module should represent one and only one function. The function of a called module must be logically contained in the function of its calling module. The code in each module should be manageable. Use a generalized send module for each map. Each module will contain one or more SEND MAP commands with various options, such as ERASE, DATAONLY, and ALARM. The send module can decide which SEND MAP command to use by evaluating a flag thats set by the calling module. Include a separate module for each file I/O statement so the statements are easy to locate and modify.

How to identify common modules and linked or called programs

To identify a common module that appears more than once in a structure chart, shade its upper right corner. If a common module has subordinate modules, you need to include them only once on the chart. To identify a linked program thats executed using the LINK command, add a module to the structure chart with a stripe at the top that gives the program name. You can use the same technique to identify a called program (a program thats executed using the COBOL Call statement).

How to number the modules in a structure chart

Use 000 or 0000 for the top-level module. Number the modules in the second level from left to right leaving large enough gaps for subordinate modules. After the first two levels, number the modules down each leg in appropriate increments. When you code the COBOL paragraph for each module later on, the paragraph name will be the module number followed by the module name.

Design variations for modular programs The specifications for a modular program will show that two programs have to be created: one for the presentation logic and one for the business logic. Keep in mind, though, that the presentation logic may be done in a different language by a different programmer. The specifications will also indicate when the presentation logic links to the business logic. You dont have to make any changes in the way you develop an event/response chart for a modular program. However, if you want to, you can use some type of notation to clarify which portion of the program should implement the responses. For example, you could include the character P after each portion of a response that will be handled by the presentation logic and the character B after each portion that will be handled by the business logic. The main trick in designing a modular program comes in creating the structure chart for each part of the program. At this point, you have to determine which processing belongs in which part. The guidelines that follow will help you with that, and youll see how theyre applied in the structure charts for the modular design of the customer maintenance program. Design considerations for the presentation logic The structure chart shown in figure 1-8 illustrates the functions that must be provided for in the presentation logic of a program. Because CICS programs are driven by user events, the presentation logic should contain the high-level logic for the program. The presentation logic can be referred to as the driver program since it drives the execution of the program. The presentation logic must determine what processing is done based on user input and the context in which its received. The presentation logic should handle all screen interactions with the user, so the structure chart will include send and receive modules. The presentation logic should handle preliminary editing of the input thats entered by the user. That includes making sure that required entries are made, that entries are numeric when required, and that a valid key has been pressed. The presentation logic should link to the business logic whenever business processing is required. This can be shown on the structure chart just like any linked program. The presentation logic should maintain a copy of any data it requires between executions in a pseudo-conversational session. It should also maintain a copy of any data thats required by the business logic between its executions. A set module like module 2300 in this figure is often used to set up the communication area so it can be passed to the business logic. The presentation logic should never include any file I/O statements. That means there are no read, write, rewrite, or delete modules.

The structure chart maintenance program

for

the

presentation

logic

of

the

customer

Figure 1-8 Design considerations for the business logic The structure chart shown in figure 1-9 illustrates the functions that must be provided for in the business logic of a program. The processing done by the business logic should be based on information sent to it by the presentation logic. The business logic should handle all file processing. The business logic should ensure that data integrity is maintained. The business logic should handle all editing of data that depends on business rules. That includes checking that a value falls within a particular range, making sure that a record with a corresponding key value does or does not exist, and making sure that related fields have values that agree with one another. The business logic should perform all calculations. The top-level module of the business logic program should represent the function indicated by the module in the presentation logic program that links to the business logic. In fact, we recommend you use the same name for both modules. The modules at the second level should represent the main functions of the business logic. In most cases, these functions will be directly related to the event processing identified by the modules at the second level of the presentation logic. A set module is usually used to format the information that needs to be sent back to the presentation logic. If the presentation logic is another CICS

program, a standard communication area is most likely used. But if the business logic program is communicating with an application outside of the CICS environment, alternate ways of sending the information may be used. This can include sending HTML and XML data strings back via an HTTP request. The business logic should never include any terminal I/O statements. That means there are no send or receive modules in the structure chart.

The structure chart for the business logic of the customer maintenance program

Figure 1-9 Structure listings If you have a tool that can create a structure listing from program source code, use it for final program documentation. That makes it easier to keep the programs documentation up-to-date. The structure listing in figure 1-10 is for the customer maintenance program that uses traditional design. A structure listing uses indentation to show the levels of the modules. The letter C in parentheses can be used to identify common modules. A structure listing can be used for design as well as for documentation. In fact, you can use the outline feature of any modern word processor to prepare a structure listing as a program design document in place of a structure chart.

A structure listing for the customer maintenance program

Figure 1-10