Chapter 1: Customization Facility Concepts

Use facility to modify APS macros and write your own

The APS Customization Facility is a high-level tool that lets you customize APS. With this tool, you can write macros--sometimes referred to as rules--to modify and supplement the default APS processing logic. Specifically, you can:

Modify and extend the APS software macros, which reside in the APSMACS PDS or data set in the APS software.
Write your own supplemental macros in the USERMACS PDS or data set in your APS Project and Group.

A Customization Facility macro is a source code component that you can reuse in any APS application. You write macros using high-level Customization Facility structures that are similar to COBOL structures, but offer more functionality with less coding. To call macros in your programs, simply assign macro calls to Online Express program functions and control points; when writing programs using the Program Painter, you simply write macro calls in the programs. In these calls, you pass values to variables in the macros according to your program requirements. For example, APS might process a macro that performs a loop and builds a table, based on the size, data name, and PIC clause values that you pass to it. You generate programs that invoke macros just as you generate any APS program. At generation, the Customization Facility processes the macros and includes them in your program; no extra generation steps are required.

The Customization Facility Control System lets APS administrators regulate developer access to user-defined Customization Facility macros. Use it to do any of the following:

Restrict all developers from using any user-defined macros (default).
Allow all developers to use any user-defined macro.
Specify selected user-defined macros that all developers can use.

Types of source code

You can write macros containing any combination of the following types of source code:

Customization Facility structures.
COBOL or COBOL/2.
S-COBOL, a set of COBOL-like APS programming structures that you can use in macros and APS programs. For information, see the APS Reference.

Customization Facility structures

The Customization Facility provides the following structures that you can use in macros and APS programs as well.

Structure	Description
% BEGIN	Positions source code in a specific column in the output.
% DECLARE	Lets you organize macro symbols into tables, providing an associative memory capability
% DEFINE	Use to begin defining a macro; assign its name and variables that receive values from macro calls.
% ESCAPE	Exits a macro.
&function	Executes predefined Customization Facility functions.
% IF ... % ELSE-IF ... % ELSE	Evaluates one or more conditions.
% INCLUDE	Opens, reads, and processes a file in a macro.
% LOOKUP	References a % DECLARE table.
% REPEAT	Establishes a loop.
% SET	Specifyies the program location where the Customization Facility places source code.
% UNTIL/WHILE	Establishes a loop and test a condition; use to add a condition test to a % REPEAT loop.
% &variable = value	Assigns a value to a variable.
<>	APS-supplied macros are assigned "less-than" (<) and "greater than" (>) as evaluation brackets.

Customization Facility structures use the reserved symbols described below.

Symbol	Description
%	When % is the first character on a line, it identifies the entire line as a Customization Facility statement. When % is the first character in a pair of evaluation brackets, it identifies the source in the brackets as a Customization Facility statement.
&	&dataname is a variable. Generally, you code variables in macros and assign values to them in your APS programs. In addition, you can both define and assign values to variables in your programs. You can use variables in a Customization Facility statement or embed them in a line of COBOL or S-COBOL. &functionname is a predefined Customization Facility function.
$	$macroname is a macro definition statement or macro call. Generally, you code macro definitions in your USERMACS files, and macro calls in your programs. You can use macro calls in a Customization Facility statement or embed them in a line of COBOL or S-COBOL.
+	&dataname+suffix appends a literal suffix to a variable. &columnnumber+source designates the column where the facility processor places source code in the output.

Define macros

You define macros in the USERMACS PDS or data set in your APS Project and Group. All macros:

Begin with a % DEFINE statement that assigns a name to the macro and can include any number of formal argument variables. A formal argument variable receives values, called actual arguments, from the macro calls that invoke the macro.
Contain any combination of Customization Facility structures, COBOL or COBOL/2 source, or S-COBOL source.
End with an % END statement, or any source code starting in the same column as the % DEFINE statement.

Include macros in applications

To include a macro in your application, you specify its macro library name on the Application Painter, in the User Mac field. In addition, you specify in the Location field the program location where you want to include it. Alternatively, you can code an % INCLUDE statement in the program at the desired location.

Invoke macros in programs

To invoke a macro, use one of the following methods depending on which APS tool you use to define your program:

APS Tool	Invocation Method
Online Express	Assign a macro call to a program function or control point, using the Alternate Functions, PF Key Functions, Special Key Definition, Control Points, or Database Call Tailoring window. In the call, you can pass values to the variables in the macro.
Program Painter	Write a macro call at the desired program location. In the call, you can pass values to the variables in the macro.

