SQL Server CE Remote Data Access and Replication

Transcription

1 04-P1914 8/24/ :26 AM Page 134 F O U R SQL Server CE Remote Data Access and Replication Remote Data Access (RDA) and replication are two techniques that allow you to take data from an SQL Server running on Windows NT or Windows 2000 and use the data in an SSCE database on a Pocket PC or HPC 2000 device. The data can be modified locally, and then changes can be sent back to the SQL Server database. Data conflicts (such as when a single record is modified in both the SSCE and SQL Server database) can be tracked and resolved. With both techniques, the Pocket PC or HPC 2000 device connects to the network through an Internet Information Server (IIS) using HTTP, and IIS can be used to apply login authorization and secure the transport of data. In general, RDA is easier to setup and is most appropriate when devices are infrequently connected to the network, and where your Pocket PC or HPC 2000 applications need control on when data will be transferred and complete control over conflict resolution. RDA will work with SQL Server versions 6.5, 7.0, and Replication can be more difficult to setup and requires more SQL Server administration knowledge. It is ideal where a device is nearly always connected (e.g., through a wireless connection such as GPRS), but it can still allow data changes to be made when the device is not connected. Replication only works with SQL Server For the sake of clarity, SQL Server for Windows CE will be referred to as SSCE in this chapter, and SQL Server 6.5, 7.0, or 2000 running on Windows NT or Windows 2000 will be referred to as SQL Server. Some typical uses of RDA and replication include 134

2 04-P1914 8/24/ :26 AM Page 135 Remote Data Access 135 Pulling down up-to-date price lists from a central server Recording orders locally on an SSCE database and then sending them to a central SQL Server Pulling down updated customer details, making changes to the customer lists in the SSCE database, and sending changes back to the SQL Server Because IIS is used to connect to the SQL Server, Windows NT authentication can be used to secure access. Since HTTP is used to transfer data, Secure Socket Layer (SSL) HTTP requests can be used to secure the data in transit. Using HTTP makes deployment easier most firewalls and proxy servers are configured to allow HTTP requests from outside the organization, so additional ports and protocols do not need to be configured. Finally, the data is compressed in transit, making transmission efficient even over low bandwidth connections. You will need to plan carefully the amount and nature of the data you will be transferring using RDA or replication. Storage on Pocket PC and HPC 2000 devices is limited (your entire customer database may not fit!), and the more data you involve in RDA or replication, the slower the transmission will be. In most cases, it is possible to identify subsets of the data, either by selecting rows ( select customers assigned to a particular salesperson ) or columns of data ( only these columns of data are relevant in the mobile situation ). Ensure that you test your RDA or replication setup across the typical connection speeds your users will operate over, rather than the fast network connection you may use in development. Remote Data Access RDA allows you to pull the entire contents of a table, or selected columns and rows of data, from a Microsoft SQL Server 6.5, 7.0, or 2000 database and store the contents in an SSCE database table. The table in SSCE will automatically be created by the pull operation, and the pull process will convert SQL Server data types to appropriate SSCE data types. Primary key and other constraints will also be created in the local SSCE database table, but relationships with other tables will not be created. Once a table is pulled down into an SSCE database the data can be accessed and manipulated using ADOCE. You can add relationships with other tables, such as declaring foreign keys using ADOXCE. When a table is pulled you can turn on tracking, and this allows you to push the changes you have made to the SSCE table back up to the SQL Server database. You can specify a table name that will contain a list of conflicts detected when a push is made. RDA also allows you to execute SQL statements from a Pocket PC or HPC 2000 on an SQL Server. Any SQL statement can be executed, including stored

3 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication procedures, INSERT, DELETE, and UPDATE statements, so long as the SQL statement does not return a result set. RDA operates through Internet Information Server (IIS) running on Windows NT 4 or Windows 2000 and can use an SQL Server located on the same server as IIS or on a different server. The configuration of RDA can be a little tricky, as you need to configure IIS, SQL Server, and Windows NT or Windows 2000 security, so you should follow the instructions in the next section carefully. RDA Installation and Configuration Figure 4.1 shows the RDA architecture, the key elements of which are SQL Server CE Client Agent SQL Server CE Server Agent The Client Agent implements the SSCE.RemoteDataAccess.1.0 object that you program against to push and pull tables and to execute SQL statements on an SQL Server database. This functionality is implemented in the file ssceca10.dll, and this should be installed in the \windows directory on the Pocket PC or HPC 2000 device. The Server Agent receives push, pull, and SQL execute requests from the client agent and passes these requests on to the SQL Server. It manages the re- Figure 4.1 Remote Data Access architecture

4 04-P1914 8/24/ :26 AM Page 137 Remote Data Access 137 turned data and conflict resolution. This functionality is implemented in the file sscesa10.dll, which is an ISAPI (Internet Server API) application that is installed in a Web virtual directory and is managed by IIS. REQUIREMENTS To install and use RDA you will need A Pocket PC or HPC 2000 with SSCE installed (as described in the last chapter), together with the file ssceca10.dll copied into the \windows directory on the device A Windows NT or Windows 2000 server running IIS An SQL Server 6.5, 7.0, or 2000 server running on either the same server as IIS or a different one The Pocket PC or HPC 2000 should be capable of connecting to the IIS server. This can be a direct network connection using a network card or a dialup RAS (Remote Access Server) connection. Making RAS connections is described in Chapter 8. Alternatively, you can use the SQL Server Relay through an ActiveSync connection using a serial or USB connection, as described later in this chapter. While you can use Windows NT or Windows 2000, and either SQL Server version 6.5, 7.0, or 2000, the instructions in this chapter describe setting up RDA on a Windows 2000 Server with SQL Server 2000 running on the same server. Instructions for Windows NT and other versions of SQL Server can be found in the on-line documentation. The examples in this section will show how to setup RDA to the pubs sample database shipped with SQL Server. The same principles can be applied to any database. The example here uses a Windows 2000 Server called malahide with an IP address of You should change these where appropriate to your server name and address as you follow through these instructions. INSTALLING SSCE SERVER TOOLS You will need to install the SSCE Server Tools on your server running IIS. Note that if you have IIS and SQL Server on separate machines, you need only run the SSCE Server Tools setup on the IIS machine. Run the ssce11.exe setup application. On the opening screen, ensure that Server Tools is selected and Development Tools is unselected. Click Next. You can now follow the wizard steps to complete the SSCE Server Tools installation.

