Chapter 6: Create an IMS Web Service Interface

In this chapter, you create a Web service interface to an IMS application by mapping its MFS screen fields using the Interface Mapper. You also deploy the service, generate a client for the service, and run the client.

The Sample Application

This session uses the supplied sample application, MFDEMO. The MFDEMO application provides access to tables of data in an IMS database. You can add, modify, or query the information via MFS screens.

Preparation

Before completing this tutorial, you must first complete all of the tasks presented in the chapter IMS Installation Verification of your reUZE Server Configuration and Administration Guide. These tasks include preparing the MFDEMO application to run under reUZE Server, creating, configuring and starting an enterprise server to run the application, and adding information to the application's database by running it in a TN3270 emulator.

When you have completed the tasks required to run the application in reUZE Server, start Net Express.

Create a Project

For the purposes of this tutorial, we'll create a Net Express project.

1. Click File > New.
2. On the New dialog box, click Project, then click OK.
3. On the New Project dialog box, click Empty Project.
4. In the Enter the name of the project field, type IMSEXT.
5. In the Enter the name of the folder you wish to contain the project field, you can optionally type the full path to a folder or click Browse to navigate to a suitable folder. Or, you can do nothing to accept the default folder. In this tutorial, the location of the project does not matter.
6. Click Create.

Create the IMSDemo Service Interface

Now we will create a new service interfaces group and a service interface named IMSDemo.

1. Click File > New.
2. On the New dialog box, click Service Interface, then click OK. This creates a service interfaces group.
3. From the Select the type of service drop-down list, click Web Service.
4. From the Select the source from which mappings will be created drop-down list, click IMS Screen.
5. Click Next.
6. In the Enter the name for the service field, type IMSDemo.
7. Click Next, then click Finish. This starts the Interface Mapper.

   Before we create any operations for this new service interface, we need to add MFS screens to our service interfaces group.

8. Click OK to clear the message.

Load MFS Screens

Now we will load the MFS screens from our Revolve project into the service interfaces group.

1. From the Net Express IDE, click the Service Interfaces tab.
2. Click Service > Add/Refresh Host Screens.
3. Click Screens from Revolve Project.
4. In the field below Screens from Revolve Project, either type the full path to and filename of the Revolve project or use the Browse button to navigate to the directory that contains the Revolve project and select it. For example, if you accepted the defaults when you installed Net Express 5.1, the appropriate directory and filename are c:\Program Files\Micro Focus\Net Express 5.1\Examples\Net Express IDE\MTO-IMS\IVP\REVOLVE\IMSIVP.prj.
5. Click Next. This next screen lists all of the MFS maps found in the Revolve project.
6. Click Select All to highlight all of the maps on the list, then click Add.
7. Click Finish. This adds all of the MFS maps to the service interfaces group, listed under Screens.

Group Screen Fields

The MFDEMO displays information returned from the database in a series of three columns across a screen. If we group these fields using the Screen Editor, we can then refer to the grouped fields as arrays when we define our service operations.

1. From the service interfaces group, right-click the screen DEMO92 and select Show Screen from the popup menu. This is the MFS screen used by the MFDEMO application to show data retrieved from the database. Notice that the data returned is presented in a series of 14 rows containing three fields each.
2. Hover the mouse over the left-most field that appears in the first row, just below the FUNC label. A popup tells us that the name of this field is FLD0014.
3. Now hover your mouse over the right-most field that appears in the last row, just above the NEXT-ELEMENT label. The popup tell us that the name of this field is FLD0055.
4. Click the x icon in the upper right-hand corner of the Map Screen window to close it.
5. From the service interfaces group, double-click the DEMO92 screen. This starts the Screen Editor.
6. Scroll down the list of fields until you find FLD0014, then click this field to select it.
7. Continue scrolling down until you find FLD0055. Hold the Shift key down and click FLD0055 to select it and all of the fields listed between it and FLD0014.
8. Move your mouse to the area of the window that is selected, then right-click and select Group Fields from the popup menu.
9. In the Number of fields to appear in the new group field, type 3.
10. In the Group name prefix field, type RETURN. This prefix along with a generated group identifier (for example, GRP1) becomes a parent to the fields in the group.
11. Click OK.

    On the DEMO92 window, you now see that the parent for the grouped fields is RETURN-GRPn, and that this group occurs 14 times as is shown in the Occurs column. The three fields listed below the parent each bear the name of the first field in each column that appears across the screen, appended by Grp.

