What's New in 7.5?

This section describes the enhancements made to ILE RPG in 7.5.

New operation code SND-MSG

With SND-MSG, you can send an informational message or an escape message to a program or procedure on the call stack.

• In the following example, "Hello from RPG" is sent to the joblog as an informational message.

  The two SND-MSG operations are equivalent. The first SND-MSG defaults to having *INFO as the message type. The second SND-MSG explicitly specifies *INFO.

  When *INFO is specified as the message-type, or the message-type operand is not specified, the message is sent by default to the current procedure.

  
  DCL-S name VARCHAR(20) inz('RPG');
  
  SND-MSG 'Hello from ' + name;
  
  SND-MSG *INFO 'Hello from ' + name;
  

• In the following example, message ACT1234 from message file *LIBL/MYMSGF is sent as an escape message to the caller of the current procedure. When *ESCAPE is specified, the message is sent by default to the caller of the current procedure.

  Assume that the message has two replacement values.

  1. TYPE(*CHAR) LEN(25)
  2. TYPE(*DEC) LEN(10)

  
  DCL-DS ACT1234_text qualified;
     account_name char(25);
     account_number packed(10);
  END-DS;
  
  CHAIN (acct_num) FILE;
  IF NOT %FOUND();
     ACT1234_text.account_name = name;
     ACT1234_text.account_number = acct_num;
     SND-MSG *ESCAPE %MSG('ACT1234' : 'MYMSGF' : ACT1234_text);
  ENDIF;
  

• The SND-MSG operation in the following example is similar to the previous example, but the message is explicitly sent to the call-stack entry 'MYCLPGM'. The RPG programmer expects that a program called MYCLPGM has been called before the current procedure, and that MYCLPGM has not returned yet. If the RPG programmer is debugging the program, and uses the DSPJOB command with parameter OPTION(*PGMSTK), the program stack must show that MYCLPGM is an active caller of the current procedure.

  
     SND-MSG *ESCAPE %MSG('ACT1234' : 'MYMSGF' : ACT1234_text)
                     %TARGET('MYCLPGM');
  

• The SND-MSG operation in the following example is similar to the previous example, but the message is explicitly sent to the caller of MYCLPGM, by specifying the value 1 for the offset operand of %TARGET.

  
     SND-MSG *ESCAPE %MSG('ACT1234' : 'MYMSGF' : ACT1234_text)
                     %TARGET('MYCLPGM' : 1);
  

• If an error occurs while sending the message, the SND-MSG operation fails with new status code 126. If you send an escape message to the current procedure, the RPG procedure fails with status code 9999.

See SND-MSG (Send a Message to the Joblog).

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

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

New operation code ON-EXCP

You can monitor for specific message IDs in a MONITOR group by listing the message IDs in an ON-EXCP operation code. ON-EXCP is similar to ON-ERROR, but with ON-EXCP, you list the message IDs to be monitored.

The ON-EXCP operations must precede any ON-ERROR operations in the MONITOR group.

Specify the (C) extender to limit ON-EXCP to escape messages sent to the procedure containing the ON-EXCP statement.

In the following example, the MONITOR group has two ON-EXCP blocks and one ON-ERROR block.

MONITOR;
ON-EXCP 'ABC1234' : 'ABC2345';
   // handle exception messages
ON-EXCP 'DEF1234';
   // handle another exception message
ON-ERROR 222;
   // handle pointer-not-set
ENDMON;

See ON-EXCP (On Exception).

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

This enhancement is also available in 7.3 and 7.4 with a compile-time PTF and a runtime 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 also available in 7.3 and 7.4 with a compile-time PTF and a runtime PTF in the last half of the year 2019.

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2020.

Sort an array data structure by more than one subfield

Use %FIELDS to list the subfields for sorting an array data structure.

In the following example, data structure array info is sorted by subfields dueDate and orderId. To determine the required order of two elements of info, subfield dueDate is compared first. If the value of dueDate is equal in the two elements, then subfield orderId is used to determine the order of the two elements of info.

