Extended IDL Help

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Tue Jul 11 20:43:37 2006.


List of Routines


Routine Descriptions

ISFILE

[Next Routine] [List of Routines]
 NAME: 
  isfile
 PURPOSE: 
  Check if a file exists
 DESCRIPTION:
 CATEGORY:
  fileio 
 CALLING SEQUENCE:
  exists = IsFile(fn)
 INPUTS:
  fn: the filename
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
 OUTPUTS:
  exists (boolean): true if file exists
 KEYWORD OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
  call findfile
 MODIFICATION HISTORY:
  2002/05/30 - Initial  version written, Leslie Young SwRI

(See fileio/isfile.pro)


NEXT_LUN

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
  next_lun
 PURPOSE: 
  find next available lun
 DESCRIPTION:
  find next available lun, useful for finding which code that
  fails to close opened luns.
 CATEGORY:
  fileio 
 CALLING SEQUENCE:
  lun = next_lun()
 INPUTS:
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
 OUTPUTS:
  Next available lun
 KEYWORD OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
  call get_lun, free_lun
 MODIFICATION HISTORY:
  2002/05/30 - Initial  version written, Leslie Young SwRI

(See fileio/next_lun.pro)


NTHLINE[1]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
  nthline

 PURPOSE: (one line)
  Return the nth line in a file

 DESCRIPTION:
  Return the nth line in a file

 CATEGORY:
  File IO
  
 CALLING SEQUENCE:
  line = nthline(filename, linenum)

 INPUTS:
  filename - file from which to get lines
  linenum - the line number to return (long or array of long)

 OPTIONAL INPUT PARAMETERS:
  None
  
 KEYWORD INPUT PARAMETERS:

 KEYWORD OUTPUT PARAMETERS:
  NSTARS -- Returns the number of successfully-retrieved lines.

 OUTPUTS:
  If input is a scalar, then output is a single string.
  If input is a vector, then output is an array of strings.
  If a line is not found (linenum out of range), returned value is ''.
  
 COMMON BLOCKS:
  None

 SIDE EFFECTS:
  None

 PROCEDURES:
  spawned call to sed

 RESTRICTIONS:

 EXAMPLE:
  print, nthline(102,[430L, 1000L])
 
 MODIFICATION HISTORY:
  Written   2006 Apr 23 Leslie Young SwRI
  2006 July 3 LAY swap if little endian

(See fileio/nthline.pro)


NTHLINE[2]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
  nthline

 PURPOSE: (one line)
  Return the nth line in a file

 DESCRIPTION:
  Return the nth line in a file

 CATEGORY:
  File IO
  
 CALLING SEQUENCE:
  line = nthline(filename, linenum)

 INPUTS:
  filename - file from which to get lines
  linenum - the line number to return (long or array of long)

 OPTIONAL INPUT PARAMETERS:
  None
  
 KEYWORD INPUT PARAMETERS:
  /VERBOSE -- If set, print diagnostics to screen.

 KEYWORD OUTPUT PARAMETERS:
  NSTARS -- Returns the number of successfully-retrieved lines.

 OUTPUTS:
  If input is a scalar, then output is a single string.
  If input is a vector, then output is an array of strings.
  If a line is not found (linenum out of range), returned value is ''.
  
 COMMON BLOCKS:
  None

 SIDE EFFECTS:
  None

 PROCEDURES:
  repeated calls to readf

 RESTRICTIONS:

 EXAMPLE:
  print, nthline(102,[430L, 1000L])
 
 MODIFICATION HISTORY:
  Written   2006 Apr 23 Leslie Young SwRI

(See fileio/nthline_v1.pro)


NTHLINE[3]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
  nthline

 PURPOSE: (one line)
  Return the nth line in a file

 DESCRIPTION:
  Return the nth line in a file

 CATEGORY:
  File IO
  
 CALLING SEQUENCE:
  line = nthline(filename, linenum)

 INPUTS:
  filename - file from which to get lines
  linenum - the line number to return (long or array of long)

 OPTIONAL INPUT PARAMETERS:
  None
  
 KEYWORD INPUT PARAMETERS:
  /VERBOSE -- If set, print diagnostics to screen.

 KEYWORD OUTPUT PARAMETERS:
  NSTARS -- Returns the number of successfully-retrieved lines.

 OUTPUTS:
  If input is a scalar, then output is a single string.
  If input is a vector, then output is an array of strings.
  If a line is not found (linenum out of range), returned value is ''.
  
 COMMON BLOCKS:
  None

 SIDE EFFECTS:
  None

 PROCEDURES:
  spawned call to sed

 RESTRICTIONS:

 EXAMPLE:
  print, nthline(102,[430L, 1000L])
 
 MODIFICATION HISTORY:
  Written   2006 Apr 23 Leslie Young SwRI

