Field-definition (function code 8)

You need to provide the input and output that are required for a field-definition operation.

On entry

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

Begin program-specific programming interface information.The registers have the following information:
Table 1. Contents of the registers on entry
Register Contains
1 Address of the field procedure parameter list (FPPL)
2 through 12 Unknown values that must be restored on exit.
13 Address of the register save area.
14 Return address.
15 Address of entry point of exit routine.

The contents of all other registers, and of fields not listed in the following tables, are unpredictable.

The work area consists of 512 contiguous uninitialized bytes.

The FPIB has the following information:
Table 2. Contents of the FPIB on entry
Field Contains
FPBFCODE 8, the function code
FPBWKLN 512, the length of the work area
The CVD has the following information:
Table 3. Contents of the CVD on entry
Field Contains
FPVDTYPE One of these codes for the data type of the column value:
Code
Means
16
CHAR
20
VARCHAR
24
GRAPHIC
28
VARGRAPHIC
FPVDVLEN The length attribute of the column

The FPVDVALE field is omitted. The FVD provided is 4 bytes long. The FPPVL field has the information:

Table 4. Contents of the FPPVL on entry
Field Contains
FPPVLEN The length, in bytes, of the area containing the parameter value list. The minimum value is 254, even if there are no parameters.
FPPVCNT The number of value descriptors that follow; zero if there are no parameters.
FPPVVDS A contiguous set of value descriptors, one for each parameter in the parameter value list, each preceded by a 4-byte length field.

On exit

The registers must have the following information:
Table 5. Contents of the registers on exit
Register Contains
2 through 12 The values that they contained on entry.
15 The integer zero if the column described in the CVD is valid for the field procedure; otherwise the value must not be zero.

The following fields must be set as shown; all other fields must remain as on entry.

The FPIB must have the following information:
Table 6. Contents of the FPIB on exit
Field Contains
FPBWKLN The length, in bytes, of the work area to be provided to the field-encoding and field-decoding operations; 0 if no work area is required.
FPBRTNC An optional 2-byte character return code, defined by the field procedure; blanks if no return code is given.
FPBRSNC An optional 4-byte character reason code, defined by the field procedure; blanks if no reason code is given.
FPBTOKP Optionally, the address of a 40-byte error message residing in the work area or in the field procedure's static area; zeros if no message is given.

Errors signalled by a field procedure result in SQLCODE -681 (SQLSTATE '23507'), which is set in the SQL communication area (SQLCA). The contents of FPBRTNC and FPBRSNC, and the error message pointed to by FPBTOKP, are also placed into the tokens, in SQLCA, as field SQLERRMT. The meaning of the error message is determined by the field procedure.

The FVD must have the following information:
Table 7. Contents of the FVD on exit
Field Contains
FPVDTYPE The numeric code for the data type of the field value. Any of the data types listed in Table 1 is valid.
FPVDVLEN The length of the field value.

Field FPVDVALE must not be set; the length of the FVD is 4 bytes only.

The FPPVL can be redefined to suit the field procedure, and returned as the modified FPPVL, subject to the following restrictions:
  • The field procedure must not increase the length of the FPPVL.
  • FPPVLEN must contain the actual length of the modified FPPVL, or 0 if no parameter list is returned.
The modified FPPVL is recorded in the catalog table SYSIBM.SYSFIELDS, and is passed again 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 value descriptors.
End program-specific programming interface information.