# scan1d__define.pro

At present this program is installed in the /usr/local/epics/extensions/bin/$HOST_ARCH directory. This program is written in IDL 5.0 object programming language . It allows the IDL user easily to access 1D scan data captured by the data catcher without bringing up data catcher or viewer.

For proper operation of the scan1d object, a user first has to make sure that the IDL 5.0 or later is used by his environment settings.

In order to access scan1d object from other IDL program, a user has to make sure that the following environment variables are set before invoking IDL :

         setenv EPICS_EXTENSIONS  /usr/local/epics/extensions

         setenv IDL_STARTUP $EPICS_EXTENSIONS/bin/$HOST_ARCH/viewer_startup.pro

and make sure including the directory /usr/local/epics/extensions/bin/$HOST_ARCH in his/her IDL search path.

From the unix operating system to access IDL scan1d object class by entering :

         idl  go_scan1d

The files u_read.pro, plot1d.pro, and scan1d__define.pro are automatically loaded into IDL 5.0 for user.

For an example to create a 'scan1d' object with variable name as v1d, where the 1D catcher data is saved in the file 'junk2':

         v1d = obj_new('scan1d',file='junk2')

To get the positioner array PA and detector array DA for scan number 10, plus plotting and listing windows:

         v1d->read,10,DA=da,PA=pa,/plot,/list

# List of Routines

- SCAN1D::ASCII
- SCAN1D::OPEN
- SCAN1D::PLOT
- SCAN1D::POINT_LUN
- SCAN1D::PRINT
- SCAN1D::READ
- SCAN1D::READINDEX
- SCAN1D::WRITEINDEX

# Routine Descriptions

## SCAN1D::ASCII

[Next Routine] [List of Routines]

     NAME:
    	scan1d::ASCII

     PURPOSE:
           This method allows the user to create a list of ASCII data files
           based on the user specified list of 1D scan numbers. The name
           convention of each ASCII file will be the 1D scan file suffixed
           with its 4 digit scan number.

     CALLING SEQUENCE:
           Obj->[scan1d::]ASCII, List, /NOWIN

     ARGUMENTS:
         List:      List is used to specify the sequence of 1D scans to be
                    generated. It can be a list of short integers which
                    explicitly specify the desired scans or it can be
                    string variable. If it is a string, it will be parsed
                    into a list of scan number first by this method.
                    The user has to insure that the number entered is valid
                    for normal operation of this method.

     KEYWORDS:
         NOWIN:     If specified, only the ASCII files will be created but the
                    xdisplayfile window will not be shown.

     EXAMPLE:
         Example 1 creates the ASCII data files for the scan # [10,20,30] from
             file 'junk2', and each file will be displayed automatically.
             The object v1 needs to be defined only if it is not yet defined.

             v1 = obj_new('scan1d',file='junk2')
             v1->ASCII,[10,20,30]

         Example 2 creates the ASCII data files for the scan # 10, 20 to 30, and
             40 from the 'junk2', and no ASCII file will be displayed.

             v1->ASCII,'10,20-30,40',/NOWIN

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 26, 1998.
    	xx-xx-xxxx      comment

(See scan1d__define.pro)

## SCAN1D::OPEN

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	scan1d::Open

     PURPOSE:
           The method opens the input data file according to the binary type.
           It supports both native binary type and XDR binary type.

           This method is automatically called by the ReadIndex method.

     CALLING SEQUENCE:
           Obj->[scan1d::]Open, Filename [,Wid]

     ARGUMENTS:
      FILENAME:  Specifies the input 1D scan file used (generated by data catcher)
      WID:       Optional input, specifies the input droplist widget ID to reflect
                 the binary TYPE

     KEYWORDS:
         None.

     EXAMPLE:
        Following example show how to explicitly open the 1D scan data file 'junk2'
        The v1 object needs to be defined only if it is not yet defined.

             v1 = obj_new('scan1d')
             v1->open,'junk2'

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 26, 1998.
    	xx-xx-xxxx      comment

(See scan1d__define.pro)

