BOX function

(Windows only; GUI for .NET only)

Returns an object reference to a .NET System.Object that contains (boxes) a .NET mapping of an ABL value. At run time, this mapping depends on the kind of ABL value passed to the function. If you pass an ABL primitive value, the function returns a corresponding .NET mapped object type. If you pass an ABL array of .NET-compatible elements, the function returns a corresponding .NET array object type.

Syntax

BOX ( ABL-expression [ , AS-data-type-expression ] )

ABL-expression

Specifies an expression with a value in one of the following .NET-compatible ABL data types:

• CHARACTER
• DATE
• DATETIME
• DATETIME-TZ
• DECIMAL
• INT64
• INTEGER
• LOGICAL
• LONGCHAR
• A .NET-compatible ABL array

A .NET-compatible ABL array is an ABL array of one of the listed ABL primitive types or an ABL array of any supported .NET object type (a .NET object type not mapped as specified in Table 4 ).

AS-data-type-expression

If ABL-expression is an ABL primitive type, this is a character expression equal to a keyword (AS data type) that matches the explicit .NET mapped data type into which you want to box the specified ABL-expression. If ABL-expression is an ABL primitive array, the character expression is an AS data type that specifies the explicit .NET mapped data type that the elements of the array should be converted to in the resulting .NET array object. This AS data type must correspond to one of the .NET types that maps appropriately to the ABL primitive type (or array element type) of ABL-expression (see Table 5).

If you do not specify AS-data-type-expression and ABL-expression is an ABL primitive (or primitive array), ABL boxes ABL-expression using the default matching .NET type that corresponds to the ABL primitive type (or array element type) of ABL-expression.

This option has no meaning when ABL-expression is an ABL array of a supported .NET object type.

Example

The following code creates a .NET DataTable with a single DataRow containing two columns. It then adds data to the row for the two columns. The Item indexed property used to access the columns has the data type System.Object. So, to add data to each column, you might have to use the BOX function to box the specified ABL value into an appropriate System.Object instance for the column. For example:

USING System.Data.* FROM ASSEMBLY.

DEFINE VARIABLE dataTable1 AS DataTable  NO-UNDO.
DEFINE VARIABLE dcCustNum  AS DataColumn NO-UNDO.
DEFINE VARIABLE dcName     AS DataColumn NO-UNDO.
DEFINE VARIABLE dcBusType  AS DataColumn NO-UNDO.
DEFINE VARIABLE row1       AS DataRow    NO-UNDO.

dataTable1 = NEW DataTable(INPUT "Customer").

/* Create columns for a dataTable */
dcCustNum = NEW DataColumn(INPUT "CustNum").
dcName    = NEW DataColumn(INPUT "Name").
dcBusType = NEW DataColumn(INPUT "BusType").
dataTable1:Columns:Add(INPUT dcCustNum).
dataTable1:Columns:Add(INPUT dcName).
dataTable1:Columns:Add(INPUT dcBusType).

/* Create a new row */
row1 = dataTable1:NewRow( ).

/* Add data to row */
row1:Item["CustNum"] = 1.
row1:Item["Name"] = "Mr Jones".
    /* Without BOX, this automatically boxes System.Int32 value. */
row1:Item["BusType"] = BOX( 236, "UNSIGNED-BYTE"). /* System.Byte value */

Notes

• For many direct assignments of a System.Object to an ABL primitive value or .NET-compatible ABL array, use of the BOX function is optional, because ABL automatically boxes the assigned ABL value into its default matching .NET object type. However, one such assignment for which you must use the BOX function is when you want to box an ABL primitive value (or primitive array) as a valid .NET mapped data type (or array of mapped types) other than the default match, for example, when boxing an ABL INTEGER (or INTEGER EXTENT) as a .NET System.Byte (or "System.Byte[]").
• If you pass a compatible ABL value or array to an INPUT parameter of a .NET method, ABL automatically boxes the ABL value into the matching .NET System.Object or array object. For an ABL primitive (or primitive array) value, this automatic boxing also allows you to explicitly specify the .NET data type mapping if you use the AS data type option on the ABL argument that you pass to the INPUT parameter (see the Parameter passing syntax reference entry). This automatic boxing does not occur for an ABL method, procedure, or user-defined function passing the same parameters. In this case, you can do an initial direct assignment or use the BOX function to explicitly do the necessary conversion.

See also

Data types, UNBOX function