%LOWER and %UPPER (Convert to Lower or Upper Case)

%LOWER(string {: start { : length } })
%UPPER(string {: start { : length } })

%LOWER returns the string operand, with all or part of the operand converted to lower case.

%UPPER returns the string operand, with all or part of the operand converted to upper case.

Otherwise, the built-in functions are identical.

The first operand is the string to be converted to lower or upper case. It can have type alphanumeric or UCS-2.

The second operand is the start position for conversion. It must be a numeric expression with zero decimal positions, and it must have a value between one and the length of the string. It is optional. If it is not specified, the conversion starts at the first position of the string.

The third operand is the length for conversion. It must be a numeric expression with zero decimal positions and it must be less than or equal to the length of the string starting at the start position. It can be zero. It is optional. If it is not specified, the conversion continues to the end of the string.

Notes for %LOWER and %UPPER:
  • If a character is already in the required case, it is unchanged. For example, the result of %LOWER('AbC') is 'abc'. The 'b' is already in lower case, so it is unchanged.
  • All alphabetic characters in the substring represented by the start position and length operands are converted. For example, the result of %LOWER('ÅNGSTRÖM') is 'ångström'. The result of %UPPER('a1234bc':start:length) is 'A1234bc' if the value of start is 1 and the value of length is 1.
  • The start position and length operands represent the number of bytes for alphanumeric data and the number of double bytes for UCS-2 data. It is the RPG programmer's responsibility to ensure that the substring represented by the start position and length operands represents complete characters. See the warning about substrings for some CCSIDs.
    • If the substring represented by the start position and length is not valid due to the start position being less than 1, or due to the length being greater than the amount of data remaining in the string, the built-in function fails with status code 100.
    • If the data to be converted is not valid due to the substring represented by the start position and length causing the final character to be incomplete, the built-in function fails with status code 125.

Examples of %LOWER and %UPPER

  1. %LOWER and %UPPER with one parameter 
    
   DCL-S result VARCHAR(10);

   result = %LOWER ('HELLO');
   // result = "hello"

   result = %UPPER ('world');
   // result = "WORLD"
  2. %LOWER and %UPPER with two parameters 
    
   DCL-S result VARUCS2(10);
   DCL-S string UCS2(5);

   string = 'HELLO';
   result = %LOWER (string : 2);
   // result = "Hello"

   string = 'world';
   result = %UPPER (string : 2);
   // result = "wORLD"
  3. %LOWER and %UPPER with three parameters 
    
   DCL-S result VARCHAR(10);

   result = %LOWER ('HELLO' : 2 : 3);
   // result = "HellO"

   result = %UPPER ('world' : 1 : 1);
   // result = "World"