Generation processes

When you generate an application that invokes Customization Facility macros, APS processes the application as follows:

Ensures that each component of your application exists.
Generates APS symbols for the windows or screens, for use by the APS Precompiler.
Generates the window or screen source native to your DC environment, such as BMS or MFS mapsets.
Arranges all APS program specifications into proper COBOL program organization.
Inserts all externally-defined components--such as APS macros, user-defined Customization Facility macros, COBOL copylibs, and APS data structures--at the program locations you specify in the programs or Application Painter.
Processes all APS macro and user-defined Customization Facility macro symbols and structures into COBOL source as follows:
- Replaces all variables with their assigned values
- Passes all actual arguments of macro calls to the formal arguments of their coresponding macro definitions
- Builds loop tables and inserts them in the program
- Replaces all Customization Facility functions with their underlying source code
- Moves all source code to the program locations you specify using % SET statements
- Calls all macros and files called within other macros and processes them
Processes all APS database and data communications calls into COBOL source.
Translates any APS Report Writer source to COBOL source.
Writes a temporary error message file and sorts it into the COBOL compiler error message file. The combined error message file presents messages sorted by program line number, with both types of messages appearing where appropriate.

Macro processing example

The following example shows two sample user macros--$CONSTRUCT-FD and $DAYDEF--and how a program invokes and uses them. To illustrate how APS processes macros, we show the program at two stages of generation:

Before APS inserts the macro source in the program. The program at this stage is stored in the GENSRC PDS or data set in your Project and Group.
After APS inserts the macro source in the executable COBOL program.

The macros are defined in a USERMACS file as shown below. The $CONSTRUCT-FD macro writes FD statements. The developer calls the macro in the program and passes arguments--the FD file names--to the FD file name variable in the macro. The $DAYDEF macro builds a Working-Storage symbol table. The developer calls the macro repeatedly in the program and passes arguments--literal strings and their lengths--to the string and length variables in the macro.

User-defined macros:

% DEFINE $CONSTRUCT-FD( &FILE-NAME)
    FD  &FILE-NAME
        BLOCK CONTAINS 0 RECORDS
        LABEL RECORDS ARE STANDARD.
% END
 
% DEFINE $DAYDEF( &DAY, &LEN)
    % &DAYCTR = &DAYCTR + 1
    02  FILLER.
      03  FILLER          PIC S9(2) COMP SYNC VALUE +&LEN.
      03  FILLER          PIC X(9) VALUE &QT&DAY&QT.
% END

Program before APS includes the macro source:

 % &REC-LEN = 121                                     315.
 % &DAYCTR = 0                                        316.
 % &QT = "'"                                          317.
                                                      318.
 IDENTIFICATION DIVISION.                             319.
 PROGRAM-ID.                     EXAMPLE3.            320.
*SPECIAL CONSIDERATIONS.                              321.
*    SAMPLE PROGRAM: CALLS TO MACROS THAT WRITE       322.
*    AN FD STATEMENT AND BUILD A TABLE.               323.
                                                      324.
 ENVIRONMENT DIVISION.                                325.
 INPUT-OUTPUT SECTION.                                326.
 FILE-CONTROL.                                        327.
     SELECT INPUT-FILE         ASSIGN-UT-S-INPUT.     328.
     SELECT OUTPUT-FILE        ASSIGN-UT-S-OUTPUT.    329.
                                                      330.
 DATA DIVISION.                                       331.
 FILE SECTION.                                        332.
                                                      333.
 $CONSTRUCT-FD( 'INPUT-FILE')                         334.
 01  INPUT-RECORD                PIC X(&REC-LEN).     335.
                                                      336.
 $CONSTRUCT-FD( 'OUTPUT-FILE')                        337.
 01  OUTPUT-RECORD               PIC X(&REC-LEN).     338.
 WORKING-STORAGE SECTION.                             340.
                                                      341.
 01  DAY-TABLE.                                       342.
   $DAYDEF( 'SUNDAY', 6)                              343.
   $DAYDEF( 'MONDAY', 6)                              344.
   $DAYDEF( 'TUESDAY', 7)                             345.
   $DAYDEF( 'WEDNESDAY', 9)                           346.
   $DAYDEF( 'THURSDAY', 8)                            347.
   $DAYDEF( 'FRIDAY', 6)                              348.
   $DAYDEF( 'SATURDAY', 8)                            349 
 01  DAY-TABLE-REDEF   REDEFINES DAY-TABLE            350.
   02  DAY-ENTRY   OCCURS &DAYCTR.                    351.
     03  DAY-LEN   PIC S9(2) COMP SYNC.               352.
     03  DAY-BOL   PIC X(9).                          353.

