5.10.2 UOC interface

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.

Figures 5-27 and 5-28 show the structure of the UOC interface area. Table 5-33 describes the contents of the UOC interface area.

Figure 5-27 Structure of UOC interface area (32-bit mode)

[Figure]

Figure 5-28 Structure of UOC interface area (64-bit mode)

[Figure]

Table 5-33 Contents of UOC interface area

Relative positionField nameLength
(Byte)
AttributeValue setterContents
32643264
00Eye catcher88charpdloadInterface area (*UOCINF*).
88Executing program44longpdloadProgram receiving control:
0: pdload
1: UOC
1212Call type44longpdloadType 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 request1
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.
1616Length of authorization identifier22shortpdloadLength of name of table owner.
1818Authorization identifier3030charpdloadName of table owner.
4848Length of table identifier22shortpdloadLength of table name.
5050Table identifier3030charpdloadTable name.
8080Length of input data248longpdload
  1. 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
  2. This item is ignored.
8488Address of input buffer48void*pdload
  1. Set to the address of the buffer that stores the data input by pdload.
  2. This item is ignored.
8896Length of edit data2, 548longUOCFor 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
  1. Set to -1 if no data is stored.
92104Address of edit buffer48void*UOCAddress of buffer that stores the data edited by the UOC.
96112Address of user parameters48void*pdloadSet 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.
100120Information used by system48void*pdloadInformation used by the system (must not be used by the UOC).
104128Reserved1616charpdloadReserved area (must not be used by the UOC).
120144Return code44longUOCReturn 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.
124148Message embedded area132132charUOCStorage 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:
  1. Using pdload to input the input data file
  2. 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:

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:

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.