Callback procedures for DATA-INTO parsers

The procedure pointers for the callback procedures are subfields of the parameter passed to the parser. See Parameter passed to a DATA-INTO parser.

In RPG, the callback procedures are enabled by setting the env pointer to the env subfield of the parameter passed to the parser. ( 1 )

The prototypes for the callback procedures are in the QRNDTAINTO member of the QOAR/QRPGLESRC source file.


/COPY QOAR/QRPGLESRC,QRNDTAINTO
DCL-PI *n;
   parm LIKEDS(QrnDiParm_T) CONST;
END-PI;

env = parm.env; //  1 
QrnDiStart (...);

In C, the callback procedure pointers are accessed as subfields of the env subfield of the parameter passed to the parser. 2


#include "QOAR/H,QRNDTAINTO"
main (int argc, void *argv[]) {
   const QrnDiParm_T *parm = (QrnDiParm_T *) argv[1];

   parm->env->QrnDiStart (...); //  2 
}

The callback procedures

The first parameter for all the callback procedures is the handle subfield of the parameter that is passed to the parser.

QrnDiStart(handle)

This procedure must be called before any other callback procedures are called.

QrnDiFinish(handle)

This procedure must be called when parsing is complete.

QrnDiReportError(handle, errorCode, bytesParsed)

The parser can call this procedure to report that it found an error in the document.

Note: Control will not return to the parser after this procedure is called.

errorCode must be greater than zero. The meaning of the error code is determined by the parser.
bytesParsed indicates the number of bytes that the parser had parsed when it discovered the error.

QrnDiTrace(handle, msg, nested)

The parser can call this procedure to add its own tracing information. If the nested parameter has the value '1', the message will be issued at the current nesting level of the trace output. If the nested parameter has the value '0', the trace message will be issued starting in column 1 of the trace output.

Note: Tracing is enabled using the QIBM_RPG_DATA_INTO_TRACE_PARSER environment variable. See the DATA-INTO section of the IBM® Rational® Development Studio for i: ILE RPG Reference.

QrnDiReportName(handle, name, nameLength)

The parser calls this procedure to report that it found a name in the document. This may be the name of a structure, an array, or some data.

name is a pointer to the value of the name. The value must be in the same CCSID as the document. If the value is not in the same CCSID as the document, the QrnDiReportNameCcsid procedure must be used instead.
The call to QrnDiReportName must be followed by a call to QrnDiStartStruct, QrnDiStartArray, QrnDiReportValue, or QrnDiReportValueCcsid.
nameLength is the length of the name measured in bytes.

QrnDiReportNameCcsid(handle, name, nameLength, ccsid)

The parser calls this procedure to report that it found a name in the document when the value of the name is in a different CCSID from the CCSID of the document. This may be the name of a structure, an array, or scalar data.

The call to QrnDiReportNameCcsid must be followed by a call to QrnDiStartStruct, QrnDiStartArray,, QrnDiReportValue, or QrnDiReportValueCcsid.

name is a pointer to the value of the name. The value must be in the CCSID specified by the ccsid parameter.
nameLength is the length of the name measured in bytes.
ccsid is the CCSID of the value of the name.

QrnDiReportValue(handle, value, valueLength)

The parser calls this procedure to report that it found a scalar value in the document.

name is a pointer to the value. The value must be in the same CCSID as the document. If the value is not in the same CCSID as the document, the QrnDiReportValueCcsid procedure must be used instead.
valueLength is the length of the value measured in bytes.

Normally, the name for the value must have been previously reported by a prior call to QrnDiReportName. However, the parser may call this procedure without previously reporting a name if the value is the only thing found in the document. In that case, RPG will assume that the name of the value is the same as the name of the target variable.

QrnDiReportValueCcsid(handle, value, valueLength, ccsid)

The parser calls this procedure to report that it found a value in the document when the value is in a different CCSID from the CCSID of the document.

name is a pointer to the value. The value must be in the CCSID specified by the ccsid parameter.
valueLength is the length of the value measured in bytes.
ccsid is the CCSID of the value.

QrnDiReportAttr(handle, name, nameLength, value, valueLength)

The parser calls this procedure to report an attribute of a name. If the name also contains other child items, then they must be preceded by a call to QrnDiStartStruct.

For example, the following sequence of calls is valid, although not all the parameters are shown. The RPG variable matching "employee" must be a data structure with a subfield "type".


QrnDiReportName ("employee")
QrnDiReportAttr ("type", "manager")

The following sequence of calls is also valid, although not all the parameters are shown. The RPG variable matching "employee" must be a data structure with subfields "type" and "id".


QrnDiReportName ("employee")
QrnDiReportAttr ("type", "manager")
QrnDiStartStruct ()
   QrnDiReportName ("id")
   QrnDiReportValue ("12345");
QrnDiEndStruct ()

RPG supports two special attributes that give additional information about scalar fields.

fmt: This specifies the format for a data, time or timestamp value. The valid values for the follow the same rules as RPG uses for %DATE, %TIME and %TIMESTAMP respectively. The format defaults to *ISO with separators. The format may begin with an asterisk, and for formats that allow more than one separator, the format may be followed by the separator.
For example, the following values are valid for a "fmt" attribute: "dmy", "DMY", "*DMY/", "dmy-", "*DMY&", "dmy0".
adjust: A value of "right" causes the value for the name to be right-adjusted in the target RPG variable. Data is left-adjusted by default, but a value of "left" is also supported.

For example, the following sequence of calls is valid, although not all the parameters are shown. The RPG variable matching "id" must be a data structure with subfields "fmt" and "value".


QrnDiReportName ("id")
QrnDiReportAttr ("fmt", "plain")
QrnDiReportAttr ("value", "12A")

If the special attribute is not relevant, or the value is not valid, the attribute is treated as a normal attribute.

QrnDiReportAttrCcsid(handle, name, nameLength, nameCcsid, value, valueLength, valueCcsid)

The parser calls this procedure when the name or value are in a different CCSID from the CCSID of the document. See the discussion for QrnDiReportAttr.

QrnDiStartStruct(handle)

The parser calls this procedure to indicate that the previously reported name is a structure.

The parser may also call this procedure without previously reporting a name if the structure is the outermost stucture in the document. In that case, RPG will assume that the name of the structure is the same as the name of the target variable.

QrnDiEndStruct(handle)

The parser calls this procedure to report that the previously reported structure has ended.

QrnDiStartArray(handle)

The parser calls this procedure to indicate that the previously reported name is an array.

The parser may also call this procedure without previously reporting a name if the array is the outermost stucture in the document. In that case, RPG will assume that the name of the array is the same as the name of the target variable.

Note: The parser only reports the name of the array once. It reports each array element the same way as it reports non-array values, structures, or arrays. For example, if it is an array of scalar values, it calls QrnDiReportName to report the name of the array, then it calls QrnDiStartStruct, then it makes repeated calls to QrnDiReportValue, then it calls QrnDiEndArray.

QrnDiEndArray(handle)

The parser calls this procedure to report that the previously reported array has ended.