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:

• Value
• Reference
• XlArray

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.

Appearance in Excel

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.:

  

Wizard-generated code for compressed groups

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.

Creating a scalar group

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.

Group descriptions

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.

Editing a scalar group

There are several ways to create and edit a scalar group in the Function Wizard.

• The New Group command can be used to create a new empty group, to which you can then add new or existing arguments.
• The Group arguments and Ungroup arguments commands can be used to group selected arguments or to ungroup an existing group.
• You can drag an argument into or out of a group using the mouse.
• You can use the   Move argument right and  Move argument left commands to move a group into or out of a group respectively.

Example

You can see an example of a scalar group of arguments in the LabelledArgs sample project.

Next: Vector groups >>