OPEN (FILE)

ANSI

A file must be created or opened prior to any attempt to process data against it. The OPEN instruction initializes an existing file for later access by the program.

Where:

label

Optional. A Program Execution Label.

file

Required. A previously defined FILE variable that is opened.

name

Required. A previously defined Character String Variable or Literal containing the file name to open.

tcpip id:port

Required. A previously defined Character String Variable or Literal containing the IP address and port number of the server executing the Data Manager.

mode

Optional. A File Access Mode parameter defining the OPEN mode.

lock

Optional. A Record Locking Mode from the table below defining the record locking strategy.

unlock

Optional. A Record Unlocking Mode from the table below defining the record unlocking strategy.

wait

Optional. A Record Locking Wait Option from the table below defining the locked record wait strategy.

viewstring

Optional. A previously defined Character String Variable or Literal containing the view schema name that is found in database.

cancelchar

Optional. A previously defined Character String Variable or Literal defining the read cancel key. (9.6A)

checktime

Optional. A previously defined Numeric Variable or Literal defining the read cancel key check interval. (9.6A)

Flags Affected: NONE

Note the following:

1. {name} is the name of the physical text file that is opened. If a character string variable is specified, only the Logical String is used. If a literal is specified, the entire literal string, within the operating system's limitations, is used.

2. Which, if any, extension is assumed is as follows:

 

Compiler	Action
SUNDB86x	If the file name is terminated with a period (.), no extension is assumed. Otherwise, the extension TXT is assumed.
PLBCMP	The current screen definition file determines whether an extension is required. If not and the file name is terminated with the `Filename to extension delimiting character' in the screen definition file, no extension is assumed. Otherwise, the text file extension specified in the screen definition file is utilized.

3. If a specific drive and/or directory path is not provided, the current directory is checked for the file. If unsuccessful, any Logged On Drives are searched in ascending order for the file. The Logged On Drives are as follows:

 

Compiler	Action
SUNDB86x	The drives that have been set to Yes in the screen definition file through the SETDRIVE utility are searched. If not found, the directories that have been set in the PLB_PATH environment variable are searched.
PLBCMP	The directories that have been established in the PLB_PATH environment variable or SEARCHPATH instruction are searched.

4. A Datapoint style filename of `filename/ext:drv' is converted to a Sunbelt format as follows:

• If an extension is found, the '/' extension delimiter is changed to a Sunbelt extension delimiter character defined in the screen definition file. The default extension delimiter would replace the '/' delimiter with a period.

• If the file name contains more than one '/' character and does not contain a colon (:), the file name is not evaluated for a Datapoint extension. If a file name contains a single '/' character, the file name is evaluated for a Datapoint extension.

• The ':drv' specification in a Datapoint filename is changed to a substituted string defined by a UET keyword that must be defined by appending the Datapoint drive identification string to 'PLBVOL_'. In the above case, the UET string must be defined as 'PLBVOL_DRV={path}' in the environment table or in the 'PLBWIN.INI' file. If the UET keyword is not found, the runtime attempts to open the file with no changes. However, if the UET keyword is found, the runtime changes the filename to '{path}\filename.ext'.

 

Example: UET has environment entry defined as PLBVOL_D1=c:\data

 

OPEN      FILE,"name/txt:D1"

 

The actual file is opened as c:\data\name.txt.

5. For PLBCMP-GUI, if a null file name is used, the standard open dialog is displayed to allow the user to select the appropriate file.

6. If a file name starts with a dollar sign ($), it is scanned to the first file path or name delimiter. That string is then appended to 'PLBENV_' and the environment table or program information file (ini) is searched for a matching entry. If a matching entry is found, the string associated with the entry is substituted within the file name. An entire file name or path name may be substituted in this manner. For example, if the UET has an entry defined as PLBENV_ARDATA=\\server2\acct\ar
   
   OPEN FILE,"$ARDATA\company1.txt"
   
   The actual file is opened as '\\server2\acct\ar\company1.txt'.
    

7. Otherwise, the file name (including drive and/or path designation) must be in the valid operating system format and in the correct case for case sensitive systems like Linux:
    

OPEN	FILE,"B:FILENAME"	(MS-DOS)
OPEN	FILE,"/usr/file/fname"	(Linux)

8. Format (2) above defines the location of data manager. The {tcpip id} string can be provided in two formats:

 

    The first format allowed is nnn.nnn.nnn.nnn where each nnn value can be a value between zero and 255. This identifies the IP address of the server executing the Data Manager.

    The second format provides the Domain Name System (DNS) string that can be translated by a DNS Server to identify the host IP server address executing the Data Manager.

 

