AST_MOCCHAN

Create a MocChan

Description:

This function creates a new MocChan and optionally initialises its attributes.

A MocChan is a specialised form of Channel which supports the reading and writing of AST Moc objects as text, using the conventions of the JSON and string encodings described in the IVOA’ s MOC recommendation, version 1.1. Writing a Moc to a MocChan (using AST_WRITE) will, if the Moc is suitable, generate a textual description of that Moc, and reading from a MocChan will create a new Moc from its textual description. See the Moc class for further information.

Normally, when you use a MocChan, you should provide " source" and " sink" routines which connect it to an external data store by reading and writing the resulting text. These routines should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such routines are supplied, a Channel will read from standard input and write to standard output.

Alternatively, a MocChan can be told to read or write from specific text files using the SinkFile and SourceFile attributes, in which case no sink or source function need be supplied.

Invocation

RESULT = AST_MOCCHAN( SOURCE, SINK, OPTIONS, STATUS )

Arguments

SOURCE = SUBROUTINE (Given)
A source routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SourceFile attribute, this routine will be used by the MocChan to obtain lines of input text. On each invocation, it should read the next input line from some external 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, and no value has been set for the SourceFile attribute, the MocChan will read from standard input instead.

SINK = SUBROUTINE (Given)
A sink routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SinkFile attribute, this routine will be used by the MocChan 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 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, and no value has been set for the SinkFile attribute, the MocChan 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 MocChan. The syntax used is identical to that for the AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value

AST_MOCCHAN = INTEGER
A pointer to the new MocChan.

Notes:

Copyright (C) 2021 East Asian Observatory