| **Navigation:**  [[advanced topics 1.htm|Advanced Topics]] > API Calls and Advanced Resources >====== Accessing Clarion's Runtime Library from C/C++ or Modula-2 Code ====== | [[prototypes and declarations.htm|{{btn_prev_n.gif|Previous page}}]][[advanced topics 1.htm|{{btn_home_n.gif|Return to chapter overview}}]][[standard c functions in clarion s runtime library.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

Following is a list of Clarion runtime library procedures, data structures, and variables that you may use at run time in your C/C++ or Modula-2 code.

__**Structures and Data Type Definitions**__

**COLORREF**

C++:  typedef unsigned long COLORREF;

Modula-2:  TYPE COLORREF = LONGINT;

__**Run-Time Variables**__

The following variables are available for interrogation at run-time:

**Cla$DOSerror**  An unsigned integer containing the last DOS error code.

**Cla$FILEERRCODE **An integer containing the last Clarion error code.

**Cla$FILEERRORMSG **A character array of 80 char's containing the last Clarion error message.

**WSL@AppInstance **An unsigned short containing the instance ID of the application.

__**Clarion Built-in Procedures**__

The following list of procedures are those internal Clarion procedures that are 'safe' to call at run-time. Unless otherwise stated, assume that these procedures have been given external C linkage.

**Cla$ACOS** The Clarion ACOS() procedure. Returns the inverse cosine of the val parameter.

C++: double Cla$ACOS(double val)

Modula-2: Cla$ACOS(val :LONGREAL):LONGREAL;

val: A numeric expression describing an angle in radians.

**Cla$ARC** The Clarion ARC statement. Places an arc of an ellipse on the current window or report, bounded by the rectangle defined by the x, y, wd and ht parameters.

C++:  void Cla$ARC(int x, int y, int wd, int ht, int start, int end)

Modula-2: Cla$ARC(x,y,wd,ht,start,end: INTEGER);

x: An integer specifying the horizontal position of the starting point.

y: An integer specifying the vertical position of the starting point.

wd: An integer specifying then width.

ht: An integer specifying then height.

start: An integer specifying the start of the arc in 10th's of a degree.

end: An integer specifying the end of the arc in 10th's of a degree.

**Cla$ASIN** The Clarion ASIN() procedure. Returns the inverse sine of the val parameter.

C++:  double Cla$ASIN(double val)

Modula-2: Cla$ASIN(val LONGREAL): LONGREAL;

val: A numeric expression describing an angle in radians.

**Cla$ATAN** The Clarion ATAN() procedure. Returns the inverse tangent of the val parameter.

C++:  double Cla$ATAN(double val)

Modula-2: Cla$ATAN(val: LONGREAL):LONGREAL;

val: A numeric expression describing an angle in radians.

**Cla$BOX** The Clarion BOX statement. This procedure draws a box of the color specified by the COLORREF structure, starting at position x, y of the width and height specified on the current window or report.

C++:  void Cla$BOX(int x, int y, int wd, int ht, COLORREF fillcolor)

Modula-2: Cla$BOX(x, y, wd, ht: INTEGER; fillcolor: COLORREF);

x: An integer specifying the horizontal start position.

y: An integer specifying the vertical start position.

wd: An integer specifying the width.

ht: An integer specifying the height.

fillcolor: A COLORREF structure.

**Cla$BSHIFT** The Clarion BSHIFT() procedure. This procedure returns the result of bit shifting val by count binary positions. If count is positive, val is shifted left, if count is negative val is shifted right.

C++:  long Cla$BSHIFT(long val, int count)

Modula-2: Cla$BSHIFT(val: LONGINT; count: INTEGER): LONGINT;

val: A numeric expression.

count: A numeric expression.

**Cla$CHORD** The Clarion CHORD statement. Draws a closed sector ellipse on the current window or report inside the box specified by the x, y, wd and ht parameters and in the color provided in the COLORREF structure. The start and end parameters specify which part of the ellipse to draw.

C++:  void Cla$CHORD(int x, int y, int wd, int ht, int start, int end, COLORREF fillcolor)

Modula-2: Cla$CHORD(x, y, wd, ht, start, end: INTEGER; fillcolor: COLORREF);

x: An integer specifying the horizontal start position.

y: An integer specifying the vertical start position.

wd: An integer specifying the width.

ht: An integer specifying the height.

start: An integer expressing the string of the chord in 10th's of a degree.

end: An integer expressing the end of the chord in 10th's of a degree.

fillcolor: A COLORREF structure.