12. Save your changes and exit the Screen Editor.

Create Service Operations

Each service interface you create is comprised of a set of operations. Each operation addresses a screen encountered by the service. In this tutorial, we will create a service interface that enables users to query a table in the database by providing the table ID. To accommodate this, we will create two operations - Query Data and Show Data.

Start Operation

The purpose of the Start operation is to connect to our application by pressing the Enter key.

1. From the Interface Mapper, click Operation > New.
2. In the Operation Name field, type Start.
3. Leave the default values in the Active Screen and Previous Screen fields.
4. In the Transaction ID field, type MFDEMO.
5. Click OK.
6. In the Assignments pane, right-click and select New Assignment from the popup menu.
7. From the Assign to drop-down list, click ATTENTION ID. This is the field that defines which AID key (for example, Enter, PF8, etc.) should be used.
8. From the Field 1/Operand 1 drop-down list, click ENTER.
9. Click OK.
10. On the Net Express IDE, click the IMSDemo tab.

    This completes the Start operation.

Query Data Operation

The purpose of the Query Data operation is to send a query instruction to the application.

Create the Operation

The first step is to create the operation.

1. Click Operation > New.
2. In the Operation Name field, type Query Data.
3. From the Active Screen drop-down list, click DEMO91. This is the screen name for the main menu of the MFDEMO application.
4. From the Previous Screen drop-down list, click <None>. DEMO91 is the first screen we want to access.
5. Leave Create Default Mapping unchecked. We will create appropriate mapping ourselves.
6. Click OK. This returns you to the Interface Mapper and shows the IMS Screen DEMO91 in the IMS Screen pane.

Create an Assignment

As we learned from running this application in its original form, to query the database we need to provide the application with a function code of I (for Inquire). We do this by assigning a value of I to the appropriate field.

1. On the IMS Screen pane, hover over the entry field located to the right of the FUNCTION CODE label. A popup indicates that the name of this field is FLD0003. We need to know the name of this field so we can create an assignment for it.
2. From the Assignments pane, right-click, then click New Assignment.
3. From the Assign to drop-down list, click FLD0003.
4. In the Field 1/Operand 1 field, type an upper-case I, then click OK. The Assignments pane now shows that FLD0003 is set to a value of I.

Create an Interface Field

We also need to provide our users with a field into which they can type the table ID for the table they want to query. We'll do this by creating an interface field based on the original input field on the DEMO91 screen.

1. On the IMS Screen pane, locate the input field to the right of the TABLE-ID label.
2. Click and drag this field to the Interface Field pane and drop it there.

   The name of this field, FLD0004, is not particularly descriptive. Because this field is really the input field for the table ID, we will rename it in the Interface Mapper so that it is more recognizable. The name we use here will appear as the field label in our generated Windows Form client.

3. In the Interface Fields pane, double-click FLD0004.
4. In the Name field, type TableID.

   The original FLD0004 field is defined as an input/output field, so by default the Interface Mapper has created its service interface equivalent as an input field, which is what we want here. No further adjustments are necessary.

5. Click OK.

   Notice that the Mappings pane shows the interface field with its new name, TableID, mapping to the COBOL field FLD0004.

Create an ATTENTION ID

To complete the operation, we need to submit the value of the interface field using an ATTENTION ID for the Enter key:

1. In the Assignments pane, right-click and select New Assignment from the popup menu.
2. From the Assign to drop-down list, click ATTENTION ID.
3. From the Field 1/Operand 1 drop-down list, click ENTER.
4. Click OK.

This completes the Query Data operation.

Show Data Operation

The Show Data operation returns and displays the data requested by the Query Data operation.

Create the Operation

Again, the first step is to create the operation.

1. Click Operation > New.
2. In the Operation Name field, type Show Data.
3. From the Active Screen drop-down list, click DEMO92. This is the name of the details screen of the application.
4. From the Previous Screen drop-down list, click DEMO91 to establish that the path to the active screen is through the DEM091 screen, or you can simply leave this field blank since DEMO91 is the only possible path to the active screen.
5. Leave the Transaction ID field blank. The transaction for this operation is a continuation of the transaction started by the Query Data operation.
6. Leave Create Default Mapping unchecked.
7. Click OK. The IMS Screen pane now shows the DEMO92 screen.

Create Interface Fields

