===============================================
HowTo: Determine the MineSight(r) Grail Version 
===============================================
.. include:: ..\version.h
.. include:: howto-reference.h


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

-------
Preface
-------

This document discusses how you can discover what the working version of
MineSightŪ Grail is on your machine. The version can be used to ensure
that you are running the correct library, or to make sure that you
script is working with the correct library.

Assumptions
-----------

It is assumed that the reader has a rudimentary knowledge of Python and
the MineSightŪ Grail scripting library.

-----------------------
Determining the Version
-----------------------

The version is stored in the :d:`grail.version` data member. You can
access the version number with a simple little script like this,

.. Python::

  import grail
  print grail.version

If you do not wish to write a script you can take advantage of the -C
option with the :file:`python.exe`. This allows you to input a small
script at the command line using the ";" as a line separator. Therefore
our above script can be re-written as the following at the command
prompt,

.. Python::

  c:\>python -C "import grail; print grail.version"

---------------------------------
Version Checking for Your Scripts
---------------------------------

The version may also be used as a check in your script to ensure that
the script is running with the correct version. You have the ability to
read the major, minor and build numbers for the MineSightŪ Grail version.
Those numbers are accessible via the following data members,

  * :d:`grail.majversion`
      The major version of the MineSightŪ Grail library. The library is
      guaranteed to remain stable in its core implementation  throughout
      a major version.

  * :d:`grail.minversion`
      The minor version of a MineSightŪ Grail library. The library will
      gain and/or deprecate features only on each minor version.

  * :d:`grail.patchversion` 
      The patch version. Used to signify bug fixes that are applied to a
      minor version. No new enhancements or deprecations are applied
      from one patch version to the next.

All the above data is in integer format.

For example, assuming that your script is only capable of running with
version 3.4 and greater MineSightŪ Grail libraries, then you could add
the following lines to the top of your script to generate a
:e:`ImportError` if the version is incorrect,

.. Python::

  import grail
  MINIMUM_VERSION = 3.4
  CURRENT_VERSION = float("%d.%d" % (grail.majversion,
                                     grail.minversion))
  if CURRENT_VERSION < MINIMUM_VERSION:
     raise ImportError,\
           "Invalid MineSight(r) Grail version; require %f." %\
           (MINIMUM_VERSION)