                 doc/preprocessors/README.txt      (14 January 2012)
                 ============================

                 Writing a Preprocessor Script
                 =============================

    LCMgui executes the Preprocessor script with 5 arguments, like the command:

       preprocessor $1 $2 $3 $4 $5

    $4 and $5 are only present if the unsuppressed water reference data is 
extracted from a single file together with the water-suppressed data (only 
with GE, Picker & Toshiba files).

    All argv[] are supplied by LCMgui.

    The first two argv are files that this Preprocessor can append output to:
$1 = absolute pathname of the cpStart file, where you append the Control 
     Parameters calculated here in the Preprocessor. 
$2 = absolute pathname of the extraInfo file, where you append the 
     extra information for LCMgui that you calculate here.  The extraInfo 
     file would seldom be modified by the Preprocessor, and it is not 
     further documented here.
    The above two files are initially produced by LCMgui's bin2raw.  You 
can append further parameters or change any that were output by bin2raw.  
You do this by appending your values at the end of the appropriate $1 or $2.  
Your values will then overwrite any values for the same parameters 
originally output by bin2raw.  bin2raw values for Control Parameters or 
extraInfo not appended by you will remain unchanged.

    The last three argv are input files supplied by LCMgui to the Preprocessor:
$3 = absolute pathname of the LCModel RAW file containing the 
     (water-suppressed) data.
$4 = absolute pathname of the extraInfo file containing extra information
     produced by bin2raw on the unsuppressed water reference data.
$5 = absolute pathname of the LCModel RAW file containing the unsuppressed 
     water reference data.
-----------------------------------------------------------------------------

PROCEDURE
    You use the 5 files $1--$5 provided to compute additional LCModel 
Parameters that you append to $1 (the cpStart file) in the following format:
<Control Parameter>= <value>
For example:

echo "nunfil= 2048
ppmref(1,2)= 2.01
title= 'Exam 777-77, ... Head-Coil'
doecc= T
"  >>  $1

Note the following strict rules for this file:
(1) The Control Parameter names must be lower case and contain no whitespace.
(2) The "=" must immediately follow the Control Parameter name with no
    whitespace. 
(3) There must be whitespace between the "=" and the value.
(4) For logical variables, use "T" instead of ".TRUE." and "F" instead of 
    ".FALSE." (as in "doecc= T" above).

    You could also change the RAW files by appending to $3 or $5.
-----------------------------------------------------------------------------

ERROR MESSAGES
     To properly communicate with LCMgui, you must:

(1) Always make a "successful" exit with "exit(0)" in C and "exit 0" in a
shell script, even on an error.

(2) On an error exit, write an error message to stdout (not stderr) i.e., in 
      C with 
        printf("Your error message.") 
      and in a shell script with 
        echo "Your error message."
    LCMgui will display "Your error message" and ask you whether or not to 
      keep using this Preprocessor.
    In your error message, do not use the special string "NeedWaterReference".

(3) Do not write to stdout except to put an error message there.  LCMgui 
    only recognizes a successful exit if nothing has been written to stdout.
============================================================================