We now need to define interface fields to accommodate the returned data. We have already identified and grouped the fields we need on the DEMO92 screen, which will simplify this process a great deal.

1. From the IMS Screen pane, click and drag the following fields to the Interface Fields pane and drop them there:
   • FLD0015Grp - located under the ELEMENT KEY heading
   • FLD0016Grp - located under the ELEMENT VALUE/DESCRIPTION heading

   Fields that originate as input/output fields are by default created as input fields in their Interface Field equivalents. Therefore, each of these fields is now defined as an input field. However, in this case, we want them to be output fields. We also want to rename each of the fields to something more meaningful. The names we assign here appear as field labels in our generated client.

2. From the Interface Fields pane, double-click FLD0015Grp.
3. In the Name field, type ElementKey to rename the field.
4. Click Output to change the direction of the field.
5. Click OK.
6. Repeat steps 2 through 5 for the FLD0016Grp field, renaming it to ElementValue.

Now let's turn our attention to the Mapping pane. The Interface Mapper has automatically generated mappings for these two fields. Notice that the Interface Fields column shows the fields with an asterisk appended to the end of each field name. The asterisk tells us that these fields each represent an array and that all occurrences of the field are included.

The COBOL Field column shows the field from the originating IMS screen that corresponds to the interface field we've created. Field names in this column are qualified by the group parent name we assigned when we grouped the fields in the Screen Editor, and also have an asterisk in parentheses appended to them. Again, this asterisk tells us that all fields on the originating screen are included.

The Map column shows us the direction that data travels. Here, because we have defined our interface fields as output fields, data moves from the COBOL fields to the interface fields as is represented by the left-pointing arrow.

Create Mapping Conditions

We need to create a condition for each of our interface fields that prevents them from receiving null values from the application.

1. From the Mapping pane, right-click ElementKey(*), then click Apply Condition on the popup menu.
2. In the New Name field, type KeyNotNull, then click Create.
3. From the Field drop-down list, click RETURN-GRPn.FLD0015Grp(14).
4. In the Field field, replace the 14 with an asterisk to represent all occurrences.
5. From the Operator drop-down list, click >=.
6. In the Field or Literal value field, type " " (double-quote followed by a space and another double-quote), then click OK.

   This condition mandates that only data that has a value greater than or equal to a space can be moved from RETURN-GRPn.FLD0015Grp(*) to ElementKey(*). We need to apply a similar condition to the other mapping.

7. From the Mapping pane, right-click ElementValue(*), then click Apply Condition on the popup menu.

   Because the condition we're creating here is so similar to the condition we created for ElementKey, we can use the condition we created for ElementKey as a starting point.

8. From the Existing Condition drop-down list, click KeyNotNull.
9. In the New Name field, type ValueNotNull, then click Create.
10. From the Field drop-down list, click RETURN-GRPn.FLD0016Grp(14).
11. In the Field field, replace the 14 with an asterisk to represent all occurrences.

    The rest of the condition definition is the same as for KeyNotNull and is already populated in the appropriate fields.

12. Click OK to close the Condition Editor, then click OK to return to the Interface Mapper.

    The Condition column in the Mappings pane now shows the conditions you defined.

We have now completed the Show Data operation.

Modify for Conversational Applications

Because the MFDEMO application is not conversational, meaning it does not maintain state, we could at this point save the service interface, close the Interface Mapper, deploy, and then and run our service interface and it would work fine. However, if this IMS application had been a conversational application, we would need to modify the service interface to terminate the application as if from a terminal. This section shows you how to modify the MFDEMO application service interface to behave as if it were accessing a conversational application:

Modify the Show Data Operation

First, we need to add an assignment to the Show Data operation that returns the application to the DEMO91 screen. We do this by assigning the string value X to FLD0056 and also adding an ATTENTION ID assignment for the Enter key:

1. Click Operations > Show Data.
2. From the IMS Screen pane, click and drag the FLD0056 field (to the right of the RETURN label) to the Interface Fields pane and drop it there.
3. In the Assignments pane, right-click and select New Assignment from the popup menu.
4. From the Assign to drop-down list, click FLD0056.
5. In the Field 1/Operand 1 field, type X, which is the value that tells the application to return to the main menu screen.
6. Click OK.
7. In the Assignments pane, right-click and select New Assignment from the popup menu.
8. From the Assign to drop-down list, click ATTENTION ID.
9. From the Field 1/Operand 1 drop-down list, click ENTER.
10. Click OK.

