[ 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.
2008 July 10 - Documentation written.
long numRecs
bool binary
string format
pointer( ) strLens
pointer( ) tagNames
pointer( ) tagTypes
pointer( ) data
argument struct data
Calls Filestream::format_strings
Adds a new line of formatted data to the end of the object's data structure.
argument int type
Return
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.
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.
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.
Structure definition. Specifies the contents of the IDL structure instantiated by the Filestream class. Used by Obj_New; do not invoke directly.
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.
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.
Return struct data
Returns a pointer to the object data member data.
Return string format
Returns the object data member format.
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.
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.
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.
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.
argument int index
keyword struct data
Calls Filestream::format_strings
Sets the row index in the objects Self.data structure to the structure passed in the argument 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.
argument string format
Sets the value of the object's format data member.
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.
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.
obj = Obj_New( 'Filestream' )
Obj_Destroy( obj )