Difference between revisions of "Solo: SoloParamHandle user data"

From Bcontrol
(New page: It can often be convenient to store data or flags with SoloParamHandles. For example, the Brody lab has an SQL database server, and we want to flag SoloParamHandles whose value should be s...)
 
Line 1: Line 1:
It can often be convenient to store data or flags with SoloParamHandles. For example, the Brody lab has an SQL database server, and we want to flag SoloParamHandles whose value should be saved in the server. Since this is a lab-specific use, we don't want to add a flag about this to the core SoloParamHandle structure. Instead, there is a "user data" field in SoloParamHandles that allows storing or retrieving in the SoloParamHandle whatever flags or data the user wants. Note that this user data is ''not'' saved with save_soloparamhandles.m
+
It can often be convenient to store data or flags with SoloParamHandles. For example, one particular lab, the Brody lab, has an SQL database server, and we want to flag SoloParamHandles whose value should be saved in the server. Since this is a lab-specific use, we don't want to add a flag about this to the core SoloParamHandle structure. Instead, there is a "user data" field in SoloParamHandles that allows storing or retrieving in the SoloParamHandle whatever flags or data the user wants. [Note that this user data is ''not'' saved with save_soloparamhandles.m.]
 +
 
 +
There are three methods of @SoloParamHandle objects that form the interface to the user data:
 +
 
 +
'''1) set_userdata.m'''
 +
<pre>
 +
% [sph] = set_userdata(sph, udata_field, udata_value)
 +
%
 +
% Use this to store data of your choice in a SoloParamHandle. Your user
 +
% data will *not* get saved when the SoloParamHandle is saved. No history
 +
% of the user data is accumulated or stored.
 +
%
 +
% SET_USERDATA(sph, udata_struct) erases any previous user data in
 +
%      SoloParamHandle sph, and sets it to udata_struct. This last,
 +
%      udata_struct, *must* be struct, even if it is an empty one.
 +
%
 +
% SET_USERDATA(sph, udata_field, udata_value), where udata_field is a
 +
%      string, erases only the previous value of the field named
 +
%      udata_field in the user data, replacing it with the new value
 +
%      udata_value. If no field of the right name existed already, then the
 +
%      field is created.
 +
%
 +
% Returns the SoloParamHandle.
 +
</pre>
 +
 
 +
'''2) get_userdata.m'''
 +
<pre>
 +
% [o] = get_userdata(sph, [udata_field])
 +
%
 +
% If called with no arguments, returns a struct that is the user data for
 +
% SoloParamHandle sph. The default value is an empty struct.
 +
%
 +
% If called with one argument, that argument must be a string; if the user
 +
% data struct has a field with name udata_field, then its value is
 +
% returned. If no such field is found, an error will occur.
 +
%
 +
</pre>
 +
 
 +
'''3) has_userdata_field.m'''
 +
<pre>
 +
% [t] = has_userdata_field(sph, fieldname)
 +
%
 +
% Returns TRUE if SoloParamHandle sph has a field called fieldname, FALSE
 +
% otherwise.
 +
</pre>

Revision as of 01:13, 18 March 2009

It can often be convenient to store data or flags with SoloParamHandles. For example, one particular lab, the Brody lab, has an SQL database server, and we want to flag SoloParamHandles whose value should be saved in the server. Since this is a lab-specific use, we don't want to add a flag about this to the core SoloParamHandle structure. Instead, there is a "user data" field in SoloParamHandles that allows storing or retrieving in the SoloParamHandle whatever flags or data the user wants. [Note that this user data is not saved with save_soloparamhandles.m.]

There are three methods of @SoloParamHandle objects that form the interface to the user data:

1) set_userdata.m

% [sph] = set_userdata(sph, udata_field, udata_value)
%
% Use this to store data of your choice in a SoloParamHandle. Your user
% data will *not* get saved when the SoloParamHandle is saved. No history
% of the user data is accumulated or stored.
%
% SET_USERDATA(sph, udata_struct) erases any previous user data in
%      SoloParamHandle sph, and sets it to udata_struct. This last,
%      udata_struct, *must* be struct, even if it is an empty one.
%
% SET_USERDATA(sph, udata_field, udata_value), where udata_field is a
%      string, erases only the previous value of the field named
%      udata_field in the user data, replacing it with the new value
%      udata_value. If no field of the right name existed already, then the
%      field is created.
%
% Returns the SoloParamHandle.

2) get_userdata.m

% [o] = get_userdata(sph, [udata_field])
%
% If called with no arguments, returns a struct that is the user data for
% SoloParamHandle sph. The default value is an empty struct.
%
% If called with one argument, that argument must be a string; if the user
% data struct has a field with name udata_field, then its value is
% returned. If no such field is found, an error will occur.
%

3) has_userdata_field.m

% [t] = has_userdata_field(sph, fieldname)
%
% Returns TRUE if SoloParamHandle sph has a field called fieldname, FALSE
% otherwise.