Open Display

From BR Wiki
(Redirected from OPEN display)
Jump to navigation Jump to search

The Open (OPE) Display statement activates a text file for input/output or opens a printer for output.

Comments and Examples

An OPEN statement must be executed for a particular file before any I/O statement can act on that file (except #0 and #255, #0 being reserved for the main BR window, and #255 for the printer).

This section discusses opening display files, which are one of three major file types in Business Rules (the other two file types are internal and external). Display files are text files that contain ASCII characters as data. It is often useful to think of them as "printer" files.

Display files can be opened for either INPUT or OUTPUT, but not both at the same time. Display files are restricted to sequential processing while internal files can be accessed as SEQUENTIAL, RELATIVE or KEYED; external files can be accessed SEQUENTIAL or RELATIVE. Internal files can be used for sorting and indexing while display and external files cannot.

Different sets of I/O statements are used with each type of file. Statements used with display files include:

Saving a Business Rules! program as source (.BRS) creates a display file. Display files can be created or modified with any text editor and most word processors that can save as plain ASCII text. Display files can be used to send data to other devices such as modems and printers.

Before doing input to or output from an existing file called STATES, a program must have a statement such as the following: 

00500 OPEN #2:"name=STATES",DISPLAY,INPUT

After line 500 is executed, the display file STATES could be used for input by using the file number, #2.

The following statement would create a new display file called ZIPCODES. 

00510 OPEN #3:"NAME=zipcodes,NEW",DISPLAY,OUTPUT

A string constant, string variable, or string expression can be used for the OPEN statement clause which indicates what file or device is to be opened. Consider the following examples: 

01000 OPEN #1: "NAME=CUSTOMER.DAT",DISPLAY,INPUT
01005 PRINT "Enter FILE NAME for balances"
01010 INPUT F$
01015 LET F$ = "NAME=" & F$ & ".DAT"
01020 OPEN #2: F$, DISPLAY, INPUT
01030 OPEN #3: "NAME=SALES" & STR$(MONTH) & ".DAT",DISPLAY,INPUT

Line 01000 shows OPEN using a string constant. Lines 1005 to 1020 show opening a file with a name constructed from a prompted keyboard entry. Line 1030 opens the file SALES10.DAT if the value of MONTH is 10. 

410 OPEN #0: "Srow=nn, Scol=nn, Caption=APPLICATION NAME", DISPLAY, OUTPUT
               -or-
420 OPEN #0:"Srow=nn, Scol=nn, Caption=APPLICATION NAME, Buttonrows=nn", DISPLAY, OUTPUT

Open #0 resizes the BR full screen window. This also lets you optionally sets the number of buttom rows (0-3). See Open Window for more information on windows.

OPEN file reference strings for Display files can contain COPIES=nn. The nn value will replace the new COPIES argument in SPOOLCMD.

In the following example, line 200 illustrates using OPEN with an output device: 

00200 OPEN #77:"name=COM1:", DISPLAY, OUTPUT

Future references to #77 would send data to the device (modem, printer, etc.) connected to the first serial communications port. See also the OPEN communications statement for using serial ports for two-way telecommunications. When LINPUT is used while EOL=NONE is active, it is possible to process incoming data one character at a time. The variable must be dimensioned to a maximum string length of 1: 

00010 DIM X$*1
00020 OPEN #1: "name=datafile,EOL=NONE",DISPLAY,INPUT
00030 LINPUT #1: X$  EOF DONE
00040 IF POS("AEIOU",X$)>0 THEN PRINT X$;" is a vowel"
00050 GOTO 30
00060 DONE: CLOSE #1

Syntax

OPEN #<file number> : {"NAME=<file ref>[, {NEW|USE|REPLACE}] [, RECL=<integer>] [, PAGEOFLOW=<integer>] [, <share spec>] [, RESERVE ] [, WAIT=<integer>] [, TRANSLATE=<file ref>] [, EOL=<spec>] ,HTTP=CLIENT"|<string expression>} ,DISPLAY ,{INPUT|OUTPUT} [<error condition> <line ref>][,...]

Defaults

1.) Use the existing file.
2.) Default record length is 132 bytes.
3.) 60 lines.
4.) NOSHR.
5.) Do not lock the file.
6.) Wait 15 seconds.
7.) No translation.
8.) CRLF for DOS systems; LF for Unix / Linux systems.
9.) Interrupt the program if an error occurs and ON is not active.

