Data is requested THROUGH a particular connection (signal_data) by using the "request_data:" message. (Typically, all this is invisible to the user at the script level). A downstream object (ie, a display or computation object) requests data from its signal_in, and the request is then propagated back through the pipeline to the reader, which reads the data.
A sub-class writer must supply a generate_data: method, and can use the one in signal_file_reader as a template. The sub-class writer is also responsible to assure that the "sample_rate" is correct for the file data (either that information is contained in a file header which is parsed during a "read!", or the user is required to set it at the script level). The subclass writer must supply an "available_channels?" method to return an ordered list of channel numbers (1 - number_of_channels). How the subclass determines the number of available channels is also the resposibility of the subclass writer. If the sub-class requires special initialization, the "read!" should be over-ridden and initialization should be done there.
There are also features for associating text labels and objects with each channel of signal data, which will be passed along with the data for use by downstream objects.
file_object Internally created object for the filename. It is used for searching for the file, and for determining its type.
error Set to non-zero if an error occurs (bad filename, etc.) The user should also set this when an error occurs in a subclass method.
connection_number Set by "@" to specify which connection to refer to in subsequent messages.
sample_rate Number of samples per second. This must be specified to access correct time slices. Default is 1.
total_number_of_samples How many samples in the file. Superclass ignores this, but most subclasses will use it to prevent attempts to read past EOF.
reread When set, a "read!" will be performed prior to servicing the next data request. Subclasses can use this to force a read! when certain instance variables are updated.
channel_number Used to access particular channels for setting/getting labels and objects.
@ value Set connection number. Does not send a "modify!" to instance. Same as "connection_number=".
ch_no= value Set channel number. Does not send a "modify!" to instance. Same as channel_number=.
channel_number= value Set channel number. Does not send a "modify!" to instance.
channel_number? Get the current value of channel_number.
close! Closes the file.
connection? Returns the name of the connection (signal_data object) at "connection_number". In this way, multiple downstream objects (signal_filters, etc.) may share a single connection, which is desirable if they are access data from the same time region. If connection_number is equal to (no_connections? + 1), a new connection is created (see "new_connection?"), otherwise, an error is returned.
connection_number= value Set connection number. Does not send a "modify!" to instance.
connection_number? Get the current value of connection_number.
does_not_understand Any messages that the instance does not understand are forwarded to the connection at "connection_number". If it is a message that the "signal_data" connection also doesn't understand, and error message is printed and OBJECT_ERROR is returned.
error= value Set error to value.
error? Get the value of error.
filename= name Sets filename to name. "name" may be either a full pathname, or simply a filename. If the full path is not specified, the user's LYMB_PATH will be searched for the file.
filename? Get the value of filename.
generate_data: start_packet, end_packet, start_index This method must be supplied by the subclass to produce (read) the data specified. This method should NOT be called directly from the shell or another object. See "signal_file_reader" for an example of a generate_data: method.
label= channel_label Set the label at "channel_number" to the string "channel_label".
label? Get the channel label at "channel_number".
labels= channel_label_list Set the channel label to the list of labels in channel_label_list.
labels? Get the list of channel labels.
object= channel_object_name Set the object at "channel_number" to the "channel_object_name".
objects? Get the channel object name at "channel_number". Warning: be sure to quote `object' from the shell or script when asking to print it, since `object' is a lymb class name :-) ie, "my_reader print: `object'; '. This is a `feature' of the parser, and all arguments to the print: method should be quoted lest they conflict with an existing object or class name.
objects= channel_object_list Set the channel object to the list of objects in
channel_object_list.
objects? Get the list of channel objects.
new_connection? Creates a new connection (signal_data object) at (no_connections? + 1), increments "no_connections" and returns the name of the created connection. Use this to "connect" to the reader. See also "connection?".
no_connections? Returns the number of current connections (signal_data objects).
open! Opens the file specified by filename. Will automatically be done if the file is not open and data is requested.
read! Causes the file to be opened and the instance to be initialized (if needed). Will be peformed automatically if "reread" is non-zero, which happens if no read! has yet been performed, or if "filename" changes, or if an "open!" has not yet been done. "read!" will not be done just because the instance is modified - if modifying a particular instance variable should require that "read!" be performed again, the set-method for the variable should set "reread" to non-zero.
recomputing_mtime? Returns the modified time of the instance. Before requesting data, the pipeline terminus is expected to send a recomputing_mtime? to its signal_in. This gets propagated all the way back up to the start of the pipeline (this reader). If any object in the pipeline has been modified, each object knows that it's cached data is no longer up to date, so the entire cache must be regenerated on the next "request_data:".
request_data:( start_time, end_time, start_index, requestor_name) This message is sent by the connection objects (signal_data). Specifying the time range needed,
and the index into the signal_data channel caches. The requestor also sends its name so the filter knows which of its connections is requesting data. This should not be called directly from the shell or another object, but only through a connection.
requestor= When a signal_data (a connection) is asked for its "available_channels?", it forwards the method to its parent. This method propagates back to the reader. However, some readers have multiple "kinds" of signal output, and each kind may have a different set of available channels. The reader has no way of knowing who sent such a message, so the signal_data is required to first send a "requestor=" in case the reader needs to differentiate between pipelines.
reread= value Set reread to value. Setting to non-zero will force a read! to be sent prior to next data request.
reread? Get the value of reread.
sample_rate= value Set sample_rate to value.
sample_rate? Get the value of sample_rate.
shell_request_data:( start_time, end_time) Same as request_data, except without the "index" and "requestor" arguments. However, this first sends a "recomputing_mtime?" to the connection at "connection_number" which makes sure the cache is up to date. It then sends a "request_data:" to that connection with itself as requestor so that the proper protocol is used. A subsequent output! will print that connection's data. This alleviates the user at the shell or script level from first having to get the name of the connection, and then sending a recomputing_mtime? and request_data: to that connection.
total_number_of_samples= value Set total_number_of_samples to value.
total_number_of_samples? Get the value of total_number_of_samples.