8.11.4 UOC interface

Organization of this subsection
(1) Structure and contents of the UOC interface area
(2) Format of data values

(1) Structure and contents of the UOC interface area

An interface area is used to exchange information between pdrorg and a UOC. It is called a UOC interface area.

pdrorg always allocates this area except for the update buffer. The UOC receives the address of this area in the first argument of a call function to reference and update information.

Figure 8-28 Structure of the UOC interface area (1/2) and Figure 8-29 Structure of the UOC interface area (2/2) show the structure of the UOC interface area.

Figure 8-28 Structure of the UOC interface area (1/2)

[Figure]

Note 1
Square brackets [ ] enclose the numeric value for HiRDB in the 64-bit mode.
Note 2
For details about the contents of the UOC interface are, see Table 8-32 Contents of the UOC interface area; for details about the contents of the column definition information address list, see Table 8-33 Contents of column definition information address list; for details about the contents of the column definition information area, see Table 8-34 Contents of column definition information area; for details about the contents of the abstract data-type reverse-creation parameter information area, see Table 8-35 Contents of the abstract data type reverse-creation parameter information area.

Figure 8-29 Structure of the UOC interface area (2/2)

[Figure]
Note 1
Square brackets [ ] enclose the numeric value for a HiRDB in the 64-bit mode.
Note 2
For details about the contents of the data address list, see Table 8-38 Contents of data address list; for details about the contents of the post-update data address list, see Table 8-39 Contents of post-update data address list.

Table 8-32 Contents of the UOC interface area

Relative locationField nameLength (bytes)AttributeProgram setting the valueDescription
32643264
00Eye-catcher88charpdrorgInterface area ('*UOCINF*')
88Running program44intpdrorgProgram that has control:
0: pdrorg
1: UOC
1212Call type44intpdrorgType of processing request to the UOC:
o: Start request
e: Data update request
c: Termination request
t: Stop request
1616Length of authorization identifier22shortpdrorgLength of the target table's owner name
1818Authorization identifier3030charpdrorgTarget table's owner name
4848Length of table identifier22shortpdrorgLength of the target table name
5050Table identifier3030charpdrorgName of the target table
8080Row length48longpdrorgIf the data storage method is Y, this field sets the row length.
8488Address of the data address list48void*pdrorgStart address of the data address list that contains the address of the data retrieved by pdrorg
8896Information used by the system48longpdrorgInformation used by the system (UOC may not use this information)
92104Address of the post-update data address list48void*UOCIf the data updated by the UOC is to be returned to pdrorg, this field sets the start address of the post-update data address list that contains the address of the data created within the UOC. If the data is not to be updated, this field sets 0.
96112Address of user parameter48void*pdrorgAddress of the character string that was specified in the param operand of the unlduoc statement (the character string ends with /0). If the param operand was omitted, the null value is set.
100120Address of the column definition information address list48void*pdrorgStart address of the column definition information address list for the target table
104128Reserved11charpdrorgReserved area (UOC may not use this information)
105129Table attribute11charpdrorgAttribute of the target table:
F: FIX table
blank: Non-FIX table
106130Number of columns22shortpdrorgNumber of columns in the target table
108132Storage flag11charUOCStorage flag:
Y: Stores data in unload data file.
N: Does not store data in unload data file.
If pdrorg is used to create an unload data file, make sure that this flag is set (if the UOC is used to create a UOC data file, there is no need to set this flag).
109133Data storage method11charpdrorgFor a FIX table, this field sets the value of the fixrow operand specified in the unlduoc statement (when fixrow is omitted, the field sets N).
Y: Passes data in the order the columns were defined (consecutively).
N: Passes the start address of the data that has been corrected according to the boundary of data type.
110134Reserved1010charpdrorgReserved area (UOC may not use this information)
120144Return code44intUOCReturn code.
The UOC that has received control from pdrorg must set a return code for each call according to the following guidelines:
0:
Set this code if the processing for each request was executed normally.
4:
Set this code if you want to display a message even when processing was normal, such as for debugging. The meaning is the same as for 0. When the return code is set to 4, the message is displayed up to three times. Note that once the message has been displayed three times, the utility ignores return code 4, if set again, in which case there is no more message display.
8:
Set this code if an error occurs during UOC processing.
If the set return code is none of the above, pdrorg cancels processing. When the return code is 4 or 8, pdrorg outputs the contents of the message-embedded area to the standard output and message log. Make sure that the message consists of no more than 131 bytes of a character string that ends with \0. pdrorg does not output any message that begins with \0.
124148Message-embedded area132132charpdrorg
UOC
Storage area for the message that is output to the standard output and message log (pdrorg places \0 at the beginning of the message before passing it).
Legend:
32: Shows the relative location or length for a HiRDB in the 32-bit mode.
64: Shows the relative location or length for a HiRDB in the 64-bit mode.
Note 1
For the start address, pdrorg guarantees a 4-byte boundary for a HiRDB in the 32-bit mode and an 8-byte boundary for a HiRDB in the 64-bit mode.
Note 2
The following table describes whether or not each field can be referenced and updated:
Field nameCall type
Start requestData update requestTermination requestStop request
Eye-catcherRRRR
Running programRRRR
Call typeRRRR
Length of authorization identifierRRRR
Authorization identifierRRRR
Length of table identifierRRRR
Table identifierRRRR
Row lengthNRNN
Address of the data address listNRNN
Address of the post-update data address listNYNN
Address of user parameterRRRR
Address of the column definition information address listRRRR
Table attributeRRRR
Number of columnsRRRR
Data storage methodNYNN
Message-embedded areaYYYY
Return codeYYYY
Storage flagNYNN
Legend:
Y: Value can be set.
R: Value can be referenced.
N: Value cannot be referenced (value is not guaranteed).