Create the Exit Gracefully Operation

In this operation, we supply the application with a value of E (for exit) for the main menu's FUNCTION CODE field (FLD0003).

1. Click Operation > New.
2. In the Operation Name field, type Exit Gracefully.
3. From the Active Screen drop-down list, click DEMO91. This is the name of the details screen of the application.
4. From the Previous Screen drop-down list, click DEMO92 to establish that the path to the active screen is through the DEM092 screen.
5. Leave the Transaction ID field blank.
6. Leave Create Default Mapping unchecked.
7. Click OK. The IMS Screen pane now shows the DEMO91 screen.
8. In the Assignments pane, right-click and select New Assignment from the popup menu.
9. From the Assign to drop-down list, click FLD0003.
10. In the Field 1/Operand 1 field, type E, which is the value that tells the application to exit.
11. Click OK.
12. In the Assignments pane, right-click and select New Assignment from the popup menu.
13. From the Assign to drop-down list, click ATTENTION ID.
14. From the Field 1/Operand 1 drop-down list, click ENTER.
15. Click OK.

    This completes the Exit Gracefully operation.

Create the Get Out Operation

Finally, we need an operation that simply terminates the service interface if, for some reason, the application screen for any operation does not match it's specified Active Screen. This operation is provided as a failsafe only.

1. Click Operation > New.
2. In the Operation Name field, type Get Out.
3. From the Active Screen drop-down list, click ANY SCREEN.
4. From the Previous Screen drop-down list, click ANY SCREEN.
5. Leave the Transaction ID field blank.
6. Leave Create Default Mapping unchecked.
7. Click OK.

   This completes the Get Out operation.

Save and Exit the Interface Mapper

You have now completed both of the operations for the IMSDemo service interface.

1. Click File > Save.
2. Click File > Close. This returns you to the service interfaces group, which now shows the completed IMSDemo service.

Set Deployment Settings

Here we will set our new service interface to run in the IMSIVP enterprise server. If you have stopped your IMSIVP enterprise server, start it again before continuing.

1. In the Net Express IDE from the service interfaces group, right-click IMSDemo and click Settings from the popup menu.
2. If you are asked to specify a namespace, click OK to accept the default value.
3. On the Mapping Properties dialog box, click the Deployment Server tab.
4. To the right of the Enterprise Server name field, click Change.
5. On the list that appears on the Select Enterprise Server dialog box, click the entry for IMSIVP, then click OK.
6. Click OK to save the settings and close the Mapping Properties dialog box.

Deploy IMSDemo

Now we'll deploy our IMSDemo service. This will generate and compile the COBOL driver program we need to run the service. It also generates a deployment package and sends it to reUZE Server.

1. From the service interfaces group, right-click IMSDemo and choose Deploy from the popup menu.
2. When the service has been successfully deployed, click OK.

Generate the Client

We will generate Web service clients to access our service that is now deployed to reUZE Server. If you have Visual Studio 2008 installed, the clients generated for a Web service include both a Windows Form and a Web Form client in addition to a COBOL console client that you can compile and run from your Net Express project.

1. From the service interfaces group, right-click IMSDemo and choose Generate Client from the popup menu.
2. On the Client Generation Project Selection dialog box, be sure that Use current Net Express project is selected, then click OK.

   Note: If you have previously generated a client for this service interface, the Client Generation Project Selection dialog box does not appear.

Run the Service

Now we're ready to run the service using a generated client.

Run the Windows Form Client

If you have Microsoft Visual Studio .NET 2008 installed, you can access the service from a Windows Form client.

1. From the service interfaces group, right-click IMSDemo and click Run WinForm Client from the popup menu.
2. In the TableID field, type TESTERS, then click Submit. The client returns the data contained in the TESTERS table of your database.
3. Click Exit.

Build and Run the Console Client

If you have not installed Microsoft Visual Studio .NET 2005, you can still access the service from the console. Before you can run a COBOL console client, you must build the project in Net Express.

1. From the Net Express IDE, with the IMSEXT project open, click Rebuild .
2. Click the Project:IMSEXT.app tab.
3. Right-click IMSDemo-app.int, then click Run.
4. On the Start Animating dialog box, click OK.
5. Enter TESTDEPT. The client returns the data contained in the TESTDEPT table of your database.

Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.