mobilink sql passthrough · the new sql passthrough feature provides the ability for powerful and...
TRANSCRIPT
MobiLink SQL Passthrough A whitepaper from Sybase iAnywhere
Author: Joshua Savill, Product Manager
Date: October 17th, 2008
This whitepaper was written in the context of SQL Anywhere 11.
CONTENTS
Introduction 3 Creating SQL Passthrough Scripts 3 Creating SQL Passthrough Entries for Remote Databases 4 Downloading and Executing SQL Passthrough Scripts 4 Manual Execution of SQL Passthrough Scripts at the Remote Database 4 Automatic Execution of SQL Passthrough Scripts at the Remote Database 5
Capturing and Reviewing Script Results 5 Repairing Script Executions that cause Errors in the Remote Databases 6 Script Administration on the Consolidated Database 6 MobiLink Server Verbosity for SQL Passthrough 6 Deleting a SQL Passthrough Script 7 Deleting a SQL Passthrough Entry 7 Deleting SQL Passthrough Repair Information 7
Demo – Mobilizing Demo Database to an Empty Remote Database 7 Creating the SQL Anywhere Consolidated Database 8 Creating the SQL Anywhere Remote Database 8 Configuring SQL Passthrough in the Consolidated Database 8 Verify Creation of the SQL Passthrough Scripts in the Consolidated Database 11 Synchronizing the Remote Database 12 Verifying the Execution of SQL Passthrough Scripts 14 Steps to Run the Demo 14
Demo – Handling Errors during Execution of SQL Passthrough Scripts 14 Creating the SQL Anywhere Consolidated Database 14 Creating the SQL Anywhere Remote Databases 15 Remote Database 1 15 Remote Database 2 15
Configuring SQL Passthrough in the Consolidated Database 16 Synchronizing the Remote Databases 16 Configuring SQL Passthrough Repair Script in the Consolidated Database 18 Steps to Run the Demo 19
Summary 20
FIGURES
Figure 1 – SQL Passthrough Script in the ml_passthrough_script Table....................................... 12 Figure 2 – SQL Passthrough Entries in the ml_passthrough Table............................................... 12 Figure 3 - SQL Passthrough Status on the Remote Database ..................................................... 13 Figure 4 – SQL Passthrough Scripts on the Remote Database .................................................... 13 Figure 5 – SQL Passthrough Progress on the Remote Database ................................................. 13 Figure 6 – SQL Passthrough Script Results ............................................................................... 14 Figure 7 – MobiLink Client Failure due to Failed Script Execution ................................................ 17 Figure 8 – SQL Passthrough Status in Remote Database 1......................................................... 17 Figure 9 – SQL Passthrough Status in the Consolidated Database .............................................. 17 Figure 10 – SQL Passthrough Status in Remote Database 1 after Execution of Repair Script ......... 19 Figure 11 – SQL Passthrough Status in Consolidated Database after Execution of Repair Script .... 19
www.sybase.com/ianywhere 3
INTRODUCTION
The new SQL Passthrough feature provides the ability for powerful and robust administration of the
remote databases in a MobiLink synchronization environment. SQL Passthrough gives administrators
the ability to download scripts of SQL statements from a consolidated database to one or more remote
databases, and have those SQL statements execute on the remotes at an appropriate time. Scripts are
guaranteed to be executed on the remotes in a predefined order that is specified at script creation time.
Provided with the SQL Passthrough feature is the ability to monitor the status of script execution
and repair scripts that failed to execute on the remote databases.
CREATING SQL PASSTHROUGH SCRIPTS
SQL Passthrough scripts are created in the consolidated database and downloaded to the remote
databases during synchronization. New SQL Passthrough scripts are created using the
ml_add_passthrough_script procedure and stored in the ml_passthrough_script table in the
consolidated database.
When calling the ml_add_passthrough_script procedure the following parameters must be provided:
script name, flags, affected publications, script content, and description. The script name parameter is
used to identify the SQL Passthrough script. This script name must be non-NULL and unique. The flags
parameter indicates how the SQL Passthrough script is executed on the remote database. The flag can
be one or a combination of the options: manual, exclusive, and schema_diff.
The options have the following meanings:
Manual – indicates the script may only run with manual execution on the remote
database. By default, all scripts execute automatically unless manual is specified.
Exclusive – indicates the script may only run automatically at the end of a synchronization
if exclusive locks are obtained on all tables involved in the synchronization. This option only
applies to SQL Anywhere remote databases and requires an affected publication to be defined.
Schema_diff – indicates the script will run in schema-diffing mode. In schema-diffing
mode, the database schema is altered to match the schema described in the script. For
example, a create statement for an existing table is treated as an alter statement. This only
applies to scripts run on UltraLite databases.
More than one flag option can be specified using a semicolon-separated string. For example
‘manual;exclusive’. The default flag when NULL is specified is equivalent to an empty string, thereby
implying automatic execution.
The affected publications parameter is a comma-separated list of publications that must have no
operations to upload before the script is executed. The script is only executed automatically at the end
of synchronization when all the publications in the affected publications list are synchronized. When the
script contains alter table statements, all publications that contain the tables being altered should be
included in the affected publications, except for download-only publications. This ensures that these
publications have no operations waiting to be uploaded when the tables are altered. Failing to do this
can result in the remote database being unable to synchronize after the script is applied. The affected
publications list can be NULL, meaning no publications need to be synchronized before the script is
executed. The affected publications list is ignore by UltraLite remotes.
The script content parameter is a collection of SQL statements that are to be executed at the
remote database. The script content supplied for the SQL Passthrough script cannot be NULL. The
script content is limited to the size of a TEXT data type for SQL Anywhere and Microsoft SQL Server
consolidated databases. For ASE the script content is limited to a VARCHAR data type of 16384. For
www.sybase.com/ianywhere 4
IBM DB2 UDB the script content is limited to a VARCHAR data type of 4000 and for Oracle the script
content is limited to the size of a CLOB.
With SQL Anywhere remotes, the script content must have proper syntax that would apply for any
SQL statement that would normally exist in a BEGIN END block. For UltraLite remotes, the SQL
statements must be separated by the word ‘go’ and each statement must appear on an individual line.
The description parameter provides the ability to add additional textual information regarding the
SQL Passthrough script. The description can be NULL.
CREATING SQL PASSTHROUGH ENTRIES FOR REMOTE DATABASES
When a SQL Passthrough script is created in the consolidated database there needs to be an
association with a remote database to which the script will be downloaded. The ml_add_passthrough
procedure is used to define which remote database or databases will download a given script. This
passthrough association is stored in the ml_passthrough table on the consolidated database.
When calling the ml_add_passthrough procedure the following parameters must be provided:
remote ID, script name, and run order.
The remote ID parameter specifies the remote database that is to receive the script. The remote ID
must match an existing remote ID in the ml_database table. If NULL is supplied for the remote ID, the
script will be applied to all remotes that exist in the ml_database table.
The script name parameter specifies the script to download to the remote database. The script
name must be valid and exist in the ml_passthrough_script table.
The run order parameter determines the order in which to apply the scripts at the remote database.
Scripts are always applied in order by the run order. The run order must be a non-negative integer. The
run order is automatically determined by the following operations if NULL is provided:
1. If remote ID is null, the value is the maximum value of the run order column in the
ml_passthrough table plus 10.
2. If remote ID is not null, the run order is the maximum value of the run order column for
the given remote ID in the ml_passthrough table plus 10.
If a row in the ml_passthrough table already exists for a given remote ID and run order, the
ml_add_passthrough procedure updates the row in the ml_passthrough table with the given script
name.
DOWNLOADING AND EXECUTING SQL PASSTHROUGH SCRIPTS
SQL Passthrough scripts are automatically downloaded to the remote database during
synchronization if the criteria defined in the ml_passthrough table are met by the remote database.
Scripts are not downloaded during file-based synchronization, when a ping from the remote is
performed on the MobiLink Server, or when a download has been automatically restarted.
With SQL Anywhere remote databases, the SQL Passthrough scripts are stored in the
dbo.sync_passthrough_script table. For UltraLite remotes, scripts are stored in the syssql table.
SQL Passthrough scripts can either be executed automatically or manually based on the definition of
the script. All script executions are based on run order. For SQL Anywhere remote databases, all scripts
are executed with DBA authority under the DBO account. This means the database object owner must
be specified when referencing, creating or altering database objects. For example, DBA.t1 must be
specified instead of just t1.
MANUAL EXECUTION OF SQL PASSTHROUGH SCRIPTS AT THE REMOTE DATABASE
SQL Passthrough scripts can be manually executed using the sync_get_next_passthrough_script
and sync_execute_next_passthrough_script functions.
www.sybase.com/ianywhere 5
The sync_get_next_passthrough_script function returns the run order of the next script to be
executed, or NULL if there are no further scripts to be executed. NULL is also be generated if an error
occurred during the execution of the last script and no instructions on how to proceed with the error
have been received from the consolidated database.
The sync_execute_next_passthrough_script function executes the next script and updates the
progress status information in the remote database that is to be uploaded to the consolidated database
on the next synchronization. No script is executed if the last script returned an error and no instructions
on how to proceed with the error have been received from the consolidated database. If a script is
executed, the run order of the script is returned. If no script is executed, NULL is returned.
For UltraLite remotes, ESQL API methods, C++ methods, .NET methods, and Pod interfaces are
available for manual execution of SQL Passthrough scripts.
AUTOMATIC EXECUTION OF SQL PASSTHROUGH SCRIPTS AT THE REMOTE DATABASE
With SQL Anywhere remote databases, automatic execution of SQL Passthrough scripts is
attempted at the end of each synchronization. The available scripts are ordered by run order and
execute individually until all scripts have executed, a script fails, or a script is reached that cannot be
executed automatically.
A script cannot be automatically executed if any of the following are true:
1. The manual flag is specified for the script.
2. The script has an affected publications value set and
a. No upload was performed, or b. The upload failed, or
c. One or more publications in the affected publications list were not synchronized, or
d. Adequate table locks are not obtained to allow the script to execute. At the beginning of a synchronization, the MobiLink client may choose to obtain locks on the
synchronizing tables that are more restrictive than those requested using the LockTables
extended option in order to ensure that scripts can be executed at the end of the
synchronization. For example, if LockTables is set to shared but the next script available for
execution requires exclusive locks, then exclusive locks may be obtained.
For UltraLite remotes, scripts that are set to run automatically run the next time the database is
started. This can be prevented by setting the dont_run_scripts option in the UltraLite database.
CAPTURING AND REVIEWING SCRIPT RESULTS
For SQL Anywhere remote databases, the results of executed SQL Passthrough scripts are stored in
the dbo.sync_passthrough_status table. The results provide the time at the remote database when the
script was executed and an indication of success or the reported error. If an error is reported during
execution of the script, the SQL code is stored with the text of the message.
For UltraLite remotes, results are stored in the syssql table. The results provide the time at the
remote database when the script was executed and an indication of success or the reported error. If an
error is reported during execution of the script, the SQL code, line number in the script that failed, and
the list of error parameters is provided.
All remote databases upload the results of any scripts that have executed as part of each
synchronization session. The MobiLink Server stores the uploaded results in the ml_passthrough_status
table in the consolidated database. This table can be monitored to determine the success of all SQL
Passthrough scripts that are distributed in the MobiLink synchronization environment.
www.sybase.com/ianywhere 6
REPAIRING SCRIPT EXECUTIONS THAT CAUSE ERRORS IN THE REMOTE
DATABASES
SQL Passthrough script execution status is stored in the ml_passthrough_status table. If any errors
occur during script execution, manual intervention is required to resolve the error. Any remote
experiencing a script execution error will not be able to execute any script until intervention is
complete.
Failure of a SQL Passthrough script can be repaired using the ml_add_passthrough_repair
procedure. The ml_add_passthrough_repair procedure is used to define actions to take when a specific
error code is encounter during execution of a specific script. SQL Passthrough repair information is
stored in the ml_passthrough_repair table. The SQL Passthrough scripts used to repair errors in the
remote database are stored in the ml_passthrough_script table.
When calling the ml_add_passthrough_repair procedure, the following parameters must be
provided: failed script name, error code, new script name, and action.
When a remote database reports a failed script name and error code, the script name and error
code are compared to entries stored in the ml_passthrough_repair table during the next
synchronization session. If the failed script name and error code reported by the remote database
matches an entry in the ml_passthrough_repair table, then the action and new script name values in
the table determine how the remote should handle the error.
The action can be defined as one of the following:
R – (Replace) indicates the failed script should be replaced with the new script specified by
the new script name parameter. The new script will be run on the remote database. The failed
script can be rerun by setting the new script name to be the same as the failed script name.
P – (Purge) indicates the remote database should discard all scripts that it has received
and continue executing scripts normally after the purge of all scripts is complete.
S – (Skip) indicates the remote database should ignore the error and continue executing
scripts as if the failed script succeeded.
H – (Halt) indicates the remote database should not execute any more scripts until it
receives further instructions.
The new script name must be a NULL value, unless the action is R. If R is the action, then a new
script name must be provided and the script must already exist in the ml_passthrough_script table.
Actions generated by the ml_passthrough_repair table are downloaded to the remote during the
synchronization session where it uploads the error, or in a subsequent synchronization session.
SCRIPT ADMINISTRATION ON THE CONSOLIDATED DATABASE
SQL Passthrough offers additional features and functionality for the management and execution of
scripts. These features and functionality are listed below.
MOBILINK SERVER VERBOSITY FOR SQL PASSTHROUGH
The MobiLink Server can be enabled to provide verbose logging to the console window, or direct to
output using the –o option, by setting the following command line option when the MobiLink Server is
started:
mlsrv11 -sl java ( -DMLVerbosePassthrough=1 ) …
This option negatively impacts the performance of the MobiLink Server and should not be used in a
production environment.
www.sybase.com/ianywhere 7
DELETING A SQL PASSTHROUGH SCRIPT
The ml_delete_passthrough_script procedure removes a SQL Passthrough script from the
ml_passthrough_script table.
When calling the ml_delete_passthrough_script procedure the script name parameter must be
provided. The script name parameter identifies the script to be removed from the
ml_passthrough_script table. The script is removed if and only if it is not referenced by any rows in the
ml_passthrough table or ml_passthrough_repair table.
DELETING A SQL PASSTHROUGH ENTRY
The ml_delete_passthrough procedure removes a SQL Passthrough entry from the ml_passthrough
table. When calling the ml_delete_passthrough procedure, the following parameters must be provided:
remote ID, script name, and run order.
The remote ID specifies which remote to remove the ml_passthrough entries from. If the remote ID
is NULL, all entries for the script name are removed from the ml_passthrough table.
The script name specifies which script will be removed from the ml_passthrough table. The script
name provided must not be NULL.
If the run order is NULL, then all rows in the ml_passthrough table are removed for the
corresponding remote ID and script name, regardless of the run order.
Removing the ml_passthrough entry for a script does not remove it from any remote database that
has already received it. Remotes that have already received the script will execute it regardless of
whether the ml_passthrough entry has been removed.
DELETING SQL PASSTHROUGH REPAIR INFORMATION
The ml_delete_passthrough_repair procedure removes SQL Passthrough repair information from the
ml_passthrough_repair table. When calling the ml_delete_passthrough_repair procedure the following
parameters must be provided: failed script name, and error code.
The failed script name is removed from the ml_passthrough_repair table and cannot be NULL. If the
error code is NULL, then all rows in the ml_passthrough_repair table are removed for the corresponding
failed script name.
DEMO – MOBILIZING DEMO DATABASE TO AN EMPTY REMOTE DATABASE
This demonstration of SQL Passthrough makes use of the demo database provided with SQL
Anywhere 11. The demonstration creates a new version of the demo database, to be used as the
consolidated database, by calling the mkdemo.sql file stored in the %SQLANY11%\Scripts directory of
the SQL Anywhere 11 installation.
The remote database is created as a shell with a single Temp_Table table used for the purpose of
synchronization. Publication pub1 contains table Temp_Table and MobiLink user rem100 is subscribed
to publication pub1. During the first synchronization, SQL Passthrough scripts are downloaded to the
remote database. The scripts are executed automatically to set up synchronization of 4 tables of the
demo database: GROUPO.Customers, GROUPO.Products, GROUPO.SalesOrderItems, and
GROUPO.SalesOrders. These 4 tables are created in the remote database, with the appropriate users
and domain definitions. A new publication pub2 is created containing these 4 tables and a subscription
is created for user rem100 to pub2.
MobiLink synchronization is configured for the 4 tables listed above in the consolidated database.
The 4 tables are modified to add a last_modified column of default current timestamp for timestamp
based synchronization. Each table has a download_cursor, download_delete_cursor, upload_insert,
www.sybase.com/ianywhere 8
upload_update, and upload_delete table synchronization scripts. For simplicity, there is no conflict
resolution defined in the synchronization scripts.
During the first synchronization of publication pub2, a SQL Passthrough script is executed to clean
up the shell Temp_Table table and all the publication pub1 definitions. This leaves only publication
pub2 in the remote database and deploys a fully functional synchronizing system.
All files for the demo can be found on the Sybase iAnywhere website here:
http://www.sybase.com/detail?id=1060044
CREATING THE SQL ANYWHERE CONSOLIDATED DATABASE
The SQL Anywhere consolidated database is created by executing the setup.bat file found in the
\SQLPassThrough_EmptyRemote\cons directory. Executing the setup.bat file will:
� Initialize the SQL Anywhere consolidated database demo.db. � Create a user DSN demo_cons with connection parameters for the demo database. � Start the demo database on a database server.
� Execute the syncsa.sql script against the demo database. � Execute the mkdemo.sql script against the demo database. � Read the consolidated database schema into the demo database. The consolidated
database schema is located in cons_schema.sql and modify_cons_schema.sql files found in the \SQLPassThrough_EmptyRemote\cons directory.
� Start the MobiLink Server and connect it to the consolidated database. The mkdemo.sql script is located in the %SQLANY11%\Scripts directory and contains a majority of
the consolidated database schema. The cons_schema.sql and modify_cons_schema.sql scripts contain
modifications and additions to the demo database schema required for MobiLink synchronization of the
shell database.
The SQL Anywhere consolidated database needs to be configured for synchronization of the 4
tables: GROUPO.Customers, GROUPO.Products, GROUPO.SalesOrderItems, and GROUPO.SalesOrders.
This requires an addition of a last_modified column to each table, creation of shadow tables to handle
deleted rows in the consolidated database and creation of various table scripts to handle uploads and
downloads. The modify_cons_schema.sql script performs these functions.
CREATING THE SQL ANYWHERE REMOTE DATABASE
The SQL Anywhere remote database is created by executing the setup.bat file found in the
\SQLPassThrough_EmptyRemote\rem directory. Executing the setup.bat file will:
� Initialize the SQL Anywhere remote database MLrem.db. � Create a user DSN demo_rem with connection parameters for the MLrem database. � Start the MLrem database on a database server. � Execute the rem_schema.sql file found in the \SQLPassThrough_EmptyRemote\rem
directory to create the remote database schema in the MLrem database. � Start the MobiLink client to complete an initial synchronization with the MobiLink Server.
The rem_schema.sql script contains the necessary information to create the shell database and
configure MobiLink synchronization. The first synchronization uses SQL Passthrough to configure
MobiLink synchronization for the demo database.
The initial synchronization performed here adds the remote database information to the
ml_database table in the consolidated database. This is necessary before SQL Passthrough scripts can
be created and scheduled for execution on this remote.
CONFIGURING SQL PASSTHROUGH IN THE CONSOLIDATED DATABASE
The SQL Passthrough file defines 5 SQL Passthrough scripts: create_users_and_domains,
create_tables_and_schema, create_data_publication, create_data_subscription, and
clean_up_remote_schema. The SQL Passthrough scripts are created by calling the
ml_add_passthrough_script procedure.
www.sybase.com/ianywhere 9
The first 4 SQL Passthrough scripts configure the remote database users, create the remote
database tables, create publication pub2, and create the synchronization subscription. The affected
publications list for the first 4 SQL Passthrough scripts is NULL, meaning no publication needs to be
synchronized before the scripts will execute. The SQL Passthrough scripts are defined as follows:
/*--------------------------------------------------------
* Setup Passthrough Scripts
*-------------------------------------------------------*/
CALL ml_add_passthrough_script (
'create_users_and_domains',
null,
null,
'
// %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
// Create groups, user IDs and grant user permissions
// %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
GRANT CONNECT, GROUP, RESOURCE TO "GROUPO";
…
',
'
This creates the users and the domains for the remote database schema
'
);
CALL ml_add_passthrough_script (
'create_tables_and_schema',
null,
null,
'
// %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
// Create tables and grant permissions
// %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
CREATE TABLE GROUPO.Customers
(
ID integer NOT NULL default autoincrement,
Surname person_name_t NOT NULL,
GivenName person_name_t NOT NULL,
Street street_t NOT NULL,
City city_t NOT NULL,
State state_t NULL,
Country country_t NULL,
PostalCode postal_code_t NULL,
Phone phone_number_t NOT NULL,
CompanyName company_name_t NULL,
CONSTRAINT CustomersKey PRIMARY KEY (ID)
);
…
',
'
This creates the tables on the remote database
www.sybase.com/ianywhere 10
'
);
CALL ml_add_passthrough_script (
'create_data_publication',
null,
null,
'
CREATE PUBLICATION GROUPO.pub2 (
TABLE GROUPO.Customers,
TABLE GROUPO.SalesOrders,
TABLE GROUPO.SalesOrderItems,
TABLE GROUPO.Products);
',
'
This is to create publication pub2 with the 4 tables to be
synchronized
'
);
CALL ml_add_passthrough_script (
'create_data_subscription',
null,
null,
'
CREATE SYNCHRONIZATION SUBSCRIPTION TO GROUPO.pub2 FOR rem100
OPTIONS ScriptVersion=''demo_v2'';
',
'
This is to create synchronization subscription to pub2 for the remote
user
'
);
The last SQL Passthrough script cleans up the shell database by removing the Temp_Table table
and publication pub1. After this script has executed, the only remaining publication will be pub2, and
MobiLink synchronization will be configured in the remote database. The affected publications list for
the last SQL Passthrough script contains pub2. This SQL Passthrough script only executes when
publication pub2 is synchronized. The SQL Passthrough script is defined as follows:
CALL ml_add_passthrough_script (
'clean_up_remote_schema',
null,
'pub2',
'
DROP SYNCHRONIZATION SUBSCRIPTION TO DBA.pub1 FOR rem100;
DROP PUBLICATION DBA.pub1;
DROP TABLE DBA.Temp_Table;
',
'
This cleans up the initial database schema in the remote
'
www.sybase.com/ianywhere 11
);
The ml_add_passthrough procedure is used to associate a SQL Passthrough script with a remote
database where it will be downloaded and executed. All 5 SQL Passthrough scripts are designed to be
executed on all of the remote databases and are associated as follows:
/*--------------------------------------------------------
* Add the Passthrough Scripts
*-------------------------------------------------------*/
CALL ml_add_passthrough (
null,
'create_users_and_domains',
10
);
CALL ml_add_passthrough (
null,
'create_tables_and_schema',
20
);
CALL ml_add_passthrough (
null,
'create_data_publication',
30
);
CALL ml_add_passthrough (
null,
'create_data_subscription',
40
);
CALL ml_add_passthrough (
null,
'clean_up_remote_schema',
50
);
This is configured by executing the passthrough.bat file located in the
\SQLPassThrough_EmptyRemote\cons directory.
To improve performance, the MobiLink Server does not enable SQL Passthrough handling until a
script is first added to the ml_passthrough_script table. The MobiLink Server queries this table at
regular intervals waiting for a script to be added. When the following message appears in the MobiLink
console window, the SQL Passthrough scripts have been read by the MobiLink Server and are ready to
download to the remote databases:
I. 2008-03-05 15:26:01. <Main> Server passthrough support has been
enabled.
VERIFY CREATION OF THE SQL PASSTHROUGH SCRIPTS IN THE CONSOLIDATED
DATABASE
In the SQL Anywhere consolidated database, SQL Passthrough scripts can be viewed in the
ml_passthrough_script table. Here is the ml_passthrough_script table in Interactive SQL:
www.sybase.com/ianywhere 12
Figure 1 – SQL Passthrough Script in the ml_passthrough_script Table
The SQL Passthrough entries can be viewed in the ml_passthrough table. Here is the
ml_passthrough table in Interactive SQL:
Figure 2 – SQL Passthrough Entries in the ml_passthrough Table
SYNCHRONIZING THE REMOTE DATABASE
With SQL Passthrough configured in the consolidated database, the remote database needs to be
synchronized to download and execute the scripts. To synchronize the remote database, run the
sync_pub1.bat file located in the \SQLPassThrough_EmptyRemote\rem directory. During this
synchronization all SQL Passthrough scripts with NULL affected publications lists
(create_users_and_domains, create_tables_and_schema, create_data_publication, and
create_data_subscription) are executed on the remote database.
After the execution of the SQL Passthrough script with NULL affected publications lists, a new
publication pub2 exists in the remote database. The status of the execution of the SQL Passthrough
scripts can be determined by viewing the dbo.sync_passthrough_status table on the remote database.
This information is synchronized back to the consolidated database during the next synchronization.
www.sybase.com/ianywhere 13
Figure 3 - SQL Passthrough Status on the Remote Database
The dbo.sync_passthrough_script table contains the scripts that were executed on the remote
database. The dbo.sync_passthrough_progress table contains the run order of the last script
successfully executed, the run order of the last script attempted, and the time (at the consolidated
database) when scripts were last downloaded.
Figure 4 – SQL Passthrough Scripts on the Remote Database
Figure 5 – SQL Passthrough Progress on the Remote Database
After the first synchronization of publication pub2, the final SQL Passthrough script
clean_up_remote_schema is executed against the remote database. To synchronize the remote
database using publication pub2, run the sync_pub2.bat file located in the
\SQLPassThrough_EmptyRemote\rem directory. This cleans up the entire schema regarding publication
pub1 and removes it, leaving only publication pub2 in the remote database.
www.sybase.com/ianywhere 14
VERIFYING THE EXECUTION OF SQL PASSTHROUGH SCRIPTS
Another synchronization of publication pub2 by executing sync_pub2.bat uploads all of the SQL
Passthrough results to the consolidated database. The ml_passthrough_status table on the consolidated
database reports the status of all SQL Passthrough scripts that were executed and on which remotes
the execution occurred.
Figure 6 – SQL Passthrough Script Results
If an error occurs in the execution of a SQL Passthrough script, the script_status and error_code are
provided in the ml_passthrough_status table.
STEPS TO RUN THE DEMO
The following steps run the demo using the provided batch files:
1. \SQLPassThrough_EmptyRemote\cons\setup.bat 2. \SQLPassThrough_EmptyRemote\rem\setup.bat 3. \SQLPassThrough_EmptyRemote\cons\passthrough.bat
Wait for the following message to appear in the MobiLink console window to indicate the
SQL Passthrough scripts have been read by the MobiLink Server:
I. 2008-03-05 15:26:01. <Main> Server passthrough support has been
enabled.
4. \SQLPassThrough_EmptyRemote\rem\sync_pub1.bat 5. \SQLPassThrough_EmptyRemote\rem\sync_pub2.bat 6. \SQLPassThrough_EmptyRemote\rem\sync_pub2.bat
DEMO – HANDLING ERRORS DURING EXECUTION OF SQL PASSTHROUGH
SCRIPTS
This demonstration of SQL Passthrough makes use of two remote databases and a consolidated
database with a simple schema definition. The demonstration shows how to use the SQL Passthrough
repair functionality to correct a failed execution of a script at a remote database. The SQL Passthrough
script executes a create view statement on the two remote databases; however one of the databases
already has a view defined with the same name. The SQL Passthrough repair functionality is used to
alter the view on the remote database that already has the view defined.
All files for the demo can be found here: http://www.sybase.com/detail?id=1060044
CREATING THE SQL ANYWHERE CONSOLIDATED DATABASE
The SQL Anywhere consolidated database is created by executing the setup.bat file found in the
\SQLPassThrough_View_Error\cons directory. Executing the setup.bat file will:
� Initialize a SQL Anywhere consolidated database MLcons.db.
www.sybase.com/ianywhere 15
� Create a user DSN viewerror_cons with connection parameters for the MLcons database. � Start the MLcons database on a database server. � Execute the syncsa.sql script against the demo database. � Read the consolidated database schema into the MLcons database. The consolidated
database schema is located in cons_schema.sql file found in the \SQLPassThrough_View_Error\cons directory.
� Insert test data into the MLcons database. � Start the MobiLink Server and connect it to the consolidated database.
The con_schema.sql script creates two tables, Table1 and Table2, and all the necessary
synchronization scripts for MobiLink synchronization.
CREATING THE SQL ANYWHERE REMOTE DATABASES
This demonstration uses two remote databases, MLrem.db and MLrem2.db each containing two
tables, Table1 and Table2.
REMOTE DATABASE 1
Remote database 1 is created using the setup.bat file located in the
\SQLPassThrough_View_Error\rem directory. The setup.bat file will:
� Initialize the SQL Anywhere remote database MLrem.db. � Create a user DSN viewerror_rem with connection parameters for the MLrem database. � Start the MLrem database on a database server. � Read the remote database schema into the MLrem database. The remote database
schema is located in rem_schema.sql file found in the \SQLPassThrough_View_Error\rem directory.
The rem_schema.sql creates a view between Table1 and Table2 with the following syntax:
CREATE VIEW DBA.v_TableData
AS SELECT Table1.Table1_id Table1ID, Table2.Table2_id Table2ID
FROM DBA.Table1, DBA.Table2
WHERE Table1.Table1_id = Table2.Table2_id;
� Insert test data into the MLrem database. � Start the MobiLink client to complete an initial synchronization with the MobiLink Server.
The view is created in remote database 1 for the purpose of demonstrating the SQL Passthrough
repair functionality.
REMOTE DATABASE 2
Remote database 2 is created using the setup.bat file located in the
\SQLPassThrough_View_Error\rem2 directory. The setup.bat file will:
� Initialize the SQL Anywhere remote database MLrem2.db. � Create a user DSN viewerror_rem2 with connection parameters for the MLrem2 database. � Start the MLrem2 database on a database server. � Read the remote database schema into the MLrem2 database. The remote database
schema is located in rem2_schema.sql file found in the \SQLPassThrough_View_Error\rem2 directory.
� Insert test data into the MLrem2 database. � Start the MobiLink client to complete an initial synchronization with the MobiLink Server.
There is no view created in remote database 2. The view is created by SQL Passthrough scripts.
The initial synchronization of both remote databases stores information in the ml_database table in
the consolidated database about the remotes. This is necessary before SQL Passthrough scripts can be
created and scheduled for execution on the remotes.
www.sybase.com/ianywhere 16
CONFIGURING SQL PASSTHROUGH IN THE CONSOLIDATED DATABASE
The SQL Passthrough script can be created by executing the passthrough.bat script located in the
\SQLPassThrough_View_Error\cons directory. The passthrough.bat file executes the passthrough.sql
script. SQL Passthrough is defined as follows:
/*--------------------------------------------------------
* Setup Passthrough Scripts
*-------------------------------------------------------*/
CALL ml_add_passthrough_script (
'create_view',
'automatic',
'pub1',
'
CREATE VIEW DBA.v_TableData
AS SELECT Table1.Table1_id TableID, Table1.Data Data1,
Table2.Data Data2
FROM DBA.Table1, DBA.Table2
WHERE Table1.Table1_id = Table2.Table2_id;
',
'
Create a view TableData on the remote databases
'
);
COMMIT;
/*--------------------------------------------------------
* Add the Passthrough Scripts
*-------------------------------------------------------*/
CALL ml_add_passthrough (
null,
'create_view',
10
);
COMMIT;
SYNCHRONIZING THE REMOTE DATABASES
The remote databases can be synchronized by executing the sync.bat file located in the appropriate
directory for the remote database.
When the SQL Passthrough script fails to execute on remote database 1, database synchronization
also fails. However, future synchronization will be successful (is this correct, or should it say “will NOT
be successful?) without any SQL Passthrough scripts executing for remote database 1 until manual
intervention occurs to resolve the script error.
The synchronization failure of remote database 1 will look as follows:
www.sybase.com/ianywhere 17
Figure 7 – MobiLink Client Failure due to Failed Script Execution
After the SQL Passthrough script has executed on remote database 1 the
dbo.sync_passthrough_status table is updated to show the status of the execution:
Figure 8 – SQL Passthrough Status in Remote Database 1
The next synchronization of each remote database will upload the results of the SQL Passthrough
status to the consolidated database. This information is stored in the ml_passthrough_status MobiLink
table:
Figure 9 – SQL Passthrough Status in the Consolidated Database
At this time, no SQL Passthrough scripts can execute on remote database 1 until manual
intervention occurs to resolve the script error.
www.sybase.com/ianywhere 18
CONFIGURING SQL PASSTHROUGH REPAIR SCRIPT IN THE CONSOLIDATED DATABASE
The failed execution of the SQL Passthrough script on remote database 1 requires manual
intervention before further scripts can be executed. To resolve the script error, a SQL Passthrough
repair script will be created and executed on remote database 1. The other option is to ignore the error,
but this demonstration will repair the script.
In figure 2 the error_code and error_text in the ml_passthrough_status table show the error as
follows:
-110
Item 'v_TableData' already exists
This error occurs because the view v_TableData already exists in remote database 1. The easiest
way to resolve this SQL Passthrough error is to create a new script that will alter the view to the
desired outcome.
The new SQL Passthrough script is defined as follows:
/*--------------------------------------------------------
* Setup Passthrough Repair Scripts
*-------------------------------------------------------*/
CALL ml_add_passthrough_script (
'alter_view',
'automatic',
'pub1',
'
ALTER VIEW DBA.v_TableData
AS SELECT Table1.Table1_id TableID, Table1.Data Data1,
Table2.Data Data2
FROM DBA.Table1, DBA.Table2
WHERE Table1.Table1_id = Table2.Table2_id;
',
'
Create a view TableData on the remote databases
'
);
COMMIT;
The ml_add_passthrough_repair procedure is then called to instruct the MobiLink Server to
download and execute the alter_view script to any remote that reports receiving an error code of -110
when executing the create_view script. The ml_add_passthrough_repair procedure is called as follows:
/*---------------------------------------------------------
* Add the Passthrough Scripts
*--------------------------------------------------------*/
CALL ml_add_passthrough_repair (
'create_view',
-110,
'alter_view',
'R'
);
COMMIT;
www.sybase.com/ianywhere 19
The next synchronization of remote database 1 causes the alter view script to be downloaded and
executed. After the execution of the script the dbo.sync_passthrough_status table is updated to show
the status of the execution:
Figure 10 – SQL Passthrough Status in Remote Database 1 after Execution of Repair Script
Another synchronization of remote database 1 uploads the results of the SQL Passthrough status to
the consolidated database. This information is stored in the ml_passthrough_status MobiLink table:
Figure 11 – SQL Passthrough Status in Consolidated Database after Execution of Repair Script
Both remote databases now have the view properly created using SQL Passthrough scripts. Remote
database 1 can now execute future SQL Passthrough scripts normally.
STEPS TO RUN THE DEMO
The following steps will run the demo using the provided batch files:
1. \SQLPassThrough_View_Error\cons\setup.bat 2. \SQLPassThrough_View_Error\rem\setup.bat 3. \SQLPassThrough_View_Error\rem2\setup.bat 4. \SQLPassThrough_View_Error\cons\passthrough.bat
Wait for the following message to appear in the MobiLink console window to indicate the
SQL Passthrough scripts have been read by the MobiLink Server:
I. 2008-03-05 15:26:01. <Main> Server passthrough support has been
enabled.
5. \SQLPassThrough_View_Error\rem\sync.bat 6. \SQLPassThrough_View_Error\rem2\sync.bat 7. \SQLPassThrough_View_Error\rem\sync.bat 8. \SQLPassThrough_View_Error\rem2\sync.bat 9. \SQLPassThrough_View_Error\cons\repair_passthrough.bat
www.sybase.com/ianywhere 20
10. \SQLPassThrough_View_Error\rem\sync.bat 11. \SQLPassThrough_View_Error\rem2\sync.bat 12. \SQLPassThrough_View_Error\rem\sync.bat 13. \SQLPassThrough_View_Error\rem2\sync.bat
SUMMARY
This document has explained the functionality of the new SQL Passthrough feature in SQL
Anywhere 11.0.0. Included in the document are two demonstrations on how to use the new feature.
The SQL Passthrough feature is a very powerful and robust administrative tool for MobiLink
synchronization environments.
www.sybase.com/ianywhere 21
Copyright © 2008 iAnywhere Solutions, Inc. All Rights Reserved. Sybase, Afaria, SQL Anywhere,
Adaptive Server Anywhere, MobiLink, UltraLite, and M-Business Anywhere are trademarks of Sybase,
Inc. All other trademarks are property of their respective owners.