Reference Manual
CHAPTER 3. Connection and Communication Parameters
This section describes each of the connection parameters that can be included in connection strings or data sources.
Connection parameters are case-insensitive.
The Usage for each connection parameter describes the circumstances under which the parameter is to be used. Common usage entries include the following:
Embedded databases When Adaptive Server Anywhere is used as an embedded database, a personal server is started by the connection, and the database is loaded by the connection. When the application disconnects from the database, the database is unloaded and the server stops.
Running local databases This refers to the case where an Adaptive Server Anywhere personal server is already running, and the database is already loaded on the server.
Network servers When Adaptive Server Anywhere is used as a network server, the client application must locate the server on the network and connect to a database already loaded on to it.
Agent connection parameterTo specify a local or network connection.
Anywhere
String. Must be any or server.
No value.
If you wish to ensure that you connect to a server on a network, and do not start a personal database server, specify Agent=server to ensure a connection to the appropriate agent.
The following entry in a file data source instructs the connection not to start a personal server:
... agent=server ...
AutoStart connection parameter [Astart]To prevent a local database server from being started if no connection is found.
Anywhere.
Yes
By default, if no server is found during a connection attempt, and a database file is specified, then a database server is started on the same machine. You can turn this behavior off by setting the AutoStart parameter to OFF in the connection string.
The following data source fragment prevents a database server from being started if no network server is located:
[My Sample Database] DatabaseFile=c:\asa6\asademo.db Autostart=No UserID=dba ENG=network_server
AutoStop connection parameter [Astop]To prevent a database from being unloaded as soon as there are no more open connections.
Embedded databases.
Yes
By default, any server that is started from a connection string is stopped when there are no more connections to it. Also, any database that is loaded from a connection string is unloaded as soon as there are no more connections to it. This behavior is equivalent to Autostop=Yes.
If you supply Autostop=No, any database that you start in that connection is not unloaded when there are no more connections to it. As a consequence, the database server will not be shut down either.
The AutoStop parameter is used only if you are connecting to a database that is not currently running. It is ignored if the database is already loaded.
The following data source fragment prevents the database from being unloaded when the connection is dropped:
[Sample Embedded Database] DatabaseFile=c:\asa6\asademo.db Autostop=No UserID=dba
CommAutoStop connection parameter [CAstop]To unload network communications ports as soon as there are no more open connections from the client machine.
Network server.
No
When the client library makes a connection over a network, it loads one or more network ports into memory.
By default, a network port that is started from a connection string is not unloaded when there are no more connections to it. This behavior is equivalent to CommAutostop=No.
If you supply CommAutostop=Yes, any network ports you start from that connection are unloaded when there are no more connections using them.
The following data source fragment instructs the client library to unload the network ports after the connection is dropped:
[Sample Connection] ServerName=network_server CommAutostop=Yes UserID=dba PWD=sql CommLinks=tcpip
CommBufferSize connection parameter [CBSize]To set the maximum size of communication packets, in bytes.
Network server only.
Integer
512
The CommBufferSize parameter specifies the size of communications packets, in bytes. The minimum value of CommBufferSize is 280, anf the maximum is 16000. If the specified packet size is larger than that of the database server, the server's packet size is used.
The maximum size of a packet on a network is set by the protocol stack. If you set CommBufferSize to be larger than that permitted by your network, the largest buffers are broken up by the network software. You should set the buffer size to be somewhat smaller than that allowed by your network, because the network software may add information to each buffer before sending it over the network.
This corresponds to the SQL Anywhere Version 5 dbclient -p command-line switch.
The following data source fragment sets the buffer size to 400 bytes:
... CommBuffSize=400 ...
CommBufferSpace connection parameter [CBSpace]To specify the amount of space to allocate on startup for network buffers, in kilobytes.
Network servers only
Integer
100.
Specify amount of space to allocate on startup for network buffers, in kilobytes. The default is 100.
The value is a global setting, for all connections.
The following data source fragment instructs the network library to allocate 200 Kb for network buffers on startup.
... CBSpace=200 ...
CommLinks connection parameter [Links]To specify network communications links.
Connections to the network server only.
Use all communications links (network protocols) supported on the current operating system.
Network communications parameters
If no CommLinks parameter is specified in a connection string, the network library is not started and no search is made for a server other than on the current machine. This behavior is equivalent to CommLinks = None.
If a CommLinks parameter is supplied, the named communication links are started and used when searching for a database server. The CommLinks parameter is required for connections to a network server.
Available values of the CommLinks parameter are as follows:
NONE Start no communications links
TCP/IP Start the TCP/IP communications link. TCP/IP is supported on all operating systems.
IPX Start the TCP/IP communications link. The IPX protocol is supported for Windows and NetWare clients.
NetBIOS Start the NetBIOS communications link. NetBIOS is supported on Windows operating systems.
ALL Start all available communications links.
You may wish to use a specific protocol, as opposed to ALL, for the following reasons:
The network library starts slightly faster if unnecessary network links are not started.
If you wish to tune the broadcast behavior of a particular protocol by providing additional network communications parameters, you must specify the link explicitly.
Additional network communications parameters may be provided for each link, to tune the broadcast behavior of the link.
The CommLinks parameter corresponds to the database server -x command-line switch. The default behavior of the network server is equivalent to -x ALL
The following data source fragment starts the TCP/IP protocol only:
CommLinks=tcpip
The following data source fragment (which is held on one line in a data source) starts the TCP/IP and IPX protocols, searching for the host kangaroo in addition to servers on the immediate TCP/IP network:
CommLinks=ipx, tcpip(HOST=kangaroo)
ConnectionName connection parameter [CON]Names a connection, to make switching to it easier in multi-connection applications.
Not available for ODBC.
No connection name.
An optional parameter, providing a name for the particular connection you are making. You may leave this unspecified unless you are going to establish more than one connection, and switch between them.
The Connection Name is not the same as the data source name.
Connect, naming the connection FirstCon:
CON=First Con
DatabaseFile connection parameter [DBF]The database file to which you want to connect.
Embedded databases
There is no default setting.
To load and connect to a specific database file.
If a database is loaded with a name that is the same as the DatabaseFile parameter, but without the .db extension, the connection is made to that database instead.
If the filename does not include an extension, a file of name .db is looked for.
The path of the file is relative to the working directory of the database server. If you start the server from the command prompt, the working directory is the directory that you are in when entering the command. If you start the server from an icon or shortcut, it is the working directory that the icon or shortcut specifies.
To load and connect to the sample database, installed in directory c:\asa6, use the following DBF parameter:
DBF=c:\asa6\asademo.db
DatabaseName connection parameter [DBN]Identifies a loaded database to which a connection needs to be made.
Running local databases or network servers.
There is no default setting.
Whenever a database is started on a server, it is assigned a database name. The default database name is the name of the database file with the extension and path removed.
Connect to a database named Kitchener
DBN=Kitchener
DatabaseSwitches connection parameter [DBS]To provide database-specific switches when starting a database.
Connecting to a running server when the database is not loaded.
No switches
StartLine connection parameter
You should supply DatabaseSwitches only if you are connecting to a database that is not currently running. When the server starts the database specified by DatabaseFile, the server uses the supplied DatabaseSwitches as command line options to determine startup options for the database.
Only database switches can be supplied using this parameter. Server switches must be supplied using the START connection parameter.
The following command, entered all on one line, connects to the default database server, loads the database file \sa60\asademo.db (DBF parameter), names it as my_db (DBS parameter) and connects to the database of that name (DBN parameter).
dbcollat -c "uid=dba;pwd=sql;dbf=\sa60\asademo.db;dbn=my_db; dbs=-n my_db" e:\temp\temp.col
DataSourceName connection parameter [DSN]Tells the ODBC driver manager or Embedded SQL library where to look in the odbc.ini file or registry to find ODBC data source information.
Anywhere
There is no default data source name.
FileDataSourceName connection parameter
It is common practice for ODBC applications to send only a data source name to ODBC. The ODBC driver manager and ODBC driver locate the data source, which contains the remainder of the connection parameters.
In Adaptive Server Anywhere, Embedded SQL applications can also use ODBC data sources to store connection parameters.
The following parameter uses a data source name:
DSN=Dynamo Demo
Debug connection parameter [DBG]To provide diagnostic information on communications links on startup.
Network server only.
No diagnostic information.
If you are having trouble establishing a connection to a network server, set the Debug connection parameter to Yes and the Logfile parameter to a log file name. Diagnostic information is then placed in the log file.
The following data source fragment says to use the Debug switch, with output to a file named error.log.
... DBG=Yes Log=ERROR.LOG ...
DisableMultiRowFetch connection parameter [DMRF]To turn off multi-row fetches across the network.
Network server only.
Yes
By default, when the database server gets a simple fetch request, it fills one network packet with several rows so that subsequent sequential fetches do not require network traffic. This is often referred to as blocking of fetches.
The following data source fragment requires no blocking of fetches:
... DMRF=Yes ...
EngineName connection parameter [ENG]Synonym for ServerName. The name of a running database server to which you want to connect.
Network servers or running personal servers.
The default local database server.
EngineName is not needed if you wish to connect to a local database server and only one server is running.
You need to supply an EngineName only if more than one database server is running, or you wish to connect to a network server.
In the Sybase Central and Interactive SQL Connect dialog box, and in the ODBC Administrator, this is the Server Name field
Connect to a server named Guelph:
ENG=Guelph
EncryptedPassword connection parameter [ENP]To provide a password, stored in an encrypted fashion in a data source.
Anywhere
None
Data sources are stored on disk as a file or in the registry. Storing passwords on disk may present a security problem. For this reason, when you enter a password into a data source, it is stored in an encrypted form.
If both Password and EncryptedPassword are specified, Password takes precedence.
Encryption connection parameter [ENC]To encrypt packets transmitted from the client machine over the network.
Network server only.
Boolean
No encryption.
You can use this parameter if you are concerned about the security of network packets. Encryption does affect performance marginally.
This parameter corresponds to the SQL Anywhere Version 5 dbclient -e command-line switch.
Using the -e switch on the dbsrv6 command line encrypts packets for all clients regardless of whether the Encryption parameter is used at the client.
The following connection parameter instructs the client to encrypt packets:
ENC=Yes
FileDataSourceName connection parameter [FileDSN]The FileDataSourceName parameter tells the client library that there is an ODBC file data source holding information about the database to which you want to connect.
Both ODBC and Embedded SQL applications can use File data sources
Anywhere
There is no default name.
DataSourceName connection parameter
File data sources hold the same information as ODBC data sources stored in the registry. File data sources can be easily distributed to end users, so that connection information does not have to be reconstructed on each machine.
The following is a data source description held in a file data source:
[Sample File Data Source] ENG = asademo DBA = dba PWD = sql
Integrated connection parameter [INT]To use the integrated login facility.
Anywhere
No
The Integrated parameter has the following settings:
Yes An integrated login is attempted. If the connection attempt fails and the LOGIN_MODE option is set to Mixed, a standard login is attempted.
No This is the default setting. No integrated login is attempted.
For a client application to use an integrated login, the server must be running with the LOGIN_MODE database option set to Mixed or Integrated.
The following data source fragment uses an integrated login:
INT=yes
LivenessTimeout connection parameter [LTO]To control the termination of connections when they are no longer intact.
Network server only, and only on TCP/IP and IPX communications protocols.
Integer
If no LivenessTimeout value is set, the liveness timeout is controlled by the setting on the server, which defaults to 120 seconds.
A liveness packet is sent periodically across a client/server TCP/IP or IPX communications protocol to confirm that a connection is intact. If the client runs for the liveness timeout period without detecting a liveness packet, the communication is severed.
Liveness packets are sent at an interval of one quarter of the LivenessTimeout value.
When the communication is severed, the client machine forgets the address of the server. It looks the address up next time there is a connection to the server from that machine, dropping all current connections to that server.
The following sets a Liveness timeout value of 60 seconds
LTO=60
Logfile connection parameter [LOG]To send client error messages and debugging messages to a file.
Network server only.
No log file.
If you want to save client error messages and debugging messages in a file, use the Logfile parameter.
If the file name includes a path, it is relative to the current working directory of the client application.
The following data source fragment says to use the Debug switch, with output to a file named error.log.
... DBG=Yes Logfile=ERROR.LOG ...
Password connection parameter [PWD]To provide a password for the connection.
Anywhere
No password provided.
EncryptedPassword connection parameter
Every user of a database has a password. The password must be supplied for the user to be allowed to connect to the database.
The password parameter is not encrypted. If you are storing passwords in a data source, you should use the EncryptedPassword parameter. Sybase Central and the Adaptive Server Anywhere ODBC configuration tool both use encrypted parameters.
If both Password and EncryptedPassword are specified, Password takes precedence.
The following connection string fragment supplies the user ID DBA and password SQL.
uid=dba;pwd=SQL
ServerName connection parameter [ENG]Synonym for EngineName connection parameter.
StartLine connection parameter [START]To start a database server running from an application.
Embedded databases.
No StartLine parameter
You should supply a StartLine parameter only if you are connecting to a database server that is not currently running. The StartLine parameter is a command line to start a personal database server.
For a detailed description of available command line switches, see The database server.
The following data source fragment starts a personal database server with a cache of 8 Mb.
StartLine=dbeng6 -c 8M asademo.db
Unconditional connection parameter [UNC]To stop a server using dbstop even when there are connections to the server.
Anywhere
No
The DBSTOP command-line utility
The dbstop command-line utility shuts down a database server. If you specify Unconditional=Yes in the connection string, the server is shut down even if there are active connections. If Unconditional is not set to Yes, then the server is shut down only if there are no active connections.
The following command line shuts down the server unconditionally:
dbstop -c "uid=dba;pwd=sql;eng=server-name;unc=yes"
Userid connection parameter [UID]The user ID with which you log on to the database.
Anywhere
None
You must always supply a user ID when connecting to a database
The following connection string fragment supplies the user ID DBA and password SQL:
uid=dba;pwd=SQL