What's New since 7.5?

This section was last updated in the first half of the year 2024.

This section describes the enhancements to ILE RPG after 7.5 with PTFs.

See https://www.ibm.com/support/pages/rpg-cafe to determine the PTFs you need on the systems where you are compiling and running your programs.

More options for the SND-MSG operation

You can now specify *COMP, *DIAG, *NOTIFY, and *STATUS for the message type, in addition to the previous supported types *INFO and *ESCAPE.

You can now specify *CTLBDY, *EXT, and *PGMBDY for the first parameter of the %TARGET built-in function in addition to the previous special targets *SELF and *CALLER.

In the following example, the first SND-MSG operation sends a message to the bottom of the screen indicating the progress of the program. The second SND-MSG operation sends a completion message to the caller of the program.

FOR n = 1 to total;
   . . .
   SND-MSG *STATUS
           %CHAR(n) + ' of ' + %CHAR(total) + ' complete'
           %TARGET(*EXT);
ENDFOR;
SND-MSG *COMP 'Processing complete'
        %TARGET(*CALLER : 1);

See SND-MSG (Send a Message to the Joblog) and %TARGET (program-or-procedure { : offset } ).

This enhancement is available with a compile-time PTF in the first half of the year 2024.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Warning: A runtime PTF was provided when the SND-MSG operation code was first enabled for 7.4. You must ensure that the runtime PTF is applied on any 7.4 system where a program compiled for TGTRLS(V7R4M0) is restored if the program has a SND-MSG operation.

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

Define a constant standalone field or data structure

You can now specify CONST for a standalone field or data structure. When you specify the CONST, the variable cannot be modified by the program.

In the following example, data structure defaults and standalone field startTimestamp cannot be changed after they are initialized by the compiler.

DCL-DS defaults QUALIFIED CONST;
   usrprf CHAR(10) INZ(*USER);
   branch VARCHAR(50) INZ('Main');
END-DS;
DCL-S startTimestamp TIMESTAMP INZ(*SYS) CONST;
DCL-S currentBranch VARCHAR(50);

currentBranch = getBranch();
IF currentBranch <> defaults.branch;
  . . .
ENDIF;

SND-MSG 'Elapsed time is '
      + %CHAR(%DIFF(%TIMESTAMP(*SYS) : startTimestamp : *SECONDS : 2))
      + ' seconds';

See Constant variables.

This enhancement is available with a compile-time PTF in the first half of the year 2024.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

%LEFT and %RIGHT built-in functions

• %LEFT returns the leftmost characters in a string.
• %RIGHT returns the rightmost characters in a string.

In the following example, the input string is "abcdefghij". The %LEFT built-in function returns the 3 leftmost characters, "abc". The %RIGHT built-in function returns the 3 rightmost characters, "hij".

DCL-S myString VARCHAR(20) inz('abcdefghij');
DCL-S leftChars VARCHAR(20);
DCL-S rightChars VARCHAR(20);

myString = 'abcdefghij';

leftChars = %LEFT(myString : 3);
// leftChars = "abc"

rightChars = %RIGHT(myString : 3);
// leftChars = "hij"

See %LEFT (Get Leftmost Characters) and %RIGHT (Get Rightmost Characters).

This enhancement is available with a compile-time PTF in the last half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Enumerations to group named constants

An enumeraton is a group of named constants. The enumeration can be qualified.

In the following example:

1. Enumeration sizes is not qualified.
2. Enumeration jobMsgQ is qualified.
3. The constant small from enumeration sizes is used without being qualified by the enumeration name.
4. The constant wrap from enumeration jobMsgQ is qualified by the enumeration name.
5. The enumeration values are assigned to an array.
6. The enumeration name is used with the IN operator. If the value of item.size is not one of the values in the enumeration, the message will be sent.
7. The enumeration name is used in a FOR-EACH statement to iterate through all the values in the enumeration.

DCL-ENUM sizes; //  1 
   tiny -1;
   small 0;
   medium 1;
   large 2;
END-ENUM;

