# u_read.pro

At APS this program is installed in the /usr/local/epics/extensions/bin/$HOST_ARCH directory. This is a utility program for unformatted binary I/O. It supports both native and platform-independent XDR binary.

# List of Routines

- U_BI2XDR
- U_CLOSE
- U_OPENR
- U_OPENW
- U_READ
- U_REWIND
- U_WRITE
- U_XDR2BI

# Routine Descriptions

## U_BI2XDR

[Next Routine] [List of Routines]

     NAME:
           U_BI2XDR

     PURPOSE:
           This IDL routine converts native binary data into platform-independent
           XDR binary data.

           The input file should contain only pure native binary data.
           The output filename uses the input filename suffixed with '.xdr'.

     CALLING SEQUENCE:

           U_BI2XDR, 'filename' [,/VT] [,/Help]

     INPUTS:
           filename:   The data file should contain pure binary data objects.

     OUTPUTS:
           filename.xdr:   Output file.
                       It contains the converted XDR binary data objects.

     KEYWORD PARAMETERS:
           VT:     If a dumb terminal without X window server is used,
                   this option must be set, e.g. a telnet session.
           HELP:   If this keyword is set, a simple on line help is given.

     RESTRICTIONS:
           The input data file should contain pure binary data objects.

     EXAMPLE:

            U_BI2XDR,'catch1d.trashcan'

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 05-30-97.

           xx-xx-xx      iii  comment

(See u_read.pro)

## U_CLOSE

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

     NAME:
           U_CLOSE

     PURPOSE:
           This routine closes a file LUN opened for unformmated I/O.

     CALLING SEQUENCE:

           U_CLOSE, Unit

     INPUTS:
           Unit:     The LUN number to be closed.

     OUTPUTS:
           None.

     EXAMPLE:

            U_CLOSE, unit

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 03-23-95.

           xx-xx-xx      iii  comment

(See u_read.pro)

## U_OPENR

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

     NAME:
           U_OPENR

     PURPOSE:
           This routine assigns a LUN to the opened file for unformatted
           read only.

     CALLING SEQUENCE:

           U_OPENR, Unit, 'filename' [,/XDR] [,/Help]

     INPUTS:
           filename: Specifies the filename to be read by the U_READ
                     command.

     OUTPUTS:
           Unit:     The LUN number to be associated with the opened file.

     KEYWORD PARAMETERS:
           XDR:      This keyword specifies that the file is opened for
                     reading data in platform-independent XDR binary form.
           HELP:     If this keyword is set, a simple on line help is given.

     RESTRICTIONS:
           The data file should contain only consistant type of binary
           objects: either native binary data or platform-independent
           XDR data. No mixture type is allowed.

     EXAMPLE:

            U_OPENR, unit, 'catch1d.trashcan'

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 03-23-95.

           xx-xx-xx      iii  comment

(See u_read.pro)

## U_OPENW

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

     NAME:
           U_OPENW

     PURPOSE:
           This routine assigns a LUN to the opened file for unformatted
           write only.

     CALLING SEQUENCE:

           U_OPENW, Unit, 'filename' [,/Append] [,/XDR] [,/Help]

     INPUTS:
           filename: Specifies the filename to be created or opened for
                     data recording through using the U_WRITE command.

     OUTPUTS:
           Unit:     The LUN number to be associated with the opened file.

     KEYWORD PARAMETERS:
           APPEND:   This keyword specifies that the file is opened for
                     data appending. If not specified, write on the unit
                     will replace the old file content by the new data.
           XDR:      This keyword specifies that the file is opened for
                     writing data in platform-independent XDR binary form.
           HELP:     If this keyword is set, a simple on line help is given.

     RESTRICTIONS:
           The data file should contain only consistant type of binary
           objects: either native binary data or platform-independent
           XDR data. No mixture type is allowed.

     EXAMPLE:

            U_OPENW, unit, 'catch1d.trashcan'

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 03-23-95.

           xx-xx-xx      iii  comment

(See u_read.pro)

