Creating Applications Using Java and Micro Focus COBOL

Transcription

1 Creating Applications Using Java and Micro Focus COBOL Part 3 - The Micro Focus Enterprise Server A demonstration application has been created to accompany this paper. This demonstration shows how Net Express 4.0, Enterprise Server and a J2EE Application Server can be used together to create a webbased application that uses Java technologies to handle the user interface processing and COBOL to handle the back-end processing. The demo can be found at [Note: The downloadable file is 1.8 MG] To install it, run CorgiTimesClassifieds.exe. Note that this application requires certain software to be already installed on your computer in order to run. Because set up configures many of the installed files based on the location of software on your system, it is highly recommended that you install this software before starting the installation of the example application. If the required software is not already installed, then set up will not be able to configure everything correctly. The following software is required: - Micro Focus Net Express 4.0 or later - The Interface Mapping Toolkit and Enterprise Server must be installed - Sun Java Development Kit (JDK) version 3.1 or later - Sun Java 2 Enterprise Edition (J2EE) SDK version or later Although this application should work with other application servers, because of differences in how application servers are configured, this application is only set up to work with the Sun J2EE Reference Implementation contained in the J2EE SDK. The Sun JDK and J2EE SDK can be downloaded from The Corgi Times Classifieds setup program installs a ReadmeFirst file on your system (ReadmeFirst.htm). This file contains instructions on additional configuration that needs to be done in order for the application to run.

2 Abstract This is the third in a series of papers that examine how Micro Focus products enable you to effectively use Java and COBOL together to develop new applications. The first two papers examined the capabilities provided by Micro Focus Net Express and Server Express. The introduction of Micro Focus Enterprise Server with Net Express 4.0 and Server Express 4.0 provides powerful new capabilities for using COBOL applications with Javabased application servers. This paper introduces Enterprise Server and shows how it can be used in a simple application.

3 Contents Introduction...1 What is Enterprise Server?...2 Why is the Enterprise Server Needed?...2 The Problems...2 In-Process or Out-of-Process...2 The Problem of Multiple Threads...3 Use of JNI in J2EE Applications is Undesirable...3 The Solution Enterprise Server...4 Developing Applications Using the Interface Mapping Toolkit...4 The Architecture of Enterprise Server...5 Using the Interface Mapping Toolkit An Example...7 Defining the Mappings Deploying the COBOL Program to Enterprise Server Enterprise Server Objects Listeners Request Handlers Services Implementation Packages The Generated Enterprise JavaBean Using the Enterprise JavaBean Further Reading Conclusion Appendix

4 Introduction This is the third in a series of papers that examine how Java and COBOL can be successfully used together to develop scalable, reliable applications for use in the enterprise. Java is not just a programming language, but an entire architecture for creating enterprise applications. Java 2 Enterprise Edition (J2EE) is becoming the mainstream enterprise application architecture. All of the leading J2EE application server vendors, including IBM with WebSphere, BEA with WebLogic and Oracle with Oracle9i Application Server are delivering solutions that can meet the largest customer s speed and scalability requirements and these application servers are increasingly being adopted by corporations to implement the applications that run their business. At the same time, much of the code that is running business today is written in COBOL and, rather than attempting to rewrite all of this code, there is increasing demand to reuse as much as possible in new applications. In addition, the programmers who know the internal workings of business today are likely to be COBOL programmers, so providing a way to utilize their experience is highly desirable. A logical choice is to adopt a solution that allows Java and COBOL technologies to work together to produce highly scalable, reliable enterprise applications. The first two papers in this series looked at the problems inherent in Java interfacing with other languages and the solutions offered by Micro Focus with previous versions of Net Express and Server Express. This paper introduces Micro Focus Enterprise Server and the Interface Mapping Toolkit provided with the latest release of Net Express. Some familiarity with Java and Enterprise JavaBeans is assumed. 1

