./guide
getchunk.pro

Last modification date:

Wed Sep 28 13:27:09 2016

getchunk

function getchunk([count=variable], [/keep], [useflag=boolean or string], [skipflag=boolean or string], [indicies=variable], [_EXTRA=extra keywords])

A function to get several data containers from an input file in one call.

It is more efficient to retrieve multiple data containers in one call. Because the global data buffers all contain a single data container, this function does not interact directly with the global buffers, as other data retrieval procedures do. Instead, it returns an array of data containers that must then be handled appropriately by the user.

Note that it is the responsibility of the caller to explicitly free the pointers used in this array of data containers. Simply use data_free as shown in the examples below.

The usual data selection operations can be specified in this function.

There is no protection against running out of memory. If one does not carefully select the data to be fetched or even avoids specifying any arguments to getchunk, all of the data that matches that selection (which might be all of the data in the file) will be read from disk into memory. That might be more memory than you have and this procedure does not protect you against that. Use this function carefully.

Flags (set via flag) can be selectively applied or ignored using the useflag and skipflag keywords. Only one of those two keywords can be used at a time (it is an error to use both at the same time). Both can be either a boolean (/useflag or /skipflag) or an array of strings. The default is /useflag, meaning that all flag rules that have been previously set are applied when the data is fetched from disk, blanking any data as described by each rule. If /skipflag is set, then all of the flag rules associated with this data are ignored and no data will be blanked when fetched from disk (it may still contain blanked values if the actual values in the disk file have already been blanked by some other process). If useflag is a string or array of strings, then only those flag rules having the same idstring value are used to blank the data. If skipflag is a string or array of strings, then all flag rules except those with the same idstring value are used to blank the data.

Returns

An array of data containers. If no data satisfy the selection criteria, count will be 0 and the returned value will be -1.

Examples

In the first example, we copy the input file to the keep file (currently only possible in line mode), one scan at a time. This would be done in a procedure, not at the command line, because of the loop.

    scans=get_scan_numbers(/unique)
    for i=0,(n_elements(scan)-1) do begin
       a = getchunk(scan=scans[i])
       putchunk, a
       data_free, a
    endfor
 

In the next example, we average all of the data for a given scan. This example also shows that we have choosen to ignore any flags with idstring='wind'. This could be done at the command line because the loop is contained on a single line.

    sclear
    a = getchunk(scan=6000,count=count,skipflag='wind')
    accum,dc=a[0]
    for i=1,(count-1) do accum,dc=a[i]
    ave
    data_free,a
 

Version

$Id$

Keywords
count out, optional variable	An output value giving the number of data containers actually returned.
keep in, optional boolean	When set, the data are fetched from the output file.
useflag in, optional boolean or string (def. true)	Apply all or just some of the flag rules?
skipflag in, optional boolean or string	Do not apply any or do not apply a few of the flag rules?
indicies out, optional variable	Array of index numbers, one for each spectrum retrieved. Returns -1 when no spectra were returned.
_EXTRA in, optional extra keywords	These are selection parameters to specify which data to retrieve. See listcols for a complete list of the columns available. Also see the discussion on "Select" in the User's Guide for a summary of selection syntax.