Field-definition (function code 8)

The input provided to the field-definition operation, and the output required, are as follows:

• Parameter 1
Input - A small (2 byte) integer that describes the function to be performed (8 - field-definition).
• Parameter 2
Input/Output - A structure that defines the field procedure parameter value list (FPPVL). This is an auto-extendable space. The minimum length of this structure is 8 bytes. The maximum returned length of this structure is 32K.
• Parameter 3
Input - The structure sqlfpParameterDescription_T containing the decoded data attributes.
• Parameter 4
Not used.
• Parameter 5
Output - The structure sqlfpParameterDescription_T containing the encoded data attributes. The output sqlfpParameterDescription_T must be valid with the appropriate CCSID, length, precision, and scale fields set.
• Parameter 6
Not used.
• Parameter 7
Input/Output - The SQLSTATE (character(5)).
• Parameter 8
Input/Output - The message text area (varchar(1000)).
• Parameter 9
Input - Reserved.

Errors returned by a field procedure result in SQLCODE -681 (SQLSTATE '23507'), which is set in the SQL communication area (SQLCA) and the DB2_RETURNED_SQLCODE and RETURNED_SQLSTATE condition area item of the SQL diagnostics area. The contents of Parameter 7 and 8 are placed into the tokens, in SQLCA, as field SQLERRMT and in the SQL Diagnostic area condition area item MESSAGE_TEXT. The meaning of the error message is determined by the field procedure.

Invalid data in Parameter 5, sqlfpParameterDescription_T, or an invalid length in Parameter 2 results in SQLCODE -685 (SQLSTATE '58002'). If the database manager is unable to invoke the field procedure then SQLCODE -682 (SQLSTATE '57010') is returned.

The FPPVL can be redefined to suit the field procedure, and returned as the modified FPPVL, subject to the following restriction:
  • sqlfpOptParmValueListLength must contain the actual length of the modified FPPVL. If no parameter list is returned, then sqlfpOptParmValueListLength must be set to 8.
The modified FPPVL is recorded in the catalog table QSYS2.SYSFIELDS, and is passed to the field procedure during field-encoding and field-decoding. The modified FPPVL need not have the format of a field procedure parameter list, and it need not describe constants by optional parameter value descriptors.

The nullability attribute of the column may not be changed.

If the encoded data attribute is a character, graphic or XML type, the CCSID value must be set to a valid CCSID for the data type.

If the column has a non-null default value, the encoded default value must not exceed the length allowed for the column's default value.