DO procname [ WITH parm-list]

X2c processes this statement into:

procname(dbx_pn, Pparm1, Pparm2, ....)

int dbx_pn; dbx_Hany *Pparm1, *Pparm2 ... ;

Where the procname is all lower case.

This is based on the normal var function statement created by ffunc of [P-#VVV].

Creating the proper C code to link to this is extremely hard and not recommended. The best way to create such a linkage is use X2c to compile a PRG function and edit the resulting C code.

CALL Cname [ WITH parm-list]

X2c processes this statement into:

procname(parm1, parm2, ....)

type-of parm1, parm2 ... ;

Where the procname is the same case as the Xbase statement, with an exact upper-lower case match.

This is based on the var function statement created by the user of [P-xxx], where x is the type of each variable using standard Xbase letters as described below.

Creating the proper C code to link to this is a matter of using the proper C declarations as noted above and is recommended where no return value is required from the function.

returnvalue = Cname([parm-list])

X2c processes this statement into:

For numerics and logicals:

returnvalue = procname(parm1, parm2, ....)

type-of parm1, parm2 ... ;

For Character strings and dates:

char *

procname(returnvalue, parm1, parm2, ....)

char *returnvalue; type-of parm1, parm2 ... ;

Where the procname is the same as the Xbase statement in both forms, except in lower case.

This is based on the VAR FUNCTION statement created by the user of [Frxxx], where 'r' is the type the function returns, and 'x' is the type of each variable using standard Xbase letters as described below. If the VAR FUNCTION statement has an Cname clause, that name is used. If not, the name used is the same as the Xbase name, except all in lower case.

Functions use the VAR FUNCTION parameter description of: [Frxxx]

Procedures use the VAR FUNCTION parameter description of: [P-xxx], which has no defined return value.

where x is the type of each variable using standard Xbase letters of:

C - Character (Ctype: char *)

N - Numeric (Ctype: double)

D - Date (Ctype: char *)

L - Logical (Ctype: BOOL)

M - Memo (Complex C type: not recommended)

The type BOOL is defined as 'unsigned char' in the dbx.h header.

Dates are character strings of the form CCYYMMDD,

where:

CC is Centry, YY is Year,

MM is Month, DD is Day.

The VAR FUNCTION statement has 4 parameters of which only two are normally used. The remaining two can be used to control the generated C code in minute detail. This is explained more completely in section 6.3 "User defined functions"

VAR FUNCTION Xbase-name [Cname] param-spec [generator]

Normally, the Cname is the defaulted to be the same as the Xbase-name except totally in lower case and a default generator is provided that maps each Xbase parameter to a matching C parameter in order.

The Cname can be specified exactly using the second parameter and the fourth parameter is used to specify alternate code sequences from the standard one, as detailed in section 6.3

The X2c for Lilnux program will recognize the file suffixes of .c (C sources), .o (object modules) and .a (link libraries) and compile or just link as approproprate. The standard X2c headers are automatically available when compiled this way.

gdb supports an emacs-like command recall. More details about these command are found in the gdb manual and readline documentation. (These are provided on the X2c release disks as print files.)

To recall a previous line:

ctl-p recalls a previous like

ctl-r<typing>

does a reverse search for the characters typed.

To edit the current line:

ctl-a goes to beginning of the line

ctl-b goes back one character

ctl-e goes to end of line

ctl-f goes forward one character

gdb provides a means to call a program function and return the result. This is used to provide a simple way of displaying the contents of an ANY-type variable.

To print the variable UVAR, use the gdb commands:

p Adsp(&Vuvar)

ps

This displays the contents of ANYshow, which Adsp() fills with a description of the file.

To display a variable when gdb steps, use the gdb command:

disp "%d,%s", Adsp(&Vuvar), ANYshow

The X-base variable 'xvar' is stored in the C variable 'Vxvar'. The C variable 'Vxvar' is of C type: dbx_Hany, which is a pointer to a complex set of structures managed by the ANY logic for your program.

The general outline of the structure is:

(1) Vxvar -> ANY variable header

(2) ANY variable header->Current value structure

(3a) For Character values:

Current value structure->current value

(3b) For Other data type: (numeric, logical, date)

Current value structure contains current value

Variables only have a meaningful value once a program is running.

This example will use the X-base variable 'XVAR'.

The following features can be enabled via .gdbinit

For a UDF to be included in the X2c process, the X2c analyzer must recognize it is needed. This can occur in a number of ways.

UDF's can be part of any .PRG just like in Clipper. If the enclosing procedure is called via DO then the UDF will be processed as part of it. The FUNCTION may be in a procedure file declared in the Xbase source by using the Xbase SET PROCEDURE TO or clipper EXTERN statement. These statements must occur in the TOP PRG or any PRG file otherwise referenced.

As in C, all actual parameters in X2c must be of a fixed data type. All references to a UDF must have the same number of parameters. X2c uses these constraints and the VAR FUNCTION statement to allow handling of parameters in ways appropriate to an Xbase function.

X2c allows handling variable parameters types by passing an ANY variable, which itself can take on different data types, thus not violating the C run of fixed data types. This allows the Xbase test of an undefined parameter by using:

TYPE("variable")='U'

X2c allows optional parameters by filling the missing parameters with a dummy and passing a parameter count which can be tested in the PCOUNT() function. This is useful for functions that do not use the stdargs form of parameters.

Because C has no real character strings, X2c uses the C substitute - static character arrays. C does not have standard routines to efficiently create and destroy strings dynamically. This is also a very slow process and not required for most Xbase programs.

X2c passes a string area to the UDF for which the UDF to place the result string. A phantom parameter is added that does not show in the Xbase expression.

X2c uses a similar approach to return ANY-type values from functions.

Character char *

Date char *

Numeric double

Logical int

The Xbase function name. The letter case is ignored.

The function name placed in the C code. If absent, the C-name will be the same as the X-base name except all in lower case.

This is a keyword which is the exact name placed in the C code. The letter case is significant, since C distinguishes between letter case in function names.

This is a character string specifying the type of value returned by the function and the types of each parameter. The parameter type can be either a simple (upper case) type letter or can have a (lower case) modifier letter to indicate optional or array parameters. The modifiers provide fine control over parameters passed to functions written in C or assembler.

This is a character string giving a special pattern used to tell X2c how to create the C call. The Code Generator has a type letter and sequence number for each parameter. Type letters can be either normal (upper case) type letters or (lower case) special operations. The special operations provide fine control over parameters passed to functions written in C or assembler.

(only one of this name)

A - Ambiguous function

(more the one of this name)

U - Unsupported function

(known but not available)

P - Procedure

- - No value Procedure with no return value

C - Character char *

D - Date char [9]

L - Logical BOOL

M - Memo dbx_memo

N - Numeric REAL (which is double)

A - Array of any type dbx_ary

V - ANY-type dbx_Hany *

Optional: To indicate an optional Xbase parameter, the parameter type code can be preceded by a lower case oh ('o'). This can be used only to call functions written in C or other languages.

Array: To indicate an array of a specific type precede the parameter type code by an lower case aye ('a').

PCOUNT(): To enable PCOUNT() for a function or procedure, the third position must be '#'. This is the position after the return type and before the parameter types. This causes a parameter count value to be placed in the code when the function is processed, for PCOUNT() to be allowed as a function, and for missing parameters to be filled in with NULL (CDV) or 0 (IL).

Code Outputs

@ Cname

(), Same character "(),"

More complex literals can be output by enclosing them with vertical bars as quotes (|text|).

Upper case characters are used for selecting data items of the indicated type character. The second character is the number of the parameter to output in the type selected. The first parameter of the function is numbered zero (0).

Code Outputs As C type

C# Character Parameter char *

D# Date Parameter char *

L# Logical Parameter BOOL

N# Numeric Parameter double

I# Integer Parameter int

M# Memo Parameters dbx_memo

A# Array Parameter dbx_ary

V# ANY-type Parameter dbx_Hany

Note that Xbase UDF's only pass numeric values as type 'double' expressions, so using 'I#' will not work. This is because it will produce a call to the function passing an 'int' value with the function expecting a 'double' value.

The character return value, optional parameters and other differences between C and Xbase environments require flexibility in calling C functions. This is handled by special codes, with the effects listed:

Code meaning

a# Special for CHR() function

b# Optional int parameter, use 0 if missing

c* Adds the value -1 where placed

e* Adds the value +1 where placed

f# Optional int parameter, use 255 if missing

g# Optional int parameter, use 10 if missing

h# Optional int parameter, use -1 if missing

i# Array parameter, required

j# Array parameter, Output NULL if missing or

not an array value given

k# Optional Character value, use NULL if missing

r* Placed before @,

indicates C function returns int value.

v* Places result character string

The Optional parameter codes output a replacement value, if the parameter selected is missing.

Normally, C functions are assumed to return integers unless otherwise explicitly stated. X2c creates C extern function for all functions as required; two forms are created: with and without parameter prototypes.

r* defines a function that returns an integer or logical value, rather than a REAL numeric which is normally expected.

s* will suppress output of the function declaration in the hf file. It is used for functions that are executed inline or are declared in standard system headers.

v* place result string name here

In the last two special codes, the asterisk (*) serves as a place holder.

Beginning the C generator column with r* forces the casting of a int returned value to REAL.

Calling the standard function REPLICATE(expC, expN) generates a call to the C function

char *strrep(char * output string,

char * input string, int count)

by the generator "@(v*,C1,I2)". The "v*" is a place holder for the string return value and is explained below.

One of the biggest differences between Xbase and C is the data typing of C. As a result, there are a number of type control codes in the generator. To test a generator, it pays to create a sample program to call your function, run X2c to create the C code and exercise it extensively. If you test functions separately as opposed to trying to test them within a larger program, much effort can be saved.

This applies to any function that returns a character or date value.

C does not have standard routines to efficiently create and destroy strings dynamically. This is also a very slow process and not required for most Xbase programs. Because of this, X2c uses the C substitute - static character arrays.

To properly handle the returning of string values in a UDF, X2c passes a string area to the UDF in which the UDF can place the result string. This requires a special 'return value' place holder parameter that does not appear in the Xbase source. The special generator 'v*' is used for this.

Array parameters can be specified in two ways, in the parameter description entry:

1) As an explicit type array or

2) As an array of any type.

The explicit type array is specified by placing a small 'a' in front of the type letter, while any type array can be indicated by using upper case 'A'. This example function has a first parameter of a character array and the second as any type array. Its parameter description is 'aCA'. The generator entries would be either 'i' or 'j' depending on if the arrays are required (i) or optional (j).

X2c has type determining function call processor. This allows calling different C functions for the same Xbase name, depending on the parameters. This is called function overloading in an object language like C++ or Objective-C.

A example of a loaded function is the Clipper EMPTY() which takes any type data but does very different tests to determine if the value is empty.

A function is defined as AMBIGUOUS in X2c by having a number of VAR FUNCTION entries, each with a different parameter description. The first letter of the parameter description must be 'A' rather than the usual 'F'. X2c will pick the right declaration based on the supplied parameters. Make sure to have a unique parameter set to choose between each alternative, and do not have optional parameters that will confuse the selection.