Parameter definition syntax

Defines one or more run-time parameters for a user-defined function, a class method (including a constructor), or a class event defined with an ABL method signature. ABL implements both scalar and array parameters for user-defined functions and methods of a class as NO-UNDO variables.

Syntax


( `parameter` [ , `parameter` ] ... )

Note: To define run-time parameters for an ABL procedure, Windows dynamic link library (DLL) routine, UNIX shared library routine, or ActiveX control event procedure, see the DEFINE PARAMETER statement reference entry.

Use the following syntax to define each parameter, which can be a primitive, array, class, interface, temp-table, ProDataSet, or buffer:

Syntax
{ INPUT \| OUTPUT \| INPUT-OUTPUT } { `parameter-name` AS { `primitive-type-name` \| [ CLASS ] `object-type-name` } [ EXTENT [ `constant` ] ] \| TABLE `temp-table-name` [ APPEND ] [ BIND ] [ BY-VALUE ] \| TABLE-HANDLE `temp-table-handle` [ APPEND ] [ BIND ] [ BY-VALUE ] \| DATASET `dataset-name` [ APPEND ] [ BIND ] [ BY-VALUE ] \| DATASET-HANDLE `dataset-handle` [ APPEND ] [ BIND ] [ BY-VALUE ] }

{ INPUT | OUTPUT | INPUT-OUTPUT }  
{   parameter-name AS { primitive-type-name | [ CLASS ] object-type-name } 
      [ EXTENT [ constant ] ]  
  | TABLE temp-table-name [ APPEND ] [ BIND ] [ BY-VALUE ] 
  | TABLE-HANDLE temp-table-handle [ APPEND ] [ BIND ] [ BY-VALUE ] 
  | DATASET dataset-name [ APPEND ] [ BIND ] [ BY-VALUE ] 
  | DATASET-HANDLE dataset-handle [ APPEND ] [ BIND ] [ BY-VALUE ] 
}


BUFFER `buffer-name` FOR `database-table-name` [ PRESELECT ]

INPUT | OUTPUT | INPUT-OUTPUT

Specifies the parameter mode, which determines the direction that data travels when the parameter is passed at run time. An INPUT parameter travels from the caller (source), which sets its value, to the called function or method (destination or receiver), which can use the value. An OUTPUT parameter travels from the called function or method (source), which sets its value, back to the caller (destination or receiver), which can use the value. An INPUT-OUTPUT parameter travels both ways, first from the caller, which sets its value; then to the called function or method, which can use and reset the value and pass it back to the caller, which can use the returned value.

parameter-name

Specifies the name of a primitive, class, interface, or array parameter.

AS primitive-type-name

Specifies a built-in primitive type for the parameter you are defining. The built-in data type (primitive-type-name) can be one of the following:

Syntax
CHARACTER \| COM-HANDLE \| DATE \| DATETIME \| DATETIME-TZ \| DECIMAL \| HANDLE \| INT64 \| INTEGER \| LOGICAL \| LONGCHAR \| MEMPTR \| RAW \| RECID \| ROWID \| `AS-data-type`

If you are defining a parameter for a user-defined function, a pure ABL class method (without reference to .NET), or a class event defined with an ABL method signature, AS-data-type does not specify a valid primitive type name.

If you are defining a parameter for a method that overrides a .NET super class method (abstract or otherwise) or implements a method defined in a .NET interface, primitive-type-name must specify the exact .NET data type of the corresponding parameter in the overridden or implemented method. For a .NET mapped data type that is a default match for a given ABL primitive type, you must use the default matching ABL data type, as shown in Table 23. (For example, INTEGER indicates a .NET System.Int32.) For a .NET mapped data type that is not a default match for one of the ABL primitive types, ABL provides a data type keyword (AS-data-type) that you must use to explicitly indicate the required .NET data type, as shown in Table 24. (For example, the AS data type, UNSIGNED-BYTE, indicates a .NET System.Byte.)

Note: At run time, a method parameter defined using an AS-data-type keyword behaves in ABL like the corresponding ABL primitive type shown in Table 24. (For example, an UNSIGNED-BYTE behaves like an INTEGER.)

Also note that when overriding or implementing a .NET array parameter, you must specify the .NET array object type (for example, "System.Int32[]" or "System.Byte[]"); you cannot use an ABL array equivalent (for example, INTEGER EXTENT or UNSIGNED-BYTE EXTENT).

AS [ CLASS ] { object-type-name }

Specifies the parameter you are defining as an object reference to a class instance. This can have the data type of a class or an interface.

object-type-name

Specifies the type name of an ABL or .NET class or interface. Specify an object type name using the syntax described in the Type-name syntax reference entry. With an appropriate USING statement, you can also specify a class or interface name alone, without the qualifying package or namespace.

