QMERGE is an unusual program, but it tackles a common problem - how to keep control of programs which exist in a number of different versions. The commonest examples are programs which run on a variety of different machines, and require slight changes to the source code for each one. For example, changes may be necessary because of different file naming conventions, word length, or different ways of accessing the system. Fortran doesn't even provide a standard way of obtaining the command line!
QMERGE solves this problem by allowing the user to keep all the code variants within the master version of the source code. It comments and un-comments sections of code depending on the settings of user-defined logical flags. Unlike a macro pre-processor or conditional compilation tool, QMERGE does not require that you deviate in any way from ANSI standard Fortran, or that you pre-process code before submitting it to a compiler - the master version is legal Fortran and can be compiled directly. QMERGE is needed only when you create a version for porting to a different machine.
The operation of QMERGE is probably best understood by reference to an example, such as that in the following table. This program fragment consists of one section which is activated if the condition IBMPC is TRUE, and another which is activated if IBMPC is FALSE, and at least one of the conditions MVS, VAX and UNIX is TRUE (the commas between them may be read as 'OR'). Inside the IBMPC section is a nested !-IF construct containing sections which may be activated depending on the values of the DEMO and DEBUG conditions.
Version 1 of the program fragment is consistent with the condition IBMPC being FALSE, and one of MVS, VAX or UNIX being TRUE . The values of DEMO and DEBUG are irrelevant in this case. Version 2 could be obtained by passing version 1 through QMERGE and specifying IBMPC as TRUE, DEMO as FALSE, and DEBUG as TRUE (the '-' in front of DEBUG may be read as 'NOT'). In fact, the result does not depend on which lines are commented out in version 1, but only on values of the conditions. It is quite possible to convert version 2 back to version 1 (by running QMERGE with IBMPC set to FALSE and MVS set to TRUE).
Version 1 |
Version 2 |
!-IF IBMPC
!- PRINT *,'IBMPC'
!-IF DEMO
!- PRINT *
!- PRINT *,'Demo'
!-ELSEIF -DEBUG
!- PRINT *
!- PRINT *,'Debug off'
!-ELSE
!- PRINT *
!- PRINT *,'Debug on'
!-ENDIF
!- X = Y
!- A = B
!-ELSEIF MVS,VAX,UNIX
PRINT *,'non PC'
!-ENDIF
|
!-IF IBMPC
PRINT *,'IBMPC'
!-IF DEMO
!- PRINT *
!- PRINT *,'Demo'
!-ELSEIF -DEBUG
!- PRINT *
!- PRINT *,'Debug off'
!-ELSE
PRINT *
PRINT *,'Debug on'
!-ENDIF
X = Y
A = B
!-ELSEIF MVS,VAX,UNIX
!- PRINT *,'non PC'
!-ENDIF
|
Condition names may be up to 16 characters long. They are not case sensitive. !-IF constructs may be nested up to 20 levels deep.
To start a run, simply type qmerge followed by the name of the file(s) you wish to process. You can use wild-cards to specify more than one file. You should also specify a condition string using the SELECT= keyword (see Section 5.3 for a discussion of condition strings). For example
qmerge a*.for b*.for SELECT=IBMPC,DEMO
or under UNIX
qmerge a*.f b*.f select=ibmpc/demo
processes the contents of all files in the current directory which fit either wildcard using the condition string 'IBMPC/DEMO'.
Under DOS/Windows and VMS, .for is assumed if no extension is specified (b* is treated as b*.for). The default file name is *.for. Thus, if you don't specify any files, all .for files in the current directory are processed. The separator in the condition string may be either '/' or ','.
Under UNIX, the extension must be specified, and there is no default file name. The separator in the condition string must be '/'.
To force QMERGE to run without a pre-specified condition string, so that it prompts for the values of all conditions it needs to know, insert the character '=' after the SELECT= keyword:
qmerge select== *.f
The operation of QMERGE may be modified by command line switches. Currently the following switches are available:
| FIG= |
specifies the configuration file name. If you don't specify a file name in this way, QMERGE assumes that the configuration file is called qmerge.fig. In either case, the search rules defined in section 1.4 are followed. If the configuration file exists, QMERGE reads it before reading the input files. The configuration file may contain source code directives to set further conditions (see Section 5.4). Nothing from the configuration file is copied to the output file. If a '?' is appended (e.g. FIG=QMERGE.FIG? or FIG=?), QMERGE lists the contents of the active configuration file to the screen, with a pause after each screen full. |
| TO= |
specifies the name of the file to which the QMERGE output is sent. The default file name is qmerge.out QMERGE sorts file names into alphabetical order before processing, and inserts header records in the output file so that the modified version of each input file can be identified. |
| HEAD= |
specifies the four characters to be used to identify the header records which are placed before each file in qmerge.out. The header record contains the 4 specified characters followed by the name of the following file. A utility called QSPLIT which splits up merged files produced by QMERGE or SPAG is supplied. The default header record identifier is **==. |
For example
qmerge a*.ftn select== head=c##==
If the SELECT= keyword is omitted, QMERGE merges the input files without processing; in this case QMERGE simply concatenates the input files in alphabetical order by name, with header records before each file to allow subsequent use of QSPLIT.
qmerge a*.for
This simple style of usage is useful because it allows you to deal with programs either as a single large file, or as a set of files each containing a single routine. For example, if you normally keep your source code in a large number of files, but you want to make a global change to a program, you can use QMERGE to merge the entire source code into a single file, and make the change in a single edit session. When the change is finished, you can use QSPLIT to split the program back into its constituent parts.
Normally, QMERGE determines the value of conditions by prompting the user as the need arises. For example:
Is IBMPC true? (Y or N) ==>
However, it is also possible to specify the value of some or all conditions externally to reduce or eliminate the need for prompts. This is done by setting up a 'condition string' which is passed to QMERGE via the command line. A condition string consists of a series of condition names separated by '/' or ',' characters. The conditions specified in the condition string are taken to be TRUE, unless the condition name is preceded by a '-' in which case the condition is FALSE. For example,
qmerge *.f select=ibmpc/debug/-demo
specifies that IBMPC and DEBUG are TRUE, but DEMO is FALSE. All other conditions are undefined, and if necessary, QMERGE will prompt for a value.
To suppress prompting, so that QMERGE can be run non-interactively, it is necessary to specify all conditions, or include a '!' in the list of conditions. This has the effect of implicitly answering with a 'N' whenever a prompt would otherwise appear. For example
qmerge select=UNIX/!
specifies that UNIX is TRUE and that everything else is FALSE.
If you include the word 'SHORT' in the list of conditions, then any lines which begin with the characters !- are not copied to the output file. Thus if the condition string contains
qmerge select=MVS/SHORT/!
the output file for the example in section 5.1 would be reduced to a single line
PRINT *,'non PC'
Conditions may be specified within the source code itself, or within a configuration file which is read at the start of every run. This is done using the !-SELECT directive. For example
!-SELECT -DEBUG,-DEMO
!-IF VAX
!-SELECT VT100,ASCII,GKS,ORACLE
!-ELSEIF IBM370
!-SELECT IBM3270,EBCDIC,GDDM,DB2
!-ELSE
!-SELECT WYSE,ASCII,XWINDOWS,DBASE
!-ENDIF
activates different flags depending on the values of VAX and IBM370.
!-DEFAULT is a variant of the !-SELECT directive. Conditions specified after !-DEFAULT take effect only if the specified condition is undefined. So, for example, if you have
!-SELECT DEBUG
!-DEFAULT -DEBUG,-DEMO
then DEBUG is true, because the specification in the !-DEFAULT directive does not override that in the !-SELECT. DEMO will be false (assuming it has not previously been set).
Note that !-SELECT will over-ride conditions passed from the command line, while !-DEFAULT will not.
A particularly useful directive is !-ONEOF. This has the effect of specifying that exactly one of the following conditions must be true, and that all others are false. If in doubt, QMERGE will ask the user to specify which is true. For example, if QMERGE reads:
!-ONEOF SUN,HP,IBM,DEC
then QMERGE evaluates the conditions SUN, HP, IBM and DEC. If one is true, then the others are set false. Otherwise QMERGE issues a prompt:
Which of the following is TRUE?
A - SUN
B - HP
C - IBM
D - DEC
Please enter letter ==>
A sample configuration file containing examples of all these source code directives is available in the plusFORT installation directory.