Next Previous Up Contents
Next: Crossmatching
Up: Table Pipelines
Previous: Specifying a list of columns

5.4 Output Modes

This section lists the output modes which can be used as the value of the omode parameter of tpipe and other commands. Typically, having produced a result table by pipeline processing an input one, you will write it out by specifying omode=out (or not using the omode parameter at all - out is the default). However, you can do other things such as calculate statistics, display metadata, etc. In some of these cases, additional parameters are required. The different output modes are listed below.

mode=cgi
Writes a table to standard output in a way suitable for use as output from a CGI (Common Gateway Interface) program. This is very much like out mode but a short CGI header giving the MIME Content-Type is prepended to the output.

Additional parameters for this output mode are:

ofmt = <out-format>
Specifies the format in which the output table will be written (one of the ones in Section 4.2 - matching is case-insensitive and you can use just the first few letters). [Default: votable]

mode=count
Counts the number of rows and columns and writes the result to standard output.
mode=discard
Reads all the data in the table in sequential mode and discards it. May be useful in conjunction with the assert filter.
mode=meta
Prints the table metadata to standard output. The name and type etc of each column is tabulated, and table parameters are also shown. See the meta filter in Section 5.1 for more flexible output of table metadata.
mode=out
Writes a new table.

Additional parameters for this output mode are:

out = <out-table>
The location of the output table. This is usually a filename to write to. If it is equal to the special value "-" (the default) the output table will be written to standard output. [Default: -]
ofmt = <out-format>
Specifies the format in which the output table will be written (one of the ones in Section 4.2 - matching is case-insensitive and you can use just the first few letters). If it has the special value "(auto)" (the default), then the output filename will be examined to try to guess what sort of file is required usually by looking at the extension. If it's not obvious from the filename what output format is intended, an error will result. [Default: (auto)]

mode=plastic
Broadcasts the table to any registered Plastic-aware applications. PLASTIC, the PLatform for AStronomical Tool InterConnection, is a tool interoperability protocol. A Plastic hub must be running in order for this to work.

Additional parameters for this output mode are:

transport = string|file
Determines the method (PLASTIC message) used to perform the PLASTIC communication. The choices are
  • string: VOTable serialized as a string and passed as a call parameter (ivo://votech.org/votable/load). Not suitable for very large files.
  • file: VOTable written to a temporary file and the filename passed as a call parameter (ivo://votech.org/votable/loadFromURL). The file ought to be deleted once it has been loaded. Not suitable for inter-machine communication.
If no value is set (null) then a decision will be taken based on the apparent size of the table.
client = <app-name>
Gives the name of a PLASTIC listener application which is to receive the broadcast table. If a non-null value is given, then only the first registered application which reports its application name as that value will receive the message. If no value is supplied, the broadcast will be to all listening applications.

mode=stats
Calculates and displays univariate statistics for each of the numeric columns in the table. Mean, standard deviation, minimum, maximum and number of good rows are shown.
mode=topcat
Displays the output table directly in TOPCAT. If a TOPCAT instance (version 1.6 or later) is already running on the local host, the table will be opened in that, otherwise a new TOPCAT instance will be launched for display. The latter mode only works if the TOPCAT classes are on the class path. A variety of mechanisms (e.g. PLASTIC and SOAP) are attempted to transfer the table, depending on what running instances of TOPCAT can be found. Depending on the transport mechanism used, there may be limits to the size of table that can be transmitted to the application in this way.
mode=tosql
Writes a new table to an SQL database. You need the appropriate JDBC drivers and -Djdcb.drivers set as usual (see Section 3.4).

Additional parameters for this output mode are:

protocol = <jdbc-protocol>
The driver-specific sub-protocol specifier for the JDBC connection. For MySQL's Connector/J driver, this is mysql, and for PostgreSQL's driver it is postgres. For other drivers, you may have to consult the driver documentation.
host = <value>
The host which is acting as a database server. [Default: localhost]
database = <db-name>
The name of the database on the server into which the new table will be written.
newtable = <table-name>
The name of the new table which will be written to the database. If a table by this name already exists, it may be overwritten.
user = <username>
User name for the SQL connection to the database. [Default: mbt]
password = <passwd>
Password for the SQL connection to the database.


Next Previous Up Contents
Next: Crossmatching
Up: Table Pipelines
Previous: Specifying a list of columns

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note 256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk