=================================
``grail.longhaul`` Module
=================================
.. include:: ..\version.h
.. include:: ..\Library_Reference\lib-reference.h


.. contents:: Table of Contents
   :backlinks: top

.. note:: 
   The 64 bit version of this library is disabled. The library
   will continue to be importable and "startable"; however it will
   no longer perform any actions in 64 bit. The module licensing
   that originally inspired this module is not active in 64 bit.

--------
Overview
--------

Longhaul is a method for acquiring a license and have subsequent MineSightŪ
products validate against the longhaul instead of making a validation across
the network or to your local dongle.

This is particularly useful if you MineSightŪ Grail script will spawn other
MineSightŪ products multiple times during the duration of the script. What
``longhaul`` provides you with, is the ability to make one license check,
and allow all subsequent license checks be against longhaul.

If longhaul fails, or if there is no license available, then the script
will still proceed. The idea here is to provide the ability to get
faster licensing, but not at the expense of causing a script to fail.

-------------
Example Usage
-------------

Suppose we have a case were we want to call the :file:`sclip.exe` many times
with different sets of arguments. We don't want the :file:`sclip.exe` to make
an expensive calls to the network, instead we would like to valid the
license once, and then proceed to,

.. Python::

  from grail import longhaul
  longhaul.start()

  for runNum in range(manyRuns):
     clipArgsForRun = MakeClipArgs(runNum)
     os.system("sclip.exe %s" % (clipArgsForRun))

The above example is simplified in the way it gets its arguments for
:file:`sclip.exe`; however, the basic steps are the same. In the above
example, if :f:`longhaul.start` succeeded, then each time you start
:file:`sclip.exe` program from the :f:`os.system` function call, the
:file:`sclip.exe` program will succeed with the faster longhaul license check.

Because we didn't supply any arguments to the :f:`longhaul.start` function,
``longhaul`` will use the `Preferred License Module Search Order`_ described
below.

Notice that you did not need to stop ``longhaul``, since when your script
stops, ``longhaul`` will stop. However, if you wish to stop lonhaul midway
through your script to release a license, you can use the :f:`stop` function.

Sometimes you may want a script to execute in conditions where MineSightŪ
Grail does not have a longhaul module. One way to make sure your scripts
are backwards compatible is by inserting the following statements into
your script,

.. Python::

  try: 
     from grail import longhaul
     longhaul.start()
  except ImportError, e:
     pass # no longhaul available

This will give you the faster longhaul license checking if it is
available, but still allow your script to execute if longhaul is not
available.

-------------------------------------
Preferred License Module Search Order
-------------------------------------

``longhaul`` has a preferred search order when it comes to individual
license modules. The preferred search order is as follows,

.. The following header file can be found in the ms2inc $(MSINCHOME), and
.. is copied to this directory as part of the msgrail.build "CompileDoc"
.. target. The file is generated based on the contents of the keymodules.mdb.

.. include:: doc-grail-longhaul-preferred.h
 
---------
Functions
---------

:df:`start([modules])`
   Starts the longhaul process with a request for a module.

   
   The :a:`modules` can either be omitted, a single module value, or a
   list specifying license module search order. If the :a:`modules` argument is
   omitted, longhaul defaults to a preferred module order discussed above (see
   `Preferred License Module Search Order`_).
   
   The function will raise a :e:`ValueError` only if the modules supplied
   are not valid, or the input is not what is expected.
   
   The function will return 1 if the license was acquired, and 0 otherwise.
   If the longhaul :f:`start` did not succeed, it only means that your
   subsequent license calls in spawned MineSightŪ Programs may have a
   chance of failing as well.

:df:`stop()`
   Stops the longhaul process. If this function is not executed it will
   be executed when the python interpreter closes. This lets you not
   need to worry about stopping a longhaul license.

---------
Constants
---------   

.. The following header file can be found in the ms2inc $(MSINCHOME), and
.. is copied to this directory as part of the msgrail.build "CompileDoc"
.. target. The file is generated based on the contents of the keymodules.mdb.

.. include:: doc-grail-longhaul-constants.h