You cannot directly specify the type name of a .NET mapped object type (such as System.Int32). To define a parameter that matches a .NET mapped type, you must define it as the corresponding ABL primitive type (primitive-type-name).

If you are defining a parameter for a method that overrides a .NET super class method (abstract or otherwise) or implements a method defined in a .NET interface, object-type-name must specify the exact .NET object type of the corresponding parameter in the overridden or implemented method. However, for .NET inner (nested) type, note the difference in the ABL syntax, which replaces the corresponding period (.) in the .NET object type with a plus (+) (see the Type-name syntax reference entry).

Also note that when overriding or implementing a .NET array parameter, you must specify the .NET array object type (for example, "System.Drawing.Point[]"); you cannot use an ABL array equivalent (such as System.Drawing.Point EXTENT).

CLASS

If the specified class or interface type name conflicts with an abbreviation for a built-in primitive type name, such as INT for INTEGER, you must specify the CLASS keyword.

For a class or interface return value, the AVM passes an object reference associated with the class or interface, not a class instance itself. For more information on object references, see the Class-based object reference reference entry.

EXTENT [ constant ]

Defines the parameter as an array of data elements with a primitive type (specified using the AS primitive-type-name option) or an object type (specified using the AS object-type-name option). This option can specify an array parameter as either determinate (has a defined number of elements) or indeterminate (has an undefined number of elements). To define a determinate array parameter, specify the EXTENT option with the constant argument. This optional argument is an integer value that represents the number of data elements in the array parameter. To define an indeterminate array parameter, specify the EXTENT option without the constant argument.

The EXTENT is part of the parameter data type. For more information, see the Type-name syntax reference entry.

An indeterminate array parameter can be in one of two states: fixed or unfixed, meaning it either has a fixed dimension or it does not. An indeterminate array parameter has an unfixed dimension when first defined. You can fix the dimension of an unfixed indeterminate array parameter by:

Setting the number of elements in the array parameter using the EXTENT statement

Defining the indeterminate array parameter so that it becomes the target of a determinate array assignment as a passed argument (on INPUT) or as a value returned from the method or user-defined function (on OUTPUT), fixing the indeterminate array to the dimension of the determinate array assignment

The AVM treats a fixed indeterminate array parameter as a determinate array parameter; that is, its size is fixed. The AVM determines the size of an unfixed indeterminate array parameter at run time.

If you are using the AS option without the EXTENT option, or you specify constant as 0, the parameter is not an array parameter.

TABLE temp-table-name

Specifies a parameter for a static temp-table.

You can pass a temp-table parameter to both local and remote user-defined functions, as well as to methods of a class. The AVM passes the parameter by value, by default. That is, the caller and the called routine each have their own instance of the temp-table. When you invoke the routine, the AVM deep-copies the parameter from one instance to the other. The table that is copied depends on whether the parameter is INPUT, OUTPUT, or INPUT-OUTPUT. When you pass a temp-table as an INPUT parameter, the AVM replaces the receiving instance with the source instance, by default. You can also append the source instance to the end of the receiving instance by specifying the APPEND option. For more information about the APPEND option, see the option description later in this reference entry.

When passing a temp-table parameter, you can override the default deep copy and pass the parameter by reference or by binding (that is, by passing the parameter using either the BY-REFERENCE or BIND option). Passing a temp-table parameter by reference or by binding allows the caller and the called routine to access the same object instance (instead of deep-copying the parameter).

For more information about passing a temp-table parameter by reference or by binding, see the Parameter passing syntax reference entry. For more information about temp-table parameters, see OpenEdge Getting Started: ABL Essentials.

TABLE-HANDLE temp-table-handle

Specifies a temp-table handle parameter.

DATASET dataset-name

Specifies a parameter for a static ProDataSet.

You can pass a ProDataSet parameter to both local and remote user-defined functions, as well as to methods of a class. The AVM passes the parameter by value, by default. That is, the caller and the called routine each have their own instance of the ProDataSet. When you invoke the routine, the AVM deep-copies the parameter from one instance to the other. The table that is copied depends on whether the parameter is INPUT, OUTPUT, or INPUT-OUTPUT. When you pass a ProDataSet as an INPUT parameter, the AVM replaces the receiving instance with the source instance, by default. You can also append the source instance to the end of the receiving instance by specifying the APPEND option. For more information about the APPEND option, see the option description later in this reference entry.

When passing a ProDataSet parameter, you can override the default deep copy and pass the parameter by reference or by binding (that is, by passing the parameter using either the BY-REFERENCE or BIND option). Passing a ProDataSet parameter by reference or by binding allows the caller and the called routine to access the same object instance (instead of deep-copying the parameter).

