lamp_mac/readers/
read_spec.pro
FILE: `spec_access.pro' OVERVIEW: Set of IDL functions to read and write SPEC data files. These functions provide information about the SPEC file (number of scans, scan list, etc...) or about a particular scan (scan data, motor positions, header information ...). In order to speed up the access to the data, a file must be open by the function SPEC_ACCESS() before any other operation is performed. This function returns a handle to the file that has to be used in all subsequent file access. The handle is a variable used to transfer information internally between different functions and must not be modified by the main program. A handle is associated to each individual file and therefore several SPEC files can be accessed by managing different handles. All the functions require at least a file handle as parameter. If the file handle has not been previously initialized, the functions call internally SPEC_ACCESS() and prompt the user for a file name. Most of the functions require also a scan identifier (see below). If the scan identifier is missing the functions call to XSPECSCAN that is an utility procedure that displays the available scans in the data file and lets the user select one. SCAN IDENTIFIERS A scan identifier is an expression that designates a particular scan in the data file. It must be a numeric or string scalar. Numeric values can be expressed as strings by using their alphanumeric representation. A scan identifier must be of one of the following three types: Scan Number - A non-zero positive number that corresponds to the SPEC scan number included in the `#S' line in the data file. A mechanism has been provided to deal with files that include scans with repeated numbers: if a scan identifier is expressed as a decimal number SSSS.OO, it refers to the OOth occurrence of the scan SSSS in the data file. Special care must be taken when using this feature with number-valued expressions because the first two decimal places are always considered. For instance, the identifier 12.02 refers to the second occurrence of the scan 12, while 12.2 refers to the 20th occurrence of the same scan. This problem does not arise when string expressions are involved: the identifiers '12.02' and '12.2' refer both to the same scan in the data file. Scan Index - A non-zero integer number that indicates the position of the scan in the data file. Positive indexes correspond to the position of scan from the beginning of the file, the first scan in the file has an index 1. Negative indexes indicate the position of the scan by counting backwards from the end: -1 is the last scan in the file, -2 is the one before the last, and so on. When an index is used as a scan identifier, the INDEX keyword must be set in the function call in order to avoid ambiguities with scan numbers. Descriptor - One of the following words: 'FIRST' : refers to the first scan in the file. 'LAST' : refers to the last scan in the file. 'CURRENT': refers to the scan that has been most recently accessed by any of the functions of this library. 'NEXT' : refers to the scan immediately after the `current' scan. FUNCTION LIST: SPEC_ACCESS() - Returns the number of scans in the file or a scan list. SPEC_COLUMNS() - Returns the number of data columns in a given scan. SPEC_DATA() - Returns the data from a given scan. SPEC_HEADERS() - Returns headers from a given scan. SPEC_LABELS() - Returns the column labels in a given scan. SPEC_MOTORS() - Returns the positions or names of the motors in a scan. SPEC_NAME() - Returns the name of a given scan. SPEC_POINTS() - Returns the number of data points in a given scan. SPEC_SAVE() - Saves data in a SPEC data file. SPEC_SCAN() - Returns the numbers or the indexes of a list of scans. MODIFICATION HISTORY: 1.00 March/95, Written by P. Fajardo. based on 'spec_analyzer.pro' from M. Sanchez del Rio 2.00 June/95, Added support for Multichannel Data (P. Fajardo). 2.01 5/07/95, SPEC_DATA() modified to speed up data access. Default return data type is no longer string. New __reads procedure and __linesplit() function. Now the error handling routines return to the caller when an error is found (P. Fajardo). 2.02 21/08/95, Fixed a bug in the handling of split lines. New CHANNELS and CALIBRATED keywords in SPEC_DATA() (P. Fajardo). 2.03 29/09/95, New NO_EMPTY, MCDATA and FILENAME keywords in SPEC_ACCESS(). New NO_EMPTY, MCDATA and NO_RANGE keywords in SPEC_SCAN() (P. Fajardo). 3.00 -------- 3.01 16/12/96, Some elements of file handles changed from integer to long to cope with very long files. 3.02 01/10/97, srio@esrf.fr places the function spec_access() at the end of the file to allow idl to resolve all names (for use in xop). ______________________________________________________________________________
Routines
result = sdep(DS=DS, PS=PS, VF=VF, VS=VS, W=W)
result = __isaspechandle(handle)
result = __linecut(line)
result = __linesplit(oldline, nspaces, imin, imax)
result = __cleanmsg(msg)
__readline, Unit, line
__reads, line, array, error
__addscan, scanlist, s, linect, range, scancounter
__speccheck, handle
__headerload, handle
__specload, handle, scan_id, errmsg, INDEX=INDEX
result = spec_columns(handle, scan_id, INDEX=INDEX, MCDATA=MCDATA)
result = spec_data(handle, scan_id, columns, INDEX=INDEX, MCDATA=MCDATA, LABELS=LABELS, OFFSET=OFFSET, STEP=STEP, NPOINTS=NPOINTS, CHANNELS=CHANNELS, CALIBRATED=CALIBRATED, DOUBLE=DOUBLE, FLOAT=FLOAT, LONG=LONG, INT=INT, STRING=STRING)
result = spec_headers(handle, scan_id, headers, ALL=ALL, INDEX=INDEX)
result = spec_labels(handle, scan_id, INDEX=INDEX)
result = spec_motors(handle, scan_id, motorlist, badvalue, INDEX=INDEX, NOERROR=NOERROR)
result = spec_name(handle, scan_id, INDEX=INDEX)
result = spec_points(handle, scan_id, INDEX=INDEX, MCDATA=MCDATA)
result = spec_scan(handle, scan_list, errmsg, INDEX=INDEX, RETURN_INDEX=RETURN_INDEX, OCCURRENCE=OCCURRENCE, STRING=STRING, NO_EMPTY=NO_EMPTY, MCDATA=MCDATA, NO_RANGE=NO_RANGE)
result = spec_save(handle, data, file, COLUMNS=COLUMNS, LABELS=LABELS, COMMENTS=COMMENTS, NAME=NAME, NO_ERROR=NO_ERROR, OVERWRITE=OVERWRITE, NO_CONFIRM=NO_CONFIRM, DIALOG_PARENT=DIALOG_PARENT)
result = spec_access(handle, file, LIST=LIST, STRING=STRING, COMPRESS=COMPRESS, READALWAYS=READALWAYS, NOREAD=NOREAD, FILENAME=FILENAME, MCDATA=MCDATA, NO_EMPTY=NO_EMPTY)
spec_wplot, event, runtxt
spec_wlist, lbase
result = read_spec(INST, PATH, FILENAME, STATUS, DATP)
Routine details
top sdep
result = sdep(DS=DS, PS=PS, VF=VF, VS=VS, W=W)
NAME: SDEP PURPOSE: Returns several System DEPendent parameters, like OS family (default), directory separator, path separator, etc. CATEGORY: General utilities CALLING SEQUENCE: Result = SDEP() INPUTS: None KEYWORD PARAMETERS: DS: (Directory Separator) When set, SDEP returns the directory separator (i.e. / (slash) under Unix or \ (backslash) under Windows). PS: (Path Separator) When set, SDEP returns the path separator (i.e. : under Unix or ; (backslash) under Windows). VS: (Version Short) returns the idl short-version (i.e. '5' for idl 5.0.2) VF: (Version Full) returns the idl full versiom (i.e. '5.0.2' for idl 5.0.2) W: (Widget allowed?) Returns 1 when widget are allowed (i.e. !d.nane is 'WIN','X' or 'MAC') otherwise returns 0 (i.e. 'PS'). OUTPUTS: This function returns (with no keywords) the !version.os_family value in uppercase. If any keyword is set, the returned value is changed to the one described below. RESTRICTIONS: Never used under Mac PROCEDURE: Straightforward EXAMPLE: print,sdep() MODIFICATION HISTORY: Written by: srio@esrf.fr and dejus@aps.anl.gov Sept, 1997 97/10/16 srio@esrf.fr adds /w keyword. 98/12/23 srio@esrf.fr tentative update for Mac
Keywords
- DS
- PS
- VF
- VS
- W
top __isaspechandle
result = __isaspechandle(handle)
******* *************** ** This function checks if the parameter is a valid handle to a Spec data file.
Parameters
- handle
top __linecut
result = __linecut(line)
******* ********* ** This function returns the first token found in the string `line' and ** modifies the content of `line' to hold only the remainder of the string.
Parameters
- line
top __linesplit
result = __linesplit(oldline, nspaces, imin, imax)
******* *********** ** This function returns an array loaded with the tokens found in the input ** string `oldline'. Tokens are separated by a 1 or 2 white spaces according ** to the parameter `nspaces'. The function returns an error if the numbers ** of tokens found is less than `imin' or greater than `imax'. This feature ** can be cancelled by setting `imin' and/or `imax' to zero.
Parameters
- oldline
- nspaces
- imin
- imax
top __cleanmsg
result = __cleanmsg(msg)
******* ********** ** This function makes up an error message.
Parameters
- msg
top __readline
** ********** ** This procedure reads a new full logic line from the data file.
Parameters
- Unit
- line
top __reads
** ******* ** This procedure loads `array' with the data in the string `line'. The data ** type depends on the initial type of array. If in `line' there are less data ** than the number of elements in `array', the remainder elements are filled ** with 0 or '' and the variable `error' is set to 1.
Parameters
- line
- array
- error
top __addscan
__addscan, scanlist, s, linect, range, scancounter
** ********* ** This procedure appends a scan `s' to the array `scanlist' and is only ** used by spec_access().
Parameters
- scanlist
- s
- linect
- range
- scancounter
top __speccheck
__speccheck, handle
** *********** ** This procedure produces and error if the parameter is not a valid handle.
Parameters
- handle
top __headerload
__headerload, handle
** ************ ** This procedure loads in `handle' the information contained in the main header ** block that correspond to the current scan.
Parameters
- handle
top __specload
__specload, handle, scan_id, errmsg, INDEX=INDEX
** ********** ** This procedure makes the scan specified by `scan_id' the current one.
Parameters
- handle
- scan_id
- errmsg
Keywords
- INDEX
top spec_columns
result = spec_columns(handle, scan_id, INDEX=INDEX, MCDATA=MCDATA)
NAME: SPEC_COLUMNS() PURPOSE: This function returns the number of data columns of a particular scan in a SPEC file. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_COLUMNS(Handle, Scan_Id) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). Scan_Id - Scan identifier. This parameter can be a numeric or string scalar value that accepts several syntax and keywords as it is explained in the `SCAN IDENTIFIERS' section at the beginning of this file). The simplest case is to use the SPEC scan number as Scan_Id. KEYWORDS: INDEX: Set this keyword to interpret a numeric value in Scan_Id as the index of the scan instead of the scan number. MCDATA: Set this keyword to return the number of channels in the multichannel data lines instead of the number of standard data columns. OUTPUT: The number of columns in the selected scan. If the MCDATA keyword is not set the information is obtained from the `#N' line in the SPEC data file and corresponds to the number of standard data columns. When MCDATA is set, the returned value is the number of channels in the multichannel data lines obtained from the `#@CHANN' line. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). If Scan_Id does not represent a valid scan the function produces an error. EXAMPLE: To print the number of data columns in the second occurrence of the scan 150 in the file 'baddata', enter: Dummy = SPEC_ACCESS(File1_handle, 'baddata') PRINT, SPEC_COLUMNS(File1_handle, 150.02) ______________________________________________________________________________
******* ************ ** This function returns the number of data columns of a particular scan ** in a SPEC file.
Parameters
- handle
- scan_id
Keywords
- INDEX
- MCDATA
top spec_data
result = spec_data(handle, scan_id, columns, INDEX=INDEX, MCDATA=MCDATA, LABELS=LABELS, OFFSET=OFFSET, STEP=STEP, NPOINTS=NPOINTS, CHANNELS=CHANNELS, CALIBRATED=CALIBRATED, DOUBLE=DOUBLE, FLOAT=FLOAT, LONG=LONG, INT=INT, STRING=STRING)
NAME: SPEC_DATA() PURPOSE: This function returns an array with data from a scan in a SPEC file. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_DATA(Handle, Scan_Id [, Columns]) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). Scan_Id - Scan identifier. This parameter can be a numeric or string scalar value that accepts several syntax and keywords as it is explained in the `SCAN IDENTIFIERS' section at the beginning of this file). The simplest case is to use the SPEC scan number as Scan_Id. OPTIONAL INPUTS: Columns - Vector that describes the columns to be loaded in the output array. This vector can be of either numeric or string type. When numbers are used columns are selected by their relative position in the data file. When non-numeric strings are used they must match the labels of the columns to select. By using a string array it is possible to combine both selection methods. If negative numbers are used it is assumed that the column position is obtained by counting backwards from the last one: i.e. -1 means the last column, -2 the one before the last, and so on. KEYWORDS: INDEX: Set this keyword to interpret a numeric value in Scan_Id as the index of the scan instead of the scan number. MCDATA: Set this keyword to return data from the multichannel data lines instead of the standard data columns. LABELS: String vector to be filled with the labels of the returned columns. This option can only be used if the MCDATA keyword is not set. OFFSET: Number of points that will be skipped before extracting the required data. This value is defaulted to 0. STEP: Interval used to extract data points. Only the first one of each group of STEP consecutive data points will be extracted. The default value is 1. NPOINTS: Maximum number of points that will be returned. If it is zero or greater than the actual number of available data points, this keyword has not any effect. CHANNELS: Float vector to be filled with the channel numbers of the multichannel data. It is not used if the MCDATA keyword is not set. CALIBRATED: Float vector to be filled with the calibrated values (usually energy) of the channels in the multichannel data set. It is not used if the MCDATA keyword is not set. STRING: Set this keyword to force the output to be a string array. DOUBLE: Set this keyword to force the output to be a double-precision array. FLOAT: Set this keyword to force the output to be a single-precision floating-point array. LONG: Set this keyword to force the output to be a longword integer array. INT: Set this keyword to force the output to be an integer array. OUTPUT: This function returns an array containing the data columns selected by the Columns parameter. If no Columns parameter is given, all the columns in the selected scan are returned. By default the output is a double-precision array for standard data and a long array for multichannel data, but the output array can be forced to any type by setting the proper keyword. If a particular column does not exist in the SPEC file, the corresponding column in the output array is filled with zeros. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). If Scan_Id does not represent a valid scan the function produces an error. EXAMPLE: To load the array GoodData with the position of the first column of the scan 5, the monitor counts and the detector counts (that are assumed to be in the last column of the file), enter: Dummy = SPEC_ACCESS(File_handle, 'weakdata') GoodData = SPEC_DATA(File_handle, 27, ['1', 'Monitor', '-1']) ______________________________________________________________________________
******* ********* ** This function returns an array with data from a scan in a SPEC file.
Parameters
- handle
- scan_id
- columns
Keywords
- INDEX
- MCDATA
- LABELS
- OFFSET
- STEP
- NPOINTS
- CHANNELS
- CALIBRATED
- DOUBLE
- FLOAT
- LONG
- INT
- STRING
top spec_headers
result = spec_headers(handle, scan_id, headers, ALL=ALL, INDEX=INDEX)
NAME: SPEC_HEADERS() PURPOSE: This function returns header lines from a particular scan in a SPEC data file. Header lines begin by the '#' character and can be situated before or after the block of data lines. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_HEADERS(Handle, Scan_Id [, Selec_Array]) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). Scan_Id - Scan identifier. This parameter can be a numeric or string scalar value that accepts several syntax and keywords as it is explained in the `SCAN IDENTIFIERS' section at the beginning of this file). The simplest case is to use the SPEC scan number as Scan_Id. OPTIONAL INPUTS: Selec_Array - Array that contains selectors to the header lines. A selector is a string with the first characters of the header lines that are wanted to be returned. A selector can include or not the first '#' character of the header lines. For instance, the string 'P' selects all the headers in the scan that contain motor positions (those that begin with the '#P' characters) and the string '#G0' selects the first line of geometry parameters. KEYWORDS: INDEX: Set this keyword to interpret a numeric value in Scan_Id as the index of the scan instead of the scan number. ALL: Set this keyword to extend the scope of the search and include the main block of header lines as well as comments embedded in the data block. In normal SPEC data files the main header block is placed at the beginning of the file and includes the file name line ('#F') the epoch line ('#E') and the motor names ('#O' lines). If there are more than one main header block in the file, the function uses the last one before the given scan. Comment lines appear embedded in the data block when a scan is resumed after been aborted from SPEC. OUTPUT: This function returns a string array that contains all the header lines that match the selection criteria. If Selec_Array is not specified all the header lines are returned. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). If Scan_Id does not represent a valid scan the function produces an error. EXAMPLE: To load the string array NewHeaders with the header lines that contain the positions of the first eight motors ('#P0' line) and the user defined values ('#U' lines), enter: Dummy = SPEC_ACCESS(FileHandle, 'baddata') Nscans = SPEC_HEADERS(FileHandle, BestScan, ['#P0','U']) (the file in this example is 'baddata' and the scan number is in the variable called BestScan) ______________________________________________________________________________
******* ************ ** This function returns header lines from a particular scan in a SPEC ** data file. Header lines begin by the '#' character and can be situated ** before or after the block of data lines.
Parameters
- handle
- scan_id
- headers
Keywords
- ALL
- INDEX
top spec_labels
result = spec_labels(handle, scan_id, INDEX=INDEX)
NAME: SPEC_LABELS() PURPOSE: This function returns the labels of data columns of a particular scan in a SPEC file. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_LABELS(Handle, Scan_Id) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). Scan_Id - Scan identifier. This parameter can be a numeric or string scalar value that accepts several syntax and keywords as it is explained in the `SCAN IDENTIFIERS' section at the beginning of this file). The simplest case is to use the SPEC scan number as Scan_Id. KEYWORDS: INDEX: Set this keyword to interpret a numeric value in Scan_Id as the index of the scan instead of the scan number. OUTPUT: This function returns an string array that contains the labels of the the data columns in the SPEC file. The information is extracted from the '#L' line. The dimension of the array depends on the number of columns of this particular scan. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). If Scan_Id does not represent a valid scan the function produces an error. EXAMPLE: To load the array NewLabels with the labels of the data columns of the scan no. 27 from a file called 'karaoke', enter: Dummy = SPEC_ACCESS(File1_handle, 'karaoke') NewLabels = SPEC_LABELS(File1_handle, 27) ______________________________________________________________________________
******* *********** ** This function returns the labels of data columns of a particular scan ** in a SPEC file.
Parameters
- handle
- scan_id
Keywords
- INDEX
top spec_motors
result = spec_motors(handle, scan_id, motorlist, badvalue, INDEX=INDEX, NOERROR=NOERROR)
NAME: SPEC_MOTORS() PURPOSE: This function returns the names or position of motors in a particular scan in a SPEC file. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_MOTORS(Handle, Scan_Id [, MotorList [, BadValue]]) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). Scan_Id - Scan identifier. This parameter can be a numeric or string scalar value that accepts several syntax and keywords as it is explained in the `SCAN IDENTIFIERS' section at the beginning of this file). The simplest case is to use the SPEC scan number as Scan_Id. OPTIONAL INPUTS: MotorList - String array that contains the names of the motors which position is requested. In addition to motor names, it is also possible to specify a motor by using a string with the format 'line,motor' where `line' in the number of the `#P' header line that includes the motor information, and `motor' is the relative position of the motor in that line. For instance, '2,1' refers to the first motor in the `#P2' line. BadValue - Dummy value to be returned as a motor position if the corresponding motor is not found or when the headers are corrupted and the NOERROR ketword is set. This value is defaulted to 1E20. KEYWORDS: INDEX: Set this keyword to interpret a numeric value in Scan_Id as the index of the scan instead of the scan number. NOERROR: Set this keyword to not return an error when the file headers are corrupted. OUTPUT: If MotorList is specified this function returns the position of the motors included in the list. Otherwise it returns a string array that contains the names of all the motors associated to the given scan. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). If Scan_Id does not represent a valid scan the function produces an error. If the file was created with an old version of SPEC and a motor name has more than 8 characters this function will not work. It will not work if a motor name includes two or more consecutive white spaces. EXAMPLE: To print the position of the motors 'Theta', 'Piezo 1' and the second motor of the first `#P' line in the fifth scan of a file called 'baddata', enter: Dummy = SPEC_ACCESS(HHH, 'baddata') PRINT, SPEC_MOTORS(HHH, -5, ['Theta', 'Piezo 1', '0,2']) ______________________________________________________________________________
******* *********** ** This function returns the names or position of motors in a particular ** scan in a SPEC file.
Parameters
- handle
- scan_id
- motorlist
- badvalue
Keywords
- INDEX
- NOERROR
top spec_name
result = spec_name(handle, scan_id, INDEX=INDEX)
NAME: SPEC_NAME() PURPOSE: This function returns the name of a particular scan in a SPEC file. In most of the cases the name of a scan is the full macro that was used to produce obtain the data. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_NAME(Handle, Scan_Id) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). Scan_Id - Scan identifier. This parameter can be a numeric or string scalar value that accepts several syntax and keywords as it is explained in the `SCAN IDENTIFIERS' section at the beginning of this file). The simplest case is to use the SPEC scan number as Scan_Id. KEYWORDS: INDEX: Set this keyword to interpret a numeric value in Scan_Id as the index of the scan instead of the scan number. OUTPUT: The name of the selected scan. The information is obtained from the '#S' line. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). If Scan_Id does not represent a valid scan the function produces an error. EXAMPLE: To print the name of the scan 150 from a file called 'baddata', enter: Dummy = SPEC_ACCESS(File1_handle, 'baddata') PRINT, SPEC_NAME(File1_handle, 150) ______________________________________________________________________________
******* ********* ** This function returns the name of a particular scan in a SPEC file. ** In most of the cases the name of a scan is the full macro that was ** used to produce obtain the data.
Parameters
- handle
- scan_id
Keywords
- INDEX
top spec_points
result = spec_points(handle, scan_id, INDEX=INDEX, MCDATA=MCDATA)
NAME: SPEC_POINTS() PURPOSE: This function returns the number of data points of a particular scan in a SPEC file. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_POINTS(Handle, Scan_Id) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). Scan_Id - Scan identifier. This parameter can be a numeric or string scalar value that accepts various syntax and keywords as it is explained in the `SCAN IDENTIFIERS' section at the beginning of this file). The simplest case is to use the SPEC scan number as Scan_Id. KEYWORDS: INDEX: Set this keyword to interpret a numeric value in Scan_Id as the index of the scan instead of the scan number. MCDATA: Set this keyword to make the function return the number of points with multichannel data (MCA, ...) instead of the conventional data. OUTPUT: The number of data points in the scan specified by Scan_Id. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). If Scan_Id does not represent a valid scan the function produces an error. EXAMPLE: To print the number of data points in the scan 999 from a file called 'sosada', enter: Dummy = SPEC_ACCESS(File1_handle, 'sosada') PRINT, SPEC_POINTS(File1_handle, 999) ______________________________________________________________________________
******* *********** ** This function returns the number of data points of a particular scan ** in a SPEC file.
Parameters
- handle
- scan_id
Keywords
- INDEX
- MCDATA
top spec_scan
result = spec_scan(handle, scan_list, errmsg, INDEX=INDEX, RETURN_INDEX=RETURN_INDEX, OCCURRENCE=OCCURRENCE, STRING=STRING, NO_EMPTY=NO_EMPTY, MCDATA=MCDATA, NO_RANGE=NO_RANGE)
NAME: SPEC_SCAN() PURPOSE: This function returns a vector loaded with the numbers of a group of scans in a SPEC file. The values returned correspond to either the numbers ('#S' lines) of the scans or their indexes (relative position in the file). This function can be used to check if a scan or group of scans exist in a SPEC data file before calling any other function of the library. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_SCAN(Handle, ScanList [, ErrMsg]) INPUTS: Handle - Handle to the SPEC data file initialised by a previous call to SPEC_ACCESS(). ScanList - List of scans in the SPEC data file. ScanList can be a scalar or an array. In the case of arrays all the elements are included in the list. ScanList can also be of numeric or string type. When using character strings one can specify a group of consecutive scans in compressed form using the syntax `first-last'. If `first' or `last' are not specified they are defaulted to the first and last scan in the file. It is also possible to include several scans or groups of scans in a single string by using commas or white spaces as separators. The values in ScanList follow the same convention used for scan identifiers (see the `SCAN IDENTIFIERS' section at the beginning of this file). By default, numeric values are interpreted as SPEC scan numbers, but this behaviour is changed by the INDEX keyword. KEYWORDS: INDEX: Set this keyword to interpret the numeric values in ScanList as the indexes of the scans instead of as scan numbers. Care must be taken when using indexes in strings that specify groups of scans. In order to allow the use of negative indexes the sign of the index must be explicitly included when the expression can be ambiguous. As an example compare the following expressions when INDEX is set: '-2' represents the scan before the last one (index=-2). '--2' represents the scans from the first to the one before the last (index=1 to index=-2). '-+2' represents the first two scans in the file (index=1 to index=2). RETURN_INDEX: Set this keyword to return the index of the scans instead of the scan numbers. OCCURRENCE: Set this keyword to return the scan number and the scan occurrence in the format SSSS.OO as explained in the `SCAN IDENTIFIERS' section at the beginning of this file). This keyword has not any effect if RETURN_INDEX is also set. STRING: Set this keyword to force the output as a string vector instead of float. NO_EMPTY: Set this keyword to make the output value of the function refer only to those scans that actually contain standard data columns, excluding the empty ones. MCDATA: Set this keyword to make the output value of the function refer only to those scans that contain multichannel data. NO_RANGE: Set this keyword to force the function to accept only single scans as input instead of lists. OUTPUT: If there is no error this function returns a vector that contains the list of scans specified in ScanList. If any of the scans is not found or any other error occurs, the function return -1. OPTIONAL OUTPUTS: ErrMsg - Error message if an error occurs. SIDE EFFECTS: The `current' scan is set to the last scan in the list. RESTRICTIONS: This function requires a valid handle to a SPEC data file obtained by a previous call to SPEC_ACCESS(). EXAMPLE: To print the number of most recently accessed scan, enter: PRINT, SPEC_SCAN(OldHandle, 'current') ______________________________________________________________________________
******* ********* ** This function returns a vector loaded with the numbers of a group of ** scans in a SPEC file. ** The values returned correspond to either the numbers ('#S' lines) of ** the scans or their indexes (relative position in the file). ** This function can be used to check if a scan or group of scans exist ** in a SPEC data file before calling any other function of the library.
Parameters
- handle
- scan_list
- errmsg
Keywords
- INDEX
- RETURN_INDEX
- OCCURRENCE
- STRING
- NO_EMPTY
- MCDATA
- NO_RANGE
top spec_save
result = spec_save(handle, data, file, COLUMNS=COLUMNS, LABELS=LABELS, COMMENTS=COMMENTS, NAME=NAME, NO_ERROR=NO_ERROR, OVERWRITE=OVERWRITE, NO_CONFIRM=NO_CONFIRM, DIALOG_PARENT=DIALOG_PARENT)
NAME: SPEC_SAVE() PURPOSE: This function saves the data contained in a 2D numeric array into a file following the SPEC data file format. If the file does not exist it is created. I the file exits, it must be a valid SPEC data file and the data is appended as a new scan. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_SAVE(Handle, Data [, File]) INPUTS: Handle - Handle to the SPEC data file. It is initialized, if necessary, and updated after the data is saved. Data - Numeric array containing the data to be saved. The first dimension correspond to the data columns in the SPEC file. OPTIONAL INPUT/OUTPUT File - If Handle is not a valid SPEC file handle, this is parameter is the name of the file where the data will be saved. Otherwise File specifies a named variable where the actual name of the file will be returned. KEYWORDS: COLUMNS: Vector that specifies the columns in the array Data that will be saved. If this keyword is not set all the columns are saved. LABELS: String vector that contains the labels for the data columns. COMMENTS: String vector that contains comment lines that will be included in the header section of the scan. NAME: String that will appear as scan name in the `#S' line. OVERWRITE: Set this keyword to overwrite the file if it exists. By default data is appended to existing files. NO_CONFIRM: Set this keyword to not ask for confirmation when writting data on existing files. NO_ERROR: Set this keyword to not produce an IDL error if an error is found when writting the data. DIALOG_PARENT: Set this keyword equal to a string that specifies the name of the parent widget (to be passed to Dialog_Message) OUTPUT: This function returns the scan number under which the data is saved in the file. If the operation is cancelled, the function returns zero. If an error happens and NO_ERROR is set the function returns -1 and the error message is stored in the system variable !ERR_STRING. EXAMPLE: To save the data in the array NewData in the file 'Newfile', enter: PRINT, SPEC_SAVE(DummyHandle, NewData, 'Newfile') ______________________________________________________________________________
******* ********* ** This function saves the data contained in a 2D numeric array into a file ** following the SPEC data file format. If the file does not exist it is created. ** I the file exits, it must be a valid SPEC data file and the data is appended ** as a new scan.
Parameters
- handle
- data
- file
Keywords
- COLUMNS
- LABELS
- COMMENTS
- NAME
- NO_ERROR
- OVERWRITE
- NO_CONFIRM
- DIALOG_PARENT
top spec_access
result = spec_access(handle, file, LIST=LIST, STRING=STRING, COMPRESS=COMPRESS, READALWAYS=READALWAYS, NOREAD=NOREAD, FILENAME=FILENAME, MCDATA=MCDATA, NO_EMPTY=NO_EMPTY)
NAME: SPEC_ACCESS() PURPOSE: This function returns the number of scans in a SPEC data file or optionally the list of scans. The first time that it is called or if the datafile is modified it reads the file and creates an internal index to speed up the subsequent access to the data. This function must be called before any other function of the library. CATEGORY: Input/Output. CALLING SEQUENCE: Result = SPEC_ACCESS(Handle [, SPECfile]) INPUTS: Handle - Variable used as a handle to the file. This variable is modified internally by the function and must be used in all subsequent function calls to access the data file. If the variable used is not a valid handle to the file in SPECfile or if the length of the file has changed, the internal index is rebuilt. If the variable used is a valid handle that has been initialised in a previous call to SPEC_ACCESS(), the function checks if the current size of the file is the same than in the previous call. If so, the internal index is not rebuilt. OPTIONAL INPUTS: SPECfile - String that contains the name of the data file. This parameter is only optional in the case that Handle is a valid SPEC file handle initialised in a previous call to SPEC_ACCESS(). KEYWORDS: LIST: Set this keyword to produce a list of the scans in the file. By default the list is a vector that contains all the numbers of the scans in the file. This behaviour can be changed by the COMPRESS and STRING keywords. COMPRESS: Set this keyword to return the scan list in a compressed format. In a compressed list the scans with consecutive numbers are grouped in blocks. Each block is described by the numbers of its first and last scan. If the STRING keyword is not set the result is an array with two dimensions where the element (0, i) is the number of the first scan in the group i, and the element (1, i) is the number of the last scan in the group. This keyword has no effect if the LIST keyword is not set. STRING: Set this keyword to format the result as a character string rather than as a number, vector or array. If the result is a compressed list, the groups in the output string are separated by commas (',') and the first and last scan number of each group are separated by a minus sign ('-'). READALWAYS: Set this keyword to force the function to read the file and build the internal index even in the case that Handle is a valid handle to the same file and the size of the file has not changed. If READALWAYS is set, the parameters SPECfile must be specified. NOREAD: Set this keyword to force the function not to read again the file even in the case that its size has changed. NO_EMPTY: Set this keyword to make the output value of the function refer only to those scans that actually contain standard data columns, excluding the empty ones. MCDATA: Set this keyword to make the output value of the function refer only to those scans that contain multichannel data. FILENAME: Variable to be loaded with the name of the Spec data file. This keyword is only useful when the function is called with a previously initialized SPEC file handle and the file name is not known. OUTPUT: If the LIST keyword is not set this function returns the total number of scans in the SPEC data file. If the LIST keyword is set, it returns a list of the scans. SIDE EFFECTS: When the internal index is built the `current' scan is set to the first scan in the file. RESTRICTIONS: This function only works with ASCII files that follow the conventions used by the program SPEC to generate data files. EXAMPLE: To create an internal index of the SPEC data file 'data.run23' and load the variable Nscans with the total number of scans in the file, enter: Nscans = SPEC_ACCESS(File1_handle, "data.run23") The variable File1_handle should not be modified by the main program. It may be used to access information from the same file by other function calls. ______________________________________________________________________________
******* *********** ** This function returns the number of scans in a SPEC data file or ** optionally the list of scans. The first time that it is called or if ** the datafile is modified it reads the file and creates an internal ** index to speed up the subsequent access to the data. ** This function must be called before any other function of the library.
Parameters
- handle
- file
Keywords
- LIST
- STRING
- COMPRESS
- READALWAYS
- NOREAD
- FILENAME
- MCDATA
- NO_EMPTY
File attributes
Modification date: | Tue Oct 1 14:38:29 2013 |
Lines: | 2,736 |