DCL-ENUM jobMsgQ QUALIFIED; //  2 
   noWrap '*NOWRAP';
   wrap '*WRAP';
   prtWrap '*PRTWRAP';
END-ENUM;

DCL-S cmd VARCHAR(100);
DCL-S array INT(10) DIM(5);
DCL-DS item QUALIFIED;
   size packed(5);
END-DS;

item.size = small; //  3 

cmd = 'CHGJOB JOBMSGQFL(' + jobMsgQ.wrap + ')'; //  4 

array = sizes; //  5 

IF NOT (item.size IN sizes); //  6 
   SND-MSG *ESCAPE 'Size is not valid for item ' + item.id_no;
ENDIF;

FOR-EACH x in sizes; //  7 
   ...
ENDFOR;

See Free-Form Enumeration Definition.

This enhancement is available with a compile-time PTF in the last half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

*ALLSEP option for %SPLIT to handle all separators

By default, separators following other separators, leading separators, and trailing separators are ignored by %SPLIT.

You can specify *ALLSEP to indicate that every separator is considered to separate two substrings.

In the following example, the input string has several extra separators. When *ALLSEP is specified, several empty substrings are returned by %SPLIT. The extra separators are marked by X in the comment following the assignment to the myString variable.

myString = '.cat..dog...fish..';
//          X    X    XX    XX

array = %SPLIT(myString : '.');
// %SPLIT returns
//   'cat'
//   'dog'
//   'fish'

array = %SPLIT(myString : '.' : *ALLSEP);
// %SPLIT returns
//    ''
//    'cat'
//    ''
//    'dog'
//    ''
//    ''
//    'fish'
//    ''
//    ''

See %SPLIT (Split String into Substrings).

This enhancement is available with a compile-time PTF and a runtime PTF in the first half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Warning: You must ensure that the runtime PTF is applied on any system where the program is restored.

Different runtime PTFs are required for 7.4 and 7.5 systems.

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

New built-in function %PASSED

%PASSED returns *ON if the specified parameter was passed and *OMIT was not passed for the parameter. If %PASSED is true, the parameter can be used.

DCL-PROC myProc;
   DCL-PI *n;
      p1 CHAR(10) OPTIONS(*OMIT);
      p2 DATE(*ISO) CONST OPTIONS(*OMIT : *NOPASS);
      p3 INT(10) VALUE OPTIONS(*NOPASS);
   END-PI;

   IF %PASSED(p1);
      DSPLY p1;
   ELSE;
      DSPLY 'P1 is not available';
   ENDIF;

   IF %PASSED(p2);
      DSPLY p2;
   ELSE;
      DSPLY 'P2 is not available';
   ENDIF;

   IF %PASSED(p3);
      DSPLY p3;
   ELSE;
      DSPLY 'P3 is not available';
   ENDIF;
END-PROC;

See %PASSED (Return Parameter-Passed Condition).

This enhancement is available with a compile-time PTF in the first half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Note:

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

New built-in function %OMITTED

%OMITTED returns *ON if *OMIT was passed for the specified parameter.

DCL-PROC myProc;
   DCL-PI *n;
      p1 CHAR(10) OPTIONS(*OMIT);
      p2 DATE(*ISO) CONST OPTIONS(*OMIT : *NOPASS);
   END-PI;

   IF %PASSED(p1);
      DSPLY p1;
   ELSEIF %OMITTED(p1);
      DSPLY '*OMIT was passed for P1';
   ENDIF;

   IF %PASSED(p2);
      DSPLY p2;
   ELSEIF %OMITTED(p2);
      DSPLY '*OMIT was passed for P2';
   ELSE;
      DSPLY 'P2 was not passed at all';
   ENDIF;
END-PROC;

See %OMITTED (Return Parameter-Omitted Condition).

This enhancement is available with a compile-time PTF in the first half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Note:

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

Specify an operand for SELECT

You can specify an operand for the SELECT statement to be used for all the comparisons in the select group. The WHEN operation code is not used when the SELECT operation has an operand. Instead, two new operation codes are used for the comparisons.

• Use new operation code WHEN-IN to start a block where the select operand is IN the WHEN-IN operand.
• Use new operation code WHEN-IS to start a block where the select operand is equal to the WHEN-IS operand.

SELECT a.b(i).c(j);
WHEN-IS 0;
   // Handle a.b(i).c(j) = 0
WHEN-IN %RANGE(5 : 20);
   // Handle a.b(i).c(j) between 5 and 100
WHEN-IN %LIST(2 : 3 : N : M + 1):
   // Handle a.b(i).c(j) = 5, 10, N, or (M + 1)
WHEN-IS N + 1;
   // Handle a.b(i).c(j) = N + 1
OTHER;
   // Handle any other values for a.b(i).c(j)
ENDSL;

See SELECT (Begin a Select Group), WHEN-IN (When the SELECT Operand is IN the WHEN-IN Operand), and WHEN-IS (When the SELECT Operand is Equal to the WHEN-IS Operand).

This enhancement is available with a compile-time PTF in the first half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Note:

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

Support for PCML version 8

If you want to take advantage of version 8 of PCML, you can specify *V8 in the PGMINFO keyword, or you can set environment variable QIBM_RPG_PCML_VERSION to the value '8.0' at compile time.

With PCML version 8, the generated PCML adds a "boolean" attribute to indicator items.

CTL-OPT PGMINFO(*PCML : V8);

See PGMINFO(*PCML | *NO | *DCLCASE { : *MODULE { : *Vx }}).

This enhancement is available with a compile-time PTF in the first half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) and TGTRLS(V7R3M0) with compile-time PTFs.

This enhancement is also available in 7.3 and 7.4 with compile-time PTFs.

Note:

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

New command parameter to improve CRTSQLRPGI with *LVL1 or *LVL2 for the RPGPPOPT parameter

If you use the CRTSQLRPG with RPGPPOPT(*LVL1) or RPGPPOPT(*LVL2), you can control the record length of the output file QTEMP/QSQLPRE created by the RPG preprocessor. The default record length is 112, which supports a line length up to 100. If your fully-free source is in a stream file, the default line length of 100 might not be long enough to handle all the lines in the source.

You can control the line length of the file created by the RPG preprocessor in two ways.

• To request that the QTEMP/QSQLPRE file be created with a specific line length, you can use environment variable QIBM_RPG_PPSRCFILE_LENGTH.

  For example, if you know that a line length of 500 is sufficient for all the source in the compilation, specify a value of 500 for the environment variable.

  
  ADDENVVAR QIBM_RPG_PPSRCFILE_LENGTH VALUE(500)
  

• If the environment variable is not present, the new parameter PPMINOUTLN for CRTBNDRPG and CRTRPGMOD sets the minimum line length for the output file.

  If the length of a line in the source file specified by the SRCFILE parameter or the maximum length of a line in the source file specified by the SRCSTMF parameter is longer than the length specified by the PPMINOUTLN parameter, the output file is created with the longer length.

  For example, to request that the QTEMP/QSQLPRE file be created with a line length at least 500, specify COMPILEOPT('PPMINOUTLN(500)'). That will cause the RPG preprocessor to create the output file with a line length that is at least 500, but might be longer if the longest line in the input file is longer than 500.

  
  CRTSQLRPGI MYLIB/MYPGM SRCSTMF('mypgm.sqlrpgle') RPGPPOPT(*LVL1) COMPILEOPT('PPMINOUTLN(500)')
  

This enhancement is available with compile-time PTFs in the first half of the year 2023.

This enhancement is also available for TGTRLS(V7R4M0) and TGTRLS(V7R3M0) with compile-time PTFs.

This enhancement is also available in 7.3 and 7.4 with compile-time PTFs.

Note:

See https://www.ibm.com/support/pages/node/6857461 for PTF details.

Options to process strings by natural characters instead of bytes or double bytes

