Chapter 2
Using X2c
The matter of names
This manual describes the product: X2c (pronounced Ecstasy if you wish). X2c has been developed over eight years and had a prior version called dBx. What will be covered in this manual and documentation files is 'X2c for Linux' - which is a much more refined product than either earlier product.
Older X2c or dBx users wil notice major gaps in this documentation - these are compilcations that have been removed from this product,
An orientation to X2c
X2c is an Xbase language compiler: it takes an Xbase program as a source text file (named .prg) and, through a series of steps, produces a final running program. Because X2c is a composite product, and because a C program is produced in the process, many people use such terms as translator and utility to describe it. These terms obscure the capability and power of X2c. It is legitimate to call X2c 'a compiler' because of the techniques it uses and the fact that it normally requires no interaction with the intermediate C code.
The internal complexity and open access of X2c leaves room for a trap for new users: getting under the hood too soon. The best way to use X2c to its capabilities is to first let X2c work as intended. Once experienced, it allows for full access to the internal steps, even though most experienced users still dip under the hood only as needed.
The Xbase language:
The Xbase language that X2c accepts includes all statements of dBASE III+, Foxbase+ 2.1 and Clipper (summer '87). (In addition, each version of X2c has new features, so check the release notes to see what new statements and functions have been added - for example, Foxpro statements are in the works.)
Yet X2c is a dialects of it's own, so the exact handling of each Xbase statement can vary. This is largely due to the lack of any clear standard for the Xbase language. The majority of statements operate the same as the other dialects.
A very short summary of X2c programming
X2c compiles your Xbase program into C source code. Once you have the source code, X2c calls the C compiler to compile the source code into object code. Then X2c calls the linker to link the object code and associated libraries into executable code, more commonly called working programs!
If some of the terms in the last paragraph seem a little vague, here are some examples that may clarify what they mean and how they are used.
The Xbase code you write in the .prg file is also called source code. With an Xbase interpreter (such as dBASE III or Foxbase), when you finish writing the code, your program can run immediately, although possibly not correctly.
When you use X2c, your Xbase code is converted into C source code in a .c source file. C is different from Xbase, and like Clipper, in that you do not run your program directly from source code. Instead, you convert your source code into a machine language executable file using the X2c process.
The process has a number of intermediate steps, which X2c runs:
Step Filename
Xbase source .prg
C source .c
Object code .o
Executable program mod x
If you have a jumbo program which you have divided into manageable modules -- perhaps a mailing list program with separate modules for adding, changing, and deleting names -- X2c will compile each module separately. This gives you a number of modules of object code in .obj files. To get these object modules to work together as a program in a bin file, X2c will use the linker. The linker combines your code, in object format, with a set of libraries.
A C library is a collection of frequently used subroutines or functions contained in a .lib or .a file. For example, a library can contain functions which print an expression to paper or display it on the screen. Other functions can evaluate a value and tell you whether it is a letter, or perhaps an even number. Some libraries are included with your C compiler; additional libraries are included with the X2c software. Instead of duplicating the code for a common task, you refer to the library function by name. X2c automatically calls upon common library functions whenever possible. The reference section and the C compiler manuals can provide more information on the library functions that are available. When using X2c, the important aspect is that most major Xbase statements become calls to a function from the function libraries.
AN OVERVIEW OF THE X2c PROCESS
The X2c process uses a shell to simplify the process. The shell (the program X2c itself) is transparent to the user. You run X2c just like you run the cc compiler, it will determine what to do based on the file suffixes and what switches are give to specify outputs.
X2c produces standard error reports when any step has errors and will not proceed to the next step.
THE X2c TUTORIALS
The on-disk tutorial programs begin with some simple Xbase code and grow more complex with each tutorial example. The intent of each tutorial is described in the following paragraphs.
Ø Ø Ø PLEASE READ THIS
All X2c users can benefit from the tutorials! Use them to verify the correct installation of your system. New users will learn the basics for using X2c by running the tutorials. Experienced users will want to review the more advanced tutorial examples when they encounter complex coding examples.
Our Tech Support staff reports that most users who call with basic questions have not run the tutorials. Tech Support strongly recommends running at least the HELLO, MENU, and MAIL tutorials. These three examples focus on issues which have proven to be challenging (read confusing) to X2c users. It generally takes less than an hour to run these three tutorials.
HELLO - This is the first sample and process test. It shows the whole process, from start to finish, and assures you that you can produce a running C program.
MATH - This program includes a table with formula logic and printed output. This is a simple Xbase loop. It shows how logic gets converted and how Xbase code can be tailored to get best results. The MATH1 program shows how to improve the format of the C display. MATH2 shows how to call a C printf() function to do direct formatting. MATH2 is written in X2c/Express and will only run with X2c
MENU - This sample menu program introduces the screen handler and a procedure file. It is just a menu shell which calls dummy procedures in the procedure file.
CHECK - This is a simple application with separate modules, a non-indexed database and data entry screen.
MAIL - This is a more complex application including an indexed database, REINDEX, printed output, record entry, edit and delete. This application builds on the CHECK program then adds a database index.
COMPILING THE TUTORIALS
The tutorial examples fall into two categories corresponding to the two type: those without databases and those with databases.
Once X2c and your C compiler is installed, the tutorials are located in the subdirectory:
/usr/x2c/src/tutor (UNIX directory)
NOTE: All examples are written in UPPER or lower case letters as appropriate to the system on which they run. On UNIX systems, this is all lower case, since UNIX is case sensitive.
COMPILING WITH X2C:
This sequence is used to compile all Xbase applications. The basic command is:
x2c <program-name>.prg
This compiles the prg program from source through to an executable a.out file.
To set the name of the output file, use the -o <output-filename> option.
The HELLO program is used as an example in the following sequence. Substitute the correct program name when you use this sequence to process other programs.
cd /usr/x2c/src/tutor
x2c hello.prg -o hello
will compile the Xbase source hello.prg into an executable program hello. This will include all steps of Xbase to C, C compile and object file linking. The first procedure in the first file listed will be called as the MAIN procedure.
Run hello and READ CAREFULLY !!
Read the message that the HELLO program displays. It say:
"I was a dBASE program and now I'm in C."
If a different message is displayed when you run HELLO, then you are not executing the X2c HELLO program. (This does happen)
hello is the executable C program that is created by x2c. It is located in the TUTOR subdirectory. If it is not, your system is not installed correctly. Correct any installation problems and rerun this tutorial.
This same sequence is used to process most applications. The example CHECK and MAIL programs have databases and the other features of a full application.
The MAILX program has a number of modules, it is compiled with the command line:
x2c mailx.prg mlx_*.prg -o mailx
The mailx.prg is listed first to force the selection of it as the starting module, but all .prg modules listed will be compiled.
MESSAGES
The prior sections show the progressing of an application. Now you have a clear understanding of the development steps. This section covers how to interpret errors -- and what to do about them.
X2c Compiler Messages
The critical path errors are marked ¤ below. Any of these ("Unable to convert expression," "Type conflicts," and "Variables of Unknown type,") will stop X2c from compiling the C code. Other errors and warnings indicate a potential for incorrect execution.
Errors marked þ will rarely occur with X2c, they are remainder from the earlier dBX product that required strict data typing.
All errors, from either X2c, C or the linker will be written to standard error. These can be re-directed to a file with the shell redirect '2>filename'
Errors:
Syntax errors. ¤
This error indicates that X2c encountered a source code statement that it simply cannot understand.
Interactive features used.
Unsupported statements such as APPEND, HISTORY, and VIEW are flagged by this message.
Unable to convert expression. ¤
This message points to a problem with a variable definition in the Variable Dictionary. Add a VAR statement or make corrections to the TOP.dbd file as needed to correctly define this variable.
Type conflicts. ¤ þ
This error can be caused by several different situations. It occurs when a PRIVATE or parameter variable is used as different data types in the same procedure or a PUBLIC is used similarly anywhere. For example, a variable might be used as both numeric and character. Usually, you need to edit the PRG file to correct this error.
A type conflict also occurs when X2c guesses incorrectly or has no guess and uses a default value, and either of these values cause a conflict in a later expression. This can be corrected by providing a VAR statement in the DBD file.
Variables of Unknown type.þ
This error indicates that a variable is not properly defined in the Variable Dictionary. The variables will be listed in the file TOP.unk. Make sure that the TOP.dbd file entry for each variable has the data type stated correctly. If there are real variable errors, other type errors will occur.
Unused PUBLIC variables can cause this error. Remove them.
Unsupported Xbase feature used.
X2c recognized a Xbase construct that is not supported. Usually, you need to edit your original Xbase code to remove the statement and correct this error. X2c may continue, and just ignore the statement
Not end of statement - syntax error.
This usually indicates a statement option that was not recognized, even though the rest of the statement up to that point was fine. This can occur because of statements that take advantage of laxness in another dialect of Xbase, such as in a comment after an ENDDO statement without a &&. These are not legal, but are accepted in some dialects. X2c may not act the same for not-standard, non-documented statement forms.
This can be a warning, when a comment is added after an ENDxx statement without the && comment delimiter.
Not needed statements.
This refers to a statement which is not needed in X2c compiled code and which X2c therefore ignored and did not translate. This is a warning and can be ignored. For example, SET statements such as SET HISTORY OFF fall into this category. X2c flag SETs for unsupported features, where the SET is OFF.
Possible unavailable file functions.
This usually identifies a complex database operation which may not be supported.
C Compiler & Linker Messages
Once all PRG source modules are compiled to C, then X2c runs the C compiler to compile the C code to object files and link the object into an executable program. There are three outcomes for the compile step.
1. Compile OK.
2. Warnings
3. Errors
If all the C modules compile successfully, even with warnings, X2c goes to the link step.
Unresolved Externals:
A frequent error at the link stage of the process is an Unresolved External. This usually means Xbase procedure files are missing. Also watch closely for problems with case sensitivity in C UDF's.
Duplicate external:
Another typical error is 'duplicate external symbol' from the linker. A reason for this could be your TOP Xbase program has a TOP.PRG called main. This is not allowed since it conflicts with the standard C main() created by X2c. Any Xbase name which is the same as a standard C name will cause this error, regardless of whether it is a procedure, or function. Xbase variables will not cause conflicts since they are given C names prefixed by 'V'.
Unlike Clipper, a X2c program with duplicate externals or undefined functions will probably not run. The linker usually refuses to mark these are executable.