OPEN

FUNCTION

The OPEN LINK command accesses a link and file. OPEN PRINTER accesses a printer. OPEN MESSAGE accesses a message dictionary. OPEN SCREEN and OPEN VIEW place the associated data attributes into memory.

SYNTAX

OPEN LINK link-name [CREATE] [CLEAR] [NEW]
      [DATA-FILE IS string-value]
      [SORT-FILE IS string-value]
      [TEXT-FILE IS string-value]
      [BUSY PROCESS IS procedure]
      [ERROR PROCESS IS procedure]

OPEN MESSAGES "msg-dict-name"

OPEN PRINTER printer-link-name
      [COLUMN numeric-value LINE numeric-value]
      [BUSY PROCESS IS procedure]
      [ERROR PROCESS IS procedure]

OPEN SCREEN screen-name

OPEN VIEW view-name

link-name: the name of a link from Dictionary-IV.
string-value: a string data name, variable, constant, or expression.
procedure: the name of a procedure to perform.
msg-dict-name: the name of a Dictionary-IV defined message dictionary.
numeric-value: a data name, variable, constant, or expression that results in an integer.
printer-link-name: the name of a printer link in Dictionary-IV.
screen-name: the name of a screen defined in Dictionary-IV.
view-name: the name of a view defined in Dictionary-IV.

NOTES

OPEN LINK

The link provides access to the data file, sort file, and text file. It is used in file I/O commands such as ADD, CHANGE, DELETE, PRINT VIEW and READ.
The link must be declared using the LN, SN, or VN command before it can be opened. Links are declared automatically when associated screens or views are declared.
If the CREATE option is used and the data file is not found, the system will automatically create the data file based on the format specified in the link. The file is created on the disk specified in #IDSV.DISK-NO-DATAFILES. If the data file already exists and is accessible, the CREATE option is ignored. The CREATE option can be used with the DATA-FILE, SORT-FILE, and TEXT-FILE options.

If the OPEN LINK link-name CREATE command creates a sort file, the size is determined by multiplying the number of records in the main file by the number of defined sorts. For example, if the main file is defined with 300 records and the number of sorts defined in the link is 3, the sort file will contain room for 900 keys.
The Script-IV Compiler supports global variable ]PFX$ with the OPEN LINK link-name CREATE command.
If the CLEAR option is used and the data file exists and can be accessed, the system will automatically clear the file of all data without changing its parameters, such as record size, number of records, location, and so on. The system must be able to successfully open and lock the file before the file can be cleared.

Note: The CLEAR option deletes all records from the physical file; even if the data file is a multi-format file, all records are deleted.

If the data file is not found, the system will automatically create the data file based on the format specified in the link. The file is created on the disk specified in #IDSV.DISK-NO-DATAFILES.
If you plan to use the CLEAR option on a previously opened link, you must first close the link.
OPEN LINK link-name NEW forces a data file to be erased and created with parameters from the link. If the file existed, the same directory is used. This is useful for work files where the same data file can be used for multiple links.

The Script-IV Compiler supports global variable ]PFX$ with the OPEN LINK link-name NEW command.
The DATA-FILE, SORT-FILE, and TEXT-FILE options can be used when two or more data files have the same format. You can open a single link and swap or specify data files by reopening the link with the DATA-FILE option. If you swap a data file that has a sort file, you must specify the sort file in the SORT-FILE option, or a sort file will be automatically created and named by adding the “sk” suffix to the data file name. The TEXT-FILE clause enables you to override the name of the file that contains the text fields defined in the link.
If @ (the file suffix indicator) is specified in a data, sort, or text file name, the @ will be replaced by the value of the FILE-SUFFIX variable. The resulting file name will be used in the command.

If the value of the FILE-SUFFIX variable is null or spaces, the file suffix indicator is ignored or dropped from the file name for the current OPEN command, and nothing is replaced. If the resulting file name is more than 14 characters long, Script-IV will truncate the file name.
The BUSY procedure specifies a procedure that is performed if the link is locked or busy. If the link is locked or busy and no BUSY PROCESS is specified, the OPEN command is ignored and script execution continues with the next command.
If an error, other than a busy condition, occurs during the processing of this command, the ERROR procedure is performed. If ERROR is not specified, the command is ignored and script execution continues with the next command.
A link does not have to be closed in order to be opened again in a script. The OPEN command automatically closes the link if it is already opened by the script and resets the record pointer.
The Script directives OPEN LINK, OPEN LINK DATA-FILE, and OPEN LINK SORT-FILE compiles with the appropriate OPT=“DLINK” option. The data and sort files are opened by the Basic runtime engine; and all secondary keys are maintained by the Basic runtime engine. This reduces the amount of code necessary to maintain files, reduces the amount of memory required by compiled scripts, reduces the number of used channel numbers, and increases runtime performance.

In addition OPEN LINK will always call the FIle Suffix Method when one is defined in the Link. The File Suffix Method takes precedence over the FILE-SUFFIX variable.

For more information on OPEN OPT=“DLINK”, please see the Basic Language Reference (F-Q).

Important Notes Regarding DLINK

The implementation of OPT=“DLINK” requires the use of LINK ALIAS (LA) when reusing the same LINK (LN) for varying sort sequences since this may affect the internal key pointers. Previously there were two channels:
1. One for traversing the Link by primary key; and
2. a second for traversing the Link by secondary key.

