Clarion Community Help

A PROCEDURE prototyped with a return value must RETURN a value. The data type to return is listed, separated by a comma, after the optional parameter list.

Value RETURN types:

An untyped value-parameter return value (?) indicates the data type of the value returned by the PROCEDURE is not known. This functions in exactly the same manner as an untyped value-parameter. When the value is returned from the PROCEDURE, standard Clarion Data Conversion Rules apply, no matter what data type is returned.

Variable RETURN types:

Untyped variable-parameter (*?)

Variable return types are provided just for prototyping external library functions (written in another language) which return only the address of data–they are not valid for use on Clarion language procedures.

Functions which return pointers (the address of some data) should be prototyped with an asterisk prepended to the return data type. The compiler automatically handles the returned pointer at runtime. Functions prototyped this way act just like a variable defined in the program–when the function is used in Clarion code, the data referenced by the returned pointer is automatically used. This data can be assigned to other variables, passed as parameters to procedures, or the ADDRESS function may return the address of the data.

CSTRING is an exception because all the others are fixed length datums, and a CSTRING is not. So, any C function that returns a pointer to a CSTRING can be prototyped as “char *” at the C end, but the compiler thunks the procedure and copies the datum onto the stack. Therefore, just like the other pointer return values, when the function is used in Clarion code the data referenced by the returned pointer is automatically used (the pointer is dereferenced).

As an example of this, assume that the XYZ() function returns a pointer to a CSTRING, CStringVar is a CSTRING variable, and LongVar is a LONG variable. The simple Clarion assignment statement, CStringVar = XYZ(), places the data referenced by the XYZ() function's returned pointer, in the CStringVar variable. The assignment, LongVar = ADDRESS(XYZ()), places the memory address of that data in the LongVar variable.

An untyped variable-parameter return value (*?) indicates the data type of the variable returned by the PROCEDURE is not known. This functions in exactly the same manner as an untyped variable-parameter.

Reference RETURN types:

Named CLASS (*ClassName)

Named QUEUE (*QueueName)

A PROCEDURE may return a reference which may either be assigned to a reference variable, or used in a parameter list wherever the referenced object would be appropriate. A PROCEDURE that returns *WINDOW may also return the label of an APPLICATION or REPORT structure. NULL is a valid value to return.

Example:

MAP

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

Func46 PROCEDURE(*CSTRING),REAL,C,RAW

                      !Pass CSTRING address-only to C function, return REAL

Func47 PROCEDURE(*CSTRING),CSTRING,C,RAW

                      !Returns pointer to a CSTRING

Func48 PROCEDURE(REAL),REAL,PASCAL

                      !PASCAL calling convention, return REAL

Func49 PROCEDURE(SREAL),REAL,C,NAME('_func49')

                      !C convention and external function name, return REAL

 END

END

See Also:

MAP

MEMBER

MODULE

NAME

PROCEDURE

RETURN

Reference Variables