In This Chapter
Scripting with Sax BASIC for SPSS
Examining BASIC classes and objects for SPSS
Creating global and automatic scripts
You can write BASIC language programs that run inside SPSS. Such programs are known to SPSS as scripts. SPSS has a dialog box specially designed for editing these scripts, running them, and saving them to disk. When you write scripts, you have the advantage that the Sax BASIC language is common and widespread — making it easy to find documentation, both in print form and on the Internet. A good deal of documentation is also available inside the SPSS help system.
Although scripts can be made to work with input data, they primarily work with output data — the data displayed in SPSS Viewer. For example, you can use a script to add items to or delete items from a pivot table. Also, you can write a script to modify a graph after it has been displayed.
This chapter is not a tutorial on programming using the BASIC language. (You can get that information from Internet tutorials and from books on Sax BASIC and Visual BASIC.) This chapter is about the particulars of using BASIC as a scripting language inside SPSS.
You should always start writing a new script by copying an old script that works. SPSS provides a number of starter scripts for you to use for this very purpose. Before you write a script of your own, look through this collection and get familiar with the available scripts. They're complete, working scripts; one of them may already perform the task you're trying to do.
The following Web site is an excellent source for examples. They are organized into categories, and you may find the exact script you're looking for. If not, you can get one that is similar and modify it to do what you want:
http://pages.infinit.net/rlevesqu/SampleScripts.htm
Scripting can be used to automate lots of things, but it does not provide magic powers for you to do things you cannot do manually. All the things you can do with a script, you can also do with mouse controls. Before writing a script, you should step through the procedure with the mouse so you know exactly what you want the script to do.
Note
In the SPSS system, only both BASIC and Python programs are referred to as scripts. Although the Syntax language fits the technical definition of a scripting language, SPSS considers BASIC as its primary scripting language and Python as an optional add-on scripting language.
The dialect of the BASIC language used in SPSS is common and known generally as Sax BASIC. Sax BASIC uses a few of the fundamental concepts of object-oriented programming. It doesn't use many, but you need to have an understanding of the little bits it does use.
Through some process that I don't quite get, object-oriented programming has gained the reputation of being difficult to understand. It isn't. It's easy to understand, but it is clumsy to explain — it's sort of like describing an accordion without using your hands. But let me try.
The roads and streets are full of cars. There are many different kinds and shapes of cars, but they are all cars. That means the word car is a specific classification of vehicle. A car, then, is a class. Fred's old, beat-up, blue 1968 Chevy is a specific car. It is an object of the class known as car. Every actual car is an object.
In the preceding paragraph I made reference to Fred's car. It was only a reference; not the actual object.
If you have all that — class, object, and reference — you now understand every fundamental that you need to be able to understand object-oriented programming. If you find yourself getting confused about which is what, just remember Fred's old, beat-up, blue Chevy. That's what I do, and it works for me.
You already know what a pivot table is (if not, it's in the glossary). And you know that although lots of pivot tables of different sizes and types exist, they're all pivot tables. That makes a pivot table a classification — or, in programming terms, a class. A specific pivot table is an object.
In SPSS scripts, a pivot table is an object of the class named PivotTable. You can't copy an entire pivot table into your program, but you can get a reference to it. Think of the reference as a kind of address that provides access to the pivot table when you want to refer to it. In your script, you can create a reference to a pivot table with a statement like the following:
Dim pt as PivotTable
In this statement, the pt variable is created as a reference to an object of the PivotTable class. The class name, PivotTable, is already defined for you by SPSS. Class names are already defined for charts, documents, data cells, and several other things. (You can find a complete list in the next section as Table 18-1.) The reason the silly word Dim is used to declare a variable has to do with the boring history of the BASIC language. I chose pt to be the name of the reference for no particular reason; you can choose any name you like. The names used for references in the example programs supplied by SPSS are made by sticking obj in front of the class name, as in the following:
Dim objPivotTable as PivotTable
A reference is not an object, but the only thing it can ever do is refer to an object, so the name of a reference beginning with "obj" should not be completely misleading.
Note
A new reference declared this way does not refer to an actual pivot table object. Yet. For it to do so, you have to select a PivotTable object and initialize your new reference variable with its address.
A few classes are built into Sax BASIC; you encounter them in the sample scripts. For example, a class named String is used to declare string variable references such as the following:
Dim mystring as String
Or you can define the reference to an Integer like the following:
Dim myinteger as Integer
A number of classes are defined and ready for you to use in your program, as listed in Table 18-1. All names of all classes (with the exception of PivotTable) begin with an uppercase I. All the references in the example programs begin with lowercase letters.
One member of the list is special: The reference name objSpssApp, which is of the class ISpssApp, has already been declared and initialized. It's ready to go in every program; it acts as your access point to objects in all the other classes. By using the properties and methods of objSpssApp, you can acquire objects in all the other classes.
Table 18.1. Predefined Classes You Can Use in Your Program
Class Name | What an Object of This Class Refers To | Name Used in the Example Programs for References |
|---|---|---|
Pivot table |
| |
| Entire SPSS application |
|
| Chart or graph |
|
| Data cells |
|
| Data document |
|
| Dimension |
|
| Documents |
|
| Footnotes |
|
| SPSS file information |
|
| Output item |
|
| Collection of output items |
|
| Row or column labels |
|
| Layer labels |
|
| SPSS options |
|
| Viewer document |
|
| Printer options |
|
| Pivot manager |
|
| Text |
|
| Syntax document |
|
Each class has a unique set of properties and methods by which you can access its internal information. A property is a variable that is part of the class definition. Each object of a class has its own set of values for its properties. Each property has read and write permission settings. Your program can use some properties only to read values from the object, other properties to write values into the object, and still other properties for both. Methods are procedures associated with the object, making it possible for you to execute a set of instructions associated with the object.
To be able to do anything with an object, you need to know which properties and methods are available. You can find out about any particular class definition by following these steps:
Choose File
New
ScriptThis opens the dialog box used to edit scripts.
Choose Help
IBM SPSS Statistics Object Help.The dialog box shown in Figure 18-1 appears, showing you the relationship among classes as clickable buttons.
Warning
Some versions of the Vista operating system will get an error with this operation. A patch should be available from Microsoft.
Click the button representing the class you want to know about.
A window appears with a brief description of the class. This same window may contain other information, such as example code that shows how to declare a reference and how to initialize the reference with a specific object.
Click Properties or Methods button to get more information.
You are presented with a list of either property or method names.
Select a name from the list and then click Display.
A full description of the property or method appears, along with the syntax of the code you can use to access it.
In the class-name layout shown in Figure 18-1, you can see the relationships among the classes. Every class (except the Application class at the very top) is derived from another class. It's more of that object-oriented programming stuff. These relationships are important. For example, the OutputItem class is a special version of the OutputDocument class. That is, an OutputItem is an OutputDocument, but with some special features added. They've devised some special object-oriented words for all this ("polymorphism" and "inheritance"), but that's all just nerd mouthwash.
The first step in creating a script is to choose File
But this skeletal start is not all the help that's available, nor is it all the help you should want. The BASIC programming language is a bit strange; my advice to you is to start with a working example. You can find examples in several places on the Web, such as the location mentioned earlier in this chapter. You will also find some examples that were installed with your SPSS software. If you used the default installation directory, you can find them in the following location:
c:Program FilesSPSSIncPASWStatistics18Samples
Note
You may have to browse around a bit to find the script that's most like the one you want to produce. These are not tiny scripts; each one has several lines of code and is filled with comments explaining how it works and how you might want to change it to make it do what you'd like.
After you have found a script you want to use for your starter, save it immediately under a new name. You don't want to save it under the same name because your changed script will overwrite the starter script — and then you won't be able to get the starter back if you need it.
While you are editing a script, you need to save it to disk from time to time for safety, and then save it again when you're finished. Your script file can be stored anywhere, but it should have the suffix .wwd (or .WWD, case doesn't matter) so you can load it into SPSS and use it again.
You can configure scripts to execute automatically whenever output is created. There are two ways to do it. You can schedule a script to run triggered by all output, and you can schedule scripts to run triggered by specific types of output. Both ways are scheduled by choosing Edit
First, you can set a single script to execute automatically on all data output. To do this, enter the name of the script file as the Base Autoscript in the dialog. This script will execute before any other automatic script scheduled for the data.
Second, you can set scripts to execute automatically on specific types of output from specific commands. IBM SPSS Statistics has hundreds of discrete triggers, and each one can be assigned its own script. You do it by using the scrollable panels at the bottom of the dialog box in Figure 18-3.
Syntax Language statements control every action that SPSS takes. You can use the panel on the left to select a Syntax Language command; you can (optionally) assign a script to that command and have the script run whenever the command is executed. Every time you make a selection in the panel on the left, the panel on the right becomes a list of specific actions that can result from running that command; you can choose the specific action and attach a script to it.