SET CONNECTION

Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be embedded in an application program, except in REXX programs. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

SET CONNECTION {location-name | host-variable}

Description

Identifies the SQL connection by the specified location name or the location name contained in the host variable. If a host variable is specified:

It must be a character string variable with a length attribute that is not greater than 16. (A C NUL-terminated character string can be up to 17 bytes.)
It must not be followed by an indicator variable.
The location name must be left-justified within the host variable and must conform to the rules for forming an ordinary location identifier.
If the length of the location name is less than the length of the host variable, it must be padded on the right with blanks.

Let S denote the specified location name or the location name contained in the host variable. S must identify an existing SQL connection of the application process. If S identifies the current SQL connection, the state of S and all other connections of the application process are unchanged. The following rules apply when S identifies a dormant SQL connection.

If the SET CONNECTION statement is successful:

SQL connection S is placed in the current state.
S is placed in the CURRENT SERVER special register.

Information about application server S is placed in the SQLERRP field of the SQLCA. If the application server is an IBM product, the information has the form pppvvrrm, where:

ppp

One of:

ARI	DB2 Server for VSE & VM
DSN	DB2 for OS/390
QSQ	OS/400
SQL	all other DB2 products

`vv`	is a two-digit version identifier such as '06'.
`rr`	is a two-digit release identifier such as '01'.
`m`	is a one-digit modification level such as '0'.

For example, if the server is Version 6 of DB2 for OS/390 with the latest maintenance, the value of SQLERRP is 'DSN06011'. Any previously current SQL connection is placed in the dormant state.

If the SET CONNECTION statement is unsuccessful, the connection state of the application process and the states of its SQL connections are unchanged.

Examples:

Execute SQL statements at TOROLAB1, execute SQL statements at TOROLAB2, and then execute more SQL statements at TOROLAB1.

EXEC SQL CONNECT TO TOROLAB1;

(execute statements referencing objects at TOROLAB1)

EXEC SQL CONNECT TO TOROLAB2;

(execute statements referencing objects at TOROLAB2)

EXEC SQL SET CONNECTION TOROLAB1;

(execute statements referencing objects at TOROLAB1)

The first CONNECT statement creates the TOROLAB1 connection, the second CONNECT statement places it in the dormant state, and the SET CONNECTION statement returns it to the current state.