@data

Use this option to read in options from the specified environment variable or configuration file. If both exist with the same name, the environment variable is used.

The environment variable may contain any set of options. For example, the first of the following pair of statements sets an environment variable holding a set of options for a database server that starts with a cache size of 4 MB, receives messages only, and connects to a database named field on a server named myserver. The set statement should be entered all on one line:

set envvar=-m 4096 -r
 -c "eng=myserver;dbn=field;UID=sa;PWD=sysadmin"
dbremote @envvar

The configuration file may contain line breaks, and may contain any set of options. For example, the following command file holds a set of options for a Message Agent that starts with a cache size of 4 MB, sends messages only, and connects to a database named field on a server named myserver:

-m 4096
-s
-c "eng=myserver;dbn=field;UID=sa;PWD=sysadmin"

If this configuration file is saved as c:\config.txt, it can be used in a command as follows:

dbremote @c:\config.txt

-a

Process the received messages (those in the inbox) without applying them to the database. Used together with -v (for verbose output) and -p (so the messages are not purged), this option can help detect problems with incoming messages. Used without -p, this option purges the inbox without applying the messages, which may be useful if a subscription is being restarted.

-b

Run in batch mode. In this mode, the Message Agent processes incoming messages, scans the transaction log once and processes outgoing messages, and then stops.

-c "keyword=value; ..."

Specify connection parameters. For SQL Anywhere, if this option is not specified, the environment variable SQLCONNECT is used.

For example, the following statement runs dbremote on a database file named c:\mydata.db, connecting with user ID DBA and password sql:

dbremote -c "UID=DBA;PWD=sql;DBF=c:\mydata.db"

The Message Agent must be run by a user with REMOTE DBA authority or DBA authority.

For information on REMOTE DBA authority, see The Message Agent and replication security.

The Message Agent supports the full range of SQL Anywhere connection parameters.

-dl

Display messages in the Message Agent window or at the command prompt and also in the log file if specified.

-ek key

This option allows you to specify the encryption key for strongly encrypted databases directly at the command prompt. If you have a strongly encrypted database, you must provide the encryption key to use the database or transaction log in any way, including offline transaction logs. For strongly encrypted databases, you must specify either -ek or -ep, but not both. The command will fail if you do not specify a key for a strongly encrypted database.

-ep

This option allows you to specify that you want to be prompted for the encryption key. This option causes a window to appear, in which you enter the encryption key. It provides an extra measure of security by never allowing the encryption key to be seen in clear text. For strongly encrypted databases, you must specify either -ek or -ep, but not both. The command will fail if you do not specify a key for a strongly encrypted database.

"language_name,charset_name[,sort_order]"

By default, the Message Agent uses the default locale, which is defined in the file sybase\locales\locales.dat.

-g n

Instructs the Message Agent to group transactions containing less than n operations together with transactions that follow. The default is twenty operations. Increasing the value of n can speed up processing of incoming messages, by doing less commits. However, it can also cause deadlock and blocking by increasing the size of transactions.

If neither -r nor -s is specified, the Message Agent executes all three phases. Otherwise, only the indicated phases are executed.

-l length

Specifies the maximum length of each message to be sent, in bytes. Longer transactions are split into more than one message. The default is 50000 bytes and the minimum length is 10000.

For platforms with restricted memory allocation, the value must be less than the maximum memory allocation of the operating system.

-m size

Specifies a maximum amount of memory to be used by the Message Agent for building messages and caching incoming messages. The allowed size can be specified as n (in bytes), nK, or nM. The default is 2048 KB (2 MB).

When all remote databases are receiving unique subsets of the operations being replicated, a separate message for each remote database is built up concurrently. Only one message is built for a group of remote users that are receiving the same operations. When the memory being used exceeds the -m value, messages are sent before reaching their maximum size (as specified by the -l option).

When messages arrive, they are stored in memory by the Message Agent until they are applied. This caching of messages prevents rereading of messages that are out of order from the message system, which may lower performance on large installations. When the memory usage specified using the -m option is exceeded, messages are flushed in a least-recently used fashion.

-ml directory

Specify the location of offline mirror logs. This option makes it possible for dbremote to delete old mirror log files when either of the following two circumstances occur:

In a typical setup, the active mirror log and renamed mirror transaction logs are located in the same directory, and dbremote is run on the same machine as the remote database, so this option is not required and old mirror log files are automatically deleted. Transaction logs in this directory are only affected if the delete_old_logs database option is set to On or DELAY.

-o file

Output messages to file. Append output to a log file. Default is to send output to the screen.

-os size

Specify the maximum file size for logging output messages. The allowed size can be specified as n (bytes), nK (KB), or nM (MB). By default there is no limit, and the minimum limit is 10000 bytes.

Before SQL Remote logs output messages to a file, it checks the current file size. If the log message will make the file size exceed the specified size, SQL Remote renames the output file to yymmddxx.dbr, where xx are sequential characters ranging from AA to ZZ, and yymmdd represents the current year, month, and date.

