===============================================
HowTo: Create a Basic MineSight(r) Grail Script
===============================================
.. include:: ..\version.h

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

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

This document covers how to set up a Python script that can be both
executed from the command line and from the within a MineSight® product.

Related Links
-------------

 * `HowTo: Create an Embedded Script`_

.. _`HowTo: Create an Embedded Script` :
         howto-create-an-embedded-script.html


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

That you are familiar with Python and have basic understanding of how
MineSight® Grail integrates with the MineSight® System.

---------------
Getting Started
---------------

MineSight® provides you with a :file:`basic-boilerplate.py` script
located in the :file:`$(medexe)\\scripts\\samples` directory. The steps to
creating your script are,

 1. Copy and rename the :file:`basic-boilerplate.py` script to your new
    script name.

 2. Open the new script in your favorite editor.

 3. Go to the :f:`run_code()` function and add your Python script.


-------
Details
-------

This boilerplate can be used to discuss a few points regarding scripts.


  **import grail**

    Any statement that uses the *import grail* statement is indicating
    that you wish to use features of the MineSight® Grail library.

    .. Note::

       If your script imports a module from either the *grail.ip* or
       *grail.ms3d* sub-packages then your script will only execute
       within the context of MineSight®-IP or MineSight®-3D
       respectively.  If you wish to create a script that executes
       within MineSight®-3D see `HowTo: Create an Embedded Script`_.

  **What is gmain?**

    The :f:`gmain` function is a standard entry point for all scripts.
    This is the location in the script that any MineSight® product can
    communicate through.

    Of the numerous messages that can travel through a :f:`gmain`
    function you are generally only concerned with the
    :d:`messages.gRUN` message. All messages can be found in the
    grail.messages_ module.

  **if __name__=="__main___" idiom**

    If any script is executed from the command line like,

    ::

      python.exe myscript.py

    Then the :d:`__name__` attribute will be set to "__main__". Using
    this idiom will guarantee that anything below the if statement will
    be executed if and only if the script is executed from the command
    line.  However, if the script is executed from within a MineSight®
    product, the script will start with the :f:`gmain` function and
    ignore anything below the if statement.

    If you use the :f:`gsys.GMAIN` helper, you can do the following,

    .. python::

      gmain = gsys.GMAIN(main, __name__)
      gmain.run()

.. _grail.messages: ../Library_Reference/lib-grail-messages.html