Chapter 3: Sample Macros

This chapter contains sample macros you can use to customize APS.

% IF Structure Example

This sample macro uses the % IF structure to build a program that tests records for any specific character and replaces some occurrences of it with any other specific character, depending on the character's mode (for example, whether the character appears as a leading or trailing character, or anywhere). The variables that control what you search for and replace with (and the length of the record read) appear at the top of the program. Thus, you can use this macro many different times for many different purposes simply by changing the values of a few variables.

Input source:

 % &MODE = 'TRAILING'                                         201.
 % &REC-LEN = 121                                             202.
 % &TEST-CHR = 'SPACE'                                        203.
 % &REPLACE-CHR = 'ZERO'                                      204.
 IDENTIFICATION DIVISION.                                     205.
 PROGRAM-ID.                     EXAMPLE2.                    206.
*SPECIAL CONSIDERATIONS.                                      207.
* SAMPLE PROGRAM TO READ RECS WHOSE LENGTH IS DETERMINED AT   208.
* AT COMPILE-TIME & REPLACE SOME OCCURRENCES OF TEST-CHR      209.
* BY THE REPLACE-CHR (BOTH TO BE SET AT COMPILE-TIME).        210.
* REPLACEMENT MODE USED (LEADING, TRAILING, OR ALL)           211.
* IS SET AT COMPILE-TIME.                                     212.
                                                              213.
 ENVIRONMENT DIVISION.                                        214.
 INPUT-OUTPUT SECTION.                                        215.
 FILE-CONTROL.                                                216.
     SELECT INPUT-FILE         ASSIGN-UT-S-INPUT.             217.
     SELECT OUTPUT-FILE        ASSIGN-UT-S-OUTPUT.            218.
                                                              219.
 DATA DIVISION.                                               220.
 FILE SECTION.                                                221.
                                                              222.
 FD  INPUT-FILE                                               223.
     BLOCK CONTAINS 0 RECORDS                                 224.
     LABEL RECORDS ARE STANDARD.                              225.
 01  INPUT-RECORD                PIC X(&REC-LEN).             226.
                                                              227.
 FD  OUTPUT-FILE                                              228.
     BLOCK CONTAINS 0 RECORDS                                 229.
     LABEL RECORDS ARE STANDARD.                              230.
 01  OUTPUT-RECORD               PIC X(&REC-LEN).             231.
                                                              232.
 WORKING-STORAGE SECTION.                                     233.
                                                              234.
 01  WS-RECORD.                                               235.
   02  WS-CHR                    PIC X OCCURS &REC-LEN.       236.
                                                              237.
 01  II                          PIC S9(3) COMP SYNC.         238.
                                                              239.
 PROCEDURE DIVISION.                                          240.
                                                              241.
 OPEN INPUT INPUT-FILE                                        242.
 OPEN OUTPUT OUTPUT-FILE                                      243.
                                                              244.
 REPEAT                                                       245.
     READ INPUT-FILE INTO WS-RECORD                           246.
 UNTIL AT END ON INPUT-FILE                                   247.
     % IF &MODE = 'LEADING'                                   248.
         REPEAT VARYING II FROM 1 BY 1                        249.
         UNTIL II > &REC-LEN                                  250.
         ... OR WS-CHR (II) NOT = &TEST-CHR                   251.
             WS-CHR (II) = &REPLACE-CHAR                      252.
     % ELSE-IF &MODE = 'TRAILING'                             253.
         REPEAT VARYING II FROM &REC-LEN BY -1                254.
         UNTIL II < 1                                         255.
         ... OR WS-CHR (II) NOT = &TEST-CHR                   256.
             WS-CHR (II) = &REPLACE-CHAR                      257.
     % ELSE-IF &MODE = 'ALL'                                  258.
         REPEAT VARYING II FROM 1 BY 1                        259.
         UNTIL II > &REC-LEN                                  260.
             IF WS-CHR (II) = &TEST-CHR                       261.
                 WS-CHR (II) = &REPLACE-CHAR                  262.
     % ELSE                                                   263.
         DISPLAY "PARAMETER ERROR IMPROPER MODE:" &MODE       264.
                                                              265.
     WRITE OUTPUT-RECORD FROM WS-RECORD                       266.
                                                              267.
 CLOSE INPUT-FILE OUTPUT-FILE                                 268.

Output source:

