Sends and applies SQL Remote messages, and maintains the message tracking system to ensure message delivery.
dbremote [ options ] [ directory ]
Reads in options from the specified environment variable or configuration file. If both exist with the same name, the environment variable is used. See 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).
The environment variable can 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 SQL Remote process that starts with a cache size of 4 MB, receives messages only, and connects to a database named field on a database server named myserver. The SET statement should be entered all on one line:
The configuration file contains line breaks, and can contain any set of options. For example, the following command file holds a set of options for a SQL Remote Message Agent that starts with a cache size of 4 MB, sends messages only, and connects to a database named field on a database server named myserver:
If this configuration file is saved as c:\config.txt, it can be used in a command as follows:
|-a||Processes 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||Runs in batch mode. In this mode, the SQL Remote Message Agent processes incoming messages, scans the transaction log once, processes outgoing messages, and then stops.|
|-c "keyword=value; ..."||
Specifies connection parameters. If this option is not specified, the environment variable SQLCONNECT is used.
For example, the following statement runs dbremote on a database file located at c:\mydata.db, connecting with user ID DBA and password sql:
The SQL Remote Message Agent must be run by a user with REMOTE DBA authority or DBA authority. See REMOTE DBA authority.
The SQL Remote Message Agent supports the full range of SQL Anywhere connection parameters. See Connection parameters.
|-dl||Displays messages in the SQL Remote Message Agent window or at a command prompt and in the log file if specified.|
|-ek key||Specifies that you want to be prompted at a command prompt for the encryption key for strongly encrypted databases. 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 fails if you do not specify a key for a strongly encrypted database.|
|-ep||Specifies 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 fails if you do not specify a key for a strongly encrypted database.|
|-g n||Instructs the SQL Remote Message Agent to group transactions containing fewer 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 fewer commits. However, it can also cause deadlock and blocking by increasing the size of transactions.|
Specifies the maximum length of each message to be sent. The size is the amount of memory, in bytes. Use k, m, or g to specify units of kilobytes, megabytes, or gigabytes, respectively. Longer transactions are split into more than one message. The default is 50000 bytes and the minimum length is 10000 bytes.
The maximum message length must be the same at all sites in an installation.
For platforms with restricted memory allocation, the value must be less than the maximum memory allocation of the operating system.
Specifies a maximum amount of memory to be used by the SQL Remote Message Agent for building messages and caching incoming messages. The size is the amount of memory, in bytes. Use k, m, or g to specify units of kilobytes, megabytes, or gigabytes, respectively. The default is 2048 kilobytes (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 SQL Remote Message Agent until they are applied. This caching of messages prevents rereading 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 deleted in a least-recently used fashion.
Specifies the location of offline transaction log mirror files. This option makes it possible for dbremote to delete old transaction log mirror files when either of the following two circumstances occur:
In a typical setup, the active transaction log mirror and renamed transaction log mirrors are located in the same directory, and dbremote is run on the same computer as the remote database, so this option is not required and old transaction log mirror files are automatically deleted. Transaction logs in this directory are only affected if the delete_old_logs database option is set to a value other than Off. See delete_old_logs option [SQL Remote].
|-o file||Prints messages to an output log file. The default is to print output to the screen.|
Specifies the maximum file size for logging output messages. The size is the amount of memory, in bytes. Use k, m, or g to specify units of kilobytes, megabytes, or gigabytes, respectively. By default, there is no limit, and the minimum limit is 10000 bytes.
Before SQL Remote logs output messages to an output log 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.dbs, where xx is a number that starts at 00 and continues incrementing (note that xx may be more than 2 digits long), and yymmdd represents the current year, month, and date.
If the SQL Remote Message Agent is running in continuous mode for a long time, this option allows you to manually delete old output log files and free up disk space.
|-ot file||Truncates the output log file and then appends output messages to it. The default is to send output to the screen.|
|-p||Does not purge messages.|
|-q||Starts the SQL Remote Message Agent with a minimized window. This option applies to Windows operating systems only.|
|-qc||Closes SQL Remote window on completion.|
Receives messages. If neither -r or -s is specified, the SQL Remote Message Agent executes both phases. Otherwise, only the indicated phases are executed.
The SQL Remote Message Agent runs in continuous mode if it is started with the -r option. To have the SQL Remote Message Agent shut down after receiving messages, use the -b option in addition to -r.
Specifies the polling frequency for incoming messages. By default, the SQL Remote 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, the following command polls every thirty seconds.
The -rd option is often used in conjunction with the -rp option that sets the number of polls for which the SQL Remote Message Agent waits before requesting that a missing message be re-sent.
Logs 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.
Specifies the number of receive polls before a message is assumed lost. When running in continuous mode, the SQL Remote Message Agent polls at certain intervals for messages. After polling a set number of times (by default, one), if a message is missing, the SQL Remote Message Agent assumes it has been lost and requests that the message be re-sent. On slow message systems, this behavior can result in many unnecessary resend requests. You can set the number of polls before a resend request is issued using this option to minimize the number of resend requests.
For more information about configuring this option, see Performance when receiving messages.
The -rp option is often used in conjunction with the -rd option that sets the polling frequency for incoming messages.
|-rt filename||Truncates the output log file on startup, and then appends the log output from the remote database to the file. This option is for use at consolidated sites. It is identical to the -rho option except that the file is truncated on startup.|
Specifies the waiting period to re-scan the log on receipt of a resend.
This option controls the resend urgency. This is the time between detection of a resend request and when the SQL Remote Message Agent starts fulfilling the request. Use this option to help the SQL Remote Message Agent collect resend requests from multiple users before rescanning the log. The time unit can be s (seconds), m (minutes), h (hours), or d (days).
|-s||Sends messages. If neither -r or -s is specified, the SQL Remote Message Agent executes both phases. Otherwise, only the indicated phases are executed.|
Controls the delay between polls of the database transaction log. The -sd option is only used when running in continuous mode.
Controls the send delay that is the time to wait between polls for more transaction log data to send.
Replicates all triggers. If you 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. See Using the CURRENT REMOTE USER special value.
Processes only transactions that exist in offline transaction logs. This option prevents the SQL Remote Message Agent from processing transactions since the latest backup. Using this option, outgoing transactions and confirmation of incoming transactions are not sent until they exist in offline transaction logs.
This means that only transactions from renamed logs are processed.
Runs the SQL Remote Message Agent as a daemon on Unix platforms. If you run the SQL Remote Message Agent as a daemon, you must also supply the -o or -ot option to log output information.
If you run the SQL Remote 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 SQL Remote Message Agent does not prompt the user for these options when running as a daemon.
For information about message link parameters, see Setting remote message type control parameters.
When you start the SQL Remote Message Agent as a daemon, its permissions are controlled by the current user's umask setting. It is recommended that you set the umask value before starting the SQL Remote Message Agent to ensure that the it has the appropriate permissions.
|-ui||For Linux with X window server support, starts the SQL Remote Message Agent in shell mode if a usable display is not available.|
Opens the SQL Remote Message Agent window on Solaris and Linux.
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||Displays verbose output. This option displays the SQL statements contained in the messages to the messages window and, if the -o or -ot option is used, to a log file.|
Specifies the number of database worker threads to apply incoming messages. This option is not supported on 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 maximum number of database worker threads is 50.
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), can improve throughput of incoming messages. Multiple processors in the computer running the SQL Remote Message Agent could also improve throughput of incoming messages.
The -w option does not improve performance significantly on hardware that cannot perform many concurrent operations.
Incoming messages from a single remote database are never applied on multiple threads. Messages from a single remote database are always applied serially in the correct order.
|-x [ size ]||
Renames and restarts 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.
If the optional size qualifier is supplied, the transaction log is renamed only if it is larger than the specified size. The size is the amount of memory, in bytes. Use k, m, or g to specify units of kilobytes, megabytes, or gigabytes, respectively. The default is 0.
|-y||Overwrites the command file without confirmation. Without specifying this option, you are prompted to confirm the replacement of an existing command file.|
Specifies the directory in which old transaction logs are held.
The optional directory parameter specifies a directory in which old transaction logs are held, so that the SQL Remote Message Agent has access to events from before the current log was started.
You can run the SQL Remote Message Agent from your own application by calling into the DBTools library. For more information, see the file dbrmt.h in the %SQLANY12%\SDK\Include\ directory.
The user ID in the SQL Remote Message Agent command must have either REMOTE DBA or DBA authority.
The SQL Remote Message Agent uses several database connections.
Message system control parameters SQL Remote uses several registry settings to control aspects of message link behavior.
On Windows, the message link control parameters are stored in the registry, at the following location:
\\HKEY_CURRENT_USER \Software \Sybase \SQL Remote
Discuss this page in DocCommentXchange.
|Copyright © 2012, iAnywhere Solutions, Inc. - SQL Anywhere 12.0.1|