Interpreting IFCID 0191 records
Each IFCID 0191 trace record contains a QW0191HD section, one QW0191CR section, and one QW01916B section for each DDM level 6b object that was successfully or unsuccessfully parsed by DDIS.
Depending upon the DDM object that is processed, there might be associated with the QW0191CR section a QW0191FD section, a QW0191RT section, and a QW0191LT section:
- The QW0191FD section is present if the DDM object is either a QRYDSC or the FDODSC scalar contained within the SQLDTA or SQLDTARD objects.
- The QW0191RT section is present if the DDM object is either a QRYDTA or the FDODTA scalar contained within the SQLDTA or SQLDTARD objects.
- The QW0191LT section is present if the DDM object is either a command data object or a reply data object, described by an FDOCA early or late descriptor.
How to read the QW0191HD section
The QW0191HD section contains the following fields:
- QW0191RS
- Contains the DDIS reason code, which uniquely describes the DRDA exception condition. This reason code should be used as the basis for further diagnosis of the DRDA exception condition.
- QW0191MN
- Contains the name of the DDF module (DRDS, DDIS, DTM) which requested the 0191 record.
- QW0191NO
- Contains the number of this IFCID 0191 record instance relative to the total number as specified in QW019190.
- QW0191T0
- Contains the total number of IFCID 0191 records that are required to capture all DDM objects and FDOCA data.
- QW0191FL
- Contains the length of the DDM object or FDOCA data that is retrieved from the data stream and that resulted in the DRDA Exception Condition.
- QW0191MI
- A unique 2-byte identifier, which identifies the processing point within the module that is defined in QW0191MN at which the 0191 request was made.
- QW0191TK
- A unique 12 character error token.
- QW0191C1
- The code point of the DDM command whose processing resulted in the request for the 0191 record.
- QW0191PA
- The DDIS parse state of the command.
- If this is 'P1', the remaining sections in the 0191 record represent reply messages and reply data objects that were received by the AR.
- If this is 'P2', the remaining sections in the 0191 record represent command data objects that are received from the AR.
- QW0191LN
- The location name of the AR (if QW0191PA is 'P2'), or the location name of the (if QW0191PA is 'P1').
- QW0191RN
- The total number of reply messages that are returned from the AS in response to the command. This is 0 if QW0191PA is 'P2'.
- QW0191ON
- The total number of OBJDSSs received from the AR.
- QW0191DN
- The total number of level 6b data streams received all of which have the same request correlator.
- QW0191ET
- Defines the Db2 response to a detected error.
- If QW0191ET is 0, then Db2 detected no syntactic or semantic errors in the data stream.
- If QW0191ET is 1, then the Db2 AR detected an error or exception condition, which resulted in formatting the SQLCA with an SQLCODE and SQLSTATE. In this case, QW0191SS contains the SQLSTATE.
- If QW0191ET is 2, then the Db2 detected an error or exception condition, which resulted in a DDM reply message that is being sent to the AR. The code point of the DDM reply message is contained in QW0191C2.
- QW0191PT
- If QW0191PA is 'P1', then QW0191PT contains the last five states and events of the top-level DDIS Reply Parser (DSNLZRPA). Similarly, if QW0191PA is 'P2', the QW0191PT contains the last five states and events of the top-level DDIS Request Parser (DSNLZSPA). These parsers are implemented as finite state machines, consequently, the (state,event) trace provides the last path through the parser.
How to read the QW0191CR section
If the value of QW0191PA is 'P1', then one QW0191CR section is included for every reply message and reply data object processed in response to the command. If the value of QW0191PA is 'P2', then one QW0191CR section is included for the command and one section for every command data object that was processed.
The QW0191CR section contains the following fields:
- QW0191PS
- Contains the parse state of the DDM object. If the value is 'DRDUCC', then this object was successfully parsed. If the value is 'DRDAFAIL', then the object parse failed.
- QW0191C3
- Contains the code point of the command, command data object, reply message, or reply data object.
- QW0191NM
- Contains the DSS number, carrying the level 6b object that is defined by QW0191C3.
- QW0191OF
- Contains the offset relative to the start of the 0191 record of QW01916B section. It contains a level 6b RQSDSS, OBJDSS, or RPYDSS containing the object that is defined by QW0191C3.
If QW0191PS is 'DRDUCC', then the value of QW0191FO is 0. If QW0191PS is 'DRDAFAIL', then the contents of QW0191FO are the offset relative to the 0191 record of the point at which the parse failed. This offset points within the data stream beginning at QW01916B. The cause of the parse failure depends on the object as defined by QW0191C3.
If the value of QW0191C3 is X'241A' (QRYDSC) or X'2413' (SQLDTARD), then the object contains a Late Descriptor. In this case, QW0191D1 contains the offset relative to the start of the 0191 record of a QW0191FD section, describing the progress of the parse of the Late Descriptor.
If the value of QW0191C3 is X'241B' (QRYDTA), or X'2413' (SQLDTARD), then the object contains data that are described by a late descriptor. In this case, QW0191D2 contains the offset relative to the start of the 0191 record of a QW0191RT section. This section contains a Db2 RDTA data structure, which correlates the DRDA types that are extracted from the Late Descriptor with the SQL type.
If the value of QW0191C3 is X'243E' (SQLOBKNAM), X'2414' (SQLSTT), X'2419' (SQLSTTVRB), X'2408' (SQLCARD), X'2411' (SQLDARD), X'241B' (QRYDTA) or X'2413' (SQLDTARD), then the object contains data that is described by an early or late FD:OCA descriptor, In this case, QW0191D3 contains the offset relative to the start of the 0191 record of a QW0191LT section. This section contains a Db2 data structure (FDLIDLST) which is a representation of the early or late descriptor and used to retrieve data from the data stream.
If the value of QW0191C3 is X'2412' (SQLDTA), then the object contains data that is described by an early or late FD:OCA descriptor. In this case, QW0191D4 contains the offset relative to the start of the 0191 record of a QW0191EA section. This section contains an internal Db2 structure that is provided for Db2 serviceability purpose only.
How to read the QW0191FD section
This section is present within the 0191 record only if the object is a Late Descriptor (SQLDTA or SQLDTARD). The section is found from offset QW0191D1 within the QW0191CR section.
- QW0191LD
- Contains the number of late environmental descriptors that are sent as part of the Late Descriptor.
- QW0191L1
- Contains the SQLDTAGRP LID extracted from the descriptor. If this is 0, the SQLDTAGRP was not processed.
- QW0191L2
- Contains the SQLCADTA LID extracted from the SQLDTARD descriptor. This is 0 if QW0191PA is 'P2'. It is also 0 if QW0191PA is 'P1' and the SQLCADTA array descriptor has not been processed.
- QW0191L3
- Contains the SQLDTA LID extracted from the SQLDTA descriptor. This is 0 if QW0191PA is 'P1'. It is also 0 if QW0191PA is 'P2' and the SQLDTA array descriptor has not been processed.
- QW0191L4
- Contains the SQLDTARD LID extracted from the SQLDTARD descriptor. This is 0 if QW0191PA is 'P2'. It is also 0 if QW0191PA is 'P1' and the SQLDTARD array descriptor has not been processed.
- QW0191GN
- Contains the total number of triplets (excluding Continue Previous Triplet) which reference DRDA types by LID, and are contained within the SQLDTAGRP. This is the number of input host variables that are being passed (QW0191PA is 'P2') or the number of columns in the answer set (QW0191PA is 'P1').
- QW0191F0
- Is on if the geometry of the SQLDTAGRP descriptor is correct. All LIDs specified by the constituent SQLDTAGRP triplets must define a valid DRDA type. If the SQLTAGRP specifies LIDs outside the range of X'02' through X'49' as late environmental descriptors, then the SQLTAGRP Meta Data Definition (MDD) (DRDA type X'D0') must precede the SQLTAGRP GDA and each Late Environmental Descriptor must be specified by its 7-byte MDD and 12-byte SDA.
- QW0191F1
- Is on if the geometry of the SQLCADTA row descriptor is correct. The SQLCADTA row must define
all occurrences of the SQLCAGRP followed by all elements of the SQLDTAGRP. If QW0191PA is 'P1', then
the DDM object is either a QRYDSC or the FDODSC scalar of the SQLDTARD. If QW0191PA is 'P2', then
the DDM object is the FDODSC scalar of the SQLDTA object.
If the SQLTAGRP specifies late environmental descriptors, then the SQLCADTA RLO must be preceded by the Meta Data Definition (MDD) for type X'E0'.
In addition to satisfying the SQLDTAGRP requirements, the SQLCADTA row descriptor must define the row as consisting of all elements of the (nullable) SQLCAGRP followed by all occurrences of elements of the SQLDTAGRP. The reference to SQLCAGRP and SQLDTAGRP is by LID. The reference to SQLCAGRP must be X'54', the reference to SQLDTAGRP must be identical to the LID, which appeared within the SQLDTAGRP descriptor.
- QW0191F2
- Is on if the geometry of the SQLDTA descriptor is correct. The SQLDTA descriptor must be such
that all late environmental descriptors precede the SQLTAGRP descriptor. The SQLDTA/SQLDTARD
geometry must be such that all late environmental descriptors precede the SQLDTAGRP descriptor.
Also, all LIDs contained within the constituent SQLDTAGRP triplets must have been defined previously
by some Late Environmental Descriptor, or default to the DRDA
type. In the latter case, the LID must be within the range X'02' through X'4F' and X 'C8' through
X'CF'. If any of these requirements are not satisfied, then the SQLDTA/SQLDTARD geometry is
incorrect.
In addition to satisfying the SQLDTAGRP requirements, the SQLDTA descriptor must define the row as all occurrences of the SQLDTAGRP. The reference to the SQLDTAGRP is via LID and this reference must be identical to the LID specified in the SQLDTAGRP descriptor. If the SQLTAGRP specifies late environmental descriptors, then the SQLDTA RLO must be preceded by the Meta Data Definition (MDD) for type X'E4'. If these requirements are not satisfied, the SQLDTA geometry is incorrect.
- QW0191F3
- Is on if the geometry of the SQLDTARD row is correct. Following the SQLCADTA row, the descriptor must define the SQLDTARD array as an (open) array such that each row is one occurrence of the SQLCADTA row. Reference to the SQLCADTA row is by LID, thus, the LID referenced within the SQLDTARD array must be identical to the LID, which appeared in the SQLCADTA row descriptor. If the SQLTAGRP specifies late environmental descriptors, then the SQLDTA RLO must be preceded by the Meta Data Definition (MDD) for type X'E4'. If any of these requirements are not satisfied, the SQLDTARD geometry is incorrect.
How to read the QW0191RT section
The QW0191RT section is included only if the object contains a late descriptor. Therefore, this section is included only if the object is a QRYDSC, SQLDTA, SQLDTARD, or OUTOVR. Both QRYDSC and SQLDTARD contain the late SQLDTARD descriptor, both of which map to a Db2 output SQLDA. The FDODSC scalar in the SQLDTA object contains the late SQLDTA descriptor, and this maps to a Db2 input SQLDA.
The OUTOVR descriptor contains override type information for the output SQLDA and only applies if LOB data formats are being overridden (either from LOB data value to LOB locator or vice versa).
This section includes the Db2 RDTA data structure that is built from the SQLDTAGRP. There is one RDTAENT entry for every LID processed as one of the elements of the SQLDTAGRP. The value of RDTANUM is identical to the number of SDA references contained in the SQLDTAGRP.
For each RDTAENT entry within this structure, the Db2 derived SQL type, subtype, CCSID, and length are recorded. The RDTA is the source of the input or output Db2 SQLDA. The DRDA type that is specified in the SQLDTAGRP triplets is used to find the 12-byte SDA for that DRDA type. If the SDA describes the data as character, then subtype is 1 for SBCS, 2 for Mixed and 3 for Graphic. Given the subtype of character data, the CCSID is derived from the CCSID overrides in effect at the time of descriptor processing.
- If Late Environmental Descriptor describes this LID, select CCSID from 12-byte SDA.
- If no late environmental descriptor, then choose command local CCSID as specified via TYPDEFOVR command/reply data object.
- If neither late environmental descriptor nor TYPDEFOVR, then choose CCSID as specified at ACCRDB/ACCRDBRM time.
RDTDA contains the address of the Db2 input/output SQLDA that was created for DRDS. The SQLDA is not traced. RDTALID contains an offset to the QW0191LT section. This points to the same section pointed to by QW0191D3. The contents of RDTAROW are 0. RDTAGLID is the SQLDTAGRP LID extracted from the SQLDTA or SQLDTARD descriptor and RDTARLID is the SQLCADTA row LID extracted from the SQLDTARD descriptor. These values are identical to the values of QW0191DG and QW0191CA, appearing within the QW0191FD section.
If the DRDA Exception Condition occurred during the data retrieval, the RDTA specifies the SQLDA that was presented to the RDS Resource Manager (input SQLDA) or the DRDS Resource Manager (output SQLDA).
How to read the QW0191LT section
This section includes the Db2 FDLIDLST data structure that is used to retrieve data that is described by an early or late descriptor. All early descriptors FDLIDLSTs are pre-built and are part of Db2. Local copies from the read only pre-built structures are made on a demand basis. The FDLIDLSTs that support late descriptors are dynamically created during descriptor processing.
There is one FDLIDLST for every FDOCA group (nullable or nonnullable) to be retrieved from the data stream. The Db2 unit of data transfer is an FDOCA row. Each row contains one or more groups, and the QW0191LT section captures the FDLIDLSTs required to retrieve all groups that constitute a row. When contained in a QW0191LT section, the contents of the FD_LIDENT_PTR fields are the offset relative to the data stream (QW01916B section) of the start of the data that is processed for that entry.
How to read the QW01916B section
The QW01916B section contains a level 6b header, defining an RQSDSS, RPYDSS, or OBJDSS data stream, followed by the data stream.