%SSC_CONNECT

Connect to a database channel

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
value = %SSC_CONNECT(dbchannel, constring)

Return value

value

This function returns SSQL_NORMAL (success) or SSQL_FAILURE (failure). (i)

Arguments

dbchannel

The intended database channel. For traditional Synergy, the range is 1 to 100 on Windows and 1 to 7 on UNIX and OpenVMS. For Synergy .NET, the range is 1 to 512, except for devices where it is 1 to 7. (n)

constring

A connection string. This argument varies according to database and configuration, but has a maximum size of 256. (a)

Discussion

%SSC_CONNECT connects to a database channel initialized by %SSC_INIT. (See Database connections for more information.)

Note that every call to %SSC_CONNECT should be paired with a call to %SSC_RELEASE, unless you use the %SSC_CMD option SSQL_KEEP_OPEN. (For information on SSQL_KEEP_OPEN, see %SSC_CMD.)

Note

On OpenVMS, if a channel is not explicitly released with %SSC_RELEASE, the associated license will not be released. Use the logging available with the SSQLLOG environment variable to verify that there is an %SSC_RELEASE call for every %SSC_CONNECT call. For information on SSQLLOG logging, see SQL Connection logging.

For information on connect strings you can pass as constring, see Building connect strings.

If the %SSC_CMD option SSQL_KEEP_OPEN is in force, passing the number for a database channel (dbchannel) that was opened by a prior program in a program chain will cause a runtime error.

Examples

The following example uses a case statement to determine what connect string to use.

case (MY_SSQL_SYSTEM) of                ;MY_SSQL_SYSTEM - user defined
  begincase
SQLSRVR:  user = "VTX12_SQLNATIVE:sa/manager" ;Do setup of connect string
ORACLE:  user = "VTX0_10:sa/manager"
  endcase
else
  user = "sa/manager"                   ;Default database connection
if (%ssc_connect(dbchn, user))
  goto err_exit

The next example tests for a SQL Server database (SSQL_DID_SQLSRV).

user = "sa/manager"                     ;Default database
if (%ssc_connect(dbchn, user))          ; connection
  goto err_exit
if (%ssc_getdbid(dbchn, dbid))          ;Get the database ID
  goto err_exit
if (dbid.eq.SSQL_DID_SQLSRV)
  if (%ssc_cmd(dbchn, SSQL_USEDB, "synergex"))
    goto err_exit