Tutorial: Code a User Rule

When we defined the BLDRAPPL application in AppMaster Buider, we created a global user rule object named CALCINV. Because CALCINV is global, all programs generated from our application automatically include the CALCINV rule. In this tutorial, we populate the user rule object with code. In a later tutorial, we call the rule from Online Express.

We use the following code to populate the CALCINV user rule. We have added line numbers so that each line is easily identified for the purpose of discussing what this user rule does:

0001       % DEFINE $CALC-INV-VALUE( &PRE,
0002       % ...  &PRICE-FLD, &UNITS-FLD )
0003           % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
0004               % &PART-INVENTORY-SEEN = 1
0005               % SET WORKING-STORAGE
0006               &08+01 WS-INVENTORY-VALUE     PIC S9(08)V99.
0007               % SET PROCEDURE
0008           % END
0009           IF &PRE+-&PRICE-FLD = ZERO
0010           ...  OR &PRE+-&UNITS-FLD = ZERO
0011               MOVE ZERO TO WS-INVENTORY-VALUE
0012           ELSE
0013               COMPUTE WS-INVENTORY-VALUE =
0014               ... &PRE+-&PRICE-FLD
0015               ... * &PRE+-&UNITS-FLD
0016       % END
		

Lines 0001 - 0002:

       % DEFINE $CALC-INV-VALUE( &PRE,
       % ...  &PRICE-FLD, &UNITS-FLD )
		

These lines identify the name of the rule, $CALC-INV-VALUE, and three parameters, &PRE, &PRICE-FLD, and &UNITS-FLD. All user rule names begin with a dollar sign ($). Values for the three parameters must be supplied when the rule is called. In this case, the user rule is looking for a prefix, which in this case represents a prefix for the Working-Storage field names, the remainder of the name of a Working-Storage field that contains the price of an item (&PRICE-FIELD), and remainder of the name of the Working-Storage field that contains the number of units being ordered (&UNITS-FLD).

The two lines here comprise one logical line of code, continued on a second line using the % sign to identify the line as Customizer code, and ellipses (...) to indicate the continuation.

Lines 0003 - 0008:

0003           % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
0004               % &PART-INVENTORY-SEEN = 1
0005               % SET WORKING-STORAGE
0006               &08+01 WS-INVENTORY-VALUE     PIC S9(08)V99.
0007               % SET PROCEDURE
0008           % END
		

Here we have an IF structure comprised of MFG structures. MFG structures are identified by the percent (%) sign in column 8 of each line. This % IF structure does the following:

Lines 0003 - 0004

0003           % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
0004               % &PART-INVENTORY-SEEN = 1

If the parameter &PART-INVENTORY-SEEN is not defined, &PART-INVENTORY-SEEN is defined and its value set to 1. If this Customizer rule is encountered again in the generation process, the MFG will not execute the remainder of the % IF structure, preventing the code it generates from being generated twice.

Line 0005

0005               % SET WORKING-STORAGE

The MFG is set to create a Working-Storage structure. Because this code appears in our program in the Procedure Division, it is necessary to temporarily assign the code generator back to Working Storage so that the structure created appears in the proper section of the generated code.

Line 0006

0006               &08+01 WS-INVENTORY-VALUE     PIC S9(08)V99.

In the Working-Storage section, on a new line beginning in column 8, the MFG writes an 01-level data structure for WS-INVENTORY-VALUE. This data structure holds the value that is eventually sent to the INV-VALUE screen field.

Line 0007

0007               % SET PROCEDURE

The MFG is reset to continue in the Procedure Division.

Line 0008

0008           % END

Indicates the end of the % IF structure.

Lines 0009 - 0015:

0009           IF &PRE+-&PRICE-FLD = ZERO
0010           ...  OR &PRE+-&UNITS-FLD = ZERO
0011               MOVE ZERO TO WS-INVENTORY-VALUE
0012           ELSE
0013               COMPUTE WS-INVENTORY-VALUE =
0014               ... &PRE+-&PRICE-FLD 
0015               ... * &PRE+-&UNITS-FLD
		

This IF/ELSE structure is comprised of COBOL syntax, using the variables defined in lines 0001 and 0002 of this user rule. This IF component of the structure checks to see if the value in the Working-Storage fields that store the price of an item or the number of units is zero (0). If so, zero is moved to the WS-INVENTORY-VALUE field. If the value in either field is not zero, the ELSE component of the structure calculates the value of the inventory and puts that value into the WS-INVENTORY-VALUE field.

The MFG writes this IF/ELSE structure to the generated program, substituting the parameter values you provide when you call the user rule.

Line 0016:

0016       % END

Indicates the end of the user rule.

Code the CALCINV user rule

1. On the Project Explorer, expand c:\amb_tutorials\BLDRAPPL\dev1 > BLDRAPPL > GLOBAL.
2. Double-click the CALCINV user rule. This starts the Program Painter.
3. Type the following, starting in column 8:

          % DEFINE $CALC-INV-VALUE( &PRE,
          % ...  &PRICE-FLD, &UNITS-FLD )
              % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
                  % &PART-INVENTORY-SEEN = 1
                  % SET WORKING-STORAGE
                  &08+01 WS-INVENTORY-VALUE    PIC S9(08)V99.
                  % SET PROCEDURE
              % END
              IF &PRE+-&PRICE-FLD = ZERO
              ...  OR &PRE+-&UNITS-FLD = ZERO
                  MOVE ZERO TO WS-INVENTORY-VALUE
              ELSE
                  COMPUTE WS-INVENTORY-VALUE =
                  ... &PRE+-&PRICE-FLD
                  ... * &PRE+-&UNITS-FLD
          % END

4. Close the Program Painter, and click Yes when prompted to save the file. AppMaster Builder saves the file in the USERMACS project subdirectory.

This completes the tutorial. Next, please complete Tutorial: Map Screen Fields.