5 What is Enterprise Server? Enterprise Server is provided with Net Express 4.0 and Server Express 4.0. It provides a managed environment for the execution of COBOL programs that are called from various Java technologies. It enables the creation of Web services and Enterprise JavaBeans (EJB) where the business logic is written in COBOL. This paper will only examine the support for Enterprise JavaBeans. Web services are a subject for another paper. Why is the Enterprise Server needed? The obvious question is why is Enterprise Server needed at all? The previous version of Net Express introduced powerful capabilities that enabled Java applications to directly call COBOL programs without having to deal with the intricacies of the Java Native Interface 1 (JNI). The first paper in this series discussed this support in detail and demonstrated how a simple Java-based graphical application could be written that calls a COBOL program to store and retrieve data from indexed-sequential files 2. However, the development of more complex applications introduces new problems to be solved. This section looks at those problems and examines what is needed to solve them. The Problems In-Process or Out-of-Process If you develop an application using the techniques described in paper one, the COBOL program will run in-process and the communication with the COBOL program is via JNI calls. This means that the COBOL code runs in the same process as the Java virtual machine that calls it. Although in-process calls execute quickly, if the COBOL program crashes for any reason, it may stop the Java application that called it as well. Obviously, in the case of a J2EE application server, which may be running many applications and serving a large number of users, this is not a desirable prospect. The solution to this is to run the COBOL program in a different process on the computer. This is called out-of-process execution. While calls to the COBOL program may be slightly slower because of the need to cross process boundaries, if the COBOL program crashes, only the process it is running in will be terminated and the calling process will be unaffected. So, for reliable systems, out-of-process execution of the COBOL code is highly desirable. In this scenario, a separate server process would load and call the COBOL code. The Java applications would 1 The Java Native Interface is a set of low-level API functions that enable non-java programs to be called from Java. 2 Creating Applications using Java and Micro Focus COBOL Part 1, 2

6 communicate with this server using standard Java cross-process communication mechanisms. The Problem of Multiple Threads More complex Java applications usually involve the use of multiple threads. Java was designed from the ground up with multi-threading in mind and the language makes the creation and control of multiple threads easy to do. Therefore, it is common for more complex Java applications to make extensive use of threads. This is particularly true in web-based applications running under a J2EE application server, which will use multiple threads to serve multiple users. In addition, to conserve resources, most application servers reuse threads. So, it is possible for the same instance of a COBOL program to be called from different threads. Both Net Express and Server Express enable a COBOL program to be run under the multi-threaded run-time system. The COBOL run-time system allocates working storage and other data areas on a per-thread basis. This means that when the COBOL program is first called in a particular thread, a new copy of working storage is allocated and associated with that thread. This works fine if the COBOL program is always called from the same thread. However, if it is called from different threads, different copies of working storage will be used in subsequent calls to the program. This is not an issue if the COBOL program is stateless, that is, it does not need to store any information between calls to the program. Such a program might be one that is called to just perform one particular calculation based on data passed to the program. However, if the program provides a number of functions that rely on data stored in working storage between calls, then this is a problem. Such programs are often known as stateful programs. Running the program out-of-process from a separate server program provides a means of solving this problem. The server can control the access to the COBOL program, ensuring that a particular instance of the COBOL program is always called from the same thread. Use of JNI in J2EE Applications is Undesirable The use of the JNI in an application does not conform to the J2EE specification. Therefore, the use of JNI in an application that is going to run under a J2EE application server is undesirable. In addition, the extra environment information that is needed (for example, the location of the native code modules) can be difficult to configure and some application server vendors explicity prevent the loading of native libraries without modification to the server configuration, so the use of a pure Java solution to invoking the COBOL program is desirable for many enterprises. 3

