Extended IDL Help

  • Return to IDL Topics

    Last modified: Tue Aug 7 08:53:42 2007.


    List of Routines


    Routine Descriptions

    CLOSEPDB

    [Next Routine] [List of Routines]
       Close a pdb file. If the current file is closed, the current file pointer
       will be set to the next file opened or to the previous file if it is the
       last file.
       format:   CLOSEPDB, [, fileid] [, /allfiles
       where:
          fileid    - file id or an array of file ids of the file(s) to be closed
                      If it is omitted or zero, the current file is closed.
          allfiles  - If set, all files are closed. FILEID is ignored.
       Example:
          Close the current file.
             closepdb
         closepdb, 0
    
          Close the file with a file id of 3
             closepdb, 3
    
          Close all files
             closepdb, /all
    

    (See ../pfidl/pdb/closepdb.pro)


    CREATEPDB

    [Previous Routine] [Next Routine] [List of Routines]
      Open a PDB file.  The current file pointer is set to this file id and 
      the dataset names are stored.  Same as openpdb with mode = 2 or 'WRITE'
    
      format: CREATEPDB , File [, Fileid ] [, Error = error] [, FILEID = fileid]
      where:
        File   - name of the PDB file to be opened.  
                 NOTE: FULFNAM procedure is used to handle environment variables
                       See FULFNAM for details
                 NOTE: FIND_NEWFILE is used to insure a new file.
        Fileid - user specified file id 
                 (If fileid is specified, it will be used as the file id.  If 
                 fileid is not provided or is zero, a value will be 
                 provided; default value is the first unused integer greater
                 than 0.  If fileid is provided but has been used for another 
                 file, the program will provide a default value.
                 If positional parameter is valid, keyword will be ignored.
        Error  - Error parameter
                 If this error is zero, no error encountered.
                 If Error = -99, file not found
    
      Examples:
        Create a PDB file, 'JUNK.pdb' with the default file id
          createpdb, 'junk.pdb'
    

    (See ../pfidl/pdb/createpdb.pro)


    CURPDB

    [Previous Routine] [Next Routine] [List of Routines]
       Name: CURPDB
      
       A wrapper for IDL cursor which returns the cell K, L components for the
         cursor position. 
       Note: PDB indices are assumed to start at 1
       NOTE: XY2KL is used to calculate the indices.
       NOTE: This feature may be accessed from the plotgrd command.
       
       Format:
           POINT = CURPDB(STR [, /QUIET] [, POINT = XYpoint]
                  [, TIME = time] [, INDEX = index]  [, _EXTRA = extrastuff])
         where
            STR        - Grid structure used for the current plot.
    
            POINT      - Node number of the cell - 1 to number of nodes
                         If IJCOORD is set then I, J coordinates of the zone 
                           of the cursor location 
                         In case of an error, -1 is returned
                         If n_elements(time) ne 0 and POINT is a 2 element vector,
                         then point is taken as the cursor location.
                         (I and J go from 1 to nx,ny)
            TIME       - If defined then used to determine the time of the grid
                         with the values in point.
                         Default is the value used for the last plot.
                         If zero or integer 1, then the first grid time is used.
                         Data is not interpolated.
            INDEX      - If set, Time is taken as an index =[1, 2, ...N_time]
                         If time = zero or integer=1 then time index is 1
            XYpoint    - X, Y coordinates of the cursor location
            QUIET      - If set, no output to the terminal
            extrastuff - any valid keywords for the IDL cursor command
        Example:
            Print the location of a point on a grid plot and get the components 
            in ind.  Structure with the grid data is 12
               ind = curpdb(12)
    

    (See ../pfidl/pdb/curpdb.pro)


    DIRPDB

    [Previous Routine] [Next Routine] [List of Routines]
    
         this routine returns information about variables in a pdb file
    
     Format:
         DIRPDB,  P1 [, P2] [, NDSET = ndset] [, /FULL] [, PAGE = page]
                     [, TYPE = type] [, NDIM = ndim]  [, DIM = dim]
                     [, PRINTIT = printit] [, LINE= LINE] [, VARIABLE = variable]
                     [, FILEID = fileid] [, /QUIET]
    
     where:
    
       P1 and P2 have several possible configurations
           DIRPDB,  start [, NUMBER]
           DIRPDB,  
          where:
            start    - first dataset number or an array of dataset numbers 
            number   - if start is a vector, then number is ignored
                       if start is a scalar, then variables are 
                         variables = variables(start+ indgen(number)
            SEARCH_STRING - Search string for the variable name
                            See GET_MATCH for details of the search.
       FILEID    - File id for the variable information
                   Default is the current file
       VARIABLE  - Variable or dataset names
       NDSET     - Number of datasets 
       FULL      - If set, full variable description will be printed
       PAGE      - Number of lines in the directory
                   Default = directorypage (24)
       TYPE      - Dataset type 
       Filename  - Name of the file
       NDIM      - Number of dimensions
       DIM       - Minimum and maximum values for each dimension 
                   array [2, 5, ndset]
       QUIET     - If set, no output
       TRUNCATE  - If set, Delete source information.
                   Default: Truncate = 1
       HELP      - Print a help message
       LINE      - Text output array
     
     Example:
        Print the variable information for variable 5 for the current dataset.
           dirpdb, 5
    
        Print the variable information for variable 5 to 8 for the current dataset.
           dirpdb, 5, 8
    
        Print the variable information for all variables beginning with src
           dirpdb, '^src'
    
     Original version:  July 29, 1999, lpm
    

    (See ../pfidl/pdb/dirpdb.pro)


    INQVAR

    [Previous Routine] [Next Routine] [List of Routines]
    
         This routine returns information about a variable in a pdb file
         This routine calls dirpdb, with quiet set.
    
     Format:
         INQVAR,  P1 [, P2] [, NDSET = ndset] [, TYPE = type]
                [, NDIM = ndim]  [, DIM = dim] [, PRINTIT = printit]
                [, VARIABLE = variable] [, FILEID = fileid]
    
     where:
    
       P1 and P2 have several possible configurations
           INQVAR,  start [, NUMBER]
           INQVAR,  
          where:
            start    - first dataset number or an array of dataset numbers 
            number   - if start is a vector, then number is ignored
                       if start is a scalar, then variables are 
                         variables = variables(start+ indgen(number)
            SEARCH_STRING - Search string for the variable name
                            See GET_MATCH for details of the search.
       FILEID    - File id for the variable information
                   Default is the current file
       VARIABLE  - Variable or dataset names
       NDSET     - Number of datasets 
       TYPE      - Dataset type 
       NDIM      - Number of dimensions
       DIM       - Minimum and maximum values for each dimension 
                   array [2, 3, ndset]
       PRINTIT   - If set, the variable data wil be printed.
                   Default:  PRINTIT = 1
       TRUNCATE  - If set, Delete source information.
                   Default: Truncate = 1
     
     Example:
        Print the variable information for variable 5 for the current dataset.
           inqvar, 5
    
        Print the variable information for variable 5 to 8 for the current dataset.
           inqvar, 5, 8
    
        Print the variable information for all variables beginning with src
           inqvar, '^src'
    
     Original version:  July 29, 1999, lpm
    

    (See ../pfidl/pdb/inqvar.pro)


    OPENPDB

    [Previous Routine] [Next Routine] [List of Routines]
      Open a PDB file.  The current file pointer is set to this file id and 
      the dataset names are stored.
      format: OPENPDB [, File] [, Fileid ] [, Error = error] [, NDSET =ndset]
                      [, PATH = path] [, FILTER = filter] [, HELP = help]
                      [, NAMES = names] [, MODE = mode] [, FILEID = fileid]
      where:
        File   - name of the PDB file to be opened.  
                 If file is omitted or undefined or is not a string,
                 then PICKFILE will be used to select a file.
                 The initial path in PICKFILE is the current directory or
                 the PATH to the last file selected.
                 NOTE: PATH and FILTER may be used to set the initial path and
                       filter for PICKFILE.
                 NOTE: FULFNAM procedure is used to handle environment variables
                       See FULFNAM for details
        Fileid - user specified file id 
                 (If fileid is specified, it will be used as the file id.  If 
                 fileid is not provided or is zero, a value will be 
                 provided; default value is the first unused integer greater
                 than 0.  If fileid is provided but has been used for another 
                 file, the program will provide a default value.
                 If positional parameter is valid, keyword will be ignored.
        Mode   - Open mode: Read Only, Write (Create), Append (READ/WRITE) 
                 (Default = Read Only)
                 Mode may be a number (1, 2 or 3) or a string.
                    (Read, Write, Append)
                 If a string is used only the first letter will be checked.
                 If the first letter is not a r, w, or a then mode = 1 (READ_ONLY).
    
        Error  - Error parameter
                 If this error is zero, no error encountered.
                 If Error = -99, file not found
        help   - Print a help text
        PATH   - Path to the current file 
                 Default is the current directory in the first call to OPENPDB but
                 the default path is changed to the final path selected is 
                 retained as the default in the next call to openpdb.
        FILTER - File filter - The default may be set in USERQSINIT; if undefined
                 the default is '*'.  The default filter is set only with
                  USERQSINIT or SETDEFAULT.
        NDSET  - Number of datasets
        NAMES  - A string array of dataset names
        SINGLE - If set, a single file will be opened.
    
      Examples:
        Open a PDB file with the default file id
          openpdb
        Open a PDB file, 'users/test', with the default file id
          openpdb, '/users/test'
        Open a file to be selected from a menu with a file id of 14
             openpdb, ' ', 14
         openpdb, 0, 14
         openpdb, file= 14
        Determine keywords and parameters for openpdb
          openpdb, /h
    

    (See ../pfidl/pdb/openpdb.pro)


    READPDB

    [Previous Routine] [Next Routine] [List of Routines]
      Reads a PDB dataset into a structure array.  Procedure options are explained
      below.
      Note: Cell or element data will be moved to the nodes.  All data except 
            
            
    
      Format:  READPDB, STRUCT/WDF [, DATASET] [, TVALUE] [, /INDEX]
                 [, FILEID = fileid]  [, GRID = grid] [, /DOUBLE] [, /MATRIX]
                 [, /STRUCTURE ] [, /NODE_VALUES] [, VOID_FRAC = void_frac]
                 [, IERROR = Ierror]
      where:
        STRUCT/WDF- Structure Array number or WDF array if TVALUE has 2 elements
                    One dimensional data is stored versus time in a wdf array.
                    For scalar data, the value is returned in STRUCT/WDF.
                    If an multiple arrays are read then WDF may be an array.
       NOTE: Dataset must be provided unless grid is set.
        dataset   - indicates a PDB dataset number or 
                    a search string for dataset comments.  
                    (Not required if GRID is set.)
            See: GET_DSET for more details
        TVALUE    - Time value for the dataset.
                    Default: All time values will be read.
                    If TVALUE has 2 elements these are interpreted as [K,L] values.
                      K, L are from 2 to number of zones in each direction.
                      Use XY2KL or CURPDB to get KL values.
        INDEX     - If ZVALUE is given and index is set then the value of ZVALUE 
                    is assumed to be a grid index in the Time array. If INDEX 
                    is set then TVALUE goes from 1 to the maximum number of
                    time steps.
        DOUBLE    - If data is double precision, the data will be saved as double 
                    precision (8-byte).  Default is to save as a float (4-byte).
        MATRIX    - If set, a matrix is returned in the structure.
                    This can be useful if the dataset was returned as a series of 
                    WDF arrays.
                    See also: READ_PDB to return the data as an idl variable.
        GRID      - If set, a node array will be returned.
        FILEID    - File id of the PDB file containing the data
                    Caution: Even if the read is not successful, the current file
                             id may be changed to FILEID.
        STRUCTURE - if set a structure will be returned in STRUCT
                    For wdf arrays, time and amplitude are returned in an array.
        NODE_VALUES - If set, the values are left on the nodes.
                   Default: Move all node values to the cell and distribute them on
                         the nodes.  Node values are then the average of the values
                         on the 4 sides of the nodes.
                         Exception: ut@history, vt@history are left on the nodes.
        VOID_FRAC - Variable is ignored unless the dataset is 4-dimensional. 
                    Variable is assumed to have 2 spatial dimensions and a fourth
                    dimension corresponding to time.
                    VOID_FRAC varies from 1 to the number of elements in the third
                    dimension.  The READPDB procedure will return only the slice 
                    corresponding to this slice in the third dimension.
                    Note:  Use READ_PDB to get the entire 4-dimensional array.
                    Example:  If F= F[NZ, NR, NV, NT], where NZ, NR and NT are the 
                    spatial and temporal dimensions, then VOID_FRAC = 2 will read
                    FF = F[*, *, 1, *] (Since IDL uses zero based indices) 
                    If TVALUE is provided, then a two dimensional array is returned.
        IERROR    - Returns 0 if no errors
    
      Examples:
        Read dataset 34 into structure 1 from file with file id of 4.
          readpdb, 1, 34, fil = 4
    
        Read dataset with 'KE' into structure 2
          readpdb, 2, 'KE'
    

    (See ../pfidl/pdb/readpdb.pro)


    READ_PDB

    [Previous Routine] [Next Routine] [List of Routines]
      Reads a PDB dataset into an IDL array.
      This is intended as a utility function.
    
      Format:
         ARRAY =  READ_PDB( Dataset# [, IER] [, FileID = FileID]
                          [, TYPE = type]  [, IJKLIST = ijklist])
      where:
          ARRAY    - IDL array of the stored values
                     The following types are supported:
                       CHAR, SHORT, DOUBLE, FLOAT, INTEGER, LONG
          Dataset# - Dataset 
                     This is the number of the dataset sorted alphabetical
                       corresponding to the dir command.
                     or a unique string corresponding to the desired dataset.
          IER      - If zero, read successful.
          FileID   - PDB file id
          TYPE     - String for the dataset type being returned
                     valid types are integer, float, double, and char
          IJKLIST  - Do indices for i, j and k dimensions 
                     3 elements per dimension: start, stop, skip
    

    (See ../pfidl/pdb/read_pdb.pro)


    SETPDB

    [Previous Routine] [Next Routine] [List of Routines]
       Set the current file pointer to file with specified pdb file id
       Format: SETPDB,  fileid, ierrror = ierror
       where:
          fileid - file id of desired file
          ierror - error parameter
                   returns zero if no error
       Note:  If fileid is undefined or is zero, nothing is done.
        Example:
       Set the current file pointer to the file with a file id (fid) of 3
          setpff, 3
    

    (See ../pfidl/pdb/setpdb.pro)


    SHOWPDB

    [Previous Routine] [Next Routine] [List of Routines]
      Show all opened PDB files, 
      their file id (fid) and indicate the location of the current file pointer.
      The current file id, and arrays of the user file ids and filesnames
        can be received as keywords.
      Format: SHOWPDB [, current = current] [, ufid = ufid]
                  [, filename = filename]  [, NUMBER= number]
      where
             current - user file id of the current file
             ufid    - array of user file id's
             filename- Array of file names corresponding to the ufid's
             number  - number of files open
                       Note: Number of datasets available with NDSPFF and PFF_INFO
             quiet   - If present and not zero, send no output to terminal
      Example:
      Show the status, including file id, of all opened PDB files
        showpdb
      
      Get the filenames and user file id's for all open pdb files
      Do not send any output to the terminal
        showpdb, c= cur, u=u, num= n, fil= fil, /q
    

    (See ../pfidl/pdb/showpdb.pro)


    SLICEKL

    [Previous Routine] [Next Routine] [List of Routines]
     Name: SliceKL
     Purpose: Slice a structure along a K or L line.
     
     Format: SLICEKL, Structure, kval, lval, time, out = out.
         where:
            Structure - the type 9 structure to be sliced.
            Note: The following, KVAL, LVAL, TIME, range from 1 to the total number
            KVAL      - the K-Value index to be sliced
                        Set to zero to have as independent variable
            LVAL      - the L-Value index to be sliced
                        Set to zero to have as independent variable
            TIME      - the Time index to be sliced
                        Set to zero to have as independent variable
                NOTE:  Tindex will return closest index for a given time
            OUT       - Output Waveform Array. Default = 1
                        Waveform will be the structure parameter vs Kvalue, Lvalue, or Time
    
     Example:
        Get the waveform array for Temperatures vs Time for kvalue equal 2, and Lvalue = 3
        Temperatures are in structure 4.  Store the result in wdf array, 6.
            SLICEKL, 4, 2, 3, 0, out = 6
    
        Get the waveform array for density vs k-value at an lvalue of 4 and a time
          step of 100.  Assume density is in structure 5.  Store the waveform in 5
            SLICEKL, 5, 0, 4, 100, out = 5
     
    

    (See ../pfidl/pdb/slicekl.pro)


    TINDEX

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           TINDEX 
    
     PURPOSE:
           Function to return the index for the closest specified time.
    
     CALLING SEQUENCE:
    	IND = TIndex (STR, TIME, /Maximum)
       where:
           IND   - Index for output time closest to TIME
                   IND = -1 indicates an error.
                   valid values are [1, ntime]
           STR   - Structure array number of a type 9 FE structure
           MAXIMUM - If set time is ignored and the maximum time index is returned
           TIME  - Time for desired INDEX.
             
    
     EXAMPLE:
           Determine the index closest to 14.5 in structure 4
               ind = tindex(4, 14.5)
           Plot the output at the time closest to 15.2 for structure 3
               plotstr, 3, tindex(3, 15.2), /index
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, December 22, 1999
    

    (See ../pfidl/pdb/tindex.pro)


    WDF2STR

    [Previous Routine] [Next Routine] [List of Routines]
     Name: wdf2str, wdstart, nwdf, str
    
     combine wdfarrays into a structure.
     This is a temporary procedure.
     wdstart  - first wdf array
     nwdf     - number of wdf arrays
     str      - structure to receive the data.
     
     example:
      combine the first 21 wdfarrays into structure #3
    
        wdf2str, 1, 21, 3
    
      Writen by: L. P. Mix, 1/29/04
    

    (See ../pfidl/pdb/wdf2str.pro)


    WRI_VAR_PDB

    [Previous Routine] [Next Routine] [List of Routines]
      Writes a variable to a PDB file
      Note:  Use openpdb to open a new file.
    
      Format:  WRI_VAR_PDB, Name, Array
                 [, FILEID = fileid] [, IERROR = Ierror]
      where:
        Name      - Name of variable
        Array     - Data array ot be written.
                    Data should be character, float, double, short, or long
                    (LONGS are stored as PDB integers.)
        FILEID    - File ID of the desired file.
                    Default:  FILEID = 0  ;  Current file
        IERROR    - Zero if no problems
      Examples:
        Write array "X Axis (cm)" to the current file.
          WRI_VAR_PDB,  "X Axis (cm)", x
    

    (See ../pfidl/pdb/wri_var_pdb.pro)


    XY2KL

    [Previous Routine] [List of Routines]
       Name: XY2KL
      
       Returns the cell K and L values for input X and Y spatial positions
    
       NOTE: This feature may be accessed from the plotgrd command.
       Note: PDB indices are assumed to start at 1 ie [1,1] is the lower left corner
    
       PROCEDURE:
             This routine looks for the cell with the closest midpoint and 
             then checks to determine if the point is in that cell.
             If the point is not in the closest cell then the routines checks to
             see if the closest cell is in a bow tie. 
       
       Format:
           POINT = XY2KL(X, Y, STR [, TIME] [, /QUIET] [, INDEX = index] 
         where
            POINT      - K and L coordinates for the cell containing X and Y
            X, Y       - Spatial locations
            STR        - Grid structure used for the current plot.
            TIME       - If defined then used to determine the time of the grid
                         with the values in X and Y.
                         Default is TIME=1, /INDEX
            INDEX      - If set, Time is taken as an index =[1, 2, ...N_time]
                         If time = zero or integer=1 then time index is 1
            QUIET      - If set, no output to the terminal
            scalar     - returned with the scalar node index in the range [1,nnodes]
        Example:
            Print the location of a point (3.5, .3) in K and L coordinates for the 
            initial grid location. Structure with the grid data is 12
               print,  XY2KL(3.5, 0.3, 12)
    

    (See ../pfidl/pdb/xy2kl.pro)