020500 IDENTIFICATION DIVISION.                               205.
020600 PROGRAM-ID.                     EXAMPLE2.              206.
020700*SPECIAL CONSIDERATIONS.                                207.
020800* PROGRAM TO READ RECS WHOSE LENGTH IS DETERMINED AT    208.
020900* COMPILE-TIME & REPLACE SOME OCCURRENCES OF TEST-CHR   209.
021000* BY THE REPLACE-CHR (BOTH TO BE SET AT COMPILE-TIME).  210.
021100* REPLACEMENT MODE USED (LEADING, TRAILING OR ALL)      211.
021200* IS SET AT COMPILE-TIME.                               212.
021300                                                        213.
021400 ENVIRONMENT DIVISION.                                  214.
021500 INPUT-OUTPUT SECTION.                                  215.
021600 FILE-CONTROL.                                          216.
021700     SELECT INPUT-FILE           ASSIGN UT-S-INPUT.     217.
021800     SELECT OUTPUT-FILE          ASSIGN UT-S-OUTPUT.    218.
021900                                                        219.
022000 DATA DIVISION.                                         220.
022100 FILE SECTION.                                          221.
022200                                                        222.
022300 FD  INPUT-FILE                                         223.
022400     BLOCK CONTAINS 0 RECORDS                           224.
022500     LABEL RECORDS ARE STANDARD.                        225.
022600 01  INPUT-RECORD                PIC X(121).            226.
022700                                                        227.
022800 FD  OUTPUT-FILE                                        228.
022900     BLOCK CONTAINS 0 RECORDS                           229.
023000     LABEL RECORDS ARE STANDARD.                        230.
023100 01  OUTPUT-RECORD               PIC X(121).            231.
023200                                                        232.
023300 WORKING-STORAGE SECTION.                               233.
023400                                                        234.
023500 01  WS-RECORD.                                         235.
023600   02  WS-CHR                    PIC X OCCURS 121.      236.
023700                                                        237.
023800 01  II                          PIC S9(3) COMP SYNC.   238.
023900                                                        239.
024000 PROCEDURE DIVISION.                                    240.
024100                                                        241.
024200     OPEN INPUT INPUT-FILE                              242.
024300     OPEN OUTPUT OUTPUT-FILE                            243.
024400                                                        244.
024500     REPEAT                                             245.
024600         READ INPUT-FILE INTO WS-RECORD                 246.
024700     UNTIL AT END ON INPUT-FILE                         247.
025400         REPEAT VARYING II FROM 121 BY -1               254.
025500         UNTIL II < 1                                   255.
025600         ... OR WS-CHR (II) NOT = SPACE                 256.
025700             WS-CHR (II) = ZERO                         257.
026600         WRITE OUTPUT-RECORD FROM WS-RECORD             266.
026700                                                        267.
026800     CLOSE INPUT-FILE OUTPUT-FILE                       268.

Discussion

Lines 201-204 of Input. Variables are assigned values. These variables are used in the Procedure Division to replace any trailing space with a zero.
Lines 245-247 and 266-268.
- Input: The S-COBOL REPEAT verb establishes a loop that can be tested at the middle or end. The statement blocks subordinate to REPEAT and UNTIL form the loop and are executed repeatedly under control of the condition specified by the UNTIL statement (for example, until the end of file). At end of file, processing continues at line 268 After line 268, S-COBOL generates a STOP RUN.
- Output: These lines are copied into the output source because they contain no Customization Facility syntax.
Lines 253-257.
- Input: This statement block is executed because &MODE has been assigned the value 'TRAILING' at the top of the program. REPEAT VARYING ... UNTIL ... is an extension of the S-COBOL REPEAT verb. It establishes a test and causes its subordinate statement block to be executed repeatedly until the test is true.
- Output: Line 253 does not appear in the output because it is a Customization Facility statement. The other lines do appear. The variables &REC-LEN, &TEST-CHR, and &REPLACE-CHR are resolved with their values 121, SPACE, and ZERO. The loop starts at the 121st character, is decremented by 1, and executes line 257 until a trailing character appears that is not a space or until all 121 characters have been tested.
Lines 263-265.
- Input: If &MODE is neither LEADING, TRAILING, or ALL, control falls to this % ELSE statement and displays an error message.
- Output: Note that input line 265 is blank. It does not appear in the output because it is considered part of the statement block subordinate to % ELSE. Remember: a statement block ends with the first non-blank character at the same or less indentation than the controlling conditional statement. To get the blank line to appear in the output, end the conditional structure by inserting a line beneath line 264 and coding % END at the same indentation as % ELSE; then leave the next line blank.

Looping Example

This program calls two user macros that use loops to create a data structure. A loop that incorporates built-in functions returns a value to text.