7 The Solution - Enterprise Server Hopefully, after reading the above section, it has become obvious that a solution that allows the COBOL program to be run out-of-process is desirable in many cases and necessary if you want to develop an application using J2EE technologies. The J2EE specification provides for a mechanism to achieve this. This is the J2EE Connector Architecture. The J2EE Connector Architecture provides a Java solution to the problem of connectivity between application servers and the many different non-java systems that an enterprise may want to utilize from their new Java-based systems. In order to use the J2EE Connector Architecture, a resource adapter is needed. The resource adapter plugs in to the application server, providing connectivity between the application server and the application that is being called and handling connection, transaction and security management. However, once you have a resource adapter, then you need something for the resource adapter to communicate with, which will be running the COBOL programs. This is where Enterprise Server enters the picture. A simplified view of Enterprise Server is that of a container in which multiple COBOL applications are executed, each in their own process. Each COBOL application is isolated from the other applications running under the Enterprise Server. Session and state management for the application is also provided by Enterprise Server. Enterprise Server and the Resource Adapters that plug into J2EE application servers are provided with Net Express 4.0 and Server Express 4.0. Note. Paper two in this series introduced an interim solution for running COBOL programs out of process. This was the COBOL Out-Of-Process Framework (COP Framework). Any application developed using the COP Framework will still run under the latest version of Net Express. In some cases, the COP Framework may still be desirable for developing applications since it does not require a J2EE application server that supports the Java Connector Architecture 3. Developing Applications Using the Interface Mapping Toolkit The J2EE specification provides an Application Programming Interface (API) that handles communication via a resource adapter with external resources such as Enterprise Server. This API is called the Common Client Interface (CCI). Note. This API should not be confused with the Common Communications Interface, a proprietary API created by Micro Focus, which is also abbreviated to CCI. The Common Communications Interface enables communication between COBOL applications developed using Micro Focus COBOL. All references to CCI in this paper will refer to the J2EE Common Client Interface. 3 Developing Applications using Java and Micro Focus COBOL, Part 2 The COP Framework, 4

8 The Java code needed to establish communication with the Enterprise Server via a resource adapter and handle the calls to the different COBOL programs is not trivial. Fortunately, Micro Focus now includes the Interface Mapping Toolkit in Net Express. The Interface Mapping Toolkit enables you to graphically define the relationship between Java variables and the linkage section definitions in the COBOL program. The Interface Mapping Toolkit will then automatically generate an EJB that handles all of the communication with the COBOL programs. This EJB is deployed under a J2EE application server and is used by Java applications that want to make use of the COBOL program. An example of using the Interface Mapping Toolkit will be seen later in this paper. A simplified view of the structure of an application that uses Enterprise Server can be seen in Figure 1. Fig 1 Application Structure. The Architecture of Enterprise Server An Enterprise Server consists of a number of components: The console daemon. This component starts immediately whenever an Enterprise Server is started. It is used to start all other processes in an Enterprise Server and detects when they terminate. It also records a log of all of the functions performed. The server manager. This retrieves the configuration information that defines the enterprise server and information about the services that run within it. The communications server. This receives incoming client requests and forwards them on to the appropriate service execution process. It also receives the output from the service execution process and sends it back to the clients. The requests can come from the following types of client: Clients requesting a Web service. The messages arrive as SOAP (Simple Object Access Protocol) messages. For more information on Web services and SOAP, refer to the paper Web Services and Micro Focus COBOL. The implementation of Web services is not covered further in this paper. 5

9 J2EE clients requiring the use of a COBOL application. Requests from J2EE clients arrive in a Micro Focus proprietary format. One or more service execution processes. A service execution process is a process that actually executes the COBOL program that handles the client request. Figure 2 shows how the different pieces fit together. Figure 2 Enterprise Server Architecture. The communications manager receives the client request upon arrival. When one of the service execution processes becomes available, it calls the application container, which is the COBOL run-time system adapted to operate in the Enterprise Server environment. The application container then calls a request handler to decode the received request. There is a Micro Focus request handler for each type of client request that Enterprise Server can handle. The request handler uses the predefined mapping information created by the Net Express Interface Mapping Toolkit to convert any parameters into the types defined in the COBOL linkage section and then calls the COBOL program. Once the COBOL program has finished execution, the application container calls the request handler to convert the returned values from the types defined in the linkage section into the format the client will understand, and then passes the results to the communications manager, which sends it back to the client. Later sections will look at how requests are handled in more detail. 6