If the Message Agent is running in continuous mode for a long time, this option allows you to manually delete old log files and free up disk space.

-ot file

Truncate the log file and then append output messages to it. Default is to send output to the screen.

-p

Do not purge messages. Process the messages without purging them.

-q

For Windows operating systems only, this option starts the Message Agent with a minimized window.

-qc

Close window on completion.

-r

Receive messages. If none of -r, -I, or -s is specified, the Message Agent executes all three phases. Otherwise, only the indicated phases are executed.

The Message Agent runs in continuous mode if called with -r. To have the Message Agent shut down after receiving messages, use the -b option in addition to -r.

-rd minutes

Polling frequency for incoming messages. By default, the Message Agent polls for incoming messages every minute. This option (rd stands for receive delay) allows the polling frequency to be configured, which is useful when polling is expensive.

You can use a suffix of s after the number to indicate seconds, which may be useful if you want frequent polling. For example:

dbremote -rd 30s

polls every thirty seconds.

See Tuning incoming message polling.

-ro filename

Log remote output to file. This option is for use at consolidated sites. When remote databases are configured to send output log information to the consolidated database, this option writes the information to a file. The option is provided to help administrators troubleshoot errors at remote sites.

See Troubleshooting errors at remote sites.

-rp number

Number of receive polls before message is assumed lost. When running in continuous mode, the Message Agent polls at certain intervals for messages. After polling a set number of times (by default, one), if a message is missing, the Message Agent assumes it has been lost and requests that it be resent. On slow message systems, this can result in many unnecessary resend requests. You can set the number of polls before a resend request is issued using this option, to cut down on the number of resend requests.

For more information on configuring this option, see Tuning incoming message polling.

-rt filename

Truncate, and log remote output to file. This option is for use at consolidated sites. It is identical to the -ro option except that the file is truncated on startup.

-ru time

Waiting period to re-scan log on receipt of a resend.

Control the resend urgency. This is the time between detection of a resend request and when the Message Agent starts fulfilling the request. Use this option to help the Message Agent collect resend requests from multiple users before rescanning the log. The time unit can be {s = seconds; m = minutes; h = hours; d = days}.

-s

Send messages. If none of -r, -I, or -s is specified, the Message Agent executes all three phases. Otherwise, only the indicated phases are executed.

-sd time

Control the send delay which is the time to wait between polls for more transaction log data to send.

-t

Replicate all triggers. All trigger actions are replicated. If you do use this option, you must ensure that the trigger actions are not carried out twice at remote databases, once by the trigger being fired at the remote site, and once by the explicit application of the replicated actions from the consolidated database.

To ensure that trigger actions are not carried out twice, you can wrap an IF CURRENT REMOTE USER IS NULL ... END IF statement around the body of the triggers. This option is available for SQL Anywhere only.

-u

Process only transactions that have been backed up. This option prevents the Message Agent from processing transactions since the latest backup. Using this option, outgoing transactions and confirmation of incoming transactions are not sent until they have been backed up.

This means that only transactions from renamed logs are processed.

-ud

On Unix platforms, you can run the Message Agent as a daemon by supplying the -ud option. If you run the Message Agent as a daemon, you must also supply the -o or -ot option, to log output information.

If you run the Message Agent as a daemon and are using FTP or SMTP message links, you must store the message link parameters in the database, because the Message Agent does not prompt the user for these options when running as a daemon.

For information on message link parameters, see Setting message type control parameters.

-ux

On Solaris and Linux, open the SQL Remote messages window.

When -ux is specified, dbremote must be able to find a usable display. If it cannot find one, for example because the DISPLAY environment variable is not set or because the X window server is not running, dbremote fails to start. On Windows, the SQL Remote messages window appears automatically.

-v

Verbose output. This option displays the SQL statements contained in the messages to the screen and, if the -o or -ot option is used, to a log file.

-w n

Number of worker threads to apply incoming messages (Not Windows Mobile).

The default is zero, which means all messages are applied by the main (and only) thread. A value of 1 (one) would have one thread receiving messages from the message system and one thread applying messages to the database.

The -w option makes it possible to increase the throughput of incoming messages with hardware upgrades. Putting the consolidated database on a device that can perform many concurrent operations (a RAID array with a striped logical drive) will improve throughput of incoming messages. Multiple processors in the computer running the Message Agent could also improve throughput of incoming messages.

The -w option will not improve performance significantly on hardware that cannot perform many concurrent operations.

Incoming messages from a single remote database will never be applied on multiple threads. Messages from a single remote database are always applied serially in the correct order.

-x [ size ]

Rename and restart the transaction log after it has been scanned for outgoing messages. In some circumstances, replicating data to a consolidated database can take the place of backing up remote databases, or renaming the transaction log when the database server is shut down. This option is available for SQL Anywhere only.

If the optional size qualifier is supplied, the transaction log is renamed only if it is larger than the specified size. The allowed size can be specified as n (in bytes), nK, or nM. The default is 0.

directory

The directory in which old transaction logs are held.