5 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication CONFIGURING IIS The best place to start configuring RDA is with the IIS server. You will need to Create a virtual directory Copy the file sscesa10.dll into the directory Set file and directory access permissions in this directory Specify the authentication control used on the website. First, run the Internet Information Services application and create the virtual directory: Select the Start Programs Administrative Tools Internet Services Manager menu command. Alternatively, on Windows 2000 Professional you can Run the Control Panel Double-click the Administrative Tools icon Double-click the Internet Services Manager icon To create the virtual directory Expand out your server name ( malahide in Figure 4.2), and Default Web Site Right-click Default Web Site and select the New Virtual Web Directory menu Selecting this menu command starts the Virtual Directory Creation Wizard. Click Next in the opening screen. Enter the alias name for the virtual directory (see Figure 4.3). In this example you should use sscepubs. Click Next. The virtual directory needs a folder that it will map to for content. Use File Explorer to create a new folder \Inetpub\wwwroot\ssce Pubs. Select this folder in the Web Site Content Directory wizard page (see Figure 4.4). Click Next. The next screen allows you to specify the access permissions for this website. RDA is implemented through an ISAPI DLL, and so Execute permissions must be enabled. Other permissions are not required. Ensure only Execute (such as ISAPI applications or CGI) is selected in the Access Permissions wizard page (see Figure 4.5). Click Next and then Finish. The next stage is configuring Directory Security options for this new virtual directory. It is crucial to get this right; otherwise, you will end up with an insecure website or will not be able to access the website at all.

6 04-P1914 8/24/ :26 AM Page 139 Remote Data Access 139 Figure 4.2 Internet Information Services Right-click the new sscepubs virtual directory in the Default Web Site list in the Internet Information Services application. Select the Properties menu command. Select the Directory Security tab in this dialog and click Edit. This displays the Authentication Methods dialog (see Figure 4.6). By default, anonymous login will be enabled (unless this option is changed in Default Web Site within Internet Information Services), and this specifies a login that will be used if the application making the HTTP request does not supply a Windows NT or Windows 2000 username and password. By default, the username is IUSR_<servername> where <servername> is replaced with the name of the service IIS is running on (for example, IUSR_Malahide). Clicking Edit allows you to change the login name used for anonymous access. Integrated Windows authentication allows the client application to specify a username and password that will be used to authenticate access to IIS and is more secure than using anonymous login. You should avoid using Basic authentication.

7 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.3 Selecting the virtual alias name In this example, anonymous login will be used; however, you may wish to use Integrated Windows authentication in a production system. Click the Edit box in the Authentication Methods dialog and record the name of the anonymous username. Close all the open dialogs. Note that the Directory Security page allows you to setup certificates for enabling Secure Socket Layer (SSL) for encrypting data in transit. This allows you to use HTTPS rather than HTTP when using RDA. You should enable SSL when transmitting data across public networks such as the Internet. You now need to copy the ISAPI DLL into the folder used by the virtual directory you have just created and to set the correct permissions on the directory. Run File Explorer and copy the file sscesa10.dll from the install location (which is, by default, in the folder \Program files\microsoft SQL Server CE\Server) to \InetPub\wwwroot\sscepubs.

8 04-P1914 8/24/ :26 AM Page 141 Remote Data Access 141 Figure 4.4 Selecting the Web site content directory Run a command shell (cmd.exe), navigate to the \InetPub\wwwroot \sscepubs folder, and run regsvr32 on this DLL: Regsvr32 sscesa10.dll This registers the COM components in this DLL. This DLL needs to read and write files in the \InetPub\wwwroot\sscepubs folder, so the anonymous user (or other users if you are using Integrated Windows authentication) must be granted access. Note that this is not done though the Internet Information Server administration program, since remote client does not need to perform the reads and writes it is the DLL itself that does. Run File Explorer, and select the \InetPub\wwwroot\sscepubs folder. Right-click the folder sscepubs and select Properties. Click the Security tab (see Figure 4.7). Click the Add button to add another user to list of users granted permissions on the directory. Select your IUSR_<servername> user (e.g., IUSR_MALAHIDE) from the list of users, click the Add button and click OK.

9 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.5 Selecting the access permissions Select the newly added user in the Name list, and click Full Control in the Permissions list. Click OK to accept the change to the security settings. TESTING THE IIS INSTALLATION You can now test the IIS installation at a basic level by attempting to execute sscesa10.dll through Internet Explorer. Run Internet Explorer on your server PC. Enter in the address line and press Enter. If IIS is configured correctly you should see the word Body being displayed. This indicates that IIS could connect and execute the ISAPI function in sscesa10.dll. If you get an error 500 returned, check that you have copied sscesa10.dll into the virtual directory folder and that you have successfully registered the DLL with regsvr32.dll. If you get a permissions problem, check that you have assigned execute permissions to the virtual directory and read/write permissions on the folder.

