Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 10.0.1 » SQL Anywhere Server - Programming » Database Tools Interface » DBTools structures

a_name structure Next Page

a_remote_sql structure


Holds information needed for the dbremote utility using the DBTools library.

Syntax
typedef struct a_remote_sql {
    short               version;
    MSG_CALLBACK        confirmrtn;
    MSG_CALLBACK        errorrtn;
    MSG_CALLBACK        msgrtn;
    MSG_QUEUE_CALLBACK  msgqueuertn;
    char *              connectparms;
    char *              transaction_logs;
    a_bit_field         receive : 1;
    a_bit_field         send : 1;
    a_bit_field         verbose : 1;
    a_bit_field         deleted : 1;
    a_bit_field         apply : 1;
    a_bit_field         batch : 1;
    a_bit_field         more : 1;
    a_bit_field         triggers : 1;
    a_bit_field         debug : 1;
    a_bit_field         rename_log : 1;
    a_bit_field         latest_backup : 1;
    a_bit_field         scan_log : 1;
    a_bit_field         link_debug : 1;
    a_bit_field         full_q_scan : 1;
    a_bit_field         no_user_interaction : 1;
    a_bit_field         _unused1 : 1;

    a_sql_uint32        max_length;
    a_sql_uint32        memory;
    a_sql_uint32        frequency;
    a_sql_uint32        threads;
    a_sql_uint32        operations;
    char *              queueparms;
    char *              locale;
    a_sql_uint32        receive_delay;
    a_sql_uint32        patience_retry;
    MSG_CALLBACK        logrtn;

    a_bit_field         use_hex_offsets : 1;
    a_bit_field         use_relative_offsets : 1;
    a_bit_field         debug_page_offsets : 1;
    a_sql_uint32        debug_dump_size;
    a_sql_uint32        send_delay;
    a_sql_uint32        resend_urgency;


    char *              include_scan_range;
    SET_WINDOW_TITLE_CALLBACK set_window_title_rtn;
    char *              default_window_title;
    MSG_CALLBACK        progress_msg_rtn;
    SET_PROGRESS_CALLBACK progress_index_rtn;
    char **             argv;
    a_sql_uint32        log_size;
    char *              encryption_key;
    char *              log_file_name;
    a_bit_field         truncate_remote_output_file:1;
    char *              remote_output_file_name;
    MSG_CALLBACK        warningrtn;
    char *              mirror_logs;
} a_remote_sql;

Members
Member Description
version DBTools version number.
confirmrtn Pointer to a function that prints the given message and accepts a yes or no response returning TRUE if yes and FALSE if no.
errorrtn Pointer to a function that prints the given error message.
msgrtn Pointer to a function that prints the given informational (non-error) message.
msgqueuertn Pointer to a function that should sleep for the number of milliseconds passed to it. This function is called with 0 when DBRemoteSQL is busy, but wants to allow the upper layer to process messages. This routine should return MSGQ_SLEEP_THROUGH normally, or MSGQ_SHUTDOWN_REQUESTED to stop SQL Remote processing.
connectparms

Parameters needed to connect to the database. Corresponds to the dbremote -c option. They take the form of connection strings, such as the following:

"UID=DBA;PWD=sql;DBF=samples-dir\demo.db"

The database server would be started by the connection string START parameter. For example:

"START=d:\sqlany10\win32\dbeng10.exe"

A full example connection string including the START parameter:

"UID=DBA;PWD=sql;DBF=samples-dir\demo.db;START=d:\sqlany10\win32\dbeng10.exe"

For a list of connection parameters, see Connection parameters.

transaction_logs Pointer to a string naming the directory with offline transaction logs. Corresponds to the transaction_logs_directory argument of dbremote.
receive

If receive is true, messages are received. Corresponds to the dbremote -r option.

If receive and send are both false then both are assumed true. It is recommended to set both to false.

send

If send is true, messages are sent. Corresponds to the dbremote -s option.

If receive and send are both false then both are assumed true. It is recommended to set both to false.