info(2).dueDate is greater than info(3).dueDate so it is not necessary to compare the second subfield orderId to determine the relative order of elements 2 and 3.

info(1).dueDate is equal to info(3).dueDate so info(1).orderId is compared to info(3).orderId to determine the relative order of elements 1 and 3.

DCL-DS info QUALIFIED DIM(3);
   orderId packed(5);
   dueDate DATE(*ISO);
   quantity int(10);
END-DS;

info(1).orderId = 23456;
info(1).dueDate = D'2021-09-08';
info(1).quantity = 5;

info(2).orderId = 12345;
info(2).dueDate = D'2021-10-08';
info(2).quantity = 3;

info(3).orderId = 12345;
info(3).dueDate = D'2021-09-08';
info(3).quantity = 25;

SORTA info %FIELDS(dueDate : orderId);

// info(1).orderId = 12345
// info(1).dueDate = D'2021-09-08'
// info(1).quantity = 25
//
// info(2).orderId = 23456
// info(2).dueDate = D'2021-09-08'
// info(2).quantity = 5
//
// info(3).orderId = 12345
// info(3).dueDate = D'2021-10-08'
// info(3).quantity = 3

See %FIELDS (Subfields for sorting).

This enhancement is also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2021.

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2020.

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2020.

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2020.

New built-in functions %LOWER and %UPPER

You can convert the case of a character or UCS-2 string to lower case by using the %LOWER built-in function or to upper case by 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 also available in 7.3 and 7.4 with a compile-time PTF and a runtime PTF in the first half of the year 2021.

New built-in function %SPLIT

You can split a string into a temporary array of substrings by 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 also available in 7.3 and 7.4 with a compile-time PTF and a runtime PTF in the first half of the year 2021.

New built-in functions %MAXARR and %MINARR

You can find the index of the maximum value or minimum value in an array using %MAXARR or %MINARR.

In the following example

1. After the assignment from %LIST, the maximum value in the array is 'Yellow' (array1(2)). The minimum value is 'Blue' (array1(3)).
2. %MAXARR(array1) returns 2.
3. %MINARR(array1) returns 3. When %MINARR(array1) is used as an index for array1, the value assigned to minVal is 'Blue'.

DCL-S array1 VARCHAR(10) DIM(3);
DCL-S i INT(10);
DCL-S minVal LIKE(array1);

array1 = %LIST('Red' : 'Yellow' : 'Blue'); //  1 

i = %MAXARR(array1); //  2 
// i = 2

minVal = array1(%MINARR(array1)); //  3 
// minVal = 'Blue'

See %MAXARR and %MINARR (Maximum or Minimum Element in an Array).

This enhancement is also available in 7.4 and 7.4 with a compile-time PTF in the last half of the year 2021.

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 by using a list of keys or %KDS.

See *STRICTKEYS.

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

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 also available in 7.3 and 7.4 with a compile-time PTF and a runtime PTF in the last half of the year 2020.

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 also available in 7.3 and 7.4 with a compile-time PTF and a runtime PTF in the last half of the year 2020.

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.

The /OVERLOAD directive can be used to request more information in the compile listing about how the compiler determines which procedure 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 ...}) and /OVERLOAD DETAIL | NODETAIL.

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

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2019.

See the value of named constants in the debugger

Specify Control keyword DEBUG(*CONSTANTS) to enable viewing the value of named constants in the debugger.

CTL-OPT DEBUG(*CONSTANTS);

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

This enhancement is also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2021.

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2020.

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 also available in 7.3 and 7.4 with compile-time PTFs in the last half of the year 2020.

%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 also available in 7.3 and 7.4 with a compile-time PTF and a runtime PTF in the first half of the year 2020.

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 also available in 7.3 and 7.4 with a compile-time PTF and a runtime PTF in the first half of the year 2020.

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2019.

*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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2019.

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 also available in 7.3 and 7.4 with a compile-time PTF in the last half of the year 2019.

The BOOLEAN data type is supported for ILE RPG

When a field in a database file is defined with type BOOLEAN, the field is considered to have Indicator type in RPG.