MobiLink SQL Passthrough. A whitepaper from Sybase ianywhere Author: Joshua Savill, Product Manager Date: October 17 th, 2008

Transcription

1 MobiLink SQL Passthrough A whitepaper from Sybase ianywhere Author: Joshua Savill, Product Manager Date: October 17 th, 2008 This whitepaper was written in the context of SQL Anywhere 11.

2 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 Figure 2 SQL Passthrough Entries in the ml_passthrough Table Figure 3 - SQL Passthrough Status on the Remote Database Figure 4 SQL Passthrough Scripts on the Remote Database Figure 5 SQL Passthrough Progress on the Remote Database Figure 6 SQL Passthrough Script Results Figure 7 MobiLink Client Failure due to Failed Script Execution Figure 8 SQL Passthrough Status in Remote Database Figure 9 SQL Passthrough Status in the Consolidated Database Figure 10 SQL Passthrough Status in Remote Database 1 after Execution of Repair Script Figure 11 SQL Passthrough Status in Consolidated Database after Execution of Repair Script... 19

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 For 3

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 the value is the maximum value of the run order column in the ml_passthrough table plus If remote ID is not 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. 4

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

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

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, 7

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: 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. 8

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, // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% // 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, // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% // 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 9

10 CALL ml_add_passthrough_script ( create_data_publication, 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, 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, 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 10

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 ( create_users_and_domains, 10 CALL ml_add_passthrough ( create_tables_and_schema, 20 CALL ml_add_passthrough ( create_data_publication, 30 CALL ml_add_passthrough ( create_data_subscription, 40 CALL ml_add_passthrough ( 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 :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: 11

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

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

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 :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: 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. 14

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

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 ( 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: 16

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

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; 18

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

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

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