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;
    const 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:\sqlany11\bin32\dbeng11.exe"

A full example connection string including the START parameter:

"UID=DBA;PWD=sql;DBF=samples-dir\demo.db;START=d:\sqlany11\bin32\dbeng11.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 that you 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 that you 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.

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:

version = DB_TOOLS_VERSION_NUMBER
argv = (argument vector passed to application)
deleted = TRUE
apply = TRUE
more = TRUE
link_debug = FALSE
max_length = 50000
memory = 2 * 1024 * 1024
frequency = 1
threads = 0
receive_delay = 60
send_delay = 0
log_size = 0
patience_retry = 1
resend_urgency = 0
log_file_name = (set from command line)
truncate_remote_output_file = FALSE
remote_output_file_name = NULL
no_user_interaction = TRUE (if user interface is not available)
errorrtn = (address of an appropriate routine)
msgrtn = (address of an appropriate routine)
confirmrtn = (address of an appropriate routine)
msgqueuertn = (address of an appropriate routine)
logrtn = (address of an appropriate routine)
warningrtn = (address of an appropriate routine)
set_window_title_rtn = (address of an appropriate routine)
progress_msg_rtn = (address of an appropriate routine)
progress_index_rtn = (address of an appropriate routine)