For more information about passing a ProDataSet object parameter by reference or by binding, see the Parameter passing syntax reference entry. For more information about ProDataSet object parameters, see OpenEdge Development: ProDataSets.

DATASET-HANDLE dataset-handle

Specifies a ProDataSet handle parameter.

APPEND

Specifies whether or not to append the data from a source instance to the receiving instance of a passed temp-table or ProDataSet parameter. To append INPUT parameter data, specify the APPEND option for the parameter in the method or user-defined function definition. To append OUTPUT parameter data, specify the APPEND option for the parameter in the method or function call.

BIND

Indicates that a TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter binds a reference-only object in one routine to an object instance defined and instantiated in another local routine.

When you define a reference-only object in the calling routine, and you want to bind that object definition to an object instance in the called routine, define the parameter by specifying the BIND option in an INPUT or INPUT-OUTPUT parameter definition. When you define a reference-only object in the called routine, and you want to bind that object definition to an object instance in the calling routine, define the parameter by specifying the BIND option in an OUTPUT parameter definition. 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 user-defined function, the AVM ignores the BIND option and deep-copies the parameter based on the specified parameter mode.

For more information about passing these parameters by binding, see the Parameter passing syntax reference entry.

BY-VALUE

Specified for an INPUT, OUTPUT, or INPUT-OUTPUT TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter in a called routine, this option forces the parameter to be passed to the local routine by value, which overrides any BY-REFERENCE option in the corresponding routine invocation. For more information on BY-REFERENCE, see the Parameter passing syntax reference entry.

BUFFER buffer-name FOR database-table-name [ PRESELECT ]

Defines a buffer parameter, where buffer-name is the name you specify for the buffer and database-table-name is the name of a database table to which the buffer is attached. Note that database-table-name can also specify the name of a temp-table. However, if the temp-table name is identical to a database table name, all ABL references to the database table name must use fully-qualified database-name.database-table-name syntax. A buffer parameter is always INPUT-OUTPUT.

Note: You cannot pass a work table buffer to a buffer parameter.

If you use the PRESELECT option and access the buffer parameter in a DO or REPEAT block, the AVM creates an internal list of the records selected. The PRESELECT option tells the AVM to apply that internal list to the buffer you define.

Note: You cannot invoke a user-defined function remotely if it has one or more buffer parameters. For more information on remote user-defined functions, see OpenEdge Application Server: Developing AppServer Applications.

Notes

When defining an overloaded method or constructor, the signature must be unique among all overloaded method or constructor definitions, respectively, with the same name. The signature consists of the name of the method or constructor, the number of parameters, and the type and mode of each of its parameters, in order from left to right. The signature of a method does not include the method return type or access mode.

So, overloading allows you to define multiple methods or constructors for a class definition, where all methods or constructors that have the same name all have different signatures. The signature cannot vary only by access mode or return type. If methods within a class definition differ only by their access modes or return types, ABL raises a compilation error.

For data types that can have an EXTENT for defining arrays, you can define overloaded methods or constructors that are distinguished only by parameters with the same data type, where:

One can have the same parameter defined as a primitive (no EXTENT)

One can have the same parameter defined with an indeterminate EXTENT

Every additional one can have the same parameter defined with a different EXTENT than all the others

You can have overloaded methods or constructors defined only with TABLE parameters or only with DATASET parameters as long as the corresponding parameter for each overloaded method or constructor is defined with a different schema from all others defined with the same type.

TABLE and TABLE-HANDLE parameters count as different data types for overloading, as do DATASET and DATASET-HANDLE parameters. However, because the schema is not known at compile time, you can define only one overloaded method or constructor with a TABLE-HANDLE parameter corresponding to other method or constructor parameters that differ only as TABLE parameters. Similarly, you can define only one overloaded method or constructor with a DATASET-HANDLE parameter corresponding to other overloaded method or constructor parameters that differ only as DATASET parameters.

At compile time, it might not be possible to identify a unique overloaded method to call that is passed a TABLE-HANDLE or DATASET-HANDLE parameter. Without a schema defined, this parameter type matches any respective TABLE or DATASET parameter, as well as any respective TABLE-HANDLE or DATASET-HANDLE parameter. Where such overloaded alternatives exist, the AVM resolves the correct method to call at run time. For more information, see the Parameter passing syntax reference entry.

A BUFFER parameter cannot be a REFERENCE-ONLY buffer or a BEFORE-TABLE buffer. Using either of these as a BUFFER type of parameter (as opposed to INPUT or OUTPUT) is a compiler error. Instead of passing the buffer, the buffer's table can be passed by-reference.