What's New since 7.4?

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

This section describes the enhancements made to ILE RPG after 7.4 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.

Warning: Some enhancements require a compile-time PTF and a runtime PTF.

If a program uses an enhancement that requires a runtime PTF, you must ensure that the runtime PTF is applied on any system where the program is restored.

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

New built-in functions %LOWER and %UPPER
You can convert the case of a character or UCS-2 string to lower case using the %LOWER built-in function or to upper case using the built-in function %UPPER.

You can limit the conversion to only part of the string by specifying the start and length for the conversion.

In the following example, the characters following the first character are converted to lower case.

DCL-S string VARCHAR(20);

string = %LOWER('GÖTEBORG' : 2);
// string = "Göteborg"

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

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

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

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

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

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

New built-in function %SPLIT
You can split a string into a temporary array of substrings using %SPLIT.

By default, the string is split at blanks. You can specify a second parameter with the characters you want to split at.

In the following examples, the result of %SPLIT is assigned to an array.

  1. In the first assignment, the string is split at blanks.
  2. In the second assignment, the string is split at either asterisks or blanks.

DCL-S array VARCHAR(20) DIM(10);

array = %SPLIT(' **One** **Two** **Three** '); //  1 
// array(1) = '**One**'
// array(2) = '**Two**'
// array(3) = '**Three**'

array = %SPLIT(' **One** **Two** **Three** ' : ' *');  //  2 
// array(1) = 'One'
// array(2) = 'Two'
// array(3) = 'Three'

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 2021.

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

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

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

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

A new option *STRICTKEYS is added to the EXPROPTS Control keyword.
When EXPROPTS(*STRICTKEYS) is specified, the rules are more strict for specifying the search argument for keyed file operations using a list of keys or %KDS.

See *STRICTKEYS.

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

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

New built-in function %RANGE
You can check whether a value is in the range of two other values by using the %RANGE built-in function.
In the following example, the IF statement is true if num is greater than or equal to 1 and less than or equal to 10.

DCL-S num PACKED(15:5);

IF num IN %RANGE(1 : 10);
   ...
ENDIF;

See %RANGE (lower-limit : upper-limit).

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

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

New built-in function %LIST
You can define a temporary array by using built-in function %LIST. %LIST is allowed in calculations anywhere an array is allowed except SORTA, %LOOKUPxx, or %SUBARR.
In the following example, the first four elements of the libraries array are assigned from the values in the %LIST built-in function. The first element of libraries is assigned the value 'QGPL', the second element is assigned the value of variable currentUserProfile and so on.

DCL-S libraries CHAR(10) DIM(10);

libraries = %LIST ('QGPL'
                 : currentUserProfile
                 : 'QTEMP'
                 : getDevLib ());

See %LIST (item { : item { : item ... } } ).

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

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

New operation code FOR-EACH
The FOR-EACH operation code begins a group of operations that iterates through the elements of an array, %LIST, or %SUBARR.

The first operand of FOR-EACH is a variable that receives the value of the current element in the array or %LIST.

The loop ends with the ENDFOR operation code.

In the following example, each element of the filenames array is processed in the FOR-EACH group. Within the group of operation codes between the FOR-EACH operation and the ENDFOR operation, the file variable has the value of the current element of the filenames array.

DCL-S filenames CHAR(10) DIM(10);
DCL-S file CHAR(10);
DCL-S numFilenames INT(10);
...
FOR-EACH file in %SUBARR(filenames : 1 : numFilenames);
   process (file);
ENDFOR;

See FOR-EACH (For Each).

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

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

New IN operator
The IN operator is used to determine whether an item is in an array or %LIST, or in a range.

IF item IN %RANGE(lower_limit : upper_limit);
   ...
ENDIF;
IF item IN myArray;
   ...
ENDIF;

IF item IN %LIST(item1 : item2 : ...);
ENDIF;

See IN operator.

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

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

Allow blanks for built-in functions that convert character to numeric
A new option *ALWBLANKNUM is added to the EXPROPTS Control keyword.

When EXPROPTS(*ALWBLANKNUM) is specified, the numeric conversion built-in functions %DEC, %DECH, %FLOAT, %INT, %INTH, %UNS, and %UNSH, a blank character value is allowed. These built-in functions return zero if the character operand is blank or it has a length of zero. For DATA-INTO and XML-INTO, if the value for a numeric field is blank or empty, a value of zero is placed in the value.

In the following example, the %DEC operation does not fail due to a blank value because EXPROPTS(*ALWBLANKNUM) is specified.

