| **Navigation:**  [[introduction.htm|Language Reference]] > 2 - Program Source Code Format > PROCEDURE Prototypes >====== Prototype Syntax ====== | [[procedure prototypes.htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[prototype parameter lists.htm|{{btn_next_n.gif|Next 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|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|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  declare procedure prototypes .htm|MAP]]

[[member  identify member source file .htm|MEMBER]]

[[module  specify member source file .htm|MODULE]]

[[name  set prototype s external name .htm|NAME]]

[[procedure  define a procedure .htm|PROCEDURE]]

[[return  return to caller .htm|RETURN]]

[[prototype parameter lists.htm|Prototype Parameter Lists]]

[[procedure overloading.htm|Procedure Overloading]]

[[class  object declaration .htm|CLASS]]