OPEN

Syntax

OPEN {filename_lit|_var|_col} AS {filenum_num_lit|_var|_col} {FOR-READING|FOR-WRITING|FOR-APPEND} {RECORD=length_num_lit[:FIXED|:FIXED_NOLF|:VARY]} [STATUS=num_var]

Description

Opens an operating system file for reading or writing. After a file is opened, it remains open until explicitly closed by the CLOSE command. A maximum of 256 files can be opened at one time.

Parameters

Parameter Description

{filename_lit | _var | _col}

Specifies the file name. The file name can be literal, variable, or column. This makes prompting for a file name at runtime easy.

{filenum_num_lit | _var | _col}

Specifies a number that identifies the file in the application. All file commands use the file number to reference the file. File numbers can be numeric variables and literals. The number can be any positive integer less than 64,000.

FOR-READING

When a file is opened for reading, SQR procures all data sequentially. SQR does not allow for random access of information.

FOR-WRITING

When a file is opened for writing, a new file is created. If a file of the same name already exists, it can be overwritten (this depends on the operating system).

FOR-APPEND

When a file is opened in append mode, the current file contents are preserved. All data written is placed at the end of the file. SQR creates the file if one does not already exist. For existing files, make sure that the attributes used are the same as those used when the file was created. Failure to do this causes the unpredictable results.

RECORD

For the VARY file type , this is the maximum size for a record. For the FIXED file type , this is the size of each record without the line terminator. For the FIXED_NOLF file type , this is the size of each record.

FIXED

This file type assumes that all records contained within the file are the same length. Terminate each record by a line terminator (system-dependent). You can use this file type when writing or reading binary data.

FIXED_NOLF

This file type specifies that all records contained within the file are the same length with no line terminators. When writing records, SQR pads short records with blank characters to ensure that each record is the same length. This file type can be used when SQR is writing or reading binary data.

VARY

This file type specifies that the records can be of varying length. Each record is terminated by a line terminator (system-dependent). Only records containing display characters (no binary data) can be used safely. When SQR is reading records, any data beyond the maximum length specified is ignored. This is the default file type.

STATUS

Sets the numeric variable to zero if the OPEN command succeeds and to –1 if it fails. Without the STATUS argument, a failure on OPEN causes SQR to halt. By using a STATUS variable, you can control what processing occurs when a file cannot be opened.

Example

This section contains two examples: a regular open command and an expanded command: 

open 'stocks.dat' as 1  for-reading record=100
open 'log.dat'    as 5  for-writing record=70
open $filename    as #j for-append  record=80:fixed
open $filename    as 2  for-reading record=80:fixed_nolf

open $filename    as 6  for-reading record=132:vary status=#filestat
if #filestat != 0
  ... error processing ...
end-if

An encoding directive added to the OPEN command allows differently encoded files to be managed in a single run of SQR. When no ENCODING is specified on the OPEN command, SQR uses the file input or output encoding specified in the INI file unless the file is UCS-2 encoded and auto-detection of UCS-2 files is enabled. The complete syntax of the OPEN command is: 

OPEN {filename_lit | _var | _col} AS {filenum_num_lit |
_var | _col}
{ FOR-READING | FOR-WRITING | FOR-APPEND }
{ RECORD = length_num_lit[:FIXED | :FIXED_NOLF |
:VARY]}
[ STATUS = num_var ]
[ ENCODING = { _var | _col | ASCII | ANSI | SJIS | JEUC
| EBCDIC |
EBCDIK290 | EBCDIK1027 | UCS-2 | UTF-8 | others... }

The ENCODING directive is allowed only when you are converting to Unicode internally.

See The READ, WRITE, and CLOSE commands for information about using files