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
			SEQential 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	if not selected the default is "FORmatteD" for sequential files
			DIRect options:
DIRect	---	dir	default if RecL = ... is an option
BINary	---	bin	this implies DIRect and RecL = 1. The difference is that READ and WRITE transfer the LEN(io_list) bytes instead of just 1 byte ( stream io ) 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 SEQential, 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 or on closing 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)
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: pool 3 lines/record	lines separated by $CRLF. 3 lines make 1 row in DLG(Edit=nam) or in direct matrix i/o
'NB=", ,'	* var, NoBreak between pairs of ". Records are separated by blanks	"this is col1" and "this is col2" defines 3 columns for this row. Without the NB=" 7 columns would be defined. Not all rows need to have the same number of columns .
"SL=3;5 ;"	SkipLines=3 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

SEQential options

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