Thoughts/Notes on CONTROL Software Methodology

This section contains notes to help document the methodology of the CONTROL software application suite.

The code is a mix of C and C++ with the C++ being mainly used to interface to the [http://trolltech.com/ Qt] cross platform toolkit that is used to provide cross platform GUI support.

The software operates on either [http://www.sco.com/products/openserver507/ "SCO OpenServer"], [http://fedoraproject.org/ "Fedora Core 3"] and Microsoft Windows. On Unix O/S the UI can be either text or GUI based.

Building

When building release 8 you need to build it on robin to ensure it is built with the correct libraries and the original gcc compiler.

The main issue with later releases is that the Qt framework not get built with a version of GCC that is too advanced as it uses some older functionaity of the compiler.

Database

The database is based on fixed size records that have two components that are contain either generally static data or variable data. With each data file may (optionally) exist associated index files (Log files are generally not indexed).

Data records are defined as two data structures that are saved in record buffers. The records are prefixed with either 's' or 'v' for static and variable. To maintain records sizes when changes are made, discarded data areas may be defined as the FILL data type which actually maps to char. However the application can be used with an SQL database engine and the FILL fields are discarded in transit.

Apparently the database can be either [http://www.mysql.com MySQL] or [http://www.postgresql.org PostGresql]. The databases can be used for normal operations, but generally the application will use its own database for normal operations and used the SQL database for mirroring which allows the user to use other reporting tools for the SQL data.

The argument for this modus operandi is 'SPEED'.

All application control and configuration data is stored in databases under the 'adm' directory. comp and contrl

Also here are menu and printer databases. These two may be stored in user private directory for development

So for a system with multiple companies any common data can be stored under the 'adm' directory.

All installations have multiple companies as a test company is included to help maintenance support.

Code

There are a few basic data structures used to manage I/O.

s_outflddes

s_outflddes is used to control CSV output.

e.g.

GLOBAL  struct  s_outflddes rfc_line[] =
 {
 {0,OUTPUT,LINE,  1, "15",      OFFSET(s_sstock, code), SSTOCK, STRING},
 {0,OUTPUT,LINE, 17, "40f",     OFFSET(s_tran2, narr),PRODDESC,STRING},
 {0,OUTPUT,LINE, 58, "15",      &supcode,       NORECBUF,       STRING},
 {0,OUTPUT,LINE, 73, "7.3mrz ", &supp_qty, NORECBUF,       SHORTD},
 {0,OUTPUT,LINE, 81, "9.3rz ",  &suppcost,      NORECBUF,       SHORTD},
 {0,COMPUTE,ADD,  0, "",        OFFSET(s_tran, tax),TOTAL,SHORTD, SHORTD, OFFSET(s_tran, tax),    TRANL},
 {0,COMPUTE,ADD,  0, "",        OFFSET(s_tran, amount),TOTAL,SHORTD, SHORTD, OFFSET(s_tran, tax),    TRANL},
 {0,OUTPUT,ADD,  92, "9.3rz ",  OFFSET(s_tran, amount),TRANL,SHORTD,SHORTD, OFFSET(s_tran, amount),     TOTAL},

 //print the additional info if exists
 {0,COMPUTE,TEST,0,"",           OFFSET(s_tran2, narr), COMMENT, STRING},
 {IF_NULL,OUTPUT,LINE+1,17, "25f ",      OFFSET(s_sstock, coment),       SSTOCK,STRING},
 {IF_NOT_NULL,OUTPUT,LINE+1,17,"60f",    OFFSET(s_tran2, narr),COMMENT,STRING},
 {0,NULL},
01140 } ;

Here we write the stock code string from the SSTOCK recbuf data then the narr string from the PRODDESC record. The NORECBUF value signals that we are not referencing data from the recbuf global but a string variable named supcode. The COMPUTE,ADD records add the s_tran.tax field to the s_tran.amount and save the result in the s_tran.amount field to be displayed on the same line as the suppcost variable in column 92.

The "COMPUTE, TEST" record tests a named variable and then the following lines are conditional on that result as to what data is displayed.

s_field

s_field used on data checking on imported data.

s_flddes

s_flddes used to control user data entry by presenting a mix of prompts and query definitions.

e.g.

GLOBAL  struct  s_flddes FAR    serial_no[] =
02373 {
02374 {0,DISPLAY,Y+2,3,"40t "},
02375 {0,DISPLAY,Y+2,3,"'Number: '"},
02376 {0,INPUT|MUST_IN,Y+2,11,"20t ",OFFSET(s_line_extn,dimlist.narr),LINE_EXTN,STRING},
02377 {0,NULL},
02378 };

The first line blanks out an area for the prompt label "Number: " to appear on the current line before we wait for the user to enter a string of up to 20 characters. The OFFSET macro describes the offset into the record buffer we write the result and the record buffer is in a global array named recbuf indexed by LINE_EXTN. The variable length structure is obviously delimited by the NULL trailing record.

There is a lot of work done using globals with the same name across applications. The application is the method of limiting the namespace extent of the globals.

Templates

There are several base code bodies to provide a basic functionality. They contain the main entry point into the application and then call specific functions which are implemented by the task specific version of the application. However when the application is being built for a Qt gui platform then a different entry point is used. The overloaded functions generally contain spcl in their name.

• [:CONTROL/CodeNotes/aad:aad.c] - add/alter/delete/list master file records
• [:CONTROL/CodeNotes/adl:adl.c] - alter, delete, list direct access records
• [:CONTROL/CodeNotes/cont:cont.c] - alter control records
• [:CONTROL/CodeNotes/cyc:cyc.c]
• [:CONTROL/CodeNotes/eat:eat.c] - transaction input/edit
• [:CONTROL/CodeNotes/enq:enq.c]
• [:CONTROL/CodeNotes/ent:ent.c] - transaction input
• [:CONTROL/CodeNotes/log:log.c] - process log.dat : file maintenance log
• [:CONTROL/CodeNotes/lstr:lstr.c] - list transactions by type
• [:CONTROL/CodeNotes/min:min.c] - minimal main
• [:CONTROL/CodeNotes/post:post.c]- post transactions
• [:CONTROL/CodeNotes/rein:rein.c] - recreate index file based on data records
• [:CONTROL/CodeNotes/rep:rep.c] - reporting
• [:CONTROL/CodeNotes/sale:sale.c] - generate sale transactions
• [:CONTROL/CodeNotes/upda:upda.c] - core of all data update programs

Source Control

We are using SCCS here for the source control.

Quick refresher notes:

Initial addition of code: admin -isourcefilename -y"comment" -r10 destination_in_sccs/s.filename

Check out: get -e .sccs/s.filename

Check in: delta -y"comment" .sccs/s.filename

To find out what release of software a particular package is run ccwatch executablefile

Script Notes

[:CONTROL/Software/Scripts: Notes] used to setup development environment.

Documentation

I (Paul) am using [http://www.stack.nl/~dimitri/doxygen/ doxygen] to cross reference and document the code. So whenever you work on a module, document what you find or do.

see file:///u/ccdev/doxygen/html/main.html;

Although the applications can support a GUI type feel this is achieved in a text terminal progressive manner, as in the fields will appear as needed rather than being predefined on the screen. You can enter a question mark in some fields to be shown a list of data choices. For optional data fields the choices will be shown alongside with the default option being capitalised.

Modules

There are three main releases of the system. Releases 8, 9 and 10. 10 obviously is the current release. However there are a few customers using the earlier releases and not upgrading to later releases as they don't want/need the new functionality or the hardware/OS upgrade hassles.

We use SCCS as the version control software. There are also separate file trees for the various releases. With various customers there are customer specific applications or report formats that are supported by unique included files which are used to build their systems.

The application suite are built nightly using a Korn shell script called build.ksh There is one of these scripts for each application in the suite. The suite is built for each supported platform.

The results are in binx11 (Qt based Linux), binl (Text based Linux), binscox (SCO Unix) and binw (Windows).

There are several overloaded functions used to allow application specific operations These include:

• [:CONTROL/base/spclinit: spclinit] - perform application initialisation
• [:CONTROL/base/spclparam: speclparam] - get application options/parameters
• [:CONTROL/base/spclbegin: spclbegin]
• [:CONTROL/base/spclend: spclend] - application finalisation

Directory Layout of /u/ccdev/std

Directory Layout

• binl - Linux text mode binaries
• binw - Win32 binaries
• binx11 - X11 binaries
• ccaadlib - native QT GUI file maintenance programs
• ccalib - sales, analysis and some eftpos routines
• ccddlib - wrapper for accessing SQL databases from CC database methodology
• cclib - core application library
• ccqtgui - QT bindings for applications
• clearall - utilities for cleaning databases
• cm - (control manager) ccmenubar, ccexplore, control
• co - company/branch related programs (select, selbr)
• cr - creditor programs
• dr - debtor programs
• err - output from nightly builds (LINUX, WIN32, X11)
• gl - general ledger
• gui - QT native file maintenance
• hdrs - include files (definitions only)
• import - template import programs (becoming obsolete)
• inc - included files containing common code that isn't in a shared library. Mainly because we have offsets into arrays of database records throughout the code and the defines may be different with different uses.
• internet - web shop stuff
• ma - manufacturing related support (BOM)
• main - templated functionality for CONTROL programs for derivation of new applications
• pde - data entry for stocktaking
• po - purchase orders
• polling - connecting for syncing databases between sites
• rdbms - SQL export support
• rein - reindex database support (generally obsolete aside from trrein (reindex transactions, see file maintains programs)
• sa - sales analysis/summaries
• ss - stock sales
• st - stock and category reporting and maintenance
• tools - kermit and intstat program used to track device loading of system.
• upda10 - upgrade to version 10
• upda9 - upgrade to version 9
• ut - Utility programs that are used by the CONTROL systems
• util - utilities called by scripts or stuff that doesn't mesh with working system
• utbinl - text mode linux utilities
• utbinw - Windows utilities
• utbinx11 - QT Linux utilities

QTSupport

Symlinks

• qtscox-3.0.4
• qtwin-3.1.1
• qtwin-3.3.5
• qtx11-3.0.4
• qtx11-3.0.6
• qtx11-3.3.5
• qtx11-3.3.5b

(not supplied to customers)

• localbinl - linux text binaries
• localbinw - windows
• localbinx11