CONCAT macro: coding rules

Purpose:

Usage:

%CONCAT &field1 &nspaces &field2

&field1: The receiving field and the 1st string to concatenate.
&nspaces: A number (a numeric field or a number) of spaces after or before the string in the &field1 field.
&field2: String to be concatenated to the &field1 string.

The outcome is placed into the &field1 field.

Note:

For explaining purposes the End-of-&field1 string is the size derived by scanning the &field1 backwards until a non-space is encountered.

The &nspaces can be a positive or a negative number. When positive, the &field2 is concatenated to the End-of-&field1 string plus the &nspaces spaces. When negative, the &field2 is concatenated to the End-of&field1 string minus the &nspaces spaces (i.e. the tail end of &field1 string is clipped).

Special handling:

&field2 is not concatenated if the End-of-&field1 string plus &nspaces exceeds the defined length of &field1. (The &field1 remains unchanged).
&field2 is not concatenated if the End-of-&field1 string minus the &nspaces is negative. (The &field1 is set to spaces).

Examples:

Example 1: with &nspaces positive value

            DEFINE FIELD1          W 40 A VALUE 'DRINKING TEA IS GOOD'
            DEFINE NSPACES         W  6 P 0 VALUE  3
            DEFINE FIELD2          W 10 A VALUE 'FOR LIFE'

            JOB INPUT NULL
            %CONCAT FIELD1 NSPACES FIELD2

            Before CONCAT macro:
               FIELD1="DRINKING TEA IS GOOD                    "
               NSPACES=             3
               FIELD2 ="FOR LIFE  "
            After CONCAT macro:
               FIELD1="DRINKING TEA IS GOOD   FOR LIFE

Example 2: with &nspaces negative value

            DEFINE FIELD1          W 40 A VALUE 'DRINKING TEA IS GOOD'
            DEFINE NSPACES         W  6 P 0 VALUE  -3
            DEFINE FIELD2          W 10 A VALUE 'FOR LIFE'

            JOB INPUT NULL
            %CONCAT FIELD1 NSPACES FIELD2

            Result before CONCAT macro:
               FIELD1="DRINKING TEA IS GOOD                    "
               NSPACES=             3-
               FIELD2 ="FOR LIFE  "
            Result after CONCAT macro:
               FIELD1="DRINKING TEA IS GFOR LIFE               "