next up previous 264
Next: AST_ZOOMMAP - Create a ZoomMap
Up: AST Routine Descriptions
Previous: AST_WRITE - Write an Object to a Channel


AST_XMLCHAN - Create an XmlChan

Description:
This function creates a new XmlChan and optionally initialises its attributes.

A XmlChan is a specialised form of Channel which supports XML I/O operations. Writing an Object to an XmlChan (using AST_WRITE) will, if the Object is suitable, generate an XML description of that Object, and reading from an XmlChan will create a new Object from its XML description.

Normally, when you use an XmlChan, you should provide "source" and "sink" routines which connect it to an external data store by reading and writing the resulting XML text. By default, however, a Channel will read from standard input and write to standard output.

Invocation:
RESULT = AST_XMLCHAN( SOURCE, SINK, OPTIONS, STATUS )
Arguments:
SOURCE = SUBROUTINE (Given)
A source routine, which is a subroutine which takes a single integer error status argument. This routine will be used by the XmlChan to obtain lines of input text. On each invocation, it should read the next input line from some external XML data store, and then return the resulting text to the AST library by calling AST_PUTLINE. It should supply a negative line length when there are no more lines to read. If an error occurs, it should set its own error status argument to an error value before returning.

If the null routine AST_NULL is suppied as the SOURCE value, the Channel will read from standard input instead.

SINK = SUBROUTINE (Given)
A sink routine, which is a subroutine which takes a single integer error status argument. This routine will be used by the XmlChan to deliver lines of output text. On each invocation, it should obtain the next output line from the AST library by calling AST_GETLINE, and then deliver the resulting text to some external XML data store. If an error occurs, it should set its own error status argument to an error value before returning.

If the null routine AST_NULL is suppied as the SINK value, the Channel will write to standard output instead.

OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new XmlChan. The syntax used is identical to that for the AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_XMLCHAN = INTEGER
A pointer to the new XmlChan.
Notes:
  • The names of the routines supplied for the SOURCE and SINK arguments should appear in EXTERNAL statements in the Fortran routine which invokes AST_XMLCHAN. However, this is not generally necessary for the null routine AST_NULL (so long as the AST_PAR include file has been used).

  • If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST.

  • A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

  • Note that the null routine AST_NULL (one underscore) is different to AST__NULL (two underscores), which is the null Object pointer.


next up previous 264
Next: AST_ZOOMMAP - Create a ZoomMap
Up: AST Routine Descriptions
Previous: AST_WRITE - Write an Object to a Channel

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council