What's New in V5R4?
The following list describes the enhancements made to ILE RPG in V5R4:
- New operation code EVAL-CORR
-
EVAL-CORR{(EH)} ds1 = ds2
New operation code EVAL-CORR assigns data and null-indicators from the subfields of the source data structure to the subfields of the target data structure. The subfields that are assigned are the subfields that have the same name and compatible data type in both data structures.
For example, if data structure DS1 has character subfields A, B, and C, and data structure DS2 has character subfields B, C, and D, statement EVAL-CORR DS1 = DS2; will assign data from subfields DS2.B and DS2.C to DS1.B and DS1.C. Null-capable subfields in the target data structure that are affected by the EVAL-CORR operation will also have their null-indicators assigned from the null-indicators of the source data structure's subfields, or set to *OFF, if the source subfield is not null-capable.
// DS1 subfields DS2 subfields // s1 character s1 packed // s2 character s2 character // s3 numeric // s4 date s4 date // s5 character EVAL-CORR ds1 = ds2; // This EVAL-CORR operation is equivalent to the following EVAL operations // EVAL ds1.s2 = ds2.s2 // EVAL ds1.s4 = ds2.s4 // Other subfields either appear in only one data structure (S3 and S5) // or have incompatible types (S1).
EVAL-CORR makes it easier to use result data structures for I/O operations to externally-described files and record formats, allowing the automatic transfer of data between the data structures of different record formats, when the record formats have differences in layout or minor differences in the types of the subfields.
- New prototyped parameter option OPTIONS(*NULLIND)
- When OPTIONS(*NULLIND) is specified for a parameter, the null-byte map is passed with the parameter, giving the called procedure direct access to the null-byte map of the caller's parameter.
- New builtin function %XML
-
%XML (xmldocument { : options } )
The %XML builtin function describes an XML document and specifies options to control how the document should be parsed. The xmldocument parameter can be a character or UCS-2 expression, and the value may be an XML document or the name of an IFS file containing an XML document. If the value of the xmldocument parameter has the name of a file, the "doc=file" option must be specified.
- New builtin function %HANDLER
-
%HANDLER is used to identify a procedure to handle an event or a series of events. %HANDLER does not return a value, and it can only be specified as the first operand of XML-SAX and XML-INTO.%HANDLER (handlingProcedure : communicationArea )
The first operand, handlingProcedure, specifies the prototype of the handling procedure. The return value and parameters specified by the prototype must match the parameters required for the handling procedure; the requirements are determined by the operation that %HANDLER is specified for.
The second operand, communicationArea, specifies a variable to be passed as a parameter on every call to the handling procedure. The operand must be an exact match for the first prototyped parameter of the handling procedure, according to the same rules that are used for checking prototyped parameters passed by reference. The communication-area parameter can be any type, including arrays and data structures.
- New operation code XML-SAX
-
XML-SAX{ (e) } %HANDLER(eventHandler : commArea ) %XML(xmldoc { : options } );
XML-SAX initiates a SAX parse for the XML document specified by the %XML builtin function. The XML-SAX operation begins by calling an XML parser which begins to parse the document. When the parser discovers an event such as finding the start of an element, finding an attribute name, finding the end of an element etc., the parser calls the eventHandler with parameters describing the event. The commArea operand is a variable that is passed as a parameter to the eventHandler providing a way for the XML-SAX operation code to communicate with the handling procedure. When the eventHandler returns, the parser continues to parse until it finds the next event and calls the eventHandler again.
- New operation code XML-INTO
-
XML-INTO{ (EH) } variable %XML(xmlDoc { : options }); XML-INTO{ (EH) } %HANDLER(handler : commArea ) %XML(xmlDoc { : options });
XML-INTO reads the data from an XML document in one of two ways:- directly into a variable
- gradually into an array parameter that it passes to the procedure specified by %HANDLER.
The first operand specifies the target of the parsed data. It can contain a variable name or the % HANDLER built-in function.
The second operand contains the %XML builtin function specifying the source of the XML document and any options to control how the document is parsed. It can contain XML data or it can contain the location of the XML data. The doc option is used to indicate what this operand specifies.
// Data structure "copyInfo" has two subfields, "from" // and "to". Each of these subfields has two subfields // "name" and "lib". // File cpyA.xml contains the following XML document // <copyinfo> // <from><name>MASTFILE</name><lib>CUSTLIB</lib></from> // <to><name>MYFILE</name><lib>*LIBL</lib> // <copyinfo> xml-into copyInfo %XML('cpyA.xml' : 'doc=file'); // After the XML-INTO operation, the following // copyInfo.from .name = 'MASTFILE ' .lib = 'CUSTLIB ' // copyInfo.to .name = 'MYFILE ' .lib = '*LIBL '
- Use the PREFIX keyword to remove characters from the beginning of field names
-
When an empty character literal (two single quotes specified with no intervening characters) is specified as the first parameter of the PREFIX keyword for File and Definition specifications, the specified number of characters is removed from the field names. For example if a file has fields XRNAME, XRIDNUM, and XRAMOUNT, specifyingPREFIX('' : number_of_characters)
PREFIX('':2)
on the File specification will cause the internal field names to be NAME, IDNUM, and AMOUNT.If you have two files whose subfields have the same names other than a file-specific prefix, you can use this feature to remove the prefix from the names of the subfields of externally-described data structures defined from those files. This would enable you to use EVAL-CORR to assign the same-named subfields from one data structure to the other. For example, if file FILE1 has a field F1NAME and file FILE2 has a field F2NAME, and
PREFIX('':2)
is specified for externally-described data structures DS1 for FILE1 and DS2 for FILE2, then the subfields F1NAME and F2NAME will both become NAME. An EVAL-CORR operation between data structures DS1 and DS2 will assign the NAME subfield. - New values for the DEBUG keyword
-
The DEBUG keyword determines what debugging aids are generated into the module. *NO and *YES are existing values. *INPUT, *DUMP and *XMLSAX provide more granularity than *YES.DEBUG { ( *INPUT *DUMP *XMLSAX *NO *YES ) }
- *INPUT
- Fields that are in Input specifications but are not used anywhere else in the module are read into the program fields during input operations.
- *DUMP
- DUMP operations without the (A) extender are performed.
- *XMLSAX
- An array of SAX event names is generated into the module to be used while debugging a SAX event handler.
- *NO
- Indicates that no debugging aids are to be generated into the module. Specifying DEBUG(*NO) is the same as omitting the DEBUG keyword.
- *YES
- This value is kept for compatibility purposes. Specifying DEBUG(*YES) is the same as specifying DEBUG without parameters, or DEBUG(*INPUT : *DUMP).
- Syntax-checking for free-form calculations
- In SEU, free-form statements are now checked for correct syntax.
- Improved debugging support for null-capable subfields of a qualified data structure
- When debugging qualified data structures with null-capable subfields,
the null-indicators are now organized as a similar data structure
with an indicator subfield for every null-capable subfield. The name
of the data structure is _QRNU_NULL_data_structure_name,
for example _QRNU_NULL_MYDS. If a subfield of the data structure is
itself a data structure with null-capable subfields, the null- indicator
data structure will similarly have a data structure subfield with
indicator subfields. For example, if data structure DS1 has null-capable
subfields DS1.FLD1, DS1.FLD2, and DS1.SUB.FLD3, you can display all
the null-indicators in the entire data structure using the debug instruction.
===> EVAL _QRNU_NULL_DS > EVAL _QRNU_NULL_DS1 _QRNU_NULL_DS1.FLD1 = '1' _QRNU_NULL_DS1.FLD2 = '0' _QRNU_NULL_DS1.SUB.FLD3 = '1' ===> EVAL _QRNU_NULL_DS.FLD2 _QRNU_NULL_DS1.FLD2 = '0' ===> EVAL _QRNU_NULL_DS.FLD2 = '1' ===> EVAL DSARR(1).FLD2 DSARR(1).FLD2 = 'abcde' ===> EVAL _QRNU_NULL_DSARR(1).FLD2 _QRNU_NULL_DSARR(1).FLD2 = '0'
- Change to end-of-file behaviour with shared files
-
If a module performs a keyed sequential input operation
to a shared file and it results in an EOF condition, and a different
module sets the file cursor using a positioning operation such as
SETLL, a subsequent sequential input operation by the first module
may be successfully done. Before this change, the first RPG module
ignored the fact that the other module had repositioned the shared
file.
This change in behaviour is available with PTFs for releases V5R2M0 (SI13932) and V5R3M0 (SI14185).
Language Unit | Element | Description |
---|---|---|
Control specification keywords | DEBUG(*INPUT|*DUMP *XMLSAX|*NO|*YES) | New parameters *INPUT, *DUMP and *XMLSAX give more options for debugging aids. |
File specification keywords | PREFIX('':2) |
An empty literal may be specified as the first parameter of the PREFIX keyword, allowing characters to be removed from the beginning of names. |
Definition specification keywords | OPTIONS(*NULLIND) | Indicates that the null indicator is passed with the parameter. |
PREFIX('':2) |
An empty literal may be specified as the first parameter of the PREFIX keyword, allowing characters to be removed from the beginning of names. |
Language Unit | Element | Description |
---|---|---|
Built-in functions | %HANDLER(prototype: parameter) | Specifies a handling procedure for an event. |
%XML(document{:options}) | Specifies an XML document and options to control the way it is parsed. | |
Operation codes | EVAL-CORR | Assigns data and null-indicators from the subfields of the source data structure to the subfields of the target data structure. |
XML-INTO | Reads the data from an XML document directly into a program variable. | |
XML-SAX | Initiates a SAX parse of an XML document. |