XLL+ Class Library (6.3)

Scalar groups

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.

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:

Name Type
StartDate Date
EndDate Date
AccountType String
PaymentDays Long

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:

Wizard-generated code for compressed groups

The wizard-generated code to unpack this group will look something like this:

CopyC++
// 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.

Example

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

Next: Vector groups >>