afopen

afopen

Open a File with System-Dependent Options

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
IMPLEMENTATION
EXAMPLES
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <lcio.h>

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

DESCRIPTION

The afopen function is an augmented version of the standard I/O fopen function. It enables the specification of various implementation-dependent and system-dependent parameters.

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.

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 at 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. If you specified neither b nor k , text access is assumed. k requests access as a keyed stream.

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

"" enables the library to select the access method.

term applies only to terminal files.

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

rel is primarily oriented toward access by relative character number. You can use the rel access method 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 afopen 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 description of amparms.

RETURN VALUE

If successful, afopen returns a FILE object associated with the named file. If the file cannot be opened, a NULL value is returned.

IMPLEMENTATION

You can use files opened with afopen and files opened with fopen interchangeably. The name and mode arguments to afopen have the same meanings and formats as the corresponding fopen arguments.

The function call afopen(name, mode, "", "") is equivalent to fopen(name, mode) .

EXAMPLES

This example saves an output matrix in a file of type matrix with 10 rows of the matrix in each block of the file. If the file does not exist, create it with enough space for the matrix.

#include <lcio.h>
#include <stdio.h>

main()
{
   FILE *matrix_out;
   char *matrix_name;
   char path_name[50];

      /* matrix parameters for afopen                 */
   char matrix_parms[90];
   int  matrix_rows;  /* number of rows in the matrix */
   double *matrix;    /* matrix definition            */

   matrix_name = "square";
   sprintf(path_name,"tso:%s.matrix", matrix_name);
      /* Set the afopen parameters.                   */
   sprintf(matrix_parms,
        "recfm=f, reclen=%d, blksize=%d, alcunit=block,"
        "space=%d", matrix_rows*sizeof(double),
        matrix_rows*sizeof(double)*10,
        matrix_rows / 10 + 1);

   matrix_out = afopen(path_name, "wb", "", matrix_parms);

     /* Write the entire matrix out at once.          */
   if (matrix_out)
      fwrite((char *)matrix, sizeof(double),
             matrix_rows*matrix_rows, matrix_out);
   else
      puts("Matrix file failed to open.");
}

RELATED FUNCTIONS

aopen , fopen

`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 at 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. If you specified neither `b` nor `k` , text access is assumed. `k` requests access as a keyed stream.

`""`	enables the library to select the access method.
`term`	applies only to terminal files.
The `seq` access method	is primarily oriented toward sequential access. It can be specified for terminal files, in which case, the `term` access method is automatically substituted.
`rel`	is primarily oriented toward access by relative character number. You can use the `rel` access method 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.