Working with Command Syntax

12

Chapter

SPSS provides a powerful command language that allows you to save and automate many common tasks. It also provides some functionality not found in the menus and dialog boxes. Most commands are accessible from the menus and dialog boxes. However, some commands and options are available only by using the command language. The command language also allows you to save your jobs in a syntax file so that you can repeat your analysis at a later date or run it in an automated job with the Production Facility. A syntax file is simply a text file that contains commands. While it is possible to open a syntax window and type in commands, it is often easier if you let the software help you build your syntax file using one of the following methods:

Pasting command syntax from dialog boxes Copying syntax from the output log Copying syntax from the journal file

In the online Help for a given procedure, click the command syntax link in the Related Topics list to access the syntax diagram for the relevant command. For complete documentation of the command language, refer to the SPSS Command Syntax Reference. Complete command syntax documentation is automatically installed when you install SPSS. To access the syntax documentation:
E From the menus choose: Help Command Syntax Reference

297

298 Chapter 12

Syntax Rules
Keep in mind the following simple rules when editing and writing command syntax:

Each command must begin on a new line and end with a period (.). Most subcommands are separated by slashes (/). The slash before the first subcommand on a command is usually optional. Variable names must be spelled out fully. Text included within apostrophes or quotation marks must be contained on a single line. Each line of command syntax cannot exceed 80 characters. A period (.) must be used to indicate decimals, regardless of your Windows regional settings. Variable names ending in a period can cause errors in commands created by the dialog boxes. You cannot create such variable names in the dialog boxes, and you should generally avoid them.

Command syntax is case insensitive, and three- or four-letter abbreviations can be used for many command specifications. You can use as many lines as you want to specify a single command. You can add space or break lines at almost any point where a single blank is allowed, such as around slashes, parentheses, arithmetic operators, or between variable names. For example,
FREQUENCIES VARIABLES=JOBCAT GENDER /PERCENTILES=25 50 75 /BARCHART.

and
freq var=jobcat gender /percent=25 50 75 /bar.

are both acceptable alternatives that generate the same results.

299 Working with Command Syntax

INCLUDE Files

For command files run via the INCLUDE command, the syntax rules are slightly different:

Each command must begin in the first column of a new line. Continuation lines must be indented at least one space. The period at the end of the command is optional.

Unless you have existing command files that already use the INCLUDE command, you should probably use the INSERT command instead since it can accommodate command files that conform to either set of rules. If you generate command syntax by pasting dialog box choices into a syntax window, the format of the commands is suitable for any mode of operation. See the Command Syntax Reference (available in PDF format from the Help menu) for more information.

Pasting Syntax from Dialog Boxes

The easiest way to build a command syntax file is to make selections in dialog boxes and paste the syntax for the selections into a syntax window. By pasting the syntax at each step of a lengthy analysis, you can build a job file that allows you to repeat the analysis at a later date or run an automated job with the Production Facility. In the syntax window, you can run the pasted syntax, edit it, and save it in a syntax file.

To Paste Syntax from Dialog Boxes

E Open the dialog box and make the selections that you want. E Click Paste.

The command syntax is pasted to the designated syntax window. If you do not have an open syntax window, a new syntax window opens automatically, and the syntax is pasted there.

300 Chapter 12 Figure 12-1 Command syntax pasted from a dialog box

Note: If you open a dialog box from the menus in a script window, code for running syntax from a script is pasted into the script window.

Copying Syntax from the Output Log

You can build a syntax file by copying command syntax from the log that appears in the Viewer. To use this method, you must select Display commands in the log in the Viewer settings (Edit menu, Options, Viewer tab) before running the analysis. Each command will then appear in the Viewer along with the output from the analysis. In the syntax window, you can run the pasted syntax, edit it, and save it in a syntax file.

301 Working with Command Syntax Figure 12-2 Command syntax in the log

To Copy Syntax from the Output Log

E Before running the analysis, from the menus choose: Edit Options...

302 Chapter 12 E On the Viewer tab, select Display commands in the log.

As you run analyses, the commands for your dialog box selections are recorded in the log.
E Open a previously saved syntax file or create a new one. To create a new syntax

file, from the menus choose:

File New Syntax E In the Viewer, double-click on a log item to activate it. E Click and drag the mouse to highlight the syntax that you want to copy. E From the Viewer menus choose: Edit Copy E In a syntax window, from the menus choose: Edit Paste

Editing Syntax in a Journal File

By default, all commands executed during a session are recorded in a journal file named spss.jnl (set with Options on the Edit menu). You can edit the journal file and save it as a syntax file that you can use to repeat a previously run analysis, or you can run it in an automated job with the Production Facility. The journal file is a text file that can be edited like any other text file. Because error messages and warnings are also recorded in the journal file along with command syntax, you must edit out any error and warning messages that appear before saving the syntax file. Note, however, that errors must be resolved or the job will not run successfully. Save the edited journal file with a different filename. Because the journal file is automatically appended or overwritten for each session, attempting to use the same filename for a syntax file and the journal file may yield unexpected results.

303 Working with Command Syntax Figure 12-3 Editing the journal file

Delete warnings and error messages before saving and running syntax from the journal file

To Edit Syntax in a Journal File

E To open the journal file, from the menus choose: File Open Other... E Locate and open the journal file (by default, spss.jnl is located in the temp directory).

Select All files (*.*) for Files of Type or enter *.jnl in the File Name text box to display journal files in the file list. If you have difficulty locating the file, use Options on the Edit menu to see where the journal is saved in your system.
E Edit the file to remove any error messages or warnings, indicated by the > sign. E Save the edited journal file using a different filename. (We recommend that you use a

filename with the extension .sps, the default extension for syntax files.)

To Run Command Syntax

E Highlight the commands that you want to run in the syntax window.

304 Chapter 12 E Click the Run button (the right-pointing triangle) on the Syntax Editor toolbar.

or
E Select one of the choices from the Run menu.

All. Runs all commands in the syntax window. Selection. Runs the currently selected commands. This includes any commands

partially highlighted.
Current. Runs the command where the cursor is currently located. To End. Runs all commands from the current cursor location to the end of the

command syntax file. The Run button on the Syntax Editor toolbar runs the selected commands or the command where the cursor is located if there is no selection.
Figure 12-4 Syntax Editor toolbar

Multiple Execute Commands

Syntax pasted from dialog boxes or copied from the log or the journal may contain EXECUTE commands. When you run multiple commands from a syntax window, multiple EXECUTE commands are unnecessary and may slow performance because this command reads the entire data file.

If the last command in the syntax file is a command that reads the data file (such as a statistical or graphing procedure), no EXECUTE commands are necessary and they can be deleted. If you are unsure if the last command reads the data file, in most cases you can delete all but the last EXECUTE command in the syntax file.

305 Working with Command Syntax

Lag Functions

One notable exception is transformation commands that contain lag functions. In a series of transformation commands without any intervening EXECUTE commands or other commands that read the data, lag functions are calculated after all other transformations, regardless of command order. For example:
COMPUTE lagvar=LAG(var1) COMPUTE var1=var1*2

and
COMPUTE lagvar=LAG(var1) EXECUTE COMPUTE var1=var1*2

yield very different results for the value of lagvar, since the former uses the transformed value of var1 while the latter uses the original value.