Chapter 3 Working with the AI Component Builder

Mapping CICS Components to AI Components

This section contains information about the relationships between target CICS programs and corresponding components in AI for CICS and Jaguar.

This section includes the following topics:

• Target CICS Programs and Method Names
• Result Sets and Method Return Value
• Parameter Information
• An Illustration of CICS Program-to-Component Mapping

Target CICS Programs and Method Names

Each Application Integrator component deployed to Jaguar contains one or more methods, each of which corresponds to a target CICS program. When you add a method to a component, the Component Builder uses the name of the target CICS program, with the first character in upper case and the subsequent characters in lower case.

Result Sets and Method Return Value

When the Component Builder parser detects an OCCURS clause in the CICS program, it maps the OCCURS clause to a result set, establishing one result set field for each field in the OCCURS clause in the COMMAREA definition.

The following table shows how the number of OCCURS clauses encountered are mapped in Jaguar:

See Chapter 2, "Getting Ready to Use AI for CICS," for restrictions on OCCURS clauses.

Parameter Information

This section covers the following topics:

• Parameter Names
• Parameter Modes

Parameter Names

For each method in an AI for CICS component, each parameter corresponds to the fields from the COMMAREA that are described by the COBOL data definition. Parameter names are derived from the corresponding COBOL fields and are altered to conform to valid Java field names. For example, the Component Builder keeps the first character in upper case, makes characters immediately following dashes ("-") in upper case, and removes the dashes.

You can also alter parameter names in the Component Builder.

Parameter Modes

Because the COBOL data definition does not indicate which fields the CICS program uses in input, input/output, or output, the Component Builder sets the defaults to inout for all fields. You can change the mode to in, out, or inout.

However, you must set the mode correctly for all fields based on how the CICS program uses the field. For example:

• If the CICS program uses a field for a database query, or if it uses the field in a calculation but never alters the value, define the field in the Component Builder with a mode of in.
• If a field contains a newly-calculated or derived value, define it in the Component Builder as out.
• If a field used by the CICS program has a value that can change, define the field as inout.

An Illustration of CICS Program-to-Component Mapping

The example in this section shows how AI for CICS maps COBOL programs to components.

A CICS COBOL program called ZXR150R is designed to get a list of customer names, addresses, and phone numbers of all customers for a specific account representative, in descending order of total sales amount. The program caller can limit the number of customers that the program will return, for example, up to ten.

The following COBOL data definition describes the COMMAREA for the CICS program:

01 COMMAREA.
   05 ACCOUNT-REP-ID          PIC X(5).
   05 NUMBER-OF-CUSTOMERS     PIC 9(4) COMP-3.
   05 ACCOUNT-REP-QUOTA       PIC 9(8)V9(2) COMP-3.
   05 CUSTOMER-DATA OCCURS 1 TO 500 DEPENDING ON
    NUMBER-OF-CUSTOMERS.
     10 CUST-NAME             PIC X(25).
     10 CUST-ADDR             PIC X(25).
     10 CUST-CITY             PIC X(15).
     10 CUST-STATE            PIC C(2).
     10 CUST-ZIP              PIC X(10).

The preceding data definition does not clearly indicate whether the parameters are used for input, output, or both.

The Component Builder uses this definition to set the modes for the parameters as follows:

Assume that the logic for the CICS program is as follows:

• The ACCOUNT-REP-ID field is used to query for customers serviced by that account rep, in descending order of the customers year-to-date sales.
• The NUMBER-OF-CUSTOMERS field will be used to limit the number of customers.
• The data from the query populates the fields in the CUSTOMER-DATA group item that contains the OCCURS clause.
• If the actual number of the account representative's customers is less than the value in the NUMBER-OF-CUSTOMERS field, set NUMBER-OF-CUSTOMERS to the actual number of customers.
• Query the database to find this account representative's sales quota and insert this value in the ACCOUNT-REP-QUOTA field.
• You may want to change the method name that is defaulted from the CICS program (altered by AI for CICS to zxr150r) to getTopCustomerList, which is more meaningful.

You must set parameter modes as follows:

• Because the CICS program only uses the ACCOUNT-REP-ID field to query information and does not alter its value, change the mode of the accountRepId parameter from inout to in.
• Because the caller can use the NUMBER-OF-CUSTOMERS field to indicate the maximum number of customers to return, and the CICS program itself can alter the field to contain a different value, allow the mode of the numberOfCustomers parameter to remain as inout.
• Because the ACCOUNT-REP-QUOTA field is used exclusively to pass a value back from the CICS program, change the mode of the accountRepQuota parameter to out.

The Resulting Component Definition

If you customize the method name, parameter names, and parameter modes of this component as described, it will accurately represent the CICS program.

In Jaguar, this component will be called AccountRep (the same name you assigned the component using the Component Builder), and it will have a method named getTopCustomerList that returns a ResultSet. The parameters for that method will be defined appropriately, based on their functions in the program.

Copyright © 1999 Sybase, Inc. All rights reserved.