NAME

auxin, auxout, auxinout, auxscr,auxsockout,copy_history - returns I/O pointer to auxiliary data file


SYNOPSIS

        From C:
        #include <seplib.h>
        FILE *auxin(tag)
        FILE *auxtmp(tag);
        FILE *auxout(tag)
        FILE *auxinout(tag)
        FILE *auxsockout(tag)
        FILE *auxscr(tag)
        void copy_history( intag, outtag )
        char *tag, *intag, *outtag;
        From Fortran:
        integer auxin(tag)
        integer auxout(tag)
        integer auxinout(tag)
        integer auxsockout(tag)
        integer auxscr(tag)
        integer auxtmp(tag)
        integer copy_history(intag,outtag)


DESCRIPTION

These routines open an auxillary seplib dataset for input, output, or both. For historical reasons they return a stream pointer (or a file descriptor for Fortran users). These return values should not be used for I/O. Always use the tag name to read and write data. The return values should only be used to check for errors.

For auxin() the location of this data is determined by a line ``in=filename'' in the auxiliary input history. The history is in turn located according the following priorities: Look for 'tag=history' on the command line. Look for 'tag=history' on standard input. Look for the file `tag' in the current directory.

For auxout(), an output history is created and initialized as necessary. The default name `tag' of this output history may be overrrided by specifying `tag=history' on the command line. If the output history already exists it will be overwritten. The location of the data file is constructed automatically following rules similar to those used by output(). If the file exists it will be truncated to zero length before starting output.

For auxinout(), the history file will be searched for using the same rules as auxin and appended to if it exists. If the history already exists, the data file it points at will be reused. If you wish to append to the end of that file you should seek to the end before writing. If the history file doesn't exist the history file and data file will be created as for auxout. The call to auxinout() must be the first use of the tag in your program. Any other call will implicity open the dataset as either an input or output dataset.

copy_history() is used to copy the input history from the stream defined by tagin to the stream defined by tagout.


EXAMPLE

        A binary file "elevations" has been generated for a 
        seismic section. The history, say Helev, describing it 
        would contain
                in="elevations"
                ne=120 units=feet datum=250
        A program written to use these elevations would be invoked
                <Hin Prog elev=Helev >Hout
        and the source for Prog might contain code such as
                auxpar("ne","d",&ne,"elev");
                auxpar("esize","d",&esize,"elev");
                auxpar("units","s",units,"elev");
                auxpar("datum","f",&datum,"elev");
                sreed("elev",elevations,ne*esize)
                for(i=0; i<ne; ++i) elevations[i] -= datum;


DIAGNOSTICS

        Calls to auxin()/auxout()/auxinout()/auxsockout()/auxscr() from C return 
        NULL if there is no auxiliary history or data whilst
        the fortran routine returns -1 in the same situation.
        Other errors will cause program termination with a
        suitable message.


SEE ALSO

        L<auxclose>, L<auxpar>, L<auxputch>, input, L<sreed>, L<srite>, 
        L<sseek>


BUGS

        Don't forget to declare auxin an integer in Fortran 
        and Ratfor programs.


KEYWORDS

auxillary dataset input output


LIBRARY

sep