Passing arrays as parameters to functions or procedures in Dexterity

First, some theory...

The individual pieces that make up an array are called elements. The elements are numbered from 1 to the size of the array. Arrays can have up to 32,767 elements. The number used to indicate a specific element of the array is called the array index. A specific element of the array is referenced in sanScript using its corresponding array index.

Typically, an array can be used in place of several fields that have the same data type and will be storing similar information. For example, if an application keeps track of monthly sales for a year, one monthly sales array field with an array size of 12 could be used to store this information instead of 12 separate fields.

Dexterity applications can use array fields [in tables] and array local variables [in memory]. Array fields are created in the Field Definition window by setting the Array Size field to the size of the array. Array local variables are created by including the size of the array in brackets – [ ] – following the local variable name. When creating local arrays, the array size must be a constant expression. Array sizes can’t be set at runtime.

To access the elements of an array from within a script, simply use the name of the array and add the index number of the element you want to reference. Be sure the index number is included in square brackets after the name of the array and before the qualifier. The following example sets the third element of the Quarterly Sales array field (corresponding to the third quarter) to the sum of the monthly sales for July, August and September.

'Quarterly Sales'[3] = 'Jul Sales' + 'Aug Sales' + 'Sep Sales';

The following example uses a local array field with five elements to act as status flags for the script. The for loop initializes the flags to false.

local boolean status[5];
local integer i;

for i = 1 to 5 do
  status[i] = false;
end for;

Now to the problem...

A couple days aback a developer reported issues when passing an array as a parameter to a Dex global procedure - won't have been any different for a function either. Her code was as follows - I say was as I assumed it has been fixed since.

local currency l_plan_total, l_month_totals[13];

call TAS_Calculate_Plan_Totals,
  'Customer Number' of table TAS_Plan_Header,
  Year of table TAS_Plan_Header,
  TAS_Plan_Status of table TAS_Plan_Header,
  'Revision Number' of table TAS_Plan_Header,
  l_plan_total,
  l_month_totals[13];

The procedure signature is as follows:

{PROC: TAS_Calculate_Plan_Totals}

in string i_customer;
in integer i_year, i_status;
in long i_revision;
out currency o_total;
out currency o_month[13];

local currency l_month[13];

Things to note... in the calling script, the developer declares an array of monthly totals of 13 elements, then calls the TAS_Calculate_Plan_Totals passing the array as a parameter. The procedure is pretty straight forward and uses an out parameter to pass-back whatever results the developer will calculate and put into each element of the array.

However, when the code is compiled, the developer receives the error type incompatibility on parameter #6. That happens to be the array parameter in the call to the global proc.

Taking a closer look, the developer is passing l_month_totals[13] to in the procedure call. Since, the parameter in the procedure has been declared as an array, l_month_totals[13] is being interpreted by the Dexterity compiler as the currency value represented by the element with an index of 13. In other words, just the plain currency value and not the array as a whole. To correct the code, the developer needed to remove the brackets from the call, just passing l_month_totals, as follows:

local currency l_plan_total, l_month_totals[13];

call TAS_Calculate_Plan_Totals,
  'Customer Number' of table TAS_Plan_Header,
  Year of table TAS_Plan_Header,
  TAS_Plan_Status of table TAS_Plan_Header,
  'Revision Number' of table TAS_Plan_Header,
  l_plan_total,
  l_month_totals;

{PROC: TAS_Calculate_Plan_Totals}

in string i_customer;
in integer i_year, i_status;
in long i_revision;
out currency o_total;
out currency o_month[13];
local currency l_month[13];

I must say that the developer in question is an experienced developer, but at the same time, I can see how this can become confusing even for the experts. I personally believe that a better approach for this call - talking to you Dex compiler gurus in Fargo - would have been as follows:

call TAS_Calculate_Plan_Totals,
  'Customer Number' of table TAS_Plan_Header,
  Year of table TAS_Plan_Header,
  TAS_Plan_Status of table TAS_Plan_Header,
  'Revision Number' of table TAS_Plan_Header,
  l_plan_total,
  l_month_totals[];

Note the use of the brackets as a way to differentiate the array variable from, say, the other currency variable just above it. On that same note, I have a long list of suggested compiler changes for Dexterity, but I am sure these are not a priority at this point.

Until next post!

MG.-
Mariano Gomez, MVP
IntellPartners, LLC
http://www.IntellPartners.com/