By default, RPG processes strings in the CHARCOUNT STDCHARSIZE, by bytes for alphanumeric data and by double bytes for UCS-2 and graphic data. If the data type is UTF-8, UTF-16, or mixed SBCS/DBCS, the number of bytes for each character can be different. When strings are processed by bytes or double bytes, the result might not be correct.

Several features are available to request that RPG handle strings by the natural size of each character. See Processing string data by the natural size of each character.

• Control specification keyword CHARCOUNTTYPES sets the data types affected by the CHARCOUNT(*NATURAL) Control keyword or the /CHARCOUNT NATURAL directive.
• Directive /CHARCOUNT sets the CHARCOUNT mode for file definitions and calculations following the directive.
• Control specification keyword CHARCOUNT sets the initial CHARCOUNT mode.
• Keyword CHARCOUNT for file definitions sets the CHARCOUNT mode for moving data from RPG expressions to the output buffer and key buffer for the file.
• New built-in function %CHARCOUNT returns the number of natural characters.
• You can specify either *NATURAL or *STDCHARSIZE for built-in functions that handle strings.
  Note: However, note that %LEN and %STR always operate in the standard-character-size mode.

In the following example

1. The CHARCOUNTTYPES specifies that only UTF-8 data is handled by CHARCOUNT NATURAL mode.
2. The UTF-8 value "ábç" is assigned to variable string. The UTF-8 characters 'á' and 'ç' have two bytes. There are three characters and five bytes.
3. The %LEN built-in function always operates in CHARCOUNT STDCHARSIZE mode, so it returns 5.
4. The %CHARCOUNT built-in function always operates in CHARCOUNT NATURAL mode, so it returns 3.
5. The %SUBST built-in function has a starting position of 1 and a length of 3. This statement is in CHARCOUNT STDCHARSIZE mode because the CHARCOUNT mode has not been set by either the CHARCOUNT Control keyword or the /CHARCOUNT directive. The substring assigned to variable string2 has three bytes, "áb".
6. The %SUBST built-in function has *NATURAL specified as the last parameter. This statement is in CHARCOUNT STDCHARSIZE mode but the %SUBST built-in function operates in CHARCOUNT NATURAL mode. The substring assigned to variable string2 has three characters, "ábç".
7. Directive /CHARCOUNT sets the mode to CHARCOUNT NATURAL.
8. The %LEN built-in function always operates in CHARCOUNT STDCHARSIZE mode, so it returns 5.
9. The %CHARCOUNT built-in function always operates in CHARCOUNT NATURAL mode, so it returns 3.
10. The %SUBST built-in function has a starting position of 1 and a length of 3. This statement is in CHARCOUNT NATURAL mode due to the /CHARCOUNT NATURAL directive. The substring assigned to variable string2 has three characters, "ábç".
11. The %SUBST built-in function has *STDCHARSIZE specified as the last parameter. This statement is in CHARCOUNT NATURAL mode but the %SUBST built-in function operates in CHARCOUNT STDCHARSIZE mode. The substring assigned to variable string2 has three bytes, "áb".

CTL-OPT CHARCOUNTTYPES(*UTF8); //  1 

DCL-S string VARCHAR(10) CCSID(*UTF8);
DCL-S string2 VARCHAR(10) CCSID(*UTF8);
DCL-S n INT(10);

string = 'ábç';  //  2 

n = %LEN(string); //  3 
// n = 5

n = %CHARCOUNT(string); //  4 
// n = 3

string2 = %SUBST(string : 1 : 3); //  5 
// string2 = 'áb'

string2 = %SUBST(string : 1 : 3 : *NATURAL); //  6 
// string2 = 'ábç'

/CHARCOUNT NATURAL //  7 

n = %LEN(string); //  8 
// n = 5

n = %CHARCOUNT(string); //  9 
// n = 3

string2 = %SUBST(string : 1 : 3); //  10 
// string2 = 'ábç'

string2 = %SUBST(string : 1 : 3 : *STDCHARSIZE); //  11 
// string2 = 'áb'

See Processing string data by the natural size of each character.

This enhancement is available with a compile-time PTF and a runtime PTF in the second half of the year 2022.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF and a runtime PTF.