10 Using the Interface Mapping Toolkit - An Example The best way to demonstrate the power of the Interface Mapping Toolkit is by means of an example. The first two papers introduced a simple example program to demonstrate the different mechanisms available for interface Java to COBOL. This paper continues with the same example. It is a very simple classified advertisement system for a newspaper called The Corgi Times that allows the user to view advertisements in the system and place new advertisements. For paper one, the user interface for this application was written with a graphical user interface using the Java Swing APIs. For this paper, the application has been changed to be a webbased application that is implemented using a J2EE application server. It uses Java Server Pages (JSP) to provide the user interface. The back-end processing code that retrieves and places advertisements is unchanged from the first paper. It is written in COBOL and is in the form of a simple, called COBOL program with the following entry points. GetCategories GetFirstAd GetNextAd GetDaysRemaining Returns an array containing the different categories of advertisement. Returns the first advertisement for a particular category. Returns the next advertisement in a particular category. Returns the number of days remaining for the last advertisement retrieved. PlaceAd Place a new advertisement. All data is stored in COBOL indexed-sequential files. The outline of the COBOL code for this program can be seen in Appendix 1. The following sections show how the Interface Mapping Toolkit included with Net Express can be used to generate an EJB that provides an interface to the COBOL program that can be used by other Java programs. The generated EJB will implement methods that correspond to the entry points in the COBOL program. The parameters to the generated methods and the results returned will be pure Java types. The generated implementation of the methods will handle all of the communication with the COBOL program running under Enterprise Server via the resource adapter. 7

11 Defining the Mappings The first task we need to achieve is to define the mappings for the interface from Java to COBOL. This is done using the Interface Mapping Toolkit. In this case, a mapping refers to how Java variables passed to a method in the EJB are converted to the parameters required by the COBOL program. For example, the COBOL entry point GetFirstAd takes the following parameters: return-status pic 9(8) comp-5 Output The returned status code category pic x(20) Input The category of the advertisement to be retrieved Ad Record Output Information about the retrieved advertisement Using the Interface Mapping Toolkit, this interface will be mapped to a Java method call in the EJB that takes a Java String as the category and returns an integer as the status code and a Java class encapsulating all of the information about the advertisement. The Interface Mapping Toolkit will generate the code for the method (and the rest of the EJB). In Figure 3, a Net Express project has been created for the COBOL program and the project has been built. This compiles and links the source code to create a dynamic link library called Classifieds.dll. This dynamic link library should be linked with the single-threaded run-time system. Note that this is different to techniques described in previous papers which used the multi-threaded run-time system. All COBOL programs deployed under Enterprise Server use the single-threaded run-time system. The dialog shown was displayed by selecting New from the File menu. You can see that in the new version of Net Express, a new entry has been added to the list Service Interface. 8

12 Figure 3 Creating a new interface mapping. If Service Interface is selected, the dialog box shown in Figure 4 is displayed. Figure 4 Selecting the type of mapping. This dialog enables you to select the type of interface you want to create. This wizard can also generate the interfaces needed to expose the COBOL program as a Web service or to expose it as a COM component for use on Windows platforms. However, for the purposes of this paper, we select Map COBOL as an EJB. The next few dialog boxes allow you to select which Net Express project to use, the COBOL program that you are generating a mapping for (in our case, we select Classifieds.cbl) and the name of the mapping (CorgiTimes is used in this example). 9

13 Figure 5 shows the next dialog box. Figure 5 Selection of Default Mapping. If you select the option Default Mapping, the Interface Mapping Toolkit will generate a default mapping for every entry point in your COBOL program. In many cases, this may be all you need. However, in this case, we select None to show how new mappings can be created manually. Once you finish with the wizard, the mapping window is displayed, as seen in Figure 6. Figure 6 An empty mapping window. 10

14 The best way to show how each of the panes in this window is used is to start to populate them. To do this, we select New from the Net Express Operation menu. The dialog box shown in Figure 7 is displayed. Figure 7 Creating a new operation. As you can see, the drop down list contains the names of all of the entry points in the COBOL program. In this case, we select GetFirstAd and enter GetFirstAd in the Operation Name field. This will be the name given to the corresponding method in the generated EJB. Once you click OK on this dialog, the left pane in the mapping window is populated with the COBOL definitions of the parameters for that entry parameter (see Figure 8). Figure 8 The COBOL parameters for the entry point. 11

