Progress
Language Reference
DEFINE PARAMETER Statement
Defines a run-time parameter in a Progress subprocedure, Windows dynamic link library (DLL) routine or UNIX shared library routine. Each parameter requires its own DEFINE statement. The parameters must be specified in the RUN statement in the same order they are defined with DEFINE statements. In addition, the parameter types (INPUT, OUTPUT, INPUT-OUTPUT, RETURN, and BUFFER) specified in the DEFINE and RUN statements must agree. The corresponding data types and run-time values must also be compatible enough to allow Progress to perform any necessary conversions.
SYNTAX
INPUT PARAMETER
Defines a parameter that gets its value from one of the following sources:
- If the calling procedure runs the current (called) procedure synchronously, the value comes from the corresponding INPUT parameter of the RUN statement.
- If the current procedure is the event procedure specified to handle the PROCEDURE-COMPLETE event for an asynchronous remote procedure, the value comes from the corresponding OUTPUT or INPUT-OUTPUT parameter of the remote procedure.
OUTPUT PARAMETER
Defines a parameter that returns a value to one of the following destinations:
- If the calling procedure runs the current (called) procedure synchronously, the value is returned to the corresponding OUTPUT parameter of the RUN statement in the calling procedure.
- If the calling procedure runs the current (called) procedure as an asynchronous remote procedure, the value is returned to the corresponding INPUT parameter of the event procedure specified to handle the PROCEDURE COMPLETE event for the current procedure.
INPUT-OUTPUT PARAMETER
Defines a parameter that receives an initial value passed from the calling procedure that can be subsequently modified by the called procedure. The calling procedure cannot pass a literal value. The called procedure returns the modified value to one of the following destinations:
- If the calling procedure runs the current (called) procedure synchronously, the value is returned to the corresponding INPUT-OUTPUT parameter of the RUN statement in the calling procedure.
- If the calling procedure runs the current (called) procedure as an asynchronous remote procedure, the value is returned to the corresponding INPUT parameter of the event procedure specified to handle the PROCEDURE COMPLETE event for the current procedure.
RETURN PARAMETER
Defines a parameter that holds the return value of a DLL or UNIX shared library routine. When the DLL routine returns, the value of this parameter is passed back to the calling procedure. You can only have one RETURN parameter per routine.
parameter
Identifies the name of the parameter you want to define.
AS [ HANDLE [ TO ] ] datatype
Specifies the data type of the parameter.
For Progress subprocedures, datatype can specify any standard Progress data type used to define variables. For more information, see the reference entry for the DEFINE VARIABLE Statement. The HANDLE option has no effect on parameters passed to Progress subprocedures.
For DLL or UNIX shared library routines, datatype can specify a Progress DLL data type. Progress DLL data types include the standard Progress data types CHARACTER and MEMPTR or a Windows DLL-equivalent data type.
Table 22 shows how Windows DLL data types map to Progress DLL data types.
Table 22: Data Types for DLL Routine Parameters Windows DLL Data Type Progress DLL Data Type 4-byte floating point FLOAT 8-byte floating point DOUBLE Character string (null-terminated) CHARACTER 16-bit signed integer SHORT 16-bit unsigned integer UNSIGNED-SHORT 32-bit signed integer LONG1 Single character BYTE Structure or character string (null-terminated)
- To pass a NULL value to a DLL routine, pass 0 to a LONG parameter. Do not use a null MEMPTR variable to pass a NULL value. If this conflicts with another way to call the DLL routine, specify a second declaration for the same routine using the ORDINAL option of the PROCEDURE statement.
- For RETURN parameters returning character strings, datatype can only specify MEMPTR.
To indicate that the DLL or UNIX shared library parameter is a pointer to a value rather than the value itself, use the HANDLE option. The HANDLE option is required when the DLL routine expects a pointer to the value. Note that the CHARACTER data type implies the HANDLE option, whether or not you specify it. The TO keyword aids readability but has no meaning.
For ActiveX control event procedures, datatype can specify the standard Progress data type that maps to the COM object data type of an ActiveX event parameter. Table 23 shows how the COM object data types for event parameters (shown as ActiveX data types) map to Progress data types.
Table 23: Data Types for ActiveX Control Event Procedures ActiveX Data Type1 Progress Data Type Boolean (2-byte integer) LOGICAL Byte (unsigned byte) INTEGER Currency (8-byte integer with fixed decimal point) DECIMAL Date (8-byte floating point) DATE Double (8-byte floating point) DECIMAL Integer (2-byte integer) INTEGER Long (4-byte integer) INTEGER Object (32-bit value) COM-HANDLE Single (4-byte floating point) DECIMAL String (character string type) CHARACTER Unsigned Byte INTEGER Unsigned Long (4-byte integer) INTEGER Unsigned Short (2-byte integer) INTEGER Variant (variable type) <ANYTYPE>2
- For more information on these data type implementations for COM objects, see the Progress External Program Interfaces manual.
- For Variant event parameters, the AppBuilder specifies <ANYTYPE> as a place holder. You must change <ANYTYPE> to the data type that most closely matches the expected value. For more information, see the available documentation on the event parameter.
LIKE, CASE SENSITIVE, FORMAT, DECIMALS, INITIAL, COLUMN-LABEL, LABEL, NO-UNDO
For descriptions of these options, see the DEFINE VARIABLE Statement reference entry.
NOTE: The INITIAL and LABEL options do not support array elements, as in the DEFINE VARIABLE Statement.PARAMETER BUFFER buffer FOR table [ PRESELECT ] [ LABEL label ]
Defines a buffer parameter. You can pass a buffer associated with a database table to a buffer parameter. You cannot pass a work table to a buffer parameter. A buffer parameter is always INPUT-OUTPUT.
For descriptions of the PRESELECT and LABEL options, see the DEFINE BUFFER Statement reference entry.
temp-table-name
The name of a temporary table.
When you use a temporary table parameter, the calling procedure and the called procedure each have a separate temporary table. When the call (the RUN statement) occurs, Progress sends one temporary table’s data across to the other temporary table. Which data travels depends on whether the parameter is INPUT, OUTPUT, or INPUT-OUTPUT. In any case, the traveling data either overlays the stationary data (if APPEND does not appear), or else appends itself to the end of the stationary data (if APPEND does appear). For more information on temporary table parameters, see the Progress Programming Handbook .
temp-table-handle
The handle of a temporary table object.
FOR ... APPEND
Determines whether or not to append the traveling temporary table data to the stationary temporary table data.
For temp-table-name, FOR is required and APPEND is optional.
For temp-table-handle, both FOR and APPEND are optional and are used together. Without the FOR keyword, the temp-table handle is local to the called procedure - it is created when the procedure starts and deleted when the procedure completes. Therefore, there is nothing to APPEND the received data to. When the FOR keyword is used, the temp-table handle is defined at a higher level outside the called procedure and continues to exist after the called procedure completes.
NOTE: APPEND is used only with the DEFINE INPUT PARAMETER statement. To APPEND output parameter data, the APPEND keyword is added to the RUN statement.EXAMPLESIn the following examples, the
r-runpar.p
procedure runs a subprocedure calledr-param.p
and passes the subprocedure an INPUT parameter. The subprocedurer-param.p
displays the INPUT parameter.
In the following example, the
r-runpr1.p
procedure runs a subprocedure calledr-param1.p
. This example illustrates the use of multiple parameters and shows that the parameters must be passed in the proper order and must be of the same data type. Note that if you do not specify a parameter type in the RUN statement, Progress assumes it is an input parameter.
In the following example, the
r-runpr2.p
procedure displays information from a database table and assigns the value of a database field to a variable called io-param. The variable is passed as an INPUT-OUTPUT parameter to a subprocedure calledr-param2.p
. The subprocedurer-param2.p
performs a calculation on the INPUT-OUTPUT parameter, then passes it back to the main procedure. Ther-runpr2.p
assigns the value io-param to a database field, then displays io-param.
The following example uses a buffer parameter. The procedure
r-bufp.p
passes the Customer buffer tor-fincus.p
. Ther-fincus.p
procedure then attempts to find a record using that buffer.
The following example defines parameters for the DLL routine,
MessageBox()
, which displays a message on the screen.
NOTES
- All procedure parameters are passed by value. This means that for any INPUT-OUTPUT or OUTPUT parameter, the field or variable that receives the output value is not set by the called procedure until and unless the procedure returns without error.
- You cannot pass an array as a parameter.
- Buffer parameters are scoped in the same way as shared buffers. They also affect cursors defined in the calling procedure in the same way as shared buffers.
- For DLL or UNIX shared library routine declarations, field can only be a database field of type CHARACTER or a variable of type CHARACTER or MEMPTR.
- For DLL or UNIX shared library routine declarations, the COLUMN, COLUMN-LABEL, DECIMALS, INITIAL, FORMAT, LABEL, and NO-UNDO options have no effect.
- For more information on DLL routine parameters and how they map to Progress data types, see the chapter on DLLs in the Progress External Program Interfaces manual.
- RETURN parameters are supported only for DLL or UNIX shared library routines. The RETURN parameter type must match the OUTPUT parameter that returns the DLL function value in the RUN statement for the routine.
- If you specify a RETURN parameter as MEMPTR to return a character string, use the GET-STRING function to extract the CHARACTER value.
- For more information on using ActiveX event parameters, see the chapter on ActiveX in the Progress External Program Interfaces manual.
- For dynamic temp-table parameters:
- If the parameter is INPUT TABLE-HANDLE, the temp-table definition behind the handle plus the temp-table contents are sent from the caller to the called routine. The called routine may have either the dynamic INPUT TABLE-HANDLE or the static INPUT TABLE as a matching parameter.
- If the parameter is INPUT TABLE-HANDLE, a new instance of the temp-table is created along with its handle, completely separate from the caller’s table, and is populated with the contents from the caller’s table.
- If the parameter is OUTPUT TABLE-HANDLE, the handle plus the definition behind the handle are sent from the caller to the called routine. The called routine may have either the dynamic OUTPUT TABLE-HANDLE or the static OUTPUT TABLE as a matching parameter.
- If the parameter is OUTPUT TABLE-HANDLE, and the handle is NULL, no definition is sent to the called routine.
- If the parameter is OUTPUT TABLE-HANDLE, the called routine sends back the definition behind the handle along with the contents of the output temp-table. In the caller, if the original handle was NULL, a new instance of the temp-table is created and populated with the output contents. The new table replaces any pre-existing table in the caller unless the APPEND keyword was used. In that case, the new table is added to the pre-existing table.
- If the parameter is INPUT-OUTPUT TABLE-HANDLE, a combination of the above will occur. If the temp-table is local, its handle will be used to identify it for both the caller and called routines so that it need not be copied.
- If you call a remote procedure asynchronously (using the ASYNCHRONOUS option of the RUN statement) and pass a parameter as OUTPUT TABLE-HANDLE temp-table-handle APPEND, the event procedure must specify a corresponding DEFINE INPUT PARAMETER TABLE-HANDLE FOR temp-table-handle APPEND statement, and temp-table-handle must be global to both the calling procedure and the event procedure.
- If you define an INPUT parameter for an asynchronous event procedure with a data type that is different from the data type of the corresponding OUTPUT parameter passed from the AppServer, note that any failure to convert the passed value causes the event procedure to fail and Progress to display an error message on the client.
- For more information on working with asynchronous remote procedures and event procedures, see the Building Distributed Applications Using the Progress AppServer manual.
SEE ALSO
DEFINE BUFFER Statement, DEFINE VARIABLE Statement, DELETE PROCEDURE Statement, RUN Statement
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |