A scalar group can contain any number of scalar (single-cell) arguments. Each of these inner arguments must have a specified value type; the following generic types are not allowed:
The inner arguments may be built-in data types or extended scalar types. The inner arguments are not constrained to be the same type, they can be the same or different as you choose.
The inner arguments will appear in Excel as a single vector argument. For example, take a group argument, PaymentDetails, that contains four inner arguments, as follows:
The wizard will generate code that inspects the outer (Excel) argument. This code will fail and return a helpful error message unless the argument is one of the following shapes:
4 rows x 1 column, with the cells in inner argument order, e.g.:
1 row x 4 columns, with the cells in inner argument order, e.g.:
4 rows x 2 columns, with labels in the left column, and the cells in any order, e.g.:
The wizard-generated code to unpack this group will look something like this:
// Input buffers long StartDate; long EndDate; std::string AccountType; long PaymentDays; // Validate and translate inputs XlReadGroupedScalarEx(*PaymentDetails, StartDate, DateConverter(), L"Payme" L"ntDetails", 0, L"StartDate"); XlReadGroupedScalarEx(*PaymentDetails, EndDate, DateConverter(), L"Payment" L"Details", 1, L"EndDate"); XlReadGroupedScalar(*PaymentDetails, AccountType, L"PaymentDetails", 2, L"AccountType"); XlReadGroupedScalar(*PaymentDetails, PaymentDays, L"PaymentDetails", 3, L"PaymentDays");
If the input-checking code fails, then a useful error message will be returned, such as:
#Error in cell 4 of PaymentDetails (PaymentDays): expected an integer
If all the input-checking code is successful, then the variables StartDate, EndDate, AccountType and PaymentDays will be populated and ready for use.
The simplest way to create a scalar group is to select all the arguments you wish to group and then using the Group arguments command.
Note: For help on selecting multiple arguments, see Selecting arguments.
After you click the Group tool, a new argument, named "Group1" will be created, containing the existing four arguments.
Go to the group's "Name" column and change it to the correct name.
You can choose to rely on the Function Wizard to create the description of the group, by selecting one of the standard descriptions that drop down below the cell, when you click on the arrow.
The advantage of using on of these built descriptions is that the group's description will automatically be updated whenever you change the order or membership of the group's arguments, or change the name or description of one the arguments.
There are several ways to create and edit a scalar group in the Function Wizard.
You can see an example of a scalar group of arguments in the LabelledArgs sample project.