Progress
Language Reference


DEFINE PARAMETER Statement

Interfaces
OS
SpeedScript
All
All
Yes

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

DEFINE { INPUT | OUTPUT | INPUT-OUTPUT | RETURN } 
  PARAMETER parameter
  { { LIKE field } | { AS [ HANDLE [ TO ] ]  datatype } }
  [ [ NOT ] CASE-SENSITIVE ]
  [ FORMAT string ]
  [ DECIMALS n ]
  [ INITIAL constant ]
  [ COLUMN-LABEL label ]
  [ LABEL string ]
  [ NO-UNDO ] 

DEFINE PARAMETER BUFFER buffer FOR table
  [ PRESELECT ]
  [ LABEL label ] 

DEFINE { INPUT | INPUT-OUTPUT }
  PARAMETER TABLE FOR temp-table-name [ APPEND ] 

DEFINE { OUTPUT }
  PARAMETER TABLE FOR temp-table-name 

DEFINE { INPUT | INPUT-OUTPUT }
  PARAMETER TABLE-HANDLE [ FOR ] temp-table-handle [ APPEND ] 

DEFINE { OUTPUT }
  PARAMETER TABLE-HANDLE [ FOR ] temp-table-handle 

INPUT PARAMETER

Defines a parameter that gets its value from one of the following sources:

OUTPUT PARAMETER

Defines a parameter that returns a value to one of the following destinations:

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:

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)
MEMPTR1,2
  1. 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.
  2. 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
  1. For more information on these data type implementations for COM objects, see the Progress External Program Interfaces manual.
  2. 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.

EXAMPLES

In the following examples, the r-runpar.p procedure runs a subprocedure called r-param.p and passes the subprocedure an INPUT parameter. The subprocedure r-param.p displays the INPUT parameter.

r-runpar.p
RUN r-param.p (INPUT 10). 

r-param.p
DEFINE INPUT PARAMETER int-param AS INTEGER.
DISPLAY int-param LABEL "Integer input param"
  WITH SIDE-LABELS. 

In the following example, the r-runpr1.p procedure runs a subprocedure called r-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.

r-runpr1.p
DEFINE VARIABLE new-param AS CHARACTER FORMAT "x(20)".
DEFINE VARIABLE out-param AS DECIMAL.
DEFINE VARIABLE in-param AS INTEGER INIT 20.
RUN r-param1.p (OUTPUT out-param, 10, OUTPUT new-param, in-param).
DISPLAY out-param LABEL "Updated YTD Sales" SKIP 
    new-param LABEL "Status" 
    WITH SIDE-LABELS. 

r-param1.p
DEFINE OUTPUT PARAMETER xout-param AS DECIMAL.
DEFINE INPUT PARAMETER newin AS INTEGER.
DEFINE OUTPUT PARAMETER xnew-param AS CHARACTER.
DEFINE INPUT PARAMETER xin-param AS INTEGER.

FOR EACH customer:
   xout-param = balance + xout-param.
END.

DISPLAY xout-param LABEL "Balance" WITH SIDE-LABELS.
xout-param = xout-param + newin + xin-param.
xnew-param = "Example Complete". 

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 called r-param2.p. The subprocedure r-param2.p performs a calculation on the INPUT-OUTPUT parameter, then passes it back to the main procedure. The r-runpr2.p assigns the value io-param to a database field, then displays io-param.

r-runpr2.p
DEFINE VARIABLE io-param AS INTEGER.

FOR EACH item:
  DISPLAY Item-name On-hand WITH 1 DOWN.
  io-param = Item.On-hand.
  RUN r-param2.p (INPUT-OUTPUT io-param).
  Item.On-hand = io-param.
  DISPLAY io-param LABEL "New Quantity On-hand".
END. 

r-param2.p
DEFINE INPUT-OUTPUT PARAMETER io-param AS INTEGER.
DEFINE VARIABLE inp-qty AS INTEGER.
PROMPT-FOR inp-qty LABEL "Quantity Received?".
ASSIGN inp-qty.
io-param = io-param + inp-qty. 

The following example uses a buffer parameter. The procedure r-bufp.p passes the Customer buffer to r-fincus.p. The r-fincus.p procedure then attempts to find a record using that buffer.

r-bufp.p
DEFINE BUTTON find-butt LABEL "Find Customer".

ENABLE find-butt Customer.Cust-num WITH FRAME cust-frame.

ON CHOOSE OF find-butt
  DO: 
     RUN r-fincus.p(INPUT Customer.Cust-num:HANDLE IN FRAME cust-frame,
                    BUFFER Customer). 
     DISPLAY Customer WITH FRAME cust-frame.
  END.

ON ENTRY OF Customer.Cust-num
  HIDE MESSAGE.
  
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.   

r-fincus.p
DEFINE INPUT PARAMETER  wid-hand  AS WIDGET-HANDLE.
DEFINE PARAMETER BUFFER curr-buff FOR Customer.

FIND curr-buff WHERE curr-buff.Cust-num = 
                     INT(wid-hand:SCREEN-VALUE) NO-ERROR.

IF NOT AVAILABLE(curr-buff)
THEN DO:
   MESSAGE "Record not found.".
   RETURN ERROR.
END. 
   
RETURN. 

The following example defines parameters for the DLL routine, MessageBox(), which displays a message on the screen.

r-dllex1.p
DEFINE VARIABLE result AS INTEGER.

MESSAGE "  It’s a whole new world!"
  VIEW-AS
    ALERT-BOX MESSAGE
    BUTTONS OKtttttttttt
    TITLE "Progress Message".

RUN MessageBoxA (0, "  It’s a whole new world, again!!", 
      "Progress DLL access", 0, OUTPUT result).

PROCEDURE MessageBoxA EXTERNAL "user32.dll":
  DEFINE INPUT PARAMETER hwnd AS LONG.
  DEFINE INPUT PARAMETER mbtext AS CHARACTER.
  DEFINE INPUT PARAMETER mbtitle AS CHARACTER.
  DEFINE INPUT PARAMETER style AS LONG.
  DEFINE RETURN PARAMETER result AS LONG.
END. 

NOTES

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