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) three 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. Proposals for new administrative MTypes may however be discussed here for introduction in future versions of the Standard.

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.

---

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.

• 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.fits

Loads a table in FITS format.

• Arguments:
  • url (string): URL of the FITS file 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.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