===================================
``grail.data.batchReserves`` Module
===================================
.. include:: ../../version.h
.. include:: ref.h

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


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

Provides access to the MineSightŪ Interactive Planner Reserves
Dictionary (dRes) outside of the IP tool.


The batchReserves library consists of a `ReservesDict Class`_ and
methods that allow you to get the reserves dictionary from the AGDM
Database and print the dictionary. 

The reserves dictionary contains cut reserves records, cut attributes,
area and materials information as well as plan information. This
reserves dictionary is the same data as in the reserves dictionary
avalible in scripts run from the IP tool, with minor differences due to
the fact that MineSightŪ Interactive Planner is not open (see
grail.ip.reserves_). 

--------
Examples
--------

Getting the Reserves Dictionary 
-------------------------------

The follow code snippet illustrate how to use the
grail.data.batchReserves module to get the reserves dictionary. 


.. Python::


    from grail.data import batchReserves                   #1
    
    ip = batchReserves.ReservesDict("msop-ip", "plan1")    #2
    dRes = ip.getReservesDict()                            #3
    

The basic steps shown above are,

 1. import the grail.data.batchReserves module into your script.
 
 2. initalize ReservesDict class.

 3. get the reserves dictionary 


Running a Standard Reserves Script in Batch Mode 
------------------------------------------------

Some of the Standard Reserves scripts can be run in batch mode by
modifying them to use the batchReserves module. The follow code snippet
is an example of how to modify ip-report.py to run outside of the
MineSightŪ Interactive Planner tool. 


.. Python::


    from grail.data import batchReserves                       #1

    DSN_STRING = "msop-ip"                                     #2
    PLAN_NAME =  "plan1"

    #from grail.ip import reserves                             #3
    #from grail.ip import core
    #from grail.ip import equtils
    #from grail.ms3d import mssys
    #sys.stdout = mssys.stdout   


        #hRes = reserves.hGetCurResRef()                       #4
        #dRes = reserves.dGetRes(hRes)       
    
        ip = batchReserves.ReservesDict(PLAN_NAME, DSN_STRING) #5
        dRes = ip.getReservesDict()                            
    

    if __name__=="__main__":                                   #6
        run()

Open ip-report.py in an editor and make the following modifications as
shown above: 

 1. add import grail.data.batchReserves 
 2. assign values to the dsn and plan name constants
 3. comment out embedded imports and code that uses them
 4. in def run(), comment out the two lines that get the reserves
    dictionary interactively
 5. in def run() add lines to get the batch reserves dictionary
 6. add script initalization at the end of the script
 


------------------
ReservesDict Class
------------------
 
This class provides access to the reserves dictionary.

class :dc:`ReservesDict(dsnName, planName)`

  Opens a database connection to the Attributed Geometry Data Model
  (AGDM) defined by the given :a:`dsnName` and IP set given by
  :a:`planName`.

  This will raise an :e:`ReservesDictError` if the :a:`dsnName` does not
  exist or if the :a:`dsnName` points to a database that is not an AGDM
  or if :a:`planName` is not an IP set. 

  If a user name and password are required to access the AGDM database,
  construct the :a:`dsnName` string as "DSN name/user name/password".
  
  Once you have a :c:`ReservesDict` object connected you can retrieve or
  print the reserves dictionary with the following methods: 

  :df:`getReservesDict()`
     
    Returns the reserves dictionary for the plan and dsn specified. 

  :df:`printReservesDict([fln, spawn])`

    Prints the reserves dictionary. :a:`fln` is an optional argument
    that if supplied, the dictionary will be printed to that file name.
    If :a:`fln` is not given, the dictionary will be printed to a
    temporary file in your systems Temp directory. :a:`spawn` is an
    optional argument, that if set to zero, the report will not be
    spawned by the application associated with :a:`fln`, otherwise the
    report file will be automatically spawed. (defaults are spawn=1 and
    fln='')