Appendix F.2 Notes on UOC creation

When a UOC is used, a user-created program is installed on HiRDB for processing. In other words, the user-created program becomes part of the database management system. Any problem with the UOC may develop into a problem with HiRDB itself. For this reason, the UOC must be created very carefully and tested thoroughly. In addition, UOC creation must follow the HiRDB programming rules.

Organization of this subsection
(1) Common rules for pdload and pdrorg
(2) pdload-specific rules
(3) pdrorg-specific rules

(1) Common rules for pdload and pdrorg

  1. The programming language that can be used is C language.
  2. Create the UOC in the shared libraryformat.
  3. Grant read and execution permissions to the created shared library. Do not grant write permission. If you grant write permission by mistake, the UOC execution time becomes long, resulting in adverse effects on performance.
  4. A function that accesses a database uses a global buffer. A function that accesses a database from a buffer also uses a global buffer. If the buffer usage time is long, HiRDB detects a system error. Therefore, minimize the UOC processing and return control back to pdload or pdrorg as soon as possible.
  5. If processing terminates abnormally within the UOC, pdload or pdrorg also terminates abnormally. For details about the database status in the event of abnormal termination and the recovery method, see 5.13 Database status in the event of an error and recovery methods or 8.14 Database status in the event of an error and recovery method.
  6. The header file for UOC creation (pdutluoc.h) that declares the UOC interface area and symbolic constants is located under $PDDIR/include. To reference or update the interface area, we recommend that you include this header file during UOC compilation. If you are defining a user-specific header file for UOC creation for reasons such as variable name settings, note that there are differences in the table structure.
  7. Make sure that no global variable or function name begins with any of the following characters:
    • Uppercase SQL, Y, or Z
    • Lowercase p_, pd, yy, or z
    If you are using plug-ins or Java stored routines, also make sure that none of the names begin with any of the following characters:
    When using plug-ins:
    Lowercase _p
    When using Java stored routines:
    Lowercase da
    Lowercase dbr
    Lowercase dp
  8. Use the void type for the UOC's return value.
  9. Do not use the UOC to set or change environment variables.
  10. No SQL statement can be issued within the UOC.
  11. Do not perform signal manipulation.
  12. The main function cannot be used as the UOC.
  13. Do not create a recursive function.
  14. A stack shortage may result in abnormal termination within the UOC. If you use a large amount of stack, change the value of the relevant operating system parameter. For details about the operating system parameters, see the HiRDB Version 9 Installation and Design Guide.
  15. Do not create threads.
  16. Do not use any functions other than the following:
    • File manipulation functions
    • Character processing functions
    • Memory allocation and release functions
  17. Do not use any of the following functions:
    • Process manipulation functions, such as fork(), exit(), abort(), and exec()
    • sleep(), select(), and wait()
    • Stack manipulation functions (such as setjmp() and longjmp())
    • Shared memory manipulation functions
    • Semaphore manipulation functions
    • Socket manipulation functions
    • System resources manipulation functions (such as setrlimit)
    • mmap() and munmap()
    • gethostent(), sethostent(), endhostent(), gethostbyname(), gethostbyaddr(), and herror()
    • tempnam() and tmpnam()
    • pstat()
    • system()
  18. Do not use within the UOC the ID of a process that is executed by the UOC.
  19. With respect to file manipulation, note the following:
    • Do not manipulate any file in the HiRDB installation directory or HiRDB directory.
    • Do not manipulate any OS file.
    • To create a file, specify its absolute path name. Otherwise, a file will be created in the current directory. The current directory of a HiRDB process is under $PDDIR/tmp/home; do not create files here.
    • If a file is to be created within a UOC, the file permissions must be set explicitly.
    • Make sure that all temporary files created by the UOC are deleted (unlinked).
    • Do not use any special files, such as PIPE.
    • Do not use the standard input, standard output, or standard error output.
    • If you execute multiple utilities, multiple sets of the UOC are also executed concurrently. If the UOC locks file resources, make sure that any of the other UOCs that are running concurrently will not be placed in lock-release wait status.
    • The user is responsible for managing files output by the UOC.

(2) pdload-specific rules

  1. For a HiRDB parallel server configuration, provide the shared librarycontaining the UOC at the host where the server specified in the source statement is located.
  2. If pdload is to read a binary-format input data file and pass a line of data to the UOC, but it cannot edit data to a single line due to invalid length of a variable-length character string, pdload cancels processing.
  3. If there is no response from pdload, you can use the pdls -d rpc command to determine whether pdload or the UOC has control. If the resulting USR_EVENT is 0x00052601, the UOC has control.
  4. A UOC cannot be used to perform data loading for a pdrorg unload file.
  5. You should note the following if you use a pdrorg-output binary file with a different endian as the input data file:
    • When using a UOC for data input
      Pass the input data using the endian employed by the platform where pdload is executed because the endian is not converted after data has been input.
    • When passing data to a UOC
      Specify the srcendian operand in the option statement to pass to the UOC the data whose endian has been converted.

(3) pdrorg-specific rules

  1. Provide the shared librarycontaining the UOC at the host where the server used to call the UOC is located. For details about the server that calls the UOC and the host, see 8.11.2 Relationships between options and control statements.
  2. The UOC must not manipulate any files other than UOC data files.
  3. If memory space is allocated by the UOC by means of a OS functions (such as malloc), make sure that the memory space is released by the following call methods:
    • Returning a nonzero value as the return code during startup processing
    • Termination processing
    • Cancellation processing
  4. If there is no response from pdrorg, you can use the pdls -d rpc command to determine whether pdrorg or the UOC has control. If the resulting USR_EVENT is 0x00051601, the UOC has control.