In this module, we're going to look at how to code your application programs to in CICS. You've heard in your instruction that CICS is a mixed language application server that runs on IBM Z. As an application server, CICS hosts and provide services to application programs. In this type of environment, CICS manages resources on behalf of the application. This allows the application program not to concentrate on coding the business logic without having to think about specific characteristics of CICS resources. For example, CICS will open and close files so the COBOL program, doesn't need any file description entries in the file section of the COBOL program. So how does your program request access to CICS resources? Well, CICS provides an application programming interface, an API, which gives the application program access to CICS services. The API consists of several parts, including a command level programming language, commonly known as the EXEC CICS interface. This EXEC CICS interface passes requests for CICS services by an EXEC Infrastructure. The interface updates that Control Block who the EIB, the status of the current CICS requests being executed by the application. There's a CICS language translator, which turns the exact CICS commands into COBOL statements, they're then called the EXEC interface. We'll look in more detail what that translator does later. The EXEC CICS command is the bit that goes in your COBOL program. For each request to access CICS Resource, command must be coded in the application logic. The command starts with EXEC CICS, which is short for execute CICS. This EXEC CICS string tells the command level translator the API command has been found. Then there is the command itself. This determines the function being performed on the CICS resource. There are over 340 of these commands available. A complete list can be found in the Knowledge Center if you want to see what they all are. Then the command is followed by one or more options and their arguments. Then we finish the command with the string and EXEC. If we look in the Knowledge Center of what these commands are, we see a summary of each command. We see a schematic diagram which illustrates the syntax and a description of the command. We also see a list of the available options and their usage along with a list of the condition responses that can be returned by CICS for that command. Finally, an example of the command actually being used. The schematic diagrams, or you might hear them referred to as Railroad Diagrams, are essential to the application programmer. They explain exactly what can be specified on an EXEC CICS command. This may sound a bit daunting, but luckily, modern editors can supply context assists to help you when you're writing your code. To make sense of this schematic diagrams, you need to understand their conventions or their rules. The same rules apply to all commands and the rules can also be found in the Knowledge Center. Let's explain it by looking at a simple example using the payroll system application. Our program papers needs to redirect code from a file called Payroll. The key stored in a variable ws- key. The data is to be returned to a work in storage variable called Payroll Record. Looking at the schematic diagram for a read shows that options, "File" and "RID" field, which is the record key, are mandatory. Options "Into" or "Set" are alternatives, but you must provide one of them. The other options are optional. So based on this our code in a program looks like this, where EXEC CICS tells the translator their CICS command is starting. The command in this case would be read. You need three options containing arguments, file, we'll give it the file name, 'PAYROLL', RID filled, which we'll give the record key, ws-key, and INTO which is the location in your program and CICS will place the record, and this is going to be our payroll record. Then the command is terminated with the string and EXEC. The argument for file was hard coded with the string Payroll, which is why it's in quote marks. The other arguments ws-key and payroll record are variables in the working storage section of our COBOL program. In the program called PAYBUS, it looks like this. When this command executes the API pass three documents by the EXEC phase through to CICS. CICS service modulus will interactive with these and access the file and retrieve the records, sending the contents back to the program's working Storage field. But these executives' commands are not reserved words in COBOL or any other language. How can the compiler understand it? Remember that command level translator, we mentioned earlier. Well, it runs in conjunction with COBOL compiler. Either integrated with COBOL compiler or as a separate precompiled step. The translator converts the EXEC CICS API command in COBOL statements. Let's take a look at the translator outputs for read example. You can see that the EXEC CICS command is commented out and replaced by COBOL statements. These COBOL statements called the EXEC stub named DFHEI1, passing the COBOL option arguments Payroll ws-key and payroll record [inaudible]. The translator also copies, the EIB copybook, dfheiblk and dfhcommarea into the linkage section and the EIB copybook. Dfheiblk and dfhcommarea are in the Procedure Division Header after the using phrase. Based on this knowledge, we can update our flow diagram. When the COBOL program executes the EXEC CICS command, it links to the EXEC step, DFHEI1, using the code, placed in the program by the CICS translator. The step locates the EXEC interface programs and branches to them. The interface passes request into the CICS service module to access the record. On the return through the interface, the EIB is updated with the status of the command. Control is then passed back to our application. So with all that going on, how do we know if the command is successful? Return to your program, the response from CICS split across two EIB fields: EIB RESP and EIB RESP2. Response code in each field consists with two digits, decimal condition number. These response codes always so early when the Knowledge Center, we're told is what's response codes could be returned for a command. Given that you know the list of response codes that can be returned, your program should test these conditions after the EXEC CICS command completes for expected conditions. If the command was successful then the EIB RESP value will always contain zero, meaning normal condition. Then may be several reasons for Error condition in the EIP RESP. If so then EIP RESP2 is used to further qualify the condition. So how do you check the response code in your program? If you simply code RESP and RESP2 options on the command with working Storage variable as the argument. Then CICS, we'll place that you are the RESP and the RESP2 values in this working storage variables as the court returns. Storage variables, a C and a C 2 can then be tested using CICS built-in function DFHRESP with the condition as the argument. In this case, the program is testing for the NOT_FOUND condition. A built-in function is used in the program like DFHRESP, the translate will replace this with the correct DFHRESP equivalent. So DFHRESP if not found, we change to the condition number if not found, which is 13. We've looked at what is needed to run your application programs in CICS. Using the CICS API, your program has access to the many services that CICS can provide. But why would you want to use CICS access [inaudible] file? We've already mentioned that CICS is a powerful mixed language application server. CICS provides a secure, reliable, online environment, enabling high levels of concurrent access to files and databases. Ensuring integrity of these files by covering any in-flight errors back to the point of consistency. This explains why most Fortune 500 companies use CICS as the host for their mission critical applications.