User macros:

 %* HERE ARE TWO MACROS: $ITEM-MAKER AND $TABLE-MAKER         601.
                                                              602.
 % DEFINE $ITEM-MAKER( &MM, &DATANAME, &TAIL)                 603.
     % &II = 1                                                604.
     % WHILE &II <= &MM                                       605.
         02  &DATANAME+-&II      &40+PIC &TAIL.               606.
         % &II = &II + 1                                      607.
 % END                                                        608.
                                                              609.
 % DEFINE $TABLE-MAKER( &MM, &NN, &TNAME, &INAME, &TAIL)      610.
     % &II = 1                                                611.
     % WHILE &II <= &MM                                       612.
         02  &TNAME+-&II.                                     613.
         % &JJ = 1                                            614.
         % UNTIL &JJ > &NN                                    615.
             % BEGIN                                          616.
               03  &INAME+-&II+-&JJ &40+PIC &TAIL.            617.
             % &JJ = &JJ + 1                                  618.
         % &II = &II + 1                                      619.
 % END                                                        620.
                                                              621.

Program input:

 % SET BLANK                                                  622.
 IDENTIFICATION DIVISION.                                     623.
 PROGRAM-ID.                     EXAMPLE6.                    624.
*SPECIAL CONSIDERATIONS.                                      625.
*    DEMONSTRATE LOOPING.                                     626.
                                                              627.
       ---------------------------------------                628.
       ---------------------------------------                629.
                                                              630.
 WORKING-STORAGE SECTION.                                     631.
                                                              632.
 01  TEST-RECORD.                                             633.
   $ITEM-MAKER( 12, 'TEST-ITEM', 'S9(9) COMP SYNC VALUE -1')  634.
   $TABLE-MAKER( 3, 4, 'ENTRY', 'ITEM', 'X(4) VALUE SPACES')  635.
 % &STR = 'MISSISSIPPI'                                       637.
 % &SUB = 'IS'                                                638.
 % &II = 0                                                    639.
 % REPEAT                                                     640.
     % &JJ = &INDEX( &STR, &SUB)                              641.
 % UNTIL &JJ = 0                                              642.
     % &II = &II + 1                                          643.
     % &JJ = &JJ + &LENGTH( &SUB)                             644.
     % &STR = &SUBSTR( &STR, &JJ)                             645.
 THE NUMBER OF 'IS' IN 'MISSISSIPPI' IS &II.                  646.
                                                              647.

Program output:

062300 IDENTIFICATION DIVISION.                               623.
062400 PROGRAM-ID.                     EXAMPLE6.              624.
062500*SPECIAL CONSIDERATIONS.                                625.
062600*    DEMONSTRATE LOOPING.                               626.
062700                                                        627.
062800     -----------------------------------                628.
062900     -----------------------------------                629.
063000                                                        630.
063100 WORKING-STORAGE SECTION.                               631.
063200                                                        632.
063300 01  TEST-RECORD.                                       633.
063400   02  TEST-ITEM-1        PIC S9(9) COMP SYNC VALUE -1. 634.
063402   02  TEST-ITEM-2        PIC S9(9) COMP SYNC VALUE -1. 623.
063404   02  TEST-ITEM-3        PIC S9(9) COMP SYNC VALUE -1. 634.
063406   02  TEST-ITEM-4        PIC S9(9) COMP SYNC VALUE -1. 634.
063408   02  TEST-ITEM-5        PIC S9(9) COMP SYNC VALUE -1. 634.
063410   02  TEST-ITEM-6        PIC S9(9) COMP SYNC VALUE -1. 634.
063412   02  TEST-ITEM-7        PIC S9(9) COMP SYNC VALUE -1. 634.
063414   02  TEST-ITEM-8        PIC S9(9) COMP SYNC VALUE -1. 634.
063416   02  TEST-ITEM-9        PIC S9(9) COMP SYNC VALUE -1. 634.
063418   02  TEST-ITEM-10       PIC S9(9) COMP SYNC VALUE -1. 634.
063420   02  TEST-ITEM-11       PIC S9(9) COMP SYNC VALUE -1. 634.
063422   02  TEST-ITEM-12       PIC S9(9) COMP SYNC VALUE -1. 634.
063500   02  ENTRY-1.                                         635.
063502     03  ITEM-1-1         PIC X(4) VALUE SPACES.        635.
063504     03  ITEM-1-2         PIC X(4) VALUE SPACES.        635.
063506     03  ITEM-1-3         PIC X(4) VALUE SPACES.        635.
063508     03  ITEM-1-4         PIC X(4) VALUE SPACES.        635.
063510   02  ENTRY-2.                                         635.
063512     03  ITEM-2-1         PIC X(4) VALUE SPACES.        635.
063514     03  ITEM-2-2         PIC X(4) VALUE SPACES.        635.
063516     03  ITEM-2-3         PIC X(4) VALUE SPACES.        635.
063518     03  ITEM-2-4         PIC X(4) VALUE SPACES.        635.
063520   02  ENTRY-3.                                         635.
063522     03  ITEM-3-1         PIC X(4) VALUE SPACES.        635.
063524     03  ITEM-3-2         PIC X(4) VALUE SPACES.        635.
063526     03  ITEM-3-3         PIC X(4) VALUE SPACES.        635.
063528     03  ITEM-3-4         PIC X(4) VALUE SPACES.        635.
063600                                                        636.
064600 THE NUMBER OF 'IS' IN 'MISSISSIPPI' IS 2.              646.
064700                                                        647.

