| Although the SQL you'll be using to control the database will be mostly universal and understood by many different database systems, there are some specific methods you'll need to use to work with Arca, as there are with any scripting Xtra. For starters, you need to create an instance of the Xtra and store it in a global variable. From there, all of the methods of the Xtra will be available through the global variable. Because the database should always be available while the application is running, instantiating the Xtra within the movie's startMovie handler will work best. 1. | In the scripts cast, double-click to open the Main Script movie script so that you can add the following code to the startMovie handler.
_global.myDB = new(xtra "arca") err = _global.myDB.openDB(_movie.path & "exercise") errCode = err.errorMsg if errCode = 604 then makeDB() else if errCode <> 0 then showError(errCode) end if
Add the code after the Lingo currently in the handler that sets up the other global variables.
First, Arca is instantiated into the myDB global variable. In the next line, the openDB() method of the Xtra is used to try and open the database named exercise located in the same folder as the movie. The result of this operation is returned, in a property list form, to the local variable err.
Note The Lingo _movie.path returns the path to the Director movie on your hard drive. Using _movie.path is a good way to place files, such as the database file, in the same folder as your movie. Having the result of the openDB operation returned in a property list is a function of how the Arca Xtra works. Considering that you have yet to create the exercise database, calling the openDB method on it is going to produce an error, which will be returned in the property list to the err variable, as shown.
err = [#errorMsg: 604]
As you may recall from using property lists when creating a getPropertyDescriptionList handler, property lists store their data in a property:value pair. In Lingo you can access the value of the property using dot notation, and the property name as is done in the next line of the code.
the_value = property_list.property_name errCode = err.errorMsg
When this executes, the local variable errCode will contain whatever numeric error code is returned in the property list. Note that if no error occurs, the error code will be 0, but the property list is still returned.
Next, an if statement tests to see if the errCode is 604 and calls the makeDB method if it is. If the error is not 604 then the else statement is executed, which does a further to check to see if errCode is anything but 0. If the errCode is not 0 then the showError method is called, with errCode being sent as a parameter.
Many error codes can be generated by the Xtrathey can be found in the documentationbut error code 604 specifically means, "Can not find the database file." If the database file can't be found, you can assume it hasn't been created yet, so a call to the makeDB method is madewhich you will write next, along with the showError method.
| 2. | After the startMovie handler, add the following createDB and showError methods.
on makeDB err = _global.myDB.createDB(_movie.path & "exercise") errCode = err.errorMsg if errCode = 0 then --create table else showError(errCode) end if end on showError errCode errString = _global.myDB.explainError(errCode) _player.alert(errString) end
As you can see, all that makeDB does is call the createDB method of the Xtra, to create the database named exercise in the same folder as the movie. Note that this is exactly the same manner in which you used the openDB method of the Xtra, within the startMovie handler.
Again, any error (including no error at all) is returned and the numeric error code retrieved from the property list. An if statement then checks to see if there has been an error. If there is no error (errCode = 0), nothing happensyet. The create table comment will be replaced later, when you create the table for the database.
If there is an error, then the showError method is called and passed the numeric error code. Within the showError method all that is happening is that you are calling the explainError method of the Arca Xtra, and passing it the numeric error code that you retrieved. This method of the Xtra takes the error code and returns a human-readable string. The string is sent to the alert method, which produces a dialog box to the user as shown here, displaying the 604 error:
| 3. | Add the stopMovie handler to the script, as shown:
on stopMovie err = _global.myDB.closeDB() errCode = err.errorMsg if errCode <> 0 then showError(errCode) end
Calling the closeDB method of Arca on stopMovie will insure that the database file is closed when the movie is not playing. By making sure you close the database when it's not in use, you will help prevent database corruption, such as what could happen if you close Director with the database still open.
| 4. | Close the script window, then rewind and play the movie.
If everything is going according to plan, you should notice absolutely nothing new. The movie will play exactly as it did before adding the new code.
When the movie starts, the Arca Xtra is instantiated into the myDB global variable and then the openDB method is called. When it fails, because it can't find the file, makeDB is called, which executes the createDB method of the Xtra, creating the database file named exercise in the movie's folder on your hard drive.
If you look in your project_two folder, you should see a file named exercise with a size of 0 K. This is the database file you just created. Its size is 0 K because it has no data in it yet. Nor does it even have anything to store data in. Within a database file, data is stored in a table, or even multiple tables. To be able to store data in the exercise database, you will first need to define a table. For this, a little SQL is needed.
| 5. | Stop the movie and open your project_two folder. Find and delete the exercise database file created by running the movie.
In the next section you'll be adding a couple of lines to the if statement within the makeDB method that will create the table for the database. If you don't first erase the file, the initial call to openDB, within the startMovie handler, won't generate an error, so the makeDB method won't run, and the table won't be created.
|
|
