Example: Using placeholders, arrays and nested arrays

In this example you implement a combination of macro and mapped methods that use placeholders, arrays, and nested arrays.

This example starts by showing you a copybook containing data items for a company whose employees have credit cards and then demonstrates how to implement a set of methods to do different functions.

The COBOL copybook

The following copybook has been created for a company whose employees have several credit cards. You can use this copybook to implement some utilities on the employees and on their credit cards.

01  Company.
    05  Name                    PIC X(20).
    05  Symbol                  PIC X(8).
    05  Employee   OCCURS 50 TIMES.
        10 Empnumber            PIC 9(5).
        10 Empname              PIC X(20).
        10 Score                PIC 9(4).
        10 CreditCard  OCCURS 4 TIMES.
            15 Bankname         PIC X(6).
            15 Cardnumber       PIC 9(15).
            15 Expense          PIC 9(15).
            15 Validity.
                20 Year         PIC 9(4).
                20 Month        PIC 9(2).

The XOM and the BOM

You use the copybook to generate the XOM, and then generate the BOM from the COBOL XOM. In this example, when you generate the BOM, you name the BOM package empcredit and you get the following BOM classes:

These classes are expressed in the BOM model as follows:

package empcredit;

   public class Company
   {
       public string name;
       public string symbol;
       public empcredit.Employee[] employee;
   }

   public class Employee
   {
       public string empname;
       public int empnumber;
       public int score;
       public empcredit.CreditCard[] creditcard;
   }

   public class CreditCard
   {
       public string bankname;
       public int cardnumber;
       public int expense;
       public empcredit.Validity validity;
   }

   public class Validity
   {
       public int year;
       public int month;
   }

You can see the BOM model by double-clicking bom.model in your rule project and selecting the model.bom tab.

BOM method implementation

You now implement some methods for the following classes:

Company
CreditCard
Employee

You use a combination of mapped and macro methods. The following examples show first the CreditCard class, then the Employee class, and finally the Company class. This ordering introduces you first to a simple macro method, then a mapped method, and then a combination of a macro method and more complex mapped methods.

CreditCard class method

For the CreditCard class, you implement the method yearOfExpiration. This method gets the year an employee’s credit card expires. You implement this method as a macro method:

Method type	Method	Description
macro	yearOfExpiration ();	Gets the year the credit card expires by using a macro method.

You implement this method as follows:

YEAR OF VALIDITY OF {this}

Here, {this} refers to a specific credit card object. Note that you do not use a {return} variable, because a macro represents a value.

Employee class method

For the Employee class, you implement the boolean method hasCreditCardOfBank.

Method type	Method	Description
mapped	`boolean hasCreditCardOfBank(String bankname);`	Tests if an employee owns a credit card belonging to a bank.

You implement this method by using the COBOL Method Body Editor:

PERFORM VARYING CARDINDEX FROM 1 BY 1 UNTIL CARDINDEX > 4
  IF BANKNAME OF CREDITCARD OF {this}(CARDINDEX)= {bankname} 
    SET {return} TO TRUE
    END-IF
END-PERFORM

In this method you loop inside the CREDITCARD table data item and use indexes to designate the correct item.

Company class methods

For the Company class, you implement three mapped methods and a macro method:

Method type	Method	Description
mapped	`String getEmployeeNameWithNumber(int empNumber);`	Gets an employee name by using an employee number.
mapped	`Employee getEmployeeWithNumber(int empNumber);`	Gets an employee by the employee number.
mapped	`int rankEmployee(Employee emp);`	Ranks an employee and returns an integer as the result of the ranking.
macro	`boolean isIBM();`	Checks that information is being retrieved for the correct company. In this example, the company is IBM®. You implement the check by using the Symbol value. This method is a simple COBOL expression so you implement it as a macro method.

You implement these methods by using the COBOL Method Body Editor:

String getEmployeeNameWithNumber(int empNumber);
```
PERFORM VARYING EMPINDEX FROM 1 BY 1 UNTIL EMPINDEX > 50
  IF EMPNUMBER OF EMPLOYEE OF COMPANY(EMPINDEX) = {empNumber}
    MOVE EMPNAME OF EMPLOYEE(EMPINDEX) OF COMPANY TO {return}
    END-IF
END-PERFORM
```
This method creates a loop, for which you must define an index variable for the array. For example, this sample code uses the EMPINDEX variable as an index variable for EMPLOYEE.

If you want, you can include an external copybook. You define this index in the external copybook. For information about including external files in the generated COBOL code, see Example: Creating a mapped method to call external COBOL code.

This method uses the PERFORM VARYING clause to loop on employees. The loop terminates when it finds the first element.
Employee getEmployeeWithNumber(int empNumber);
```
PERFORM VARYING EMPINDEX FROM 1 BY 1 UNTIL EMPINDEX > 50
   IF EMPNUMBER OF EMPLOYEE OF COMPANY(EMPINDEX) = {empNumber}
      SET ADDRESS OF {return} TO ADDRESS OF EMPLOYEE OF COMPANY(EMPINDEX)
   END-IF
END-PERFORM
```
This code assumes that you have declared the following data items in the local copy:
```
01  EMPINDEX    PIC 9(3)
```
This method shows you an example of using the {} placeholder. The method differs from the previous one in that it returns an object as the result.

int rankEmployee(Employee emp);

IF SCORE OF {emp} < 100
    MOVE 1 TO {return}
  ELSE
    IF SCORE OF {emp} < 200
    MOVE 2 TO {return}
  ELSE
    IF SCORE OF {emp} < 300
    MOVE 3 TO {return}
    END-IF
    END-IF
END-IF

When a parameter is an object, you can use the {emp} argument to access its fields directly.

boolean isIBM();
```
SYMBOL OF {this} = "IBM"
```
The placeholder {this} refers to the COBOL data item matching the current BOM class. To refer to a data member, just specify its name.