Explore XML Processing Capabilities of the IBM Enterprise COBOL Compiler

Application Lifecycle Management with Enterprise COBOL Compilers V4 R2 for System z

By: Tom Ross

Level: Introductory

April, 2010

Using XML and MSGEXIT feature of IBM Enterprise COBOL Compiler V4R2, of 25

Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.

Contents

About this series ...................................................................................................... 3

About this Tutorial ................................................................................................... 3

Objectives .............................................................................................................. 3

Prerequisites ........................................................................................................... 3

System Requirements............................................................................................... 3

Glossary ................................................................................................................. 3

Use XML and Message Exit features of COBOL version 4 release 2................................... 5 Setup user environment.............................................................................................................................................6 Use XML PARSE to retrieve data from XML document .........................................................................................12 Use Message Exit to suppress known and annoying warning messages.................................................................20

Conclusion ............................................................................................................ 25

Trademarks........................................................................................................... 25

Resources............................................................................................................. 25



Before you start

About this series

Walk through this scenario and others online as part of the Enterprise Modernization sandbox for System z

About this Tutorial

This tutorial teaches you how to use new XML and Message Exit features of IBM® Enterprise COBOL compiler version 4 release 2.

Objectives

• Use XML features of Enterprise COBOL compiler to read values from XML document. • Use Message Exit feature of Enterprise COBOL compiler to suppress compiler

messages. • Use underscore in user-defined words and use an intrinsic function • Total time: 30 minutes

Prerequisites

• Basic IDE skills • Basic knowledge of the System z • Basic COBOL and XML knowledge

System Requirements

http://www-01.ibm.com/software/awdtools/cobol/zos/sysreq/

Glossary

Enterprise COBOL Compiler Version 4 Release 2: IBM Enterprise COBOL for z/OS®, Version 4 Release 2 helps you create, maintain and modernize business-critical COBOL applications on z/OS systems. Enabling the integration of COBOL applications with Web services, XML, and Java; Delivers enhanced XML parsing support; Facilitates compiler message severity customization; Exploits system-determined block size for QSAM files, using the BLOCK0 compiler option; Supports the underscore (_) character in COBOL user-defined words; Provides compiler listings that display CICS® options in effect; Supports Java 5 and Java 6 SDKs for Java interoperability. Rational developer for System z (RDz): Consists of a common workbench and an integrated set of tools that support end-to-end, model-based development, run-time testing, and rapid deployment of simple and complex applications. It offers an integrated development environment (IDE) with advanced, easy-to-use tools and features to help



WebSphere, CICS, and IMS developers rapidly design, code, and deploy complex applications.



Getting Started

Use XML and Message Exit features of COBOL version 4 release 2

You will use Rational Developer for System z (RDz), to modify JCL and COBOL application source code. First, you will use a local JCL stored on windows to copy the source file from a repository to your work location (datasets). 1. Launch Rational Developer for System z by clicking on the RDz icon on the desktop

(See Figure 1)

Take the default workspace location when RDz prompts to select the workspace location. (See Figure 2)

Figure 1 RDz icon on the Desktop

Figure 2 Select a Workspace

2. Check important RDz components and views that we will use.

Rational Developer for System z is an IDE that is based on the popular Eclispse based workbench and includes easy to use tooling to developers create, maintain, test and deploy COBOL, Batch, IMS™, WebSphere®, CICS®, and DB2® applications.



The following is the typical RDz environment for a mainframe developer. On the right, is the Remote System Explorer, which provides a tool to access remote hosts. (See Figure 3)

On the bottom panel, there is a z/OS File System Mapping view, which is used to map z/OS artifacts for extension and transfer. Notice the gray area in the center. This is the place where editors will show contents of programs, XML, JOB output document etc for viewing and editing.

Figure 3 Rational Developer for System z IDE

RDz is a very powerful IDE and has lot of options. However for our tutorial of COBOL compiler features we would be using only “Remote System Explorer” and “z/OS File System Mapping”. If you prefer then you may close the rest of the views.

Setup user environment 3. Switch off RDz context sensitive COBOL syntax analysis. RDz has an ability to

dynamically look at the source code and prompt incorrect syntax in side an editor window. This is a very important and helpful feature for productivity. However, for this tutorial it is not required and some of the syntax used in the tutorial code is too new for RDz to correctly analyze mistakes.

In the z/OS File System Mapping view double click on row or line starting with **COBOL (See Figure 4).

Figure 3 z/OS File System Mapping



On the Pop window change Workstation File Extension to Default(undefined) and click the ok button. (See Figure 4) Incase z/OS File System Mapping view is blank then you should close that view by clicking x on the view tab as shown in the figure 3.1

Figure 3.1 Close z/OS File System Mapping

Reopen the z/OS File System Mapping view by selecting Main menu Windows->Show View->z/OS File System Mapping option. See Figure 3.2

