Every Absyntax project has an entry-point and an exit-point. However, it is up to a project's creator to determine whether said entry- and exit-points transmit signals or data. You are expected to know these details for all Absyntax projects you want to invoke using the Absyntax Excel Add-in.
Input Data
If a project to be invoked has an entry-point that requires data, you must define a
project invocation rule that specifies the worksheet cell range from which data is to be acquired prior to each invocation. An attempt to invoke a data input project without supplying data to it will result in an error. An attempt to invoke a signal input project with supplied data will result in the data being ignored.
The input data range may refer to a single cell or multiple cells. If it refers to a single cell then the data type of the cell's value must be convertible to the type of data required by the target project's entry-point. If, on the other hand, it refers to multiple cells then the target project's entry-point data type must be either System.Object or an enumerable type (such as System.Collections.IEnumerable, System.Collections.Generic.IEnumerable<> or a one-dimensional array object). Furthermore, if the cells contain values that have different data types, the target project's entry-point data type can only be a strongly typed enumerable if the element type is System.Object. Examples of this include System.Object[] and System.Collections.Generic.IEnumerable<System.Object>.
Where an input data range defines multiple cells, the values of these cells are presented to the project's entry-point as a single collection in a sequence determined by the input range order, which can be either "by row" or "by column". For example, an input range defined as A1:C2 and with a "by row" range order would result in data being presented to the target project in the order indicated by the cell values shown below.
Contrast this with the same range and a "by column" range order. This would result in data being presented to the target project in the order indicated by the cell values shown below.
Where an input data range refers to a worksheet range name, the cells therein may occupy multiple worksheet areas. In such cases the values of these cells are obtained in a sequence determined firstly by the order in which the areas are defined within the range, and secondly by the input range order. In the example below, a named range consists of two areas defined in the order A1:B3 and D1:D4. Assuming a "by row" input range order, this would result in data being presented to the target project in the following sequence.
If, on the other hand, the areas had been defined in reverse order (D1:D4 and A1:B3), data would be presented as follows.
Output Data
A project may emit data but you can choose to ignore it by suitably configuring the project invocation rule. In such cases all returned data is discarded and no worksheet is updated. Equally, it is acceptable (if, perhaps, confusing) to configure the rule to handle output data for a project that does not emit data. An attempt to invoke such a project will not result in an error but it will result in a single, empty value being written to the top-left cell of the range defined for the selected output worksheet. If this is undesirable then configure the rule to ignore output.
If a rule is configured to handle output data and the project emits non-enumerable data, the Absyntax Excel Add-in will attempt to write a single value to the top-left cell of the first area of the defined output range. If, instead, the project emits enumerable data then an attempt will be made to write each enumerable value to consecutive cells in the defined output range, in accordance with the specified output range order. The defined range does not need to be sufficiently large to accommodate all output values because the Absyntax Excel Add-in will extend the range as necessary. This does, of course, mean that cells outside the defined output range may be overwritten and you should allow for this when identifying the location and ordering of your output range.
For example, if the defined output range is an area of three columns and two rows (i.e. six cells) and the project outputs an array of seven values, all seven values will be written. This is achieved by extending the range in a direction determined by the value of the specified output range order. In fact, the output data range needs only to be defined in terms of 1 x n columns or n x 1 rows. Consider an output range defined as "A1:C1" with a "by row" output range order: this would result in the first three output values being written to cells A1 through C1, the next three being written to cells A2 through C2 and so on, as shown below.
Similarly, an output range defined as "A1:A3" with a "by column" output range order would result in the first three output values being written to cells A1 through A3, the next three being written to cells B1 through B3 and so on.
It is also possible to write output values to non-contiguous cells or cell areas. To do this, define a named range in Microsoft Excel that cross-references the target cells, then select the range name as the output data range for the project invocation rule. The Absyntax Excel Add-in will write any output values to the range areas in the order they are defined within the range while honouring the rule's defined output range order. Note that only the last range area is extended (if necessary): in such cases the behaviour is as described above.
For example, suppose a project invocation rule's output data range refers to a worksheet range name defined as encompassing two cell areas, A1:A3 and C1:C3 (in that order). If the project outputs an array of seven values, all seven values will be written as shown below. Note that the first area (A1:A3) is filled first, and the last area (C1:C3) is extended to accommodate the extra output values.
Note that although Microsoft Excel allows you to define named ranges that span multiple worksheets, the Absyntax Excel Add-in does not recognise such ranges.
