<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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.

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

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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

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

bibcode.load

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

voresource.loadlist (and subtypes)

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

• 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

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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.

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

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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

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

bibcode.load

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

voresource.loadlist (and subtypes)

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.

Experimental Administrative MTypes

x-samp.query.by-meta

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

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:

Process

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

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

table.highlight.row

table.select.rowList

image.load.fits

coord.pointAt.sky

spectrum.load.ssa-generic

client.env.get

bibcode.load

voresource.loadlist (and subtypes)

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

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.

Experimental Administrative MTypes

x-samp.query.by-meta

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.

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

• 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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

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

bibcode.load

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

voresource.loadlist (and subtypes)

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.

Experimental Administrative MTypes

x-samp.query.by-meta

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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:

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

• 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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

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

bibcode.load

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

voresource.loadlist (and subtypes)

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.

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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

• 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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

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

bibcode.load

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

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

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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

• 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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

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

bibcode.load

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

voresource.loadlist

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

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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

• 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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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

• 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

• 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

• 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

• 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

• 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

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

spectrum.load.ssa-generic

• 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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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

• 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

• 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

• 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

• 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

• 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

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

• Return Values: none

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

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.

Application MTypes

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

table.load.votable

• 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

• 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

• 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

• 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

• 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

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

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

Introduction

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

• 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

• 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

• 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

• 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

• 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

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

table.load.votable

• 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

• 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

• 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

• 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

• 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

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

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

This page lists MTypes currently in use by applications which implement SAMP (beyond that small number of administrative MTypes currently defined in the SAMP document). It may at some point be formalised into an IVOA Note.

The items listed here are a work in progress, and may be revised, replaced or removed in the future. Discussion of the content on this page is best done on the apps-samp mailing list.

Application domain MTypes

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

table.load.votable

• 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

• 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

• 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

• 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

• 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

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

Administrative MTypes

The following MTypes are ones which have been proposed for addition to the SAMP standard as administrative MTypes. If people agree, they will be added to the next version of the SAMP draft.

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

This page lists MTypes currently in use by applications which implement SAMP (beyond that small number of administrative MTypes currently defined in the SAMP document). It may at some point be formalised into an IVOA Note.

The items listed here are a work in progress, and may be revised, replaced or removed in the future. Discussion of the content on this page is best done on the apps-samp mailing list.

Application domain MTypes

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

table.load.votable

• 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

• Return Values: none

table.load.fits

• 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

• Return Values: none

table.highlight.row

• 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

• 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

• 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

• Return Values: none

coord.pointAt.sky

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

Administrative MTypes

The following MTypes are ones which have been proposed for addition to the SAMP standard as administrative MTypes. If people agree, they will be added to the next version of the SAMP draft.

samp.hub.disconnect

• Arguments:
  • reason (string) optional: short message indicating the reason that the disconnection is being forced
• Return Values: none

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

This page lists MTypes currently in use by applications which implement SAMP (beyond that small number of administrative MTypes currently defined in the SAMP document). It may at some point be formalised into an IVOA Note.

The items listed here are a work in progress, and may be revised, replaced or removed in the future. Discussion of the content on this page is best done on the apps-samp mailing list.

Application domain MTypes

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

table.load.votable

• 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
• Return Values: none

table.load.fits

• 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
• Return Values: none

table.highlight.row

• 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

• 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

• 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

• Return Values: none

Administrative MTypes

The following MTypes are ones which have been proposed for addition to the SAMP standard as administrative MTypes. If people agree, they will be added to the next version of the SAMP draft.

samp.hub.disconnect

• Arguments:
  • reason (string) optional: short message indicating the reason that the disconnection is being forced
• Return Values: none

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

• 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
• Return Values: none

• 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
• Return Values: none

• 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

• Arguments:

• Return Values: none

• 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
• Return Values: none

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

The items listed here are a work in progress, and may be revised, replaced or removed in the future. Discussion of the content on this page is best done on the apps-samp mailing list.

table.load.votable

• 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
• Return Values: none

table.load.fits

• 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
• Return Values: none

table.highlight.row

• 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

• Arguments:
  • table-id (string):
  • url (string):
  • row-list (list of SAMP int):
• Return Values: none

image.load.fits

• 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
• Return Values: none

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->

SAMP MTypes

This page lists MTypes currently in use by applications which implement SAMP (beyond that small number of administrative MTypes defined in the SAMP document). It may at some point be formalised into an IVOA Note.

The items listed here are a work in progress, and may be revised, replaced or removed in the future. Discussion of the content on this page is best done on the apps-samp mailing list.

table.load.votable

• 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
• Return Values: none

table.load.fits

• 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
• Return Values: none

table.highlight.row

• 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

• Arguments:
  • table-id (string):
  • url (string):
  • row-list (list of SAMP int):
• Return Values: none

image.load.fits

• 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
• Return Values: none