How toThis chapter explains the Interface Mapping Toolkit, the principal set of tools in your COBOL development system for developing services - that is, COM Objects, Java interfaces and Web services.
The Interface Mapping Toolkit enables you to take an existing COBOL application, and deploy it as a service - that is, a software component that can be kept loaded ready to be invoked by a separately written client application. The main thing you need to do is create a new interface that can be invoked through one of the established mechanisms used for such components. These mechanisms are COM, Java interfaces and Web Services. You need to define how this new interface maps onto the parameters of your existing program.
You can also use the Interface Mapping Toolkit to extend CICS applications. For more information, see the chapter The Interface Mapping Toolkit in your Extending CICS Applications book.
In many cases, the program to be turned into a service has formed part of an application in production use for many years. Therefore we often refer to it as the legacy program. However, there is no reason why it should not be a new program especially written to be the basis of the new service.
The main elements in the Toolkit are:
To access the tools in the Toolkit, you need the Service Interfaces window open.
There is also a command line interface to the Interface Mapping Toolkit. It is called imtkmake, and it is documented fully in the topic imtkmake. We give a brief overview here.
It has the following functions:
| -defmap | Create a default mapping |
| -generate | Generate the deployment package (.car file) |
| -query | List the enterprise servers available for deployment |
| -deploy | Deploy the package to an enterprise server |
| -showlog | Display the deployment log file |
| -genclient | Generate a COBOL client from the mapping |
| -genclientwsdl | Generate a COBOL client from a WSDL file |
| -help | Display information about the functions |
These can be used together or in separate commands. For example, to create a Web service called myservice with default mapping, from the program program.cbl, use:
imtkmake -defmap src=program.cbl service=myservice
type=webservice
Then, to generate the deployment package, use:
imtkmake -generate service=myservice type=webservice
Then, to deploy it to the enterprise server ESDEMO, use:
imtkmake -deploy carname=myservice.car server=ESDEMO,Deployer
You store the files created by the Interface Mapping Toolkit, containing the definition of the new interface and the mapping, in a repository. In practice the terms "interface" and "mapping" are often used interchangeably.
The Service Interfaces window shows the service interfaces (also called mappings) stored in a given service interface repository (.mpr file). Such a set of service interfaces is called a service interface group.
A service interface group is not necessarily associated with a project. However, when you create a new service interface using the Mapping Wizard, if a project is open, the service interface is added to the service interface group in that project’s project folder. If the group does not exist, it is created.
The tree view shows whether a service is a COM interface, Web service or Java interface. It also shows the operations in each service.
You can import and export service interfaces between machines and between different COBOL development systems.
Right-click the name of a service interface to get a menu giving access to functions for editing and deploying the service.
You use the Mapping Wizard to prepare a COBOL application for exposure as a COM interface, Web service or Java interface, so it can be invoked as a service by client applications.
In the Wizard, you define the basic properties of the service, such as its name and whether it is a COM interface, Web service or Java interface. At the end of the Wizard, the Interface Mapper opens so that you can define how data sent between a client and the service maps onto the parameters expected by the COBOL application.
The Interface Mapping tutorials demonstrate
in detail how to use the Mapping Wizard and Interface Mapper. The fields are
described in popup help, accessible by clicking the Context Help
buttons and then clicking
the field. There are
also a number of
How-to
topics.
The following notes give some more details on some aspects of this wizard.
New Service Interfaces Group - If no project or service interface group is open when you try to create a new Service Interface, you first need to create a service interface group to add the new service to.
A typical COBOL program performs several related functions. For example, a file maintenance program may be able to add a record, return a record, delete a record, and so on. When you expose your program as a service, you make these functions available to be invoked at any time by separately-written client applications. In the terminology of services, these functions are called operations.
The Interface Mapper is the heart of the Interface Mapping Toolkit. You use it to define which of the program's functions to expose as operations of the service. For each operation, you define the fields that will be in the messages sent between the service and a client. They are called interface fields.
Data sent and received in interface fields can be mapped either onto data items in the program's Linkage Section or onto data items that are the subject of ANSI ACCEPT, ACCEPT FROM COMMAND-LINE or ANSI DISPLAY statements or the program's RETURN-CODE special register. This chapter uses the term non-Linkage Section items for this second type. Normally a program uses either Linkage Section items or non-Linkage Section items to communicate with the caller, but you can map both types of fields in the same program.
When a service is invoked, the data received in the interface fields is moved to the mapped items in the COBOL program. When the service exits, the data from the mapped items is returned in the interface fields.
You can have the Interface Mapper generate a default mapping that simply reflects the formal structure of the COBOL program. However, a programmer with a good knowledge of the workings of the COBOL program may see ways of making the interface more efficient and user-friendly. You use the Interface Mapper to do this. You can start off with the default mapping and modify it, or you can start with the Interface Mapper empty and define the interface and mapping from scratch.
When you have finished creating a mapping, you should validate it. The validate option reports one error at a time, so you need to repeat the validation until no errors are reported.
The Interface Mapper displays one operation at a time. Its window is split into the following areas:
The Interface Mapper displays details of one operation at a time. The name of the operation currently displayed is at the top right, with a dropdown list for you to select a different operation.
At the top left is the name of the entry point at which the program will be entered when this operation is invoked.
To add a new operation, you use Operation > New. You specify a name for the new operation and select the entry point where the program is to be entered.
In the default mapping that the Interface Mapper can create for you, each entry point becomes one operation. A typical improvement you might make is if you know that a single entry point leads to an EVALUATE statement choosing between different functions. You could make each of these functions into a separate operation. Often in such a program, one parameter is a code tested by this EVALUATE to see which function is wanted - see the section COBOL Assignments for how to handle this.
The left-hand pane shows the Linkage Section of your COBOL program, in a tree view reflecting the COBOL data hierarchy.
The easiest way to create new entries in the right-hand panes is by dragging items from this pane. For details, see the sections for the appropriate right-hand pane.
You can also create a new interface field by right-clicking in this pane and using the popup menu.
In the Interface Fields pane, you define interface fields for the operation currently displayed. This pane shows the interface fields for just the operation currently displayed. To see those for a different operation, use the dropdown list at the top right of the Interface Mapper to display that operation.
You can define new entries using the Field menu, or the popup menu in the Interface Fields pane, or the popup menu in the Linkage Section pane, or by dragging data items from the Linkage Section pane. Dragging is usually the most convenient method for Linkage Section items. If you need interface fields for the non-Linkage Section items, you use the the Field menu, or the popup menu in the Interface Fields pane.
If you define a field by dragging, it is mapped to the data item you dragged. You can create a set of interface fields by dragging a group item.
In the default mapping that the Interface Mapper can create for you, the interface fields for each operation are defined automatically from the Linkage Section items used by the operation's entry point. Each interface field is mapped onto the corresponding Linkage Section item.
Most of an interface field's properties are shown in columns in the Interface Fields pane, and you can update a property by double-clicking it. Some properties can then be overtyped, while others can be selected from a dropdown menu. For some properties, you must use Field > Properties. The following properties are available:
When a service is invoked, data in the input fields is moved to the corresponding Linkage Section items in the COBOL program. When the service exits, data is moved from the Linkage Section items to the corresponding output fields.
Fields within the same group cannot have different directions from one another. A group’s direction applies to all items within it.
In the default mapping that the Interface Mapper can create for you, fields mapped to BY VALUE parameters are Input. Fields mapped to BY REFERENCE parameters are I/O in a COM interface or an Java interface, while in a Web service two fields are declared, one Input and one Output, for each parameter. A typical improvement you might make is if you know that a parameter passed as BY REFERENCE contains data on output but is ignored on input. You could make it Output rather than I/O.
A mapping defines which COBOL data item the interface field is mapped to. It is shown on the field's Mappings dialog box (Field > Mappings) in a format similar to:
data-name -> interface-field-name
The arrow shows the direction of the mapping. This derives from the direction of the interface field, and you can change it only by changing the interface field's Direction property. For an input field, data is moved from the interface field to the data item when the service is invoked. For an output field or output return field, data is moved from the data item to the interface field when the service returns to the caller. For an I/O field, both these moves are done (represented by a double-headed arrow).
If you create an interface field by drag-and-drop, it is mapped by default to the COBOL item you dragged.
A field can have more than one mapping. For an input field, this means data received in the field is moved to all the data items the field is mapped to. For an output field it is meaningless (data from several COBOL items would be moved to the field, overwriting one another), unless the interface field has an Occurs property. In this case you can specify different values of the subscript in different mappings.
On the Mappings dialog box, a list box shows the mappings for the interface field. To add a mapping, you specify the name of the desired COBOL data item or one of the non-Linkage Section types in the COBOL Field field and click Add. The mapping is added to the list box.
The mappings for a non-Linkage Section item are ANSI ACCEPT and COMMAND-LINE for input fields, and ANSI DISPLAY and RETURN-CODE for output fields. These always appear at the bottom of the list box.
You cannot normally change the Field Name on this dialog box, since the purpose of the Mappings function is to specify the mappings for a particular interface field. However, if the interface field has the Occurs property, you can edit the Field Name so as to specify the subscript. Changing anything other than the subscript will result in an error message when you click Add to add a mapping.
By default, for an item with the Occurs property, each occurrence is mapped onto the corresponding occurrence of the COBOL data item. If the number in the Occurs column does not match the OCCURS clause of the Linkage Section item, a message warning you appears before the Mappings dialog box opens. You should then use the dialog box to specify mappings for the individual occurrences.
Note: If you are creating a Web service you should take care not to map an output interface field defined as a string to a COBOL alphanumeric data item that can contain a character value that is invalid for a SOAP string. Invalid character values are values less than x"20" except for x"09", x"10" and x"13". If you do create such a mapping, the client program might receive the message: "458 Illegal character in SOAP string".
The Reusable Fields pane is primarily for convenience. If you want to create a group of interface fields, and use the same group in several operations, you cannot create it in the Interface Fields pane and copy it from operation to operation, because the Interface Fields pane shows only the fields for the operation currently displayed. So instead you create it in the Reusable Mappings pane, and copy it from there to the Interface Fields pane for each operation. The Reusable Fields pane does not change when you display a different operation.
You can define new entries using the Field menu, or the popup menu in the Reusable Fields pane, or by dragging data items from the Linkage Section pane. Dragging is usually the most convenient method.
What you are in fact doing is defining a complex data type. Technically, for a Web service it defines a complex data type in the WSDL file. For a Java interface, it creates a custom record according to the CustomRecord interface defined in the Common Client Interface (CCI) from Sun. For COM, it creates a new complex data type, with the items within the group structure exposed as its properties.
In these cases, what you see in the Interface Mapper is a complex type, displayed in a way similar to a COBOL data hierarchy. Every item in the Reusable Fields pane, whether it is a group item or an elementary item, is a complex type. When you drag such a type to the Interface Fields pane, you create an interface field which has as its type the name of the type you dragged. If you double-click the Type column in the Interface Fields pane, you see listed there all the types you have defined, as well as the native types for the mechanism - COM, Java interfaces or Web Services - that you are using for the service.
The properties available for an entry in the Reusable Fields pane are the same as those for an interface field, except that, being a type declaration not an actual field, it has no direction. Most properties are shown in columns in the Reusable Fields pane. You can update a property by double-clicking the entry. Alternatively, click Field > Properties or right-click the entry and click Properties.
You update the mappings of an entry in the Reusable Fields pane in the same way as for an interface field, using Field > Mappings.
For a Web service there is an extra reason for using the Reusable Fields pane. When you drag a group item to the Interface Fields pane, this creates a hierarchy of interface fields similar to the COBOL hierarchy. The Interface Mapping Toolkit declares each group field as a complex type in the WSDL file. If you create the same group in several different operations, this complex type will be declared several times. But this is illegal in WSDL, where each complex type must have a unique name.
You could get around this by renaming each group field after creating it. But an easier and more convenient way is to drag the group item to the Reusable Fields pane instead, resulting in the complex type being declared just once. You can then create as many interface fields as you like using this type - by dragging it from the Reusable Fields pane to the Interface Fields pane - without the type being declared again.
In the COBOL Assignments pane, you define values to be placed into specified Linkage Section items when the operation currently displayed is invoked.
This pane shows the COBOL Assignments for just the operation currently displayed. To see those for a different operation, use the dropdown list at the top right of the Interface Mapper to display that operation.
Use a COBOL assignment when several operations go to the same entry point and the program takes different paths depending on the value of a parameter. Instead of defining an interface field to map to that parameter, place the value here that makes the program take the required path.
You can define new entries using the Field menu, or the popup menu in the COBOL Assignments pane, or by dragging data items from the Linkage Section pane. Dragging is usually the most convenient method. A dialog box automatically opens where you can specify the value to be placed into the item at the start of the operation.
If you drag a group field, a dialog box opens for each elementary item in turn. You can click Cancel if you do not want to set values for all of them.
A COBOL Assignment entry has only one property, the value to be assigned. It is shown in a column in the COBOL Assignments pane, and you can update it by double-clicking the entry.
The Interface Mapping Toolkit includes a Deploy tool, which does several things for you. It:
In the case of a COM object, the .dll is copied to a deployment folder in Net Express.
In the case of a Web service or EJB, you must deploy to an enterprise server that has a deployment service and a deployment listener, such as ESDEMO. The Deploy tool creates a new directory under the deployment directory specified in the deployment service's and listener's configuration. It then copies the interface files, together with the application files, to the new directory.
For more information about deployment services and listeners, see the section Deployment Services and Listeners in the chapter Configuration in your Enterprise Server Configuration and Administration Guide.
You use the Deploy tool in two stages. First you specify the deployment settings and then you deploy your service. If you find you have to make updates to the source code or service mapping to make the service perform as expected, you can redeploy it.
Alternatively, you can deploy services from the command line, using the tools imtkmake or mfdepinst. See the reference Help topics imtkmake and mfdepinst.
After deploying the service interface to an enterprise server, you deploy further software depending on the type of interface you generated:
When a service interface is ready to be run in a production environment, administrators usually take responsibility for deployment, and they typically deploy using a manual mechanism. For more information about manual deployment and about the extra tasks required for EJB services, see the chapter Deploying Interfaces in your Enterprise Server Configuration and Adminstration Guide.
You need to make sure the legacy program can find its data files.
For COM, the client and the service both run in the folder where the client application starts, so you can ensure the data files are found by putting them in this folder.
For a Web service or EJB, you can deploy the data files with the program, by specifying them on the Application Files tab on the Settings dialog box. By default, the current directory for the execution of a service is set to the directory where the service starts executing, so the service will find the files you deployed with it.
If a data file is also maintained by another application, beware that this application and the service will be maintaining different copies of the file. This situation will arise if you continue to run the old legacy application in parallel with the new service. To avoid this problem, there are several alternatives to copying the files.
You can specify the filenames in the SELECT statements with an environment variable (for example, $MYDATADIR\myfile.dat), and then set the environment variable to point to the original copy of the file. For COM, simply set it in the operating system.
Setting the environment variable in the operating system works for a Web service or EJB too - the enterprise server inherits the setting from the operating system environment. You can also set it locally in the enterprise server where the service is deployed - the server definition is then portable and can be administered remotely. See your Enterprise Server Configuration and Administration Guide for details. You can also set it for your individual service, as described below under Enterprise Server Run-time Environment.
If the service is to be deployed to a specific server where the location is known, you can simply give an absolute path in the SELECT statement.
You configure the deployment settings in the Interface Mapping Toolkit. For a COM interface, you can select the threading model to use. For more details on threading models, see the chapter Running COM Automation Servers. For a Web service or EJB, you can configure a range of deployment settings, including:
To enable these settings, check Enable enterprise server run-time environment. When this is not checked, the settings are ignored.
By default, the Deploy tool deploys to the enterprise server called ESDEMO. If your enterprise server is running on a different machine, you need to specify the remote machine name in the file mf-client.dat.
Clients can be generated for Web services. These clients are WS-I compliant. See the chapter COBOL Web Services with the Interface Mapping Toolkit.
Clients can also be generated for EJBs. See the chapter Mapping a Java Interface and Using Resource Adapters.
Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.