If you have a group of vector arguments which are closely related, and are always the same size as each other, then you may want to use a vector group. The user will then see only one argument, and the wizard will generate code to split it into a number of vectors, checking that each inner argument is present and that all columns (or rows) are the same length.

Advantages of vector groups

Vector groups can be useful for both the add-in developer and the user.

• The total number of arguments is reduced. Since Excel has a limited number of arguments per function, combining multiple vector arguments into one grouped argument may leave room for more arguments.
• The user has less arguments to worry about. Furthermore, if the vectors are returned from some other function or from a database as a single result, it may be very convenient for the user to pass them on to another function as a single group.

Disadvantages of vector groups

Vector groups are not always a useful feature.

• The columns or rows must be in a particular order, left to right, or top to bottom. It may be inconvenient for the user to arrange them in this way.

  Note: However, the user can work around this problem by using a function which combines multiple cells into a single range, such as TFOLD.

Wizard-generated code for vector groups

For example, take a grouped argument, PaymentSchedule, that contains two vectors, as follows:

The XLL+ Function Wizard will generate code that declares a vector of the appropriate type for each column or row and populates it with the contents of the corresponding region of input. If the input cannot be read, then an appropriate error message will be returned.

// Input buffers 
std::vector<long> PaymentDates;
std::vector<double> PaymentAmounts;
// Validate and translate inputs
XlReadGroupedVectorEx(*PaymentSchedule, PaymentDates, DateConverter(), L"Pa"
    L"ymentSchedule", 0, L"PaymentDates", XLA_TRUNC_ONEMPTY|XLA_TRUNC_ONBLANK
    |XLA_OPER_IS_GROUP);
XlReadGroupedVector(*PaymentSchedule, PaymentAmounts, L"PaymentSchedule", 1, 
    L"PaymentAmounts", XLA_TRUNC_ONEMPTY|XLA_TRUNC_ONBLANK|XLA_OPER_IS_GROUP);

If the validation code fails, then a useful error message will be returned, such as:

#Error in cell 3 of PaymentSchedule column 1 (PaymentDates): expected a date

or:

#Error column 2 of PaymentSchedule: expected 4 rows

If all the validation code is successful, then the variables PaymentDates and PaymentAmounts will be populated and ready for use. In addition, both vectors will be the same length.

Next: Choice arguments >>