## U_READ

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

     NAME:
           U_READ

     PURPOSE:
           This routine reads an unformatted data entity from a file unit which is
           opened for unformatted read. It supports all IDL data type except the
           complex number and up to 2D array.

     CALLING SEQUENCE:

           U_READ, Unit, Var [,ERRCODE ,/Help]

     INPUTS:
           Unit:   The logic unit number returned by file open for unformatted
                   read.

     KEYWORD PARAMETERS:
           HELP:   If this keyword is set, a simple on line help is given.

     OUTPUTS:
           Var:    This variable holds the right type of data obtained from
                   the opened file, it can be either 1D vector, or 2D array.
       ERRCODE:    This variable holds the error code for the u_read. It
                   returns 0 if succeeded, returns -99 if failed.

     RESTRICTIONS:
           All the data must be created by the U_WRITE routine in order to be
           read by this routine.

     EXAMPLE:

           Read the first data entity from the 'test.dat' which was previously
           created by the U_WRITE routine.

             u_openr,unit,'test.dat'
             u_read, unit, X
             u_close,unit

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 03-23-95.

           05-30-97	bkc	Support opened file as XDR type data.
           10-13-97	bkc	Add the ERRCODE to indicate success or failure.

(See u_read.pro)

## U_REWIND

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

     NAME:
           U_REWIND

     PURPOSE:
           This routine locates the LUN file pointer at the beginning of the
           file.

     CALLING SEQUENCE:

           U_REWIND, Unit

     INPUTS:
           Unit:     The LUN number to be rewind.

     OUTPUTS:
           None.

     EXAMPLE:

            U_REWIND, unit

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 03-23-95.

           07-25-97      bkc  Rename routine rewind to u_rewind

(See u_read.pro)

## U_WRITE

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

     NAME:
           U_WRITE

     PURPOSE:
           This routine writes an IDL data array to a file unit which is
           opened for unformatted write. It supports all IDL data type except the
           complex number and up to 2D array.

     CALLING SEQUENCE:

           U_WRITE, Unit, Var [,/Help]

     INPUTS:
           Unit:   The logic unit number returned by file open for unformatted
                   write.

           Var:    This variable holds the data  array to be written to
                   the opened file, it can be scaler, vector, or 2D array.

     KEYWORD PARAMETERS:
           HELP:   If this keyword is set, a simple on line help is given.

     RESTRICTIONS:
           The data array can not be complex number. In order to make the
           data to be read by the U_READ routine, all the data saved must
           be using this routine.

     EXAMPLE:

           Create the 'test.dat'  and write the variable X to the file

             u_openw,unit,'test.dat'
             u_write, unit, X
             u_close,unit

           Create or append X to the 'test.dat'

             u_openw,unit,'test.dat',/append
             u_write, unit, X
             u_close,unit

           Create XDR platform independent data to the 'test.dat'

             u_openw,unit,/XDR,'test.dat'
             u_write, unit, X
             u_close,unit

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 03-23-95.

           05-30-97	bkc	Support opened file as XDR type data.

(See u_read.pro)

## U_XDR2BI

[Previous Routine] [List of Routines]

     NAME:
           U_XDR2BI

     PURPOSE:
           This IDL routine converts platform-independent XDR data into
           native binary data.

           The output filename uses the input filename suffixed with '.2bi'.

     CALLING SEQUENCE:

           U_XDR2BI, 'filename' [,/VT] [,/Help]

     INPUTS:
           filename:   The data file should contain XDR binary data objects.

     OUTPUTS:
           filename.2bi:   Output file.
                       It contains the converted native binary data objects.

     KEYWORD PARAMETERS:
           VT:     If a dumb terminal without X window server is used,
                   this option must be set, e.g. a telnet session.
           HELP:   If this keyword is set, a simple on line help is given.

     RESTRICTIONS:
           The XDR input file should be created by the u_write command.

     EXAMPLE:

            U_XDR2BI,'catch1d.trashcan.xdr'

     MODIFICATION HISTORY:
           Written by:     Ben-chin K. Cha, 08-10-98.

           xx-xx-xx      iii  comment

(See u_read.pro)