XML specification of the extension command syntax

To create an extension command, you must specify the syntax for the command. The syntax consists of the subcommands, keywords, and keyword values that define the command. Syntax for extension commands is specified with XML. As an example, consider a Python extension command that gets an Excel file from a user-specified URL and opens a specified sheet from the Excel file in IBM® SPSS® Statistics.

The inputs to this example command are as follows:

URL: Required parameter that specifies the URL of the Excel file.
FILETYPE: Optional parameter that specifies the file type. Possible values are XLS or XLSX, and the default is XLS.
SHEETNUMBER: Optional parameter that specifies the number of the sheet to open in SPSS Statistics. The default is sheet 1.
READNAMES: Optional parameter that specifies whether to use values in the first row of the sheet as variable names in the resulting SPSS Statistics dataset. Possible values are "ON" and "OFF", where "ON" specifies to use the values in the first row and is the default.

Before you create the XML representation of the syntax, it's always a good idea to construct a syntax chart for your command. The syntax chart specifies the command name, keywords, and keyword values that are available with the command. In that regard, the documentation for every native SPSS Statistics command includes a syntax chart, which provides a quick reference of the specifications for the command.

The syntax chart for the example command is as follows:


MYORG GETURL EXCEL URL = "URL specification"
[/OPTIONS ]
   [FILETYPE = {XLS**}]
               {XLSX }
   [SHEETNUMBER = {1**    }]
                  {integer}
   [READNAMES = {ON**}]
                {OFF }

The name of the command is MYORG GETURL EXCEL.
The command contains a single subcommand that is named OPTIONS that contains the optional inputs. Subcommands are preceded by a forward slash.
The OPTIONS subcommand includes the following keywords: FILETYPE, SHEETNUMBER, and READNAMES. Curly brackets in syntax charts indicate a set of mutually exclusive choices for a keyword. For example, the FILETYPE keyword can have the value XLS or XLSX. A double asterisk in a syntax chart indicates the default value for a keyword. Square brackets in syntax charts indicate optional elements of the syntax.

Notation conventions for syntax charts are described in the Commands topic, under Reference > Command Syntax Reference > Universals, in the SPSS Statistics Help system.

The XML representation of the syntax chart for the MYORG GETURL EXCEL extension command is as follows:


<Command xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="http://www-01.ibm.com/software/analytics/spss/xml/extension-1.0.xsd" 
Name="MYORG GETURL EXCEL" Language="Python">
	<Subcommand Name="" IsArbitrary="False" Occurrence="Optional">
		<Parameter Name="URL" ParameterType="TokenList"/>
	</Subcommand>
	<Subcommand Name="OPTIONS" Occurrence="Optional">
		<Parameter Name="FILETYPE" ParameterType="Keyword"/>
		<Parameter Name="SHEETNUMBER" ParameterType="Integer"/>
		<Parameter Name="READNAMES" ParameterType="Keyword"/>
	</Subcommand>
</Command>

The top-level element, Command, names the command. Subcommands are children of this element. The Name attribute is required and specifies the command name. The command name can consist of up to three words that are separated by spaces, as in MY EXTENSION COMMAND, and is not case-sensitive. Command names are restricted to 7-bit ascii characters. The Language attribute is optional and specifies the implementation language. The default is the Python programming language (Python 2). The choices for Language are Python, R, and Java. For Python code that is implemented in Python 3, specify Language="Python" LanguageVersion="3". Support for Python 3 requires IBM SPSS Statistics release 24 or higher.
Subcommands are specified with the Subcommand element, which is a child of the Command element. In this example, the first Subcommand element has an empty string for a name. Because it doesn't have a name, it is referred to as the anonymous subcommand. A command can have only a single anonymous subcommand. The anonymous subcommand is typically used to specify global keywords for the command. In this example, the anonymous subcommand contains the single keyword URL that specifies the URL of the Excel file. Many native SPSS Statistics commands, such as the FREQUENCIES command, contain an anonymous subcommand.
Keywords are specified with the Parameter element, which is a child of the Subcommand element. The Parameter element for the URL keyword is specified as a TokenList, which is an arbitrary list of comma separated or blank separated values. Although the actual URL is a single string, a URL that exceeds the allowed length of a string literal needs to be broken up into a set of strings.

A complete specification of the XML schema for defining extension commands is provided in the SPSS Statistics Help system under Reference > Extension Schema. A copy of the extension schema, extension-1.0.xsd, is installed with SPSS Statistics, at the root of the installation directory. Numerous XML specification files for extension commands are installed with SPSS Statistics and might be useful as examples. The files are in the location where extension commands are installed on your computer. To view the location, run the SHOW EXTPATHS syntax command from within SPSS Statistics. The output displays a list of locations under the heading "Locations for extension commands". The files are installed to the first writable location in the list.

Naming conventions and name conflicts

Extension commands take priority over built-in command names. For example, if you create an extension command that is named MEANS, the built-in MEANS command is replaced by your extension. Likewise, if an abbreviation is used for a built-in command and the abbreviation matches the name of an extension command, the extension command is used. Abbreviations are not supported for extension commands.
To reduce the risk of naming conflicts with built-in commands or commands that are created by other users, you might want to use two- or three-word command names, where the first word specifies your organization.
There are no naming requirements for the file that contains the XML specification of the syntax. As with choosing the name of the extension command, take care when you choose a name to avoid conflicting XML file names. A useful convention is to use the same name as the Python module, R source file, or Java class file (or JAR file) that implements the command.
The installed extension commands are read when SPSS Statistics is launched, but they can also be defined during a session with the EXTENSION command.

Color coding and auto-completion in the syntax editor

The XML syntax specification file contains all of the information that is needed to provide color coding and auto-completion for your extension command in the SPSS Statistics Syntax Editor. Both color coding and auto-completion are available after the extension command is installed.