Dim question about QDBRTVFD

[Nick Ballinger]

Hi, I have a utility which calls the IBM API QDBRTVFD. It has been working fine, but recently we introduced a file with a VARCHAR key field. So has anyone come across the scenario where a key field data type causes a "Receiver value too small to hold result" error when the data type of the field is a VARCHAR.

According to the manual an 8004 should be returned rather than a 0004, but I see a negative number -2764.

I thought it was down to the definition of the fields in the data structure, but they are as IBM advise.

Anyone seen this or know how to circumvent the issue ?

Any information will be very gratefully received.

Cheers

Nick Ballinger

[CRPence]

On 29-Jan-2014 03:13 -0800, Nick Ballinger wrote:
> I have a utility which calls the IBM API QDBRTVFD. It has been
> working fine, but recently we introduced a file with a VARCHAR key
> field. So has anyone come across the scenario where a key field data
> type causes a "Receiver value too small to hold result" error when
> the data type of the field is a VARCHAR.
>
> According to the manual an 8004 should be returned rather than a
> 0004, but I see a negative number -2764.

Apparently this is a reference to the Data_Type BIN(2) value in the
Key Field Description Array (Qdb_Qdbwhkey) as requested from the
FILD0300 Format (Key Field Information)? Note that VARCHAR is 0x8004,
not 0d8004; i.e. the value of the BINARY(2) in hexadecimal string
notation is X'8004' as shown in the docs. Thus having been declared as
a signed small\2-byte integer, the value 0x8004 correctly would be shown
to have a negative value, though more accurately, about 30000 larger [on
a negative scale].

Thus by whatever means was utilized to review the value [e.g. an EVAL
in debugL] may have done much like an RPG truncate of significant
digits, from which an incorrect inference was made about the actual
value; e.g. if using a debugger for a language that /supports/ that odd
truncation, be sure to review the hexadecimal content of the variable
[EVAL varName:X instead of EVAL varName] rather than the edited
as-character presentation mode, or /correct/ the declarative to allow
for the additional digit.

> I thought it was down to the definition of the fields in the data
> structure, but they are as IBM advise.
>
> Anyone seen this or know how to circumvent the issue ?
>
> Any information will be very gratefully received.

If the above does not describe the difficulty encountered, then...

Include the DDL for the CREATE TABLE or DDS for the CRTPF, and a
DMPOBJ of the file created with that source. Preferably a minimally
specified file, i.e. just one or few fields, that will re-create the
error encountered by your utility. Also include what invocation is made
of the API. I will gladly review the scenario.

--
Regards, Chuck

[Nick Ballinger]

Thanks for the information Chuck. I will look into this further and if I cannot resolve it, I will post the information requested. I would rather figure it out myself, but there are time constraints.

Sorry for the poor explanation of the issue, but the situation is as you have inferred.

Thanks again.

Nick Ballinger

[Nick Ballinger]

Hi Chuck, below is further information as requested. I have done some further testing.

The problem occurs when trying to examine the DS item see below. In DEBUG the item is indeed hex 8004, but trying to do the comparison following, causes the receiver overflow issue.

c if Qdb_Qdbwhkey.DataType = x'8004' VarChar

Here is the DS
Qdb_Qdbwhkey DS 64 qualified
D based(Qdb_Qdbwhkey@)
D IntName 1 10a
D ExtName 11 20a
D DataType 21 22b 0
D FieldLen 23 24b 0
D Digits 25 26b 0
D Decimals 27 28b 0
D Attributes1 29 29a
D AltNameLen 30 31b 0
D AltName 32 61a
D Attributes2 63 63a

Here is the code which gets the details
* Call API - FILD0300. To obtain key fields in user space. Nonkeyed file will cause error!
C CALLP GetFileDetails(
C QHeader
C :16776704
C :outFileName
C :'FILD0300'
C :inFileName
C :' '
C :'0'
C :'*LCL'
C :'*EXT'
C :QUSEC)

* Set the return parameter - the number of record formats
C eval total = QHeader.FmtCount

* Loop through each record format
C for i = 1 TO QHeader.FmtCount
* - calculate the offset to the record format
C eval offset = %len(QHeader)
C + (i-1) * %len(Qdb_Qdbwhrec)
* - set the record format data structure
C eval Qdb_Qdbwhrec@ = OffsetPtr(QHeader@
C :offset)

After some code to set up structures to move the data into (for comparison against another version of the same file) we come to the line that fails - repeated from above
c if Qdb_Qdbwhkey.DataType = x'8004' c

Obviously the Key Information Header DS and the Record Key Information Array are as described in the IBM literature as well and everything works fine until we hit a file with an 80 byte VARLEN key field (obviously 82 bytes total).

A UNIQUE
A R RDSBRMR
A TEXT('BRM Relationship')
A BRMID 80A VARLEN
A PTKY R REFFLD(PTKY)
A PTTP R REFFLD(PTTP)
A FLDZ R REFFLD(FLDZ)
A FLID R REFFLD(FLID SYSREF)
A NAME 200A
A TYPE 5A
A FLDF R REFFLD(FLDF)
A AUDTDJ R REFFLD(AUDT)
A AUTMDJ R REFFLD(AUTM)
A AUPFDJ R REFFLD(AUPF)
A ZFFL R REFFLD(ZFFL)
*
*****************************************************
* Key Fields
*****************************************************
A K BRMID

