Defines an internal procedure as an ABL procedure or declares an internal procedure
prototype for an external routine in a Windows dynamic link library (DLL) or UNIX shared
library, or for an internal ABL procedure defined in an external procedure that is itself a
super procedure of the declaration procedure. The following syntax boxes describe the syntax
for each use of the statement, beginning with an internal procedure definition.
Syntax
PROCEDURE proc-name[ PRIVATE ] :
[procedure-body]
|
This is the syntax to declare an internal procedure prototype for a routine in a Windows
DLL or UNIX shared library, or for an internal ABL procedure defined in a super
procedure:
PROCEDURE proc-name
{ EXTERNAL "dllname" [ CDECL | PASCAL | STDCALL ]
[ ORDINAL n ][ PERSISTENT ][ THREAD-SAFE ]
| IN SUPER } :
[ procedure-body ]
|
-
proc-name
- The name of the internal procedure.
To define the name of an internal ABL procedure
that is an event handler for ActiveX controls (OCX event procedure), you must specify
proc-name according to the following syntax:
{control-frame-name.control-name.event-name | ANYWHERE.event-name}
|
For more information on naming event handlers for ActiveX controls using this
syntax, see the notes for this reference entry.
- EXTERNAL "dllname"
- Declares the internal procedure as a Windows DLL or UNIX shared library routine.
The dllname argument, specified as a string literal, is the
name of the DLL or library containing the routine. The value of dllname
can contain Unicode characters. See OpenEdge Development:
Internationalizing Applications for more information about Unicode.
- CDECL
- Tells ABL to use the C calling convention when accessing the routine.
- PASCAL
- Supported only for backward compatibility. This option is not valid for
SpeedScript.
- STDCALL
- Tells ABL to use the standard Windows calling convention when accessing the
routine. This is the default.
Note: The 64-bit Windows GUI and
character clients ignore the CDECL, PASCAL, and STDCALL calling conventions if
they are specified. The 64-bit Windows GUI and character clients always use the
standard 64-bit FASTCALL calling convention.
- ORDINAL n
- Specifies the number of the DLL entry point (the nth routine)
to invoke. If you use the ORDINAL option, then proc-name can
specify any name used in the corresponding RUN statement to reference the routine.
If you omit the ORDINAL option, proc-name specifies which DLL
routine you want to invoke.
For UNIX shared library routines, this option does
not apply and is ignored.
- PERSISTENT
- Specifies that the DLL or shared library routine should remain loaded in memory
until the AVM exits or the session executes the RELEASE EXTERNAL statement.
- THREAD-SAFE
- Specifies that the DLL or shared library routine is thread
safe. When a DLL or shared library is marked as THREAD-SAFE, multiple sessions can
access it simultaneously. This option is only valid when running an application on an
instance of the Progress Application Server for OpenEdge; otherwise, this option does not
apply and is ignored.
- PRIVATE
- Indicates the following about the internal procedure:
- It cannot be invoked from an external procedure—that is, from a procedure
file external to the current procedure file.
- The INTERNAL-ENTRIES attribute on the procedure that defines it does not
provide its name (unless the procedure that defines it is the current
procedure file).
- The GET-SIGNATURE method on the procedure that defines it does not provide
its signature (unless the procedure that defines it is the current procedure
file).
- IN SUPER
- Declares that the definition of the internal procedure resides in a super
procedure. For more information on super procedures, see OpenEdge Development: ABL Handbook.
- procedure-body
- The body of an internal procedure definition. Define
procedure-body using the following syntax:
procedure-logic
.
.
.
[ catch-block [ catch-block...]]
[ finally-block ]
[ END [ PROCEDURE ] . ]
|
- procedure-logic
- Zero or more ABL statements, depending on the internal procedure definition or
declaration. Each logic statement must end in with a period (.).
If you declare
the internal procedure as an ABL procedure, these statements can include
executable statements and non-executable statements including definitions of
run-time parameters (using the DEFINE PARAMETER statement), local program
variables, frames, widgets, and buffers. Any such objects you define within the
internal procedure remain in effect only for the life of the internal
procedure.
If you are defining the internal procedure for use as an event
procedure to handle asynchronous remote requests, you can specify run-time
parameters as INPUT only. (Any other type of parameter generates a run-time
error.) Each INPUT parameter must correspond in order and data type with an
OUTPUT (or INPUT-OUTPUT) parameter as defined in the remote procedure that
executes the request. For more information on working with asynchronous remote
requests and event procedures, see OpenEdge Application Server: Developing
AppServer Applications.
If you declare the internal procedure as
a DLL or UNIX shared library routine (using the EXTERNAL option), these
statements can include only DEFINE PARAMETER statements.
For more
information on accessing DLL or UNIX shared library routines from ABL, see the
chapter on DLLs in OpenEdge Development: Programming
Interfaces.
- catch-block
- Specifies a CATCH statement that defines error handling code for one or more
error types. A DO block does not have any default error handling. Therefore, a DO
block must have error handling options specified such that it becomes an undoable
block. Otherwise, ABL generates a compiler warning. For more information on
catch-block, see the CATCH statement reference entry.
- finally-block
- Specifies a FINALLY statement that defines the processing that must occur after
all other processing in the block occurs. For more information on
finally-block, see the FINALLY statement reference entry.
- END [ PROCEDURE ]
- Specifies the end of the internal procedure body. If
procedure-logic contains one or more statements, you must end
the internal procedure body with the END statement.
Example
The following example declares an ABL internal procedure that computes the factorial of an
integer entered as an INPUT parameter. The result is returned as an OUTPUT parameter. Note
that the following procedure calls itself recursively to obtain the result:
r-factrl.p
DEFINE VARIABLE FactorialResult AS INTEGER NO-UNDO FORMAT ">>>,>>>,>>9".
DEFINE VARIABLE FactorialInput AS INTEGER NO-UNDO.
REPEAT:
SET FactorialInput VALIDATE(FactorialInput <= 12 AND FactorialInput >= 0,
"Value must be between 0 and 12.").
RUN Factorial (INPUT FactorialInput, OUTPUT FactorialResult).
DISPLAY FactorialResult.
END.
PROCEDURE Factorial:
DEFINE INPUT PARAMETER PTerm AS INTEGER NO-UNDO.
DEFINE OUTPUT PARAMETER FactorialResult AS INTEGER NO-UNDO.
DEFINE VARIABLE WorkingResult AS INTEGER NO-UNDO.
IF PTerm <= 1 THEN DO:
FactorialResult = 1.
RETURN.
END.
ELSE DO:
RUN Factorial (INPUT PTerm - 1, OUTPUT WorkingResult).
FactorialResult = PTerm * WorkingResult.
END.
END PROCEDURE.
|
The following example declares a DLL routine, MessageBox(), which displays
a message:
r-dllex1.p
DEFINE VARIABLE iResult AS INTEGER NO-UNDO.
MESSAGE " It's a whole new world!"
VIEW-AS ALERT-BOX MESSAGE BUTTONS OK TITLE "ABL Message".
RUN MessageBoxA (0, " It's a whole new world, again!!",
"ABL DLL Access", 0, OUTPUT iResult).
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.
|
The following code fragment declares a UNIX shared library routine:
PROCEDURE atoi EXTERNAL "/usr/lib/libc.so.1":
...
|
Notes
- You can terminate a PROCEDURE statement with either a period (.) or a colon (:), but
typically use a colon (:) for a procedure definition or prototype that includes
procedure-body and a period (.) for a procedure definition or
prototype that omits any procedure-body.
- You can place an internal procedure definition or declaration before, after, or in the
middle of your main procedure code. You cannot nest an internal procedure within
another internal procedure.
- Use the RUN statement to invoke an internal procedure. You can run an internal procedure
from within the external procedure that defines it, either from the main-line of the
external procedure or from another internal procedure defined in the external procedure.
You can also run an internal procedure defined in another external procedure using the IN
proc-handle option of the RUN statement as long as the external
procedure meets one of these conditions:
- It is active on the procedure call stack
- It is an instance of a persistent procedure
- You cannot define shared objects, work tables, or temp-tables within an internal
procedure.
- An internal procedure can reference any objects defined in the outer procedure block.
For example, it can reference variables, buffers (explicit or implicit; shared or
unshared), variables, run-time parameters, named frames, or temp-tables. If you define an
object with the same name in the internal procedure and the external procedure, a
reference within the internal procedure resolves to the local object.
- A buffer explicitly defined in an internal procedure is scoped to the internal
procedure. Any other buffers are scoped to the outer procedure block.
- To define the internal procedure as an event handler for ActiveX controls (OCX event
procedure), you must specify proc-name according to the following
syntax:
{ control-frame-name .control-name .event-name
| ANYWHERE .event-name
}
|
In
control-frame-name.control-name.event-name,
control-frame-name is the name (unquoted) of the control-frame that
contains the ActiveX control. This is the name that the AppBuilder typically assigns to
the control-frame (NAME widget attribute) when you insert the control into your user
interface. The control-name is the value (unquoted) that you assign
to the control Name property at design time in the AppBuilder Property Window. The
event-name is the name (unquoted) of the ActiveX control event that
you want to trigger execution of this procedure.
In
ANYWHERE.event-name, ANYWHERE specifies an event procedure that
handles the specified event in any ActiveX control. This event procedure executes only
if you have not defined a
control-frame-name.control-name.event-name
event procedure that exactly matches the control/event combination at run time.
At
design time, the AppBuilder lists the available events for a control and automatically
creates a template for the OCX event procedure definition from the event that you
select. For more information on how to create OCX event procedures in the AppBuilder,
see the information on ActiveX controls in OpenEdge Development: Programming
Interfaces. For more information on how to work with OCX event procedures in an
application, see OpenEdge Development: Programming Interfaces.
- When you define an OCX event procedure, you can access the component handle (COM-HANDLE
value) of the control that generates the event at run time using the COM-SELF system
handle. You can also access the handle of the parent control-frame using the SELF system
handle.
- The RETURN-VALUE function provides the value returned by the most recently executed
RETURN statement of a local or remote procedure.
- You use the call object handle to dynamically invoke a Windows DLL routine or UNIX
shared library routine at run time.