Documentation

Open a connection to a dataset.

In order to do anything to a dataset, you need to use this function to open a connection to that particular dataset. Note that you use one connection for one dataset, so if you wish to open two datasets then you will need to do to tsmConnect's.

In order to open a connection you need to specify two pieces of information (with an optional third). These are:

1. The name and location of the dataset. This can be a local filesystem filename, or a URL. Examples of valid dataset names include:
   1. ~magic/TileSets/Pyramids/ntc-1-utm-2scene.128.oi
   2. file://localhost/homedir/magic/TileSets/Pyramids/yosemite.oi
   3. x-dpss://iss-1.sri.magic.net/Pyramids/ntc-1-utm-2scene.33.dem

2. The access mode that you wish for the connection. Currently you can request a read-only connection ("r"), a write-only connection ("w"), or a read-write connection ("rw"). For example, if you request a read-only connection then you will not be able to use the tsmWriteTile() function.

3. (Optional) You can also provide a TsmConnectionParams structure which lets you specify further details about the dataset and override any default settings (such as the image format of tiles to use). If you don't want to specify this, then you can pass a NULL pointer for this parameter. To find out what details you can specify with the TsmConnectionParams structure and how to use it, please refer to the triumvirate: tsmInitParams, tsmSetParams, and tsmFreeParams.

Once you have opened a connection to a dataset, then you can do any processing that you wish, e.g. read tiles from the dataset (if you have requested a readable connection), or write new tiles to the dataset (if you have asked for a write connection). When you have finished manipulating the dataset, you call the tsmDisconnect function to close the connection and free up any held resources.

The following list provides details to help you understand how the use of the TsmConnectionParams structure affects the dataset that is actually connected to:

Reading a Local Disk Dataset (file:// URL)

• Reading Tile Data : Local disk pyramids can contain any of a number of different representations of the tile data. These include .tile files (1 .tile file per tile), and .tiff files (1 .tiff file per pyramid level). In addition, you can have raw .tiff files or jpeg compressed .tiff files.

  You can specify if you want to use the raw .tile format tiles by setting TSM_PARAM_TIFF to FALSE, otherwise the default will be to use a TIFF format file for the data.

  If you are asking for a TIFF file, then you can use the TSM_PARAM_FORMAT hint to specify if you want to use the raw lrbt (TSM_LRBT_FORMAT), or jpeg compressed (TSM_JPEG_FORMAT) version of the dataset. The default is to use the raw lrbt tiles. This hint will be ignored if you have set TSM_PARAM_TIFF to FALSE.

  If the specified combination of .tile/.tiff and lrbt/jpeg does not exist, then tsmApi will try to find another version of dataset that it can use, e.g. if the lrbt TIFF file doesn't exist and there is a jpeg TIFF, then tsmApi will use this one instead. You can override this behaviour by setting TSM_PARAM_FALLBACK to FALSE. In which case, tsmApi will fail immediately if it cannot fulfil your specific dataset requirements.

• Reading Tspecs : Tspecs can be stored in two different formats: an older multi-file format where many different tspec files were used, and a newer single-file format where all this information is stored in a single file. By default, tsmApi will try to load the newer style tspec file. If this fails (e.g. file does not exist), then it will fallback and try to load the older style tspec files. You can override this by setting the value of TSM_PARAM_NEW_TSPEC. If this is TRUE, then only the new single-file tspec will be looked for. If this is FALSE, then only the older tspec files will be looked for.

  Once a tspec file has been read it, it will be validated to check that it contains valid data. This check is performed by the tsmValidateTspec routine (refer to the documentation for this page to see which fields are validated). You may disable this validation process by setting the TSM_PARAM_VALIDATE_TSPEC param to FALSE using tsmSetParam.

Reading a DPSS Dataset (x-dpss:// URL):

• Reading Tile Data : A dataset on a DPSS is uniquely identified by a set-id. It is entirely possible to have two datasets with exactly the same name, server combination, and image format; as long as their set IDs differ. The following steps are performed in order to try and find a dataset's set ID:
  1. If the dataset URL that you provide is in the form x-dpss://host/Pyramids/set-id then this set ID is used.

  2. Next, if the param structure has a set ID defined (TSM_PARAM_SETID), then this value is used.

  3. Otherwise, if the URL that you provide is in the form x-dpss://host/Pyramids/name and the param structure has a list of server names defined (TSM_PARAM_SERVERS) then these are used to try and find a dataset with that combination of servers. In addition, if you specify an image format with TSM_PARAM_FORMAT then this will try to be matched against also (the default image format is raw lrbt).

  4. If all of this fails to find a valid set ID, then tsmApi will try to find any dataset with the specified name on the DPSS (i.e. this could be any server combination and any image format).

  N.B. if you set TSM_PARAM_FALLBACK to be FALSE, then tsmApi will fail immediately at step 3) if the specified server/image combination does not exist (i.e. you need to specify a server combination if you set TSM_PARAM_FALLBACK to FALSE).

• Reading Tspecs : Tspec data for a DPSS dataset can exist either on some other server (accessed via http or file protocols), or they can be embedded in a block in the DPSS dataset itself. By default, tsmApi will check to see if the dataset exists on the DPSS dataset itself. It this fails, then the various metadata (tspec) URLs for that set are tried in turn until one succeeds. If you want to override the loading of the tspec file from the DPSS set, then set TSM_PARAM_DPSS_TSPEC to FALSE. This tells tsmApi to only try the metadata URLs.

  The TSM_PARAM_VALIDATE_TSPEC param can also be set to FALSE to bypass the tspec validation process once it has been found and loaded.

Reading HTTP Datasets (http:// URL):

• Reading Tile Data : reading of tile data is not currently supported over http links.

• Reading Tspecs : Reading tspec files over http has the same behaviour as reading tspec files from localdisk. That is, the new tspec format will be tried first, and if this is not available then the old tspec files will be tried. You can set the value of TSM_PARAM_NEW_TSPEC to override this default behaviour as you can for localdisk datasets, and TSM_PARAM_VALIDATE_TSPEC param can be set to FALSE to bypass the tspec validation process upon loading.