**Cla$CLOCK** The Clarion CLOCK() procedure. Returns the system time in the form of a Clarion standard time.

C++:  long Cla$CLOCK(void)

Modula-2: Cla$CLOCK(): LONGINT;

**Cla$COS** The Clarion COS() procedure. Returns the cosine of the val parameter.

C++:  double Cla$COS(double val)

Modula-2: Cla$COS(val: LONGREAL): LONGREAL;

val: A numeric expression describing an angle in radians.

**Cla$DATE** The Clarion DATE() procedure. Returns a Clarion standard date value form the component day, month and year parameters.

C++:  long Cla$DATE(unsigned mn, unsigned dy, unsigned yr)

Modula-2: Cla$DATE(mn, dy, yr: CARDINAL): LONGINT;

mn: A numeric expression for the month in the range 1 to 12.

dy: A numeric expression for the day in the range 1 to 31.

yr A numeric expression for the year in the range 1801 to 2099.

**Cla$DAY** The Clarion DAY() procedure. Returns the day in the range 1 to 31 from the Clarion standard date parameter.

C++:  long Cla$DAY(long dt)

Modula-2: Cla$DAY(dt: LONGINT): LONGINT;

dt: A numeric expression for Clarion standard date.

**Cla$ELLIPSE** The Clarion ELLIPSE statement. Draws an ellipse on the current window or report, of the color specified in the COLORREF structure, inside the area bounded by the x, y, wd and ht parameters.

C++:  void Cla$ELLIPSE(int x, int y, int wd, int ht, COLORREF fillcolor)

Modula-2: Cla$ELLIPSE(x, y, wd, ht: INTEGER; fillcolor: COLOREF);

x: An integer expression.

y: An integer expression.

wd: An integer expression.

ht: An integer expression.

fillcolor: A COLORREF structure.

**Cla$INT** The Clarion INT() procedure. Returns the integer portion of the val parameter. The value is truncated at the decimal point and no rounding is performed.

C++:  double Cla$INT(double val)

Modula-2: Cla$INT(val: LONGREAL): LONGREAL;

val: A numeric expression.

**Cla$LOG10** The Clarion LOG10() procedure. Returns the base 10 logarithm of the val parameter.

C++:  double Cla$LOG10(double val)

Modula-2: Cla$LOG10(val: LONGREAL): LONGREAL;

val: A numeric expression.

**Cla$LOGE** The Clarion LOGE() procedure. Returns the natural logarithm of the val parameter.

C++:  double Cla$LOGE(double val)

Modula-2: Cla$LOGE(val: LONGREAL): LONGREAL;

val: A numeric expression.

**Cla$MONTH** The Clarion MONTH() procedure. Returns the month from a Clarion standard date in the range 1 to 12.

C++:  long Cla$MONTH(long dt)

Modula-2: Cla$MONTH(dt: LONGINT): LONGINT;

dt: A numeric expression containing a Clarion standard date.

**Cla$MOUSEX** The Clarion MOUSEX() procedure. Returns the horizontal position of the mouse.

C++:  int Cla$MOUSEX(void)

Modula-2: Cla$MOUSEX(): INTEGER;

**Cla$MOUSEY** The Clarion MOUSEY() procedure. Returns the horizontal position of the mouse.

C++:  int Cla$MOUSEY(void)

Modula-2: Cla$MOUSEY(): INTEGER;

**Cla$NUMERIC** The Clarion NUMERIC() procedure. Returns 1 (true) if str contains a valid representation of a number, otherwise returns 0 (false).

C++:  unsigned Cla$NUMERIC(char *str, unsigned slen)

Modula-2: Cla$NUMERIC(VAR str: ARRAY OF CHAR; slen:CARDINAL): CARDINAL;

str: A pointer to a string.

slen: Length of the str parameter.

**Cla$RANDOM** The Clarion RANDOM() procedure. Returns a pseudo-random number who's value will be between the low and high bound values.

C++:  long Cla$RANDOM(long low, long high)

Modula-2: Cla$RANDOM(low, high: LONGINT): LONGINT;

low: A numeric value specifying the lower bound.

high: A numeric value specifying the upper bound.

**Cla$ROUND** The Clarion ROUND() procedure. Returns the val parameter rounded to power of 10 specified by the ord parameter.

C++:  double Cla$ROUND(double val, double ord)

Modula-2: Cla$ROUND(val, ord: LONGREAL): LONGREAL;

val: A numeric expression.

ord: A numeric expression equal to a power of 10 (e.g. .001, .0, 1, 10, 100 etc...).