Discussion

Macro lines 603-608. The macro $ITEM-MAKER is defined with three formal arguments whose values are supplied by the macro call in the program on line 634. % WHILE starts a loop that is executed repeatedly while the value of &II is <= to the value of &MM. The loop generates the 02 TEST-ITEM data elements (see output line 634). Note the two uses of the plus symbol in line 606. Used in &DATANAME+-&II, the plus concatenates the two variables, resulting in TEST-ITEM-1 for the first data item. On the next line, &II is incremented by one during each loop, resulting in TEST-ITEM-2 for the second data item, etc. The second use for the plus symbol is to place the value of PIC &TAIL in column 40 of the output for each TEST-ITEM.
Macro lines 610-620. The macro $TABLE-MAKER is defined with five formal arguments whose values are supplied by the macro call in the program on line 635. % WHILE starts an outer loop that repeatedly executes lines 613-619 while the value of &II is <= the value of &MM. The outer loop generates the 02 data elements ENTRY-1, ENTRY-2, and ENTRY-3. & UNTIL starts a nested, inner loop. Its subordinate statement block (lines 616-618) is executed repeatedly until the value of &JJ is > the value of &NN. The inner loop generates the 03 data elements for the outer loop 02s. Note that the % BEGIN statement means that the 03 data items will appear in the output shifted left four spaces in the inner loop so that they are indented two spaces from the 02 data items. Without % BEGIN, they would be at the same indentation as the 02s. (The whole outer and inner loop structure shifts as a unit, thus all lines retain their relative positioning.) Line 618 increments the inner loop variable &JJ. Line 619 increments the outer loop variable &II; note that to be part of the outer loop, it must be indented from the outer loop but not from the inner loop. The loops generate the multiple lines output from both loops appears in the multiple lines 634-635.
Line 622, Input. % SET BLANK means that all blank lines that follow appear in the output
Lines 637-646, Input. These lines illustrate a % REPEAT and % UNTIL structure that uses the built-in functions &INDEX, &LENGTH, and &SUBSTR to find the number of occurrences of the substring IS in the literal string MISSISSIPPI. Lines 641-645 are executed repeatedly until &JJ = 0.

Customization Facility Functions Example

User macro:

 %* HERE IS THE MACRO $DAYDEF                                     501.
                                                                  502.
 % DEFINE $DAYDEF( &DAY)                                          506.
     % &PREFIX = &SUBSTR( &DAY, 1, 24)                            507.
     % &CHR = &SUBSTR( &PREFIX, 24)                               508.
     % IF &CHR = '-'                                              509.
         % &PREFIX = &SUBSTR( &PREFIX, 1, 23)                     510.
     % &SUFFIX = '-ENTRY'                                         511.
     % &DAYCTR = &DAYCTR + 1                                      512.
     02  &PREFIX&SUFFIX.                                          513.
       03  FILLER   &40+PIC S9(2) COMP SYNC VALUE +&LENGTH( &DAY).514.
       % IF &LENGTH( &DAY) <= 16                                  515.
         03  FILLER &40+PIC X(30) VALUE &QT&DAY&QT.               516.
       % ELSE                                                     517.
         03  FILLER &40+PIC X(30) VALUE                           518.
                    &40+&QT&DAY&QT.                               519.
 % END                                                            520.
                                                                  521.

Program input:

 % &DAYCTR = 0                                                522.
 % &QT = "'"                                                  523.
                                                              524.
 % SET BLANK                                                  525.
 IDENTIFICATION DIVISION.                                     526.
 PROGRAM-ID.                 EXAMPLE&INDEX( 'ABCDEFG', 'EF'). 527.
 DATE-COMPILED.              &COMPILETIME.                    528.
