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