Provides step-by-step instructions that guide you through the process of defining four operations for the AccessBooks Java
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 COBOL, you describe a data item's data type precisely, using its picture clause. Java uses its own set of data types. The
Interface Mapper enables you to create mappings between the COBOL types in your program and the types available in Java.
You use the Interface Mapper to define streamlined access to your program by defining an operation for each of the program's
four possible actions - Read record, Add record, Delete record, and Next record. Each operation requires the client to send
just the data needed by that particular operation.
Tip: As you define these operations, save your work periodically by clicking
File > Save AccessBooks.svi from the Visual Studio menu.
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:
- 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
Output
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 output field to contain the
value so the client can send it to the application:
- Define a Group of Interface
Input
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
input
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
BigDecimal. 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
int. You change the type of the
lnk-b-retail interface field to reflect this:
- Double-click the
BigDecimal type for the
lnk_b_retail interface field.
- Select
int 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.
- In the
Value field, type
2, and then click
OK.
- Click
File > Save
AccessBooks.svi to save the Java 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
Operation at the top left, 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 Java 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
-
- 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 and drop it. This ensures that the new interface field is first on the list and thus the first field to supply its value
to the program.
- 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
input
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
BigDecimal to
int, just as you did for the Add operation.
- Click
File > Save AccessBooks.svi to save the Java 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
input
field named
lnk_file_status from the
COBOL Entry Point field
lnk-file-status.
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
BigDecimal to
int.
- Save the Java 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. In Java terms, a reusable field is a custom record according to the
CustomRecord interface defined in the Common Client Interface (CCI). For Java-based service interfaces, the Interface Mapper
assigns a custom data type to interface fields created from reusable fields based on the CCI. Here you create a group of reusable
fields that contains only the fields used by the Java interface, eliminating those that are not:
- Drag
lnk-b-details from the
COBOL Entry Point pane 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 - Output 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.
- Because Java requires that group fields have unique names across operations, change the name of
lnk_b_details interface field to
readop_input.
- Save the Java 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- Output pane and rename the new interface field
delete_input.
- Save the Java interface; then close the Interface Mapper by closing the
AccessBooks tab.