GoldenGate Developer's Manual For Macromedia Authorware

Transcription

1 GoldenGate Developer's Manual For Macromedia Authorware Integration New Media Inc

2 Contents Contents 2 Overview 4 What the GoldenGate Client Xtra can do 4 What is not supported 5 System requirements 6 Client Xtra 6 Macintosh version 6 Windows version 6 Server 6 Using the GoldenGate Client Xtra 7 Initializing the GoldenGate Client 7 Creating an Instance of GGConnection 7 Creating an Instance of GGDBE 7 Example 7 Creating a recordset 8 Creating instances of GGRecordSet 8 Creating instances of GGSQLQueryRS 8 Managing data 8 Selecting records 8 Selecting all the records of a table 8 Selecting records that match specific criteria 9 Selecting records by executing an SQL Query 9 Browsing through a recordset 9 Checking the position of the current record 10 Checking the size of the recordset 10 Reading data from the current record 10 Reading one or more record at a time 10 Adding records (using GGRecordSet) 11 Adding records (using GGSQLQueryRS) 11 Modifying records (using GGRecordSet) 11 Modifying records (using GGSQLQueryRS) 11 Deleting records (using GGRecordSet) 12 Deleting records (using GGSQLQueryRS) 12 Cleaning-up 12 GoldenGate Developer's Manual 2

3 Checking for errors 12 Appendix: Controlling dialup 14 Index 15 Apple, Mac and Macintosh are trademarks or registered trademarks of Apple Computer, Inc. Macromedia, Authorware, Director and Xtra are trademarks or registered trademarks of Macromedia, Inc. in the United States and/or other countries. Microsoft, Windows and Windows NT are trademarks or registered trademarks of Microsoft Corporation, registered in the U.S. and/or other countries. Other trademarks, trade names and product names contained in this manual may be the trademarks or registered trademarks of their respective owners, and are hereby acknowledged. GoldenGate Developer's Manual 3

4 Overview At the heart of GoldenGate, there is: The GoldenGate Server, who is responsible of managing your databases and answering to commands from GoldenGate Clients. One or more GoldenGate Clients who accept commands from the Authorware pieces they are linked to. They execute the commands by communicating with the GoldenGate Server through the GoldenGate Client Xtra and a TCP/IP network. V12-DBE Online overview What the GoldenGate Client Xtra can do This is a brief overview of what the GoldenGate Client Xtra can do. For a complete list of the GoldenGate Client Xtra methods, see the Golden Gate Client Xtra Reference Manual. Manage the connection to the server: Open or Close the connection to the server with New(GGConnection). Build a record selection: specify criteria with SetCriteria, optionally specify a sorting order with OrderBy then call Select to actually send the query and bring one record at a time to the Client. Multiple criteria can be defined with operators such as = (matches exactly),<> (does not match), > (Greater), >= (Greater or equal), < (Smaller), <= (Smaller or equal), Starts (records that start with the specified string), Contains (records that contain the specified string), Start (records that start with a specified string). SelectAll can eventually be called to retrieve all the records of a table. Manage the selection: SelectCount returns the number of records in the selection. GetPosition returns the position of the cursor in the current record. GoldenGate Developer's Manual 4

5 Go, GoNext, GoPrevious, GoFirst, GoLast allow browsing across the selection. Read and write records: Read the current record's fields data with GetField or GetMedia. Read multiple records at once into a string, a list or a property list with GetSelection. Delete the current record with DeleteRecord. Modify the current record with SetField (see Using the GoldenGate Client Xtra to learn how to combine SetField with AddRecord, EditRecord and UpdateRecord). Execute an SQL query with New(GGSQLQueryRS). What is not supported Although GoldenGate uses advanced tools like ODBC on the server side, you will never need to invoke the ODBC 's methods yourself. Instead, you link the GoldenGate Client Xtra to your Authorware piece and use its methods. However, not all ODBC methods can be used from the GoldenGate Client Xtra, mostly because such features would be irrelevant to use over the Internet, or sometimes insecure. The GoldenGate Client Xtra does not support the following: Create a new database through Scripting Create a new table through Scripting Import/export files Change the password of a database Lock/unlock manually records of a table (this feature depends on the database manager on the server side). GoldenGate Developer's Manual 5

