%RIGHT (Get Rightmost Characters)

%RIGHT(string : length { : *NATURAL | *STDCHARSIZE } )

%RIGHT returns the rightmost characters of a string.

The first operand is a string. It can be alphanumeric, graphic, or UCS-2.

The second operand is the number of characters to return.

The third operand can be specified to set the CHARCOUNT mode for the statement. See Example demonstrating the effect of the CHARCOUNT mode on %RIGHT.

• Specify *NATURAL as the third parameter for %RIGHT to operate in CHARCOUNT NATURAL mode.
• Specify *STDCHARSIZE as the third parameter for %RIGHT to operate in CHARCOUNT STDCHARSIZE mode.
• If the third parameter is not specified, %RIGHT operates in the charcount mode for the statement as set by the CHARCOUNT Control keyword or the /CHARCOUNT directives.

When %RIGHT is operating in CHARCOUNT NATURAL mode, the second operand refers to the number of characters to return.

When %RIGHT is operating in CHARCOUNT STDCHARSIZE mode, the second operand is the number of bytes or double-bytes to return.

For more information, see String Operations and Built-in Functions.

Example of %RIGHT

In the following example, the string ends with a timestamp in the form ‘YYYY-MM-DD-HH-MM-SS’.

1. The %RIGHT built-in function returns the character form of the timestamp, “2023-12-25-12.30.01”.
2. The %TIMESTAMP built-in function returns the timestamp Z’2023-12-25-12.30.01’.

DCL-S string VARCHAR(1000);
DCL-S tstamp TIMESTAMP(0);
DCL-S tstamp_string CHAR(%SIZE(tstamp));

string = 'ABCD 201 PQR XYZ 304 2023-12-25-12.30.01';
tstamp_string = %RIGHT(string : %SIZE(tstamp_string)); //  1 
// tstamp_string = "2023-12-25-12.30.01"
tstamp = %TIMESTAMP(tstamp_string : *ISO : 0); //  2 
// tstamp = Z'2023-12-25-12.30.01'

Example demonstrating the effect of the CHARCOUNT mode on %RIGHT

• In the following example, the UTF-8 string “ábç” has three characters, but characters ‘á’ and ‘ç’ have two bytes each.

  1. %RIGHT(‘ábç’ : 2) returns ‘bç’ in natural mode.
  2. %RIGHT(‘ábç’ : 2) returns ‘ç’ in stdcharsize mode.

  CTL-OPT CHARCOUNTTYPES(*UTF8);
  
  DCL-S string VARCHAR(10) CCSID(*UTF8);
  DCL-S right VARCHAR(10) CCSID(*UTF8);
  
  string = 'ábç';
  
  /CHARCOUNT NATURAL
  right = %RIGHT(string : 2); //  1 
  // right = 'bç'
  
  /CHARCOUNT STDCHARSIZE
  right = %RIGHT(string : 2); //  2 
  // right = 'ç'