Figure 3.2 Close z/OS File System Mapping



Figure 4 Edit Data Set Mapping

4. Refresh tutorial source code from repository location. It is important that you complete

this step even if you see demonstration source code in your datasets.

In Remote System view click on sign of Local, Local Files, Drives, C:\ and then on COBOLCompilerSandbox to expand lists and find REFRESH.jcl. (See Figure 5)

Figure 5 Find REFRESH.jcl

Double click REFRESH.jcl to open in an editor and press Ctrl+F to use Find/replace or select Edit->Find/Replace menu option from main menu. (See Figure 6)

Figure 6 Edit REFRESH.jcl



Enter EM4Z14 in Find text box and enter your dataset qualifier name in Replace text box. This document assumes EM4Z14 as dataset qualifier, yours may differ. To find your dataset qualifier, please see My Data Sets in Remote System explorer. (See Figure 7)

Figure 7 Find Dataset qualifier

Replace all EM4Z14 with your dataset qualifier (EM4Z14 is used in this document) in REFRESH.jcl. (See Figure 8)



Figure 8 Replace Dataset qualifiers

Save REFRESH.jcl file by clicking save button on the tool bar of RDz. (See Figure 9)

Figure 9 Save REFRESH.jcl

Right click on editor window and select Submit to zserveros.demos.ibm.com by clicking on the menu item. (See Figure 10)

Figure 10 Submit REFRESH.jcl



On successful submission of the job you will be presented with dialog box. See Figure 10.1. Click ok on this dialog box.

Figure 10.1 Submit REFRESH.jcl

5. Modify demonstration JCL with your dataset qualifiers Look at Remote System view and open MYEXIT.jcl and RUNIT.jcl by double clicking on them under EM4Z14.POT.JCL dataset (In your case replace EM4Z14 with your dataset qualifier). (See Figure 11)

Figure 11 Submit REFRESH.jcl

Replace EMPOTXX with your dataset qualifier (In this document we use EM4Z14) (See Figure 12) in both MYEXIT.jcl and RUNIT.jcl. Save both files. Hint: To use Find/Replace press Ctrl+F keys or select from Edit->Find/Replace menu option.

Figure 12 Replace EMPOTXX in MYEXIT.jcl and RUNIT.jcl



Use XML PARSE to retrieve data from XML document 6. Double click to view the XML document in EM4Z14.POT.COBOL dataset. (See Figure 13)

Figure 13 XML document

Notice the XML document structure as it contains attributes and sub elements.

7. Double click on PARSEIT in EM4Z14.POT.COBOL dataset. (See Figure 14) Figure 14 PARSEIT COBOL Program



Notice the structure inventory_info will receive the contents of the XML document after PARSE. Also Note the underscore ‘_’ in the file and variable names (XML_File, item_num and item_name). On Line 104 of the program notice the use of FUNCTION MOD to index into ‘hv’ of printable equivalents for hex values.

Notice the DD statement for XML input file XMLFILE and the DD for XML schema SCHEMADD on line 9 and 10 respectively. (See Figure 15). The XML schema DD SCHEMADD will be used later on in this demo.

Figure 15 DD’s in RUNIT.jcl

8. Run PARSEIT program by submitting RUNIT.jcl. (See Figure 16) Right click on the editor

window to popup a menu. Select submit option from the pop up menu. Figure 16 Submit RUNIT.jcl



On Remote Systems view right click on JES List. From the popup select Refresh option to reload output queue. (See Figure 17)

Figure 17 Refresh Job List

9. View the output of the PARSEIT program. Drill down the JES list on Remote Systems view to see My Jobs containing RUNIT:JOBxxxx where xxxx is time stamp. Double click on RUNIT:JOBxxxx to open to view the output. (See Figure 18)



Figure 18 View RUNIT job output

Notice the display of values in the structure inventory_info retrieved from the XML document. Also notice the Return code of 00.

10. Test if PARSE will detect an invalid item_number.

Double click on the XMl document dataset to edit it Change the value of the attribute itemNumber from 453-SR to 453-7R in the XML and save the XML document. (See Figure 19)

Figure 19 Edit XML document

Submit RUNIT.jcl to rerun the PARSEIT program (See Figure 20).

Figure 20 Submit RUNIT.jcl



Hint: See step 8 and 9. View the output of the PARSEIT program from this run (See Figure 21)


Notice the value of item_num is 453-7R and the return code is 00. The parse did not identify the invalid value in the attribute itemNumber.



11. Change the parse to a validating parse in the above program. Edit RUNIT.jcl to uncomment line 10 to allocate a schema file and save RUNIT.jcl. (See Figure 22) //GO.SCHEMADD DD DISP=SHR,DSNAME=EM4Z14.STKITMPG.SCHEMA

Figure 22 Edit RUNIT.jcl