Table 8-33 Contents of column definition information address list

Relative locationField nameLength (bytes)AttributeProgram setting the valueDescription
32643264
00Definition information address for column ID148void*pdrorgSets the address of the column definition information for column ID1.
48Definition information address for column ID248void*pdrorgSets the address of the column definition information for column ID2.
(n - 1) [Figure] 4(n - 1) [Figure] 8Definition information address for column IDn48void*pdrorgSets the address of the column definition information for column IDn.
Legend:
32: Shows the relative location or length for a HiRDB in the 32-bit mode.
64: Shows the relative location or length for a HiRDB in the 64-bit mode.
Note 1
For the start address, pdrorg guarantees a 4-byte boundary for a HiRDB in the 32-bit mode and an 8-byte boundary for a HiRDB in the 64-bit mode.
Note 2
The contents of the column definition information address list are passed consecutively in the order of the column definitions.

Table 8-34 Contents of column definition information area

Relative locationField nameLength (bytes)AttributeProgram setting the valueDescription
32643264
00Length of column name22shortpdrorgSets the length of the column name.
22Column name3030charpdrorgSets the column name.
3232Column ID22shortpdrorgSets the column ID.
3434Reserved 111------
3535Data type11unsigned charpdrorgSets the data type of the column. For details about the data code and data value boundary for each data type, see Table 8-37 Data code and data value boundary for each data type.
3636Defined length22shortpdrorgSets the defined length of the column. For details about the length and contents of the definition length area for columns, see Table 8-37 Data code and data value boundary for each data type.
3838Repetition count22shortpdrorgSets the repetition count for the column.
4040BLOB or BINARY length88int[2]pdrorgThis field is set if the column's data type is large object data or BINARY. The first 4 bytes are set to 0 and the remaining 4 bytes contain the defined length of large object data type in bytes.
4848Number of parameter22shortpdrorgFor an abstract data type, this field sets the number of functions in the corresponding unld_func statements (number of parameters). A value of 0 is set in the following cases:
  • The column's data type is not an abstract data type.
  • No unld_func statement is specified for the abstract data type.
5050Reserved 266charpdrorgReserved area
5656Extended address48void*pdrorgSets the start address of the abstract data type reverse-creation parameter information. A value of 0 is set if the number of parameters is 0.
6064Reserved 36464charpdrorgReserved area
Legend:
32: Shows the relative location or length for a HiRDB in the 32-bit mode.
64: Shows the relative location or length for a HiRDB in the 64-bit mode.
--: Not applicable.
Note
For the start address, pdrorg guarantees a 4-byte boundary for a HiRDB in the 32-bit mode and an 8-byte boundary for a HiRDB in the 64-bit mode.