Warning: You must ensure that the runtime PTF is applied on any system where the program is restored.

Different runtime PTFs are required for 7.4 and 7.5 systems.

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

New built-in function %CONCAT

%CONCAT concatenates several strings with a common separator between the strings.

In the following example, name, addr, and city are concatenated into a result string, separated by the first operand, which is a comma followed by a space.

DCL-S list VARCHAR(50);
DCL-S name VARCHAR(10) INZ('Sally');
DCL-S addr VARCHAR(20) INZ('123 Elm St.');
DCL-S city VARCHAR(20) INZ('Springfield');

list = %CONCAT(', ' : name : addr : city);
// list = "Sally, 123 Elm St., Springfield"

If no separator is required, you can specify *NONE. If a single blank is required as the separator, you can specify *BLANK or *BLANKS.

list = %CONCAT(*BLANKS : name : addr : city);
// list = "Sally 123 Elm St. Springfield"

See %CONCAT (Concatenate with Separator).

This enhancement is available with a compile-time PTF in the second half of the year 2022.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Note:

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

New built-in function %CONCATARR

%CONCATARR concatenates the elements of an array with a common separator between the elements.

In the following example, the array elements are concatenated into a result string, separated by the first operand, which is a comma followed by a space.

DCL-S list VARCHAR(50);
DCL-S arr VARCHAR(20) DIM(3);

arr(1) = 'Cat';
arr(2) = 'Dog';
arr(3) = 'Pony';
list = %CONCATARR(', ' : arr);
// list = "Cat, Dog, Pony"

The array operand can be any array expression, including %SUBARR, %LIST, and %SPLIT.

If no separator is required, you can specify *NONE. If a single blank is required as the separator, you can specify *BLANK or *BLANKS.

list = %CONCATARR(*NONE :  arr);
// list = "CatDogPony"

See %CONCATARR (Concatenate Array Elements with Separator).

This enhancement is available with a compile-time PTF in the second half of the year 2022.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

Note:

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.

OPTIONS(*CONVERT) to convert parameters to strings

With OPTIONS(*CONVERT), the passed parameter can have a different type from the prototyped parameter.

• When OPTIONS(*CONVERT) is specified for a prototyped parameter of type alphanumeric or UCS-2, the passed parameter can be numeric, date, time, timestamp, alphanumeric, graphic, or UCS-2.
• When OPTIONS(*CONVERT) is specified for a prototyped parameter of type pointer, the passed parameter can be numeric, date, time, timestamp, alphanumeric, graphic, UCS-2, or pointer.

If the prototyped parameter is alphanumeric or UCS-2, and the passed parameter is numeric, date, time or timestamp, the value is first converted to character using the %CHAR rules, and then it is converted to the required type of the prototyped parameter.

If the prototyped parameter has type pointer, and the passed parameter is not a pointer, the parameter is converted to a null-terminated string in the job CCSID. If the passed parameter is a pointer, no conversion is needed.

In the following example, the parameters received by the procedure are

1. "2022-12-25     "
2. "25.7", converted to a varying-length UCS-2 value
3. A null-terminated string in the job CCSID with the value "/home/mydir/myfile.txt"

DCL-PR myProc;
   p1 CHAR(15) CONST OPTIONS(*CONVERT);     //  1 
   p2 VARUCS2(20) CONST OPTIONS(*CONVERT);  //  2 
   p3 POINTER VALUE OPTIONS(*CONVERT);      //  3 
END-PR;
DCL-S filename VARUCS2(30) INZ('/home/mydir/myfile.txt');

myProc (D'2022-12-25'     //  1 
      : 25.7              //  2 
      : filename);        //  3 

Note: See OPTIONS(*CONVERT).

This enhancement is available with a compile-time PTF in the second half of the year 2022.

This enhancement is also available for TGTRLS(V7R4M0) with a compile-time PTF.

This enhancement is also available in 7.4 with a compile-time PTF.

See https://www.ibm.com/support/pages/rpg-cafe for PTF details.