Define ACCTWS Operations

Guides you through the process of adding the operations that enable the ACCTWS Web service to interact with the ACCT application.

Each service interface you create is comprised of a set of operations. For a CICS Screen service interface, each operation addresses a screen encountered by the application. In this section of the tutorial, you define three operations that enable users to retrieve and display the account information you provided earlier in this tutorial when interacting with the ACCT application. You also define an operation to handle error conditions.

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 ACCTWS.svi from the Visual Studio menu.

Define the Start operation

The purpose of the Start operation is to connect to the ACCT application.

  1. In the Interface Mapper, right-click the Operation button, and then select New from the context menu.
  2. In the Operation Name field, type Start.
  3. Leave the default values in the Active Screen and Previous Screen fields.
  4. In the Transaction ID field, type ACCT.
  5. Click OK.

Define the Send Request operation

The Send Request operation interacts with the ACCT application, automatically setting the request type to D (Display), and provides a means for a user to enter the account number of the record to be displayed.

Create the Send Request operation
  1. Right-click the Operation button, and then select New from the context menu.
  2. In the Operation Name field, type Send Request.
  3. From the Active Screen drop-down list, click ACCTSET.ACCTMNU.

    This is the name defined in the acctset.bms map for the ACCOUNT FILE: MENU screen, which is the initial screen called when the ACCT application starts.

  4. Leave the default value, ANY SCREEN, in the Previous Screen field.
  5. Leave the Transaction ID field blank. This operation does not start a transaction.
  6. Leave Create Default Mappings unchecked.
  7. Click OK.

    This returns you to the Interface Mapper and renders the ACCTSET.ACCTMNU screen in the CICS Screen pane.

Assign a value to the REQUEST TYPE input field
As you learned from running this application in its original form, if you want to display account information, you need to provide the application with a D (for Display) in the REQUEST TYPE screen field. Rather than requiring the user to enter the request type value manually, you create an assignment to provide the value automatically.
  1. On the CICS Screen pane, hover over the input field next to the REQUEST TYPE label. Note that the name of the input field is REQM.
    Note: If the screen rendering is too small, resize it by grabbing and pulling on the perimeter.
  2. In the Assignments pane, right-click and select New Assignment from the context menu.
    Note: The Assignments pane is located below the Mappings pane. If you cannot see the Assignments pane, drag the bottom of the Mappings pane upwards until it appears.
  3. From the Assign to drop-down list, select REQM.
  4. In the Field 1/Operand 1 field, type D, which is the value that tells the application to display information.
  5. Click OK.
Map the ACCOUNT input field to an interface field
Instead of assigning a value for the account number, you can enable users to enter an account number manually by mapping the ACCOUNT input field to an interface field.
  1. On the CICS Screen pane, identify the name of the input field for ACCOUNT by hovering over the field. Note that the name of this input field is ACCTM.
  2. Click and drag the ACCTM field to the Interface Fields pane and drop it there.

    The interface mapper creates a new interface field named ACCTM.

    When you eventually generate a client for a service interface, the name of each interface field is used as a label for the corresponding input field on the client UI.

    The name ACCTM does not adequately convey the purpose of the field to an end user. Therefore, you need to rename it to be easily recognized as the input field for the account number.

  3. In the Interface Fields pane, double-click ACCTM.
  4. In the Name field, type AccountNumber.

    The other fields on this dialog box are accurate so no additional adjusting is necessary here.

  5. Click OK.

    Notice that the Mappings pane shows the interface field with its new name, AccountNumber, mapping to the COBOL field ACCTM.

Assign the Enter key to send values to the application
You need to define an AID key (for example, Enter) that the user can push to send the provided input values to the application.
  1. In the Assignments pane, right-click and select New Assignment from the context menu.
  2. From the Assign to drop-down list, click ATTENTION ID.

    This is the field that defines which AID key to use.

  3. From the Field 1/Operand 1 drop-down list, click ENTER.
  4. Click OK.

Define the Display Account Data operation

The Display Account Data operation retrieves the requested account information and displays it in the client UI.