15 In order to map any of the simple parameters on to the corresponding Java data types, all you need to do is drag the required parameter from the left pane to the Interface Fields pane. In Figure 9, the returned-status and category parameters have been mapped on to the most appropriate Java data types. Figure 9 Mapping simple types. The returned-status field, defined in COBOL as pic 9(8) is mapped on to an int in Java. The category field, defined as pic x(20), has been mapped on to a Java String. The default type selected can easily be changed by clicking on the appropriate Type field in the Interface Fields pane and selecting a new type from the list displayed. In most cases, the default type chosen by the Interface Mapping Toolkit will be the most appropriate. Note that the name of the returned-status field has been changed in the Interface Fields pane to returned_status to conform to Java variable naming rules. Again, if you want to change the default name generated, you can simply click on it and enter a new name. Now we turn our attention to the Ad parameter, which is a record structure used to return information about an advertisement. If the Ad parameter is simply dragged from the left pane to the Interface Fields pane, the Interface Mapper will create a separate Java variable for each field in the record structure. Although a valid approach, this is not the behavior we want, especially for large records. What would be much more desirable is for the Interface Mapping Toolkit to create a new Java class that corresponds to the COBOL record structure, so that all of the information about an advertisement can continue to be encapsulated in one variable. 12

16 We can achieve this by first dragging the Ad record to the Reusable Mappings pane. This will create a structure that appears to be the same as the record defined in the COBOL linkage section, but using Java data types and having names that conform to Java variable naming rules. This can be seen in Figure 10. Figure 10 A reusable mapping. The Reusable Mappings pane is used to hold the definitions that may be used in a number of different mappings. For example, the Ad record structure is passed as a parameter to the GetFirstAd, GetNextAd and PlaceAd entry points. Now we can drag the Ad structure from the Reusable Mappings pane to the Interface Fields pane and the structure will remain intact as seen in Figure 11. The Ad parameter is shown as having type Ad. When the EJB is generated, this means that the code for a class called Ad will be generated that encapsulates all of the data in the Ad COBOL record structure. 13

17 Figure 11 Using a reusable mapping. Finally, all we need to do for this entry point is change the Direction of the Interface Fields. By default, the Interface Mapper sets the Direction field to Input. In most COBOL programs, parameters are passed by reference and so can be used to pass data to the program and return data from the program. In this case, the Direction field would be set to I/O. However, if you know that some parameters are only used to pass values into the program or return values from the program, you can set the direction field to indicate the specific direction for certain types of field. The values are Input, Output or Input/Output. This will simplify the definition of the method generated in the EJB and make it obvious to other programmers who use the EJB, which values are needed for input and which are returned values. Note that Net Express does not support types that map on to COBOL records being defined as Output only. If one of the parameters to the COBOL program is a record structure and values are returned in that structure, the Direction field must be set to Input/Output. To change the direction, simply click on the corresponding Direction field and select the required direction. Figure 12 shows the final mapping for this entry point. The field returned_status has been defined as output only, category has been defined as input only and Ad has been defined as I/O (since, as noted earlier, all records must be defined as input/output). 14

18 Figure 12 the final mapping for GetFirstAd. 15

19 You may have noticed that there is one pane in the Interface Mapping Toolkit window that we did not use in this example. The Preset COBOL Values pane is used to define fixed values to be placed in a COBOL linkage section when the entry point is called. For example, you may have an entry point that takes a numeric parameter as a function code and performs different actions depending on the value of the function code. A value of 1 may indicate that a record is to be added to a file, a value of 2 may indicate that a record is to be deleted and so on. You can define different mappings for this entry point, where a meaningful name is given to the function. For example, you might define a mapping called AddRecord where you specify that the function code is set to 1 and a mapping called DeleteRecord where the function code is set to 2. Both of these mappings will cause the same COBOL entry point to be called, but with a different value in the function code. The mappings for the other entry points in the COBOL program are created in a similar manner to that used for GetFirstAd. Once all of the entry points have been mapped, the Mapping window can be closed. Figure 13 shows the Service Interfaces window, which displays all of the interfaces created for the project. Figure 13 The Service Interfaces Window. 16

