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 Create Macro MaxL 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:

Table 2-35 Keywords Used in Arguments

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)';

Table 2-36 Example Macro Inputs and Results

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 Essbase calculator language can represent any of the following data types:

Table 2-37 Data Types of Arguments

Data Type	Description
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 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.