This is part of the HicEst documentation

OPEN a File for Read, Write, Sort, or MatrixExplorer

To start standard file operations and the spreadsheet-like MatrixExplorer with direct access to ordered and to non standardized files (CSV etc.).

⇾Home ⇾Contents ⇾more Input_Output ⇾ Examples

⇾existing_file ⇾file-filter ⇾file-matrix-io ⇾file_manager ⇾multi-line_records ⇾no-break_pairs ⇾read_edit_save ⇾skip_top_file_lines ⇾stream_io

Optional keywords:
(Syntax of optional keywords)
APPend BINary DIRect DREAWRI DenyREAd DenyWRIte ERror FIle FORmatteD FiLTer Format GetRecL IOStat LENgth NEW OLD RePLace ReadOnly RecL SCRatch SEQuential UNFormatted WriteOnly
option type mini sample Option sequence is irrelevant
(required )
txt fi=nam
    • OPEN(file='c:\ HicEst\text.txt') ! default open is FORmatteD SEQuential
  • the Windows is called if nam is blank or contains wildcards, i.e. nam = ' ', or nam = '*.*', or nam = '*.txt', or nam = '*.txt; *.lst', or similar.
    The full file path selected is returned in nam.
    • nam = "A*.txt" ! all txt files starting with A
    • OPEN(file=nam) ! opens file manager, selected file is opened
SEQuential options :
SEQuential --- seq sequential is the default OPEN if RecL is not an option
APPend --- app if not selected the default is 'rewind' (start at the beginning of the file)
UNFormatted --- unf
  • OPEN(FIle=name, SEQuential, UNFormatted) ! opens "name" for
  • READ and WRITE statements transfer the io_list bytes without translation as a single stream
  • no end of record marks are written
  • If UNFormatted is not selected the default is 'FORmatteD' for sequential files
  • with optional Rec=x in READ or WRITE transfers start at byte number x
  • Example for a cycle of the file "name":
    • OPEN(FIle=name, UNFormatted, LENgth=len) ! open name and get file length
    • ALIAS(workspace,1, nametext,len) ! define nametext as substring of workspace to read the complete file to
    • READ(FIle=name) nametext ! read complete file
    • EDIT(Text=nametext, ....) ! do all kinds of things
    • WRITE(FIle=name, Rec=1, CLoSe=1) nametext ! (over)write changes back to file
DIRect options:
DIRect --- dir default if RecL = ... exists as an option
BINary --- bin
  • same as UNFormatted SEQential with Rec=.. option, but slower for READs
  • implies DIRect and RecL = 1
  • READ and WRITE transfer the LEN(io_list) bytes instead of just RecL bytes
  • OPEN(FIle=nam, BINary, Length=L)
  • bytes = READ(File=nam, Rec=x, ItemS=n) list
    • start to read at byte x
    • the number of bytes actually read is in bytes
    • n is the number of list items actually read.
RecL num rl=80 record length
  • OPEN(FIle=nam, RecL=10) ! implies direct unformatted
  • READ(FIle=nam, rec= 2) ten_bytes ! is assigned byte11...byte20 of nam
FORmatteD --- ford default with SEQuential, with DIRect the default is unformatted
if none of NEW, OLD, or SCRatch is selected the file can be either NEW or OLD :
NEW --- new the file may not exist
OLD --- old the file must exist
SCRatch --- scr the file is deleted on WRITE(...CLOSE=1) or on exiting the script
RePLace --- rpl replace an existing file of the same name if it exists
GetRecL NUM grl=L get record length by evaluation of th Format string
LENgth NUM len=L get file bytes (for indexed file: lines).
L=-1: file does not exist
ReadOnly --- ro write(...) generates an error
WriteOnly --- wo read( ...) generates an error
DenyREAd --- drea no other process can open for read
DenyWRIte --- dwri no other process can open for write
DREAWRI --- dreawri no other process can open this file (long form: DenyREAdWRIte)
IOStat NUM ios=nr nr will be the error number
ERror LBL err=99 on error jump to label 99, no error message
Format= matrix rows have
(* variable length rows)
sample row:
(if numeric: 1.111, 222222, -333.333)
3F6 fixed length integer or real values, 3 columns 6 byte each
 1.111 22222 -333.3