10 04-P1914 8/24/ :26 AM Page 143 Remote Data Access 143 Figure 4.6 Directory security You can check the username being used to access IIS through the logs: Navigate to the folder \winnt\system32\logfiles\w3svc1 Open the most recently accessed log file with Notepad and scroll to the end. You will see lines like the following: :28: POST /sscepubs/sscesa10.dll SSCEReplicationClient This shows the date and time of the HTTP request followed by the IP address of the requester and the IP address of IIS. The - between the two IP addresses indicates that an anonymous login was used to access IIS. If Windows authentication was used, the domain name and username would be shown: :30: MALAHIDE\Administrator POST /sscepubs/sscesa10.dll SSCEReplicationClient TESTING THE POCKET PC OR HPC 2000 CONNECTION You can now test that your Pocket PC or HPC 2000 can connect to your IIS server by using Pocket Internet Explorer.

11 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.7 Folder security Run Pocket Internet Explorer on your Pocket PC or HPC 2000 device. Enter the address in the address line, replacing Malahide with the name of your server. Pocket Internet Explorer should display the text Body if it can connect to sscesa10.dll. Note that the screen will be blank if you have Fit to Screen turned on, so use the View Fit to Screen menu to turn off this option and ensure that the text Body appears. If you cannot connect, try using the IP address of your server rather than the server name. For example, enter

12 04-P1914 8/24/ :26 AM Page 145 Remote Data Access 145 sscesa10.dll in the address line, replacing with the IP address of your server. If this solves the problem it is likely that the Pocket PC or HPC 2000 cannot connect to a Domain Name Server (DNS), or the DNS is not configured properly. You can either fix the DNS problem or continue to use an IP address in place of the server name. You will need to be careful, though, if your server has a server-assigned IP address rather than a fixed IP address the next time the server reboots, the IP address may change, and you will no longer be able to connect. Once you have IIS configured, you can move on to configuring SQL Server. CONFIGURING SQL SERVER 2000 When configuring SQL Server 2000 there are two types of security you can use: Mixed security ( SQL Server and Windows ): Users can login either using an SQL Server login identifier or using integrated security with an automatic login using a Windows username. Windows only: Integrated security only with a Windows username. This is sometimes known as trusted security. When using RDA, the type of security is selected through a connection string from within your program. However, you will need to ensure that the connection string you choose uses a security type configured on SQL Server. In this example, Mixed Security will be used so that code using both SQL Server login identifiers and integrated security can be shown. To configure security Run the SQL Server Enterprise Manager by selecting the Start Programs Microsoft SQL Server Enterprise Manager menu command. Expand out Microsoft SQL Servers under Console Root in the Tree pane until you locate your server (e.g., Malahide ). If you cannot locate your server, right-click SQL Server Group in the Tree pane, select the New SQL Server Registration menu command, and follow the Register SQL Server Wizard instructions. Next, you will set the security options for your server. Right-click your server name (e.g., Malahide ) in the Tree pane, and select the Properties menu command. Select the Security tab (see Figure 4.8). Ensure that SQL Server and Windows security is selected. Ensure that All is selected for Audit level. Selecting All for Audit level causes SQL Server to write an event into the application event log for all attempts at logging into the server, regardless of whether they succeed or fail. Using this option when setting up RDA is useful, as you can quickly determine the username being used by IIS to access SQL Server. However, you should remember to reset this option at some stage

13 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.8 SQL Server security options to ensure your event log does not become full. Figure 4.9 shows a typical event log for a successful login using integrated (trusted) security for the anonymous login user IUSR_MALAHIDE. You will now need to check that users have the correct access rights to the database being accessed through RDA. In this example the user in question is IUSR_MALAHIDE and the database is pubs. Expand out your server (e.g., Malahide ) in the Tree pane so that Security is visible, and then expand out Security so Logins is visible. Single-click Logins to display the current list of logins (see Figure 4.10).

14 04-P1914 8/24/ :26 AM Page 147 Remote Data Access 147 Figure 4.9 SQL Server login Notice that there is not currently an IUSR_MALAHIDE user added to this list. If you were to access the SQL Server through IIS with anonymous login, you would get an error explaining that IUSR_MALAHIDE was not a trusted user of the SQL Server. You now need to add a trusted user. Right-click Logins in the Tree pane and select the New Login menu command. In the SQL Server Login Properties New Login dialog (see Figure 4.11), click the button with the caption... to the right of the Name edit box. Double-click IUSR_MALAHIDE from the list of users and click OK. Click the Database Access tab in the SQL Server Login Properties New Login dialog.

15 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.10 SQL Server logins Select the Permit check box for the pubs database. Select the db_owner role for the pubs database (see Figure 4.12). Click on OK to create the login. Note that the user IUSR_MALAHIDE has had the db_owner role selected this grants full access to all objects in this database. You would normally not make a user a db_owner unless the user was a developer. Instead, you should set the permissions on all objects appropriately through the database s user permission settings. That completes the SQL Server configuration and the RDA setup you now need to execute some RDA code to test the configuration. Remember, if you have trouble logging in to SQL Server or need to check the actual login being used, use the Event Viewer to look at the application event log. Programming RDA RDA is programmed through the RemoteDataAccess object s methods and properties. This object is created using the progid SSCE.RemoteDataAccess.1.0. A reference to the library Microsoft SQL Server Control 1.0 should be added to the project using the evb Project Add References menu command. All the code shown in this section can be found in the project \Ex amples\pocketpc\rda\rda.ebp or \Examples\HPC2000\RDA\RDA.ebp on the CDROM. The code to use RDA is the same for Pocket PC and HPC 2000.

