===========================================
HowTo: Find the Item List for a Given Model 
===========================================
.. include:: ..\version.h
.. include:: howto-reference.h


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


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

Discusses how to find a list of items for a given model.

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

 * grail.data.model_ for model access.
 * grail.data.pcf_ for Project Control File (PCF) access.


----------
Background
----------

Project Control Files (PCFs) and Model files are inter-related in so far
as the items defined within the Model file are all listed within the
PCF. The PCF generally provides all the information necessary to work on
the data files for a given project.

---------------------------------------
Finding the Item List for a Given Model
---------------------------------------

By using the :c:`Pcf` object's :f:`itemlist()` function one is able to
get a list of items that are defined for a model. As an example consider
that you have Project Control File (PCF) called :file:`samp10.dat`, and
a model file called :file:`samp15.dat`. You can determine the item list
with the following script,
   
   .. Python::

     from grail.data import pcf
     p = pcf.Pcf("samp10.dat")
     itemlist = p.itemlist("samp15.dat")

which returns a list of items that are found in the :file:`samp15.dat` model
file that is part of the *samp* project.

Item Lists within Compass Style Scripts
---------------------------------------

When you are within a compass style script (a script that requires you
define a project file to start), then you can retrieve the contents of
the item list using the grail.compass.cmpsys_ module's :f:`getpcf()`
function. For example, the following line will retrieve the current
:c:`Pcf` object, and determine the items for a File 13 model file,

   .. Python::
      
      p = cmpsys.getpcf()
      items = p.itemlist("samp13.dat")