Parameter passing syntax

Specifies one or more parameters to pass during invocation of an ABL procedure, a user-defined function, a method of a class (ABL or .NET), a class constructor (ABL or .NET), or the built-in Publish( ) event method or PUBLISH statement to publish class or named events, respectively.

Syntax

( parameter[ , parameter ]... )

The parameters specified by parameter must match in number and order, according to mode and data type, as required by the given procedure, user-defined function, method, or constructor definition. Use the following syntax to specify each parameter:

[ INPUT | OUTPUT | INPUT-OUTPUT ]
{   parm [ AS data-type]
  | { {   TABLE temp-table-name 
         | TABLE-HANDLE temp-table-handle 
         | DATASET dataset-name 
         | DATASET-HANDLE dataset-handle 
        } [ APPEND ] [ BY-VALUE | BY-REFERENCE | BIND ] 
     }
}
BUFFER buffer
[ INPUT | OUTPUT | INPUT-OUTPUT ]
Specifies the parameter mode. For more information on parameter modes, see the reference entries for the DEFINE PARAMETER statement (for procedures) and the Parameter definition syntax (for user-defined functions, methods, and class events).

Note that for methods and constructors, the parameter mode is optional except for certain overloading conditions. Thus, the default mode depends on the type of invocation, as described in the following table.

Default parameter passing mode
Invocation type Default mode
Procedure INPUT
User-defined function Uses the mode defined for the corresponding parameter in the function prototype. For more information on defining prototypes for user-defined functions, see the FUNCTION statement reference entry.
Method of a class or class constructor Uses the mode defined for the corresponding parameter in the method or constructor prototype, depending on overloading requirements. For more information on defining prototypes for class-based methods and constructors, see the METHOD statement and CONSTRUCTOR statement reference entries.

If the method is overloaded by a given parameter only by mode, you must specify the mode for this parameter in the method call. If you do not do so, ABL raises a compile-time ambiguity error. For example, if a method is overloaded twice by an INTEGER parameter, and the parameter for one method definition has the INPUT mode while the parameter for the other method definition has the OUTPUT mode, you must specify the INPUT keyword if you intend to use the method defined with the INPUT parameter.

Publish( ) event method Uses the mode defined for the corresponding parameter in the class event definition. For more information on defining class events, see the DEFINE EVENT statement reference entry.

When identifying the parameter mode for a .NET method or constructor, each .NET language uses its own keyword syntax to identify it. The following table shows the C# parameter syntax that corresponds to an ABL parameter specified with a given mode. Note that in C#, the default (no keyword) corresponds to the ABL INPUT mode.

C# syntax matching ABL parameter modes
ABL parameter mode Corresponding C# syntax
INPUT parm parm
OUTPUT parm out parm
INPUT-OUTPUT parm ref parm

Also note, as with ABL class-based methods, the default parameter passing modes for calling .NET methods and constructors are based on the parameter passing modes defined for the method or constructor prototypes, depending on overloading. Thus, you must specify the parameter passing mode for each affected parameter if the method is overloaded only by a given parameter's mode.

parm
Specifies the argument passed to the parameter. This can be either an ABL data element or Expression, or a .NET data element, depending on the parameter mode. For an INPUT parameter, parm can be an Expression. For an OUTPUT or INPUT-OUTPUT parameter, parm can be any of the elements defined for the left side of an Assignment (=) statement. For an INPUT-OUTPUT parameter, any property argument must be both writable and readable.
Note: Syntactic limitations require that none of the following data items can be an OUTPUT or INPUT-OUTPUT parameter: a writable handle attribute, a writable property (ABL or .NET) on an object reference, or a data member (ABL or .NET) on an object reference. The limitation is that OUTPUT and INPUT-OUTPUT parameters cannot have a colon in their syntax. For example, OUTPUT myObjectRef:WritableProperty is invalid syntax.

For procedures, the data type of parm must be compatible with the data type defined for the parameter. Procedures allow the matching of a wide variety of different data types between the passed parameter and the parameter definition. When it can, the AVM converts the passed value from the source data type to an appropriate value in the destination data type, depending on the direction (parameter mode) of the passed value. For procedures, the AVM checks data type matching and appropriate overflow conditions at run time.

For user-defined functions, methods of a class, class constructors, and the Publish( ) event method, the data types of the passed parameter and the parameter definition are validated by the AVM at compile time and must match exactly, unless they have a widening relationship.

