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.

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'.

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]
• [:CONTROL/CodeNotes/adl:adl.c]
• [:CONTROL/CodeNotes/cont:cont.c]
• [:CONTROL/CodeNotes/cyc:cyc.c]
• [:CONTROL/CodeNotes/eat:eat.c]
• [:CONTROL/CodeNotes/enq:enq.c]
• [:CONTROL/CodeNotes/ent:ent.c]
• [:CONTROL/CodeNotes/log:log.c]
• [:CONTROL/CodeNotes/lstr:lstr.c]
• [:CONTROL/CodeNotes/min:min.c]
• [:CONTROL/CodeNotes/post:post.c]
• [:CONTROL/CodeNotes/rein:rein.c]
• [:CONTROL/CodeNotes/rep:rep.c]
• [:CONTROL/CodeNotes/sale:sale.c]
• [:CONTROL/CodeNotes/upda:upda.c]

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

[:CONTROL/Software/Scripts:Script Notes]

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.

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:

• spclinit - perform application initialisation
• speclparam - get application options/parameters
• spclbegin
• spclend - application finalisation