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
, andREADNAMES
. Curly brackets in syntax charts indicate a set of mutually exclusive choices for a keyword. For example, theFILETYPE
keyword can have the valueXLS
orXLSX
. 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. TheName
attribute is required and specifies the command name. The command name can consist of up to three words that are separated by spaces, as inMY EXTENSION COMMAND
, and is not case-sensitive. Command names are restricted to 7-bit ascii characters. TheLanguage
attribute is optional and specifies the implementation language. The default is the Python programming language (Python 2). The choices forLanguage
are Python, R, and Java. For Python code that is implemented in Python 3, specifyLanguage="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 theCommand
element. In this example, the firstSubcommand
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 keywordURL
that specifies the URL of the Excel file. Many native SPSS Statistics commands, such as theFREQUENCIES
command, contain an anonymous subcommand. - Keywords are specified with the
Parameter
element, which is a child of theSubcommand
element. TheParameter
element for theURL
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-inMEANS
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.