(a) What is the multi-connection facility?

The multi-connection facility establishes multiple connections to the HiRDB server from one AP process in a HiRDB client. This facility can be used only when creating or executing a UAP in the HP-UX, Solaris, or Windows environment.

The multi-connection facility establishes independent individual connections. A separate server process is allocated to each connection, and the connections are processed as separate transactions. The AP process can, therefore, execute multiple SQL statements simultaneously. Because multiple connections can be established from one UAP, the number of UAPs to be executed can be reduced, and the overall memory requirement for UAPs can be reduced.

Because each connection is counted as a separate user, the maximum number of server connections becomes the maximum number of simultaneous connections rather than the maximum number of users.

The multi-connection facility has the following characteristics:

• A different authorization server and password can be used for each connection.
• One AP process can connect to HiRDB servers on multiple server computers and execute SQL statements because each connection can be connected to a HiRDB server in a different server computer.
• The multi-connection facility can be used for all servers that can connect to the client library.

(b) Multi-connection facility in the X/Open XA interface environment

When the multi-connection facility is used in the X/Open XA interface environment, a UAP operating under a single transaction manager (such as OpenTP1) can use the XA interface to access multiple HiRDB systems. Because the UAP is using the XA interface, the UAP can synchronize and control processing among transactions that access multiple HiRDB systems.

For the open character string to be specified in the xa_open() function, specify the name of the file in which the environment variables (client environment definitions) were set. The xa_open() function establishes a connection to HiRDB according to those environment variables. You can select the destination to which an SQL statement is issued from among the connection destinations connected by the xa_open() function.

The multi-connection facility in the X/Open XA interface environment can be used only with the following client platforms:

• HP-UX 11.0
• Solaris
• AIX 5L (single thread)
• Linux (single thread)
• Windows

Figures 4-54 through 4-58 show an overview of multi-connection facility processing.

Figure 4-54 Overview of multi-connection facility processing (when multithreading is not used)

Figure 4-55 Overview of multi-connection facility processing (when multithreading is used)

Figure 4-56 Overview of multi-connection facility processing (when a connection is shared by multiple threads)

Figure 4-57 Overview of multi-connection facility processing (when an AP uses an X/Open-compliant API in a single-thread OLTP system)

Explanation

Register HiRDB 1 and HiRDB 2 in the OLTP system beforehand. When tx_open() is executed, the OLTP system connects to all registered HiRDB systems. When an SQL statement is executed, select the connection destination for that SQL statement.

Figure 4-58 Overview of multi-connection facility processing (when an AP uses an X/Open-compliant API in a multi-thread OLTP system)

Explanation

Register HiRDB 1 and HiRDB 2 in the OLTP system beforehand. When tx_begin() is executed, the OLTP system connects to all registered HiRDB systems. When an SQL statement is executed, select the connection destination for that SQL statement. Because the individual transactions are independent, SQL statements for different threads can be executed simultaneously.

(a) Normal UAPs

Figures 4-59 and 4-60 show coding examples of UAPs that use the multi-connection facility.

Figure 4-59 Coding example (C) of a UAP that uses the multi-connection facility

Explanation

1. Defines the connection handle.
2. Allocates the connection handle.
3. Specifies HiRDB processing for connection 1.
4. Specifies HiRDB processing for connection 2.
5. Releases the connection handle.
   

   Figure 4-60 Coding example (COBOL) of a UAP that uses the multi-connection facility

   

Note

Specify the entire SQL, including the SQL prefix and terminator, in the B area (columns 12 to 72).

Explanation

1. Defines the connection handle.
2. Allocates the connection handle.
3. Specifies HiRDB processing for connection 1.
4. Specifies HiRDB processing for connection 2.
5. Releases the connection handle.

(b) UAPs that use an X/Open-compliant API under OLTP

Figures 4-61 and 4-62 show coding examples in which the multi-connection facility is used by UAPs that use an X/Open-compliant API under OLTP.

Figure 4-61 Coding example (C) in which the multi-connection facility is used by a UAP that uses an X/Open-compliant API under OLTP

Explanation

Register HiRDB 1 (environment variable group identifier HDB1) and HiRDB 2 (environment variable group identifier HDB2) in the OLTP system beforehand. For details about how to register a HiRDB system to a transaction manager, see the HiRDB Version 8 Installation and Design Guide.

Figure 4-62 Coding example (COBOL) in which the multi-connection facility is used by a UAP that uses an X/Open-compliant API under OLTP

Note

Specify the entire SQL, including the SQL prefix and terminator, in the B area (columns 12 to 72).

Explanation

Register HiRDB 1 (environment variable group identifier HDB1) and HiRDB 2 (environment variable group identifier HDB2) in the OLTP system beforehand. For details about how to register a HiRDB system to a transaction manager, see the HiRDB Version 8 Installation and Design Guide.

1. If a UAP is to use the multi-connection facility, a special library must be linked to that UAP. For details, see 8.3.4 Compiling and linking when the multi-connection facility is used.
2. If a UAP that uses the multi-connection facility library branches a thread while maintaining a single connection, and that thread executes SQL statements, serialize the processing between that thread and the other threads that issue SQL statements. SQL statements for the same connection cannot be issued simultaneously. However, SQL statements for different connections can be issued simultaneously.
3. To obtain error information for ALLOCATE CONNECTION HANDLE or FREE CONNECTION HANDLE, reference the value of the return code receiving variable instead of SQLCODE and SQLERRM. For details about the return code receiving variable, see the HiRDB Version 8 SQL Reference manual.
4. To reference an SQL Communications Area, the UAP must use the DECLARE CONNECTION HANDLE SET statement to declare a connection handle to the SQL Communications Area to be referenced.
5. When the programming language is COBOL, UAPs containing SQL statements that use the multi-connection facility cannot specify SQL statements except those for connection handle allocation and fetching before the DECLARE CONNECTION HANDLE SET specification (outside the effective scope).
6. When the programming language is COBOL, DECLARE CONNECTION HANDLE UNSET cannot be used.
7. The multi-connection facility can be used by UAPs that support multiple threads (DCE threads or real threads) or a single thread. To create a UAP that supports multi-threads and uses the multi-connection facility, you need to know how to develop a UAP in HiRDB and how to develop a UAP that uses DCE threads or real threads.
8. The multi-connection function in Windows can only be used by UAPs that support multi-threads. Therefore, when specifying the C runtime library to be used in UAP compilation, select the multi-thread DLL (specify Multithread DLL in Compile option: Code generation).
9. When using C or C++ to reference the SQL Communications Area, use and reference macro names that begin with SQL. Do not reference the SQLCA structures directly. For details about the macro names to be used, see B.2(1)(a) C.