Parameters

The required "file-num" parameter is a numeric expression that must equal an integer from 1 to 999. Two special default values for "file-num" are provided to facilitate I/O from the keyboard and to the printer and screen. These special defaults are: #0 (reserved for the BR main window), and #255 (reserved for printer, equivalent to DOS PRN:). No OPEN is necessary for these two reserved values.

From this point, there are two possible paths through the OPEN display syntax. The top path will be described first. "NAME = file-ref" is a required parameter which specifies the file or device to be opened. This parameter can be a string constant, string variable, or string expression. Using Name=save will allow the user to select a file location and name to save under. And using Name=open will allow the user to select a file to open from the standard Windows open file location window. See File Ref in for more information about the file-ref syntax.

The "NEW" parameter indicates that the file to be opened must also be newly created. Error 4150 (duplicate file name) will occur if NEW is specified and the file already exists.

The USE parameter indicates that an existing file by the specified name should be opened, but a file by the specified name may not exist, in which case Business Rules will create a new file for it; so the OPEN statement needs to have the specifications for creating it.

The "REPLACE" parameter indicates that any existing file under the specified name should be freed and that a new file under that same name be created. There will be no warning that the file is being replaced when this parameter is used. See File I/O for more information about NEW, USE and REPLACE.

"RECL = int" is an optional parameter used to specify the maximum record length of the file being opened. The default is 132 bytes -both for new files and for existing display files. Any other value must be coded explicitly each time the file is opened (unlike internal files).

Used primarily to control page breaks with printers, the optional parameter "PAGEOFLOW=int" specifies the line number which will generate a PAGEOFLOW condition when that line number is printed or exceeded. See the On Error and Exit statements and PAGEOFLOW for more information.

Four options are available for the "share spec" parameter: NOSHR, SHR, SHRI and SHRU. NOSHR indicates that the current workstation is to have exclusive access to the file. No other opens are permitted to the same file until it has been closed. NOSHR is the default when a "share spec" is not specified. SHRI allows others to use the file for input only. Others may read but not change a file opened SHRI. SHR allows others to read and write an open file. In processing display files, individual records are not locked. This protection is not needed since the file cannot be opened OUTIN. SHRU operates the same as SHR; it is maintained for System/23 compatibility.

Even if your programs are not currently designed for multi-user or NetWork systems, it is a good idea to include share specifications for future portability. See Multi-User Programming for additional information.

"RESERVE" locks the file until otherwise specified; other users are denied access even when the file is not open. A reserved file is not released until a CLOSE statement with the RELEASE parameter has been specified or until a PROTECT file-ref, RELEASE command has been issued (this last command is ignored by the IBM PC-NetWork operating system). Exiting Business Rules also releases all files locked by that workstation.

The "WAIT= int" parameter specifies the number of seconds that Business Rules should wait for a locked record before generating error code 0061.

The "TRANSLATE=file-ref" parameter indicates that character translation is required for all input or output of C, V, G, N, ZD or PIC strings. The file-ref must identify either a 256- or 512-byte file. The first 256 bytes are used as an input translation table. If provided, the second 256 bytes are used as an output translation table. When the output table is not provided, Business Rules constructs the output table by inverting the input translation table. See File I/O for more information about TRANSLATE=.

The "EOL=spec" parameter defines the end-of-line separator (record delimiter) for the display file being opened (including communications files). It specifies the character/s to be sent at the end of every record (after RECL characters have been printed and at the end of each normal output line).