Edit PARSIT COBOL program to uncomment Configuration Section entries and XML PARSE statement at line 4 and at line 41 respectively. Comment XML parse statement on line 40 and save PARSEIT program (See Figure 23 and 24)

Figure 23 Edit PARSEIT 1

Figure 24 Edit PARSIT 2

Submit RUNIT.jcl to rerun the PARSEIT program (See Figure 25).



Figure 25 Submit RUNIT.jcl

Hint: See step 8 and 9. View the output of the PARSEIT program from this run (See Figure 26)




otice the bad return code is 24 and reason =x ‘8890’.

tation t C:\COBOLCompilerSandbox\XML System Services Guide.pdf (See Figure 27)

Figure 27 XML System Services Guide

N Open XML System Service Guide, Appendix B: It is stored on the windows worksa

Search for reason code ‘8890’. (See Figure 28)

Figure 28 Reason Code in XML System Guide

disk at C:\COBOLCompilerSandbox\ COBOL Programming Guide.pdf (See

Figure 29)

Figure 29 COBOL Programming Guide

To understand this better open COBOL Programming Guide also stored on the windowsworkstation

earch for ‘pattern facet’. (See Figure 30) S



Figure 29 itemNumber facet

Notice the schema declaration of itemNumber and what the legal values can be.

r from 453-7R to 453-SR in XML document

Figure 30 Change itemNumber to 453-SR

Change the value of attribute itemNumbeand save the document. (See Figure 30)

Submit RUNIT.jcl to check if PARSIT reports a bad return code with the changed value

XML document.

int: See step 8, 9 and 10

2. Check of compiler return code for PARSEIT

sible

sing Message Exit it is possible to suppress this message to get a clean compilation.

in H

Use Message Exit to suppress known and annoying warning sme sages

1

Notice the Return code 4, around line 460 in the output of the last submitted RUNIT job (See Figure 31). This is from a compiler warning message being issued about a postruncation of value. This warning is analyzed and determined to not be a problem. U



Figure 31 Compiler Return Code

13. dit MYEXIT COBOL program to handle 3113 warning massage.

r). Press Ctrl+F to find clause When(3188) in YEXIT COBOL program (See Figure 32)

Figure 31 Find When Clause

E Double click on MYEXIT COBOL program in EM4Z14.POT.COBOL dataset. (Remember to replace EM4Z14 qualifier with your qualifieM



Add following statement above When(3188) statement (See Figure 32) and save the program. When(3113) Compute EXIT-USER-SEV = -1

Figure 32 Add When clause

Submit MYEXIT.jcl and check the return code around line 650. It should be 0. (See Figure 33)

Figure 33 Compiler Return Code



Hint: See steps 8, 9, and 10 on how to submit JCl and check its output.

14. Change RUNIT.jcl to take advantage of this message handling.

In RUNIT.jcl comment line 5 and uncomment line 6 to add the EXIT(MSGEXIT(MYEXIT)) compiler option following XREF(FULL) (See Figure 34) and save RUNIT.jcl

Figure 34 Find When Statement

Submit RUNIT.jcl. Hint: See steps 8 and 9 on how to submit JCL.



15. Check the RUNIT.jcl output for compiler message.

Notice no massage 3113, Return code is 0 and notice new line with “Messages suppressed by MSGEXIT: 1” (See Figure 35)

Figure 34 Compiler Return Code and suppressed message

This completes the task.

What you have learned In this exercise you learnt how to:

• Use XML PARSE in a COBOL program • Use XML schema to do a validating parse of an XML document • Use Message Exit features to suppress known but annoying warning messages from

the compiler. • Use RDz with COBOL compiler Version 4 Release 2.



Conclusion

This concludes the tutorial on using IBM Enterprise COBOL Compiler’s validating XML parse and Message Exit features. This tutorial has shown how to code COBOL programs to retrieve values from XML documents, use XML schema to do a validating parse of an XML document and use MSGEXIT to suppress unwanted messages from compiler.

Trademarks IBM and the IBM logo are trademarks of International Business Machines Corporation in the United States, other countries or both. Microsoft, Windows, Windows NT, and the Windows logo re trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product and service names may be trademarks or service marks of others.

Resources

What is new in Enterprise COBOL for z/OS, V4.2

http://www-949.ibm.com/software/rational/cafe/docs/DOC-3281

Learn:

http://www-01.ibm.com/software/awdtools/cobol/zos/library/

Get products and technologies:

http://www-142.ibm.com/software/dre/h2b/buildh2bpage.wss?synkey=S777668Z03634S44 Community: http://www-949.ibm.com/software/rational/cafe/community/cobol

Explore XML Processing Capabilities of the IBM Enterprise COBOL Compiler

Documents

Transcript of Explore XML Processing Capabilities of the IBM Enterprise COBOL Compiler