20 Deploying the COBOL Program to Enterprise Server Now that the interface to the COBOL program has been mapped, the next step is to deploy it to Enterprise Server and generate the corresponding EJB. Before the COBOL program can be deployed, Enterprise Server must be started. Enterprise Server is controlled via a browser-based interface. This can be reached from the Net Express program group that was added to the Windows Start menu when Net Express was installed. For the Net Express program group select, Configuration->Enterprise Server Administration. This will start the Enterprise Server Administration utility as shown in Figure 14. Figure 14 Enterprise Server Administration. The Enterprise Server Administration utility will show all of the Enterprise Servers visible on your network. When Net Express is installed, an instance of Enterprise Server is installed that is given the name ESDEMO. This can be used to develop and test your applications. If Enterprise Server is currently stopped, then start it by clicking on the Start button. Now we can go back to Net Express to deploy the COBOL program for our application to Enterprise Server. First, we need to select which COBOL files are going to be deployed. In the Service Interfaces window, right click on the interface you want to deploy. In this case, it is CorgiTimes. One of the options on the menu is Settings. Select this and then select the Application Files tab. This is seen in Figure

21 Figure 15 Selecting the COBOL files to be deployed. By pressing Add files, the COBOL files to be deployed to Enterprise Server can be selected. In this example only the dynamic link library, Classifieds.dll, needs to be deployed. This window can then be closed. Finally, in the Service Interfaces window, right click on the CorgiTimes interface and select Deploy from the popup menu. A status window will then show the status of the deployment as seen in Figure

22 Figure 16 Deploying the application to Enterprise Server. The following sections look in detail at what happened when you deployed your application. Enterprise Server Objects If we look at the Enterprise Server Administration screen now, the Objects column now looks like Figure 17: Figure 17 Objects after deployment. If this is compared with the window before deployment, you can see that five services and five packages have been added. But what are these different objects? There are four different types of object. Listeners A listener is an object that listens on a port for particular requests for services. Request Handlers A request handler (referred to simply as Handler in the Enterprise Server Administration utility) receives client requests for access to a service, and translates the requests into a form that the application providing the business functionality can understand. The following request handlers are provided with Enterprise Server: MFRHSOAP handles requests that use SOAP (Simple Object Access Protocol). These are requests for Web services. They are coded in XML. MFRHBINP handles binary requests made by the Micro Focus resource adapter that works with the J2EE application server. Services A service provides access to specific business functionality. It specifies which listeners are to be used and which package is to be used to perform the business function. 19

23 Implementation Packages An implementation package (referred to simply as package in the Enterprise Administration utility) defines the application that provides the business functionality. It specifies the mappings to be used and the location of the COBOL code that will perform the function. Figure 18 shows how the different objects fit together: Figure 18 The different objects in Enterprise Server. When the application was deployed earlier, an implementation package and service was added for each mapping, which we created using the Interface Mapping Toolkit. As we defined five mappings, five services and five implementation packages were deployed. 20

