Custom-Defined Macro Input Parameters

When creating a macro, you can define how many and what kind of arguments are passed into the macro. Specifying the argument set (also known as the signature) for a macro is optional, but specifying it can make the macro easier to use and prevent usage errors.

The argument set is specified as part of the macro name when you create a macro with the MaxL create macro statement. In the following macro name, the argument set is enclosed in parentheses:

@SUMRANGE(single, group)

The preceding macro signature indicates that this macro requires two arguments: single, which represents one input parameter, and group , which represents a list of input parameters. These macro arguments do not represent a specific data type (such as a boolean, double, or string); instead, they only indicate how many arguments are accepted by the macro.

Arguments are specified in a comma-delimited list (argument1 , argument2, ... argumentX ) as part of the macro name when the macro is created. Arguments can be specified using the following keywords, which tell the macro processor how to check the arguments for a macro:

Argument	Description
SINGLE	A single argument
GROUP	A list of arguments. Any argument following GROUP is ignored.
OPTIONAL	A single argument that is not required
OPTIONAL_GROUP	A list of arguments that is not required. Any argument following OPTIONAL_GROUP is ignored.
ANY	No checking of arguments. Any argument following ANY is ignored.

In the macro presented previously, the following sets of arguments are valid:

@SUMRANGE(Profit, @CHILDREN(East))
@SUMRANGE(Profit, "New York", "New Jersey", Connecticut)
@SUMRANGE(Sales, @DESCENDANTS(Product))

The following table shows examples of how the macro processor interprets arguments for macros with different signatures given different input parameters. The definition of the example macro is:

create macro SUM3( argument1, argument2, argument3 ) as '(@@1 + @@2 + @@3)';

*Macro with Signature of SUM3(signature)*	Result when given input of SUM3 (X,Y)	Result when given input of SUM3 (X,Y,Z)	Result when given input of SUM3(X,Y,Z,T)
SUM3(SINGLE, SINGLE, SINGLE)	Error (wrong number of arguments)	X+Y+Z	Error (wrong number of arguments)
SUM3(SINGLE, SINGLE, GROUP)	Error (wrong number of arguments)	X+Y+Z	X+Y+@LIST(Z,T)
SUM3(SINGLE, SINGLE, OPTIONAL_GROUP)	X+Y+@_NULL	X+Y+Z	X+Y+@LIST(Z,T)
SUM3(SINGLE, SINGLE, OPTIONAL)	X+Y+@_NULL	X+Y+Z	Error (wrong number of arguments)
SUM3(SINGLE, SINGLE, ANY)	X+Y+@_NULL	X+Y+Z	X+Y+Z
SUM3(SINGLE, ANY)	X+Y+	X+Y+Z	X+Y+Z
SUM3(SINGLE, GROUP)	X+Y+	X+@LIST(Y,Z)+	X+@LIST(Y,Z,T)+
SUM3(ANY)	X+Y+	X+Y+Z	X+Y+Z

As noted previously, specification of arguments in the macro name only restricts the number of arguments that are accepted by the macro and does not restrict the data types that may be passed into the macro. Arguments in the Hyperion Essbase calculator language can represent any of the following data types:

Number	A single, double precision, floating point type number, which can have a special value, #MISSING, or an array of these numbers
Boolean	A single three-valued variable with the possible values, TRUE, FALSE, and #MISSING, or an array of these variables
Member	A single Hyperion Essbase database outline member, cross-member combination, or an array of members
String	A string variable type, or an array of these strings

When developing macros, you should consider the types of data that can be passed into macros to avoid errors in calculation.

Using Argument Values in Macro Definitions

Specifying an argument set for a custom-defined macro is only part of creating a macro. You must use the argument values in the macro expansion, which defines what functions the macro performs. Two types of argument variables can be used in a macro definition: numbered argument variables and argument variable shortcuts.

Using Numbered Argument Variables

In a macro definition, argument variables can be referenced by the order in which they appear in the macro signature. Consider the following example macro signature with three argument variables:

SUM3(single, single, group)

To use the input from this function in the macro definition, you reference the arguments using the argument variables @@1 for the first input parameter, @@2 for the second input parameter, and @@3 for the third input parameter. Thus, using the macro in the preceding example and providing the following input,

SUM3("New York", "New Jersey", @CHILDREN(Products));

results in the macro variables being set to the following values:

@@1 = "New York"
@@2 = "New Jersey"
@@3 = @CHILDREN(Products)

Use of the optional argument in the macro signature has no effect on which macro variable represents which incoming argument; for example, the input,

Macro signature: SUM3(single, optional, group)
Macro input: SUM3("New York", , @CHILDREN(Products));

results in the macro variables being set to the following values:

@@1 = "New York"
@@2 = @_NULL
@@3 = @CHILDREN(Products)

Using Argument Variable Shortcuts

You can represent sets of arguments with the variable shortcuts @@S and @@SHx. These shortcuts enable you to specify a set of arguments with one variable, rather than listing a set of numbered variables. Using input from the preceding example, the @@S variable would be set to the following value,

@@S = "New York", @_NULL, @CHILDREN(Products)

Argument variables and shortcuts for custom-defined macros can be used in any order within a macro definition and can be repeated in a macro.