Directives 

Formats

Where: 

(The TABLE option was added in PxPlus v6.30.)
(The CREATE option was added in PxPlus v6.30. Support for the CREATE option for WindX was added in PxPlus 2018.)
(The FOR dependency option was added in PxPlus 2020.)

Description

Use this directive to open a file or device and assign a logical file number to it.

Note:
WindX in PxPlus supports the use of this directive via the [WDX] or [LCL] tags; e.g. OPEN "[WDX]somefile.ext". Non-PxPlus versions require you to encapsulate the command in an EXECUTE directive with a [WDX] tag (i.e. EXECUTE "[WDX]..."). See [WDX] Direct Action to Client Machine or [LCL] Access to Users Local Machine.

Error Messages on OPEN

If you use a channel that is already OPEN, the system returns an Error #14: Invalid I/O request for file state. If you try to OPEN a file that does not 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: Record/file busy is generated.

Example:

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 a variety of file types. For example, on ODBC/database files, the option string can provide record layout declarations, database connection options, etc. For *MEMORY* files, it can contain the key definitions, and on Windows COM ports, you can specify communications port settings (e.g. OPT="9600,n,8,1,x" where the values represent baud rate, parity, data bits, stop bits and xon/xoff flow control). See COM Ports and Serial Devices.

The OPT="ZIP" file option can be used with the OPEN CREATE directive to specify to PxPlus to create a ZIP file.

See the specific file type definitions in the Special Command Tags section for details on the various OPT= values supported by PxPlus.

Use the IOL= option to define a standard IOList to be used while the file is open. The system will use this IOList for all subsequent file READ, WRITE, EXTRACT or FIND statements where you do not explicitly supply variable lists. You can also use the REC= option to supply a prefix to be added to all the variables in the IOL= specification.

If the ISZ= option is used, the system opens the file in binary mode; that is, there is 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. For compatibility reasons, you can also use ISZ=-1, which works the same as setting ISZ=1.

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 is opened.) The first of the two fields is the path/filename of the real file to open. The second is an options field. Any value in this field will be passed 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 the system append these as additional options for the true file being opened (i.e. the filename in the prefix file record).

Example:

Given a prefix file record containing:

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

If you open(chan)"GLMAST", then internally the system will issue:

open(chan,opt="KEY=field1")"[ODB]DSN;TABLE"

If you open(chan,opt="REC=somedata")"GLMAST", then internally the system will issue:

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

TABLE Option

The keyword TABLE before the string$ indicates that the value provided is the logical table name for the file as defined in the currently opened data dictionary file. See OPEN DICTIONARY.

(The TABLE option was added in PxPlus v6.30.)

OPEN LOAD Caching

A new option included in PxPlus 2019 allows the system to locally cache data files/tables in memory resident keyed tables to improve performance. With this option enabled, the system will automatically convert an OPEN LOAD of a database table or any keyed file (VLR/EFF) to a memory file with the same data, key structure, IOList and embedded data dictionary elements. This reduces the number of SQL requests or disc/network requests for files that will remain static during batch processing.

See OPEN LOAD Caching.

(OPEN LOAD Caching was added in PxPlus 2019.)

Dependencies

The OOP interface included in PxPlus allows for the automatic linking of objects to other system components, such as programs, windows, controls, files and other objects. As these other components are closed or deleted, its linked objects will automatically have their usage count decremented. Potentially, the linked objects could also be freed up.

This allows programmers to leave much of the housekeeping logic related to objects up to the system, as opposed to having to worry about coding for it themselves. By linking objects to items such as the current window, the programmer no longer needs to worry about dropping the object when the window is deleted.

To establish this linkage, the file OPEN directive includes a FOR option where the programmer can specify the component that will be linked to the object.

Where:

(The object dependency capability for the OPEN directive was added in PxPlus 2020.)

See Also

CLOSE Close File
OPT( ) Return File Open Options
PREFIX Set File Search Rules
PASSWORD Apply Password and Encryption
Special Command Tags
Accessing ZIP Files

Format 1

Open File/Device Channel

OPEN [ CREATE ] [ END ] (chan[,fileopt]) [ TABLE ] string$ [ FOR dependency ]

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 session (less under some operating systems). In the extended file access mode 'XF', you can open up to 65000 files, subject to operating system limitations.

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

PxPlus supports the use of the OPEN CREATE directive with OPT="ZIP" to create ZIP files.

Note:
The actual number of files you can open at any one time depends on operating system parameters. Consult your system configuration information for details on how to increase the number of files you can open.

Example:

0010 open (2,err=1000)"CSTMER"

The following example uses the REC= option:

open (1,rec=ABC$,err=1000)"myfile"
read (1)A$,B$
print ABC.A$,ABC.B$

Format 2

Open for Read-Only Mode

OPEN INPUT (chan[,fileopt]) [ TABLE ] string$ [ FOR dependency ]

If you use the OPEN INPUT format, the program cannot 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.

Format 3

Open Locked

OPEN [ CREATE ] [ END ] LOCK (chan[,fileopt]) [ TABLE ] string$ [ FOR dependency ]

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 the program will be returned with an Error #0: Record/file busy.

Note:
Under UNIX, /dev/null and /dev/console files are not locked when opened; however, all other files are.

WindX Example

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

Note:
WindX supports the use of SERIAL and ERASE commands via the [WDX] tag. It is not necessary to embed these commands in an EXECUTE directive.

Format 4

Open Locked and Pre-Cleared

OPEN [ CREATE ] PURGE (chan[,fileopt]) [ TABLE ] string$ [ FOR dependency ]

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

Format 5

Open Static Keyed File Read Only

OPEN LOAD (chan[,fileopt]) [ TABLE ] string$ [ FOR dependency ]

With the OPEN LOAD format, the file is assumed to be a static Keyed file (i.e. no other task on the system will update this file) and is opened for READ access only. Whenever a portion of the file's key structure is read into memory, it will be kept in memory until you CLOSE the file. This yields extremely fast access to static files by reducing the disk I/O and effectively caches the file in memory.

OPEN LOAD Caching

A new option included in PxPlus 2019 allows the system to locally cache data files/tables in memory resident keyed tables to improve performance. With this option enabled, the system will automatically convert an OPEN LOAD of a database table or any keyed file (VLR/EFF) to a memory file with the same data, key structure, IOList and embedded data dictionary elements. This reduces the number of SQL requests or disc/network requests for files that will remain static during batch processing.

For example, a Sales report might want to access the Salesperson Name, Department and Vendor information when producing a listing. These files would likely not change during the report execution; therefore, they could be loaded in a quick access memory table. By caching the file contents in the memory file, the processing time for the report will improve, particularly in cases where the same file/table is being accessed repeatedly.

Since a file opened using an OPEN LOAD is read only, existing logic would remain intact with no application changes required.

See OPEN LOAD Caching.

(OPEN LOAD Caching was added in PxPlus 2019.)

Format 6

Open File for Use in Object (OOP)

OPEN OBJECT (chan[,fileopt]) [ TABLE ] string$ [ FOR dependency ]

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 an 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 and thus cannot affect its position or other characteristics; 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

The file is opened in the ON_CREATE. There is no need to worry about closing the file since the system does it automatically.

See Also

DEF CLASS Define Object Class
PROPERTY Declare Object Properties
FUNCTION Declare Object Method
LIKE Inherit Properties
PROGRAM Create/Assign Program File
RENAME CLASS Change Name of Class
STATIC Add Local Properties at Runtime
DROP OBJECT Delete Object
NEW( ) Create New Object
REF( ) Control Reference Count

Format 7

Open Dictionary

OPEN DICTIONARY [ [DIRECTORY] string$ ] [ FOR dependency ]

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.

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 PTH(*DICTIONARY) function can be used to determine the current dictionary being used.

(The TABLE option was added in PxPlus v6.30.)

Format 8

OPEN+ Compatibility Mode Open

OPEN+ (chan[,fileopt]) [ TABLE ] string$ [ FOR dependency ]

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$ through $1F$ are all considered field separators.
• Changes the logic for a READ directive when dealing with a Binary file to scan up to the next delimiter, regardless of the length.
• Processes the following OPT= string values:

The conversion utility *conv.bbx/cv_gui (as of PxPlus build 9163) allows for the automatic translation of all OPEN directives to OPEN+.

(The OPEN+ capability was added in PxPlus v7.00, build 9163.)

Formats 9, 10 and 11

Open Read and/or Write Pipes to Executable

OPEN (chan) "|"+exe_path$
OPEN (chan) "<"+exe_path$
OPEN (chan) ">"+exe_path$

Where:

You can interact with an external executable (exe_path$) by using | (pipes), which allow you to send data to the executable via standard input (stdin) and read data from the executable via standard output (stdout).

Example:

open (hfn)"|sqlite3.exe"
write record (lfo)selectcmd$
read record (lfo)response$
write record (lfo)".exit"
close (lfo)

BBx® is a registered trademark of BASIS International Ltd.