24 The Generated Enterprise JavaBean As well as deploying the COBOL to the Enterprise Server, the Interface Mapping Toolkit also generates the EJB that will access the COBOL and the Java classes that represent each of the COBOL records. A method is generated for each of the interface mappings that accepts the Java parameters and calls the Enterprise Server to perform the parameter conversion and call the COBOL program. Upon return from the COBOL program, the Enterprise Server converts the parameters back to Java and passes them back to the method in the EJB. Because the code is regenerated each time a COBOL program is deployed, the implementation code in the EJB should not be modified. However, you will need to look at the interface generated in order to call it from your Java application. The Java files are generated in a sub-directory below the directory containing your project files. The following files are generated for this example: CorgiTimesHome.java CorgiTimes.java CorgiTimesBean.java CategoryArray.java Ad.java Contains the home interface for the EJB Contains the remote interface for the EJB Contains the implementation of the EJB Contains the implementation of the class that represents the CategoryArray record structure used by the call to GetCategories Contains the implementation of the class that represents the Ad record structure When the COBOL program is deployed to Enterprise Server, these Java files are created, compiled and packaged into an EJB jar file which can be included as part of your J2EE application. Using the Enterprise JavaBean The following is the remote interface generated for the COBOL program in this example: package com.microfocus.demo.corgitimes ; public interface CorgiTimes extends javax.ejb.ejbobject { public java.util.arraylist GetCategories( com.microfocus.demo.corgitimes.categoryarray p1) throws java.rmi.remoteexception, javax.ejb.ejbexception; public java.util.arraylist GetFirstAd( java.lang.string p1, com.microfocus.demo.corgitimes.ad p2) throws java.rmi.remoteexception, 21

25 javax.ejb.ejbexception; public java.util.arraylist GetNextAd( com.microfocus.demo.corgitimes.ad p1) throws java.rmi.remoteexception, javax.ejb.ejbexception; public int GetDaysRemaining() throws java.rmi.remoteexception, javax.ejb.ejbexception; public java.util.arraylist PlaceAd( com.microfocus.demo.corgitimes.ad p1) throws java.rmi.remoteexception, javax.ejb.ejbexception; } When the mapping for GetFirstAd was created earlier, it was defined as taking two input parameters, a String and a record structure, and returning two output parameters, an integer and a record structure (the record structure was defined as I/O). As you can see, the Java method GetFirstAd() takes two parameters, a String and a parameter defined as class Ad. However, the returned result is an ArrayList. The reason for this is that a Java method can only return one result. If more than one output results were defined in the mapping, the output results are returned in an ArrayList. The first element in the ArrayList corresponds to the first returned result; the second element corresponds to the second returned result and so on. Because the ArrayList holds references to Objects, any return result that is defined as one of the Java basic types will be returned as an object of the corresponding wrapper class. For example, a result defined as type int will be returned in an object of type Integer. This can be seen in the following code, which shows how the method GetFirstAd() could be called from a Java client that has established a connection to the EJB and stored the reference to the remote interface for the EJB in the variable corgitimes. // Create a new Ad record to pass to GetFirstAd and // initialize it to be an empty record. All String fields // must be initialized. The class created for Ad contains // methods to set and retrieve each field. Ad adrecord = new Ad(); adrecord.setadcategory(""); adrecord.setadtext(""); adrecord.setadcustomerphone(""); String requiredcategory = Antiques ; ArrayList results = corgitimes.getfirstad(requiredcategory, adrecord); // Get the status returned by the COBOL program returnstatus = ((Integer)results.get(0)).intValue(); if (returnstatus == 0) { // Get the Ad record returned 22

26 } adrecord = (Ad)results.get(1); If only one output result is returned, then it is returned from the method directly. This can be seen in the method GetDaysRemaining() which returns an int. For example: int daysremaining = corgitimes.getdaysremaining(); This is the only code that the Java programmer needs to write in order to make use of the COBOL application. This code can be included in a JavaBean that can be called from a Java Server Page or any Java application to obtain information from the COBOL program. Further Reading For further information on some of the technologies covered in this paper, the following links may be useful. General information on Java 2 Enterprise Edition Information about the J2EE Connector Architecture Information about the Enterprise JavaBeans specification 23

27 Conclusion This paper has introduced the problems involved in reusing COBOL programs in applications that use J2EE Application Servers. It has also shown how Micro Focus Enterprise Server and the Interface Mapping Toolkit provide a powerful solution to these problems. Enterprise Server provides a scalable, easy to administer environment for executing COBOL programs in a different process to the J2EE Application Server. The Interface Mapping Toolkit provides an easy to use and powerful capability for automating the complex connectivity code required. This paper has only touched the surface of the capabilities of Enterprise Server. Enterprise Server provides full transactional capabilities and the Interface Mapping Toolkit can generate transactional Enterprise JavaBeans. In addition, Enterprise Server supports the deployment of COBOL web services without requiring any other software. For more information on these features, refer to the Enterprise Server documentation or other white papers from Micro Focus. About the author: Wayne Rippin is a self-employed consultant. Previously, he worked for Micro Focus for 16 years, first as a systems programmer and later as a product manager. His most recent role there was director of product management, leading a team of product managers responsible for Net Express, Mainframe Express and UNIX compiler products. 24

