MobiLink SQL Passthrough · The new SQL Passthrough feature provides the ability for powerful and...

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


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.


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.


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.


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,


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.


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

'

);


'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


'

);


'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

'

);


'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:


'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

'


);

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

);


null,

'create_tables_and_schema',

20

);


null,

'create_data_publication',

30

);


null,

'create_data_subscription',

40

);


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:


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.


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.


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:


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.


� 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.


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

*-------------------------------------------------------*/


'create_view',

'automatic',

'pub1',

'

CREATE VIEW DBA.v_TableData

AS SELECT Table1.Table1_id TableID, Table1.Data Data1,

Table2.Data Data2



',

'

Create a view TableData on the remote databases

'

);

COMMIT;

/*--------------------------------------------------------


*-------------------------------------------------------*/


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:


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.


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

*-------------------------------------------------------*/


'alter_view',

'automatic',

'pub1',

'

ALTER VIEW DBA.v_TableData

AS SELECT Table1.Table1_id TableID, Table1.Data Data1,

Table2.Data Data2



',

'

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:

/*---------------------------------------------------------


*--------------------------------------------------------*/

CALL ml_add_passthrough_repair (

'create_view',

-110,

'alter_view',

'R'

);

COMMIT;


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:


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


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.


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.

Date post:	12-Oct-2020
Category:	Documents
Upload:	others
View:	1 times
Download:	0 times

MobiLink SQL Passthrough · The new SQL Passthrough feature provides the ability for powerful and...

Documents