Information is input and output between the database load utility and the UOC via the interface area. The database load utility allocates this area. The UOC receives the address of this area in the first argument of the function, and references and updates the area.
Figure 5-30 Structure of UOC interface area (32-bit mode) and Figure 5-31 Structure of UOC interface area (64-bit mode) show the structure of the UOC interface area. Table 5-51 Contents of UOC interface area describes the contents of the UOC interface area.
Figure 5-30 Structure of UOC interface area (32-bit mode)
![[Figure]](figure/zu050440.gif)
Figure 5-31 Structure of UOC interface area (64-bit mode)
![[Figure]](figure/zu050441.gif)
Table 5-51 Contents of UOC interface area
Relative position | Field name | Length (Byte) | Attribute | Value setter | Contents |
---|
32 | 64 | 32 | 64 |
---|
0 | 0 | Eye catcher | 8 | 8 | char | pdload | Interface area (*UOCINF*). |
8 | 8 | Executing program | 4 | 4 | long | pdload | Program receiving control: 0: pdload 1: UOC |
12 | 12 | Call type | 4 | 4 | long | pdload | Type of processing request to UOC:
- o: Start request
- Requests processing startup preparations (prepares to start processing, such as by opening the input data file).
- e: Edit request#1
- Requests editing of row data. For method (1), one row of data input by pdload is set in the input buffer pointed to by the input buffer address. For method (2), the UOC reads the input data file. In both methods, the results of editing the data are then set in the edit buffer pointed to by the edit buffer address. This call is repeated until all data has been processed or the return code from the UOC is a value other than 0 or 4.
- c: End request
- Requests termination of processing. Such termination processing as closing the input data file is performed. For method (1), the request is issued when there is no more data to be input by pdload. For method (2), the request is issued when return code 16 is received from the UOC.
- t: Termination request
- Requests forcible termination of processing. This call is used instead of an end request when an error occurs on the pdload side or when a return code other than 0, 4, or 16 is received from the UOC.
Once a start request is issued, an end request is issued when processing terminates normally, and a termination request is issued when processing terminates abnormally. The UOC is not called once an end request or termination request is issued. |
16 | 16 | Length of authorization identifier | 2 | 2 | short | pdload | Length of name of table owner. |
18 | 18 | Authorization identifier | 30 | 30 | char | pdload | Name of table owner. |
48 | 48 | Length of table identifier | 2 | 2 | short | pdload | Length of table name. |
50 | 50 | Table identifier | 30 | 30 | char | pdload | Table name. |
80 | 80 | Length of input data#2 | 4 | 8 | long | pdload | - For a binary-format or extended-DAT-format input data file, this is set to the length of the data (full length) set in the input buffer.#3
- This item is ignored.
|
84 | 88 | Address of input buffer | 4 | 8 | void* | pdload | - Set to the address of the buffer that stores the data input by pdload.
- This item is ignored.
|
88 | 96 | Length of edit data#2, #5 | 4 | 8 | long | UOC | For a binary-format or extended-DAT-format input data file, this is set to the length of the data (full length) set in the edit buffer.#4
- Set to -1 if no data is stored.
|
92 | 104 | Address of edit buffer | 4 | 8 | void* | UOC | Address of buffer that stores the data edited by the UOC. |
96 | 112 | Address of user parameters | 4 | 8 | void* | pdload | Set to the address of the character string specified in the param operand of the srcuoc statement. If the param operand is omitted, it is set to NULL. |
100 | 120 | Information used by system | 4 | 8 | void* | pdload | Information used by the system (must not be used by the UOC). |
104 | 128 | Reserved | 16 | 16 | char | pdload | Reserved area (must not be used by the UOC). |
120 | 144 | Return code | 4 | 4 | long | UOC | Return code that notifies the calling program of the results of UOC processing. The UOC that received control from pdload must return one of the codes explained as follows. Because this area is cleared (set to -1) each time pdload calls the UOC, the UOC must set this area after every call.
- 0:
- Start or end request executed normally, or one row of data has been made available in the edit buffer for an edit request.
- 4:
- Message output processing is to be performed (even if processing terminated normally); the details are the same as for the 0 return code.
- When the return code is 4, the message is output up to three times. Once the message has been output three times, the return code is ignored and the message is no longer output, even if the return code remains as 4.
- 8:
- Input processing is to be committed up to that point but further processing is to be discontinued because an error occurred during the UOC processing. However, if an internal error occurred on the HiRDB side, input processing is rolled back. The message output to the message log should be checked to determine whether input processing was committed or rolled back.
- 16:
- The UOC has read the input data file, and pdload is to be notified that there is no more data to be processed. When the input data file is read by pdload, this return code can also be set when no more data is to be received after this time. When pdload receives this return code, it performs end processing.
- 20:
- An error occurred during UOC processing. This return code is set when input processing is rolled back up to the time of the error and processing is discontinued.
- If a return code other than 0 or 16 is set, the contents of the message embedded area are output to the standard output and the message log. The message should be a character string of up to 131 bytes terminating with \0.
|
124 | 148 | Message embedded area | 132 | 132 | char | UOC | Storage area for message output to standard output and log. |
32: Relative position and length for HiRDB in 32-bit mode
64: Relative position and length for HiRDB in 64-bit mode
- Note
- 1. and 2. in the Contents column indicate the following:
- Using pdload to input the input data file
- Using a UOC to input the input data file
#1: When the -e option is specified, UOC processing is also discontinued if erroneous data is detected. If pdload was used to input the input data file, the following results:
- If the -r option is specified, data up to the specified row data is not passed.
- If data contains a carriage return code (\r) before a linefeed code (\n) such as those in a DAT-format file created by a personal computer, the data is passed with the carriage return deleted.
- In the case of an input data file in pdrorg-output binary format with the -W option specified, LOB and BINARY columns cannot be edited.
- When processing a binary-format input data file, data is not passed if it has an invalid length for a variable-length character string.
#2: The value is set to -1 when the corresponding data is not to be input In the case of a HiRDB in the 64-bit mode, the maximum length of data valid for processing is 2 gigabytes minus 1 byte.
#3: The area that is pointed to by the input buffer address field is called the input buffer. The input buffer is allocated by pdload when pdload reads the input data file. The input buffer contains each row of data input by pdload. The format of the input buffer is as follows:
- DAT-format input data file
Text data read up to the linefeed code is stored as is. The end of the data consists of a linefeed code (\n) plus the NULL character (\0). Do not reference or update data beyond the last NULL character.
- Extended-DAT-format input data file
Text data up to the null character or linefeed code that is not enclosed in the enclosing character is stored as is. The length of the stored data is set as the input data length. Do not reference or update the area that is larger than this input data length.
- Binary-format input data file
The row length of the data is stored, as calculated from the table definition. The length of the stored data is set in the input data length. Do not reference or update the area beyond the length set in the input data length.
- Input data file output by pdrorg
For a FIX table, the input data length is set to the length of the data section only. For a non-FIX table, the input data length is set to the sum of the offset section plus the data section. Do not reference or update the area beyond the length set in the input data length. Because UOCs cannot handle LOB or BINARY columns, use pdrorg's UOC to edit tables that contain LOB or BINARY columns.
- Fixed-size-data-format input data file
The row length of the data is stored, as calculated from the column information in the column structure information file. For a text file, the data still contains linefeed (\n) and carriage return (\r) codes.
#4: The area pointed to by the edit buffer address field is called the edit buffer. The UOC allocates the edit buffer. However, when pdload reads the input data file, the input buffer can be used as is as the edit buffer if the input buffer is not to be updated beyond the specified data length. For binary-format data, set the length of data in the edit data length field to indicate the actual data part in the edit buffer. For DAT-format data, there is no need to set the length, but the end of the edit buffer data must be a linefeed code (\n) followed by the NULL character (\0).
#5: For an input data file in the binary or extended DAT format, specify the length of data for the edit buffer. For an input data file in the extended DAT format, make sure that the length of edited data does not exceed the maxreclen operand value specified in the source statement. For an input data file in any other format, specify the initial value of 0.