28 Appendix 1 The outline of the COBOL program used as an example in this paper, showing the linkage section and entry points. program-id. Classifieds. Environment Division. Input-Output Section. File-Control. select AdFile assign to external AdFile organization is indexed access mode is dynamic record key is AR-Key file status is AR-File-Status. select AdCategories assign to external AdCategories organization is indexed access mode is dynamic record key is CR-Category file status is CR-File-Status. Data Division. File Section. FD AdFile. 01 Ad-Record. 03 AR-Key. 05 AR-Category pic x(20). 05 AR-Index pic 9(4). 03 AR-Text pic x(200). 03 AR-Start-Date pic 9(8). 03 AR-Number-Of-Days pic AR-Customer-Phone pic x(20). FD AdCategories. 01 Category-Record. 03 CR-Category pic x(20). 03 CR-Count pic 9(4). working-storage section. 01 CR-File-Status. 03 CR-File-Status-1 pic x. 03 CR-File-Status-2 pic x. 03 CR-Binary-Status redefines CR-File-Status-2 pic 99 comp-x. 01 Category-Index pic 9(2) comp. 01 EOF-Reached pic 9(2) comp. 25

29 rest of working storage variables linkage section. 01 Category-Array. 03 Category-Rec occurs Category-Name pic x(20). 05 Category-Ad-Count pic 9(4). 01 Category-Count pic 9(2). 01 Category pic x(20). 01 Returned-Status pic 9(8) comp Status-OK value Status-Category-Exists value Status-Error-Writing value Status-No-Categories value Status-Error-Reading value Status-End-Of-Categories value Status-No-Ads value Status-End-Of-Ads value Ad. 03 Ad-Category pic x(20). 03 Ad-Index pic 9(4). 03 Ad-Text pic x(200). 03 Ad-Start-Date. 05 Ad-Start-Year pic 9(4). 05 Ad-Start-Month pic Ad-Start-Day pic Ad-Number-Of-Days pic Ad-Customer-Phone pic x(20). 01 Days-Remaining pic 99. procedure division. * This is just used to load the program. * The real work is done by the various entry * points exit program. GetCategories section. entry "GetCategories" using Returned-Status Category-Array Category-Count. set Status-Ok to true open input AdCategories if CR-File-Status-1 not = "0" set Status-No-Categories to true move 0 to Category-Count else move 0 to EOF-Reached 26

30 move 1 to Category-Index perform until EOF-Reached = 1 read AdCategories next at end move 1 to EOF-Reached not at end move Category-Record to Category-Rec(CategoryIndex) end-read if EOF-Reached = 0 add 1 to Category-Index end-if end-perform move Category-Index to Category-Count subtract 1 from Category-Count end-if close AdCategories exit program. GetFirstAd section. entry "GetFirstAd" using Returned-Status Category Ad. * Logic to get the first ad exit program. GetNextAd section. entry "GetNextAd" using Returned-Status Ad. * Logic to get the next ad exit program. GetDaysRemaining section. entry "GetDaysRemaining" using Days-Remaining. * Logic to retrieve the number of days * remaining for the last ad retrieved exit program. PlaceAd section. entry "PlaceAd" using Returned-Status Ad. * Logic to place a new ad exit program. 27

31 Micro Focus Micro Focus is the fastest, most effective way to migrate, extend, develop and deploy enterprise applications. As the industry standard for COBOL, Micro Focus enables organizations to maximize ROI while reducing development costs for accelerated business success. Founded in 1976, Micro Focus is a global company with principal offices in the United Kingdom, United States and Japan. For more information, visit Micro Focus Worldwide Austria Australia Belgium Canada Ontario Quebec France Germany Ireland Italy Japan Luxembourg Netherlands Norway Switzerland Sweden United Kingdom United States Other Countries Micro Focus. All Rights Reserved. Micro Focus and Net Express are registered trademarks, and Server Express is a trademark of Micro Focus. Other trademarks are the property of their respective owners. WPJAEE0503-US 28