*SPECIAL CONSIDERATIONS.                                      529.
*    A PIECE OF A SAMPLE PROGRAM TO DEMONSTRATE SOME          530.
*    OF THE MACRO FACILITY BUILT-IN FUNCTIONS.                531.
                                                              532.
     --                                                       533.
     --                                                       534.
                                                              535.
 WORKING-STORAGE SECTION.                                     536.
                                                              537.
 01  DAY-TABLE.                                               538.
   $DAYDEF( 'SUNDAY')                                         539.
   $DAYDEF( 'MONDAY')                                         540.
   $DAYDEF( 'TUESDAY')                                        541.
   $DAYDEF( 'WEDNESDAY')                                      542.
   $DAYDEF( 'THURSDAY')                                       543.
   $DAYDEF( 'FRIDAY')                                         544.
   $DAYDEF( 'A-LARGE-SYMBOL-TO-CHECK-DAYDEF')                 545.
 01  DAY-TABLE-REDEF             REDEFINES DAY-TABLE.         546.
   02  DAY-ENTRY                 OCCURS &DAYCTR.              547.
     03  DAY-LEN                 PIC S9(2) COMP SYNC.         548.
     03  DAY-BOL                 PIC X(30).                   549.
                                                              550.
 PROCEDURE DIVISION.                                          551.
                                                              552.
     --                                                       553.
     --                                                       554.

Program output:

052300 IDENTIFICATION DIVISION.                               526.
052400 PROGRAM-ID.                 EXAMPLE5.                  527.
052500 DATE-COMPILED.              22 OCT 79 14.24.00.        528.
052600*SPECIAL CONSIDERATIONS.                                529.
052700*    A PIECE OF A SAMPLE PROGRAM TO DEMONSTRATE SOME    530.
052800*    OF THE MACRO FACILITY BUILT-IN FUNCTIONS.          531.
052900                                                        532.
053000     --                                                 533.
053100     --                                                 534.
053200                                                        535.
053300 WORKING-STORAGE SECTION.                               536.
053400                                                        537.
053500 01  DAY-TABLE.                                         538.
053600   02  SUNDAY-ENTRY.                                    539.
053602     03  FILLER           PIC S9(2) COMP SYNC VALUE +6  539.
053604     03  FILLER           PIC X(30) VALUE 'SUNDAY'.     539.
053700   02  MONDAY-ENTRY.                                    540.
053702     03  FILLER           PIC S9(2) COMP SYNC VALUE +6. 540.
053704     03  FILLER           PIC X(30) VALUE 'MONDAY'.     540.
053800   02  TUESDAY-ENTRY.                                   541.
053802     03  FILLER           PIC S9(2) COMP SYNC VALUE +7. 541.
053804     03  FILLER           PIC X(30) VALUE 'TUESDAY'.    541.
053900   02  WEDNESDAY-ENTRY.                                 542.
053902     03  FILLER           PIC S9(2) COMP SYNC VALUE +9. 542.
053904     03  FILLER           PIC X(30) VALUE 'WEDNESDAY'.  542.
054000   02  THURSDAY-ENTRY.                                  543.
054002     03  FILLER           PIC S9(2) COMP SYNC VALUE +8. 543.
054004     03  FILLER           PIC X(30) VALUE 'THURSDAY'.   543.
054100   02  FRIDAY-ENTRY.                                    544.
054102     03  FILLER           PIC S9(2) COMP SYNC VALUE +6. 544.
054104     03  FILLER           PIC X(30) VALUE 'FRIDAY'.     544.
054200   02  A-LARGE-SYMBOL-TO-CHECK-ENTRY.                   545.
054202     03  FILLER           PIC S9(2) COMP SYNC VALUE +30.545.
054204     03  FILLER           PIC X(30) VALUE               545.
054206                       'A-LARGE-SYMBOL-TO-CHECK-DAYDEF'.545.
054300 01  DAY-TABLE-REDEF      REDEFINES DAY-TABLE.          546.
054400   02  DAY-ENTRY          OCCURS 7.                     547.
054500     03  DAY-LEN          PIC S9(2) COMP SYNC.          548.
054600     03  DAY-BOL          PIC X(30).                    549.
054700                                                        550.
054800 PROCEDURE DIVISION.                                    551.
054900                                                        552.
055000     --                                                 553.
055100     --                                                 554.

Discussion

The $DAYDEF Macro

$DAYDEF uses the built-in functions &SUBSTR and &LENGTH to build a data structure for a table. $DAYDEF builds for each table entry an 02-level data name and provides the values of the VALUE clauses of the two 03-level entries that follow it. The 02-level data name is constructed as &PREFIX&SUFFIX.

The value of &SUFFIX for each macro call is the literal string -ENTRY.