## SCAN1D::PLOT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	scan1d::Plot

     PURPOSE:
           The method reads and plots the next scan record from the opened
           logical unit. Scan record supports 4 positioners and 15 detectors.
           Default option all present detectors will be plotted. If X vector
           is a constant value then vector index will be used in X axis.

     CALLING SEQUENCE:
           Obj->[scan1d::]Plot [,Seqno] [,IX=#] [,IY='#,...']

     ARGUMENTS:
         SEQNO:       Optional, if specified the specified record will be read
                      and plotted. Otherwise the next record from the current
                      file pointer will read and plotted.

     KEYWORDS:
         IX:          Optional, it specifies the positioner number to be used
                      as X axis.
                      If not specified, the positioner one's vector is used.
         IY:          Optional, it specifies the list of detector numbers to
                      be plotted.
                      If not specified, every existing detector will be plotted.
                      If specified, only the entered detectors will be plotted.

     EXAMPLE:
        Following example plots the first and the 10th record from the file 'junk2'.
        The object v1 needs to be defined only if it is not yet defined.

             v1 = obj_new('scan1d',file='junk2')
             v1->Plot
             v1->Plot,10

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 26, 1998.
    	xx-xx-xxxx      comment

(See scan1d__define.pro)

## SCAN1D::POINT_LUN

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	scan1d::Point_lun

     PURPOSE:
           The method moves the file pointer to the end of the specified scan
           record and ready to read the next record.

     CALLING SEQUENCE:
           Obj->[scan1d::]Point_lun, SEQNO

     ARGUMENTS:
         SEQNO:   Specifies the zero based scan record number.

     KEYWORDS:
         None.

     EXAMPLE:
        Following example moves the file pointer to the end of 10th record.
        of the 1D scan file 'junk2'.
        The object v1 needs to be defined only if it is not yet defined.

             v1 = obj_new('scan1d',file='junk2')
             v1->point_lun,10

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 26, 1998.
    	xx-xx-xxxx      comment

(See scan1d__define.pro)

## SCAN1D::PRINT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	scan1d::Print

     PURPOSE:
           The method dumps the current contents of the index object.

     CALLING SEQUENCE:
           Obj->[scan1d::]Print

     ARGUMENTS:
         None.

     KEYWORDS:
         None.

     EXAMPLE:
        Lists the index object corresponding to 'junk2'.
        The object v1 needs to be defined only if it is not yet defined.

             v1 = obj_new('scan1d',file='junk2')
             v1->Print

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 16, 1998.
    	xx-xx-xxxx      comment

(See scan1d__define.pro)

## SCAN1D::READ

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	scan1d::Read

     PURPOSE:
           The method reads a scan record from the opened logical unit and
           returns the user desired data components through the keyword
           specification.

     CALLING SEQUENCE:
           Obj->[scan1d::]Read,No,/List,/Plot,pa=pa,da=da,np=np,nd=nd,...

     ARGUMENTS:
         NO:       Optional. If not specified the next record from the current
                   file pointer will be read in. If the scan # is specified,
                   then the file pointer will be moved to the beginning of
                   the desired scan record before reading in the next set
                   of scan record.

     KEYWORDS:
      PLOT:        To view the DA array after reading in the data if specified
      LIST:        If /LIST specified then the ASCII PA & DA array will be saved
                   in default file name 'temp'. If LIST='filename' is specified
                   then the 'filename' will be saved.
      NOWIN:       If /NOWIN specified, the ASCII files will be created but will
                   not be displayed by the scroll window.
      NP:          Returns the number of positioner vectors
      ND:          Returns the number of detector vectors
      PTS:        Returns the number of data points acquired for the scan
      PA[NPTS,NP]: Returns the positioner array
      DA[NPTS,ND]: Returns the detector array
      X_NAMES[NP]: Returns the string names of positioners
      X_DESCS[NP]: Returns the string descriptions of positioners
      X_ENGUS[NP]: Returns the string engineering units of the positioners
      Y_NAMES[ND]: Returns the string names of detectors
      Y_DESCS[ND]: Returns the string descriptions of detectors
      Y_ENGUS[ND]: Returns the string engineering units of the detectors
      SEQNO:       Returns current scan number
      SCANNO_2D:   Returns corresponding 2D scan number
      TITLE:       Returns plot title stored
      STAMP:       Returns time stamp and user ID stored
      FILE:        Returns the filename
      DEF[19]:     Returns 4 positioner and 15 detector presence indicators

     EXAMPLE:
        Following example read the scan record #10 from the 'junk2'.
        The object v1 needs to be defined only if it is not yet defined.

             v1 = obj_new('scan1d',file='junk2')
             v1->point_lun,10
             v1->read,da=da,pa=pa,pts=pts,np=np,nd=nd

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 26, 1998.
    	xx-xx-xxxx      comment

(See scan1d__define.pro)

## SCAN1D::READINDEX

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	scan1d::Readindex

     PURPOSE:
           The method reads the index file of a given 1D scan file. It is
           assumed that the index file is written in native binary format.
           If index file does not exist yet, it will be created by this
           method.

     CALLING SEQUENCE:
           Obj->[scan1d::]Readindex,Filename

     ARGUMENTS:
      FILENAME:  Specifies the input 1D scan file used (generated by catcher)

     KEYWORDS:
         None.

     EXAMPLE:
        Following examples reads in the index object corresponding to 'junk2'
        The following two examples are equivalent in scan1d object creation:

        Example 1

             v1 = obj_new('scan1d')
             v1->readindex,'junk2'

        Example 2

             v1 = obj_new('scan1d',file='junk2')

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 26, 1998.
           05-15-1998  bkc Catch error for nozeo (due to openw )

(See scan1d__define.pro)

## SCAN1D::WRITEINDEX

[Previous Routine] [List of Routines]

     NAME:
    	scan1d::Writeindex

     PURPOSE:
           The method creates the index file for the specified 1D scan file.
           Normally if the index file is not found for the scan file, it will
           be automatically called by the Readindex method.

     CALLING SEQUENCE:
           Obj->[scan1d::]Writeindex, filename

     ARGUMENTS:
         FILENAME:   Specifies the input 1D scan file name.

     KEYWORDS:
         None.

     EXAMPLE:
        Following example creates the scan index file for the file 'junk2'.

             v1->writeindex,'junk2'

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 26, 1998.
    	xx-xx-xxxx      comment

(See scan1d__define.pro)