The following list describes the enhancements made to ILE RPG in V5R4:
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.
%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.
%HANDLER (handlingProcedure : communicationArea )
%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.
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.
XML-SAX{ (e) } %HANDLER(eventHandler : commArea ) %XML(xmldocument { : saxOptions } );
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.
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:
Various options may be specified to control the operation.
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 '
PREFIX('' : number_of_characters)
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, specifying 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.
DEBUG { ( *INPUT *DUMP *XMLSAX *NO *YES ) }
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.
===> 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'
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. |