Below shows the references resolved for the referenced fields.
2 PTKY 3 A 83 85 Paint Type Key
3 PTTP 1 A 86 86 Paint Type
4 FLDZ 15 0 P 87 94 Field Unique ID
5 FLID 4 A 95 98 Unique Field ID
6 NAME 200 A 99 298
7 TYPE 5 A 299 303
8 FLDF 1 A 304 304 Field Derivn Freq.
9 AUDTDJ 8 0 P 305 309 Audit Date
10 AUTMDJ 6 0 P 310 313 Audit Time
11 AUPFDJ 10 A 314 323 Audit Profile
12 ZFFL 1 A 324 324 Fixed Fld

I cannot see this issue is caused by our utility, which access the API and returns what is expected, but I would appreciate any ideas as to how we can sort this out, as there will be other varying length key fields which would cause us issues.

Many thanks, in advance for any help or observations.

Nick Ballinger

[CRPence]

On 30-Jan-2014 03:43 -0800, Nick Ballinger wrote:
> On Thursday, 30 January 2014 09:18:11 UTC, Nick Ballinger wrote:
>

> <<SNIP>> I have done some further testing.

>
> The problem occurs when trying to examine the DS item see below. In
> DEBUG the item is indeed hex 8004, but trying to do the comparison
> following, causes the receiver overflow issue.
>
> c if Qdb_Qdbwhkey.DataType = x'8004'
>

> Here is the DS
> Qdb_Qdbwhkey DS 64 qualified
> D based(Qdb_Qdbwhkey@)
> D IntName 1 10a
> D ExtName 11 20a
> D DataType 21 22b 0
> D FieldLen 23 24b 0
> D Digits 25 26b 0
> D Decimals 27 28b 0
> D Attributes1 29 29a
> D AltNameLen 30 31b 0
> D AltName 32 61a
> D Attributes2 63 63a
>

> Here is the code <<SNIP>>>

>
> I cannot see this issue is caused by our utility, which access the
> API and returns what is expected, but I would appreciate any ideas as
> to how we can sort this out, as there will be other varying length
> key fields which would cause us issues.
>
> Many thanks, in advance for any help or observations.

That line of code would fail whenever the value for
Qdb_Qdbwhkey.DataType is any value greater than 9999 or less than -9999.
Thus that line of code will fail when the value of
Qdb_Qdbwhkey.DataType = x'8004', no matter how ridiculous that might
seem, because the value x'8004' is not supported for *that particular*
declaration used for the BINARY(2) referenced in the API documentation.

Solving that issue can be done by simply changing the Internal Data
Type specification on the DataType variable declared in the DS, to use
instead, one of [if using A (or a Blank), then also remove the Decimal
Positions specification] the following:
• U - unsigned integer field
• I - signed integer field
• A - character field

Of the other B="a fixed binary field" representations, i.e. for the
other variables with 2-bytes of Internal Data Type of B, only the
FieldLen would require a similar change because that value can also
exceed 9999.

So without actually looking at the code {thus <snip>ped above} beyond
the above declarative and that specific failing line of code [i.e. the
IF OpCode for a comparison of the variable to the hex literal], the
problem for that line of code is a usage problem, albeit heavily
influenced\exacerbated by a variety of issues:

First, the documentation for the Data_Type under the Key Field
Description Array (Qdb_Qdbwhkey) is somewhat poor; i.e. the declarative
descriptive as documented for the Data_Type should have been shown
identical to the declarative of Qddfftyp as CHAR(2) under the Field
Header (Qdb_Qddffld) instead of being shown as BINARY(2).

Second, although BINARY(2) means the same as an SQL SMALLINT, the RPG
has a heritage, for which a two-byte binary integer value is limited to
four digits of precision. Thus the exception msg MCH1210 overflow
condition effecting a 103 error condition [aka msg RNX0103] leading to
the inquiry RNQ0103, whenever the integer value represented by the
type=B requires more than four digits. Using the data type designation
of I tells the RPG that a true INTEGER type is required; i.e. the legacy
restrictions of the Fixed-Binary data type are not an issue.

Third, the debugger EVAL for its character presentation of that type
of numeric values, honors the four-digit presentation rules, but warns
not, that the presented value is not really what is there; the onus is
on the user to review the hexadecimal presentation of the full variable
storage using the :X suffix\extension for the EVAL request.

Fourth, although the API documentation includes some "common errors"
and some effective "best practices" which should have informed *against*
that particular declarative, the first problem with the "poor"
documentation could have eliminated any issue; i.e. the data-type was
never intended to be declared nor utilized as a numeric, thus it should
have been consistently shown declared as clearly a non-numeric type...
which although IMO just as unclear, the CHARacter data type has
sufficiently served that purpose [the whole issue with
BINARY(nbrOfBytes) being used _incorrectly_ where INT(nbrOfBytes) was
intended, should have been dealt with before ever any API docs were
published]. Besides that, my inability to find the doc reference that
warns of the use of RPGLE\RPG B data type was fruitless; difficult for
someone to be aware if not made extremely conspicuous.

--
Regards, Chuck

[Nick Ballinger]

Many thanks Chuck. An excellent explanation and I have now sorted the problem. Thanks very much for taking the time to look at this and respond, it has helped me a great deal and saved me something which I have too little of always - time.

I knew there were some shortcomings of using binary fields, but the old memory cells are not on full charge any more. The fact that it works fine for most returned values also muddies the waters.

Anyhow - I am most grateful for, and most appreciative of, your help.

Cheers

Nick.