SAMP MTypes

This page discusses SAMP MTypes. MTypes define the semantics of messages exchanged between SAMP clients.

Introduction

An MType (Message Type) is the semantic label attached to a SAMP message (see SampInfo). An MType is a string which looks syntactically like a.b.c , and it has associated named parameters and return values - it can be thought of as a bit like a subroutine definition. More detailed and definitive discussion of MType syntax and usage can be found in the SAMP Standard.

MTypes fall into (about) four categories:

Administrative

MTypes beginning samp. have meanings concerned with the workings of the SAMP protocol itself. An example is samp.hub.event.register, which is broadcast whenever a new client registers with the hub. These are defined in the SAMP standard, and new ones may not in general be introduced at will.

Experimental administrative

MTypes beginning x-samp. are candidates for administrative ones. They are not currently part of the standard, but may be introduced in future versions of it, with the x-samp. replaced by samp. .

Application

In order for applications to communicate meaningfully they must agree on what MType to use for a given action. Public MTypes are ones agreed by several application authors with well-known meanings. An example is table.load.votable , which instructs to load a table in VOTable format at a given location. These are currently documented below.

Private

Any application author is free to introduce any MType for his/her own purposes, as long as it does not start with the reserved string " samp. ". In the case that this is for private testing, specialised communication between tools developed in the same place, or similar, there is no requirement to document these in a public fashion.

Process

An application author who needs to exchange an application-type message with particular semantics should proceed along the following lines:

1. Check the list below to see whether a suitable MType already exists
2. If not, or if one exists but needs adjustment such as new optional parameters, make or solicit suggestions on the form of a suitable MType on the apps-samp@ivoa.net mailing list
3. When some agreement is reached, add the documentation to the list below

The intention is that application MTypes, once added to this list, will continue to be used for the purpose for which they were introduced rather than being replaced by other differently-named ones of similar purpose. There may be amendments which involve addition of optional parameters or return values, on the understanding that they do not invalidate messages exchanged without knowledge of the new additions. In this way backward compatibility should be maintained.

This procedure is currently quite informal. It has worked well to date, but will remain under review. If the SAMP community decides that a change to the procedure is desirable, for instance publication of Application MTypes in an IVOA Note, or more structured review of suggestions, the new policy will be described here. This page may be reorganised at some point, for instance splitting the known Application MTypes into more than one list.

---

Application MTypes

The following MTypes are ones which application authors are using, or are considering using.

table.load.votable

Loads a table in VOTable format. This is the usual way to exchange table data between SAMP clients.

• Arguments:
  • url (string): URL of the VOTable document to load
  • table-id (string) optional: identifier which may be used to refer to the loaded table in subsequent messages
  • name (string) optional: name which may be used to label the loaded table in the application GUI
• Return Values: none

table.load.*

Other table.load variants are permitted for different formats. The parameters and return value are the same as for table.load.votable above, but the resource referenced by the url argument has the appropriate file format. Variants known to be in use are:

• table.load.fits (FITS ASCII or binary table)
• table.load.cdf (NASA Common Data Format, not netCDF)

Note that clients are not encouraged to proliferate these format-specific MTypes. Where possible, it is recommended to use VOTable for exchange between VO-aware SAMP clients. For general purpose clients it is appropriate to send and receive only table.load.votable and not other table.load.* variants. However, where clients need to exchange tabular data in a particular format, for instance because both ends of the communication are known to understand the format in question, or because the data or metadata are likely to be compromised by conversion to VOTable, use of a different format-specific MType may be appropriate, on the understanding that such communication may not be interoperable with generic table-handling SAMP clients.

table.highlight.row

Highlights a single row of an identified table by row index. The table to operate on is identified by one or both of the table-id or url arguments. At least one of these must be supplied; if both are given they should refer to the same thing. Exactly what highlighting means is left to the receiving application.

• Arguments:
  • table-id (string): identifier associated with a table by a previous message (e.g. table.load.*)
  • url (string): URL of a table
  • row (SAMP int): Row index (zero-based) of the row to highlight.
• Return Values: none

table.select.rowList

Selects a list of rows of an identified table by row index. The table to operate on is identified by one or both of the table-id or url arguments. At least one of these must be supplied; if both are given they should refer to the same thing. Exactly what selection means is left to the receiving application.

• Arguments:
  • table-id (string): identifier associated with a table by a previous message (e.g. table.load.*)
  • url (string): URL of a table
  • row-list (list of SAMP int): list of row indices (zero-based) defining which table rows are to form the selection
• Return Values: none

image.load.fits

Loads a 2-dimensional FITS image.

• Arguments:
  • url (string): URL of the FITS image to load
  • image-id (string) optional: Identifier which may be used to refer to the loaded image in subsequent messages
  • name (string) optional: name which may be used to label the loaded image in the application GUI