(See fileio/nthline_v2.pro)


NTHLINE_LOOKUP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
  nthline_lookup

 PURPOSE: (one line)
  make a lookup table for use by nthline

 DESCRIPTION:
  make a lookup table for use by nthline

 CATEGORY:
  File IO
  
 CALLING SEQUENCE:
  nthline_lookup, filename, lookup=lookup, recalc=recalc

 INPUTS:
  filename - file for which to make the lookup

 OPTIONAL INPUT PARAMETERS:
  
 KEYWORD INPUT PARAMETERS:

  lookup - name of lookup table (otherwise filename.lookup)
  recacl - if set, recalculate and save lookup table, even if file exists

 KEYWORD OUTPUT PARAMETERS:

 OUTPUTS:
  
 COMMON BLOCKS:
  None

 SIDE EFFECTS:
  Creates lookup table, a file of 2 x n longs
  startbyte  nbyte

 PROCEDURES:

 RESTRICTIONS:

 EXAMPLE:
 
 MODIFICATION HISTORY:
  Written   2006 Apr 23 Leslie Young SwRI

(See fileio/nthline_lookup.pro)


READ_PRINCETON

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   READ_PRINCETON

 PURPOSE:
   This procedure reads data files written by Princeton Instruments'
   WinSPEC and WinVIEW software.

 CATEGORY:
   File input.

 CALLING SEQUENCE:
   READ_PRINCETON, File, Data

 INPUTS:
   File:
       The name of the data file to read.

 OUTPUTS:
   Data[nx, ny, nframes]:
   The output data array.  The array will be 1, 2 or 3 dimensions
   (depending upon whether ny and nframes are 1) and can be integer,
   long or float data type.

 KEYWORD OUTPUTS:
   HEADER:
       The 4100 byte header from the file.  This header can be used to
       extract additional information about the file.  See the Princteon
       Instruments "PC Interface Library Programming Manual" for the
       description of the header structure, and this procedure for
       examples of how to extract information from the header.

   X_CALIBRATION:
       An nx array of calibrated values for each pixel in the X direction.
   Y_CALIBRATION:
       An ny array of calibrated values for each pixel in the Y direction.
   COMMENTS:
       A 5-element string array containing the "experiment comments"
       fields, which is a 5x80 byte array starting at location 200 in
       the PI header.  These fields are typically used to store
       experiment-specific information.  For example, in the tomography
       experiments we use the first two strings to store the frame type
       and rotation angle.
   DATE:
       A date string of the form DDMMMYYYY:HH:MM:SS
   EXPOSURE:
       The exposure time in seconds.
   BACKGROUND_FILE:
       The name of the background file that was subtracted from the data

 RESTRICTIONS:
   This procedure currently only extracts limited information from the
   header. It should be exhanced to extract more fields, probably into a
   structure.
   The data and calibration are corrected for byte order when reading on
   a big-endian host, but other elements of the header are not converted.

 EXAMPLE:
   Read a data file:

       IDL> READ_PRINCETON, 'test.spe', data, header=header, x_cal=x_cal
       IDL> plot, x_cal, data
       IDL> clock_speed = float(header, 1428)
       IDL> print, 'Vertical clock speed (microseconds) = ', clock_speed

 MODIFICATION HISTORY:
       Written by:     Mark Rivers, 11/4/97
   Mark Rivers 10/27/98  Convert data to long if any pixels are > 32K
   Mark Rivers 11/12/98  Fix to not convert data if already long
   Mark Rivers 3/16/99   Added /BLOCK keyword to openr to work with VMS
   Mark Rivers 3/27/99   Added "Comments" keyword
   Mark Rivers 3/29/99   Added "Date" keyword
   Mark Rivers 2/22/00   Corrected byte order for data and calibration.
   Mark Rivers 9/11/01   Added "exposure" keyword
   Mark Rivers 9/12/01   Added "background_file" keyword

(See fileio/read_princeton.pro)


