Parameter passed to a DATA-GEN generator
The parameter that is passed to a DATA-GEN generator is a data structure with type QrnDgParm_T.
The parameter is defined in member QRNDTAGEN of source file QRPGLESRC for ILE RPG, QCBLLESRC for ILE COBOL, and H for ILE C/C++.
The parameter has the following subfields.
- generatorState
- (Input and output) A pointer that is holding state information that is owned by the generator.
The generator can place a pointer here, and the same pointer is available
for all subsequent calls to the generator until the operation ends.
If the operation is part of a sequence of DATA-GEN operations, started by DATA-GEN *START and ended by DATA-GEN *END, the pointer is available for all subsequent calls to the generator in the entire sequence. See Sequences of DATA-GEN operations.
Use the doTerminateEvent subfield to ensure that the generator is called for the QrnDgEvent_12_Terminate event so that it can reliably perform cleanup-operations such as deallocating the generatorState pointer.
- env
- (Input only) A pointer to a structure with callback procedure pointers. See Enabling calls to the callback procedures for information on the way to use this pointer to enable calling the callback procedures.
- handle
- (Input only) A pointer that is passed to every callback procedure.
- userParm
- (Input and output)
A pointer to the second operand of %GEN,
owned by the RPG program,
unless the userParmType
subfield has the value QrnUserParmType_nullTerminatedString,
which indicates that the user-parameter is a
null-terminated string, in which case it must be considered read-only.
The userParmSize subfield has the size of the value.
The userParmCcsid subfield has the CCSID of the value.
- userParmSize
- (Input only)
This subfield has the length in bytes of the user-parameter.
If it is a null-terminated string (userParmType is QrnUserParmType_nullTerminatedString), it represents the length of the string.
If it is a varying-length string (userParmType begins with QrnUserParmType_var), it includes the 2 or 4 bytes of the varying-length prefix. See subfield userParmType for the type of the user-parameter. - userParmCcsid
- (Input only)
This subfield indicates the CCSID of the user-parameter.
This subfield is not relevant if the userParm subfield is null, or if the value of the userParmType subfield is QrnUserParmType_notPassed, QrnUserParmType_dataStruct, or QrnUserParmType_other. For the possible values of the userParmType subfield, see Types of the user-parameter passed to the DATA-GEN generator.
- userParmType
- (Input only) This subfield indicates the type of the
value pointed to by the userParm pointer.
Note: Full type information is not available for every type of user-parameter.For the possible values of this parameter, see Types of the user-parameter passed to the DATA-GEN generator.
- outputIsToFile
- (Input only) An indicator whose value is '1' if the output from the callbacks is being written to a stream file; '0' otherwise.
- doTerminateEvent
- (Output) An indicator
that is set to '1' by the
generator if DATA-GEN
should call the generator
with the
QrnDgEvent_12_Terminate event
so that it can do clean-up.
The generator can change it to '0' if
the QrnDgEvent_12_Terminate
event is no longer needed.
The value of this indicator following the most recent call to the generator is used by DATA-GEN when deciding whether to call the generator with the QrnDgEvent_12_Terminate event.
- isPartOfSequence
- (Input only) An indicator whose value is '1' if the DATA-GEN operation is part of a sequence; '0' otherwise.
- name
- (Input only)
The name of the array,
data structure, or scalar
value.
The data type is defined as QrnDgName_t.
It is a varying length UTF-16 value,
with a maximum length of 4096.
This subfield can be used directly if the generator is written in RPG.
if parm.name = *blanks; ...For generators written in other languages, this subfield is a data structure with len and name subfields.
This value is blank for the following events:- QrnDgEvent_01_StartMultiple
- QrnDgEvent_02_EndMultiple
- QrnDgEvent_03_Start
- QrnDgEvent_04_End
- QrnDgEvent_12_Terminate
- event
- (Input only) This subfield indicates the type of event that is passed to the generator. See Events for DATA-GEN generators.
- ds (u.ds for generators written in C)
- (Input only) This subfield must only be used for the following events: The type of the ds data structure is QrnDgDs_T. See Data structure information (type QrnDgDs_T) for the description of this data structure.
- array (u.array for generators written in C)
- (Input only)
This subfield must only be used for the following events:
- QrnDgEvent_07_StartScalarArray
- QrnDgEvent_08_EndScalarArray
- QrnDgEvent_09_StartStructArray
- QrnDgEvent_10_EndStructArray
- scalar (u.scalar for generators written in C)
- (Input only) This subfield must only be used for the QrnDgEvent_11_ScalarValue event. The type of the subfield is QrnDgScalar_T. See Scalar information (type QrnDgScalar_T) for the description of this data structure.
Data structure information (type QrnDgDs_T)
An RPG data structure or data structure subfield is described by the ds subfield of the parameter that is passed to the generator. The type of the ds subfield is QrnDgDs_T.
- elem
- If the data structure is part of an array, this subfield indicates the element number. Otherwise, this subfield is zero. The element number is 1-origin, beginning at 1 and ending with the number of elements indicated by the totalElems subfield.
- totalElems
- If the data structure is part of an array, this subfield indicates the number of elements in the array. Otherwise, this subfield is zero. The current element is indicated by theelem subfield.
- numSubfields
-
This subfield indicates the number of subfields for this data structure.
Tip: If the names of the subfields are needed in advance, this subfield can be used together with the QrnDgGetSubfieldName callback to obtain the subfield names during the QrnDgEvent_05_StartStruct or QrnDgEvent_06_EndStruct events.
- subfieldNumber
- If this RPG data structure is a subfield of another RPG data structure, this subfield indicates the subfield number in that data structure. If this RPG data structure is the top-level variable for the DATA-GEN operation, this subfield is zero. The subfield number is 1-origin, beginning at 1 and ending with the number of subfields in the data structure.
- isExtDesc
- This subfield is an indicator. The value is '1' if the data structure is externally-described, and '0' otherwise.
- extLibrary
- If the data structure is externally-described, this subfield indicates the library with the external file. Otherwise, this subfield is blank.
- extFile
- If the data structure is externally-described, this subfield indicates the external file. Otherwise, this subfield is blank.
- extFormat
- If the data structure is externally-described, this subfield indicates the external record format. Otherwise, this subfield is blank.
- recordLevelId
- If the data structure is externally-described, this subfield indicates the level ID of the external record format. Otherwise, this subfield is blank.
Array information (type QrnDgArray_T)
An RPG data array or array subfield is described by the array subfield of the parameter that is passed to the generator. The type of the array data structure is QrnDgArray_T.
Each element of the array is described by the QrnDgEvent_05_StartStruct event or the QrnDgEvent_11_ScalarValue event.
All the subfields of the QrnDgArray_T data structure are input-only:
- totalElems
- This subfield indicates the number of elements in the array.
- numSubfields
-
If this is an array of data structures,
this subfield indicates the number of subfields for this data structure.
Otherwise, this subfield is zero.
Tip: If the names of the subfields are needed in advance, this subfield can be used together with the QrnDgGetSubfieldName callback to obtain the subfield names during the QrnDgEvent_09_StartStructArray or QrnDgEvent_10_EndStructArray events.
- subfieldNumber
- If this RPG array is a subfield of an RPG data structure, this subfield indicates the subfield number in that data structure. If this RPG array is the top-level variable for the DATA-GEN operation, this subfield is zero. The subfield number is 1-origin, beginning at 1 and ending with the number of subfields in the data structure.
Scalar information (type QrnDgScalar_T)
Scalar information describes an RPG field, subfield, or array element that is not a data structure. The type of the scalar data structure is QrnDgScalar_T.
All the subfields of the QrnDgScalar_T) data structure are input-only:
- elem
- If the scalar item is part of an array, this subfield indicates the element number. Otherwise, this subfield is zero. The element number is 1-origin, beginning at 1 and ending with the number of elements indicated by the totalElems subfield.
- totalElems
- If the scalar item is part of an array, this subfield indicates the number of elements in the array. Otherwise, this subfield is zero. The current element is indicated by the elem subfield.
- definedCcsid
-
This subfield indicates the CCSID of the RPG scalar item.
If the data type of the RPG scalar item is not alphanumeric,
UCS-2, or graphic, this subfield is zero.
Note: This is not the CCSID of the data in the value subfield.
- subfieldNumber
- If this RPG scalar value is a subfield of an RPG data structure, this subfield indicates the subfield number in that data structure. If this RPG scalar value is the top-level variable for the DATA-GEN operation, this subfield is zero. The subfield number is 1-origin, beginning at 1 and ending with the number of subfields in the data structure.
- dataType
-
This subfield indicates the data type of the scalar value.
See Data types used in name-value information.
Note: Varying-length string types are not distinguished from fixed-length string types.
- This subfield is QrnDatatype_Alpha for all alphanumeric scalar values.
- This subfield is QrnDatatype_Unicode for all UCS-2 scalar values.
- This subfield is QrnDatatype_Dbcs for all graphic scalar values.
- dtzFormat
- If the RPG scalar value is of type Date or Time, this subfield gives the format. See Constants QrnDtzFormat_* defining date, time, and timestamp formats.
- separator
-
If the RPG scalar value is of type Date or Time, this subfield gives
the separator character.
If the RPG scalar value is numeric, this subfield gives the decimal point, either period or comma. The decimal point character for numeric values is determined by the DECEDIT keyword in the Control statements of the RPG module. If the DATA-GEN operation is part of a sequence of operations, the decimal point might not be the same for all the DATA-GEN operations in the sequence. For example, a numeric value of 12.3 for one DATA-GEN operation in the sequence might be passed to the generator as "12,3", and the same numeric value for another DATA-GEN operation in a different module might be "12.3".
- valueLenBytes
- This subfield indicates the length of the value measured in bytes.
- valueLenChars
- This subfield indicates the length of the value measured in UTF-16 double-byte characters.
- valueCcsid
- This subfield indicates the CCSID of the
value subfield.
Note: This is not necessarily the CCSID of the RPG scalar item. Use the definedCcsid to determine the CCSID of the RPG scalar item.
- value
- This subfield is a pointer to the UTF-16 value
of the RPG scalar item, in human-readable form.
The length of the value in bytes is given by the valueLenBytes subfield.
The length of the value in double-byte characters is given by the valueLenChars subfield.
String data (types QrnDatatype_Alpha, QrnDatatype_Unicode, and QrnDatatype_Dbcs) is trimmed of leading and trailing blanks unless option "trim=none" is specified for the DATA-GEN operation. See the DATA-GEN section of the IBM® Rational® Development Studio for i: ILE RPG Reference for information on the trim option.
Numeric data is edited with a leading sign if the value is negative. For QrnDatatype_Decimal and QrnDatatype_Float data, the decimal point is either a period or a comma, determined by the DECEDIT keyword of the RPG module. See scalar.separator.
Date, Time, and Timestamp data is edited according to the format and separators of the field in the RPG module.
