Create an IMS service

This scenario shows how you can use the API toolkit to create an IMS phonebook service for the phone book application.

About this task

In this scenario, the API toolkit, running on a Windows workstation is used to re-create the IMS phonebook service. The service archive file uses an existing IMS COBOL copybook from the IMS phone book application.

This scenario uses the following values:

• IMS region = IMS1
• IMS program = PROG1
• IMS transaction code = IVTNO

1. Copy the IMS phone book COBOL copybook structure to a folder on your workstation, for example, C:/COPYBOOKS/IMSPHBK.cpy, making sure that the asterisks are in column 7.

         *
         *    IMS PhoneBook Transaction (IVTNO) Sample                
         *
          01  IVTNO_INPUT-MSG.                                   
            02  IN-LL          PICTURE S9(3) COMP.       
            02  IN-ZZ          PICTURE S9(3) COMP.       
            02  IN-TRANCDE     PICTURE X(10).            
            02  IN-COMMAND     PICTURE X(8).             
            02  IN-LAST-NAME   PICTURE X(10).            
            02  IN-FIRST-NAME  PICTURE X(10).            
            02  IN-EXTENSION   PICTURE X(10).            
            02  IN-ZIP-CODE    PICTURE X(7).             
                 
          01  IVTNO_OUTPUT-MSG.                                  
            02  OUT-LL         PICTURE S9(3) COMP VALUE +0.
            02  OUT-ZZ         PICTURE S9(3) COMP VALUE +0.
            02  OUT-MESSAGE    PICTURE X(40) VALUE SPACES. 
            02  OUT-COMMAND    PICTURE X(8) VALUE SPACES.  
            02  OUT-LAST-NAME  PICTURE X(10) VALUE SPACES. 
            02  OUT-FIRST-NAME PICTURE X(10) VALUE SPACES. 
            02  OUT-EXTENSION  PICTURE X(10) VALUE SPACES. 
            02  OUT-ZIP-CODE   PICTURE X(7) VALUE SPACES.  
            02  OUT-SEGNO      PICTURE X(4) VALUE SPACES.    

2. Switch to the z/OS Connect perspective.
   1. From the main menu, select Window > Open Perspective > Other
      The Select Perspective wizard opens.
   2. Click z/OS Connect.
   3. Click OK.
      The z/OS Connect perspective opens.
3. Select File > New > Project.
   The New Project wizard opens.
4. Select z/OS Connect > z/OS Connect Service Project, and click Next.
5. Specify a project name, select the project type, and optionally provide a description.
   1. Specify the project name, phonebook.
   2. For project type, select IMS Service.
   3. Click Finish to create the project.

      

   The service project is created in the Project Explorer view. The service definition opens in the service project editor, where you can configure the service and define the service interface. The IBM z/OS Connect service project editor opens, with some errors initially that indicate some required information is still missing.

   

6. For the transaction code to invoke, specify IVTNO.

In the following steps, you create the service interface for the request and response message. In this step, you import the COBOL data structure into this project and specify which fields are to be exposed for input and output messages.

7. In the Define Request and Response Service Interfaces section, click Create Service Interface.

In the following steps, you create a service interface for the request messages.

8. Specify a name such as phonebookRequest for the service interface. This service interface can later be identified as the request service interface for this service project. It can also be reused by other service projects.
9. Click the button to import the phone book copybook.
10. In the Import wizard, import the input and output message data structures.
    1. From the Import from: list, select Local file system.
    2. For the Source folder: field, select the folder where you copied the phonebook copybook to, for example, C:/COPYBOOKS
    3. From the File type: list, select COBOL data structures only.
    4. On the Data structure file: field, click Browse.
    5. In the Select File dialog, navigate to the phone book copybook file IMSPHBK.cpy on your workstation. For example, C:/COPYBOOKS and click Open.
11. Specify the data structure for the input messages:
    1. In the Data structure name list, select IVTNO_INPUT_MSG.
    2. For the Message name list, <service_interface_name> is automatically selected.
    3. For the Segment name list, ensure that Segment 1 is selected.
    4. Click Add to Import List to add this message data structure to the Import list.
    5. Click OK.
       The service interface editor opens.
12. Expand Segment 1 and IVTNO_INPUT_MSG to see all fields in the data structure.
13. The phone book service requires most of the fields for input messages, except IN_LL and IN_ZZ. These are IMS internal fields.
    1. Exclude IN_LL and IN_ZZ by clicking the check boxes in the Include column to de-select them.

       

14. Click File > Save to save the request service interface.

To define the service interface for the response message for the phone book application:

15. Click the service.properties tab to go to the overview page of your service project.
16. In the Define Request and Response Service Interfaces section, click Create Service Interface.
17. Specify a name such as phonebookResponse for the service interface.
18. Click the button to import the phone book copybook.
    1. Again, select where you are importing the phone book copybook from.
    2. Select the file type. For this tutorial, the default of COBOL data structures only is used.
    3. For the Data structure file field, click Browse.
    4. In the Select File dialog, navigate to the phone book copybook file IMSPHBK.cpy on your workstation and click Open.
19. Specify the data structure for the output messages:
    1. In the Data structure name list, select IVTNO_OUTPUT_MSG.
    2. For the Message name list, <service_interface_name> is automatically selected.
    3. For the Segment name list, ensure that Segment 1 is selected.
    4. Click Add to Import List to add this message data structure to the Import list.
    5. Click OK.
       The service interface editor opens.
20. Expand Segment 1 and IVTNO_OUTPUT_MSG to see all fields in the data structure.
21. The phonebook service requires most of the fields for output messages, except OUT_LL and OUT_ZZ. These are IMS internal fields. Exclude OUT_LL and OUT_ZZ by clicking the check boxes in the Include column to deselect them.
22. Save your changes.
    You have created two service interface files. In the Project Explorer view, two service interface files (.si files) are created in the service-interfaces/ folder in your service project.

The next step is to go back to the service project editor to select this service interface file as the request and response service interface for this project.

23. Go back to the Overview tab of your service project.
24. Select the service interface files that you created as the interface to use for the request and the response.
    1. For the Request service interface field, select the .si file that you created for the request, for example, phonebookRequest.si.
    2. For the Response service interface field, select the .si file that you created for the response, for example, phonebookResponse.si.
25. Save your changes.

The final step is to enter the details of the required configuration for this service.

26. Select the Configuration tab of your service project.
    
27. In the Connection profile: field, enter the ID value that is associated with your imsmobile_imsConnection XML element in your ims-connections.xml file, for example, Connection1_CF. Your ims-connections.xml file is located under the resources/imsmobile-config/connections directory for your server.
28. In the Interaction profile: field, enter the ID value that is associated with your imsmobile_interaction XML element in your ims-interactions.xml file, for example, InteractionProperties1. Your ims-interactions.xml file is located under the resources/imsmobile-config/interactions directory for your server.
29. Save your changes.