• Return Values: none

coord.pointAt.sky

Directs attention (e.g. by moving a cursor or shifting the field of view) to a given point on the celestial sphere.

• Arguments:
  • ra (SAMP float): right ascension in degrees
  • dec (SAMP float): declination in degrees
• Return Values: none

spectrum.load.ssa-generic

Loads a spectrum or SED. The name refers to the fact that the metadata passed with this MType is based on the Simple Spectral Access protocol, but not on any particular version of it. The arguments are chosen such that it is convenient to use this MType for passing the results of an SSA query from an SSA client to a spectrum viewer (particularly to an SSA-capable spectrum viewer). However it is not necessary for SSA to be involved; SSA-like metadata may be faked and used to message loading of a spectrum from any source. In the latter case it is RECOMMENDED to provide at least the Access.Format entry in the meta map.

• Arguments:
  • url (string): URL of the spectrum to load
  • meta (map): Additional metadata describing the spectral data found at the URL. Key->Value pairs represent either Utypes or UCDs as defined or used in some version of the SSA specification or its predecessors. Example map keys are Access.Format (SSA 1.0 MIME type Utype) or VOX:Spectrum_Format (pre-1.0 SSA MIME type UCD). It is up to the recipient to make sense of these and, for instance, deal with the possibility that given expected keys are present or that apparently contradictory information is presented. Most existing SSA-aware spectrum viewing clients already contain this functionality.
  • spectrum-id (string) optional: Identifier which may be used to refer to the loaded spectrum in subsequent messages
  • name (string) optional: name which may be used to label the loaded spectrum in the application GUI
• Return Values: none

client.env.get

Returns the value of an environment variable present in the environment of the receiver client.

• Arguments:
  • name (string): environment variable name
• Return Values:
  • value (string): value of env variable "name" in receiver's environment

bibcode.load

Exchange a bibcode:

• Arguments:
  • bibcode (string, required) the bibcode to load
• Return Values:
  • none

voresource.loadlist (and subtypes)

Exchange a set of vo registry resources.

A registry resource is described by an xml document - a VOResource . Each registry resource is uniquely identified by a IVOID - a uri starting ivo://

• Subtypes: As well as the voresource.loadlist MType itself, which is appropriate for transmission of resources of any type, there are also specialised sub-MTypes for lists of particular resource types. Those currently defined are
  • voresource.loadlist.cone
  • voresource.loadlist.siap
  • voresource.loadlist.ssap
  • voresource.loadlist.tap
  • voresource.loadlist.vospace

• Arguments:
  • name: (string, optional) A descriptive name for this set of resources
  • ids: (required) A map of IVOID -> (optional) URL
    • The keys of this map are the IVO-identifiers of the voresources to load. The optional value associated with each key is an URL from which the XML of the voresource can be downloaded using a HTTP GET

• Return Values:
  • none

The URL values in the ids map are a convenience for receivers who may not possess a SOAP Registry client with which to retrieve the voresources themself. The URLs may also be useful in the case where the resource is only available in registry private to the sender, not in a registry known by the receiver.

However, the URL values are not mandatory, because to implement this, it may be necessary for the sender to create a local web-server - which is quite a demand for, say, a trivial script.

If the registry spec ever develops to provide a trival http / rest interface to resources, the URL values could link direct to this - but at the moment it's a work-around for the relative inaccessability of the registry SOAP interface.

coverage.load.moc.fits

Load a Multi-Order Coverage map in FITS format. MOCs and their FITS serialization are described in the MOC standard. FITS is the standard exchange format for MOCs - the introduction of alternative MOC load MTypes is not encouraged.

• Arguments:
  • url (string): URL of a FITS file containing the MOC to load
  • coverage-id (string) optional : identifier which may be used to refer to the loaded coverage specification in subsequent messages
  • name (string) optional : name which may be used to label the loaded coverage specification in the user interface

• Return values: none

---

Experimental Administrative MTypes

x-samp.query.by-meta

Queries which clients are currently registered with a given metadata value. A typical use would be to query which client(s) is currently registered with a given samp.name, so for instance you could find the client ID of a registered Aladin instance by calling this MType with key="samp.name" and value="Aladin". This is effectively a convenience method for interrogating the metadata currently available from the Hub, and so could typically be implemented by the Hub, but there is nothing to stop a client from implementing it too.

• Arguments:
  • key: (string, required) The metadata key of interest
  • value: (string, required) The value that key must have
• Return Values:
  • ids: (list of strings, required) A list containing the ID for each currently registered client whose metadata contains an entry with the given key and value (both treated case-sensitively). The list is empty if no such clients are registered.