chan					Channel or logical file number to assign to the file.
fileopt					Supported file options (see also, File Options):
					BSZ=num Block size ERR=stmtref Error transfer IOL=iolref Default IOList ISZ=num Open file in binary mode (see limits below) KEY=pswd$ Password to open file (see PASSWORD Directive) NBF=num Dedicated number of buffers OPT=char$ File open option string. REC=name$ Record prefix (REC=VIS(name$) can also be used) TIM=num Number of seconds to try and open the file for.
					When using the ISZ= option, the following limits apply to EFF files: ISZ=1 indicates greater than 2GB access ISZ>1 is limited to 2GB.
string$					Name of the file, table, or device to open. The string expression can include a specialty filename or file tag (e.g., *MEMORY*, [RPC], etc .).
stmtref					Program line number or statement label to which to transfer control.

Error Messages on OPEN

If you use a channel that is already OPEN, ProvideX returns an Error#14. If you try to OPEN a file that doesn't exist, it returns an Error #12: File does not exist (or already exists). In some circumstances (e.g., in trying to OPEN a printer twice), an Error#0 is generated.

-:KEYED "TEST",[1:1:6],,128
-:OPEN (5)"TEST"
-:OPEN (5)"TEST" ! Not okay: channel 5 is already in use
Error #14: Invalid I/O request for file state
-:OPEN (4)"TEST" ! Okay - "TEST" file can be OPEN on two channels
-:OPEN (30)PRINTER$
-:OPEN (10)PRINTER$ ! Not okay: Error #0: Record/file busy

About File OPEN Options

Use the OPT= parameter to define options for Windows COM ports. That is, in the Windows environment you can specify communications port settings for COM ports by adding, for example, OPT="9600,n,8,1,x" where the values represent baud rate, parity, data bits, stop bits and xon/xoff flow control. See also COM Ports and Serial Devices .

If the ISZ= option is used, ProvideX opens the file in binary mode. That is, ProvideX makes no attempt to analyze the file structure or contents. All subsequent access to the file / channel is done as if the file is an indexed file with a record size equal to the value set in the ISZ= option.

With ISZ=1, a READ RECORD directive will return 1 byte at a time (each logical record is 1 byte). For ISZ=1024, the data is returned 1024 bytes at a time, with the first 1024 bytes in IND=0, the next 1024 bytes in IND=1 and so on. You can gain access to the file sequentially or by using the index. A negative value notifies ProvideX to return up to the given number of bytes.

If you use ISZ=-1, ProvideX will not append record terminators to output lines printed to a file without a hanging comma. (Normally ProvideX appends a line feed to the end of such output lines in UNIX, or a carriage return and line feed in Windows and to the end of every record written to a serial file.)

If you use the BSZ= option, file access will be buffered in a buffer equal to the size you set for the option.

OPEN with PREFIX FILE Definition

You can have two fields in a prefix file data record. (A prefix file is a special Keyed file that contains information used when a file.) The first of the two fields is the path/filename of the real file to open. The second is an options field. ProvideX uses any options in this field as the OPT= values when opening the real path/filename. When opening a filename assigned in a prefix file directive, you can include additional OPT= values in the OPEN directive to have ProvideX append these as additional options for the true file being opened (i.e., the filename in the prefix file record).

Given a prefix file record containing:

Key="GLMAST"
DATA RECORD="[ODB]DSN;TABLE"+sep+"KEY=field1"

If you OPEN(chan)"GLMAST" then internally ProvideX will issue:

OPEN(chan,OPT="KEY=field1")"[ODB]DSN;TABLE"

If you OPEN(chan,OPT="REC=somedata")"GLMAST" then internally ProvideX will issue:

OPEN(chan,OPT="KEY=field1;REC=somedata")"[ODB]DSN;TABLE"

The TABLE option is a +PxPlus Exclusive

OPEN (chan[,fileopt])string$

The given file or device must be opened before the program can gain access to it. You can normally have a maximum of 127 files open at any time in a ProvideX session (less under some operating systems). In the extended file access mode 'XF' you can open up to 65000 files, subject to OS limitations.

In Windows use a colon (:) at the end of a filename to open an LPTn port number directly. For instance, LPT1 and LPT1: are considered to be the same device.

0010 OPEN (2,ERR=1000)"CSTMER"

OPEN INPUT (chan[,fileopt])string$

If you use the OPEN INPUT format, the program can't update the file (opened as read-only). Use this format to open a disk directory or to access files with read-only permissions. The OPEN INPUT directive under UNIX will not lock a text mode device.

OPEN LOCK (chan[,fileopt])string$

Using this format, the file is reserved for exclusive use prior to the OPEN. However, if another user already has the file OPEN, the LOCK format of the directive fails and ProvideX returns an Error #0: Record/file busy.

00010 BEGIN
00020 PRINT
00030 !
00040 LET in_file$=%wdx$+"D:\DATA\BATCH\R0000188"
00050 LET o_file$="D:\JUNK\TEST\TST_OUT"
00060 EXECUTE "[WDX]ERASE "+o_file$+",ERR=*NEXT"
00070 EXECUTE "[WDX]SERIAL ""D:\JUNK\TEST\TST_OUT"""
00130 LET no_file$="Y"
00140 LET in_file=HFN;
          OPEN (in_file)in_file$