Three options are available for the EOL spec: CRLF (carriage return and line feed), LF (line feed only) and NONE (no characters are to be added or removed). CRLF is the default for DOS and DOS NetWork versions. LF is the default for Unix / Linux versions. If CRLF is used for output, a CHR$(26) end of file character is added to the end of the file when it is closed.

The above parameters (excluding the #filenum parameter) make up the file identification string. Normally they must be all be enclosed within a single set of quotation marks. If you wish to define this information elsewhere in the program, Business Rules will accept the "string expression" (see the bottom path of the syntax diagram) parameter in their place. The following parameter descriptions apply to all forms of OPEN display statement, no matter which syntax path is selected.

The "DISPLAY" keyword is required; it identifies the file being as a display file.

"INPUT" indicates that information in the file will be input into the program. "OUTPUT" indicates that information from the program will be output to the file. One of these two keywords is required.

The OPEN display statement provides for error processing with the optional "error-cond line-ref" parameter. See Error Conditions for more information.

Technical Considerations

1.) Relevant error conditions are: ERROR, EXIT, IOERR and LOCKED.
2.) Blanks are not allowed before the equal sign in OPEN statement parameters.
3.) Parameter items enclosed in quotes are not checked, syntactically, until program execution. Also, the distinction between uppercase and lowercase is ignored in OPEN statements, including in the "NAME=..." parameter.
4.) Only two things are special about #255 being reserved for printer references: an implied OPEN #255 occurs when the first PRINT #255 is encountered, and an implied CLOSE #255 occurs when the system encounters an OPEN #255 statement.
5.) When a display file is open for INPUT, the sequential pointer is positioned at the beginning of the file.
6.) When a display file is open for OUTPUT, the sequential file pointer is positioned at the end of the file, so that new records will be added at the end of existing records. To override this, specify the REPLACE parameter. It will drop all existing records in the file, similar to the DROP command.
7.) Business Rules utilizes the host operating system's capability for dynamic file extension. It automatically allocates additional space to a file when space is needed (until the disk is full).
8.) Variables can be used for "file-num" and "file-ref". Coding "file-num" as a variable (e.g., PRINTDEVICE), makes it easy to switch output from screen to printer to file.
9.) Also, two special device references are maintained for S/23 compatibility: "name=//10" is the same as PRN: or LPT1: for the first parallel port, and "name=//11" is the same as AUX: or COM1: for the first serial port.
10.) When LINPUT is used while EOL=NONE is active, Business Rules reads data from the input buffer until one of the following occurs:
  • The variable is full.
  • The buffer for a non-communications file is empty.
  • A timeout occurs on a communications file.
11.) During output, if the number of characters exceeds the value specified in the RECL= clause, the characters defined in the EOL= clause are inserted in the data stream. For example, with RECL=132 (the default) and EOL=CRLF (the DOS default), if a PRINT statement outputs 150 characters, CRLF will be inserted after 132 characters and again after the 150th character. When the output is to a 132-column printer, this will look as if a "wrap around" occurred at the end of the first 132-character line. When the output is to a file, this will result in two records being written to the file (since the one output string has two EOLs in it).
12.) RECL has no effect on input processing. With RECL=132 (the default), it is still possible to input strings longer than 132 (provided the input variables are dimensioned large enough). When EOL=NONE is specified, input processing in LINPUT and INPUT statements is terminated by the dimensioned length of the string variables. When EOL=CRLF or EOL=LF is specified, input processing in LINPUT and INPUT statements continues until finding the EOL characters in the file.
13.) See the Functions section for more information about the FILENUM and FILE$ functions. These functions should be especially useful for displaying messages after OPEN errors. See also STATUS FILES command, which displays information about file opens and file reservations.
14.) The number of open files allowed by the operating system dictates the number of OPEN statements allowed in a Business Rules program.
15.) The RETRY=int parameter is now supported in the syntax of the OPEN display statement. When at least one character has been output and the output device fails, int attempts are made again for the output. The default value for int is 5. This parameter can be adjusted for slow devices.
16.) When a file is opened for both SHR and INPUT, Business Rules will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.
17.) The OPEN display statement now supports a PRINTER= parameter. This parameter is used to specify the printer translation table (located in the BRConfig.sys file) that should be used. If the specified printer translation table is not found in the BRConfig.sys file, error 0609 will result. When no name is specified after the PRINTER= parameter, the default printer translation table will be used. For example:
00100 OPEN #1:"NAME=filename,PRINTER=LASER",DISPLAY,OUTPUT
00100 OPEN #1:"NAME=filename,PRINTER=",DISPLAY,OUTPUT ! use default

