=========================
``grail.messages`` module
=========================
.. include:: ..\version.h
.. include:: ..\Library_Reference\lib-reference.h


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

-----------
Description
-----------

This module contains messages that are used in conjunction with the 
:f:`gmain()` function (see grail.gsys_). The typical MineSightŪ Grail 
script will contain the following lines of code,

 .. Python::
 
   from grail import messages
   from grail import gsys
   
   def gmain(message, data):
      if message == messages.gRUN:
         run_my_code()
      else:
         return gsys.grailmain(message, data)

**However** starting with v4.70, you can now simply do the following,
and not have to worry about any messages,

    .. python::

      from grail import gsys

      def main():
          # Run my code...

      gmain = gsys.GMAIN(main, __name__)

This will take care of handling all messages, and redirecting execution
to your :f:`main` function.


Typical Messages 
----------------

For scripts that do not need to interact within a compass environment 
the most important messages are,

:dd:`gPRE_RUN`
  This message is sent prior to the time when a script is set up. You 
  can use this message for some pre-configuration options.

:dd:`gRUN`
  By far the *most* common message that you will listen for. This message
  signals that you can start executing your code.
  
:dd:`gPOST_RUN`
  Use this as an opportunity to perform some post-processing.


Messages for MineSightŪ Compass Style Scripts
---------------------------------------------  
  
With MineSightŪ Compass, there are some additional messages that you may find
of interest if you are attempting to build a "Compass Style" script.

:dd:`gRUN`:
   This message signals that you should post your dialog using the 
   :f:`cmpsys.runprocedure` function.
   
:dd:`gCREATE_RUN_FILE`
   This message is sent requesting that you go ahead and create a runfile
   using the grail.compass.runfile_ module.
   
:dd:`gMXPERT_STR_OUT`:
   This message is sent requesting that you return the string that you
   wish to insert within the Mxpert batch file.

   
All other messages are generally used by the MineSightŪ Grail system itself.

Messages for PYZ Command Line
-----------------------------

If you are executing a PYZ script from the command line some additional
messages will be supplied. Namely the following.

:dd:`gPZ_COMMAND_LINE_ARGS`
   This message will have a data value equal to the arguments supplied
   at the command line.


.. _grail.gsys: lib-grail-gsys.html
.. _grail.compass.runfile: grail.compass/lib-grail-compass-runfile.html