FILE
Jump to navigation
Jump to search
Macro interface to Midas data(*.tmp,*.prm), text or other files
<FUNC> Function to perform: CLOSE, COPY, DETACH, EDIT, NAME, NEXT, OPEN,
PROTECT, READ, RENAME, SAVE, UNPROTECT, VIEW, WRITE
<LABEL> Label of results parameter that will reference Text or Data File object
<P1> First <FUNC>-dependent parameter
<P2> Second <FUNC>-dependent parameter
<P3> Third <FUNC>-dependent parameter
Enables a macro command to perform I/O with a Midas text or data file. If the
end-of-file is encountered during READ and DEBUG ON IO is applied, a WARNING
will be issued.
NeXtMidas supports a number of file types, not just Midas Blue files. A partial
list of supported files includes:
File Type Extension(s) Supporting Class
------------------------------ ------------ ----------------
* Midas Blue tmp, prm nxm.sys.lib.DataFile
* Text txt nxm.sys.lib.TextFile
* Comma-Separated-Value (CSV) csv nxm.sys.lib.CsvFile
* Audio wav nxm.sys.lib.DataFile
* Image jpeg,jpg,gif, nxm.sys.lib.ImageFile
bmp,wbmp,png
* Shapefile shp nxm.sys.lib.ShapeFile
dbf nxm.sys.lib.DbfFile
* Zip zip nxm.sys.lib.ZipFile
* Multi-Resolution Seamless sid nxm.map.lib.MrSidFile
Image Database (MrSid)
For a complete list of file extensions mapped to Java supporting class, type
nM> res reg.handlers.file
Functions:
CLOSE - FILE CLOSE <LABEL>
Close the file referenced by <LABEL>
COPY - FILE COPY <LABEL> <P1=target file>
Copy a generic, unopened file named <LABEL> to <target file>. This performs
a BINARY copy of the file.
One or more of the following modifiers can be attached to the COPY function:
/F - Overwrite target file if it exists
/M - Make directories as required if they do not exist
The output <target> file's size is pre-allocated to the input file's size
on disk (since NextMidas 3.1.2). This can be disabled via the
{PREALLOCATELENGTH=false} file qualifier on the output file name.
COPY/L - FILE COPY <LABEL> <P1=target file> (Since NeXtMidas 2.5.0)
Copy a generic, unopened ListFile named <LABEL> to another ListFile named
<target file>. This can be used to convert between file types (e.g. CSV to
PRM or PRM to CSV) provided that both types implement the ListFile
interface.
One or more of the following modifiers can be attached to the COPY function:
/F - Overwrite target file if it exists
/M - Make directories as required if they do not exist
See /PROPAGATE= (since NeXtMidas 2.5.0) and /PROPMASK= (since NeXtMidas
3.3.0) for options controlling the propagation of column definitions and/or
other header/keyword values.
Since NeXtMidas 3.3.0 it is possible to include output columns that are
automatically computed from the input file. This is done by adding one or
more of the following file-qualifiers to the output file:
TIME_NAME=[col] - Name of the column to be populated with the computed
time values. The time value inserted will be a Time
object (which will convert to String/number as needed).
This is only applicable when the input is:
- DataFile (time value taken from df.getTimeAt()), or
- PlotFile with UNITS=TIME_S or UNITS=TIMECODE (value
is computed from pf.getStart() and pf.getDelta())
ABSC_NAME=[col] - Name of the column to be populated with the computed
abscissa values. This is only applicable when the input
is:
- DataFile or PlotFile (value is computed from
pf.getStart() and pf.getDelta())
INDEX_NAME=[col] - Name of the column to be populated with the computed
index value. This applies to all file types and is
automatically computed based on the (zero-based) row
number.
The primary use of TIME_NAME=, and ABSC_NAME= is in a DataFile to CsvFile
conversion where this information would otherwise be lost. If TIME_NAME=
or ABSC_NAME= are used in a situation where they are not applicable, the
default value for that column (0 or "") will generally be inserted.
When using TIME_NAME=, ABSC_NAME= or INDEX_NAME=, if the column identified
already exists in the input file, the value from the input file will be
ignored in favor of the computed value (where applicable) -- EXCEPT when
the column name is given with a "+" prefix (e.g. TIME_NAME=+TIME) in which
case the value from the input file will be kept.
DETACH - FILE DETACH <LABEL=file> <P1=data_file_ext DEF=det> (Since 2.9.1)
Rename <LABEL=file> to <file's_basename>.<data_file_ext> (if it exists and
contains an attached header) and create a new detached header (BLUE) file.
The header is created on the same AUX as the original file and the data
offset is set such that the data portion of the input file is not disturbed
(i.e. the original file is not modified it will still contain an unused
header which is ignored by all Midas commands). This is the same as
"DETACH <file>" in X-Midas. For Example:
One or more of the following modifiers can be attached to the this function:
/F - Overwrite target file if it exists
/D - Split the <LABEL=file> into a header-only detached header (BLUE) file
and copy the data section into a data-only file
<file_basename>.<data_file_ext> (starting at offset 0). This similar
to using "NOOP origfile newfile{det=data_file_ext}"
nM> file detach testfile.tmp
nM> file detach/d testfile2.tmp raw
EDIT - FILE EDIT <LABEL>
Edit the opened .txt, .html, or .rtf file referenced by <LABEL>.
(reserved for future implementation)
NAME - FILE NAME <LABEL> <P1=pathlist> <P2=root name> <P3=extension>
Form a name in a system independent manner from <pathlist>, <root name>,
and <extension>, storing the assembled name into the results parameter named
<LABEL>. The <pathlist> parameter must be in the form (top,next,lower,...)
as shown in the example below. NOTE: On Windows, you cannot specify a
mapped drive in your path; you must use the full path. See AUXILIARY.
NEXT - FILE NEXT <LABEL> <P1=string>
Read the next valid line from the opened file referenced by <LABEL> into the
results parameter named <string>. This command interprets continuation
characters and comment characters as they are in macros, .KEY files, and
other Midas text files. If an end-of-file or file error occurs, <string>
receives the value "NULL".
OPEN - FILE OPEN <LABEL> <P1=filename>
Open a file named <filename> and store a reference to resulting TextFile,
DataFile or BaseFile object in the results parameter named <LABEL>. The
following switches can be attached to the OPEN parameter:
File Type: (default based on file extension)
/D - Treat the file as a DataFile (Midas Blue File)
/T - Treat the file as a TextFile (can not be combined with /D)
In/Out Mode: (default is INPUT)
/A - APPEND to an existing file
/N - Create a NEW file for OUTPUT
/W - Open an existing file for INPUT/OUTPUT (this keeps file header
but does not advance write pointer to the end of the file - in
most cases /A is what you want, not /W)
If neither /T or /D is specified, the type is determined from the extension
or the {FG=x} qualifier and handled by the class named in REG.FILE.HANDLERS.
To apply other flags when opening the file use the FLAGS="" qualifier with
the flag names (Input|Output|Wrap|Append|Flush|NoAbort|Optional|Native):
nM> file open/t tag temp.txt{flags="APPEND|FLUSH"}
Once the file is open it is possible to find out what methods are available
using:
nM> query <LABEL>
** Note: In NeXtMidas 2.4.0 TextFile assumes that {FLAGS=NOABORT} is always
set. Since 2.5.0 this behavior is deprecated and NOABORT will only
be used when explicitly set. To disable the deprecation warnings,
set {FLAGS=NOABORT} or {FLAGS=FORCEABORT} when opening a TextFile.
PROTECT - FILE PROTECT <P1=filename>
Sets the protected flag in the header of a DataFile (.tmp or .prm) to true.
READ - FILE READ <LABEL> <P1=element>
Read the next element from the opened file referenced by <LABEL> into the
results parameter named <element>. If an end-of-file or file error occurs,
<element> receives the value "NULL" (when <LABEL> references a TextFile
object).
Note: Prior to NeXtMidas 3.3.0, calls to READ that were at end-of-file
erroneously returned a data buffer (with junk data) in cases where
<LABEL> pointed to a DataFile.
RENAME - FILE RENAME <LABEL> <P1>
Rename the unopened file named <LABEL> to <P1> One or more of the following
switches can be attached to the RENAME parameter:
/F - Overwrite target file if it exists
SAVE - FILE SAVE <LABEL>
Save the unopened file named <LABEL> by changing its extension to .prm
UNPROTECT - FILE UNPROTECT <P1=filename>
Sets the protected flag in the header of a DataFile (.tmp or .prm) to false.
VIEW - FILE VIEW <LABEL>
View the opened .txt, .html, or .rtf file referenced by <LABEL>.
(reserved for future implementation)
WRITE - FILE WRITE <LABEL> <P1=data>
Append <data> to the end of the opened file referenced by <LABEL>
(data is String when <LABEL> references a TextFile object)
(data is Data/Table when <LABEL> references a DataFile object)
Examples:
1. Define the structure and open a new type 3000 file for writing, write one
element, and then close the file
nM> file open/d/n tag temp{sr=(LAT/SD,LON/SD)}
nM> res tag.setdata(0,"LAT") 77.7
nM> res tag.setdata(0,"LON") 99.9
nM> file close tag
Note: the quotation of record names inside the method signature is HIGHLY
RECOMMENDED.
2. Open a file for reading and writing with its existing structure intact
(assumes file exists)
nM> file open/d/w tag temp
nM> res tag.getdata(0,LAT)
D: TAG.GETDATA(0,LAT) = 77.7
3. Load a row of data from the type 3000 file into a table
nM> file open/d tag temp
nM> res tab tag.getDataTable(0)
nM> res tab
T: TAB = Table of 2 entries
D: LAT = 77.7
D: LON = 99.9
NOTE: To read through and process an entire file from the macro language,
see FOREACH.
4. Form a full file name on a UNIX system
nM> file NAME fullname (home,user,temp) myfile ext
nM> res fullname
26S: FULLNAME = /home/user/temp/myfile.ext
5. Convert a comma-separated value (CSV) text file into a table
nM> file open filetag nxm.sys.dat.airports.csv{HEADERROWS=1}
nM> res t:tbl filetag.toTable(ROW_)
nM> file close filetag
6. Protect or unprotect a file
nM> file protect temp
nM> file unprotect temp
7. Copy a CSV file to a BLUE (.prm) file:
nM> file COPY/L test_list2_colors.csv{COLUMNNAMES='ID,COLR'} myfile.prm
8. Copy a BLUE (.prm) file to a CSV file:
nM> file COPY/L testxy3000.prm myfile.csv{HEADERROWS=1}
9. Copy a BLUE (.prm) file to a CSV file, but copy include the columns
named "ABSC" and "ORD" in the new file:
nM> file/PROPAGATE=FALSE COPY/L/F &
testxy3000.prm &
myfile.csv{HEADERROWS=1,COLUMNNAMES="ABSC,ORD"}
10. Define the structure and open a new complex type 2000 file for
writing that has 3 frames; write one frame, and then close the file
nM> file open/d/n tag temp{TYPE=2000,FORM=CF,FRAMESIZE=3}
nM> file write tag {F1=(1.0,1.0),F2=(2.0,2.0),F3=(3.0,3.0)}
nM> file close tag
Switches:
/CLEAN - Cleans the string from a READ or NEXT operation [DEF=FALSE]
/PROPAGATE=[T|F] - Used with COPY/L: Propagate column definitions from input
file to output file. [DEF=TRUE]
/PROPMASK=[mask] - Used with COPY/L: Mask controlling the propagation file
header values, other than the column definitions (which is
controlled by /PROPAGATE=). This is most frequently used to
propagate the xStart/xDelta values and the keywords
(e.g. /PROPMASK=ALL). Since 3.3.0 [DEF=NONE]
/TL= - Transfer Length (bytes) used with FUNC=COPY [DEF=32768]
Since 3.1.2
See Also: HEADERMOD, FNAME, FOREACH, ERASE
