The tsmAPI Library: Tutorials

OPENING A DATASET CONNECTION

In order to read or write any data via the tsmApi you need to open a connection to the particular dataset. Once you are finished accessing this dataset you should then close the connection in order to free up any memory, handles, locks, etc. that it owns. As an example, the following code segment opens a read-only connection to a dataset

   TsmConnection connect;
   char          *name = "~magic/TileSets/Pyramids/ntc-1-utm-2scene.128.oi";

   connect = tsmConnect( name, "r", NULL );
   /* do some dataset access */
   tsmDisconnect( connect );

In this example we passed two parameters to tsmConnect: the dataset name and the access mode. We will deal with the third, NULL, parameter in a moment.

The dataset name can be any directory on local disk that contains a valid TerraVision dataset, or it can be a URL that specifies the same. tsmApi supports URLs that refer to localhost pathnames, http pathnames, or DPSS locations. For example:

file://localhost/homedir/magic/TileSets/Pyramids/yosemite.oi
x-dpss://iss-1.sri.magic.net/Pyramids/ntc-1-utm-2scene.33.dem
http://www.ai.sri.com/~magic/TileSets/Pyramids/ntc-1-utm-2scene.128.oi

The third parameter to the tsmConnect call can be used to provide a list of optional hints to specify various requirements for the dataset; from characteristics like the image format of the data desired to the set id number that uniquely specifies a dataset on a DPSS. If this parameter is NULL (as in the above code example), then this means that you are happy to take any version of the dataset that is available, e.g. any image format for a local disk dataset or any server combination for a DPSS pyramid.

If you wish to provide some specific requirement for your connection, then you can build a TsmConnectionParams structure and pass this as the third parameter to tsmConnect. For example, the following code sets up a request for a JPEG dataset on a DPSS with a specific server combination:

   TsmConnection       connect;
   TsmConnectionParams params;
   char                *name = "x-dpss://iss1.ai.sri.com/Pyramids/ntc-1-utm-2scene.128.oi"

   tsmInitParams( &params );
   tsmSetParam( params, TSM_PARAM_FORMAT, TSM_JPEG_FORMAT );
   tsmSetParam( params, TSM_PARAM_SERVERS, "sri-server1" );
   tsmSetParam( params, TSM_PARAM_SERVERS, "lbl-server3" );

   connect = tsmConnect( name, "r", params );
   tsmFreeParams( params );

   /* do some dataset access */
   tsmDisconnect( connect );

Note that once you have finished using a TsmConnectionParams structure, you should free up any memory that it is using by calling the tsmFreeParams call. You can of course use the same TsmConnectionParams structure for multiple tsmConnect calls. In which case, make sure that you free the structure only after the last call to tsmConnect that uses it.

Next Tutorial: Querying a Dataset Connection
Previous Tutorial: Compiling a tsmApi Program
Manual Page References: tsmConnect, tsmInitParams, tsmSetParam, tsmFreeParams,

The tsmApi Home Page / The tsmApi Tutorials Page

Martin Reddy, <reddy@ai.sri.com> / Yvan Leclerc, <leclerc@ai.sri.com>
Last modified: Wed Aug 23 00:45:34 PDT 2000