How to...This chapter describes using the Interface Mapper to create service interfaces for CICS and IMS applications running under Enterprise Server/MTO.
Net Express provides a tool called the Interface Mapper that you use to define your service interfaces. You can create a service interface for an application from the screens it uses or, in the case of a CICS application that does not use BMS screens, its commarea. This tool is quite powerful. You can use it to define a broad range of interfaces from those that provide access to a subset of the functions performed by your application and expanding to interfaces that do more than your application in its original form.
For CICS or IMS screen services, you start with the screens of an application and build a new interface based on existing screen fields. You have a great deal of creative license as you build your new interface. The Interface Mapper enables you to pick and choose the fields you want to use, how users interact with those fields, and how the fields map to your application. You can also define work fields to serve any number of purposes. Work fields are not included in the service interface.
For CICS commarea services, you start with the input and output commareas of a CICS program and build a new interface based on commarea fields.
The Interface Mapper window is split into two parts, the left side presenting what we refer to as your "COBOL" fields. These are in the form of screen renderings or lists of commarea fields and work fields. On the right are your interface fields, mappings, and assignments.
The left side contains:
The right side contains:
Note: For general details about Interface Mapper functionality, see the section Interface Mapper in the chapter Interface Mapping Toolkit of your Interface Mapping Toolkit book.
Generally, an operation represents an interaction with a single screen or commarea. In the Interface Mapper you work with 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.
Once you have initially created the service interface using the Mapping Wizard, you define its functionality by creating a series of operations. A single service interface typically contains multiple operations, one for each screen that might be encountered during the execution of the service, or one for each commarea program invoked.
For CICS or IMS screen services, operations can specify any of the following:
The screen that the operation is intended to process. It contains the fields you use in the operation. This screen appears in the CICS or IMS screen pane of the Interface Mapper when you are defining the operation. The operation that is intended to be performed first has no active screen. Typically, the operation that is performed first starts an application using a transaction ID.
The screen that is presented immediately before the active screen is presented during execution of the service. Most of the time, you should set this to ANY SCREEN (see below). Specifying a particular previous screen is only important when you want to interact with a screen differently depending on which screen preceded it. In this case, you would create multiple operations with the same active screen and differentiate them by specifying a particular previous screen for one or more of the operations.
After any interaction with the active screen, starts a new transaction using the ID specified. Most operations do not have a transaction ID. When you do not specify a transaction ID, the operation returns to the application with any data for the active screen.
It is common practice for IMS applications to specify a transaction ID in the MFS MID definition. In this case, to ensure that offsets are calculated properly, select the USE TRANSACTION ID FROM SCREEN DEFINITION option when specifying the transaction ID for your operation.
Active and previous screens can be a screen from the service interfaces group or one of the following special screens:
You can also opt to automatically create default mappings between interface fields and all of the fields on the active screen.
In general, you want to create an initial operation to start your application. This operation consists of only a name and the transaction ID that starts the application. We recommend you use an operation name that clearly identifies this operation, such as Start.
Note: Service interfaces written for IMS conversational applications must include an operation that enables the service to gracefully exit the application and ensure that the application’s state is properly maintained and that its SPA is properly cleared. While this type of operation is not required for other types of service interfaces, it is good practice to include one.
Once an operation has been created, you use the Interface Mapper to define its behavior.
CICS commarea services require that you specify the input and output commareas you want to use in the operation. You do this by first specifying the COBOL source and then by identifying the commarea or commareas you want to use for input and output.
In the Interface Fields pane, you define the details of each field you want to include in your service interface. Interface fields are grouped by the operation that has the COBOL fields with which the interface fields are mapped. Only the interface fields for the current operation show in this pane. The full interface for the service is comprised of all of the interface fields for all of the operations combined, in two groups - input and output. They are ordered first by the order of operations and second by the field order in the operation.
A mapping is a designation of a relationship between a COBOL field and an interface field. You identify a COBOL field (screen, commarea or work) to map to the selected interface field and optionally apply a condition to the mapping. If you have created the interface field by dragging and dropping, a mapping is done for you - the interface field maps to the field you dragged and dropped. For fields that are an array (have an OCCURS clause), all occurrences are automatically mapped by default.
An interface field that you define manually requires that you also define its mapping or mappings manually. You can define more than one mapping for each interface field. Only elementary (non-grouped) interface fields and COBOL fields can be mapped.
If a field you are mapping is an array or part of an array, use an asterisk (*) to show that all occurrences of that field are mapped (default), or define it using a subscript to specify a particular occurrence. For example:
fieldname(*)
or
fieldname(4)
For CICS screen interfaces, Net Express provides two special COBOL fields, USER ID and PASSWORD, that you can map to input interface fields to control access to your application. Use these fields to collect the user ID and password when you want to verify users before granting authorization to access the application.
You enable the run-time functionality for USER ID and PASSWORD by editing the merncntl.igc file, found in the Net Express ver\base\cntlfiles folder, as follows:
% if not &defined(&cntl-security-on) % * &cntl-security-on = "yes" % &cntl-security-on = "no" % end
% * &cntl-security-on = "yes"
So that it reads:
% &cntl-security-on = "yes"
% &cntl-security-on = "no"
So that it reads:
% * &cntl-security-on = "no"
This changes the security setting from the default of no to yes, so that user IDs are validated against those defined in the Enterprise Server System Name Table (SNT).
For CICS and IMS screen interfaces, Net Express provides three special COBOL fields, ABEND CODE, STATUS, and MESSAGE, you can map to your output interface fields as follows:
You can also make a mapping conditional. For information on creating and applying conditions, see the section Conditional Statements later in this chapter.
In the Assignments pane you can assign a value to any COBOL field. The value you specify can be a numeric or non-numeric literal or COBOL field value, or the result of a function using one or more such values. By assigning values to certain fields, you can streamline the service by reducing the amount of information that must be supplied by the user.
For example, let's say that your application adds, modifies, and deletes records in a database. In its original form, the application requires users to enter "A" for add, "M" for modify, or "D" for delete into a certain screen field. Let's also say that you want this service interface to add records but not modify or delete them. By assigning the literal "A" to the appropriate screen field, you eliminate the need for the user to enter a value.
As with mappings, you can only create assignments using elementary COBOL fields. If the assignment includes an array field, you can make the assignment using an asterisk (*) to show that all occurrences of that field are included, or you can use a subscript to specify a particular occurrence.
You can specify a function or an operator to generate a value for assignment. You can add, subtract, multiply, or divide two literal values or field values. You can also concatenate two string values or extract part of a string value.
For CICS and IMS screen services, Net Express provides a special assignment field named ATTENTION ID. Assign this field to the name of a keyboard key to represent the user pressing that key when this screen is displayed. Net Express provides a list of valid keys from which to choose. The most common value of ATTENTION ID is ENTER to represent transitioning from one screen to another.
Also for CICS screen services, Net Express provides a special assignment field named CURSOR POSITION that enables you to represent the placement of the cursor at a specific screen field.
You can also make an assignment conditional. For information on creating and applying conditions, see the section Conditional Statements later in this chapter.
For an operation, you can construct conditional statements to be evaluated to determine whether or not to perform a mapping or an assignment. You can build a collection of conditional statements for an operation. Using the collection, you can apply the same condition to multiple mappings or assignments without having to reconstruct the conditional statement for each.
The Work Fields pane enables you to create additional non-interface fields for use by the service. You can think of work fields as an extension of the screen or commarea. Work fields persist across operations, so the contents of the Work Fields pane is the same for all operations of your service interface.
For example, to use data from one screen on another screen, in one operation you can assign that data to a work field. In another operation, you can assign that work field to a field on the other screen.
Work fields can be alphanumeric or numeric. For all fields, you must specify a length and optionally the number of times the field occurs. For numeric fields, you can also specify the number of decimal places and whether or not the field is signed.
You can customize your services by coding initialization or termination logic. This can be helpful for handling application-level security, for housekeeping tasks, or for executing standard code. Initialization code executes before the first operation of a service, and termination code executes just after completion of the last operation. Initialization and termination logic applies to and is executed for all service interfaces in your service interfaces group.
To add initialization or termination code:
nxprojdir\servintprojname\servintname\UserRules\usermain.igl
Where nxprojdir is your Net Express project directory, servintprojname is the name of your service interfaces project, and servintname is the name of your service interface.
% if 0
% defini $ebiz-user-initialisation-exit
ebiz-user-initialisation-exit section.
% * Code your ebiz initialisation exit logic here
% * Change the preceeding '% if 0' to '% if 1'
exit
.
% end
% end
% if 0
% defini $ebiz-user-termination-exit
ebiz-user-termination-exit section.
% * Code your ebiz termination exit logic here
% * Change the preceeding '% if 0' to '% if 1'
exit
.
% end
% endThe operations of your service interface execute at run time based on the screens encountered as the service executes.
Execution of a screen service involves performing a series of the specified operations, starting with the operation that has no active screen and typically specifies a transaction ID that starts the application. Once the application is started, service operation execution is determined by:
Each operation entails processing the active screen as follows:
Execution of a CICS commarea service involves performing all the specified operations in the order in which they are listed in the service interface. Each operation executes as follows:
The service terminates after executing the last operation listed for the service.
Copyright © 2007 Micro Focus (IP) Ltd. All rights reserved.