Chapter 5.1

X2c System components

The X2c shell program

The X2c shell is a C program that calls the Xbase compiler, the C compiler and the linker as need for each processing step required.

The Xeq symbol processor

The Xeq symbol processor (x2c.xeq) program extracts the name of each Xbase variable, function and procedure from the compiled .o modules. It creates a set of C tables that the X2c run-time modules use to resolve Xbase macro references and to link Xbase database fields to the respective Xbase variables. It also determines the starting module the will be called first. The resultant table is a temporary C module that is created for each X2c complile and then removed.

The Xbase compiler

The Xbase compiler (DBX3 or x2c.xlt.*) program is the heart of the system. It processes each .PRG Xbase source file into a C source file. It uses the existing Dictionary file (TOP.DIC) and Function file (TOP.FUN) and updates them as it finds new variables and functions.

X2c Standard Header Files:

These files are used by the system to compile the application C source files (The stdio.h, dbx.h and dbmtie.h files are usually kept with the C compiler include files):

Include file list:

The correct include header files for application program creation are placed in $TPGM/include directory. The headers are:

dbx.h dBx and X2c

dbxmemo.h dBx with memo's and X2c

dbmtie.h dBx with databases and X2c

dbfalib.h Included by dbmtie.h

any.hf X2c with prototyping

STDIO.H

This is a standard function library containing many of the commonly used C functions. It is supplied with the C compiler.

DBX.H

This contains general information for X2c routines.

DBXMEMO.H

This contains definitions for X2c memo functions.

DBMTIE.H

This contains information about the tie-in functions used by the data manager, it includes a header for the specific file manager. The standard DBFA file manager uses DBFATIE.H. Other file managers will have their own headers.

ANY.HF

This contains function definitions with parameter prototypes. It has two #ifdef alternatives: with and without parameters.

X2c Standard Function Libraries:

The vast majority of the complex fucntion of any X2c compiled program will came a pre-written function in one of the X2c function libraries.

There are five function libraries:

dbx: Screen, string, System and general functions

dbfa: File and database manager

memo: Memo handler (long strings)

ev: Run-time expression evaluator

any: ANY-time variable logic

Variable Dictionary Format

In order to properly understand your Xbase application, X2c creates a variable dictionary. This file identifies each of the variables found in your Xbase code and explains how each is used. When your Xbase code is actually translated into C source code, X2c uses the variable dictionary as a reference to insure correct contextual translations.

Once created, the variable dictionary is updated by X2c whenever the system is run. In the X2c for Linux, the dictionary is transient and is removed once each modules is compiled.

WARNING: Do not edit the dictionary manually. Since the dictionary format is text, it will load into a text editor, but any hand changes can destroy the proper functioning of the system.

To set the length of a string variable. X2c sets a default length of 255 unless a different length has been specified using the OPTION CHARSIZE dbd statement, or if a VAR statement is provided with <size> information.

Each section in the dictionary starts with a line as:

:WORD(space)[value(s)]

Version header:

:VER product major-rev minor-rev Update-rev

Where:

Product is a string

rest are numeric values 0-255

Global Temps:

:TEMPS strings memos

Options:

:OPTION

With following lines as option values

in the format <keyword>(space)<value>

following lines are options:

Meaning

CHARSIZE int strsize Default char size

TEMPSIZE int tempsize Default temp str size

DEF_TYPE char vdefault Default variable type

Enable

EXPRESS int express ON/OFF Error if bad xlt

TRACE int deb_line ON/OFF Trace output

PRELINE int pre_line ON/OFF #LINE

SNAP int snapspec ON/OFF Snapcodes

SRCECHO int allsrc ON/OFF Xbase Source in .C

Not allowed in dictionary options entry

INCLUDE

CSOURCE

CFUNCTION

Database fields:

:DB <database name>

field-list in the form:

fieldname typestring length precision field-seq-number

Dynamic variables:

