================================
HowTo: Create an Embedded Script
================================
.. include:: ..\version.h
.. include:: howto-reference.h

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

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

This document discusses the basic creation of a MineSight® Grail embedded
script. It will go through the process of creating a script that
displays "helloworld!" in the MineSight® 3D message window.

Note that an embedded script has some extra components that must be
considered above and beyond the basic MineSight® Grail Script.

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

  * `HowTo: Create a Basic MineSight® Grail Script`_

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

It is assumed that you are familiar with the MineSight® 3D, and the basic
mechanics of a python script.

To execute a MineSight® Grail embedded script you must run the script
inside the MineSight® 3D. Any script that references the grail.ms3d
module, has this requirement.

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

The process for creating and running an embedded script involves first,
editing your script, then executing your script within MineSight® 3D.


Creating the Script
-------------------

To start the creation of a basic helloworld script open the
:file:`$(medexe)\\scripts\samples` directory and copy the
:file:`em-boilerplate.py` to a new file called :file:`helloworld.py`.

Now open the :file:`helloworld.py` script and go to the :f:`run_code`
function, which will look something like this,

.. Python::

 def run_code():
     """Sample 'function' in embedded script.

     This function will write some text out the message
     window, but you can have it do anything you like.
     """
     print "Boilerplate."

Replace the "Boilerplate" text with "Helloworld!".

.. Python::

 """Example of Helloworld embedded script.

 This script illustrates how to print helloworld to the MineSight 3D
 message window.

 LICENSE AGREEMENT

 The Original Code is "helloworld.py".

 The Initial Developer of the Original Code is Leica Geosystems.
 Portions created by Leica Geosystems are Copyright (C) 2014 year.
 Leica Geosystems. All Rights Reserved.
 """

 from grail import gsys

 def run_code():
     """Displays helloworld to the message window."""
     print "Helloworld!"


 gmain = gsys.GMAIN(run_code)
 gmain.run()


`Download the complete helloworld.py script`__.

.. __ : helloworld.py

.. That was an anonymous link.

Running the Script
------------------

To execute the :file:`helloworld.py` script, you must,

 1. Start up MineSight® 3D.
 2. Select File->Run Script...
 3. Use the file chooser to select :file:`helloworld.py`

After selecting the file, the script will execute. The "Helloworld!"
string will be displayed within your MineSight® 3D message window.


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

This simple example can be useful for discussing a few points regarding
embedded scripts,

  **Using grail.ms3d**

    Any script that has a "from grail.ms3d import..." line within it is
    termed a MineSight® Grail embedded script. This means that the script
    can only be executed within the context of a MineSight® 3D
    environment.

    Notice, that since MineSight® IP is also within MineSight® 3D you can
    use embedded features within a MineSight® IP 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.

    Starting with v4.70 we introduced the "GMAIN" function to help
    simplify creating a script entry point. Now all you have to do is,

    .. python::

       from grail import gsys

       def main():
          # your code

       gmain = gsys.GMAIN(main)

  **Print Statements**

    All print statements will appear in the MineSight 3D message
    window.