Ping utility (dbping)

Locates database servers and tests connections to databases.

Syntax
dbping [ options ]
Option Description
@data

Reads 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; ..."

Specifies 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 demo11 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 demo11 is found, dbping attempts to autostart one.

dbping -d -c "UID=DBA;PWD=sql;ENG=demo11;DBN=demo;DBF=samples-dir\demo.db"

For information about samples-dir, see Samples directory.

-d

Pings 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 Ping database failed -- specified database not found:

dbping -c "ENG=blair;DBN=demo" -d
-en Specifies that you want dbping to exit with a failed return code when NULL is returned for any of the properties specified. 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. This option can only be used in conjunction with -pc, -pd, and -ps.
-l library

Specifies the library to use (without its file extension). This option avoids the use of the ODBC driver manager, and so is useful on Unix operating systems.

For example, the following command loads the ODBC driver directly:

dbping -m -c "DSN=SQL Anywhere 11 Demo" -l dbodbc11

On Unix, if you want to use a threaded connection library, you must use the threaded version of the Ping utility, dbping_r.

-m Establishes a connection using ODBC. By default, the utility connects using the embedded SQL interface.
-o filename Writes output messages to the named file.
-pc property,...

Displays 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 properties.

For example, the following command displays the fire_triggers option setting, which is available as a connection property.

dbping -c ... -pc fire_triggers
-pd property[@db-name],...

Displays the specified database properties. Supply the properties in a comma-separated list. See Database 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
-ps property,...

Displays 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 Database server properties.

For example, the following command displays the number of licensed seats or processors for the database server:

dbping -c ... -ps LicenseCount
-q Runs in quiet mode—messages are not displayed.
-s Returns 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 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 specifies 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 Displays the network communication protocols used to attempt connection, and other diagnostic messages. This option is available only when an embedded SQL connection is being attempted. That is, it cannot be combined with -m or -l.
Remarks

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.