OPEN

Edit online

The OPEN request creates a session with the DS Client server, and obtains the shared memory object used to buffer the result sets.

The server can be identified either by subsystem name or by server group name. The group name is configured in AVZSIN00 using the parameter DSCLIENTGROUP. Connections to the same server group are distributed in a round-robin fashion. The API will return a connection handle in #DVCB-CNID; this handle must be maintained and returned on all subsequent API calls.

The OPEN call is optional. If a connection is not open when a request is sent, an implicit OPEN will be performed.

The following options can be presented on the OPEN call:
  • The subsystem name or group name that identifies the Data Virtualization Manager server.
  • The Db2 subsystem name (or none to use SQL Engine).
  • The row limit for the result set(s)
  • The auto-commit option
  • The request SQLDA option
  • The user ID and password to be used for access to the data source. The default is the API application user ID.

Providing alternate credentials

By default, the server will use the API application address space user ID to access the data source. Alternate credentials can be provided in #DVCB-USERID and #DVCB-PASSWORD. If #DVCB-USERID is non-zero, a password must be provided in #DVCB-PASSWORD. The application should clear #DVCB-PASSWORD to zeros after the OPEN call.

Map Reduce Client

Map Reduce Client (MRC) technology provides the ability for a client application to process large requests in parallel on multiple threads. Depending on the data source and the system architecture, significant reductions in elapsed time can be achieved using MRC. The data source must be enabled for Map Reduce in order to benefit from MRC.

To achieve end-to-end parallel processing using MRC, first determine the number of processing threads to use. Start or attach this number of client threads, and open a DS Client connection on each thread. In each DVCB, set #DVCB-MAPREDUCE-NO equal to the total number of threads. Set #DVCB-MAPREDUCE-ID in each thread to a unique value 1 – n, where n is the value of #DVCB-MAPREDUCE-NO. Send the same request on each client thread. The aggregate of all n composite result sets will be the complete result set for the request.
Note: If Map Reduce is not enabled for the data source, the complete result set will be returned to the thread which has specified #DVCB-MAPREDUCE-ID = 1. Threads 2 - n will immediately receive SQLCODE 100.

Map Reduce Client can also significantly reduce the elapsed time for large queries when running the application on a single thread, especially for locate-mode requests, and move-mode requests for which the row order is not essential. To use MRC on a single thread, set #DVCB-MAPREDUCE-NO equal to the total number of server threads desired, and set #DVCB-MAPREDUCE-ID to zero. For move-mode requests, set #DVCB-OPT-PRESERVE-ORDER to N if row order is not necessary. (The default is Y to preserve the row order of the result set.)

Note: MRC with #DVCB-OPT-PRESERVE-ORDER = ‘Y’ is generally slower than the server’s normal Map Reduce processing. Do not use this option unless row order is essential.

Example of an OPEN call in Natural

ASSIGN #DVCB-REQUEST-CODE = #OPEN-REQUEST                          
CALL 'AVZCLIEN' #DVCB(*) #SEND-AREA(*) #RECEIVE-AREA(*) #ERROR-AREA
     #SQLDA-AREA(*)

Connection handle

An explicit or implicit open creates a 16-byte connection handle, which is returned in field #DVCB-CNID. The application is responsible to preserve this value and present it intact on all future API calls. If the application must save and restore the connection handle, it must save the value after each OPEN or SEND API call.