9. {port} is a number that identifies the basic process performed at server IP address. When {port} is not specified, the default port number used is 3934. The 3934 port number has been assigned as a registered user port number by IANA (Internet Assigned Numbers Authority). Care should be taken in selecting a port number to insure that a conflict with pre-assigned numbers does not occur. Please refer to RFC1700 documentation on the internet for port assignment information. The {port} number specified must be the same as specified for the Data Manager task executing at the server.

10. File names that are in excess of operating system allowances are truncated to meet those standards.

11. Files resident on a Datapoint RMSRAS server may be opened.

12. Attempting to OPEN a file that does not exist or using a mode (SHARE, SHARENF, EXCLUSIVE, and READ) that is incompatible with the privileges set for the file or with a mode the file is already open in, results in a trappable I/O error (see TRAP).

13. The optional {mode} parameter, if used, must be the last parameter on the instruction.

14. The {mode} may be a keyword or a decimal number or Numeric Variable as follows:

 

    Valid keywords are EXCLUSIVE, READ, SHARE, and SHARENF.

    If not specified, a MODE of SHARE is assumed.

    The string "MODE=" followed by a decimal number or Numeric Variable (four byte INTEGER) containing bit maps as follows:

 

Keyword	Value	Meaning
CMP_EOR_MASK	0xF	Mask for all EOR bit definitions
CMP_EOR_CR	0x1	MODE input request EOR type CR only.
CMP_EOR_CRLF	0x2	MODE input request EOR type CRLF.
CMP_EOR_LF	0x4	MODE input request EOR type LF only.
CMP_EOR_LFCR	0x8	MODE input request EOR type LFCR.
CMP_OPEN_MASK	0x70	File mode mask in OPEN/PREP.
CMP_SHARE	0x0	Share mode requested in OPEN/PREP when no bit is set within the bit definition mask range defined by CMP_OPEN_MASK
CMP_EXCLUSIVE	0x10	Exclusive mode requested in OPEN/PREP.
CMP_SHARENF	0x20	Share NoFlush requested in OPEN/PREP.
CMP_READ	0x40	Read mode requested in OPEN/PREP.
CMP_NOTEMPCLOSE	0x80	Keep file open across EXECUTE statements.
CMP_NOPREPTRUNC	0x400	Prep AFILE/IFILE without truncating the txt file.
CMP_NO_TRAN	0x1000	Do not put this file under a transaction. (9.0)
CMP_RESERVED_1	0x20000	DO NOT USE. This bit is ignored by the runtime. (9.6)
CMP_RESERVED_2	0x400000	DO NOT USE. This bit is ignored by the runtime. (9.6)
CMP_RESERVED_3	0x80000	DO NOT USE. This bit is ignored by the runtime. (9.6)
CMP_DONOTUSEIP	0x100000	Ignore the PLB_OPENUSEIP and PLB_PREPUSEIP keywords. Also, this bit definition indicates that a '|' redirection character in a file name is to be ignored. This bit gives the PLB application the flexibility to allow individual file variables to always be processed local to a client with minimal changes to the application while other file variables are generically being redirected to a Data Manager. (9.6)
CMP_NOSQLIO	0x200000	If this bit value is specified in the MODE bit mask values, the PREPUSESQL and OPENUSESQL keywords are not used for the FILE, IFILE, or AFILE being opened or prepared. This bit mask value also applies to the SETMODE PREPUSESQL and OPENUSESQL keywords. (9.6B)
CMP_LOCALCDF	0x1000000	This {mode} bit setting enables the Windows locale mode which causes the *CDFON delimiter character (i.e., normally comma) to be replaced by the Windows List Separator locale character setting (i.e., single character used!). (9.8A - Windows Only)
CMP_RESERVED	0x80000000	DO NOT USE. This bit is ignored by the runtime.

 

15. The {mode} keyword option expands functionality and makes OPEN or PREP instructions more dynamic for a user program. When the mode bit definitions specifies an EOR type, this EOR type overrides a type specified by a FORMAT keyword on a AFILE/FILE/IFILE variable declaration. In addition, the inclusion of an EOR type in the MODE causes the runtime to verify that the EOR type of a pre-existing file is the same as required by the MODE settings for all cases except when FORMAT=BINARY is specified in the file declaration. An error occurs if this EOR verification fails.

16. If the same File Definition Label ({file}) is opened a second time within the same program, the currently open file is CLOSEd before an attempt is made to initialize the new file.

17. The default sector size for the file is 256 bytes unless modified through the BUFFER/FIX/FIXED parameter in its declaration.

18. Operating system standard devices (COM1:|LPT1: under MS-DOS; /dev/lp1|/dev/tty01 under Linux) may be opened as files and processed using the sequential -1 or -2 access methods. However, the success of this type of technique depends upon the programmer's knowledge of the environment and any interface requirements. Sunbelt may provide examples of this technique but does not guarantee its practicality for use or provide support, except on a time and material basis.