:DYN

Variable-list in the form:

varname typestring length precision array-dims(0..n)

Public variables:

:PUB

Variable-list in the form:

varname typestring length precision array-dims(0..n)

Local variables:

:LOCAL function-name

Variable-list in the form:

varname typestring length precision array-dims(0..n) param-flag

Variable entry details.

Each variable dictionary entry follows an established format. Data items are separated by required spaces.

Each entry has two significant components, the Xbase name and owner. There can be only one entry for each unique pair. Duplicate Xbase field names are allowed as long as the owners' databases are different. This situation normally occurs when two different databases have fields of the same name. The owner is determined by the section of the dictionary the entry is within, DB, LOC, PUB.

Database fields are added to the variable dictionary in the same order as they are defined in the Xbase code.

Within each entry, individual fields are separated by required spaces. The fields are listed as they appear from left to right.

Xbase name

Data type (C/N/L/D/M/I/U)

Use (V/A/D/M/S/*)

Definer (G/U/D)

Source (D/X)

Size (255)

Decimal Digits

Array Size 1

Array Size 2

Field Sequence Number

The Xbase name is extracted from the Xbase code.

Owner indentifies the .DBF file, program, procedure, or PUBLIC variable which defined the name. Local variables (PRIVATEs) are prefixed by the right parenthesis symbol ). PARAMETERS are prefixed by double parentheses ().

Data types are the standard Xbase data type, with some additions:

C Character

D Date

I Integer

L Logical

M Memo

N Numeric

U Unknown

V ANY-type variable

Character fields have an extra byte added to their length for the null byte required by C string conventions.

NOTE: Integer variables are for special X2c uses, you cannot use (I) for integer variables.

Data Use indicates how the entry is used.

A Alias

D Database

M Macro

S Structure (named field is in a single database)

V Variable

* Ambiguous (named field occurs in multiple databases)

The Definer shows how the definition was derived.

D Database, as filled in by the Definer.

G Guess by X2c

U User

For a macro variable, the variable itself always has a Data type of Character. The type of variable referenced by the macro is stored in the definer field.

The Source is the program that provided the information:

D Definer

X Xltr

The Size of a variable is set to by X2c. It is 255 or CHARSIZE for character, or to 6 or the precision of a numeric field.

The number of Decimal Digits defaults to the standard Xbase value.

Array Size 1, and

Array Size 2 are the sizes of each array subscript.

Parameter flag is 0 for a variable, or a sequence number for parameters or database fields.

Dictionary Example

:VER DBX3 4 7 2

:TEMPS 0 0

:DB mail_lst

NAMEPTR C*DUD 31 0 0 0

FNAME C*DUD 16 0 1 0

LNAME C*DUD 16 0 2 0

STREET C*DUD 26 0 3 0

CITY C*DUD 16 0 4 0

STATE C*DUD 3 0 5 0

ZIP C*DUD 7 0 6 0

:LOC mail

CHOICE CVGUX 255 0 0 0

HL1 CVGUX 255 0 0 0

HL2 CVGUX 255 0 0 0

SM1 CVGUX 255 0 0 0

SM2 CVGUX 255 0 0 0

SM3 CVGUX 255 0 0 0

SM4 CVGUX 255 0 0 0

SM5 CVGUX 255 0 0 0

Chapter 5.2

X2c UNIX Library

X2c has five libraries of functions that are the primitive commands required by a program written using the X2c Xbase dialect.

We give up - THERE AIN'T NO STANDARD UNIX.

Until release 4 (of dBx, circa 1989), we tried to distribute a generic portable UNIX library and did nothing but get everyone (ourselves included) frustrated. We can't give you (the Xbase programmer) a library that you can self install on any UNIX system, anyone that has watch Larry Wall's Configure script run knows how muc variation UNIX systems have.

We do provide specific installs for popular UNIX and other systems. These include SCO Xenix and Unix on 386 AT's (286 are just too small for even Xenix), Intergraph CLIP SYS V, SUN System 4, IBM RS-6000 (AIX3) and OS/2 -- and now Linux. Special code support is available on a custom basis for such machines as the Macintosh, DEC VAX/VMS and IBM 3090 and AS-400 mainframes using MVS or dialog manager.

Contrary to the impression given by the press, UNIX systems are not as similar as DOS systems. In addition (actually subtraction) there are far fewer UNIX customers to distribute the development effort over, there being about 2 million UNIX systems from over 70 manufactures that are all significantly different. This is in contrast with 60 million DOS machine that are practically identical.

As a result, the UNIX versions are not going to cost a flat rate like the PC version but are priced based on the work involved, the market size and the price of other database systems for these machines. You will still find we are still priced less than other database systems, but for us to provide what you are asking for, we have a lot of support to provide.

Building libraries:

This chapter is only relevant if a user needs to create modified libraries.

This does not need to be done to use X2c, but only when run-time code changes are desired or when requested by Tech Support.

The standard XENIX system is built using gnu C (gcc) with the mk1-g script.

Library summary:

There are five libraries:

dbx: Screen, string, System and general functions

dbfa: File and database manager

memo: Memo handler (long strings)

ev: Run-time expression evaluator

any: ANY-time variable logic

Making X2c libraries from library source

The source is provided on a TAR disk or on MS-DOS diskettes as a compressed tar file (a binary file). The following process describes how to create the libraries.

Setup the development machine.

This section will have already been done on any system where X2c has already been installed. In this case, skip the rest of this section.

The development computer must have the UNIX/XENIX software development system with the C compiler and assorted utilities and libraries. Where available, use the gnu gcc C compiler. The XENIX gcc compiler is provided with the XENIX version of X2c.

Define an environment variable TPGM with the lib directory in which test libraries and objects are to be placed. The library make process only places the final libraries and stand-alone object files in this directory, not all development object files.

The TPGM variable is defined as part of the X2c installation procedure.

Place the directory $TPGM/bin in the environment PATH.

Define the environment variable DBXSYS to define the target environment, with the following values:

Setting Machine

LINUX x86 CPU running Linux

RS6000 RS-6000, AIX3

ITG Intergraph

SUNOS Sun OS (version 4.x)

SYSV Any other System V

XNX Xenix

The Xenix system does not need DBXSYS because the scripts are able to determine the system type automatically. Any other BSD system (such as UTRIX) should start by defining SUNOS.

Installing the library source:

The lsrc archive contains sub-directories for each library and should be created on a disk with at least 6 meg free.

To create source directories on /usr/x2c:

mkdir /usr/x2c

cd /usr/x2c

tar xv x2c.lsrc.tar.Z - Un-tar file from floppy

ztar xv x2c.lsrc - Un-ztar archive from .Z file

rm x2c.lsrc.tar.Z

Full library build for defined system versions:

For already defined system versions, all libraries can be build by doing:

cd $DBXDEV/makelib

mk-all

The created libraries will be placed in the directory $TPGM/glib.

None of the subsequent steps are needed.

Modify the compile script:

This script 'mk1' controls the compile switches used to compile each library module. It is found in the $TPGM/bin directory.

For Sco XENIX/UNIX using the gnu gcc C compiler, the mk1-g script is already provided and should be used as is for all compiles. Skip the rest of this section if you are using SCO Xenix and gnu gcc.

For all other Unix systems, the 'mk1' script is provided.

It has the following switches set for XENIX 386, (do not change these unless you know what your doing). There are a number of optional switch settings in the mk1 script as comments. Uncomment the one that applies to your system.

The generic compile script is called 'mk1'.

The standard compile script for SCO XENIX/UNIX is 'mk1-g' which uses the gcc compiler.

-LARGE Selects LARGE stack version of C compiler.

Do not change if using XENIX, for modules that would compile due to complier failure, use script mk1s.

-DM_TERMINFO Select terminfo for screen I/O

-pack Select packed data structures.

This is required for dBFA to work correctly.

Other possible switches required for other compilers are:

-DSUNOS For SUN systems

-DVAX For Vax systems

-DX_PORT For non-86 type of CPU's

-DPORT_68 For 68000 type CPU's

-DPORT_386 For SUN 386i systems

-DC370 For IBM mainframe systems

-DEBCDIC For systems using EBCDIC character set

Create and test the dbx screen and general functions library.

This is in the directory lsrc/dbxlib.

Create the library:

This is done using the make utility and the script 'mkdbx'. This script will compile and archive all modules needed.

Test the library:

There are a number of t*.c test modules: tsys.c, tstr.c, tscn.c, tscn2.c. Each one can be created in to running program using the script:

mktest t...

Do this for each one and make sure they run.

Release the library:

The mkdbx script will automatically, move it to the directory $TPGM/lib. All X2c processes expect to find the script there.

Create and test dbfa.a library

This is in the directory lsrc/dbfa.

Create the library:

This is done using the make utility and the script 'mkdbfa'. This script will compile and archive all modules needed.

Test the library:

There is one overall test: dbmtest.c. It can be created by using the script:

mktest dbmtest

Do this and make sure it runs.

Release the library:

The mkdbx script will automatically, move it to the directory $TPGM/lib. All X2c processes expect to find the script there.

Create and test ev, memo and any libraries

This are in the directories:

ev lsrc/ev

memo lsrc/memo

any lsrc/any

Follow the same procedures for the ev (expression evaluator) library, the memo library and the any library. This are in their own directories and are created with the mkev, mkmemo and mkany scripts.

Considerations when porting to new machine environments:

Moving sources to the target machine.

The sources are all standard ASCII files. They are broken up into six sections: the five libraries and tpgm/bin.

Where possible, move the x2c.lsrc.tar.Z file to the target machine and install normally.

If tar on the target machine does not read properly, then you must move the files in each directory of lsrc to the target machine

If you have moved the files as text files, you will have to make the shell script files executable, use the command:

chmod +x mk*

to do this.

The work files in the TPGM/bin directory should be placed in your TPGM/bin directory and each of the other libraries in their own directory.

DBXLIB library:

The sy*.c and hw*.c modules contain all system specific routines. When modifying for different UNIX/XENIX versions, the key changes will be in the modules hwunix.c and hwxenix.c. Before re-writing, look for hw*.c functions that are appropriate for the target machine.

The key routine needing changing is the routine HWkypoll(). It gets a single character while timing out after 1 sec.

Re-run mkdbx after any changes.

DBFA library:

The dbf*.c modules contain all system specific routines. When modifying for different UNIX/XENIX versions or different processor hardware, the key changes will be in the modules: dbfport.c, dbflock.c and dbfopen.c.

In particular, dbfport.c and the #ifdef ALIGN code in dbfopen.c are critical for processor changes. Contact Desktop Ai support for the align.c test program if you are having problems configuring ALIGN.

dbflock.c is critical for multi-user locking code.

Re-run mkdbfa after any changes.

EV, MEMO and ANY libraries:

These libraries do not have any environmentally dependent functions.

Variable number of parameters:

There are two sets of routines that can take a variable number of parameters. These are those in DBFA that process index file names: DBuse() and DBindex(); and those in DBXLIB that set colors: SCcolor(). Both are setup to expect a push-down stack where each parameter is a (char *). For hardware where this does not works and have UNIX's that support varargs, these have been re-coded to use varargs. (Contact Desktop Ai technical support for how to activate this function.)

General Notes:

The libraries are designed to be as independent as possible. The independence is only of significance when trying to minimize the size of a program. This is not usually needed for full sized applications under Unix nor does it apply to X2c applications where the majority of functions are needed.