NAME
    qprepPreTranslationCallback: directive pre-translation callback for qprep


  ARGUMENTS
   \%state_table (in/out): reference to hash table of qprep options
     See qprepStateInitializeParserControls.

   \%directives_table (in): table of valid directives
     See qprepValidDirectiveTableInitialize.

   $directive_key_ref (in/out): reference to directive key scalar

   $directive_value_ref (in/out): reference to directive key scalar

   $output_stream (in): file handle for output script


  DESCRIPTION
    qprep calls this routine after reading an input directive,
    but before applying the translation table.

    The primary utility of this routine is to record or alter state
    information and write directives in the local queue system language
    which would be too complicated or impossible to handle with the
    translation table.

    For example, some systems distinguish between "nodes" and "cpus",
    and to reflect this, qprep has directives to set each of these.
    Many systems, however, do not make this distinction, so you simply
    want to set the number of CPUs for the job to use.  A simple
    translation will not, in general, work, since the idea behind qprep
    is to allow users to write one script that works on all systems,
    hence the user often must specify "nodes" and "cpus_per_node",
    even on systems where those do not directly apply.  The solution is
    to write code in this routine to handle that situation:

    () qprepInitCallback would initialize state_table entries for "nodes"
       and "cpus_per_node" to special nonsense values to indicate to
       this routine that those values have not yet been set.

    () This routine would check to see whether directive_key_ref is either
       "nodes" or "cpus_per_node".

       [] If not, this routine ignores the input and returns.

       [] If so, this routine checks to see whether both values are unset.

          {} If not, this routine returns.

          {} If so then this routine alters the contents of
             directive_key_ref to the directive key that the local
             queue system uses to indicate the number of CPUs, sets
             directive_value_ref to that value, stores the value in
             the state table (which should be the product of node and
             cpus_per_node), and returns.

    () The qprepFinishPreambleCallback must also check to see whether
       this routine performed that last step.  If not then
       qprepFinishPreambleCallback must write the appropriate directive.

    This returned directive information will pass through table-based
    translation, and therefore the directives_table and translation_table
    must have an entry for the target directive key, and the associate
    directive table acceptance pattern must allow this value, or the qprep
    directive checker will reject the directive, report an error, and die.

    This routine can also handle other similar situations, such as
    in PBS, where multiple resources are set with a single directive.
    The solution there is similar to the one described above.


  SEE ALSO
    In this file:
       qprepInitCallback(), qprepFinishPreambleCallback(),
       qprepFinishScriptCallback().