The AVM implicitly converts passed parameter values of certain data types from a narrow data type in the source to a widened data type in the destination, depending on the parameter mode. A widened data type is one that can hold all the values of a narrower data type without loss of data. Widening is supported for three related sets of data types, as shown in the following table, where the arrow ( —>) indicates the direction that a value can be passed for the parameter.

Data type widening support
Narrower —> Wider
CHARACTER LONGCHAR
INTEGER INT64 DECIMAL
DATE DATETIME DATETIME-TZ

Thus, ABL supports the widening of data types in the direction that the parameter is defined, according to its mode:

  • INPUT parameters — The data type of the passed parameter can be narrower than the defined parameter.
  • OUTPUT parameters — The data type of the passed parameter can be wider than the defined parameter.
  • INPUT-OUTPUT parameters — Widening is not supported. Because values are passed in both directions, the data type of the passed parameter must exactly match the data type of the defined parameter.

For .NET method parameters, ABL also supports widening relationships between ABL and some .NET data types. For more information, see the notes of this reference entry.

For a parm that involves .NET data types, either as the parameter definition or as the argument, the requirements for parameter passing depend on the parameter and argument data types and the type of routine that defines the parameter. The following table shows the possible combinations.

Note: The following table refers to .NET value types, .NET mapped data types, .NET arrays of mapped types, boxing, and unboxing. Boxing and unboxing refer to a .NET mechanism for converting between .NET value types and .NET object types. ABL supports a similar mechanism for converting between ABL primitive or array types and a .NET System.Object or compatible array object type. For more information on .NET data types, concepts, and compatibility, see the Data types reference entry.
Passing parameters involving .NET types
The following parameter data type . . . In this routine type . . . Can take these arguments (parm) . . .
.NET mapped data type1 .NET routine2 The same .NET data type (for example, a .NET property), any corresponding ABL primitive type (as shown in Table 43), and on OUTPUT only, a System.Object4
.NET mapped data type5 ABL method that overrides or implements a .NET method Any compatible ABL primitive type or any compatible .NET mapped data type (for example, a .NET property) as shown in Table 43,6
.NET array .NET routine A compatible .NET or ABL array type7, 8, and on OUTPUT only, a System.Array, System.Object, or Progress.Lang.Object
.NET array ABL routine9, 10 A compatible .NET array type8,, 11and on OUTPUT only, a System.Array, System.Object, or Progress.Lang.Object,
System.Array .NET routine On INPUT, any .NET array object type or compatible ABL array type12, and on OUTPUT only, a System.Array, System.Object, or Progress.Lang.Object
System.Array ABL routine9, 10 On INPUT, any .NET array object type11, and on OUTPUT only, a System.Array, System.Object, or Progress.Lang.Object
System.Object .NET routine On INPUT, any .NET object type, an ABL primitive type, or compatible ABL array type12, and on OUTPUT only, a System.Object or Progress.Lang.Object
System.Object ABL routine9, 10 On INPUT, any .NET object type11, and on OUTPUT only, a System.Object or Progress.Lang.Object
Any .NET object type (except those in the previous rows) .NET routine Any compatible .NET object type, and on OUTPUT only, a System.Object or a Progress.Lang.Object
Any .NET object type (except those in the previous rows) ABL routine9, 10 Any compatible .NET object type, and on OUTPUT only, a System.Object or a Progress.Lang.Object
ABL primitive type5 ABL routine (always)9 Any compatible ABL primitive type or any compatible .NET mapped data type (for example, a .NET property) as shown in Table 43,6
ABL array ABL routine (always)9 A compatible ABL array type6
Progress.Lang.Object ABL routine (always)9 On INPUT only, any ABL object and any supported .NET object type except a .NET mapped data type4
AS data-type
Indicates an explicit mapping between an argument with an ABL primitive type and the parameter of a .NET method or constructor. Assuming that the .NET data type defined for the parameter is compatible with the data type of the ABL argument, data-type represents an ABL keyword (AS data type) that indicates an alternative .NET data type mapping to identify with the .NET parameter. This option is necessary in the following cases:
  • When the .NET method or constructor is overloaded by multiple implicit .NET data type mappings for the passed ABL primitive type and the method you want is not identified by the default match for the passed ABL data type. Thus, by explicitly specifying an AS data type, you can disambiguate the implicit .NET overloadings for the method or constructor.
    Note: You can specify a passed parameter AS data type for a .NET method that is not overloaded. However, you have no need to do so unless the method is overloaded by a given parameter.
  • The parameter is defined as a System.Object, and you want the .NET value of the passed ABL primitive type to be stored as a .NET mapped data type that is not the default match. For example, you might want the System.Object parameter to store an ABL INTEGER value as a System.Int16 instead of as a System.Int32 (the default match).