Although not recommended this allowed the Script developer to READ and UPDATE the same LN with various SORT values without impacting the current key pointer. With OPT=“DLINK” the Basic runtime engine will use a single channel for traversing the Link by both primary key and all sort keys. For this reason it is not safe to assume that the same LN can be reused for various functions, if maintaining the current key pointer is critical to the Script logic. It is important that your Scripts maintain the proper channel context. We strongly recommend using the LA LINK ALIAS as it is intended and not relying upon an understanding of the underlying Script code in order to achieve the desired result.

The OPEN LINK directive always executes the File Suffix Method defined for the Link. When opening a file with OPT=“DLINK” the Basic engine always executes the File Suffix Method. In previous releases compiled Script code executed the File Suffix Method and this occurred only when a File Suffix was defined for the Link. Starting with this release the execution of the File Suffix Method is no longer dependent upon the presence of a File Suffix definition in the Link. This is also true for the CLOSE LINK ERASE directive.

OPEN MESSAGES

The message dictionary provides lists of messages that can be used in a script.
When opened, the message dictionary is added to memory and selected as the default dictionary. You can temporarily override the default dictionary in commands accessing messages with the USING option. For more information on overriding the default dictionary see the PRINT MESSAGE and INPUT MESSAGE command.
The message dictionary does not have to be opened before it is used, but opening the dictionary avoids having to specify the USING option on PRINT MESSAGE and INPUT MESSAGE commands.

OPEN PRINTER

Scripts allow two methods of printer handling. You can hard-code in the script to select specific printers, or soft-code in the script to enable the operator to select a printer from a list of available printers. For most applications, the developers prefer to let the script handle the printer selection. It is recommended that you select one method and use it consistently.

Hard-Coded

For each printer on your system that you wish to use in scripts, the printer-link-name must first be declared using an LN data declaration command and opened before it can be used.
To create a hard-coded printer link the name of the link must be formed as 4Gxx where 4G is the library and xx is the printer device name. For example, 4GP1 is a validly formed name. The data file name must be the printer device name, for example, P1. The format name must be blank. Entries in all other fields in the link are ignored.
The printer-link-name must be one of the special links included in the 4G library. The printer-link-name is specified when you open, print to, and close a printer.

Soft-Coded

To create a soft-coded printer link the name of the link must be formed as 4Gxx where 4G is the library and xx is any two characters. For example, 4GPA is a validly formed name. The data file name is ignored. The format name must be blank. Entries in all other fields in the link are ignored.
A soft-coded printer is set up in the data environment section by specifying a printer-link-name with a ? appended to the printer-link-name, for example, LN 4GLP?. When the printer-link-name is opened, as in the OPEN PRINTER 4GLP command, the operator is prompted to select a printer from a list of configured printers. The script will open the selected printer.
The soft-coded printer selection prompt is displayed on the terminal at column 0, line 0, unless you override the position by specifying the COLUMN and LINE parameters.

The following example shows how to open soft-coded printers and hard-coded printers:

LN    4GLP?
LN    4GP1
MAIN-LINE
      OPEN PRINTER 4GLP ! Asks user to select printer
      OPEN PRINTER 4GP1 ! Opens printer defined in 4GP1 link
END-SCRIPT

Any printer link can be opened as a soft-coded printer by appending the ? (question mark) when the link is referenced in a script.
Soft-coded printer 4GxxO references the default printer from the operator code record. The OPERATOR-PRINTER variable contains the printer name specified in the operator record. The xx does not have to refer to a defined printer device.

Soft-coded printer 4GxxS references the name of the printer contained in the SYSTEM-PARM(1) variable. The xx does not have to refer to a defined printer device.

The printer-link name must be declared using an LN data declaration statement. You must issue the OPEN PRINTER command before you can issue a PRINT TO PRINTER command. You can use the ERROR or BUSY clauses to test the success of the OPEN PRINTER command.

The following example shows how to use soft-coded printers 4GxxO and 4GxxS:

   LN    4GLP?             ! Soft-coded printer
   LN    4GP1              ! Hard-coded printer - P1 exists
   LN    4GP2O             ! P2 is not a defined printer device
   LN    4GP3S             ! P3 is not a defined printer device

   MAIN-LINE

         OPEN PRINTER 4GLP ! Asks user to select printer
         OPEN PRINTER 4GP1 ! Opens printer defined in 4GP1 link
         OPEN PRINTER 4GP2 ! Opens default printer from operator
                           !   code record
         OPEN PRINTER 4GP3 ! Opens printer contained in
                           !   SYSTEM-PARM(1)

OPEN SCREEN

The screen must first be declared using an SN data declaration command. When opened, the screen definition is loaded into memory. A screen must be opened before it can be used.

OPEN VIEW

The view must first be declared using a VN data declaration command. When opened, the view definition is loaded into memory. A view and the associated link must be opened before the view can be used.

EXAMPLES

OPEN SCREEN 4STOPSC1

OPEN MESSAGES "4SSAMPLE"

OPEN LINK 4SSLSRP CREATE

OPEN VIEW 4SCUST

OPEN LINK 4SSAMPLE
      DATA-FILE "MYDATAFILE"
      TEXT-FILE "MYTEXTFILE"