00150 LET f$=FIN(in_file)
00160 CLOSE (in_file)
00165 LET pd=POS(DLM=in_file$,-1);
          IF pd<>0 \
              THEN LET inn_file$=in_file$(pd+1) \
              ELSE LET inn_file$=in_file$
00170 LET chars=DEC(f$(1,4))
00180 !
00190 LET blk_size=1024,done$="N",c=0
00200 IF chars<blk_size \
              THEN LET blk_size=chars
00210 !
00220 OPEN (in_file,ISZ=blk_size)in_file$
00230 LET o_file=HFN;
          OPEN LOCK (o_file,ISZ=blk_size)%wdx$+o_file$
00250 LET cur_byte=0,st_byte=0,se_byte=0
00260 LET r_c=blk_size
00500 ! !500
00510 ! Get Pos Of First ISA
00520 !
00530 READ RECORD (in_file,END=0700)in_rec$
00540 LET l=l+1;
          PRINT @(0,5),l
00550 WRITE RECORD (o_file)in_rec$
00555 LET by=by+LEN(in_rec$)
00556 LET tst=chars-by;
          IF tst<blk_size \
              THEN LET r_c=tst
00590 GOTO 0530

OPEN PURGE (chan[,fileopt])string$

If you use the OPEN PURGE format, the file will be locked and pre-cleared (purged)
prior to the completion of the OPEN statement.

OPEN LOAD (chan[,fileopt])string$

With the OPEN LOAD format, ProvideX assumes that the file is a static Keyed file and opens it for READ access only. ProvideX assumes that the file is a static Keyed file; i.e., no other task on the system will update this file. Whenever a portion of the file's key structure is read into memory, ProvideX keeps it in memory until you CLOSE the file. ProvideX gives you extremely fast access to static files by reducing the disk I/O and effectively caches the file in memory.

OPEN OBJECT (chan[,fileopt])string$

In Object Oriented Programming, the OPEN OBJECT directive indicates that a file being opened is for the exclusive use of an object. Only the object itself can alter the state of the file, and once the object is deleted, the file is automatically closed. Any external attempt to alter the state of the file returns Error #13: File access mode invalid.

The file is not closed on an external BEGIN. It will only be closed when the object is deleted, or by an explicit CLOSE (chan) from within the object. FFN and other file functions will not see the file while outside of the object thus cannot effect its position or other characteristics.e; however, system variables like HFN and CHN will reflect that the file is open, and some functions (PTH, FIN, FIB, etc.) can be used to query file attributes.

Example:

DEF CLASS "Customer"
PROPERTY CUST_NO$, NAME$,ADDR$,CITY$,SALESMAN$,AMT_OWING
LOCAL FILE_NO
!
FUNCTION FIND(X$)
ENTER C$
READ (FILE_NO,KEY=C$) ! Loads all the variables
RETURN 1
!
FUNCTION NEXT()
READ (FILE_NO,END=*NEXT); RETURN 1
RETURN 0
!
FUNCTION UPDATE()
WRITE (FILE_NO); RETURN 1
END DEF
!
ON_CREATE:
FILE_NO = HFN
OPEN OBJECT (FILE_NO,IOL=*)"ARCUST"
RETURN

Refer to the following functions and directives for related information on Object Oriented Programming:

OPEN DICTIONARY [ [DIRECTORY] string$ ]

If desired, files can be referenced by their logical table, as opposed to their physical file pathname. Before referencing file by their table name, you must define where the Data Dictionary is in the system by using the OPEN DICTIONARY directive.

For Example:

->OPEN DICTIONARY ! Open dictionary in current directory
->OPEN (1) TABLE "Customer"
->PRINT PTH(1)
C:\Pvxsrc\cstfile

The value in string$ should be either the pathname of the 'providex.ddf' file or the pathname of the directory in which the 'providex.ddf' file exists. If no string$ is provided, the current directory is assumed to contain the dictionary file.

The function PTH(*DICTIONARY) can be used to determine the current Dictionary being used.

Access by table name is a +PxPlus Exclusive

OPEN+ (chan[,fileopt])string$ ]

The compatibility mode OPEN+ directive is designed to simplify the conversion of applications from BBx^®. It provides the following functionality:

• Opens files that do not have recognized file headers in BINARY mode (same as ISZ=-1) as opposed to considering them as SERIAL text mode files.
  
• Processes field separators in the same manner as BBx, that is $00$, $0D, $0A$, and $1C$ thru $1F$ are all considered field seperators
  
• Changes the logic for a READ directive when dealing with a Binary file to scan up to next delimiter regardless of the length.
  
• Processes the following OPT= string values:
  

  O_RDONLY	Opens the file as INPUT only (same as OPEN INPUT)
  O_EXCL	Opens the file for exclusive access (same as OPEN LOCK)
  O_APPEND	Opens the file but sets the logical position for serial files at EOF so that subsequent data will be appended to the file.
  O_TRUNC	Opens the file and pre-clears all existing data from it. (same as OPEN PURGE followed by UNLOCK once cleared)
  O_CREATE	Opens the file if it exists else creates a text file (serial/binary file)

The conversion utility *conv.bbx/cv_gui has been enhanced as of build 9163 of PxPlus to allow for the automatic translation of all OPEN directives to OPEN+.

The compatibilty mode OPEN+ directive is a +PxPlus Exclusive

BBx® is registered trademarks of BASIS International Ltd.