CTL-OPT EXPROPTS(*ALWBLANKNUM);

DCL-S num PACKED(15:5);
DCL-S string CHAR(10) INZ(*BLANKS);

num = %DEC(string : 63 : 15);

See EXPROPTS(*MAXDIGITS | *RESDECPOS | *ALWBLANKNUM | *USEDECEDIT) and Rules for converting character values to numeric values using built-in functions.

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

This enhancement is also available in 7.3 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.

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

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

Allow thousands separators for built-in functions that convert character to numeric
A new option *USEDECEDIT is added to the EXPROPTS Control keyword.

When EXPROPTS(*USEDECEDIT) is specified, the numeric conversion built-in functions %DEC, %DECH, %FLOAT, %INT, %INTH, %UNS, and %UNSH interpret the period and comma characters according to the setting defined by the Control keyword DECEDIT. This keyword also affects the way the data for a numeric field is processed by DATA-INTO and XML-INTO.

By default, and with DECEDIT('.') or DECEDIT('0.'), or with DECEDIT(*JOBRUN) when the job DECFMT value is not J, the period is the decimal-point character and the comma is the digit-separator (thousands separator) character.

With DECEDIT(',') or DECEDIT('0,'), or with DECEDIT(*JOBRUN) when the job DECFMT value is J, the comma is the decimal-point character and the period is the digit-separator.

In the following example
  • Keyword EXPROPTS(*USEDECEDIT) is specified.
  • Keyword DECEDIT keyword is not specified, so the decimal-point character defaults to the period and the digit-separator character defaults to the comma.
  • The string '1,234,567.89' is allowed for %DEC. The commas are ignored because the comma is the digit-separator character.
  • The %DEC built-in function returns 1234567.89.

CTL-OPT EXPROPTS(*USEDECEDIT);

DCL-S num PACKED(15:5);

num = %DEC('1,234,567.89' : 15 : 5);

See EXPROPTS(*MAXDIGITS | *RESDECPOS | *ALWBLANKNUM | *USEDECEDIT) and Rules for converting character values to numeric values using built-in functions.

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

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

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

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

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

Optionally require prototypes for the main procedure and exported procedures
Parameter REQPREXP is added to the CRTBNDRPG and CRTRPGMOD commands to control how the compiler responds when no prototype is specified for an exported procedure. Additionally, the keyword REQPREXP can be specified as a Control Specification keyword.

The default for the parameter is *NO.

With the *WARN level, the compiler issues a warning diagnostic message.

With the *REQUIRE level, the compiler issues a severe diagnostic message, which causes the compile to fail.

You can specify keyword REQPROTO(*NO) for an exported procedure or for the procedure interface of the cycle-main procedure to indicate that a prototype is never required for the procedure.

See REQPREXP(*NO | *WARN | *REQUIRE), REQPROTO(*NO) for exported procedures, and REQPROTO(*NO) for the procedure interface of the cycle-main procedure.

This enhancement is available with several compile-time PTFs in the last half of the year 2020.

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

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

See or change the return value from a procedure while debugging
If Control keyword DEBUG(*RETVAL) is specified, you can evaluate special variable _QRNU_RETVAL to see or change the value that the procedure will return.
Set a breakpoint on the last statement of the procedure to view or change the value of this variable.
  • In free-form code, set the breakpoint on the END-PROC statement.
  • In fixed-form code, set the breakpoint on the Procedure-End specification.
For example, a programmer is debugging the following procedure.
  1. The procedure returns the value 'abcde'.
  2. The programmer sets a breakpoint on the END-PROC statement.
  3. In the debug session, the programmer displays the return value.

CTL-OPT DEBUG(*RETVAL);
...
DCL-PROC myProc;
   DCL-PI *n CHAR(10) END-PI;

   RETURN 'abcde';  1 
END-PROC;           2 
  1. In the debug session at the END-PROC statement, the programmer displays the return value.
  2. The programmer changes the return value to '12345'.
  3. The value '12345' is returned from the procedure.

> EVAL _qrnu_retval                     1 
  _QRNU_RETVAL = 'abcde     '
> EVAL _qrnu_retval = '12345'           2 
  _QRNU_RETVAL = '12345' = '12345     '

See DEBUG{(*DUMP | *INPUT | *RETVAL | *XMLSAX | *NO | *YES)}.

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

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

%TIMESTAMP to return microsecond precision
%TIMESTAMP() now returns a timestamp with microsecond precision.

If you specify %TIMESTAMP(*UNIQUE), the returned timestamp has a nonzero value for all 12 fractional digits. The first 6 fractional seconds provide microsecond precision. The final 6 digits are used to create a unique timestamp.

See %TIMESTAMP (Convert to Timestamp).

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

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

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

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

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

A variable or expression is allowed for the second parameter of %KDS
The second parameter of %KDS is the number of keys to use for the keyed operation. You can now specify a variable or expression for the second parameter.

DCL-F myfile KEYED;
DCL-DS keys LIKEREC(myRec : *KEY);
DCL-S numKeys INT(10);

numKeys = 3;
CHAIN %KDS(keys : numKeys) myRec;
READE %KDS(keys : numKeys - 1) myRec;
See %KDS (Search Arguments in Data Structure).

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

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

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

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

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

Qualified name for the LIKEDS keyword
You can now specify a qualified name for the LIKEDS keyword. In the following example
  1. Data structure subfield employees is defined directly in data structure employee_info.
  2. The LIKEDS keyword for the parameter for procedure check_employee is defined by using the LIKEDS keyword to define the parameter the same as the qualified subfield employee_info.employeeds.

DCL-DS employee_info QUALIFIED;
   num_employees INT(10);
   DCL-DS employees DIM(20);  //  1 
      name VARCHAR(25);
      salary PACKED(7:2);
   END-DS;
END-DS;
DCL-PR check_employee IND;
   employee LIKEDS(employee_info.employees);  //  2 
END-PI;
See Specifying LIKEDS with a qualified data structure name.

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

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

*ON and *OFF can be logical expressions
You can now use *ON and *OFF directly in conditional statements. For example, if you want an infinitely DOW loop, you can code "DOW *ON".

   DOW *ON;
    ...
   ENDDO;

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

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

New operation code DATA-GEN
DATA-GEN generates a structured document, such as JSON or CSV, from an RPG variable. It requires a generator to generate the document. The DATA-GEN operation calls the generator, passing it the names and values of the RPG variables, and the generator passes the text for the structured document back to the DATA-GEN operation, which places the information into the output file or the output RPG variable.

DCL-DS product QUALIFIED;
   name VARCHAR(25);
   id CHAR(10);
   price PACKED(9 : 2);
END-DS product;

DATA-GEN product %DATA('ProductInfo.JSON' : 'doc=file')
                  %GEN('MYLIB/MYJSONGEN');
See DATA-GEN (Generate a Document from a Variable), %DATA (document {:options}), %GEN (generator {: options}).

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

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

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

If you compile your program with TGTRLS(*V7R3M0), different runtime PTFs are required for 7.3 and 7.4 systems.

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

Overloaded prototypes
The OVERLOAD keyword defines a list of other prototypes that can be called by using the name of the prototype with the OVERLOAD keyword. When the prototype with the OVERLOAD keyword is used in a call operation, the compiler uses the parameters that are specified for the call to determine which of the candidate prototypes that are listed in the OVERLOAD keyword to call.
In the following example, FORMAT is defined with the OVERLOAD keyword.
  1. For the first call to FORMAT, the parameter has type Date, so FORMAT_DATE is called.
  2. For the second call to FORMAT, the parameter has type Time, so FORMAT_TIME is called.
  3. For the second call to FORMAT, the parameters have type Character, so FORMAT_MESSAGE is called.

DCL-PR format_date VARCHAR(100);
   dateParm DATE(*ISO) CONST;
END-PR;
DCL-PR format_time VARCHAR(100);
   timeParm TIME(*ISO) CONST;
END-PR;
DCL-PR format_message VARCHAR(100);
   msgid CHAR(7) CONST;
   replacement_text VARCHAR(100) CONST OPTIONS(*NOPASS);
END-PR;
DCL-PR format VARCHAR(100) OVERLOAD(format_time : format_date : format_message);
DCL-S result varchar(50);

result = format(%date());              //  1 
result = format(%time());              //  2 
result = format('MSG0100' : filename); //  3 
See OVERLOAD(prototype1 { : prototype2 ...}).

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

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

OPTIONS(*EXACT) for prototyped parameters
When OPTIONS(*EXACT) is specified for a prototyped parameter, additional rules apply to ensure that the called procedure receives the same value as the passed parameter. For example, without OPTIONS(*EXACT), the compiler allows the passed parameter to be longer than the prototyped parameter, and it allows a data structure to be passed that is related by LIKEDS to a different data structure from the passed parameter. With OPTIONS(*EXACT), the passed parameter cannot be longer than the prototyped parameter, and if the prototyped parameter is defined with LIKEDS keyword, the passed parameter must be related by LIKEDS to the same data structure.

