Array mapping: conversion between ABL arrays and .NET arrays
ABL supports a mapping between compatible .NET and ABL arrays when you assign between them, which converts one kind of array to the other. Because ABL arrays are always one-dimensional arrays, array mapping works only with one-dimensional .NET arrays.
You might want to convert a .NET array to an ABL array, for example, if you want all the .NET array data to end up in the ABL context as an ABL array, where you can use native ABL array mechanisms to access it, for example to write a report. On the other hand, you might want to convert an ABL array directly to a .NET array, when you need to initialize the .NET array completely from all the data in the ABL array. You would then assign the ABL array to a .NET array property or pass the ABL array to an array parameter of a .NET method.
In either case, whenever you assign between an ABL array and a .NET array, a deep copy of the array elements occurs. When you assign a .NET array to an ABL array, ABL copies all of the .NET array elements into the elements of the specified ABL array variable, property, or routine parameter. When you assign an ABL array to a .NET array object, ABL instantiates a new .NET array object, copies all of the ABL array elements to it, and assigns its object reference to the specified .NET data member, property, or method parameter.
Because assignments between ABL and .NET arrays always copy the entire array, you might want to avoid doing so until you must move the array from one context to the other. Otherwise, where updates occur to only a few elements, you might prefer to apply these updates directly to the context (ABL or .NET) where they apply. Also, note that if you are simply passing a .NET array from one .NET object to another, you do not need to copy it first to an ABL array.
Note that when assigning a .NET array to an ABL array, the ABL array must have exactly the same number of elements as the .NET array or the ABL array must be indeterminate, in which case the .NET assignment fixes the number of elements in the ABL array. However, when assigning an ABL array to a .NET array, the number of elements do not matter because a new .NET is created and the target .NET array reference points to the new array. This is different from assigning to ABL arrays, where each element of the target ABL array is replaced.
When mapping between an ABL array and a .NET array, the data types of the array elements in the two arrays must be compatible. This type compatibility involves the following basic rules:
In general, a mapped ABL array cannot contain either pure ABL object elements (such as Progress.Lang.Object) or ABL-extended .NET object elements (see DefiningABL-extended .NET objects).
If the .NET array is an array of mapped data types, the ABL array must contain elements of an ABL primitive type that maps (without widening) to the element type of the .NET array. For more information on how ABL primitive types map to .NET data types, see Implicitdata type mappings.
If the element type of one array is a .NET value type (other than a mapped data type), the element type of the other array (.NET or ABL) must be the same identical .NET value type, for example, System.Drawing.Size.
For arrays containing .NET reference type elements, the two arrays are compatible if the element type of the source array is in the class hierarchy of the element type of the target array, for example a source array element type of System.Windows.Forms.Button and a target array element type of System.Windows.Forms.Control.
ABL does no automatic unboxing from a System.Object scalar to a target ABL array type. ABL does do automatic boxing for direct assignments and parameter passing from an ABL array type to a target System.Object scalar, but only for .NET methods and constructors (see .NET boxingsupport).
ABL does not box twice. That is, if ABL boxes or unboxes between a .NET array object and an ABL array, it does not also box or unbox the elements. So for example, it does not convert between a .NET "System.Object[]" and an ABL INTEGER array.
Any incompatibility between the types of the source and target arrays in an array assignment raises a compile-time error.
For an example of mapping .NET and ABL arrays, see Example: Mapping an ABL array to a .NET array. The following section describes how array assignments work and some examples of array assignments that are valid and invalid.
In general, a mapped ABL array cannot contain either pure ABL object elements (such as Progress.Lang.Object) or ABL-extended .NET object elements (see DefiningABL-extended .NET objects).