Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


FXGOPEN

FXGOPEN

Name


  FXGOPEN

Author


  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
  craigm@lheamail.gsfc.nasa.gov
  UPDATED VERSIONs can be found on my WEB PAGE:
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

Purpose


  Open generic resource as a seekable file.

Major Topics


  File I/O, Pipes, URLs, FITS

Calling Sequence


  FXGOPEN, UNIT, RESOURCE, ACCESS=ACCESS, ERRMSG=ERRMSG

Description



  FXGOPEN opens a generic "resource" for reading or writing. A
  "resource" can be a file or a Unix pipe, or a standard network
  URL for the http, https, or ftp protocols. Networked URLs are
  handled using the Unix command-line program called 'curl'.
  Readable resources are fully random access. You are permitted to
  perform seek operations on both files and streams such as Unix
  pipes. In the case of a stream, the stream is read upon demand
  and saved to an on-disk cache.
  FXGOPEN also automatically recognizes some standard Unix file
  extensions and operates on them. For example, files ending with
  '.gz' are recognized as being compressed with gzip, and are passed
  through gzcat to uncompress them. You can display existing
  filename extension mappings and add new ones using the FXMAKEMAP
  procedure. This feature also worked with files retrieved over the
  network, as long as the processing command declared with FXMAKEMAP
  is able to accept '-' to indicate the data is supplied via
  standard input.
  The UNIT number is allocated using GET_LUN; however, the internal
  implementation may allocate more LUNs. Therefore you must use
  FXGCLOSE to close the LUN and be sure that all resources are
  deallocated.
  You must use the specialized 'FXG' style functions to read, write
  and seek on the resulting unit number:
    FXGOPEN - open resource
    FXGCLOSE - close resource
    FXGREAD - read from resource
    FXGWRITE - write to resource
    FXGSEEK - seek on resource (i.e., perform POINT_LUN)
    FXGFILTERED - determine if resource is a normal file.

Inputs



  UNIT - FXGOPEN will return a LUN in this variable. It should be
          subsequently read and written with FXGREAD, FXGWRITE, and
          closed with FXGCLOSE.
  RESOURCE - a string, describing the resource to be opened.
              FXGOPEN will automatically determine how to open it
              according to:
              * If a filename the suffix may be mapped according to
              FXMAKEMAP. In that case the appropriate pipe command
              is opened as a Unix pipe with FXPOPENR.
              * If a string beginning with "|" then the remaining
              part of the string is interpretted as a Unix pipe
              command, to be opened with FXPOPENR.
              * If a URL (uniform resource locator), then it is
              accessed. Currently supported protocols are:
                file - a local file
                http - a file served by a web (HTTP) server
                ftp - a file served an FTP server
              I would like to add some sort of in-memory files,
              probably with a "mem" protocol.

Keyword Parameters



  ACCESS - a string, set to the access privileges of the resource.
            Possible values are:
 
              'R' - read-only
              'W' - write/create
              'RW' - write/update
            Not all protocols support writing (for example, none of
            the "pipe" or network protocols supports writing).
            DEFAULT: 'R'
  ERRMSG - If a named variable is passed with this keyword, an error
            message is returned: the empty string indicates success;
            a non-empty string indicates failure. If a named
            variable is not passed, and the ERROR keyword is not
            used, then execution is stopped upon an error.
  ERROR - If a named variable is passed with this keyword, the error
          status is returned: a zero indicates success; non-zero
          indicates failure. If a named variable is not passed, and
          the ERRMSG keyword is not used, then execution is stopped
          upon an error.
  SUFFIX - Force a particular file type by specifying the suffix.
            Default is to extract the suffix from the file name
            itself.

Example



  fxgopen, unit, 'myfile.gz', errmsg=errmsg
  if errmsg NE '' then do_error_message
  bb = bytarr(1000) ;; Read 1000 bytes
  fxgread, unit, bb
  fxgclose, unit
  This example opens the file myfile.gz using FXGOPEN. It is
  automatically gunzip'ed on demand as the request for a 1000-byte
  read is made.

Modification History


  Written, 1999, CM
  Documented, 02 Oct 1999, CM
  Added correct ERROR keyword behavior, 04 Oct 1999, CM
  Changed copyright notice, 21 Sep 2000, CM
  Modified to use ARG_PRESENT for ERRMSG and ERROR, 21 Sep 2000, CM
  Added SUFFIX keyword, 31 Oct 2000, CM
  Added the HTTP and FTP protocols using curl, 22 Oct 2006, CM

Todo


  * Make more windows friendly
  $Id: fxgopen.pro,v 1.5 2009/02/12 02:32:50 craigm Exp $



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us