6 System requirements Client Xtra Macintosh version Power Macintosh or PPC 100Mhz or faster with System or later with 32Mb of available RAM. The hard disk space required by the Xtra is negligible. On the Macintosh, GoldenGate (basically, any Xtra) will share the same memory allocation as Macromedia Authorware. For simple database applications, you do not need to change the Authorware piece s memory allocation. For more advanced projects, you might want to consider increasing the memory allocation on the projector. Windows version Any PC with Intel Pentium 100Mhz or later, running Windows 95/98/ME/ NT4.0/2000 (32-bit) or later with 32Mb of available RAM. The hard disk space required by the Xtra is negligible. Server Any PC running Windows NT 4.0 or 2000 with 128Mb RAM. Recommended: 256Mb RAM. GoldenGate Developer's Manual 6

7 Using the GoldenGate Client Xtra Initializing the GoldenGate Client When your Authorware piece starts, or when your piece needs to access a GoldenGate database, you will need to initialize the client by: Creating an Instance of GGConnection Create an instance of GGConnection and assign it to a global variable. Example to initiate a connection: gcx := NewObject("GGConnection", " ", 2003, "guest", "anonymous") error checking (GGStatus()) In this example, the parameters , 2003, guest and anonymous are respectively the server's IP number, the server's port number, the user name and the user password. See details in the GoldenGate Client Xtra Reference Manual. It is highly recommended to check whether or not NewObject succeeded by checking the value of objectp(gcx) as shown above. Creating a GGConnection instance does open a connection to the server. Creating an Instance of GGDBE Create an instance of GGDBE and assign it to a global variable. Example to open a remote database: gdb := NewObject( GGDBE", gcx, "catalog") GGError() In this example, the parameters gcx and catalog are respectively the references to the GGConnection instance and the remote database name. See details in the GoldenGate Client Xtra Reference Manual. It is highly recommended to check whether or not NewObject succeeded by checking the value of GGError() as shown above. Example A typical GoldenGate Client initialization script looks like this: gcx := NewObject ("GGConnection"", " ", 2003, "guest", "anonymous) GGError() gdb := NewObject ("GGDBE", gcx, "catalog") GGError() GoldenGate Developer's Manual 7

8 Recordsets are the equivalent of V12 Database Engine selections. Both terms can be used interchangeably with GoldenGate. Creating a recordset A recordset is a collection of records. There are two ways of creating recordsets: - V12 database engine-like: Create an instance of GGRecordSet to open a table. - SQL-like: Create an instance of GGSQLQueryRS to directly execute an SQL query (create a recordset, add, edit or delete a record). Creating instances of GGRecordSet Once the connection is opened and a database is opened, create as many instances of GGRecordSet as needed by your project, and assign them to global variables. grs := NewObject("GGRecordSet", gdb, "Articles") gdb is the global variable that was assigned to the GGDBE instance. Articles is the name of the table to open. Creating instances of GGSQLQueryRS Once the connection is opened and a database is opened, execute as many instances of GGSQLQuery as needed by your project, and assign them to global variables. grs := NewObject("GGSQLQueryRS", gdb, "SELECT name, price FROM catalog WHERE price >=?", [150.00]) gdb is the global variable that was assigned to the GGDBE instance. SELECT is the SQL Query and [150.00] is the query parameter of the SQL Query to execute. Managing data Only the general use of each GoldenGate Client Xtra method is described below. See details in the GoldenGate Client Xtra Reference Manual. Keep in mind that it is very important to check for possible errors after each call to the GoldenGate Client. Selecting records Before reading or modifying any data, you must have a valid recordset and a valid current record. The recordset is created by either SelectAll (all records of a table) or Select (only records that match specific criteria). Selecting all the records of a table SelectAll selects all the records of a table. It can be preceded by a call to OrderBy to specify a particular sorting order. CallObject(gRS, OrderBy, "LastName") CallObject (grs, SelectAll ) GoldenGate Developer's Manual 8

9 Selecting records that match specific criteria Select selects the records that match specific criteria. It must be preceded by calls to SetCriteria and optionally to a call to OrderBy. This example selects the records of the table gprodstable whose price is at most $100: CallObject (grs, SetCriteria, ["price", "<=", 100]) CallObject (grs, Select ) This example selects all the records of the table gprodstable who's price is at most 100$ and sorts the recordset by order of product name: CallObject (grs, SetCriteria,["price", "<=", 100]) CallObject (grs, OrderBy,"prodName") CallObject (grs, select ) This example selects all the records of the table gprodstable whose price is between $50 and $200: CallObject (grs, SetCriteria,[["price", ">=", 50], "AND", ["price", "<=", 200]]) CallObject (grs, Select ) Selecting records by executing an SQL Query Instead of using an instance of GGRecordSet, you can use an instance of GGSQLQuery. You can build a simple recordset in a single call or create a more complex recordset based on the database manager's ability to resolve relations between tables. This example selects all the records of the table named catalog whose price is between $50 and $200 and sorts the recordset by order of product name: GRS := NewObject("GGSQLQueryRS", gdb, "SELECT * FROM catalog WHERE price >=? AND price <=? ORDERBY name",[50,200]) Browsing through a recordset To read, write or delete a record, you must first designate it as the current record. Upon the creation of a recordset (by either SelectAll or Select), the first record of the recordset is set to be the current record. To browse through a recordset, call the GoFirst, GoPrevious, GoLast, GoNext and Go methods. These methods can be used with either an instance of GGRecordSet or an instance of GGSQLQueryRS. -- assume that the recordset contains 100 records CallObject(gRS, Go,47) -- current rec. becomes #47 CallObject(gRS, GoNext ) -- current rec. becomes #48 CallObject(gRS, GoNext ) -- current rec. becomes #49 CallObject(gRS, GoLast ) -- current rec. becomes #100 CallObject(gRS, GoPrevious ) -- current rec. becomes #99 GoldenGate Developer's Manual 9

10 CallObject(gRS, GoFirst ) -- current rec. becomes #1 Checking the position of the current record At any time, you can read the position of the current record within the recordset with GetPosition. This method can be used with either an instance of GGRecordSet or an instance of GGSQLQueryRS. pos := CallObject (grs, GetPosition ) This is a handy method in situations such as: if CallObject (grs, GetPosition ) > 1 then CallObject (grs, GoPrevious ) This script sets the current record's preceding record as the new current record, unless the current record is already the first one in the recordset. Checking the size of the recordset To check how many records the recordset contains, call SelectCount. This method can be used with either GGRecordSet and GGSQLQueryRS instances. count := CallOject(gRS, SelectCount ) If the recordset is empty, SelectCount returns 0. Reading data from the current record To read the value of a specific field from the current record, call GetField. This applies to fields of type String, Integer, Float, Date and Binary (Media). This method can be used with either GGRecordSet and GGSQLQueryRS instances. username := CallObject(gRS, GetField,"FirstName") This example retrieves the content of the field FirstName in the current record. Optionally, for fields of type Integer, Float and Date, you can specify the format of the result. Result := GetField(gRS, "price", "9,999.99") into field "theprice" Assuming the value in field "price" is 1245, this example places the string "1,245.00" in the member named "theprice". Reading one or more record at a time To read one or more records at a time, call GetSelection. This method can be used with either GGRecordSet and GGSQLQueryRS instances. Result := GetSelection(#LITERAL, 1, 8, ["LastName", "FirstName"], ", ", RETURN) into field "myscrollfield" This example retrieves the contents of the fields "LastName" and "FirstName" of records 1 through 8 of the recordset to the member "myscrollfield", as in: Curie, Marie Einstein, Albert GoldenGate Developer's Manual 10

11 Gödel, Kurt Karp, Richard McLuhan, Marshall Neumann, John Von Shannon, Claude Turing, Alan The recordset must have been previously built by Select, SelectAll or new(ggsqlqueryrs). Adding records (using GGRecordSet) Adding a record to a table requires: a call to AddRecord as may calls to SetField as you wish a call to UpdateRecord The record is actually added to the database (i.e., on the server) by UpdateRecord. No network activity is initiated by AddRecord and SetField. If grs contains a recordset before the call to UpdateRecord, this recordset becomes the new added record. Adding records (using GGSQLQueryRS) A record can be added to a table by executing a direct SQL query. grs := NewObject("GGSQLQueryRS", gdb, "INSERT INTO client (LastName, FirstName) VALUES (?,?)", ["Testaburger", "Wendy"]) Modifying records (using GGRecordSet) Modifying the current record requires: a call to EditRecord as may calls to SetField as you wish a call to UpdateRecord The record is actually modified by UpdateRecord. No network activity is initiated by EditRecord, SetField and SetMedia. Modifying records (using GGSQLQueryRS) One or more records can be modified by executing a direct SQL query. Example (modify one record): grs := NewObject("GGSQLQueryRS", gdb, "UPDATE client SET FirstName =? WHERE LastName =?", ["Wendy","Testaburger"]) Example (modify all records): grs := NewObject("GGSQLQueryRS", gdb, "UPDATE product SET price = price *?", [1.12]) GoldenGate Developer's Manual 11

12 Deleting records (using GGRecordSet) Call DeleteRecord to delete the current record. CallObject(gRS, DeleteRecord ) DeleteRecord immediately initiates a network connection to instruct the server to delete the current record. Deleting records (using GGSQLQueryRS) One or more records can be deleted by executing a direct SQL query. Example (delete one record): grs := NewObject("GGSQLQueryRS", gdb, "DELETE FROM client WHERE LastName =? AND FirstName =?", ["Testaburger", "WENDY"]) Example (delete all records): grs := NewObject("GGSQLQueryRS", gdb, "DELETE FROM client") Cleaning-up Cleaning-up before quitting a project is necessary to inform the GoldenGate Server to remove the Client from the list of active connections, and also to free up memory on the server. To free up the GGConnection, GGRecordSet, GGSQLQueryRS and GGDBE instances, call Authorware s DeleteObject() function. This also closes the current connection. DeleteObject(gRS) DeleteObject(gdb) Checking for errors Always make sure to check for errors after calling the GoldenGate Client Xtra methods. Actually, this is a very good programming practice known as defensive programming that must be applied to GoldenGate, other Xtras as well as to your internal scripts. Typically, you would have a generic calculation such as: if GGStatus() then -- GGStatus() is 0 if no error GGError() -- show explicit error message and you would call it after every call to the GoldenGate Client Xtra. CallObject (grs, SetCriteria,["City", "=", "Paris"]) GGError() CallObject(gT, mselect ) Optionally, you take advantage of CheckGGError s return value to decide how to continue the execution of your handler. gdb := NewObject("GGDBE", gcx, "mydatabase") GoldenGate Developer's Manual 12

13 if NOT CheckGGError() then grs := NewObject("GGRecordSet", gdb, "mytable") end if This script attempts to create a table instance only if the database instance was successfully created. GoldenGate Developer's Manual 13

14 Appendix: Controlling dialup GoldenGate Client Xtra assumes that a valid TCP/IP network connection exists on the computer it is running on. That connection is available either permanently through the computer's TCP/IP network adapter, or possibly through a dial-up modem connection. If a dial-up connection is assumed and no connection is actually established, the Golden Gate Client Xtra fails with a Network Connection Error as soon as OpenConnection is called. To avoid this, you may want to control the end-user's computer dialup connectivity with a third party Xtra such as DirectConnection Xtra ( ). Below is a summary of DirectConnection Xtra's methods, which may be useful in a dial-up situation: use dcdial(connectionname) to open a dialup connection using the connectionname configuration of the end-user's computer. You can also use dcdial() in conjunction with dcgetdefaultinternetconnection() to open the default dialup configuration. use dchangup() to close a dialup connection. use dcgetconnectioninfo()and dcgetactiveconnections() to detect if a network connection is open. use dcgetconnectionstatus() to test the current network connection. use dccreateconnection()to launch a profile creation wizard. GoldenGate Developer's Manual 14

15 Index A Adding Records, 11 B Browsing, 9 Browsing Through a Selection, 9 C Checking for Errors, 12 Cleaning-up, 12 Controlling Dialup, 14 D Deleting Records, 12 Dialup Connections, 14 DirectConnection Xtra, 14 E Errors Checking for, 12 G GGConnection, 7 Creating Instance, 7 GGDBE, 7 Clean-Up, 12 Creating Instance, 7 GGRecordset Creating Instance, 8 GGRecordSet, 8 Clean-Up, 12 GGSQLQueryRS, 8 GGSQLQueryRS Clean-Up, 12 Creating Instance, 8 GoldenGate Client Xtra What it can do, 4 M Methods AddRecord, 11 DeleteRecord, 12 EditRecord, 11 GetField, 10 GetPosition, 10 GetSelection, 10 Go, 9 GoFirst, 9 GoLast, 9 GoNext, 9 GoPrevious, 9 New, 7, 8 OpenConnection, 14 OrderBy, 9 Select, 8, 9 SelectAll, 8, 9 SelectCount, 10 SetCriteria, 9 SetField, 11 UpdateRecord, 11 Modifying Records, 11 R Reading Data, 10 S Selecting Records, 8 All, 8 Partial, 9 System Requirements, 6 System Requirements, 6 GoldenGate Developer's Manual 15