Provides step-by-step instructions that guide you through the process of defining four operations for the AccessBooks service
interface.
A service interface is defined as a series of operations. In each operation, you create service interface fields that correspond
to your COBOL program's entry point fields. At run time, data is sent between the service and the program via these fields.
In this section of the tutorial, you use the Interface Mapper to define one operation for each of the program's four possible
actions - Read record, Add record, Delete record, and Get next record. Each operation requires the client to send just the
data needed by that particular operation.
Tip: As you define these operations, we recommend that you save your work periodically. You can do this at any point you choose
and as often as you like by clicking
File > Save AccessBooks.svi from the Visual Studio menu.
Add Operation
The first logical operation to define for this Web service is one that enables you to add a record. The process entails identifying
the COBOL program that contains the Add action, identifying the COBOL Entry point code for that program, determining which
fields send and receive information, and defining your operation to interact with the program, specifying the Add action.
- Create the Add operation
- First, you create the operation, giving it a name and identifying the program and entry point with which you want to interact.
In this case, you want to create an operation that enables you to add a record:
- In the Interface Mapper, right-click
Operation at the top, and select
New from the context menu.
- In the
Name field, type
Add.
The programs available in your Visual Studio project appear on the
Select program/copybook list. From studying the COBOL code in the application, you know that the
book.cbl program performs the add record action.
- Select
book.
The name of each entry point contained in the program appears farther down on the dialog box. This shows that
Book.cbl contains only one entry point -
BOOK.
- From the
Select entry point list, click
BOOK. The entry point code appears to its right.
- Click
OK.
In the
Interface Mapper, you now see that the entry point fields have been placed into the
COBOL Entry Point pane.
- Define an Interface Field
- You see from the
book.cbl source that the
lnk-file-status field returns the status of the last file input/output action. You need to create an interface field to contain the value
so the client can send it to the application:
- Define a Group of Interface Fields
- You see from the COBOL source that to add a record, the client must supply all the data needed to add the new record to the
indexed file. The Book program receives the data in the group item
lnk-b-details. For this operation, you need to define a set of interface fields to hold this data:
- Drag
lnk-b-details from the
COBOL Entry Point pane to the
Interface Fields - Input pane.
By default, the name of the new interface field group created is
lnk_b_details. However, in this case you should change the default name. You need to use this same group of source fields to create similar
groups of interface fields in other operations in this same service interface. The Interface Mapper requires that interface
field groups have unique names across operations in the same service interface. Because the default name for each of these
would be identical in each operation, you must change the name in each operation to ensure that each is different from that
used in other operations.
- In the
Interface Fields - Input pane, double-click
lnk_b_details
- In the
Name field, type
addop_details.
- Click
OK.
- Change a Type
-
- If not already expanded, fully expand the tree for
addop_details in the
Interface Fields - Input pane.
When defining a service interface, knowledge of the application and how it is used can enable you to make refinements to the
new interface. For example, looking at the
COBOL Entry Point pane, notice that the retail price field
lnk-b-retail is defined as 9(2)V9(2). If you fully expand the tree for
addop_details in the
Interface Fields - Input pane, you see that
lnk_b_retail has defaulted to
number. Imagine that you know from your experience with the application that the retail prices are in fact always in whole numbers
of dollars, and that
lnk_b_retail can be an
integer. You change the type of the
lnk-b-retail interface field to reflect this:
- Double-click the
number type for the
lnk_b_retail field.
- Select
integer from the drop-down list..
- Define a COBOL Assignment
- When the Book program executes, it uses the value in the
lnk-function field to determine which action to perform. In cases like this where the value required to initialize an action is known,
you create a COBOL Assignment field rather than an interface field, and assign it the value required by the program to ensure
a specific action.
For the Add operation, you want the program to perform the add-record action. From looking at the source code, you know that
when the value in the
lnk-function field is 2, the program performs an add-record action:
- Drag the
lnk-function field from the
COBOL Entry Point pane to the
COBOL Assignments pane.
Note: If the
COBOL Assignments pane is not in view, drag the bottom of the
Reusable Fields pane upward to reveal it.
- Click
File > Save AccessBooks.svi to save the service interface.
Next Operation
In your indexed file, the primary key is the stock number. The program action that gets the next record takes a stock number
as input, finds the record in the data file that has that stock number, and returns the next record found.
The program uses the
COBOL Entry Point field
lnk-b-details as both an input and an output field, although on input
lnk-b-stockno is the only part of
lnk-b-details actually used. In your operation, you use the same field to access the program action that gets the next record in the data
file.
- Create the Next operation
-
- In the Interface Mapper, right-click the
Operation button at the top, and select
New from the context menu.
- In the
Name field, type
Next.
The
Select program/copybook list shows the
book program and the
book-rec copybook. The
book program is already selected for you. This is because each service interface can use only one program, and you specified the
book program in the Add operation you defined earlier for this same service interface.
- In the box under
Select entry point, click
BOOK.
The entry point details are shown on the right.
- Click
OK.
- Define the Next operation
-
- Based on the instructions for the Add operation, define a COBOL Assignment for the
lnk-function field and set its value to
4. This is the value that instructs the program to get the next record.
- Create an interface output field named
lnk_file_status from the
COBOL Entry Point field
lnk-file-status.
The program action that retrieves the next record gets the required record from the data file and returns it. So you need
a set of output fields into which the fields of this record return.
- Drag
lnk-b-details from the
COBOL Entry Point pane to the
Interface Fields - Output pane.
The new interface field created is called
lnk_b_details. As you did when defining the Add operation, you must change the field name to ensure that it is different from the name
used for similar groupings in the other operations for this interface.
- Double-click the
lnk_b_details field name in the
Interface Fields - Output pane.
- Change the name to
nextop_details; then click
OK.
- Fully expand the tree for
nextop_details, and change the type of
lnk_b_retail from
number to
integer, just as you did for the Add operation.
In the application, the
lnk-b-stockno field serves as an output field and is also the field in which the key identifying the required record is input. To handle
this, you create an input interface field to accept the key.
- In the
COBOL Entry Point pane, fully expand
lnk-b-details.
- Drag
lnk-b-stockno from the
COBOL Entry Point pane to the
Interface Fields - Input pane. Ensure that
lnk-b-stockno is first on the list and thus the first field to supply its value to the program.
Because this is a JSON service, all fields of the same direction must share a structure to represent the root object in the
JSON request or response. Therefore, you need to add the
lnk_file_status output field to the
nextop_details group.
- On the
Interface Fields - Output pane, drag the
lnk_file_status field and drop it onto the
lnk_b_text_details field.
- Click
File > Save AccessBooks.svi to save the service interface.
Read Operation
For the program action that reads a record, the caller supplies a book's stock reference number, title, or author in the appropriate
field in the
lnk-b-details group. The program looks it up in the indexed file and returns the data back to the
lnk-b-details group. The program uses the fields contained in the
lnk-b-details group as both input and output. On input, the program expects the stock number, title, or author to be supplied; the other
data items in
lnk-b-details are ignored. On output,
lnk-b-details is used to return the record indicated by the supplied stock number, title, or author.
- Create and define the Read operation
-
- Create a new operation named
Read that uses the
BOOK entry point.
- Create a COBOL Assignment for the
lnk-function field and set its value to
1. This is the value that instructs the program to read a record.
- Create an interface output field named
lnk_file_status from the
COBOL Entry Point
lnk-file-status field.
The program functionality that reads a record gets the required record from the data file and returns it. You need a set of
output fields in which to return the fields of this record.
- Drag
lnk-b-details from the
COBOL Entry Point pane to the
Interface Fields - Output pane.
- Change the name of the
lnk_b_details interface field to
readop_details.
- Expand the tree for
readop_details and change the type of
lnk_b_retail from
number to
integer.
- Save the service interface.
- Define a reusable field
- You now need to define your input fields. In doing this, you demonstrate another feature of the Interface Mapper – Reusable
Fields. You create reusable fields from
COBOL Entry Point fields for the purpose of using them across operations. Here you create a group of reusable fields that contains only the
fields used by the service interface, eliminating those that are not:
- Drag
lnk-b-details to the
Reusable Fields pane.
- Fully expand the tree under
lnk_b_details in the
Reusable Fields pane.
- Ungroup
lnk_b_text_details so that all the items are at the same level. To do this, right-click
lnk_b_text_details; then click
Ungroup.
- Delete each elementary field in the
Reusable Fields pane except
lnk_b_title,
lnk_b_author and
lnk_b_stockno. To delete a field, either click it and press
Delete or right-click it and select
Delete from the context menu. If the tree view contracts, expand it to see what you have created.
You have defined a group of reusable fields as shown here:
![The Reusable Mapping Created for your EJB](BKGSGSDMAP17IMG-low.gif)
- Drag
lnk_b_details from the
Reusable Fields pane to the
Interface Fields - Input pane.
This creates an interface field of type
lnk_b_details. By default, its name is also
lnk_b_details.
- Group output fields
- Because this is a JSON service, all fields of the same direction must share a structure to represent the root object in the
JSON request or response. Therefore, you need to add the
lnk_file_status output field to the
readop_details group.
- On the
Interface Fields - Output pane, drag the
lnk_file_status field and drop it onto the
lnk_b_text_details field.
- Save the service interface.
Delete Operation
Like the program action that reads a record, the action that deletes a record expects the stock number, title, or author to
be supplied. The other data items in
lnk-b-details are ignored. It deletes the record indicated by the supplied stock number, title, or author.
- Create a new operation named
Delete that uses the
BOOK entry point.
Note: Reusable fields you created in a different operation remain visible in the Interface Mapper for all operations.
- Create a COBOL Assignment for the
lnk-function field and set its value to
3. This is the value that instructs the program to delete a record.
- Create an interface output field named
lnk_file_status from the
COBOL Entry Point field
lnk-file-status. This is the only required output field.
- Drag
lnk_b_details from the
Reusable Fields pane to the
Interface Fields - Input pane.
- Save the service interface; then close the Interface Mapper.