FOPEN Function

Opens an external file and returns a file identifier value.

Category:	External Files
See:	FOPEN Function: z/OS in SAS Companion for z/OS

Syntax

FOPEN(fileref<,open-mode<,record-length<,record-format> > > )

Required Argument

fileref

is a character constant, variable, or expression that specifies the fileref assigned to the external file.

Tip	If fileref is longer than eight characters, then it will be truncated to eight characters.

Optional Arguments

open-mode

is a character constant, variable, or expression that specifies the type of access to the file:

A	APPEND mode allows writing new records after the current end of the file.
I	INPUT mode allows reading only (default).
O	OUTPUT mode defaults to the OPEN mode specified in the operating environment option in the FILENAME statement or function. If no operating environment option is specified, it allows writing new records at the beginning of the file.
S	Sequential input mode is used for pipes and other sequential devices such as hardware ports.
U	UPDATE mode allows both reading and writing.

Default

record-length

is a numeric constant, variable, or expression that specifies the logical record length of the file. To use the existing record length for the file, specify a length of 0, or do not provide a value here.

record-format

is a character constant, variable, or expression that specifies the record format of the file. To use the existing record format, do not specify a value here. Valid values are:

B	data are to be interpreted as binary data.
D	use default record format.
E	use editable record format.
F	file contains fixed length records.
P	file contains printer carriage control in operating environment-dependent record format. Note: For z/OS data sets with FBA or VBA record format, specify 'P' for the record-format argument.
V	file contains variable length records.

Note: If an argument is invalid, FOPEN returns 0, and you can obtain the text of the corresponding error message from the SYSMSG function. Invalid arguments do not produce a message in the SAS log and do not set the _ERROR_ automatic variable.

Details

CAUTION:

Use OUTPUT mode with care.

Opening an existing file for output overwrites the current contents of the file without warning.

The FOPEN function opens an external file for reading or updating and returns a file identifier value that is used to identify the open file to other functions. You must associate a fileref with the external file before calling the FOPEN function. FOPEN returns a 0 if the file could not be opened. You can assign filerefs by using the FILENAME statement or the FILENAME external file access function. Under some operating environments, you can also assign filerefs by using system commands.

If you call the FOPEN function from a macro, then the result of the call is valid only when it is passed to functions in a macro. If you call the FOPEN function from the DATA step, then the result is valid only when it is passed to functions in the same DATA step.

Operating Environment Information: It is good practice to use the FCLOSE function at the end of a DATA step if you used FOPEN to open the file, even though using FCLOSE might not be required in your operating environment. For more information about FOPEN, see the SAS documentation for your operating environment.

Examples

Example 1: Opening a File Using Defaults

This example assigns the fileref MYFILE to an external file and attempts to open the file for input using all defaults. Note that in a macro statement that you do not enclose character strings in quotation marks.

%let filrf=myfile;
%let rc=%sysfunc(filename(filrf,
   physical-filename));
%let fid=%sysfunc(fopen(&filrf));

Example 2: Opening a File without Using Defaults

This example attempts to open a file for input without using defaults. Note that in a macro statement that you do not enclose character strings in quotation marks.

%let fid=%sysfunc(fopen(file2,o,132,e));

Example 3: Handling Errors

This example shows how to check for errors and write an error message from the SYSMSG function.

data _null_; 
   f=fopen('bad','?');
   if not f then do;
      m=sysmsg();
      put m;
      abort;
      end;
      ... more SAS statements ...
   run;