In the following example, field fld10 can be passed to parameter parm5 of prototype p1, but the called procedure receives the value "abcde" instead of the full value 'abcdefghij' of fld10.

Field fld10 cannot be passed to parameter parm5Exact of prototype p2 because the length, 10, of fld10 is greater than the length, 5, of the prototyped parameter parm5Exact.


dcl-pr p1;
   parm5 char(5);
end-pr;
dcl-pr p2;
   parm5Exact char(5) OPTIONS(*EXACT);
end-pr;
dcl-s fld10 char(10) inz('abcdefghij');

p1 (fld10);
p2 (fld10);  // Error
See OPTIONS(*EXACT).

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

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

Table 1. Changed Language Elements Since 7.4: Built-in functions
Element Description
%KDS A variable can now be specified as the second parameter of %KDS See %KDS (Search Arguments in Data Structure).
%TIMESTAMP %TIMESTAMP() returns a value with microsecond precision. %TIMESTAMP(*UNIQUE) returns a unique timestamp. See %TIMESTAMP (Convert to Timestamp).
Table 2. Changed Language Elements Since 7.4: Control specification keywords
Element Description
DEBUG keyword Specify parameter *RETVAL if you want to debug the return value from a procedure. See DEBUG{(*DUMP | *INPUT | *RETVAL | *XMLSAX | *NO | *YES)}.
EXPROPTS keyword Parameters *ALWBLANKNUM, *USEDECEDIT, and *STRICTKEYS can now be specified for the EXPROPTS keyword. See EXPROPTS(*MAXDIGITS | *RESDECPOS | *ALWBLANKNUM | *USEDECEDIT).
Table 3. Changed Language Elements Since 7.4: Definitions
Element Description
LIKEDS Allows a qualified name See Specifying LIKEDS with a qualified data structure name.
OPTIONS(*EXACT) The OPTIONS keyword for a prototyped parameter can have value *EXACT, indicating that additional rules should be applied by the compiler when checking the validity of the passed parameter. See OPTIONS(*EXACT).
Table 4. New Language Elements Since 7.4: Directives
Element Description
/OVERLOAD Specify /OVERLOAD DETAIL to obtain detailed information about calls to overloaded prototypes in the statements following the directive. Specify /OVERLOAD NODETAIL to stop obtaining the detailed information. See /OVERLOAD DETAIL | NODETAIL.
Table 5. New Language Elements Since 7.4: Definition specification keywords
Element Description
OVERLOAD Defines candidate prototypes that can be called by the name of the overloaded prototype (the prototype with the OVERLOAD keyword) See OVERLOAD(prototype1 { : prototype2 ...}).
REQPROTO REQPROTO(*NO) can be specified on the procedure interface for the cycle-main procedure to indicate that a prototype is never required. See REQPROTO(*NO).
Table 6. New Language Elements Since 7.4: Control specification keywords
Element Description
REQPREXP Controls whether prototypes are required for the main procedure and exported subprocedures. See REQPREXP(*NO | *WARN | *REQUIRE).
Table 7. New Language Elements Since 7.4: Expression Operators
Element Description
IN Used in a binary conditional statement that tests whether the first operand is in the second operand. See IN operator.
Table 8. New Language Elements Since 7.4: Built-in functions
Element Description
%GEN Specifies the generator for the DATA-GEN operation code See %GEN (generator {: options}).
%LIST Returns a temporary array See %LIST (item { : item { : item ... } } ).
%LOWER Returns the input string converted to lower case. See %LOWER (Convert to Lower Case).
%RANGE Specifies the range to check with the IN operator See %RANGE (lower-limit : upper-limit).
%SPLIT Returns an array of substrings See %SPLIT (Split String into Substrings).
%UPPER Returns the input string converted to upper case. See %UPPER (Convert to Upper Case).
Table 9. New Language Elements Since 7.4: Operation codes
Element Description
DATA-GEN Generate a structured document from an RPG variable. See DATA-GEN (Generate a Document from a Variable).
FOR-EACH Iterate through the items in an array, %LIST, or sub-array See FOR-EACH (For Each).
Table 10. New Language Elements Since 7.4: Procedure specification keywords
Element Description
REQPROTO REQPROTO(*NO) indicates that a prototype is never required for the exported procedure. See REQPROTO(*NO).