Create the Service Interface
- From the
Solution Explorer in
Enterprise Developer, right-click the
IMSSupport project; then click
Add >
New Item.
- In the left pane, expand
COBOL; then click
Native.
- In the center pane, click
Service Interface.
- In the
Name field, type
IMSScreenWS, and then click
Next.
- On the
Service Interface dialog box, select
Web Service from the
Type of interface drop-down list. This automatically sets the
SOAP transport type.
- In the
Type of source field, select
IMS Screen; then click
OK.
At this point,
Enterprise Developer adds the
IMSScreenWS service interface to the
Solution Explorer and invokes the
Interface Mapper.
Define IMSScreenWS Operations
Each service interface you create is comprised of a set of operations. For an IMS Screen service interface, most operations
address a screen encountered by the program. Others address initialization and termination of the service.
The MFDEMO application is not conversational, meaning it does not maintain state. You could successfully deploy, run, and
access your service without providing a way to terminate the application from a terminal. However, if this IMS application
were a conversational application, you would need to add this functionality. To show how this is done, this section walks
you through the process of defining the service interface to behave as if it were accessing a conversational application,
enabling it to:
- Connect to the MFDEMO application
- Query a table in the database
- Show the returned data
- Exit the application
- Terminate on an error at any stage
Create the following operations to accommodate these requirements:
- Start operation
- The purpose of the Start operation is to initialize the MFDEMO application by sending the transaction ID and simulating the
pressing of the
Enter key.
- From the
Interface Mapper, right-click the
Operation pane and then from the drop-down list, click
New.
This opens the Operation Properties window where you specify general information for the new operation.
- In the
Operation Name field, type
Start.
Because this is the operation that initiates the service, there is no active screen or previous screen to specify.
- Leave the default values in the
Active Screen and
Previous Screen fields.
The name of the transaction that initiates the MFDEMO application is MFDEMO.
- In the
Transaction ID field, type
MFDEMO; then click
OK.
To actually initiate the transaction, a user would need to then press
Enter. To simulate this action, you create an ATTENTION ID assigned to the
Enter key. ATTENTION ID defines which AID key (for example,
Enter,
PF8, etc.) to use.
- Right-click anywhere in the
Assignments pane; then select
New Assignment from the popup menu.
- From the
Assign to drop-down list, click
ATTENTION ID.
- From the
Field 1/Operand 1 drop-down list, click
ENTER.
- Click
OK.
- Click
File > Save IMSScreenWS.svi to save the service interface.
This completes the Start operation.
- Query Data operation
- The purpose of the Query Data operation is to send a query instruction to the application and to provide a return path to
the application's main menu.
- Create the Query Data operation
-
- Right-click the
Operation pane and then from the drop-down list, click
New.
- In the
Operation Name field, type
Query Data.
Now you want to set the active screen that shows the main menu of the MFDEMO application. The name of this screen is DEMO91.
- From the
Active Screen drop-down list, click
DEMO91.
DEMO91 is the first screen you want to access, so no previous screen exists.
- From the
Previous Screen drop-down list, click
<None>.
This operation does not initiate a transaction.
- Leave
Transaction ID blank.
You could have the Interface Mapper create default mappings for you, but in this tutorial you want to create the mappings
yourself.
- Leave
Create Default Mappings unchecked.
- Click
OK.
This returns you to the
Interface Mapper and shows the IMS Screen DEMO91 in the
IMS Screen pane.
- Create an assignment
- To query the database you need to provide the application with a function code of
I (for Inquire). You do this by assigning a value of
I to the appropriate field.
- On the
IMS Screen: DEMO91 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. You need to know the name of this field so you can create an assignment for it.
- In the
Assignments pane, right-click; then click
New Assignment.
- From the
Assign to drop-down list, select
FLD0003.
- 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
- You also need to provide your users with a field into which they can type the table ID for the table they want to query. You
do this by creating an interface field based on the original input field on the DEMO91 screen.
- On the
IMS Screen: DEMO91 pane, locate the input field to the right of the
TABLE-ID label.
- Click and drag this field to the
Interface Fields 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, you can rename it in the
Interface Mapper so that it is more recognizable. The name used here appears as the field label in your generated clients.
- In the
Interface Fields pane, double-click
FLD0004.
- In the
Name field, type
TableID.
The original FLD0004 field is defined as an input/output string. By default the
Interface Mapper has defined this service interface equivalent as an input string, which is what you want here. No further adjustments are
necessary.
- Click
OK.
Notice that the
Interface Fields and
Mappings panes now show the interface field with its new name, TableID. The
Mappings pane shows that the TableID interface field maps to the FLD0004 COBOL field.
- Assign an ATTENTION ID
- Once again, if your end user were interacting with the application on a terminal, they would have to press the
Enter key to send the table ID to the application. For the service interface, this requires that you create an ATTENTION ID assigned
to the
Enter key.
- Right-click anywhere in the
Assignments pane; then select
New Assignment from the popup menu.
- From the
Assign to drop-down list, click
ATTENTION ID.
- From the
Field 1/Operand 1 drop-down list, click
ENTER.
- Click
OK.
- Click
File > Save IMSScreenWS.svi to save the service interface.
This completes the Query Data operation.
- Show Data operation
- The Show Data operation displays the data requested by the Query Data operation.
- Create the Show Data operation
-
- Right-click the
Operation pane and then from the drop-down list, click
New.
- In the
Operation Name field, type
Show Data.
In this operation, you want display information from the screen that shows the returned data. The name of this screen is DEMO92.
- From the
Active Screen drop-down list, click
DEMO92.
Because this operation requires input provided by the Query Data operation, you need to provide the name of the screen used
in that operation, DEMO91. This establishes that the path to the active screen is through the DEMO91 screen.
- From the
Previous Screen drop-down list, click
DEMO91.
- Leave the
Transaction ID field blank.
- Leave
Create Default Mappings unchecked.
- Click
OK.
The
IMS Screen pane now shows the DEMO92 screen.
- Group Map Fields
- The MFDEMO application displays information returned from the database on the DEMO92 screen in a series of three columns across.
You can simplify the service interface definition for these fields by grouping them using the Map Annotation Editor. Once
grouped, you can reference grouped fields as an array when you define them in the operation.
- In the
IMS Screen: DEMO92 pane, hover the mouse over the left-most field that appears in the first row, just below the
FUNC label.
A popup tells you that the name of this field is
FLD0014.
- Now hover your mouse over the right-most field that appears in the last row, just above the
NEXT-ELEMENT label.
The popup tells you that the name of this field is
FLD0052.
- From the Solution Explorer, right-click
DEMO92.mfs; then click
Edit Annotations for Services > Map DEMO92. This starts the Map Annotations Editor.
- Scroll down the list of fields until you find
FLD0014; then click this field to select it.
- Continue scrolling down until you find
FLD0052. Hold the
Shift key down and click
FLD0052 to select it and all of the fields listed between it and
FLD0014.
- Move your mouse to the selected area in the Map Annotations Editor; then right-click and select
Group from the popup menu.
You want to group the fields just as they are displayed on the DEMO92 screen. Therefore, the number of fields in the resulting
array needs to match the number of columns on the screen, which is three.
- In the
Number of fields in the group field, type
3.
- 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.
- Click
OK.
In the Map Annotations Editor, you now see that the parent for the grouped fields is
RETURN-GRP1, and that this group occurs 13 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. The direction for all fields is defined as Input/Output.
- Click
File > Save DEMO92.emp to save your changes; then close the tab containing the Map Annotations Editor.
The rendering of the DEMO92 screen in the
Interface Mapper is automatically updated with these changes to the map.
- Create interface fields
- With the fields we need from the DEMO92 screen identified and grouped, you are now ready to define the interface fields that
receive the returned data. In this case, you don't need to display the FUNC data from the first column on the screen. You
are only interested in showing the data from the ELEMENT KEY and ELEMENT VALUE/DESCRIPTION columns.
- From the
IMS Screen: DEMO92 pane, click and drag the following fields to the
Interface Fields pane, and drop them there:
- FLD0015Grp - located under the
ELEMENT KEY label
- FLD0016Grp - located under the
ELEMENT VALUE/DESCRIPTION label
By default, the
Interface Mapper assigns the
Input direction to interface fields created from IMS screen Input/Output fields. Therefore, each of the interface fields you have
just created is defined as an
Input field. However, because you want to use these fields to show data returned from the IMS database, you need to redefine their
direction to
Output.
In addition, you should also rename each of the fields to something more meaningful as the names you assign here appear as
field labels in your generated clients.
- From the
Interface Fields pane, double-click
FLD0015Grp.
- In the
Name field, type
ElementKey to rename the field.
- Click
Output to change the direction of the field.
- Click
OK.
- Repeat steps
2 through
5 for the
FLD0016Grp field, changing its direction to
Output and renaming it to
ElementValue.
- Create mapping conditions
- To prevent your client from displaying null values, which can show up as garbage characters, you can create mapping conditions
that prevent the output fields from accepting null values from the application.
- From the
Mappings pane, right-click
ElementKey(*), then select
Apply Condition from the context menu.
- In the
New Name field, type
KeyNotNull; then click
Create.
- From the
Field drop-down list, select
RETURN-GRP1.FLD0015Grp(13).
- In the
Field field, replace the
13 with an asterisk to represent all occurrences.
- From the
Operator drop-down list, click
>=.
- In the
Field or Literal value field, type
" " (double-quote followed by a space and another double-quote).
The completed defined condition is:
RETURN-GRP1.FLD0015Grp(*) >=" "
This condition mandates that only data that has a value greater than or equal to a space can be moved from
RETURN-GRP1.FLD0015Grp(*) to
ElementKey(*).
- Click
OK to close the Condition Editor, and
OK again to close the Apply Condition dialog box.
You need to apply a similar condition to the other mapping.
- From the
Mappings pane, right-click
ElementValue(*); then select
Apply Condition from the context menu.
Because the condition you're creating here is so similar to the condition you created for ElementKey, you can use the condition
you created for ElementKey as a starting point.
- From the
Existing Condition drop-down list, select
KeyNotNull.
- In the
New Name field, type
ValueNotNull; then click
Create.
- From the
Field drop-down list, select
RETURN-GRP1.FLD0016Grp(13).
- In the
Field field, replace the
13 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.
- 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.
- Click
File > Save IMSScreenWS.svi to save the service interface.
- Create Assignments
- To enable this service interface to terminate the application as if from a terminal, you must add assignments to the Show
Data operation that return the application to the DEMO91 screen, which is the main menu for the MFDEMO application. When done
from a terminal, a user would type an
X into the
NEXT FUNCTION: RETURN field, and then press
Enter. To do the same in your service interface, you assign the string value
X to the
FLD0056 field, which is the name of the field labeled NEXT FUNCTION: RETURN, and then assign an ATTENTION ID for the
Enter key.
- In the
Assignments pane, right-click; then select
New Assignment from the context menu.
- From the
Assign to drop-down list, select
FLD0056.
- In the
Field 1/Operand 1 field, type
X, which is the value that tells the application to return to the main menu screen.
- Click
OK.
- In the
Assignments pane, right-click and select
New Assignment from the popup menu.
- From the
Assign to drop-down list, click
ATTENTION ID.
- From the
Field 1/Operand 1 drop-down list, click
ENTER.
- Click
OK.
- Click
File > Save IMSScreenWS.svi to save the service interface.
This completes the Show Data operation.
- Clean Exit operation
- In this operation, you supply the application with a value of
E (for exit) for the main menu's
FUNCTION CODE field (FLD0003). This action provides a clean exit from the application.
- Right-click the
Operation pane and then from the drop-down list, click
New.
- In the
Operation Name field, type
Clean Exit.
- From the
Active Screen drop-down list, click
DEMO91. This is the name of the details screen of the application.
- From the
Previous Screen drop-down list, click
DEMO92 to establish that the path to the active screen is through the
DEM092 screen.
- Leave the
Transaction ID field blank.
- Leave
Create Default Mappings unchecked.
- Click
OK. The
IMS Screen pane now shows the DEMO91 screen.
- In the
Assignments pane, right-click and select
New Assignment from the popup menu.
- From the
Assign to drop-down list, click
FLD0003, which is the name of the FUNCTION CODE field.
- In the
Field 1/Operand 1 field, type
E, which is the value that tells the application to exit.
- Click
OK.
Once again, you need to simulate the pressing of the
Enter key after providing a value for the field.
- In the
Assignments pane, right-click and select
New Assignment from the popup menu.
- From the
Assign to drop-down list, click
ATTENTION ID.
- From the
Field 1/Operand 1 drop-down list, click
ENTER.
- Click
OK.
- Click
File > Save IMSScreenWS.svi to the service interface.
This completes the Clean Exit operation.
- Get Out operation
- Finally, you need an operation that simply terminates the service if, for some reason, the application screen for any operation
does not match its specified Active Screen. This operation is provided as a failsafe only.
- Right-click the
Operation pane and then from the drop-down list, click
New.
- In the
Operation Name field, type
Get Out.
You need this operation to execute when the active screen and/or previous screen cannot be determined by the service.
- From the
Active Screen drop-down list, click
ANY SCREEN.
- From the
Previous Screen drop-down list, click
ANY SCREEN.
- Leave the
Transaction ID field blank.
- Leave
Create Default Mappings unchecked.
- Click
OK.
- Click
File > Save IMSScreenWS.svi to the service interface.
This completes the Get Out operation.
Close the
Interface Mapper
You have now completed the IMSScreenWS service interface definition. You can close the
Interface Mapper tab