Overview (DEFINE-!ENDDEFINE command)

DEFINE—!ENDDEFINE defines a program macro, which can then be used within a command sequence. A macro can be useful in several different contexts. For example, it can be used to:

• Issue a series of the same or similar commands repeatedly, using looping constructs rather than redundant specifications.
• Specify a set of variables.
• Produce output from several program procedures with a single command.
• Create complex input programs, procedure specifications, or whole sessions that can then be executed.

A macro is defined by specifying any part of a valid command and giving it a macro name. This name is then specified in a macro call within a command sequence. When the program encounters the macro name, it expands the macro.

In the examples of macro definition throughout this reference, the macro name, body, and arguments are shown in lowercase for readability. Macro keywords, which are always preceded by an exclamation point (!), are shown in uppercase.

Options

Macro Arguments. You can declare and use arguments in the macro definition and then assign specific values to these arguments in the macro call. You can define defaults for the arguments and indicate whether an argument should be expanded when the macro is called. See the topic Macro Arguments (DEFINE-!ENDDEFINE command) for more information.

Macro Directives. You can turn macro expansion on and off. See the topic Macro Directives (DEFINE-!ENDDEFINE command) for more information.

String Manipulation Functions. You can process one or more character strings and produce either a new character string or a character representation of a numeric result. See the topic String Manipulation Functions (DEFINE-!ENDDEFINE command) for more information.

Conditional Processing. You can build conditional and looping constructs. See the topic Conditional Processing (DEFINE-!ENDDEFINE command) for more information.

Macro Variables. You can directly assign values to macro variables See the topic Direct Assignment of Macro Variables (DEFINE-!ENDDEFINE command) for more information.

Basic Specification

All macros must start with DEFINE and end with !ENDDEFINE. These commands identify the beginning and end of a macro definition and are used to separate the macro definition from the rest of the command sequence.

• Immediately after DEFINE, specify the macro name. All macros must have a name. The name is used in the macro call to refer to the macro. Macro names can begin with an exclamation point (!), but other than this, follow the usual naming conventions. Starting a name with an ! ensures that it will not conflict with the other text or variables in the session.
• Immediately after the macro name, specify an optional argument definition in parentheses. This specification indicates the arguments that will be read when the macro is called. If you do not want to include arguments, specify just the parentheses; the parentheses are required, whether or not they enclose an argument.
• Next specify the body of the macro. The macro body can include commands, parts of commands, or macro statements (macro directives, string manipulation statements, and looping and conditional processing statements).
• At the end of the macro body, specify !ENDDEFINE.

To invoke the macro, issue a macro call in the command sequence. To call a macro, specify the macro name and any necessary arguments. If there are no arguments, only the macro name is required.

Operations

• When the program reads the macro definition, it translates into uppercase all text (except arguments) not enclosed in quotation marks. Arguments are read in upper- and lowercase.
• The macro facility does not build and execute commands; rather, it expands strings in a process called macro expansion. A macro call initiates macro expansion. After the strings are expanded, the commands (or parts of commands) that contain the expanded strings are executed as part of the command sequence.
• Any elements on the macro call that are not used in the macro expansion are read and combined with the expanded strings.
• The expanded strings and the remaining elements from the macro call, if any, must conform to the syntax rules for the program. If not, the program generates either a warning or an error message, depending on the nature of the syntax problem.

Syntax Rules

Just like other commands, expanded macros must adhere to the rules of the processing mode under which they are run. While it is desirable to create macro syntax that will run in both interactive and batch modes, this may sometimes add a layer of complexity that you may want to avoid. So we recommend that you write macro syntax that adheres to interactive syntax rules and structure your jobs to execute macro syntax under interactive syntax rules.

• DEFINE and !ENDDEFINE must be spelled in full. They cannot be abbreviated.
• The macro !ENDDEFINE statement should end with a period. A period as the last character on a line is interpreted as a command terminator in interactive mode.
• Other macro statements (for example, !IF, !LOOP, !LET) should not end with a period.
• Text within the body of the macro that represent commands that will be generated when the macro is expanded should include the period at the end of each command, and each command should start on a new line.

The macro body cannot contain the characters \ or ^ unless they are contained within a quoted string, as in "a valid backslash \ in a quoted string".

Example

DEFINE !macro1(type = !DEFAULT(1) !TOKENS(1)
                             /varlist=!CMDEND)
!IF (!type = 1)!THEN
frequencies variables=!varlist.
!ELSE
descriptives variables=!varlist.
!IFEND
!ENDDEFINE.

• The macro statements DEFINE, !IF, !ELSE, and !IFEND do not end with a period.
• !ENDDEFINE ends with a period.
• The FREQUENCIES and DESCRIPTIVES commands generated by the macro each start on a new line and end with a period.

To structure your command syntax jobs so that interactive processing rules are always used instead of batch processing rules:

• Use INSERT instead of INCLUDE to combine command files containing macros with other command files. See the topic INSERT for more information.
• In Production Facility jobs, select Interactive for the Syntax Input Format. See the topic Production jobs for more information.
• In the Batch Facility (available only with IBM® SPSS® Statistics Server), use the -i switch to use interactive processing rules.

Compatibility

Improvements to the macro facility may cause errors in jobs that previously ran without errors. Specifically, for syntax that is processed with interactive rules, if a macro call occurs at the end of a command, and there is no command terminator (either a period or a blank line), the next command after the macro expansion will be interpreted as a continuation line instead of a new command, as in:

DEFINE !macro1()
var1 var2 var3
!ENDDEFINE.
FREQUENCIES VARIABLES = !macro1
DESCRIPTIVES VARIABLES = !macro1.

In interactive mode, the DESCRIPTIVES command will be interpreted as a continuation of the FREQUENCIES command, and neither command will run.

Limitations

• The BEGIN DATA—END DATA commands are not allowed within a macro.
• BEGIN PROGRAM-END PROGRAM commands are not supported within a macro.
• The DEFINE command is not allowed within a macro.