Program after APS includes the macro source:

030200                                                315 
030800                                                316.
031100                                                317.
031800                                                318.
031900 IDENTIFICATION DIVISION.                       319.
032000 PROGRAM-ID.                     EXAMPLE3.      320.
032100*SPECIAL CONSIDERATIONS.                        321.
032200*    SAMPLE PROGRAM: CALLS TO MACROS THAT WRITE 322.
032300*    AN FD STATEMENT AND BUILD A TABLE          323.
032400                                                324.
032500 ENVIRONMENT DIVISION.                          325.
032600 INPUT-OUTPUT SECTION.                          326.
032700 FILE-CONTROL.                                  327.
032800     SELECT INPUT-FILE   ASSIGN-UT-S-INPUT.     328.
032900     SELECT OUTPUT-FILE  ASSIGN-UT-S-OUTPUT.    329.
033000                                                330.
033100 DATA DIVISION.                                 331.
033200 FILE SECTION.                                  332.
033300                                                333.
033400 FD  INPUT-FILE                                 334.
033402     BLOCK CONTAINS 0 RECORDS                   334.
033404     LABEL RECORDS ARE STANDARD.                334.
033500 01  INPUT-RECORD                PIC X(121).    335.
033600                                                336.
033700 FD  OUTPUT-FILE                                337.
033702     BLOCK CONTAINS 0 RECORDS                   337.
033704     LABEL RECORDS ARE STANDARD.                337.
033800 01  OUTPUT-RECORD               PIC X(121).    338.
033900                                                339.
034000 WORKING-STORAGE SECTION.                       340.
034100                                                341.
034200 01  DAY-TABLE.                                 342.
034300   02  FILLER.                                  343.
034302     03  FILLER   PIC S9(2) COMP SYNC VALUE +6. 343.
034304     03  FILLER   PIC X(9)  VALUE 'SUNDAY'.     343.
034400   02  FILLER.                                  344.
034402     03  FILLER   PIC S9(2) COMP SYNC VALUE +6. 344.
034404     03  FILLER   PIC X(9)  VALUE 'MONDAY'.     344.
034500   02  FILLER.                                  345.
034502     03  FILLER   PIC S9(2) COMP SYNC VALUE +7. 345.
034504     03  FILLER   PIC X(9)  VALUE 'TUESDAY'.    345.
034600   02  FILLER.                                  346.
034602     03  FILLER   PIC S9(2) COMP SYNC VALUE +9. 346.
034604     03  FILLER   PIC X(9)   VALUE 'WEDNESDAY'. 346.
034700   02  FILLER.                                  347.
034702     03  FILLER   PIC S9(2) COMP SYNC VALUE +8. 347.
034704     03  FILLER   PIC X(9)  VALUE 'THURSDAY'.   347.
034800   02  FILLER.                                  348.
034802     03  FILLER   PIC S9(2) COMP SYNC VALUE +6. 348.
034804     03  FILLER   PIC X(9)  VALUE 'FRIDAY'.     348.
034900   02  FILLER.                                  349.
034902     03  FILLER   PIC S9(2) COMP SYNC VALUE +8. 349.
034904     03  FILLER   PIC X(9)VALUE 'SATURDAY'.     349.
035000 01  DAY-TABLE-REDEF   REDEFINES DAY-TABLE.     349.
035100   02  DAY-ENTRY  OCCURS 7.                     351.
035200     03  DAY-LEN  PIC S9(2) COMP SYNC.          352.
035300     03  DAY-BOL  PIC X(9).                     353.

See...	For more information about...
% BEGIN Functions, Customization Facility	Positioning source code in a specific column in the output
% DECLARE	Organizing macro symbols into tables, providing an associative memory capability
% DEFINE	Writing macro definition statements
% ESCAPE	Exiting macros
Functions, Customization Facility	Executing predefined Customization Facility processes
% IF/ELSE-IF/ELSE	Evaluating conditions
Evaluation Brackets	Specifying the order in which the Customization Facility evaluates variable values
% INCLUDE	Opening, reading, and processing files in macros
% LOOKUP	Referencing % DECLARE tables
% REPEAT % UNTIL/WHILE	Establishing loops and testing conditions
% SET Statements	Specifying the program location where the Customization Facility places source code; overriding processing defaults
Variable Assignment Statements	Assigning values to variables