3F8.1 fixed length real values, 3 columns 8 byte each
     1.1 22222.0  -333.3
3I8 fixed, integer values, 3 columns 8 byte each
       1   22222    -333
3EN10.1E1 fixed, real values, 3x engineering fmt
    1.1E+0   22.2E+3 -333.3E+0
'3A5' fixed, strings, 3 x 5 byte each
'A' variable length, string, 1 column
  • txt = filename(8,1) ! matrix file i/o: read row 8
'5 ,' * variable length, strings, 5 columns blank separated
alfa beta 3 delta 5.55
'5,;' * var, strings, 5 columns, comma separated
1, b 2, 3:c, 4..., and more
'2[],' * var, strings, 2 columns, [] embraced
bla[column 1]bla[column 2]bla
  • OPEN(FIle=nam, Format='2[],')
  • DLG(Edit=nam, Format='2a20')
  • Edits in 2 20-byte-columns without blabla
'2N[],' * as '2[],' if the type is needed for i/o
[-1.111] 2 num columns [22222] 
row1: " 1.11 22222.00" with:
  • DLG(Edit=nam, Format='2F9.2')
'100Ib1' fixed, 1-byte integer, 100 byte unsigned integer i = ICHAR( CHAR(i))
'100Ib2' fixed, 2-byte integer, 200 byte little endian storage:
'100Ib4' fixed, 4-byte integer, 400 byte the least significant bit/byte
'100Ib8' fixed, 8-byte integer, 800 byte has the lowest address
'100Fb4' fixed, 4-byte binary float, 400 byte little endian IEEE binary floating-point
'100Fb8' fixed, 8-byte binary float, 800 byte little endian IEEE binary floating-point
'Fb8,2A5' fixed, 8-byte binary float + 2 x 5-byte string
'ML=3,A,' * var, :
pool 3 lines/record
combine lines separated by $CRLF to make 1 row in DLG(Edit=nam) or in direct matrix i/o
'NB=", ,' * var, of characters. In the example records are separated by blanks and text within pairs of " is 1 record
  • "this is col1" and "this is col2"
defines 3 columns in this row.
Without the NB=" 7 columns would be defined. Not all rows need to have the same number of columns .
'SL=3;5 ;' , SL=3 skips 3 lines from top of file row 1 for all i/o is now the file row 4. SORT(..., PhySsort=1) will delete the skipped lines.

  • OPEN(FIle=nam, Format=fmt, FiLTer=flt)
  • a to filter along a column of a file, whether it contains or lacks one or more specified numerical values or strings:
  • FiLTer=[column:][< or > or & or ~](num or txt)[sep...]sep
  • the last character determines the separator between filter items
  • blanks allowed in filter items only
  • OPEN(FIle=diary, Fmt='2A20, 10i2,;,', FLT='1:&E,3:>3.7,3:<5.3,7:~0,', LEN=rows) ! opens diary with 2 columns 20 characters wide and 10 integer columns 2 characters wide:
filter for each row it is required that
1:&E column1 contains "E"
3:>3.7 column3 > 3.7
3:<5.3 column3 < 5.3
7:~0 column7 is not equal 0
"3.14" 3.14 contained, standard numerical tolerance is 1E-13
"4:hello" hello contained in column 4
"x,y" "x" or "y" in any character column
"~hello" "hello" is not contained
'&x,&y' "x" and "y"
'x,y$' "x,y" contained. The separator in this example is the trailing " $" instead the "," in the above examples
"1:&x,12:~y" requires "x" in column1, without "y" in column12

Note: returncode = OPEN(...) is the sum of (hexadecimal format):

OLD z'00001' NEW z'00002' SCRatch z'00004' RePLace z'00008'
BINary z'00010' ReadOnly z'00020' WriteOnly z'00040' DenyREAd z'00080'
DenyWRiTe z'00100' DenyREAdWRIte z'00200' formatted z'00400' UNFormatted z'00800'
DIRect z'01000' SEQuential z'02000' indexed z'04000' FiLTer z'08000'
initially sequential z'10000'

Support HicEst   ⇾ Impressum
©2000-2019 Georg Petrich, HicEst Instant Prototype Computing. All rights reserved.