For the a list of available keywords that you can specify for data-type, as well as the default matches for ABL primitive types with multiple .NET data type mappings, see Table 5 in the Data types reference entry.

Note: The AS data types in Table 5  represent some different data types than you can specify using the AS option to pass a COM method parameter. For more information on passing COM method parameters, see Syntax for accessing COM object properties and methods.
TABLE temp-table-name
Specifies the name of a static temp-table.

This parameter type can match at compile time with any TABLE parameter with the same schema, or any TABLE-HANDLE parameter. If the matching type is TABLE-HANDLE, a run-time check occurs if the TABLE-HANDLE is not the Unknown value (?) in order to ensure that the run-time schemas match. A parameter of a user-defined function or method of a class is verified at compile time, while a parameter of a procedure is verified at run time.

TABLE-HANDLE temp-table-handle
Specifies a handle to a temp-table. Use a temp-table handle as a parameter for a dynamic temp-table. The full schema definition behind the handle and the contents of the temp-table are passed unless the temp-table SCHEMA-MARSHAL attribute is set to minimize or prevent schema marshalling.

This parameter type can match at compile time with any TABLE or TABLE-HANDLE parameter. If the matching type is TABLE-HANDLE, a run-time check occurs if the TABLE-HANDLE is not the Unknown value (?) in order to ensure that the run-time schemas match. A parameter of a user-defined function or method of a class is verified at compile time, while a parameter of a procedure is verified at run time.

DATASET dataset-name
Specifies the name of a static ProDataSet.

This parameter type can match at compile time with any DATASET parameter with the same schema, or any DATASET-HANDLE parameter. If the matching type is DATASET-HANDLE, a run-time check occurs if the DATASET-HANDLE is not the Unknown value (?) in order to ensure that the run-time schemas match. A parameter of a user-defined function or method of a class is verified at compile time, while a parameter of a procedure is verified at run time.

DATASET-HANDLE dataset-handle
Specifies a handle to a ProDataSet. Use a ProDataSet object handle as a parameter for a dynamic ProDataSet. The full schema definition behind the handle and the contents of the ProDataSet object are passed unless the SCHEMA-MARSHAL attribute for one or more of its temp-tables are set to minimize or prevent schema marshalling.

This parameter type can match at compile time with any DATASET or DATASET-HANDLE parameter. If the matching type is DATASET-HANDLE, a run-time check occurs if the DATASET-HANDLE is not the Unknown value (?) in order to ensure that the run-time schemas match. A parameter of a user-defined function or method of a class is verified at compile time, while a parameter of a procedure is verified at run time.

BUFFER buffer
Specifies the name of a buffer.
APPEND
Specifies whether or not to append the source temp-table data to the destination temp-table data. To append OUTPUT parameter data, specify the APPEND option for the parameter in the routine call. To append INPUT parameter data, specify the APPEND option for the parameter in the routine definition.
BY-VALUE | BY-REFERENCE | BIND
Specifies whether to pass a TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter by value, by reference, or by binding. The default is BY-VALUE.

You can pass TABLE, TABLE-HANDLE, DATASET, and DATASET-HANDLE parameters to both local and remote procedures. These parameter types are normally passed by value, by default. That is, the calling routine and the called routine each have their own instance of the object, and the parameter is deep-copied from the calling routine's instance to the called routine's instance.

When passing one of these parameters to a local routine, you can override the default in the calling routine by specifying the BY-REFERENCE or BIND option.

Passing one of these parameters to a local routine using the BY-REFERENCE option allows the calling routine and the called routine to access the same object instance. That is, both routines access the calling routine's instance and ignore the called routine's instance. Since the called routine's object instance is ignored, you should define the static object as reference-only by specifying the REFERENCE-ONLY option in the DEFINE statement for the object.

