Assigning Tokens to Arguments (DEFINE-!ENDDEFINE command)

A token is a character or group of characters that has a predefined function in a specified context. The argument definition must include a keyword that indicates which tokens following the macro name are associated with each argument.

  • Any program keyword, variable name, or delimiter (a slash, comma, and so on) is a valid token.
  • The arguments for a given macro can use a combination of the token keywords.

!TOKENS (n). Assign the next n tokens to the argument. The value n can be any positive integer and must be enclosed in parentheses. !TOKENS allows you to specify exactly how many tokens are desired.

!CHAREND ('char'). Assign all tokens up to the specified character to the argument. The character must be a one-character string specified in apostrophes and enclosed in parentheses. !CHAREND specifies the character that ends the argument assignment. This is useful when the number of assigned tokens is arbitrary or not known in advance.

!ENCLOSE ('char','char'). Assign all tokens between the indicated characters to the argument. The starting and ending characters can be any one-character strings, and they do not need to be the same. The characters are each enclosed in apostrophes and separated by a comma. The entire specification is enclosed in parentheses. !ENCLOSE allows you to group multiple tokens within a specified pair of symbols. This is useful when the number of tokens to be assigned to an argument is indeterminate, or when the use of an ending character is not sufficient.

!CMDEND. Assign to the argument all of the remaining text on the macro call, up to the start of the next command. !CMDEND is useful for changing the defaults on an existing command. Since !CMDEND reads up to the next command, only the last argument on the argument list can be specified with !CMDEND. If !CMDEND is not the final argument, the arguments following !CMDEND are read as text.

Example

* Keyword !TOKENS.
 
DEFINE macname (!POSITIONAL !TOKENS (3)
frequencies variables = !1.
!ENDDEFINE.
 
macname ABC DEFG HI.
  • The three tokens following macname (ABC, DEFG, and HI) are assigned to the positional argument !1, and FREQUENCIES is then executed.

Example

* Keyword !TOKENS.

* Macro definition.
DEFINE earnrep (varrep = !TOKENS (1))
sort cases by !varrep.
report variables = earnings
  /break = !varrep
  /summary = mean.
!ENDDEFINE.

* Call the macro three times.
earnrep varrep= SALESMAN.  /*First macro call
earnrep varrep = REGION.   /*Second macro call
earnrep varrep = MONTH.    /*Third macro call
  • This macro runs a REPORT command three times, each time with a different break variable.
  • The macro name is earnrep, and there is one keyword argument, varrep, which has one token.
  • In the first macro call, the token SALESMAN is substituted for !varrep when the macro is expanded. REGION and MONTH are substituted for !varrep when the macro is expanded in the second and third calls.

Example

* Keyword !CHAREND'.
 
DEFINE macname (!POSITIONAL !CHAREND ('/')
               /!POSITIONAL !TOKENS(2))
frequencies variables = !1.
correlations variables= !2.
!ENDDEFINE.
 
macname A B C D / E F.
  • When the macro is called, all tokens up to the slash (A, B, C, and D) are assigned to the positional argument !1. E and F are assigned to the positional argument !2.

Example

* Keyword !CHAREND.
 
DEFINE macname (!POSITIONAL !CHAREND ('/'))
frequencies variables = !1.
!ENDDEFINE.
 
macname A B C D / E F.
  • Although E and F are not part of the positional argument and are not used in the macro expansion, the program still reads them as text and interprets them in relation to where the macro definition ends. In this example, macro definition ends after the expanded variable list (D). E and F are names of variables. Thus, E and F are added to the variable list and FREQUENCIES is executed with six variables: A, B, C, D, E, and F.

Example

* Keyword !ENCLOSE.
 
DEFINE macname (!POSITIONAL !ENCLOSE('(',')'))
frequencies variables = !1
  /statistics = default skewness.
!ENDDEFINE.
 
macname (A B C) D E.
  • When the macro is called, the three tokens enclosed in parentheses--A, B, and C--are assigned to the positional argument !1 in the macro body.
  • After macro expansion is complete, the program reads the remaining characters on the macro call as text. In this instance, the macro definition ends with keyword SKEWNESS on the STATISTICS subcommand. Adding variable names to the STATISTICS subcommand is not valid syntax. The program generates a warning message but is still able to execute the frequencies command. Frequency tables and the specified statistics are generated for the variables A, B, and C.

Example

* Keyword !CMDEND'.
 
DEFINE macname (!POSITIONAL !TOKENS(2)
               /!POSITIONAL !CMDEND)
frequencies variables = !1.
correlations variables= !2.
!ENDDEFINE.
 
macname A B C D E.
  • When the macro is called, the first two tokens following macname (A and B) are assigned to the positional argument !1. C, D, and E are assigned to the positional argument !2. Thus, the variables used for FREQUENCIES are A and B, and the variables used for CORRELATION are C, D, and E.

Example

* Incorrect order for !CMDEND.
 
DEFINE macname  (!POSITIONAL !CMDEND
                /!POSITIONAL !tokens(2))
frequencies variables = !1.
correlations variables= !2.
!ENDDEFINE.
 
macname  A B C D E.
  • When the macro is called, all five tokens, A, B, C, D, and E, are assigned to the first positional argument. No variables are included on the variable list for CORRELATIONS, causing the program to generate an error message. The previous example declares the arguments in the correct order.

Example

* Using !CMDEND.
SUBTITLE 'CHANGING DEFAULTS ON A COMMAND'.
 
DEFINE myfreq (!POSITIONAL !CMDEND)
frequencies !1
  /statistics=default skewness  /* Modify default statistics.
!ENDDEFINE.

myfreq VARIABLES = A B /HIST.
  • The macro myfreq contains options for the FREQUENCIES command. When the macro is called, myfreq is expanded to perform a FREQUENCIES analysis on the variables A and B. The analysis produces default statistics and the skewness statistic, plus a histogram, as requested on the macro call.

Example

* Keyword arguments: Using a combination of token keywords.
 
DATA LIST FREE / A B C D E.
DEFINE macdef3 (arg1 = !TOKENS(1)
               /arg2 = !ENCLOSE ('(',')')
               /arg3 = !CHAREND('%'))
frequencies variables = !arg1  !arg2 !arg3.
!ENDDEFINE.
macdef arg1 = A  arg2=(B C)  arg3=D E %.
  • Because arg1 is defined with the !TOKENS keyword, the value for arg1 is simply specified as A. The value for arg2 is specified in parentheses, as indicated by !ENCLOSE. The value for arg3 is followed by a percentage sign, as indicated by !CHAREND.