16 04-P1914 8/24/ :26 AM Page 149 Remote Data Access 149 Figure 4.11 Creating a new SQL login PULLING DATA The RemoteDataAccess object s Pull method allows a table to be downloaded from an SQL Server database and the data loaded into an SSCE table. The Pull method automatically creates the table in the SSCE database and provides suitable data type conversions where the SQL Server database uses data types that are unsupported in SSCE. The Pull method is passed an SQL statement that will be executed on the SQL Server, and this defines the data to be downloaded. In the simplest case, you can specify a SELECT * FROM table type statement to download all fields and all records from the table. Alternatively, you can specify a list of fields in place of * or add a WHERE clause to filter only particular records. Be-

17 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.12 Database access for an SQL Server login cause almost any SQL statement producing a result set can be used, stored procedures, views, or SELECT statements joining several tables can be used. However, if you later want to push data back up onto the server, you should ensure that the recordset resulting from executing the SQL statement is updateable. There are some limitations to be aware of when using the RDA Pull method. With SSCE databases, object names are not case sensitive, whereas SQL Server databases can optionally be configured as case sensitive. You cannot use RDA against a case-sensitive SQL Server database. You cannot pull data from a table having a primary key of type CHAR, NCHAR, VARCHAR, or NVARCHAR where the length of the field is greater

18 04-P1914 8/24/ :26 AM Page 151 Remote Data Access 151 than 255 characters. In a Pull, fields of this type with a length greater than 255 are mapped to NTEXT, and an NTEXT field cannot be a primary key. When using RDA to pull data from a table that also participates in replication on the server, you must exclude the system column with the ROWGUIDCOL attribute. By default, this column is named RowGuid. The number of columns pulled must be 253 or less. RDA adds two extra columns for tracking changes made to pulled data. You need to apply service pack 6 to SQL Server 6.5 when tracking data changes. Pull can be used with two different data change tracking options: Tracking Off: The data is pulled from the SQL Server and SSCE does not monitor changes made to the data locally. Changes cannot be automatically pushed back to the server. Tracking On: Data changes made locally will be tracked. At a later stage, the changes can be pushed back to the server. Optionally, a table can be specified into which information on conflicts will be added. In the first RDA example, a new database will be created called \pubs.sdf, and the three tables authors, titles, and titleauthor will be pulled from the pubs database without tracking. The relationships will not automatically be created between these tables during the Pull operation, so they will be added using ADOXCE techniques described in the previous chapter. The code for creating the database and pulling the tables is shown in Listing 4.1. This code is associated with a form called frmgettables in the project \Examples\PocketPC\RDA\RDA.ebp or \Examples\HPC2000\ RDA\RDA.ebp on the CDROM. The form is illustrated in Figure The form prompts the user for the name or IP address of the IIS server and allows the SQL Server username and password to be specified the code uses an SQL login id rather than integrated security in this example. Clicking the OK button proceeds with creating the database (deleting the old database if one exists) and then pulling the three tables. A label on the form notifies the user of progress. The form has a File System object called FileSystem1, and this is used to delete an existing database. Listing 4.1 Pulling tables with RDA Option Explicit Private sserver Private suser Private spassword Private Sub cmdcancel_click()

19 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.13 The form frmgettables Me.Hide End Sub Private Sub cmdok_click() sserver = Me.txtServerName suser = Me.txtSQLUser spassword = Me.txtPassword Call MakeDB Me.Hide End Sub ' makes the SSCE database by copying files from SQL Server ' using RDA. Private Sub MakeDB() Dim cerda As SSCE.RemoteDataAccess Dim ocatalog As adoxce.catalog Dim ssvrcon, slocalcon ' Delete database if it already exists, and then create On Error Resume Next If FileSystem1.Dir("\Pubs.sdf") <> "" Then FileSystem1.Kill "\Pubs.sdf" DisplayError "Deleting database: " Exit Sub Set ocatalog = CreateObject("ADOXCE.Catalog.3.1") DisplayError "Creating ADOXCE.Catalog object: "

20 04-P1914 8/24/ :26 AM Page 153 Remote Data Access 153 Exit Sub lblstatus.caption = "Creating local database" slocalcon = "Provider=Microsoft.SQLSERVER.OLEDB.CE.1.0;" slocalcon = slocalcon & "Data source=\pubs.sdf" ocatalog.create slocalcon ' create the database DisplayError "Creating Database: " Exit Sub Set ocatalog = Nothing lblstatus.caption = "Connecting to remote server" Set cerda = CreateObject("SSCE.RemoteDataAccess.1.0") ' set RDA properties cerda.interneturl = " & sserver & _ "/sscepubs/sscesa10.dll" cerda.localconnectionstring = slocalcon ssvrcon = "Provider=sqloledb;Data Source=(local);" ssvrcon = ssvrcon & "Initial Catalog=Pubs" ssvrcon = ssvrcon & ";user id=" & suser ssvrcon = ssvrcon & ";password=" & spassword lblstatus.caption = "Pulling Authors" cerda.pull "Authors", "SELECT * FROM Authors", _ ssvrcon, _ TRACKINGOFF ReportEngineErrors "Pulling Authors:", cerda Exit Sub lblstatus.caption = "Pulling Titles" cerda.pull "Titles", "SELECT * FROM Titles", _ ssvrcon, _ TRACKINGOFF ReportEngineErrors "Pulling Titles", cerda Exit Sub lblstatus.caption = "Pulling TitleAuthor" cerda.pull "TitleAuthor", "SELECT * FROM TitleAuthor", _ ssvrcon, _ TRACKINGOFF ReportEngineErrors "Pulling TitleAuthor", cerda Exit Sub