The value of &PREFIX is supplied by the formal argument &DAY which receives its value from a macro call to $DAYDEF. For example, the first macro call in the program gives the value SUNDAY to &DAY. The built-in function &SUBSTR checks this value and dictates that up to 24 characters will be accepted (values longer than 24 characters are truncated). On the next line, &SUBSTR checks to see whether the 24th character (if there is one) is a hyphen. If it is a hyphen, only 23 characters are used in order to prevent a double hyphen which would be undesirable (for example, you don't want a hyphen from the name followed by the hyphen of the suffix -ENTRY). SUNDAY is only 6 characters long, so the entire value is accepted as the value for &PREFIX. Thus the value of &PREFIX&SUFFIX for the first call is SUNDAY-ENTRY.

Now $DAYDEF provides the values of the VALUE clauses of the two 03-level data elements for SUNDAY-ENTRY. In the first 03 element, VALUE +&LENGTH( &DAY) becomes VALUE +6 because the value of &DAY (which is SUNDAY) is 6 characters long. The plus symbol is recognized as the COBOL plus symbol because there is a space before it. (In contrast, the plus symbol in &40+PIC is recognized as a Customization Facility column indicator, which in this case means "Put the PIC clause in column 41.")

Line 515 checks to see whether the length of the values of &DAY can fit all on one line (for example, whether it is 16 characters maximum). If it can fit, its format is the one on line 516 (remember: the line will shift under the % IF statement during processing). If it cannot fit, its format is the two-line format on lines 518-519.

The Program:

Lines 527-528, Input. &INDEX returns a number which identifies the character position of the first occurrence of EF within ABCDEFG. The number is 5 -- thus EXAMPLE&INDEX( 'ABCDEFG', 'EF') becomes EXAMPLE5. This is simply an illustrative example, not a particularly useful one. &COMPILETIME, however, returns the current date and time each time the program is compiled.
Lines 539-545, Input. These are seven macro calls to $DAYDEF, each providing a value for the &DAY argument in $DAYDEF.
Line 547. The OCCURS clause value &DAYCTR is initialized to 0 at the top of the program and is used in $DAYDEF.

Program Location Statements Example

This example illustrates the use of program location statements and in-line macros. In addition to showing macros, program input and the resultant Customization Facility output, this example goes one step further and shows the program after APS Precompiler processing.

User macros:

 1.            % DEFINE $IN-LINE( &ARG)
 2.                COUNTER = &ARG
 3.                % &IN-LINE = &ARG
 4.            % END
 5.            % DEFINE $MY-EPILOGUE
 6.               % * MARK COLUMN 7 MARGIN
 7.                % SET LINKAGE
 8.                01  MY-EPILOGUE-CHR        &40+PIC X.
 9.                % SET PROCEDURE
10.                    COUNTER = 100
11.                % SET EPILOGUE $SECOND-EPILOGUE
12.            % DEFINE $SECOND-EPILOGUE
13.               % BEGIN
14.                    COUNTER = 101
15.            % SET EPILOGUE $MY-EPILOGUE

Program input:

16.            % SET EVAL-BRACKETS "<>"
17.            IDENTIFICATION DIVISION.
18.            PROGRAM-ID.
19.                                          EXAMPLE9.
20.            ENVIRONMENT DIVISION.
21.            INPUT-OUTPUT SECTION.
22.            FILE-CONTROL.
23.                SELECT YOUR-FILE          ASSIGN UT-S-YOURFILE.
24.            DATA DIVISION.
25.            FILE SECTION.
26.            FD  YOUR-FILE.
27.            01  YOUR-RECORD                 PIC X(80).
28.            WORKING-STORAGE SECTION.
29.            01  COUNTER                     PIC S9(4) COMP.
30.            01  WS-1                        PIC X.
31.            % SET END-WORKING-STORAGE
32.           *    PLACE FOR STUFF THAT MUST BE AT END OF WS FOR 
33.           *    CERTAIN NON-APS PRE-PROCESSORS.
34.            PROCEDURE DIVISION.
35.                COUNTER = 1
36.                $IN-LINE( 2)
37.                TEST-NO-DELIMITERS = <$IN-LINE( 3)>
38.                ADD <$IN-LINE( 4)> <$IN-LINE( 5)> TO COUNTER
39.            % SET LINKAGE
40.            01  LINKAGE-STUFF               PIC X.
41.            % SET PROCEDURE
42.            % SET DELIMITERS-OPTIONAL
43.                $IN-LINE( TEST-NO-DELIMITERS)
44.                $IN-LINE( 6)
45.            % SET DATA
46.           * PLACING DATA IN DATA DIVISION
47.            % SET PROCEDURE
48.            % SET FILE
49.            FD  MY-FILE.
50.            01  MY-RECORD                   PIC X(80).
51.            % SET PROCEDURE
52.            % SET FILE-CONTROL
53.                SELECT MY-FILE              ASSIGN UT-S-MYFILE.
54.            % SET PROCEDURE
55.                OPEN INPUT MY-FILE YOUR-FILE
56.                CLOSE MY-FILE YOUR-FILE
57.            % SET WORKING-STORAGE
58.            01  TEST-NO-DELIMITERS          PIC 9(&IN-LINE).
59.            % SET PROCEDURE
61.            % SET AUXILIARY-OUTPUT
62.            THIS IS AUXILIARY FILE DATA
63.            % SET NORMAL-OUTPUT

Output source:

001700 IDENTIFICATION DIVISION.                                17.
001800 PROGRAM-ID.                                             18.
001900                               EXAMPLE9.                 19.
002000 ENVIRONMENT DIVISION.                                   20.
002100 INPUT-OUTPUT SECTION.                                   21.
002200 FILE-CONTROL.                                           22.
002300     SELECT YOUR-FILE          ASSIGN UT-S-YOURFILE.     23.
005300     SELECT MY-FILE            ASSIGN UT-S-MYFILE.       53.
005302 DATA DIVISION.                                          24.
005304* PLACING DATA IN DATA DIVISION                          46.
005306 FILE SECTION.                                           25.
005308 FD  YOUR-FILE.                                          26.
005310 01  YOUR-RECORD                 PIC X(80).              27.
005312 FD  MY-FILE.                                            49.
005314 01  MY-RECORD                   PIC X(80).              50.
005316 WORKING-STORAGE SECTION.                                28.
005318 01  COUNTER                     PIC S9(4) COMP.         29.
005320 01  WS-1                        PIC X.                  30.
005322 01  TEST-NO-DELIMITERS          PIC 9(6).
005324*    PLACE FOR STUFF THAT MUST BE AT END OF WS FOR       32.
005326*    CERTAIN NON-APS PRE-PROCESSORS.                     33.
005328 LINKAGE SECTION.
005330 01  LINKAGE-STUFF               PIC X.                  40.
006300 01  MY-EPILOGUE-CHR             PIC X.
006302 PROCEDURE DIVISION.                                     34.
006304     COUNTER = 1                                         35.
006306     COUNTER = 2
006308     COUNTER = 3
006310     TEST-NO-DELIMITERS = 3
006312     COUNTER = 4
006314     COUNTER = 5
006316     COUNTER = COUNTER + 4 5
006318     COUNTER = TEST-NO-DELIMITERS
006320     COUNTER = 6
006322     OPEN INPUT MY-FILE YOUR-FILE                        55.
006324     CLOSE MY-FILE YOUR-FILE                             56.
006326*/*  THIS IS AN S-COBOL COMMENT LINE.                    60.
006328     COUNTER = 100                                       11.
006330     COUNTER = 101                                       15.

Discussion

Lines 1-14, Macros. Three macros are defined: $IN-LINE, $MY-EPILOGUE, and $SECOND-EPILOGUE.
Line 15, Macros. % SET EPILOGUE $MY-EPILOGUE causes $MY-EPILOGUE to be automatically invoked at the very end of the program (after line 63).
Line 31, Input. A marker for the code on line 58 that is relocated to WORKING-STORAGE; it will go immediately above this marker.
Line 36, Input. $IN-LINE is invoked, passing the actual argument 2 to the macro formal argument &ARG. The result appears in output line 6306 (COUNTER = 2).
Line 37, Input. First, the contents of the evaluation brackets are evaluated. The brackets contain a call to the $IN-LINE macro, passing the argument 3 to the macro argument &ARG. Thus the macro is called and the result appears in output line 6308 (COUNTER = 3). Next, the contents of the brackets are resolved, giving TEST-NO-DELIMITERS a value. The value comes from a variable within $IN-LINE that exists for this purpose;. this variable must have same name as the macro it belongs to, and its value is the same as the argument passed to the macro (for example, 3). Thus <$IN-LINE( 3)> is replaced by 3, and TEST-NO-DELIMITERS = 3 is output to line 6310.
Line 38, Input. Outputs lines 6312-6316. If we had wanted to add 45 to COUNTER instead of 4 and 5, we would have omitted the space between the first and second appearance of the in-line macro.
Lines 39-41, Input. Line 39 generates the LINKAGE SECTION statement and relocates line 40 to the Linkage Section (see output lines 5328-5330); line 41 ends the effect of % SET LINKAGE.
Line 42, Input. Lets us omit delimiters around string arguments, as on line 43.
Line 45-47, Input. Line 45 relocates line 46 to immediately after the DATA DIVISION statement (see output line 5304); line 47 ends the effect of % SET DATA.
Line 48-51, Input. Line 48 relocates lines 49-50 to the end of the File Section (see output lines 5312-5314); line 51 ends the effect of % SET FILE.
Lines 52-54, Input. Line 52 relocates line 53 to the end of FILE-CONTROL.; line 54 ends the effect of % SET FILE-CONTROL.
Lines 57-59, Input. Line 57 relocates line 58 to the end of WORKING-STORAGE; line 59 ends the effect of % SET WORKING-STORAGE.
Lines 61-63, Input. Valid only for APS for z/OS product; line 61 causes line 62 to be output to an external auxiliary file named MACRO; line 63 ends the effect of % SET AUXILIARY-OUTPUT.
Line 6328, Output. Line 15 of the macro source (% SET EPILOGUE $MY-EPILOGUE) put $MY-EPILOGUE in the storage area called EPILOGUE. All macros in EPILOGUE are automatically invoked at the end of the program, after all other all Customization Facility processing is completed, starting with the last macro put into EPILOGUE. Because $MY-EPILOGUE is the only macro in EPILOGUE, it is invoked. The result is line 6328 in the output.
During processing of $MY-EPILOGUE, % SET LINKAGE relocates line 9 to the end of the Linkage Section (line 6300), and puts COUNTER = 100 at the end of the Procedure Division (line 6328). Line 15 is an EPILOGUE statement nested within a $MY-EPILOGUE; it puts $SECOND-EPILOGUE into the EPILOGUE area. The processing of $MY-EPILOGUE is now completed.

Now that $MY-EPILOGUE is finished and $SECOND-EPILOGUE has become the last macro existing in EPILOGUE, $SECOND-EPILOGUE is automatically invoked.

After the above program is processed by the Customization Facility, it is processed by the APS Precompiler. The result is shown below. Note the additional lines (5324 through 5340 and 6236 through 6242) that have been generated by the Precompile process.

After APS Precompiler processing:

001700 IDENTIFICATION DIVISION.                                17.
001800 PROGRAM-ID.                                             18.
001900                                 EXAMPLE9.               19.
002000 ENVIRONMENT DIVISION.                                   20.
002100 INPUT-OUTPUT SECTION.                                   21.
002200 FILE-CONTROL.                                           22.
002300     SELECT YOUR-FILE            ASSIGN UT-S-YOURFILE.   23.
005300     SELECT MY-FILE              ASSIGN UT-S-MYFILE.     53.
005302 DATA DIVISION.                                          24.
005304* PLACING DATA IN DATA DIVISION                          46.
005306 FILE SECTION.                                           25.
005308 FD  YOUR-FILE.                                          26.
005310 01  YOUR-RECORD                 PIC X(80).              27.
005312 FD  MY-FILE.                                            49.
005314 01  MY-RECORD                   PIC X(80).              50.
005316 WORKING-STORAGE SECTION.                                28.
005318 77  COUNTER                     PIC S9(4) COMP.         29.
005320 01  WS-1                        PIC X.                  30.
005322 01  TEST-NO-DELIMITERS          PIC 9(6).
005322
005324 01  GENERATED--FLAGS.
005326     05  TRUE                    PIC X VALUE 'T'.
005328         88  ALWAYS              VALUE 'T'.
005330         88  NEVER               VALUE 'F'.
005332     05  FALSE                   PIC X VALUE 'F'.
005334     05  YOUR-FILE--END          PIC X.
005336     05  YOUR-FILE--INV          PIC X.
005338     05  MY-FILE--END            PIC X.
005340     05  MY-FILE--INV            PIC X.
005342
005344*    PLACE FOR STUFF THAT MUST BE AT END OF WS FOR       32.
005346*    CERTAIN NON-APS PRE-PROCESSORS.                     33.
005348 LINKAGE SECTION.
005350 01  LINKAGE-STUFF               PIC X.                  40.
006200 01  MY-EPILOGUE-CHR             PIC X.
006202 PROCEDURE DIVISION.                                     34.
006204 MAIN--SECTION SECTION.                                  35.
006206 MAIN--SECTION--PARA.                                    35.
006208     COUNTER = 1.                                        35.
006210     COUNTER = 2.
006212     COUNTER = 3.
006214     TEST-NO-DELIMITERS = 3.
006216     COUNTER = 4.
006218     COUNTER = 5.
006220     COUNTER = COUNTER + 4 5
006222     COUNTER = TEST-NO-DELIMITERS.
006224     COUNTER = 6.
006226     OPEN INPUT MY-FILE YOUR-FILE.                       55.
006228     CLOSE MY-FILE YOUR-FILE.                            56.
006230*    THIS IN AN S-COBOL COMMENT LINE                     60.
006232     COUNTER = 100.                                      11.
006234     COUNTER = 101.                                      15.
006236 MAIN--SECTION--EXIT.                                    15.
006238     EXIT PROGRAM.                                       15.
006240 MAIN--SECTION--EXIT.                                    15.
006242 STOP RUN.                                               15.