User Tools

Site Tools


prototype_syntax.htm
Navigation:  Language Reference > 2 - Program Source Code Format > PROCEDURE Prototypes >====== Prototype Syntax ====== Previous pageReturn to chapter overviewNext page

name PROCEDURE [(parameter list)] [,return type] [,calling convention] [,RAW] [,NAME( )] [,TYPE] [,DLL( )]  [,PROC] [,PRIVATE] [,VIRTUAL] [,PROTECTED] [,REPLACE] [,DERIVED]

name[(parameter list)] [,return type] [,calling convention] [,RAW] [,NAME( )] [,TYPE] [,DLL( )]

[, PROC] [, PRIVATE]

blk2blue.jpg

name The label of a PROCEDURE statement that defines the executable code.
PROCEDURE Required keyword.
parameter list The data types of the parameters. Each parameter's data type may be followed by a label used to document the parameter (only). Each numeric value parameter may also include an assignment of the default value (a constant) to pass if the parameter is omitted.
return type The data type the PROCEDURE will RETURN.
calling convention Specify the C or PASCAL stack-based parameter calling convention.
RAW Specifies that STRING or GROUP parameters pass only the memory address (without passing the length of the passed string). It also alters the behaviour of ? and *? parameters. This attribute is only for 3GL language compatibility and is not valid on a Clarion language procedure.
NAME Specify an alternate, “external” name for the PROCEDURE.
TYPE Specify the prototype is a type definition for procedures passed as parameters.
DLL Specify the PROCEDURE is in an external .DLL.
PROC Specify the PROCEDURE with a return type may be called as a PROCEDURE without a return type without generating a compiler warning.
PRIVATE Specify the PROCEDURE may be called only from another PROCEDURE within the same MODULE. Can be used by a CLASS method or a local declared PROCEDURE.
VIRTUAL Specify the PROCEDURE is a virtual method of a CLASS structure.
PROTECTED Specify the PROCEDURE may be called only from another PROCEDURE within the same CLASS or any directly derived CLASS.
REPLACE Specify the “Construct” or “Destruct” PROCEDURE in the derived CLASS completely replaces the constructor or destructor of its parent CLASS.
DERIVED Specify the PROCEDURE is a derived method of a CLASS structure, There must be a matching prototype in the parent class.

All PROCEDUREs in a PROGRAM must have a prototype declaration in a MAP or CLASS structure. A prototype declares to the compiler exactly what form to expect to see when the PROCEDURE is used in executable code.

There are two valid forms of prototype declarations listed in the syntax diagram on the previous page. The first one, using the PROCEDURE keyword, is valid for use everywhere and is the preferred form to use. The second form is supported only for backward compatibility with previous versions of Clarion.

A prototype contains:

·The name of the PROCEDURE.

·The keyword PROCEDURE is optional in a MAP structure, but required in a CLASS structure.

·An optional parameter list specifying all parameters that will be passed in.

·The data return type, if the prototype is for a PROCEDURE which will return a value.

·The parameter calling convention, if you are linking in objects that require stack-based parameter passing (such as objects that were not compiled with a Clarion TopSpeed compiler).

·The RAW, NAME, TYPE, DLL, PROC, PRIVATE, VIRTUAL, PROTECTED, and DERIVED attributes, as needed.

You can optionally specify the C (right to left) or PASCAL (left to right and compatible with Windows 32-bit) stack-based parameter calling convention for your PROCEDURE. This provides compatibility with third-party libraries written in other languages (if they were not compiled with a TopSpeed compiler). If you do not specify a calling convention, the default is the internal, register-based parameter passing convention used by all the TopSpeed compilers.

The RAW attribute allows you to pass just the memory address of a *?, STRING, or GROUP parameter (whether passed by value or by reference) to a non-Clarion language procedure or function. Normally, STRING or GROUP parameters pass both the address and the length of the string. The RAW attribute eliminates the length portion. This is provided for compatibility with external library functions which expect only the address of the string.

The NAME attribute provides the linker an external name for the PROCEDURE. This is also provided for compatibility with libraries written in other languages. For example: in some C language compilers, with the C calling convention specified, the compiler adds a leading underscore to the function name. The NAME attribute allows the linker to resolve the name of the function correctly.

The TYPE attribute indicates the prototype does not reference a specific PROCEDURE. Instead, it defines a prototype name used in other prototypes to indicate the type of procedure passed to another PROCEDURE as a parameter.

The DLL attribute specifies that the PROCEDURE prototype on which it is placed is in a .DLL. The DLL attribute is required for 32-bit applications because .DLLs are relocatable in a 32-bit flat address space, which requires one extra dereference by the compiler to address the procedure.

The PRIVATE attribute specifies that only another PROCEDURE that is in the same MODULE may call it. This would most commonly be used on a prototype in a module's MAP structure, but may also be used in the global MAP.

When the name of a prototype is used in the parameter list of another prototype, it indicates the procedure being prototyped will receive the label of a PROCEDURE that receives the same parameter list (and has the same return type, if it returns a value). A prototype with the TYPE attribute may not also have the NAME attribute.

Example:

MAP

MODULE('Test')                                !'test.clw' contains these procedures

MyProc1 PROCEDURE(LONG)                        !LONG value-parameter

MyProc2 PROCEDURE(<;*LONG>)                     !Omittable LONG variable-parameter

MyProc3 PROCEDURE(LONG=23)                     !Passes 23 if omitted

END

MODULE('Party3.Obj')                          !A third-party library

Func46 PROCEDURE(*CSTRING),REAL,C,RAW          !Pass CSTRING address-only to C function

Func47 PROCEDURE(*CSTRING),*CSTRING,C,RAW      !Returns pointer to a CSTRING

Func48 PROCEDURE(REAL),REAL,PASCAL             !PASCAL calling convention

Func49 PROCEDURE(SREAL),REAL,C,NAME('_func49') !C convention and external function name

END

MODULE('STDFuncs.DLL')                        !A standard functions .DLL

Func50 PROCEDURE(SREAL),REAL,PASCAL,DLL(dll_mode)

END

END

PRIVATE Example1:

MyClass CLASS

MyProc1  PROCEDURE()

MyProc2  PROCEDURE(),PRIVATE

       END

!MyProc2 can only be called from MyProc1

PRIVATE Example2:

MEMBER

MAP

MyLocalProc PROCEDURE(),PRIVATE

END

!MyLocalProc will only be accessible to any other procedure/method declared within this module

NoteBox.jpg

The PRIVATE attribute allows you to define the same internal PRIVATE procedure in more than one un-named MEMBER.

PRIVATE should always be used for procedures and data objects local to a member module unless they are exported or used in other modules.

See Also:

MAP

MEMBER

MODULE

NAME

PROCEDURE

RETURN

Prototype Parameter Lists

Procedure Overloading

CLASS

prototype_syntax.htm.txt · Last modified: 2021/04/15 15:57 (external edit)