FILL( ) Fill string

Domain: String processing

The FILL( ) function fills the string specified in the function call with zeros up to the specified length and in the specified direction. This fill character can be defined in the function call.

Format

FILL( )

STRING = string_expression

,LENGTH = arithm_expression

,SIDE = *RIGHT / *LEFT

,FILL-BYTE = C’ ‘ / character

Result type

STRING

Input parameters

STRING = string_expression
Designates the input string which is to be filled to the length defined with the parameter LENGTH = .

LENGTH = arithm_expression
Positive number which determines the length of the input string.
If the value for LENGTH is greater than the current length of the input string (see STRING parameter) and lies within the valid range of values for string lengths, the input string is filled with the character defined in FILL-BYTE = .
If “arithm_expression” is not within the valid range of values, an error message is output. If LENGTH is shorter than the actual length of STRING, STRING is returned unchanged as the result.

SIDE =
Determines the direction of the input string in the result string, i.e. the direction in which the fill characters are appended; SIDE = is ignored if the input string is returned unchanged.

SIDE = *RIGHT
Appends the fill characters to the right, i.e. after the last character in the input string.

SIDE = *LEFT
Appends the fill characters to the left, i.e. before the first character in the input string.

FILL-BYTE =

Determines which character is used to fill the input string. FILL-BYTE = is ignored if the input string is not lengthened.

FILL-BYTE = C’ ’
Fills the input string with blanks (to the left or right).

FILL BYTE = character
Fills the input string with the character specified in this position (to the left or right). “character” can be any character. If more than one character is specified, only the first character is used as the fill character.
If a null string (C’’) is specified instead of a character, an error message is output.

Result

String with the length of LENGTH = number

Error messages

SDP0431    ERROR '(&00)' IN BUILTIN FUNCTION '(&01)' 
SDP0436    GIVEN LENGTH NOT BETWEEN ZERO AND MAXIMUM POSSIBLE STRING LENGTH 
SDP0437    LENGTH OF PARAMETER 'FILL-BYTE' EQUAL TO ZERO 

Example

/A = 'ABCDE'
/SHOW-VARIABLE A
A = ABCDE
/A = FILL(STRING = A, LENGTH = 8, FILL-BYTE = C'.')
/SHOW-VARIABLE A
A = ABCDE...
/A = FILL(STRING = A, LENGTH = 12, SIDE=*LEFT, FILL-BYTE = C'.')
/SHOW-VARIABLE A
A =....ABCDE...