Table 8-35 Contents of the abstract data type reverse-creation parameter information area

Relative locationField nameLength (bytes)AttributeProgram setting the valueDescription
0Parameter number2shortpdrorgParameter number (beginning with 1)
2Data type1unsigned charpdrorgSets the data type of the parameter. For details about the data code and data value boundary for each data type, see Table 8-37 Data code and data value boundary for each data type.
3Reserved 13charpdrorgReserved area
6Defined length2shortpdrorgSets the defined length of the parameter. For details about the length and contents of the definition length area for columns, see Table 8-36 Length and contents of the definition length area for columns.
8BLOB or BINARY length8int[2]pdrorgIf the parameter's data type is large object data or BINARY, this field sets the BLOB length. The first 4 bytes are set to 0 and the remaining 4 bytes contain the defined length of large object data type in bytes.
16Reserved 2112charpdrorgReserved area
Note 1
For the start address, pdrorg guarantees a 4-byte boundary for a HiRDB in the 32-bit mode and an 8-byte boundary for a HiRDB in the 64-bit mode.
Note 2
The contents of the abstract data type reverse-creation parameter information area are passed consecutively in the order of functions (parameters) specified in the unld_func statement.

Table 8-36 Length and contents of the definition length area for columns

Data typeArea sizeDescription
DECIMAL, LARGE DECIMAL,
INTERVAL YEAR TO DAY, and
INTERVAL HOUR TO SECOND
Leading 1 bytePrecision specified in the definition
Trailing 1 byteUnit specified in the definition
TIMESTAMP(p)2 bytes7 + [Figure]p/2[Figure]
BLOB, abstract data type, and BINARY2 bytesValue is not guaranteed
Other2 bytesDefined length

Table 8-37 Data code and data value boundary for each data type

Data typeData code (hexadecimal)Boundary (in bytes)
NOT NULL constraint omittedNOT NULL constraint specified
MVARCHARA1A02
MCHARA5A4--
NVARCHARB1B02
NCHARB5B4--
VARCHARC1C02
CHARC5C4--
FLOATE1E08
SMALLFLTE3E24
DECIMALE5E4--
INTEGERF1F04
SMALLINTF5F42
INTERVAL YEAR TO DAY6564--
DATE7170--
TIME7978--
INTERVAL HOUR TO SECOND6F6E--
TIMESTAMP7D7C--
BINARY91904
BLOB93924
Abstract data typeAddress list of abstract data type parameter83824 for a HiRDB in the 32-bit mode and 8 for a HiRDB in the 64-bit mode
Data for parameterDepends on the data type of the parameter
Legend:
--: Address boundary is not adjusted.

Table 8-38 Contents of data address list

Relative locationField nameLength (bytes)AttributeProgram setting the valueDescription
32643264
00Data storage address for column ID148void*pdrorgSets the address of the data for column ID1.
48Data storage address for column ID248void*pdrorgSets the address of the data for column ID2.
(n - 1) [Figure] 4(n - 1) [Figure] 8Data storage address for column IDn48void*pdrorgSets the address of the data for column IDn.
Legend:
32: Shows the relative location or length for a HiRDB in the 32-bit mode.
64: Shows the relative location or length for a HiRDB in the 64-bit mode.
Note 1
For the start address, pdrorg guarantees a 4-byte boundary for a HiRDB in the 32-bit mode and an 8-byte boundary for a HiRDB in the 64-bit mode.
Note 2
The contents of the data address list are passed consecutively in the order defined.
Note 3
If the column value is null, 0 is set.
Note 4
In the case of a FIX table, if the data storage method is Y in the UOC interface area, the data buffer stores a contiguous area equivalent to the row length of the UOC information beginning at the address indicated by the data storage address for column ID1. Data is stored in the order of column IDs.
Note 5
If the data storage method is N in the UOC interface area, the start address of the data is adjusted at the specified boundary for each data type. Data is not consecutive for each column.
Note 6
If the number of parameters in the column definition information area is 0, a value of 0 is set.