21 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Set cerda = Nothing Call AddIndexesEtc(sLocalCon) End Sub The function MakeDB uses the FileSystem1 control s Dir method to determine if the file \pubs.sdf already exists. This method returns an empty string if the file does not exist or the fully qualified filename if it does. The Kill method is used to delete the file: If FileSystem1.Dir("\Pubs.sdf") <> "" Then FileSystem1.Kill "\Pubs.sdf" DisplayError "Deleting database: " Exit Sub Next, ADOXCE is used to create the new database \pubs.sdf using a connection string specifying the OLEDB SSCE provider and the name of the file, as follows: slocalcon = "Provider=Microsoft.SQLSERVER.OLEDB.CE.1.0;" slocalcon = slocalcon & "Data source=\pubs.sdf" ocatalog.create slocalcon ' create the database This connection string will also be used to specify the database into which RDA will place the pulled tables. When calling RDA you will need to create an object using the progid SSCE.RemoteDataAccess.1.0 and specify the URL to the IIS server, including the virtual directory and name of the ISAPI DLL sscesa10.dll. This is assigned to the InternetURL property. The connection string for the SSCE database is specified in the LocalConnec tionstring property: Set cerda = CreateObject("SSCE.RemoteDataAccess.1.0") ' set RDA properties cerda.interneturl = " & sserver & _ "/sscepubs/sscesa10.dll" cerda.localconnectionstring = slocalcon The Pull method also needs a connection string for connecting to the SQL Server. This connection string will be used on the IIS server, so you can use (local) for the Data Source (that is, the server name where SQL Server is located). If your SQL Server is on another server, you will need to change this to the name of the server. In this case, the initial catalog is set to the pubs database, and the user id and password are taken from the dialog: ssvrcon = "Provider=sqloledb;Data Source=(local);" ssvrcon = ssvrcon & "Initial Catalog=Pubs" ssvrcon = ssvrcon & ";user id=" & suser ssvrcon = ssvrcon & ";password=" & spassword

22 04-P1914 8/24/ :26 AM Page 155 Remote Data Access 155 This code, when executed, results in the following connection string being created: Provider=sqloledb;Data Source=(local);Initial Catalog=Pubs; user id=sa;password= It is important that Initial Catalog is used to specify the database being used; otherwise, the default database defined for the SQL Server user will be used (which is master by default). The Pull method is now called and is passed the following parameters: The name for the new table in the SSCE database, Authors in this case. The SQL statement that provides the recordset for the new table. All columns and all rows are selected. The SQL Server connection string created above. The tracking option for changed data. Tracking is not enabled in this case as the TRACKINGOFF constant is specified: cerda.pull "Authors", "SELECT * FROM Authors", _ ssvrcon, _ TRACKINGOFF ReportEngineErrors "Pulling Authors:", cerda Exit Sub Note that the table being pulled must not exist in the SSCE database. In this case the database has been re-created so the tables cannot exist. In your code you may need to drop tables before pulling them. As you can imagine, there are many things that can (and often do) go wrong with pulling data; therefore, it is essential to provide good error-checking code. In the above code, the subroutine ReportEngineErrors is called if an error is detected, and this is passed the RDA Engine object. Listing 4.2 shows this subroutine it is located in the module utils.bas. Listing 4.2 Reporting RDA errors Public Sub ReportEngineErrors(sMsg, oengine As SSCE.Engine) Dim oengerr As SSCEError For Each oengerr In oengine.errorrecords MsgBox smsg & vbcrlf & _ "SSCE Error: " & vbcrlf & oengerr.description _ & vbcrlf & "Number: " & oengerr.number & _ vbcrlf & "Native: " & oengerr.nativeerror

23 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Next End Sub The Engine object has an ErrorRecords collection containing one or more SSCEError objects describing the error. The code in Listing 4.2 iterates through the errors, displaying each in a message box. The Description property does not always describe the error fully, so you should look up the NativeError in the SSCE on-line documentation for more information. Search the help file for Client Agent Errors for a list of error numbers generated by the SSCE Client Agent and Server Agent Errors for error numbers generated by the IIS ISAPI agent. Similar code is executed to pull the Titles and the TitleAuthor tables. Once this has been done, the code in Listing 4.3 is called to add primary and foreign keys between the tables. The techniques used in this code are described in Chapter 3, ADOCE and ADOXCE. Listing 4.3 Adding indexes and keys Private Sub AddIndexesEtc(sLocalCon) ' add indexes, primary keys etc for these new tables Dim ot As adoxce.table Dim o As adoxce.catalog Dim ok As adoxce.key Dim oic As adoxce.column Set o = CreateObject("ADOXCE.Catalog.3.1") o.activeconnection = slocalcon On Error Resume Next ' set primary key on au_id for Authors table Set ot = o.tables("authors") Set ok = CreateObject("ADOXCE.Key.3.1") ok.type = adkeyprimary ok.name = "pkauthors" Set oic = CreateObject("ADOXCE.Column.3.1") oic.name = "au_id" ok.columns.append oic ot.keys.append ok DisplayError "Authors PK" ' set primary key on title_id for titles table Set ot = o.tables("titles") Set ok = CreateObject("ADOXCE.Key.3.1") ok.type = adkeyprimary ok.name = "pktitles" Set oic = CreateObject("ADOXCE.Column.3.1")