The string specified by this parameter overrides the NAME= string that is used in a PRINTER translation. If no PRINTER= clause is specified in the open string, the PRINTER translation that will be used is the NAME= string.

18.) The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules.
00100 OPEN #1:"NAME=TEST,NOCLOSE",INTERNAL,RELATIVE,INPUT
19.) On DOS and IBM NetWork versions, the CONFIG SPOOLCMD must now be specified, or opens to PRN: will return error 6298 (printer error) if the printer is not ready.
20.) The OPEN display statement now allows the CONV= parameter, which can be used to avoid conversion errors on N, G and PIC output to display files. CONV= specifies the character to fill a numeric field with in situations where a conversion would normally occur. For example, a report could print asterisks (********) in a numeric field instead of stopping with a conversion error. The fill character starts from the second position in the field and continues to the last digit specifier. (If the field is only one character in length, the fill character is used for that position.) Also, when CONV= is used, PIC processing will first try removing the commas from this example:
PRINT USING "FORM PIC(ZZZZZ)":12345,123456

output: 

12345 ****

PRINT USING "FORM PIC(ZZ,ZZZB)":12345,123456

output: 

12,345 123456
21.) The WAIT specification in the OPEN statement for all physical files will now also be used as the number of seconds to wait before re-attempting to open a file that another workstation has locked. Previously it affected the wait time on locked records only. Error code 4146 will be returned if the OPEN fails due to file locking.

EOL

The "EOL=spec" parameter indicates the end-of-line separator for the data file being opened. The EOL keyword and equal (=) symbol are required. The "spec" keyword must be replaced with one of three options: LF (line feed), CRLF (carriage return, line feed and Ctrl-Z for end of file marker), or NONE. If either CRLF or LF is specified, then both are accepted as valid record delimiters for input; they are removed from incoming data. The syntax for this parameter can be inserted into any diagram that calls for the EOL=spec parameter. 

EOL={LF|CRLF|NONE}


Defaults

  1. EOL=CRLF for DOS systems;
  2. EOL=LF for Unix / Linux systems.

Standard Out

If you specify “Name= STD_OUT:” in an OPEN display file statement, all output to this file is redirected to standard out.


Used in:


HTTP Client (browser simulation)

The OPEN string for HTTP DISPLAY files requires a parameter called HTTP=CLIENT (BR4.2+). The CLIENT designation denotes processing in the following sequence: 

HTTP=CLIENT
  1. OPEN
    1. NAME=Full URL - web page or service reference -
    2. CONTROL= optional display filename
  2. PRINT (accumulate post data)
  3. PRINT - When the first LINPUT is issued POSTing of all print lines occurs and all responses are buffered before the LINPUT returns data.
  4. LINPUT - Until EOF is reached or until another PRINT is issued a PRINT clears the LINPUT buffer.

Processing must be performed in the above sequence or an error is generated. FILE$(fileno,”HTTPINFO”) returns LOG info for the latest action. For more information, see HTTP=CLIENT.

Retrieved from "https://brwiki2.brulescorp.com/brwiki2/index.php?title=Open_Display&oldid=10835"