$PAD Function

$PAD is an alphanumeric function that returns the string that results from filling an alphanumeric expression with the specified character on the left, right, or both ends, to the length specified.

This function has the following format:

                                     [RIGHT= {'a'     }]
$PAD(alpha‑expression,LENGTH=num‑exp,[CENTER={a‑field }])
                                     [LEFT=            ]

alpha‑expression

Any alphanumeric expression.

num‑exp

A numeric expression indicating the length of the string produced by adding fill characters to the expression. It must be defined with integer digits only. If any other kind of numeric expression is specified or if the value is not a whole number, the integer portion is used.

RIGHT|CENTER|LEFT

The RIGHT= clause adds the specified character to the right of the expression. The CENTER= clause adds the specified character equally to the right and left. The LEFT= clause adds the specified character to the left of the expression. You cannot specify more than one clause. If you do not specify a clause, the default is RIGHT=' ' (pad with trailing blanks). If you specify a clause, its keyword can be abbreviated to the first three characters (RIG=, LEF=, CEN=).

'a'

A single‑character, alphanumeric literal used as the fill character.

a‑field

A one‑byte alphanumeric field containing the fill character. (This cannot be a variable length field.) You cannot use $HIGH, $LOW, and $SPACE.

The function does not change the alphanumeric expression. It uses it to build the expression that it returns. Thus, a return value longer than the original expression is possible.
If the length specified is less than or equal to the length of the alphanumeric expression, the expression is returned unchanged.
If you specify CENTER= and the specified length minus the length of the alphanumeric expression is an odd number, then the extra byte is placed on the right.

Examples

Assume that IDENT is a four‑byte alphanumeric field containing 'ABCD'. The following function results in a nine‑byte result containing 'ABCDbbbbb', where b is a blank.

$PAD(IDENT,LENGTH=9)

Using the same input field, IDENT,

$PAD(IDENT,LENGTH=4)

returns 'ABCD'.

The following example converts five‑digit zip codes in DVW.ZIP.CODE to nine‑digit zip codes by padding to the right with zeros. ZIP_NINE is defined in working data as a nine‑byte alphanumeric field.

SET ZIP_NINE = $PAD(DVW.ZIP.CODE,LENGTH=9,RIGHT='0')

The string returned by $PAD is an intermediate result. When the intermediate result is moved to a field, the final result depends on the field type and length. For example, given the following fields:

FIX_FLD-Type X, length 10, initial value 'ABC'
VAR_FLD-Type V, length 10, initial value 'ABC'.

The following function returns the string 'ABC????bbb', where 'b' is a blank.

SET FIX_FLD = $PAD(VAR_FLD, LENGTH =7, RIGHT='?')

The following statement sets FIX_FLD to 'ABCbbbbbbb'. Because the length specified (7) is less than the length of the alphanumeric expression (FIX_FLD is 10 characters long), the expression is returned unchanged.

SET FIX_FLD = $PAD(FIX_FLD,LENGTH=7, RIGHT='?')

On the other hand, the following statement sets VAR_FLD to 'ABCbbbbbbb'.

SET VAR_FLD = $PAD(FIX_FLD, LENGTH=7, RIGHT='?')

The statement following sets VAR_FLD to 'ABC????'.

SET VAR_FLD = $PAD(VAR_FLD, LENGTH=7, RIGHT='?')

A nested example, such as that shown, sets FIX_FLD to 'ABC????bbb'.

SET FIX_FLD = $PAD($TRIM(FIX_FLD),LENGTH=7, RIGHT='?')

Intermediate results in a nested example are treated the same as variable length moves.