verbose When true, extra information is printed. Corresponds to the dbremote -v option.
deleted Should be set to true. If false, messages are not deleted after they are applied. Corresponds to dbremote -p option.
apply Should be set to true. If false, messages are scanned, but not applied. Corresponds to dbremote -a option.
batch If true, force exit after applying messages and scanning log. Same as at least one user having 'always' send time. If false, allow run mode to be determined by remote users' send times.
more Should be set to true.
triggers Should be set to false in most cases; otherwise, true means DBRemoteSQL replicates trigger actions. Corresponds to the dbremote -t option.
debug Include debugging output if set true.
rename_log If set to true, logs are renamed and restarted.
latest_backup If set to true, only process logs that are backed up. Don't send operations from a live log. Corresponds to the dbremote -u option.
scan_log Reserved; set to false.
link_debug If set to true, debugging is turned on for links.
full_q_scan Reserved; set to false.
no_user_interaction If set to true, no user interaction is requested.
max_length Set to the maximum length (in bytes) a message can have. This affects sending and receiving. The recommended value is 50000. Corresponds to the dbremote -l option.
memory Set to the maximum size (in bytes) of memory buffers to use while building messages to send. The recommended value is at least 2 * 1024 * 1024. Corresponds to the dbremote -m option.
frequency Set the polling frequency for incoming messages. This value should be set to the max( 1, receive_delay/60 ). See receive_delay below.
threads Set the number of worker threads that should be used to apply messages. This value must not exceed 50. Corresponds to the dbremote -w option.
operations This value is used when applying messages. Commits are ignored until DBRemoteSQL has at least this number of operations(inserts, deletes, updates) that are uncommitted. Corresponds to the dbremote -g option.
queueparms Reserved; set to NULL.
locale Reserved; set to NULL.
receive_delay Set this to the time (in seconds) to wait between polls for new incoming messages. The recommended value is 60. Corresponds to the dbremote -rd option.
patience_retry Set this to the number of polls for incoming messages that DBRemoteSQL should wait before assuming that a message it is expecting is lost. For example, if patience_retry is 3 then DBRemoteSQL tries up to three times to receive the missing message. Afterwards, it sends a resend request. The recommended value is 1. Corresponds to the dbremote -rp option.
logrtn Pointer to a function that prints the given message to a log file. These messages do not need to be seen by the user.
use_hex_offsets Set to true if you want log offsets to be shown in hexadecimal notation; otherwise decimal notation will be used.
use_relative_offsets Set to true if you want log offsets to be displayed as relative to the start of the current log file. Set to false if you want log offsets from the beginning of time to be displayed.
debug_page_offsets Reserved; set to false.
debug_dump_size Reserved; set to 0.
send_delay Set the time (in seconds) between scans of the log file for new operations to send. Set to zero to allow DBRemoteSQL to choose a good value based on user send times. Corresponds to the dbremote -sd option.
resend_urgency Set the time (in seconds) that DBRemoteSQL waits after seeing that a user needs a rescan before performing a full scan of the log. Set to zero to allow DBRemoteSQL to choose a good value based on user send times and other information it has collected. Corresponds to the dbremote -ru option.
include_scan_range Reserved; set to NULL.
set_window_title_rtn Pointer to a function that resets the title of the window (Windows only). The title could be "database_name (receiving, scanning, or sending) - default_window_title".
default_window_title A pointer to the default window title string.
progress_msg_rtn Pointer to a function that displays a progress message.
progress_index_rtn Pointer to a function that updates the state of the progress bar. This function takes two unsigned integer arguments index and max. On the first call, the values are the minimum and maximum values (for example, 0, 100). On subsequent calls, the first argument is the current index value (for example, between 0 and 100) and the second argument is always 0.
argv Pointer to a parsed command line (a vector of pointers to strings). If not NULL, then DBRemoteSQL will call a message routine to display each command line argument except those prefixed with -c, -cq, or -ek.
log_size DBRemoteSQL renames and restarts the online transaction log when the size of the online transaction log is greater than this value. Corresponds to the dbremote -x option.
encryption_key Pointer to an encryption key. Corresponds to the dbremote -ek option.
log_file_name Pointer to the name of the DBRemoteSQL output log to which the message callbacks print their output. If send is true, the error log is sent to the consolidated (unless this pointer is NULL).
truncate_remote_output_file Set to true to cause the remote output file to be truncated rather than appended to. See below. Corresponds to the dbremote -rt option.
remote_output_file_name Pointer to the name of the DBRemoteSQL remote output file. Corresponds to the dbremote -ro or -rt option.
warningrtn Pointer to a function that prints the given warning message. If NULL, the errorrtn function is called instead.
mirror_logs Pointer to the name of the directory containing offline mirror transaction logs. Corresponds to the dbremote -ml option.

The dbremote tool sets the following defaults before processing any command-line options:

See also