24 04-P1914 8/24/ :26 AM Page 157 Remote Data Access 157 oic.name = "title_id" ok.columns.append oic ot.keys.append ok DisplayError "Titles PK" ' set primary key on au_id, title_id ' for titleauthor table Set ot = o.tables("titleauthor") Set ok = CreateObject("ADOXCE.Key.3.1") ok.type = adkeyprimary ok.name = "pktitleauthor" Set oic = CreateObject("ADOXCE.Column.3.1") oic.name = "au_id" ok.columns.append oic Set oic = CreateObject("ADOXCE.Column.3.1") oic.name = "title_id" ok.columns.append oic ot.keys.append ok DisplayError "TitleAuthor PK" ' set foreign key on titleauthor table to authors table Set ok = CreateObject("ADOXCE.Key.3.1") ok.type = adkeyforeign ok.name = "fkauthor" Set oic = CreateObject("ADOXCE.Column.3.1") oic.name = "au_id" oic.relatedcolumn = "au_id" ok.columns.append oic ok.relatedtable = "Authors" DisplayError "Author FK" ot.keys.append ok ' set foreign key on titleauthor table to titles table Set ok = CreateObject("ADOXCE.Key.3.1") ok.type = adkeyforeign ok.name = "fktitles" Set oic = CreateObject("ADOXCE.Column.3.1") oic.name = "title_id" oic.relatedcolumn = "title_id" ok.columns.append oic ok.relatedtable = "Titles" ot.keys.append ok Set o = Nothing DisplayError "Title FK"

25 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication End Sub You can use this code to test your own RDA installation. Copy the files from the folder \Examples\PocketPC\RDA from the CDROM into a folder on your PC s hard drive. Use File Explorer to remove the read-only settings on these files. Open the project rda.ebp in evb. Open the code associated with the form frmrda.ebf and change the constant definition smyserver to your own IIS server name or IP address of the IIS server: Const smyserver = " " Run the application on your Pocket PC. Select the Operations Create Tables menu command to display the Get Server Details dialog. Enter your server name (it does not use the constant smyserver in this case) and enter a valid SQL login and password. Click OK to download the tables. To confirm that the data has been downloaded, select the Operations Show Authors menu command to list the contents of the Authors table (see Figure 4.14). Figure 4.14 List of authors from a pulled table

26 04-P1914 8/24/ :26 AM Page 159 Remote Data Access 159 SQL PASS-THROUGH The RDA Engine object s SubmitSQL method can be used to execute any SQL statement on an SQL Server providing the SQL statement does not return a recordset. The SQL statement could be an INSERT, DELETE, or UPDATE statement or a stored procedure. Note that you cannot determine the number of rows affected when using SubmitSQL. Therefore, if you delete a number of rows using a WHERE clause, you cannot determine how many, if any, records were deleted. When calling the RDA Engine object s SubmitSQL method (see Listing 4.4), you will first need to specify the URL of the IIS server in the Internet URL property and the SSCE connection string in the LocalConnection String property. The format of the URL and connection string is exactly the same as for the Push method. The SubmitSQL method itself is passed two parameters: The SQL statement to execute The connection string used by IIS to connect to the SQL Server As usual, you will need to check for errors, and these can be displayed using the ReportEngineErrors method. Listing 4.4 Using SubmitSQL Public Sub RemoteSQL(sServer, ssql) Dim slocalcon, ssvrcon Dim cerda As SSCE.RemoteDataAccess Set cerda = CreateObject("SSCE.RemoteDataAccess.1.0") On Error Resume Next slocalcon = "Provider=Microsoft.SQLSERVER.OLEDB.CE.1.0;" slocalcon = slocalcon & "Data source=\pubs.sdf" cerda.interneturl = " & sserver & _ "/sscepubs/sscesa10.dll" cerda.localconnectionstring = slocalcon ssvrcon = "Provider=sqloledb;DataSource=(local)" ssvrcon = ssvrcon & ";Initial Catalog=Pubs;" ssvrcon = ssvrcon & "Integrated Security=SSPI" cerda.submitsql ssql, ssvrcon ReportEngineErrors "Adding Author:", cerda Exit Sub End Sub

27 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Figure 4.15 Adding an author using RemoteSQL In the project RDA.EBP the function RemoteSQL is used by the form frmaddauthor.ebf to get details for each of the fields in the Author table, to produce an INSERT SQL statement containing these values, and to send the INSERT statement to the server (see Figure 4.15). The Add Author form is accessed from the main form through the Operations Add Author menu command. The following code is executed when the Add button is clicked in the Add Author dialog: Private Sub cmdadd_click() Dim s s = "INSERT INTO Authors " s = s & "(au_id, au_lname, au_fname, phone," s = s & "address, city, state, zip, contract)" s = s & "VALUES(" s = s & "'" & au_id.text & "'," s = s & "'" & au_lname.text & "'," s = s & "'" & au_fname.text & "'," s = s & "'" & phone.text & "'," s = s & "'" & address.text & "'," s = s & "'" & city.text & "'," s = s & "'" & state.text & "'," s = s & "'" & zip.text & "'," If contract.value Then

