This is a copy of the help text for the Action control on the front panel of any driver. That ChannelsAction.ctl control is the definitive place for information. This information here is correct as of 9th February 2004.
Error in/out always used. Skips routine if error in contains error.
Channel and Action must always be set.
'Number(s) to be written' is an array, usually only first element used, except eg for 'Set parameters'. 'Result(s) (number)' is also an array. Usually only the first element is used.
Register vi: asks vi to list the sources and reading channel numbers it handles. 'Channel number'=0. All such vi's should be in the Channels directory. The lists should be returned in 'Result (string)', starting with source numbers separated by commas, any of which may be a range (two numbers separated by a hyphen); then there should be a semicolon (;) and another list of sources that can only be read. The semicolon must always be used (if not, channels are assumed to be reading channels). Source numbers should lie in the range(s) allocated for sources, and should include the read-back version and one that just uses the computer's copy of the output value (for speed). Put an "r" followed by another channel number to specify which channel is the "read-back" equivalent of this channel (for a range, specify the number of the first "read-back" channel, and the others will be taken to follow on consecutively) - i.e. reading this channel just gives the number stored in the computer, whereas reading the "read-back" channel refers to the same source but actually reads back from the source (this information is vital when starting a sweep when the program has just started). Put the read-back channels in the list too, unless (as is conceivably possible) they are handled by a different driver vi. If a source is not followed by an r, then it is assumed to read back from the instrument. It is up to each routine to decide which to use for which channel numbers, but they should stick to the conventions laid down, e.g. that read-back channels are 100 greater than ordinary sources. Set 'Result(s) (number)'={0}. Put a "t" before each number or range that has trigger flags that need resetting by calling "Trigger flags". eg "1r101,3-5r103,101,t103-105;91,t93-95". Of course, non-read-back channels should not need a "t" since they just read the computer's copy of the value.
Initialise: inits channel, sending init string etc. No output. It can assume that element 'Channel number' of ChannelsInfo.vi's global array Ch Inited is later set to True. It should set elements for other linked channels itself to avoid initialising an instrument twice.
Bye: sends finishing string, sets channel back to local etc. No output. It can assume that element 'Channel number' of ChannelsInfo.vi's global array Ch Inited is later set to False. It should set elements for other linked channels itself.
Trigger: initialise flags: cancels any response from last trigger. No output. The driver will be called with this Action code at the start of each new source/measure cycle (i.e. for each data point). Use it to reset any flags the driver keeps about the trigger state of the instrument - some instruments (eg source-measure units) can need two (identical) triggers, one to source and one to measure. Giving an extra one gets the whole sequence out of step, and will often cause timeouts. So the driver should keep a flag of which level the trigger state is at, e.g. 0=not triggered, 1=triggered to write, 2=triggered to read. (These triggers may have been sent by different channels number that the driver uses for source and measuring.) An additional complication is that usually such instruments return one string, that has both the sourced and measured values in it, and this string can only be read once. When this string is returned (in the Read or Read quickly actions), store it in a variable ('Latest reading', say). Reset 'Latest reading' to an empty string and the trigger flag to 0 when the action 'Trigger: initialise flags' is called. Also set the trigger flag back to zero when the string is read successfully from the instrument, at the same time as setting 'Latest reading' to this string, so that the driver can distinguish each stage of the process and will not trigger extra times. When 'Trigger to write' is called, if the trigger flag<1, trigger to write and set the trigger flag to 1. When 'Trigger to read' is called, if the trigger flag<2, trigger to read and set the trigger flag to 2. In 'Read' and 'Read quickly', if 'Latest reading'<>"" then take the value required for the current channel from it, otherwise read it from the instrument. If in 'Read quickly' the read times out before the instrument is ready, obviously do not set 'Latest reading' - only set it when the string is actually read. in 'Read', it should not time out, so 'Latest reading' should always be set. As mentioned above, set the trigger flag=0 when the string has been read.
Trigger to write: triggers source to output the value already sent using the Action 'write number'. No output. See 'trigger: initialise flags' for information about trigger flags. 'result (string)' is <>"" if the compliance limit is reached (though this may already have occurred if writing itself causes the value to be output, rather than once 'trigger to write' is used; thus 'write number' can also return this condition).
Trigger to read: triggers the channel to measure. For many instruments this does not send an actual trigger command to the instrument, but sends the command(s) that ask it to output its value(s) to the computer. This will not be read until the 'Read' or 'Read quickly' action is called later. This action returns no output. See 'trigger: initialise flags' for information about trigger flags.
Write number: sets source channel to 'number to be written'. Does not trigger channel to source it. 'Result(s) (number)' is set to output value, rounded to step size if known without reading back from instrument. 'result (string)' is <>"" if the compliance limit is reached (though this will not occur yet if writing does not itself cause the value to be output, because that only happens once 'trigger to write' is used; thus 'trigger to write' can also return this condition).
Write string: sends 'string to be written' to channel. If first element of 'number to be written'=1, do not read back any response, else if =0 (or anything else), should read back any response quickly (eg using 'Flush input.vi'), in which case set 'Result(s) (number)'=1 to indicate it has done so, and set 'result (string)' to any output. Older or simpler drivers can leave it up to the main program to do so instead.
Write bulk data: writes set of data (eg oscillosope trace) as a 1D array 'Number(s) to be written', consisting of columns one after another. 'String to be written' has number of columns,other parameters, if any.
Read: assumes channel already triggered to read (see above); returns the value of this channel (by reading appropriate information from instrument, waiting until it is ready). Output is an array of numbers (usually only one element). Reading a non-read-back source should use the computer's copy (in ChannelsInfo.vi's global variable Channel Array[channel number]).
Read quickly: assumes already triggered to read (see above); returns the value of this channel (by reading appropraite information from instrument) if it is ready, else returns (first) output=sillynum (from GlobalCluster.vi). Driver should choose a time constant that is long enough to ensure that available data is read, but as short as possible to give the main program time to do other things if the data is not yet available. Output is an array of numbers (usually only one element).
Read string: reads string from channel, waiting until it is ready. Output is string. Input string is blank. This action may be used to extract some useful info from the instrument. The input value (as an integer) indicates what to read. input (number) =1 returns the identification string of the instrument if available (eg from "*IDN?" on GPIB), or else some suitable identifying text the driver generates. Other values of input (number): 0 is the usual; -1 means the timeout has been set very short, so do not change the timeout, or else set it to a sensible short value; the rest are unassigned: values are unassigned: values<-1 are reserved for general use in the future; the meaning of values >1 may be chosen (and documented) by the writer of the driver. ONLY the specified cases should be handled. In other cases a blank string should be returned (by connecting input string to output).
Read bulk data: reads set of data (eg oscilloscope trace). The data is returned in the usual one-dimensional array array 'Result(s) (number)', but the first element is the number of columns being provided, the second element is the type: 1 means the array consists of complete rows one after another, whereas 3 means it contains complete columns one after the other [one or other may be faster for your method of taking data, so use it]. The rest of the array is the data itself, reshaped into the 1D array as just described. See DemoChannels.vi in the Channels directory for an example of how to do this.
Read parameter names: 'Result (string)' contains firstly a name for the section of the configuration file in which this channel's parameters are to be stored [leave blank to use the vi name; you can use one section for more than one channel or even for different driver vis, but the parameter names within the section must not conflict; the name may include the channel number, but it is best to avoid this in case the channel number is changed in the driver at some stage]. This name is terminated by a line feed (LF, the usual end-of-line character in a multiline string), and is followed by the names of the parameters for channel, with names EXACTLY as expected by 'set parameters' above; each is separated by LF. String and numeric parameters may be specified in any order, but the corresponding entry for string parameters in 'Result(s) (number)' must specify 0 elements (see Read parameters action, below). The first three or four string parameters should usually be Address, Initialisation string, and Finishing string, (and Instrument type if appropriate) but only for the main channel that uses these [Address may alternatively, but more limitingly, be numeric]. These names are used, e.g., in the global configuration window and in the configuration file. The initialisation string is the string sent to instrument when initialised (in the Initialise action). The finishing string is the string sent to the instrument when a run ends (in the Bye action).
Read parameters: reads any parameters for channel, as 'set parameters' above. 'Result(s) (number)' has a list (array) of ALL parameters: each parameter can have more than one number (but usually just one, or zero if the parameter is a string). To provide this flexibility, the array consists of sets of values, one set for each string or numeric parameter; the first number in a set is the NUMBER of numbers for that parameter (e.g. 0 for a string parameter, in which case the current line of 'Result (string)' is used, or 1 for single numeric parameters), and the rest of the set is that many numbers. 'Result (string)' has a list of string parameters ONLY, separated by line-feeds. Note that the numeric array lists ALL parameters, but the lines of the string are only for string parameters. Note that the driver should only respond to parameter requests for ONE channel for each parameter (the only exception is that non-read-back sources are automatically suppressed so there is no need for the driver to suppress them).
Set parameters: sets ONE parameter for channel, eg autoranging flags, units, etc. 'String to be written' starts with a line which is the parameter name (which identifies which parameter is being set), terminated by a line feed (LF); the rest of the string is the parameter if this is a string parameter. 'Number(s) to be written' has an array which is the parameter(s) if this is a numeric parameter. There is one special parameter name, "Runtime", which must not appear in the list of parameter names, since it should not be stored in the configuration file. Its use is for setting parameters during a run, e.g. with the header command a channel,par1,par2[,type]["string par"], or using the configuration/instrument control window. 'Number(s) to be written' is an array: the first element is the "type" of the command (default 0); the second and third are par1 and par2 respectively. 'String to be written' is 'string par' if relevant. It is up to the driver to interpret these parameters as most appropriate. For lockins and other instruments that autorange, for type=0, par1 controls whether autoranging occurs immediately (so this action contacts the instrument), and par2 controls autoranging later, i.e. while taking data.
Reset instrument: resets instrument, e.g. by sending Selected Device Clear to it. This is only used when the user specifically requests it. The instrument driver should set all the relevant items in the array Ch Inited to false.
Other operations: carries out some other operations, perhaps specific to each channel vi. Operation number is 0th element of 'Number(s) to be written'. Numbers 0-99 are reserved for general use, numbers >99 can be allocated by the writer of each vi for specific purposes. Other elements of 'Number(s) to be written' are any required data.
Do nothing: no change, no output, useless!
© Chris Ford 2004-6