Define AccessBooks Operations

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.

Add Operation

The first logical operation to define for this Java service interface 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:

1. In the Interface Mapper, right-click the Operation button at the top of the middle pane, and select New from the context menu.
2. 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.

3. 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.

4. From the Select entry point list, click BOOK. The entry point code appears to its right.
5. Click OK.

In the Interface Mapper, you now see that the entry point fields have been placed into the COBOL Entry Point pane on the left.

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:

1. Drag lnk-file-status from the COBOL Entry Point pane to the Interface Fields pane.

   This creates an interface field called lnk_file_status. A mapping is automatically created between the new field and the entry point field it was created from. The purpose of this field is to relay information back to the user; you need to change its direction from Input to Output.

2. In the Direction column, double-click Input and use the drop-down list to change the direction of the lnk_file_status interface field to Output.

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:

1. Drag lnk-b-details from the COBOL Entry Point pane to the Interface Fields pane.

   The default direction, Input, is what you want because this group of fields receives data and then pass it on to the data items in lnk-b-details.

   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.

2. In the Interface Fields pane, double-click lnk_b_details
3. In the Name field, type addop_details.
4. Click OK.

Change a Type

1. If not already expanded, fully expand the tree for addop_details in the Interface Fields 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 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:

2. Double-click the number type for the lnk_b_retail field.
3. 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:

1. 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.
2. In the Value field, type 2, and then click OK.
3. Click File > Save AccessBooks.svi to save the service interface.

The Completed Add Operation

In looking a little closer as to what this all means, notice that the correspondence between the COBOL Entry Point fields and interface fields is set up when you do the drag-and-drop. If you right-click an elementary interface field, such as lnk_file_status, and click Mapping, you see a dialog box showing the COBOL Entry Point field associated with it. This correspondence is not affected by the names or order of interface fields. You can use the dialog box to alter the mapping if you want.

In the messages passed between the service and a client, the interface fields are identified by keywords. Their names in the Interface Fields pane are used as the keywords. Their order in the Interface Fields pane is the order in which they are seen by a client, so it is good practice to be aware of this order. You can re-order fields by dragging them.

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

1. In the Interface Mapper, right-click the Operation button at the top of the middle pane, and select New from the context menu.
2. 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.

3. In the box under Select entry point, click BOOK.

   The entry point details are shown on the right.

4. Click OK.

   The Interface Fields and COBOL Assignments panes for the new operation are blank in anticipation of new definitions for this operation.

Define the Next operation

1. 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.
2. Create an interface field named lnk_file_status from the COBOL Entry Point field lnk-file-status; then set its direction to Output.

   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.

3. Drag lnk-b-details from the COBOL Entry Point pane to the Interface Fields 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.

4. Double-click the lnk_b_details field name in the Interface Fields.
5. Change the name to nextop_details, and change the direction to Output; then click OK.
6. 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.

7. In the COBOL Entry Point pane, fully expand lnk-b-details.
8. Drag lnk-b-stockno from the COBOL Entry Point pane to the Interface Fields pane and drop it onto the lnk_file_status interface field. This ensures that the new interface field 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.

9. On the Interface Fields pane, drag the lnk_file_status field and drop it onto the lnk_b_text_details field.
10. Click File > Save AccessBooks.svi to save the service interface.

The Completed Next Operation

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

1. Create a new operation named Read that uses the BOOK entry point.
2. 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.
3. Create an interface field named lnk_file_status from the COBOL Entry Point field lnk-file-status; then set its direction to Output.

   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.

4. Drag lnk-b-details from the COBOL Entry Point pane to the Interface Fields pane.
5. Change the name of the lnk_b_details interface field to readop_details, and change its direction to Output.
6. Expand the tree for readop_details and change the type of lnk_b_retail from number to integer.
7. 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:

1. Drag lnk-b-details to the Reusable Fields pane.
2. Fully expand the tree under lnk_b_details in the Reusable Fields pane.
3. 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.
4. 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:
   
   

5. Drag lnk_b_details from the Reusable Fields pane to the Interface Fields pane. Be sure not to drop it amongst the fields that are subordinate to readop_details.

   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.

1. On the Interface Fields pane, drag the lnk_file_status field and drop it onto the lnk_b_text_details field.
2. Save the service interface.

The Completed Read Operation

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 and define the Delete operation

1. 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.
2. 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.
3. Create an interface field named lnk_file_status from the COBOL Entry Point field lnk-file-status; then set the direction to Output. This is the only required output field.
4. Drag lnk_b_details from the Reusable Fields pane to the Interface Fields pane.
5. Save the service interface; then close the Interface Mapper.

The Completed Delete Operation