READ_PRINCETON2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   READ_PRINCETON2

 PURPOSE:
   This procedure reads data files written by Princeton Instruments'
   WinSPEC and WinVIEW software.

 CATEGORY:
   File input.

 CALLING SEQUENCE:
   READ_PRINCETON, File, Data

 INPUTS:
   File:
       The name of the data file to read.

 OUTPUTS:
   Data[nx, ny, nframes]:
   The output data array.  The array will be 1, 2 or 3 dimensions
   (depending upon whether ny and nframes are 1) and can be integer,
   long or float data type.

 KEYWORD OUTPUTS:
   HEADER:
       The 4100 byte header from the file.  This header can be used to
       extract additional information about the file.  See the Princteon
       Instruments "PC Interface Library Programming Manual" for the
       description of the header structure, and this procedure for
       examples of how to extract information from the header.

   X_CALIBRATION:
       An nx array of calibrated values for each pixel in the X direction.
   Y_CALIBRATION:
       An ny array of calibrated values for each pixel in the Y direction.
   COMMENTS:
       A 5-element string array containing the "experiment comments"
       fields, which is a 5x80 byte array starting at location 200 in
       the PI header.  These fields are typically used to store
       experiment-specific information.  For example, in the tomography
       experiments we use the first two strings to store the frame type
       and rotation angle.
   DATE:
       A date string of the form DDMMMYYYY:HH:MM:SS

 RESTRICTIONS:
   This procedure currently only extracts limited information from the
   header. It should be exhanced to extract more fields, probably into a
   structure.
   The data and calibration are corrected for byte order when reading on
   a big-endian host, but other elements of the header are not converted.

 EXAMPLE:
   Read a data file:

       IDL> READ_PRINCETON, 'test.spe', data, header=header, x_cal=x_cal
       IDL> plot, x_cal, data
       IDL> clock_speed = float(header, 1428)
       IDL> print, 'Vertical clock speed (microseconds) = ', clock_speed

 MODIFICATION HISTORY:
       Written by:     Mark Rivers, 11/4/97
   Mark Rivers 10/27/98  Convert data to long if any pixels are > 32K
   Mark Rivers 11/12/98  Fix to not convert data if already long
   Mark Rivers 3/16/99   Added /BLOCK keyword to openr to work with VMS
   Mark Rivers 3/27/99   Added "Comments" keyword
   Mark Rivers 3/29/99   Added "Date" keyword
   Mark Rivers 2/22/00   Corrected byte order for data and calibration.
   Roban Kramer 7/13/2001 roban@sccs.swarthmore.edu, changed
                          data_type=2 to use 
                          data = intarr(nx, ny, nframes)
                          Added "exposure" structure

(See fileio/read_princeton2.pro)


TMPPRO

[Previous Routine] [List of Routines]
 NAME:
        TMPPRO

 PURPOSE:
        Get the filename and path of a temporary .pro file.

 CATEGORY:
        IO.

 CALLING SEQUENCE:

        Result = TMPPRO( [Prefix, Ndigits] )

 OPTIONAL INPUTS:

        Prefix:   The prefix of the filename, ('tmp'=default).

        Ndigits:  The number of digits to append to the Prefix, (3=default).

 OPTIONAL INPUT KEYWORD PARAMETERS:

        SEED:     The seed used by the random number generator to determine
             the number to append to the Prefix.

 OUTPUTS:
        The file specification returned is:

             tmp_dir+Prefix+NNN+Suffix

        where NNN is a random LONG integer with number of digits = Ndigits.
        This routine also searches the tmp_dir for this filename. If a
        duplicate filename is found, then another random number is chosen.

        tmp_dir is the path to the /tmp directory 
        where  is the directory containing tmppro


 EXAMPLE:
        Let's create a temp filename myNNNN.pro:

             tmp_file = TMPFILE('my',4)

 MODIFICATION HISTORY:
        30-DEC-2005    Modified from tmpfile by Leslie Young, SwRI
        MODIFICATION HISTORY OF TMPFILE
        Written by:    Han Wen, November 1994.
        08-FEB-1995    Fixed minor bug, random integer -> random LONG integer
        12-JUN-1995    Check existence of TMP directory and create it if no
                       such directory exists.
        01-JUL-1995    Use DIR_EXIST to check existence of TMP directory.
        07-AUG-1996    Use TMPPATH (hacked version of FILEPATH) to determine
                       TMP directory.

(See fileio/tmppro.pro)