afreopen

afreopen

Reopen a File with System-Dependent Options

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <lcio.h>

FILE *afreopen(const char *name, const char *mode, FILE *oldf,
               const char *am, const char *amparms);

DESCRIPTION

The afreopen function closes the stream associated with the FILE object addressed by oldf and then reopens it using the filename, open mode, access method, and amparms specified by the remaining arguments. The oldf pointer can also identify a stream that has been closed, in which case, only the open portion of afreopen is performed.

The name argument is the external name (sometimes called a pathname) of the file to be opened. Its form is operating-system-dependent. See General filename specification for syntax details. Note that the name to be opened may be different from the filename currently associated with the oldf argument.

The mode argument is a string defining how the file will be used. The mode string contains one to three characters with the following syntax:

r  | [b]  
w  | [+] | [k]  
a

r indicates that the file will be read.

w indicates that the file will be written and the previous contents discarded.

a indicates that data will be added to the end of the file. (If a is specified, the file is automatically positioned to the end of the file immediately before data are physically written.) For a keyed file, new data can be added anywhere in the file, but existing records cannot be changed.

+ indicates that the file will be both read and written if it is present in the mode string.

b requests access as a binary stream, and k requests access as a keyed stream. If neither b nor k is specified, text access is assumed.

Refer to Open modes for more details.

The am argument is a string naming an access method. Remember to enclose the method in quotation marks. The following specifications are permitted:

"" enables the library to select the access method.

term applies only to terminal files.

seq is primarily oriented towards sequential access. It can be specified for terminal files, in which case the term access method is automatically substituted.

rel is oriented primarily toward access by relative character number. The rel access method can be used only when the open mode specifies binary access.

kvs is oriented toward access to data by physical or logical keys. The kvs access method can be used only with VSAM files and only when the mode specifies keyed access.

fd provides access to USS HFS files.

If the file cannot be handled with the access method you specify, the afreopen operation fails.

See Library access method selection for more information on access method selection.

The amparms argument is a string specifying access method parameters, which are system- and access-method dependent file processing options. See Access method parameters for a complete discussion of amparms.

RETURN VALUE

If afreopen is successful, the value of oldf is returned. The FILE object addressed by oldf is now associated with the file specified by name .

If afreopen is unsuccessful, a NULL FILE pointer is returned. Further use of oldf after an unsuccessful afreopen is not permitted.

EXAMPLE

#include <lcio.h>

   /* Reopen stdin to the terminal or the DDname */
   /* INPUT. Use "/*" to indicate end of file.   */
afreopen("tso:*INPUT", "r", stdin, "", "eof=/*");

RELATED FUNCTIONS

afopen , freopen

`r`	indicates that the file will be read.
`w`	indicates that the file will be written and the previous contents discarded.
`a`	indicates that data will be added to the end of the file. (If `a` is specified, the file is automatically positioned to the end of the file immediately before data are physically written.) For a keyed file, new data can be added anywhere in the file, but existing records cannot be changed.
`+`	indicates that the file will be both read and written if it is present in the `mode` string.
`b`	requests access as a binary stream, and `k` requests access as a keyed stream. If neither `b` nor `k` is specified, text access is assumed.

`""`	enables the library to select the access method.
`term`	applies only to terminal files.
`seq`	is primarily oriented towards sequential access. It can be specified for terminal files, in which case the `term` access method is automatically substituted.
`rel`	is oriented primarily toward access by relative character number. The `rel` access method can be used only when the open mode specifies binary access.
`kvs`	is oriented toward access to data by physical or logical keys. The `kvs` access method can be used only with VSAM files and only when the mode specifies keyed access.
`fd`	provides access to USS HFS files.