Accessing Clarion's Runtime Library from C/C++ or Modula-2 Code

Top  Previous  Next

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();