28 04-P1914 8/24/ :26 AM Page 161 Remote Data Access 161 s = s & "1)" Else s = s & "0)" RemoteSQL Me.txtServer, s Me.Hide End Sub This code generates an SQL INSERT statement such as INSERT INTO Authors (au_id, au_lname, au_fname, phone,address, city, state, zip, contract) VALUES(' ','First Name', 'Last Name',' ', '1500 Bridge Street','Oakland','CA','94026', Remember that this results in a record being added to the Authors table on the SQL Server, not on the local SSCE database. You will not see this new record in your Pocket PC or HPC 2000 application unless you again pull the Authors table from SQL Server. There is no automatic update with RDA. TRACKING DATA WITH PULL In the Engine object s Push example described earlier in this chapter, the TRACKINGOFF option was used. The SSCE client agent does not track changes made on the Pocket PC or HPC 2000 device, so changes cannot automatically be sent back to the SQL Server. When the TRACKINGON option is used, two new fields are added to the table being pulled, called s_binarykey and s_operation. Values are placed in these fields indicating the type of change operation (such as a record being inserted, deleted, or updated). A table with these two fields can be pushed back to the SQL Server, and the SSCE client agent will only send back to SQL Server those records that have been changed in some way. Of course, it is possible that one particular record may be changed in SSCE and on the SQL Server database between the time the table was pulled and the time it is eventually pushed back to the server this creates a conflict that must be resolved. When calling the Pull method you can specify the name of a table in the SSCE database that will contain records detailing any conflicts that have been detected. In the \Examples\PocketPC\RDA\RDA.ebp project on the CDROM, the Stores table from the Pubs database is used to illustrate using the TRACKINGON option and resolving conflicts. The Operations Pull Stores menu command executes the code in Listing 4.5 to pull the Stores table using tracking. The code is located in frmrda.ebf.

29 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication This code uses ADOXCE to determine if the Stores table already exists in the database. If it does, the table is deleted. This uses the DoesObject Exist function described in Chapter 3. Listing 4.5 Pulling Stores table Public Sub PullStores() Dim cerda As SSCE.RemoteDataAccess Dim slocalcon, ssvrcon Dim ocatalog As adoxce.catalog On Error Resume Next ' first delete the table if it exists Set ocatalog = CreateObject("ADOXCE.Catalog.3.1") DisplayError "Creating ADOXCE.Catalog object: " Exit Sub slocalcon = "Provider=Microsoft.SQLSERVER.OLEDB.CE.1.0;" slocalcon = slocalcon & "Data source=\pubs.sdf" ocatalog.activeconnection = slocalcon If DoesObjectExist(oCatalog.Tables, "Stores") Then ocatalog.tables.delete ("Stores") DisplayError "Deleting 'Stores' table: " Exit Sub Set ocatalog = Nothing Set cerda = CreateObject("SSCE.RemoteDataAccess.1.0") ' set RDA properties cerda.interneturl = " & smyserver & _ "/sscepubs/sscesa10.dll" cerda.localconnectionstring = slocalcon ssvrcon = "Provider=sqloledb;Data Source=(local)" ssvrcon = ssvrcon & ";Initial Catalog=Pubs;" ssvrcon = ssvrcon & "Integrated Security=SSPI" cerda.pull "Stores", "SELECT * FROM Stores", _ ssvrcon, _ TRACKINGON, "tblerror" ReportEngineErrors "Pulling Stores:", cerda Else MsgBox "Stores Pulled"

30 04-P1914 8/24/ :26 AM Page 163 Remote Data Access 163 End Sub An RDA Engine object is created as usual, and the InternetURL property is assigned the URL of the SSCE Server agent DLL, sscesa10.dll. Next, the local connection string is assigned to the LocalConnectionString property. Both these two strings are the same as the previous Pull example. The server connection string uses integrated SQL Server security rather than specifying an SQL Server login and password. Because anonymous access is used for IIS, the IUSR_MALAHIDE login will be used to access SQL Server. The connection string will look like the following: Provider=sqloledb;Data Source=(local); Initial Catalog=Pubs;Integrated Security=SSPI The call to the Pull method specifies: The name of the table to create in the SSCE database, which is Stores. The TRACKINGON option this results in the two extra fields being added to the Stores table. The name tblerror used for the errors table. This table will automatically be created when a Push is performed. Note that you should specify a different errors table name (tblerror) for each table being pulled. The errors table contains the same fields as the pulled table and is therefore specific to that table. The Operations Show Stores menu command can be used to display the pulled table and the contents of the s_binarykey and s_operation fields. When first pulled, the contents of these two fields will always be NULL the values are set as records are changed. CREATING A CONFLICT To illustrate how conflicts can be detected, the Operations Create Stores Conflict menu in the \Examples\PocketPC\RDA\RDA.ebp project adds a record to the SSCE database table Stores and another record to the SQL Server database table Stores with the same primary key value for stor_id, but different data in the other fields. When the table is finally pushed, the conflict will be detected. The code to create the conflict is shown in Listing 4.6. Two INSERT statements are created in the strings ssqlloc (for adding to the SSCE database) and ssqlrem (for adding to the SQL Server database). The local record is inserted using the ADOCE s Execute method through the Connection object. The remote record is inserted using the RemoteSQL method described earlier in this chapter.

31 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication Listing 4.6 Creating a conflict in the Stores table Public Sub CreateStoresConflict() Dim ssqlloc, ssqlrem, slocalcon Dim olocado As ADOCE.Connection On Error Resume Next ' create the SQL INSERT statements ssqlloc = "INSERT INTO Stores (stor_id, stor_name, " ssqlloc = ssqlloc & "stor_address, city, state, zip)" ssqlloc = ssqlloc & "VALUES ('9999', 'Store 1', " ssqlloc = ssqlloc & "'11 High Street', " ssqlloc = ssqlloc & "'Portland', 'OR', '89076')" ssqlrem = "INSERT INTO Stores (stor_id, stor_name, " ssqlrem = ssqlrem & "stor_address, city, state, zip)" ssqlrem = ssqlrem & "VALUES ('9999', 'Store 2', " ssqlrem = ssqlrem & "'1021 Lost Creek', " ssqlrem = ssqlrem & "'Fremont', 'CA', '90019')" ' add record locally Set olocado = CreateObject("ADOCE.Connection.3.1") MsgBox "Error Creating ADOCE Object" & _ vbcrlf & Err.Description Exit Sub slocalcon = "Provider=Microsoft.SQLSERVER.OLEDB.CE.1.0;" slocalcon = slocalcon & "Data source=\pubs.sdf" olocado.open slocalcon MsgBox "Error opening local database" & _ vbcrlf & Err.Description Exit Sub olocado.execute ssqlloc MsgBox "Error adding local record" & _ vbcrlf & Err.Description Exit Sub olocado.close Set olocado = Nothing ' add record remotely Call RemoteSQL(sMyServer, ssqlrem) MsgBox "Conflict Created" End Sub The easiest way to look at and edit records in an SQL Server database is through the Enterprise Manager. Click on Tables in the pubs database

32 04-P1914 8/24/ :26 AM Page 165 Remote Data Access 165 in the Tree pane, right-click the table name Stores, and select the Open Table Return All Rows menu command. This displays the records in a table and is editable. PUSHING A TABLE Changes made locally in the Stores table can be pushed back to the SQL Server using the RDA Engine object s Push method. In Listing 4.7 the Inter neturl and LocalConnection strings are initialized as before. The Push method is passed The name of the table to push, which is Stores in this case. The connection string used to connect to the SQL Server database. Once again, this uses integrated security. This code can be executed through the Operations Push Stores menu command in the sample application. Executing this menu command will result in a native error being generated. This is a client agent error that the on-line documentation describes as One or more error rows returned from RDA_PUSH; see associated _err table. This results because of the conflict created in the previous section. Listing 4.7 Pushing a table Public Sub PushStores() Dim cerda As SSCE.RemoteDataAccess Dim slocalcon, ssvrcon On Error Resume Next Set cerda = CreateObject("SSCE.RemoteDataAccess.1.0") ' set RDA properties cerda.interneturl = " & smyserver & _ "/sscepubs/sscesa10.dll" slocalcon = "Provider=Microsoft.SQLSERVER.OLEDB.CE.1.0;" slocalcon = slocalcon & "Data source=\pubs.sdf" cerda.localconnectionstring = slocalcon ssvrcon = "Provider=sqloledb;Data Source=(local);" ssvrcon = ssvrcon & "Initial Catalog=Pubs;" ssvrcon = ssvrcon & "Integrated Security=SSPI" cerda.push "Stores", ssvrcon ReportEngineErrors "Pushing Stores:", cerda Exit Sub Else MsgBox "Stores Pushed"

33 04-P1914 8/24/ :26 AM Page Chapter 4 SQL Server CE Remote Data Access and Replication End Sub The following happens when a conflict is detected: The offending record is removed from the SSCE Stores table The conflicting record on the SQL Server database Stores table is not changed the SQL Server changes take precedence A record is added to the tblerror table describing the conflict Note that a Push does not result in records changed on the SQL Server table being downloaded to the SSCE table. You must perform a Pull again to get changes from the SQL Server table, and to do this you must first drop the SSCE table. This can make RDA inefficient when pulling large tables. The contents of the tblerror table can be viewed in the sample application by selecting the Operations Show Conflicts menu command. The table will contain a single record describing the conflict with the following fields: s_errordate: Date and time of the Push that detected the conflict s_oldeberr: Database access error causing the conflict s_oldeberrorstring: A string describing the error Fields for each of the fields in the original table Stores containing the record resulting in the conflict The conflict in this case results in an error 2627 Violation of PRIMARY KEY constraint UPK_storeid, since the conflict created earlier used the same primary key for the local record and the record added to the SQL Server database. SQL Server CE Relay Generally, when you have a serial or USB connection to ActiveSync, you cannot connect to other servers on the network using TCP/IP. This means that while you can use RDA when a network or dial-up connection is present, you cannot use RDA with ActiveSync. Release 1.1 of SSCE introduced the SQL Server CE Relay application this acts as a point-to-point proxy between the Pocket PC or HPC 2000 device and the IIS server (see Figure 4.16). By using relay, all connection methods between a Pocket PC and HPC 2000 devices can use RDA. You should note the following limitations in using relay: Relay must have a connection using ActiveSync 3.1 Relay does not support Secure Socket Layer (SSL) encryption or Integrated Windows authentication

34 04-P1914 8/24/ :26 AM Page 167 Remote Data Access 167 Figure 4.16 SQL Server CE relay architecture CONFIGURING SQL SERVER CE RELAY Before starting to configure SSCE Relay ensure that you have your Pocket PC or HPC 2000 connected to a desktop PC using ActiveSync 3.1 using a serial or USB connection. It is best to start by manually configuring SSCE Relay as it is easy to change parameters without having to reconnect your device to ActiveSync. When you have Relay working, you can then configure Relay to start automatically when an ActiveSync connection is made. Relay acts as a proxy server, so you will need to change your RDA code to use a proxy server. You will need to add the line shown in bold to any code that makes a Push, Pull, or SubmitSQL call through the RDA Engine object: cerda.interneturl = " & sserver & _ "/sscepubs/sscesa10.dll" cerda.localconnectionstring = slocalcon ' enable this line if SSCE Relay is used cerda.internetproxyserver = "ppp_ peer:81" ssvrcon = "Provider=sqloledb;DataSource=(local)" ssvrcon = ssvrcon & ";Initial Catalog=Pubs;"