Create the Display Account Data operation
  1. Right-click the Operation button, and then select New from the context menu.
  2. In the Operation Name field, type Display Account Data.
  3. From the Active Screen drop-down list, click ACCTSET.ACCTDTL.

    This is the name defined in the acctset.bms map for the ACCOUNT FILE: RECORD DISPLAY screen, which is the screen called when the user sends a request.

  4. In the Previous Screen field, leave the default value of ANY SCREEN because in this service interface, the ACCTSET.ACCTDTL screen is used only once.
  5. Leave the Transaction ID field blank. This operation does not start a transaction.
  6. Leave Create Default Mappings unchecked.
  7. Click OK.

    This returns you to the Interface Mapper and renders the ACCTSET.ACCCDTL screen in the CICS Screen pane.

Create interface fields
You need to identify the fields on the ACCTSET.ACCTDTL screen that contain the information you want to return to the user. For this service interface, you want to return the account number, last name, first name, and the first two address fields.
  1. Drag and drop the corresponding output field for each of the following field labels on the ACCTSET.ACCCDTL screen from the rendered screen to the Interface Fields pane:
    • SURNAME
    • FIRST
    • TELEPHONE
  2. Hover over the output fields associated with the ADDRESS label and identify the ADDR1D and ADDR2D output fields.
  3. Drag and drop the identified output fields from the rendered screen to the Interface Fields pane.
Redefine the interface fields
As with the interface field in the Send Request operation, you need to rename each of these interface fields to something more meaningful for the end user. In addition, the default direction assigned to each new interface field is Input; however, because these function as output fields in the client UI, you need to change the direction for each to Output.

Perform the following steps for each interface field:

  1. Double-click an entry on the Interface Fields list.
  2. On the Field Properties dialog box, type a new name as indicated in the table:
    Name New Name
    SNAMED LastName
    FNAMED FirstName
    TELD Telephone
    ADDR1D Address1
    ADDR2D Address2
  3. Change the direction by selecting the Output radio button.
  4. Click OK.

Define the On Error operation

You need to define an operation that returns an ACCT application error message if something goes wrong during the execution of your Web service. For example, if an end user provides an invalid account number, the ACCT application cannot retrieve the requested data, and sends an error message instead.

Create the On Error operation
  1. Right-click the Operation button, and then select New from the context menu.
  2. In the Operation Name field, type On Error.
  3. From the Active Screen drop-down list, click ACCTSET.ACCTMNU.
  4. From the Previous Screen drop-down list, click ACCTSET.ACCTMNU. This sets the operation to execute if the application sends a second consecutive ACCTSET.ACCTMNU screen, indicating an error in processing the input.
  5. Leave the Transaction ID field blank. This operation does not start a transaction.
  6. Leave Create Default Mappings unchecked.
  7. Click OK.

    The CICS Screen pane now shows the ACCTSET.ACCTMNU screen.

Create an interface field
You need to identify the field that the ACCT application uses to send error messages, and then create an interface field to display its output.
  1. On the ACCTSET.ACCTMNU screen, hover over the bottom-most field.

    As you can see in the popup, the name of this field is MSGM. It is the output field for ACCT application messages.

  2. Drag the MSGM field from the rendered screen to the Interface Fields pane and drop it there.
  3. In the Interface Fields pane, double-click MSGM and change its name to ErrorMsg and its direction to Output.
    Note: It seems logical to name this output field Message. However, MESSAGE is a COBOL reserved word, and the Interface Mapper does not allow COBOL reserved words to be used as names for interface fields.

Save and close the Interface Mapper

You have now defined all of the required operations for your CICS Screen service interface. Before proceeding, be sure you have saved your work, and then close the Interface Mapper:

  1. From the Visual Studio main menu, click File > Save ACCTWS.svi.
  2. Click the x on the ACCTWS.svi tab to close the Interface Mapper.
Parent topic: Tutorial: CICS Screen Web Service
Previous topic: Create the ACCTWS Service Interface
Next topic: Create and Configure a deploy Directory