19. Each FILE requires a single operating system file handle. The maximum number of files that may be opened concurrently is limited to those restrictions imposed by the environment in use.

20. If a FILEPI is active and {name} is null causing the activation of the file dialog, the FILEPI is terminated.

21. The {lock} parameter must be one of the following record locking modes:

 

Keyword	Specifies that ...
LOCKMANUAL	only READ statements with the 'LK' suffix are to invoke record locking.
LOCKAUTO	all READ statements invoke record locking for the file.

22. The {unlock} parameter must be one of the following record unlocking modes:

 

Keyword	Specifies that ...
SINGLE	Any locked record is automatically unlocked before a new record is locked by a READ instruction. This insures that only one record is locked at any given time for a file.
MULTIPLE	every record read for the file will lock the record. Records are unlocked only with the UNLOCK statement or when the file is closed.

23. The {wait} parameter must be one of the following record locking wait options:

 

Keyword	Specifies that the READ(LK) statements will...
NOWAIT	not wait for a record that is locked by some other program. The LESS flag is set.
WAIT	wait indefinitely to lock the record.
WAIT=nn	wait a specified number of seconds to lock the record. If the record cannot be locked within the specified time limit, the LESS flag is set.

24. Record Locking is not available when using the PLBCE runtime.

25. The {viewstring} data can be formatted to access various view schema information from a specific database (9.4). The following defines supported data formats for the {viewstring} data:
    
    VIEW="viewname"

In this case, the 'viewname' is a name that has been inserted into the 'sun_views' table that exists in the default schema database currently being used for a runtime. The default schema database for the runtime is established when the runtime initially loads. The PLB_SCHEMA keyword for the runtime initially establishes a schema database that is used as the default schema database. If the PLB_SCHEMA runtime keyword is not used, a default schema database named 'sunschema.db' is used in the same directory where the runtime executable is located.

 

VIEW="schemaname.viewname"

In this case, the 'schemaname' is a name that must exist in the 'sun_databases' table found in the default schema database currently being used for a runtime. When the 'schemaname' is found in the 'sun_databases' table, the final schema database file can be loaded and used to find the specified viewname definitions to be used for the file being opened.

 

VIEW="viewname|ipaddr"

In this case, the 'viewname' is a name that has been inserted into the 'sun_views' table that exists in the default schema database currently being used for a Data Manager that has a TCPIP/URL address specified as the 'ipaddr'. The 'ipaddr' can be a URL or a TCPIP:PORT address.

 

VIEW="schemaname.viewname|ipaddr"

In this case, the 'schemaname' is a name that must exist in the 'sun_databases' table found in the default schema database currently being used for a Data Manager. The 'ipaddr' can be a URL or a TCPIP:PORT address where the Data Manager can be accessed. The schema database accessed using the 'schemaname' at the Data Manager must exist at the server where the Data Manager is executing.

26. Before a view can be used in an OPEN instruction, the view schema data must already exist in the schema database. The SCHEMA instruction with the IMPORT keyword also loads the view data into a schema database.

27. The {cancelchar} value specifies the cancel character or key that aborts a READ operation (9.6A). If the {cancelchar} is a null variable or literal, the cancel support is disabled for this variable. If this keyword is not specified, the cancel character feature is determined by the current program/runtime default settings. This value can be specified as a single key for a character or a key name. The following key names are supported:

 

ESC, ESCAPE

F1, F2, F3, F4, F5, F6, F7, F8, F9, F10

F11, F12, F13, F14, F15, F16, F17, F18, F19, F20

F21, F22, F23, F24, F25, F26, F27, F28, F29, F30

F31, F32, F33, F34, F35, F36, F37, F38, F39, F40

UP,DOWN, LEFT, RIGHT

INS, INSERT, DEL, DELETE

HOME, PGUP, PAGEUP.PGDN, PAGEDOWN, END

 

28. The {checktime} value specifies the elapsed time in seconds used when checking for abort key (9.6A). The value must be in the range of zero (0) to thirty seconds. If a value greater than thirty is specified, thirty is used. If this keyword is not specified, the cancel character feature is determined by the current program/runtime default settings.

29. When a file variable is opened using a Linux OS PL/B runtime, the current SETMODE *LINUXREADLOCK={0|1} value determines whether Linux OS read locks may be used for PL/B read statements using this file variable opened for record locking. Also, note that the Linux OS read locks are only allowed for a file variable opened the LOCKAUTO, SINGLE, and NOWAIT parameters.
     

When a file variable is opened to use Linux OS PL/B read locks, the read locks are only used for these PL/B read statements:

 

FILE	READ
AFILE	READ, READKG, READKGP
IFILE	READ, READKS, READKP

See Also: Example Code, CLOSE, Disk I/O Instructions