Locates database servers and tests connections to databases.
dbping [ options ]
Use this option to read in options from the specified environment variable or configuration file. See Using configuration files.
If you want to protect passwords or other information in the configuration file, you can use the File Hiding utility to obfuscate the contents of the configuration file. See File Hiding utility (dbfhide).
|-c "keyword=value; ..."||
Use this option to specify connection parameters that control the behavior of dbping. If connection parameters are not specified, connection parameters from the SQLCONNECT environment variable are used, if set. See Connection parameters.
If you use the following command to start dbping and there is a database server named demo10 already running, dbping attempts to connect to a database named demo. If no such database is running on that database server, the database server attempts to load demo.db. If no server called demo10 is found, dbping attempts to autostart one.
dbping -d -c "UID=DBA;PWD=sql;ENG=demo10;DBN=demo;DBF=samples-dir\demo.db"
For information about samples-dir, see Samples directory.
Ping the database, not just the server.
If you supply the -d option, then dbping reports success only if it connects to the server and also connects to a database. If you do not supply the -d option, then dbping reports success if it finds the server specified by the -c option.
For example, if you have a database server named blair running the sample database, the following succeeds:
dbping -c "ENG=blair;DBN=demo"
The following command fails, with the message
dbping -c "ENG=blair;DBN=demo" -d
|-en||By default, dbping prints NULL when the value for a property specified by -pc, -pd, or -ps is unknown, and exits with a success return code. Specify the -en option if you want dbping to exit with a failed return code when NULL is returned for any of the properties specified. This option can only be used in conjunction with -pc, -pd, and -ps.|
Specify the library to use (without its file extension). This option avoids the use of the ODBC driver manager, and so is particularly useful on Unix operating systems.
For example, the following command loads the ODBC driver directly:
dbping -m -c "DSN=SQL Anywhere 10 Demo" -l dbodbc10
On Unix, if you want to use a threaded connection library, you must use the threaded version of the Ping utility, dbping_r.
|-m||Establish a connection using ODBC. By default, the utility connects using the embedded SQL interface.|
|-o filename||Write output messages to the named file.|
Upon connection, display the specified connection properties. Supply the properties in a comma-separated list. You must specify enough connection information to establish a database connection if you use this option. See Connection-level properties.
For example, the following command displays the divide_by_zero_error option setting, which is available as a connection property.
dbping -c ... -pc divide_by_zero_error
Upon connection, display the specified database properties. Supply the properties in a comma-separated list. See Database-level properties.
For example, the following command displays the page size in use by the database:
dbping -c ... -pd PageSize
Optionally, you can specify the name of a database running on the database server you want to obtain the value from. For each property listed, if the database name is not specified by appending @db-name to the property, then the database name used for the previous property is used.
The following command displays the page size and collation of the database mydb:
dbping -c ... -pd PageSize@mydb,Collation
Upon connection, display the specified database server properties. Supply the properties in a comma-separated list. You must specify enough connection information to establish a database connection if you use this option. See Server-level properties.
For example, the following command displays the number of licensed seats or processors for the database server:
dbping -c ... -ps LicenseCount
|-q||Run in quiet mode—do not display messages.|
|-s||Use this option to obtain information about the performance of the network between the computer running dbping and the computer running the database server. Approximate connection speed, latency, and throughput are displayed. The -c option is usually required to specify the connection parameters to connect to a database on the desired server. You can only use dbping -s for embedded SQL connections. This option is ignored if -m or -l is also specified. By default, dbping -s loops through the requests for at least one second for each statistic it measures. A maximum of 200 connect and disconnect iterations are performed, regardless of the time they take, to avoid consuming too many resources. On slower networks, it can take several seconds to perform the minimum number of iterations for each statistic. The performance statistics are approximate, and are more accurate when both the client and server computers are fairly idle. See Testing embedded SQL connection performance.|
|-st time||This option is the same as -s, except that it lets you specify the length of time, in seconds, that dbping loops through the requests for each statistic it measures. This option allows more accurate timing information to be obtained that -s. See Testing embedded SQL connection performance.|
|-z||This option is available only when an embedded SQL connection is being attempted. That is, it cannot be combined with -m or -l. It displays the network communication protocols used to attempt connection, and other diagnostic messages.|
The dbping utility is a tool to help debug connection problems. It takes a full or partial connection string and returns a message indicating whether the attempt to locate a server or database, or to connect, was successful.
The utility can be used for embedded SQL or ODBC connections. It cannot be used for jConnect (TDS) connections.
Exit codes are 0 (success) or non-zero (failure). See Software component exit codes.