Table 8-39 Contents of post-update data address list

Relative locationField nameLength (bytes)AttributeProgram setting the valueDescription
32643264
00Data storage address for column ID148void*UOCSets the address of the data for column ID1.
48Data storage address for column ID248void*UOCSets the address of the data for column ID2.
(n - 1) [Figure] 4(n - 1) [Figure] 8Data storage address for column IDn48void*UOCSets the address of the data for column IDn.
Legend:
32: Shows the relative location or length for a HiRDB in the 32-bit mode.
64: Shows the relative location or length for a HiRDB in the 64-bit mode.
Note 1
For the start address, guarantee a 4-byte boundary for a HiRDB in the 32-bit mode and a 8-byte boundary for a HiRDB in the 64-bit mode.
Note 2
After data has been updated, set the data address list in consecutive areas in the order of column definitions.
Note 3
You may set the data storage address contained in the data address list as the data address value. Make sure that the data value is not updated.
Note 4
There is no need to guarantee the boundary for the data address.
Note 5
Set 0 if you are changing to null the value of a column for which the NOT NULL constraint was not specified in the column definition. The following table describes whether or not data can be changed, depending on the NOT NULL constraint specification.
Column attributeData before updatingData after updating
Non-null valueNull value
NOT NULL constraint omittedNull valueYY
Non-null valueYY
NOT NULL constraint specifiedNon-null valueYN
Legend:
Y: Can be changed.
N: Cannot be changed.
Note 6
In the case of a FIX table for which reserved columns are defined, updating the values of the reserved columns has no effect on the unload files. If you want to store data in the reserved columns and then unload the table, use a UOC to output the files. For details about using a UOC to output files, see 8.9.4 unload statement (specification of unload data file).

(2) Format of data values

This section explains the data values of each data type.

(a) INTEGER or SMALLINT
(b) FLOAT or SMALLFLT
(c) DECIMAL

[Figure]

(d) CHAR, MCHAR, VARCHAR, or MVARCHAR

The following figure shows the format when character code conversion is not performed or when character code conversion that does not affect the data lengths is performed.

[Figure]

(e) CHAR or VARCHAR

The following figure shows the format when data lengths are changed by character code conversion.

[Figure]

(f) NCHAR or NVARCHAR

[Figure]

(g) DATE

[Figure]

(h) TIME

[Figure]

(i) INTERVAL YEAR TO DAY

[Figure]

(j) INTERVAL HOUR TO SECOND

[Figure]

(k) TIMESTAMP

[Figure]

(l) BINARY

[Figure]

(m) BLOB

[Figure]

(n) Abstract data type

For an abstract data type, the address list of an abstract data-type parameter is stored. Figure 8-30 Structure of the address list for an abstract data-type parameter shows the structure of the address list for an abstract data-type parameter, and Table 8-40 Contents of the address list for an abstract data-type parameter describes the contents of the address list for an abstract data-type parameter.

Figure 8-30 Structure of the address list for an abstract data-type parameter

[Figure]

Note
Square brackets [ ] enclose the numeric value for HiRDB in 64-bit mode.

Table 8-40 Contents of the address list for an abstract data-type parameter

Relative locationField nameLength (bytes)AttributeProgram setting the valueDescription
32643264
00Data address for parameter 148void*pdrorgSets the address of the data for parameter 1.
48Data address for parameter 248void*pdrorgSets the address of the data for parameter 2.
(n - 1) [Figure] 4(n - 1) [Figure] 8Data address for parameter n48void*pdrorgSets the address of the data for parameter n.
Legend:
32: Shows the relative location or length for a HiRDB in the 32-bit mode.
64: Shows the relative location or length for a HiRDB in the 64-bit mode.
Note 1
For the start address, pdrorg guarantees a 4-byte boundary for a HiRDB in the 32-bit mode and an 8-byte boundary for a HiRDB in the 64-bit mode.
Note 2
The start address of the parameter data is adjusted by the boundary set for each data type.
Note 3
The contents of the address list for an abstract data-type parameter are passed consecutively in the order of functions (parameters) specified in the unld_func statement.
(o) Repetition columns

[Figure]