The Solar-Stellar Spectrograph

[ Home | About | Tech Info & Data | Publications | References ]      [ Site by Jeffrey Hall | Research funded by NSF ]



The Filestream class is a file I/O class. It inherits Filelink.

This class is designed to encapsulate reading and writing of text files with rows containing data in various data types and formats. It was designed specifically for input and output of SSS observing log files and data reduction diagnostic files, but should be usable for an arbitrary ASCII or binary data file.

This class works by creating and performing I/O on IDL structures defined by the data members. numRecs specifies the number of records in the file (and, analogously, the number of rows in the structure). (The class can also read files of unknown length, dynamically setting numRecs when it hits the end of the file.) The tagNames and tagTypes data members are arrays specifying the properties of the structure tags. The types are represented by integers corresponding to the various IDL data types; see the create_datum description for details. The strLens data member is an integer array matching the tagNames and tagTypes; for any tag that is a string, the strLens member should contain the length of the string. Finally, the class can be made to work with binary or ASCII data via the boolean binary data member.

Version History

2008 July 10 - Documentation written.


Data Members

long numRecs

bool binary

string format

pointer( ) strLens

pointer( ) tagNames

pointer( ) tagTypes

pointer( ) data


Method List


create_datum( )





format_strings( )

get_data( )

get_format( )

get_strlens( )

init( )

is_valid( )

read( )








write( )


Method Descriptions


PRO add_tail

argument struct data

Calls Filestream::format_strings

Adds a new line of formatted data to the end of the object's data structure.


FUNCTION create_datum

argument int type

Return datum

Returns a variable with data type depending on the value of the type argument: 1 = byte, 2 = int, 3 = long, 4 = float, 5 = double, 7 = string, 12 = unsigned int. Any other value of type returns an int. Do not call this function directly; it is used by the object to generate formatted structures.


PRO cleanup

Calls Filelink::cleanup

Destructor. Clears its history list by calling Filelink::cleanup. It then frees all pointers associated with its data members. Never call this procedure directly; it is invoked by IDL's Obj_Destroy function.


PRO crop_data

argument int first

argument int last

Crops the set of rows of data in the data member structure to [ first, last ]. Numbering of rows is zero-relative.


PRO define

Structure definition. Specifies the contents of the IDL structure instantiated by the Filestream class. Used by Obj_New; do not invoke directly.


PRO dump_stat

Calls Filelink::dump_stat

This is a standard OIL class method. It dumps the current state of the object's data members, followed by those of the Filelink object, to the command output window. The dump will look best if the output font is fixed rather than proportional width.


FUNCTION format_strings

argument struct data

Return bool TRUE, FALSE

Sets the lengths of the strings specified for the data structure. For any column for which the type tag is 7 (string), the corresponding data element of the structure is set to the corresponding element of the strLen data member. Do not call this function directly; it is used by the object to generate formatted structures.


FUNCTION get_data

Return struct data

Returns a pointer to the object data member data.


FUNCTION get_format

Return string format

Returns the object data member format.


FUNCTION get_strlens

Return int[ ] strLens

Returns the object data member strLens. (Note this gets the array of lengths themselves, not a pointer.)



keyword int numRecs

keyword bool binary

keyword int[ ] strLens

keyword string[ ] tagNames

keyword int[ ] tagTypes

keyword struct _EXTRA

Calls Filestream::reset_data, Root::add_history

Return bool TRUE

Constructor. The keywords are used if you wish to specify initial values for the data members. If they are not set, the following defaults are used: the data array is set to contain one record (row), the data are assumed to be binary (binary = TRUE), and the format string is set til NULL. If the keywords for tagNames and tagTypes are not set, the data structure will be a null pointer. Never call this function directly; it is invoked by IDL's Obj_New function.


FUNCTION is_valid

Calls Root::add_history, Filelink::is_valid

Return long[3] valid

Each OIL class has an is_valid function that performs class-specific tests on its data members. If all members are found to be valid, however validity is defined for that class, this funtion returns 1. Otherwise, a negative number is returned that contains a bitwise combination of all errors detected. In the case of Filestream, the error codes are: -1 (tagNames is invalid), -2 (tagTypes is invalid), -4 (data is invalid), -8 (numRecs is zero or less), and -16 (binary is not Boolean). The Filelink override of this function returns a two-element array of longs, the first element containing the validity state of the Root, and the second that of the Filelink. An event is written to the log if the Filelink is invalid.



keyword bool lengthUnknown

Calls Filelink::open_datafile, Root::add_history

Return bool TRUE, FALSE

Reads formatted data from a file into the object. Set the lengthUnknown keyword if you do not know how many records are in the file.


PRO reset_all

argument string id

argument string format

argument string[ ] tagNames

argument long[ ] tagTypes

argument int numRecs

Calls Filestream::set_format, Filestream::reset_data, Filelink::set_datafile

Resets the entire object with a new file name, format string, tag names, tag data types, and number of records.


PRO reset_data

argument string[ ] tagNames

argument long[ ] tagTypes

keyword int[ ] strLens

keyword int[ ] numRecs

Calls Filestream::create_datum, Filestream::format_strings, Root::add_history

Creates a new, empty data structure based on the values in the object's data members. The structure is created with tags named per the values of tagNames, and with data types specified by tagTypes via calls to create_datum. The structure will have numRecs rows.


PRO set_at

argument int index

keyword struct data

Calls Filestream::format_strings

Sets the row index in the objects structure to the structure passed in the argument data.


PRO set_data

argument string format

Sets the value of the object's data structure data member. The pointer to the existing structure is freed, and a new pointer to structure data created.


PRO set_format

argument string format

Sets the value of the object's format data member.


PRO set_iotype

argument string ioType

Calls Root::add_history

Sets the value of the object's binary data member. If ioType is 'ascii', then binary is set to FALSE. If ioType is 'binary', then binary is set to TRUE.


PRO set_strlens

argument int[ ] strLens

Sets the value of the object's strLens array data member.



keyword bool a

Calls Filelink::open_datafile, Root::add_history

Return bool TRUE, FALSE

Writes formatted data to a file. Set the an keyword to open the file in append mode; otherwise, the file is opened in write mode.



Sample Usage

obj = Obj_New( 'Filestream' )

Obj_Destroy( obj )


[Back to contents]

Supported by grants from the National Science Foundation.
[ Back to my home page | Email me: jch [at] lowell [dot] edu ]
The SSS is publicly funded. Unless explicitly noted otherwise, everything on this site is in the public domain.
If you use or quote our results or images, we appreciate an acknowledgment.
This site is best viewed with Mozilla Firefox.