**Cla$SETCLOCK**

The Clarion SETCLOCK statement. Sets the system clock to the time contained in the dt parameter.

C++:  void Cla$SETCLOCK(long dt)

Modula-2: Cla$SETCLOCK(dt: LONGINT);

dt: A numeric expression representing a Clarion standard time.

**Cla$SETTODAY**

The Clarion SETTODAY statement. Sets the DOS system date to that contained in the dt parameter.

C++:  void Cla$SETTODAY(long dt)

Modula-2: Cla&SETTODAY(dt: LONGINT);

dt: A numeric expression containing a Clarion standard date.

**Cla$SIN** The Clarion SIN() procedure. Returns the sine of the val parameter.

C++:  double Cla$SIN(double val)

Modula-2: CLA$SIN(val: LONGREAL): LONGREAL;

val: A numeric expression describing an angle in radians.

**Cla$SQRT** The Clarion SQRT() procedure. Returns the square root of the val parameter.

C++:  double Cla$SQRT(double val)

Modula-2: Cla$SQRT(val:LONGREAL): LONGREAL;

val: A numeric expression.

**Cla$TAN** The Clarion TAN() procedure. Returns the tangent of the val parameter.

C++:  double Cla$TAN(double val)

Modula-2: Cla$TAN(val: LONGREAL): LONGREAL;

val: A numeric expression describing an angle in radians.

**Cla$TODAY** The Clarion TODAY() procedure. Returns the system date in Clarion standard date format.

C++:  long Cla$TODAY(void)

Modula-2: Cla$TODAY(): LONGINT;

**Cla$YEAR** The Clarion YEAR() procedure. Extracts the year from a Clarion standard date, in the range 1801 to 2099.

C++:  long Cla$YEAR(long dt)

Modula-2: Cla$YEAR(dt: LONGINT): LONGINT;

dt: A numeric expression describing a Clarion standard date.

__**Clarion String Stack Handling Procedures**__

The following section describes the use Clarion internal run-time string handling procedures available to 3GL code. Clarion uses a LISP like approach to string handling whereby, parameters are pushed onto the top of the string stack, with operations being performed on the topmost entries. Assume, unless otherwise documented, that the procedures remove (or Pop) items off the stack that they have used.

Please note that some of the following procedures require pointers to null terminated strings, to be passed as parameters. Modula-2 programmers should use the Modula library procedure Str.StrToC to convert strings to null terminated equivalents. Also, the pragma call(o_a_size=>off,o_a_copy=>off) must be issued to prevent the passing of array size information to the run-time procedures.

**Cla$PopCString** Takes the topmost item off the stack and copies it to the string pointed to by s; len contains the length of the string copied to s.

C++:   void Cla$PopCString(char *s, unsigned len)

Modula-2:  Cla$PopCString(s: POINTER TO CHAR; len: CARDINAL);

s: A pointer to a null terminated string

len: The length of string s

**Cla$PopPString** Takes the topmost item off the stack and copies it to the string pointed to by s; len contains the length of the string copied to s. The string is converted to a Pascal style string (i.e. first byte is string length) during copy.

C++:   void Cla$PopPString(char *s, unsigned len)

Modula-2:  Cla$PopPString(VAR s: ARRAY OF CHAR; len: CARDINAL);

s: A pointer to a string

len: The length of string s

**Cla$PopString**  Pops the uppermost stack item and copies it to the string s.

C++:   void Cla$PopString(char *s, unsigned len)

Modula-2:  Cla$PopString(VAR s: ARRAY OF CHAR; len: CARDINAL);

s:  A pointer to a null terminated string

len: The length of string s

**Cla$PushCString** Pushes s onto the top of the stack.

C++:   void Cla$PushCString(char *s)

Modula-2:  Cla$PushCString(VAR s: ARRAY OF CHAR);

s: A pointer to a null terminated string

**Cla$PushString** Pushes the string s onto the top of the stack. Len specifies the length of string s.

C++:   void Cla$PushString(char *s, unsigned len)

Modula-2:  Cla$PushString(VAR s: ARRAY OF CHAR; len: CARDINAL);

s: A pointer to a string

len: The length of string s

**Cla$StackALL** The Clarion ALL() procedure. Pops the top item of the stack and replaces it by a string containing the original string replicated as many times as necessary to produce a string of length len.

C++:   void Cla$StackALL(unsigned len)

Modula-2:  Cla$StackALL(len: CARDINAL);

len: An unsigned integer

**Cla$StackCENTER **The Clarion CENTER() procedure. Pops the topmost item of the stack and replaces it with a string padded with leading spaces so as to center the text in a string of length len.

