Define MakeCheckAppt Operations

Provides step-by-step instructions that guide you through the process of defining four operations for the MakeCheckAppt service interface.

Each service interface you create is comprised of a set of operations. In this section of the tutorial, you create one operation for each of the two functions provided by the application.

Tip: As you define these operations, save your work periodically by clicking File > Save from the Eclipse menu.
Note: By default, Visual COBOL creates REST operations that use the HTTP POST method, which enables the sending of a REST request.

MakeAppt Operation

The purpose of the MakeAppt operation is to create an appointment and store it in the system.

Create the MakeAppt Operation
  1. From the COBOL Explorer, expand ProgramREST > Web Services.
  2. Right-click the MakeCheckAppt Web service and select New > Operation from the context menu.
  3. In the Operation name field, type MakeAppt.

    This application contains only one program, schedule.cbl, that contains one entry point, SCHEDULE, from which to create the operation. By default, SCHEDULE appears in the Entry point field.

  4. Click OK.
  5. From the COBOL Explorer, expand MakeCheckAppt.
  6. Double-click MakeAppt.
    Note: If MakeAppt does not appear in the tree view, right-click MakeCheckAppt; then select Refresh from the context menu.

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

Define Interface Fields
The Schedule program needs several input items to create an appointment, including variable information such as the customer's name, the identification number of the consultant with whom the appointment is to be made, the date of the proposed appointment, and the desired time slot. You define interface fields to hold this information so that the client can send it to the application.
  1. Drag the following fields from the Linkage Section pane to the MakeAppt Operation - Interface Fields pane:
    • lnk-customer-name
    • lnk-consultant-id
    • lnk-yyyy
    • lnk-mm
    • lnk-dd
    • lnk-time-slot

    This creates interface field names similar to those of the entry point fields from which they were created. The difference is that all dashes (-) are automatically replaced with underscores (_). In addition, a mapping is automatically created between each new interface field and its corresponding entry point field.

    The purpose of the lnk_customer_name, lnk_consultant_id, lnk_yyyy, lnk_mm, lnk_ddand lnk_time_slot fields are to hold data that is sent to the application for processing; therefore, they are input fields. The default mapping direction for each of these, Input, is correct.

    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. Currently, this operation has multiple input fields; therefore those fields must be put into a group.

  2. Select all the fields in the MakeAppt Operation - Interface Fields pane; then right-click and select Group.
  3. On the Group Properties dialog box, type root_in into the Name field, and then click OK.
    Note: The default values for Occurs (0) and Direction (Input) are correct.

    Once the Schedule program receives the input information from the client, it sends back a code to indicate whether or not the requested appointment is available. The program field that receives this code is lnk-op-ok. Therefore, you need to create a corresponding interface field, and change its mapping direction from Input (default) to Output.

  4. Drag the lnk-op-ok field from the Linkage Section pane to the MakeAppt Operation - Interface Fields pane.
  5. Double-click lnk_op_ok in the MakeAppt Operation - Interface Fields pane.
  6. Click Output; then click OK.
Define COBOL Assignments
Because the MakeAppt operation executes only one program function, the value required to initialize that function remains constant. In this case, you create a COBOL Assignment field rather than an interface field, and assign it the value required by the program to ensure the execution of the specific function.

From looking at the program source code, you know that when the value in the lnk-operation field is 0, the program executes the set-appt code. Therefore, you want to assign the lnk-operation field a value of 0.

  1. In the Linkage Section pane, right-click the lnk-operation field, and select New Assignment from the context menu.
  2. In the Value field, type 0; then click OK.

    For this particular service, you want to make appointments only for one specific store. When the Schedule program executes, it reads the value in the lnk-id field to identify the store where the appointment is to be made. Therefore, you can provide the same store identification number each time the service runs by assigning a constant value.

  3. In the Linkage Section pane, expand the lnk-store-info group.
  4. In the Linkage Section pane, right-click the lnk-id field, and select New Assignment from the context menu.
  5. In the Value field, type 08780; then click OK.
  6. Click File > Save to save the service interface.

CheckAppt Operation

The purpose of the CheckAppt operation is to look up an existing appointment and return its details.

Create the CheckAppt Operation
  1. From the COBOL Explorer, expand ProgramREST > Web Services.
  2. Right-click the MakeCheckAppt Web service and select New > Operation from the context menu.
  3. In the Operation name field, type CheckAppt.

    The Entry point list shows only the SCHEDULE program, which is already selected for you. This is because each service interface can use only one program, and you specified the SCHEDULE program in the MakeAppt operation you defined earlier for this same service interface.

  4. Click OK.
  5. From the COBOL Explorer, expand the MakeCheckAppt Web Service.
  6. Double-click CheckAppt.

In the Interface Mapper, the entry point fields once again appear in the Linkage Section pane on the left.

Define Interface Fields
The CheckAppt operation uses most of the same interface fields as does the MakeAppt operation, and in addition includes an output array in which the queried appointment appears, if found. Follow these steps:
  1. Drag the following fields from the Linkage Section pane to the CheckAppt Operation - Interface Fields pane:
    • lnk-customer-name
    • lnk-consultant-id
    • lnk-yyyy
    • lnk-mm
    • lnk-dd
    • lnk-time-slot

    Because there are multiple input fields, they must be grouped to represent the JSON request structures.

  2. Select all fields in the CheckAppt Operation - Interface Fields pane, right-click, and then select Group from the context menu.
  3. On the Group Properties dialog box, type root_in into the Name field, and then click OK.
    Note: The default values for Occurs (0) and Direction (Input) are correct.
  4. Drag the lnk-op-ok field from the Linkage Section pane to the CheckAppt Operation - Interface Fields pane.
  5. In the Linkage Section pane, expand the lnk-day group.
  6. Drag the lnk-cust-id field to the CheckAppt Operation - Interface Fields pane.

    Because both lnk_op_ok and lnk_cust_id need to be output fields, you need to group them and change their direction to represent the JSON response structures.

  7. In the CheckAppt Operation - Interface Fields pane, select the lnk_op_ok and lnk_cust_id fields, right-click, and then select Group from the context menu.
  8. On the Group Properties dialog box, type root_out into the Name field.
  9. Select Output, and then click OK.
    Note: The default value for Occurs (0) is correct.
Define COBOL Assignments
The CheckAppt operation needs to execute the read-appt application code. Therefore, you need to assign the lnk-operation field a value of 1.
  1. Drag the lnk-operation field from the Linkage Section pane to the COBOL Assignments pane.
  2. In the Value field, type 1; then click OK.

    Just as you did for the MakeAppt operation, you want to assign a constant value for the lnk-id field so you are sure to query the same store each time.

  3. In the Linkage Section pane, expand the lnk-store-info group.
  4. In the Linkage Section pane, right-click the lnk-id field, and select New Assignment from the context menu.
  5. In the Value field, type 08780; then click OK.
  6. Click File > Save to save the service interface.
  7. Close the Interface Mapper.
Parent topic: Tutorial: REST Web Service
Previous topic: Create the MakeCheckAppt Service Interface
Next topic: Set Up the ESREST Enterprise Server Instance