Passing one of these parameters to a local routine using the BIND option allows the calling routine and the called routine to access the same object instance. You can do this by:

  • Binding a reference-only static object defined in one routine to an object instance defined in another routine
  • Binding an unknown TABLE-HANDLE or DATASET-HANDLE parameter defined in one routine to an object instance defined in another routine

In the static case, you must define a reference-only object in either the calling routine or the called routine by specifying the REFERENCE-ONLY option in the DEFINE statement for the object. You must also define the parameter by specifying the BIND option in the parameter definition.

When you define a reference-only object in the calling routine and pass it to the called routine using the BIND option, the AVM binds the definition of the object in the calling routine to the object instance in the called routine. When you define a reference-only object in the called routine and receive the object from the calling routine, the AVM binds the definition of the object in the called routine to the object instance in the calling routine. In either case, the reference-only object definition remains bound to the object instance until the routine containing the reference-only object definition is deleted or terminates.

Caution:
Do not delete the object or routine to which a reference-only object is bound, or you might be left with references to an object that no longer exists.

You can bind multiple reference-only object definitions to the same object instance. You can also bind a single reference-only object definition to the same object instance multiple times without generating an error. However, you cannot bind a single reference-only object definition to multiple object instances.

When passing one of these parameters to a remote procedure, the AVM ignores the BY-REFERENCE and BIND options and deep-copies the parameter based on the specified parameter mode.

Examples

The following two code fragments show how the AS data type works when calling an overloaded .NET method, in this case the System.Math:Max( ) method. This static .NET method compares two values of the same data type and returns the largest of the two. The first fragment compiles and runs. It compares the value 50, passed as a System.Byte (specified by the AS data type, UNSIGNED-BYTE), with the maximum value of a System.Byte, returned by the System.Byte:MaxValue data member. The result returned by the Max( ) method is 255, the maximum System.Byte value:

DEFINE VARIABLE iVal1   AS INTEGER NO-UNDO INITIAL 50.
DEFINE VARIABLE iVal2   AS INTEGER NO-UNDO.
DEFINE VARIABLE iReturn AS INTEGER NO-UNDO.

iVal2 = System.Byte:MaxValue.
iReturn = System.Math:Max( INPUT iVal1 AS UNSIGNED-BYTE, 
                           INPUT iVal2 AS UNSIGNED-BYTE ).

The second fragment compiles, but returns a run-time error. Again, it passes the same two values to the System.Math:Max( ) method, but this time passes them as a System.SByte (specified by the AS data type, BYTE). A signed byte parameter cannot hold positive values as large as an unsigned byte. So, passing the maximum value of a System.Byte (unsigned byte) as a System.SByte (signed byte) causes the Max( ) method to raise a run-time overflow error:

DEFINE VARIABLE iVal1   AS INTEGER NO-UNDO INITIAL 50.
DEFINE VARIABLE iVal2   AS INTEGER NO-UNDO.
DEFINE VARIABLE iReturn AS INTEGER NO-UNDO.

iVal2 = System.Byte:MaxValue.
iReturn = System.Math:Max( INPUT iVal1 AS BYTE, 
                           INPUT iVal2 AS BYTE ). /* Run-time error */

The following code fragment shows an example of ABL data type widening when passing parameters to a .NET method. This example shows INPUT widening, in this case, passing different ABL data types (INTEGER and INT64) that are acceptable as arguments to a System.Double input parameter:

DEFINE VARIABLE i4Val  AS INTEGER NO-UNDO.
DEFINE VARIABLE i8Val  AS INT64   NO-UNDO.
DEFINE VARIABLE iRoot1 AS DECIMAL NO-UNDO.
DEFINE VARIABLE iRoot2 AS DECIMAL NO-UNDO.

ASSIGN
  i4Val  = System.Int32:MaxValue
  i8Val  = System.Int64:MaxValue
  iRoot1 = System.Math:Sqrt( INPUT i4Val )
  iRoot2 = System.Math:Sqrt( INPUT i8Val ).

For more information on data type widening, see the Notes section later in this reference entry.

Notes

See also

Assignment (=) statement, Expression, FUNCTION statement, NEW function (classes), Publish( ) event method, PUBLISH statement, RUN statement, RUN SUPER statement, SUPER statement, SUPER system reference, THIS-OBJECT statement