C++:   void Cla$StackCENTER(unsigned len)

Modula-2:  Cla$StackCENTER(len: CARDINAL);

len: An unsigned integer

**Cla$StackCLIP **The Clarion CLIP() procedure. Removes trailing spaces from the top most item on the stack.

C++:   void Cla$StackCLIP(void)

Modula-2:  Cla$StackCLIP();

**Cla$StackCompare **Compares the top item on the stack (s1) with the 2nd item on the stack (s2) and returns one of the following values:

-1:  if s1 <; s2

0: if s1 = s2

1: if s1 > s2

After the compare instruction, s1 and s2 are removed from the stack automatically.

C++:   int Cla$StackCompare(void)

Modula-2:  Cla$StackCompare(): INTEGER;

**Cla$StackCompareN **Compares the topmost item on the stack to null. Returns true if the topmost item is null, otherwise returns false.

C++:   int Cla$StackCompareN(void)

Modula-2:  Cla$StackCompareN(): INTEGER;

**Cla$StackConcat** Pops the top two items off the stack, concatenates them together and pushes the resulting string back onto the stack.

C++:   void Cla$StackConcat(void)

Modula-2:  Cla$StackConcat();

**Cla$StackINSTRING **The Clarion INSTRING() procedure. Searches the topmost item on the stack, for any occurrence of the second item on the stack. The search starts at character position start and increments the start position by step until the end of the string is reach. Returns the iteration count required to find the search string, or 0 if not found.

C++:   unsigned Cla$StackINSTRING(unsigned step, unsigned start)

Modula-2:  Cla$StackINSTRING(step, start: CARDINAL): CARDINAL;

step: An unsigned integer, the search increment

start: An unsigned integer, the start position of the search

**Cla$StackLEFT** The Clarion LEFT() procedure. Replaces the topmost string on the stack with its left justified equivalent. The replacement sting will have a length of len.

C++:   void Cla$StackLEFT(unsigned len)

Modula-2:  Cla$StackLEFT(len: CARDINAL);

len: An unsigned integer

**Cla$StackLen** Returns the length of the topmost item on the stack. Does not pop the item off the stack.

C++:   unsigned Cla$StackLen(void)

Modula-2:  Cla$StackLen(): CARDINAL;

**Cla$StackLen2** Returns the length of the topmost item on the stack. Pops the item of the stack after getting its length.

C++:   unsigned Cla$StackLen2(void)

Modula-2:  Cla$StackLen2(): CARDINAL;

**Cla$StackLOWER **The Clarion LOWER() procedure. Replaces the topmost string on the stack with its lower case equivalent.

C++   void Cla$StackLOWER(void)

Modula-2:  Cla$StackLOWER();

**Cla$STACKpop** Pops the top item off the stack.

C++:   void Cla$STACKpop(void)

Modula-2:  Cla$STACKpop();

**Cla$StackNUMERIC **Returns true if the topmost string on stack contains a valid numeric representation, otherwise returns false.

C++:   unsigned Cla$StackNUMERIC(void)

Modula-2:  Cla$StackNUMERIC(): CARDINAL;

**Cla$StackPRESS** The Clarion PRESS statement. Pushes every character in the topmost string of the stack into the Windows keyboard buffer.

C++:   void Cla$StackPRESS(void)

Modula-2:  Cla$StackPRESS();

**Cla$StackRIGHT** The Clarion RIGHT() procedure. Replaces the topmost item on the stack with its right justified equivalent. The replacement string will have a length of len characters.

C++:   void Cla$StackRIGHT(unsigned len)

Modula-2:  Cla$StackRIGHT(len: CARDINAL);

len: An unsigned integer

**Cla$StackSUB** The Clarion SUB() procedure. Replaces the topmost string on the stack with a sub slice of the string starting at character position pos and of length len.

C++:   void Cla$StackSUB(unsigned pos, unsigned len)

Modula-2:  Cla$StackSUB(pos, len: CARDINAL);

pos: An unsigned integer; the start position of the sub string

len: An unsigned integer; the length of the sub string

**Cla$StackVAL** The Clarion VAL() procedure. Returns the ANSI value of the first character of the topmost string of the stack.

C++:   unsigned char Cla$StackVAL(void)

Modula-2:  Cla$StackVAL(): BYTE;

**Cla$StackUPPER** Replace the topmost string on the stack with its uppercase equivalent.

C++:   void Cla$StackUPPER(void)

Modula-2:  Cla$StackUPPER();