OPEN: Initialize a file for read, write, sort, or matrix explorer (f)

OPEN a file is needed to:
- READ the file
- WRITE the file
- and with the Format option:
  - to SORT the file
  - to open the MatrixExplorer dialog on the file (spreadsheet-like file edit)
  - to directly read/write file matrix elements that could also be edited with MatrixExplorer

option	type	mini sample	Option sequence is irrelevant
FIle ( required )	txt	fi=nam	OPEN(file="c:\HicEst\text.txt") ! default open is FORmatteD SEQuential the windows file manager 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 stream io 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 reads, edits, and saves the file "name": OPEN(FI=name, SEQ, UNF, LENgth=len) ! open name and get file length ALIAS(workspace,1, nametext,len) ! define nametext as substring of workspace to get the full file READ(FIle=name) nametext ! start read at default byte 1 EDIT(Text=nametext, ....) ! do all kinds of things WRITE(FIle=name, CLoSe=1) nametext ! and 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 OPEN(FIle=checkfile, LENgth=L) ! returns L>0 for existing file
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=s	s will have error number
ERror	LBL	err=99	on error jump to label 99, no error message

Format
is needed as an OPEN() option for MatrixExplorer including
file-matrix-io
and SORT:
- - OPEN(FIle=nam, Format=fmt) ! minimum options for a file matrix
- The table below describes the Format option by examples
- different matrix column formats can be freely mixed.
- the
  last character of the Format string
  defines the separator between multiple format items, usually a komma. It should always be set for variable length records.
- ⇒ on details of Format options that are also used in READ and WRITE

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	ABCDEabcde12345
"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	........ABCDEabcde ........FGHIJfghij
"ML=3,A,"	* var, multi-line records : 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, no-break pairs 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 ;"	skip top file lines , 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.

FiLTer

flt=

OPEN(FIle=nam, Format=fmt, FiLTer=flt)

a
file-filter
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"

OPEN: Initialize a file for read, write, sort, or matrix explorer (f)

required

SEQuential options

with optional Rec=x in READ or WRITE transfers start at byte number x

DIRect options:

if none of NEW, OLD, or SCRatch is selected the file can be either NEW or OLD

last character of the Format string

Not all rows need to have the same number of columns

last character determines the separator

or

not

and