SAS/C Library Reference, Vol. 1

aopen -- Open a UNIX-Style File for I/O with Amparms

SYNOPSIS

 #include <fcntl.h>

 int aopen(const char *name, int flags, const char *amparms);

DESCRIPTION

aopen is a variant of open. It enables you to open a file for UNIX style I/O while specifying access method parameters (amparms) to request 370-dependent options.

The name argument is the external name (sometimes called pathname) of the file to be opened. Its form depends on the operating system. If name is an HFS file, the file is not opened directly. The file is opened through standard I/O as though it were an MVS file because aopen is used to specify amparms. OpenEdition does not support amparms. This should be a rare occurrence because there is little reason to call aopen for an HFS file.

The flags argument is a bit string formed by ORing option bits. The bits are defined symbolically, and the header file <fcntl.h> should be included to obtain their definitions. The flags and their meanings are as follows:

O_RDONLY: specifies to open for reading only.
O_WRONLY: specifies to open for writing only.
O_RDWR: specifies to open for both reading and writing.
O_APPEND: specifies to seek to end of file before each write.
O_CREAT: specifies to create a new file if it does not exist.
O_TRUNC: specifies to discard old data from existing file.
O_EXCL: specifies to not accept an existing file.
O_TEXT: specifies to open for text access.
O_BINARY: specifies to open for binary access.
O_NONBLOCK: specifies the use of nonblocking I/O. This option is meaningful only for OpenEdition HFS files.
O_NOCTTY: specifies that the file is not to be treated as a controlling terminal. This option is meaningful only for OpenEdition HFS files.

You should only set one of the following options: O_RDONLY, O_WRONLY, or O_RDWR. O_EXCL is ignored if O_CREAT is not also set. If neither O_TEXT nor O_BINARY is specified, O_BINARY is assumed unless the file to be opened is the terminal.

The amparms argument is a string specifying access method parameters, which are system- and access-method-dependent file processing options.

See Open modes for more information on details of the filename, open mode, and amparms specifications.

RETURN VALUE

aopen returns the file number of the file that was opened. If it fails, aopen returns - 1.

IMPLEMENTATION

You can use files opened with aopen and files opened with open interchangeably. The name and mode arguments to aopen have the same meanings and formats as the corresponding open arguments. aopen(name, mode, "") is equivalent to open(name, mode).

EXAMPLE

  #include <fcntl.h>
  #include <stdlib.h>

  main()
  {
    int cardfd;
    char ending = '.';

       /*  Open a card-image file.                             */
    cardfd = aopen("tso:cards.out", O_WRONLY | O_CREAT | O_TRUNC,
                   "recfm=f,reclen=80");

    if (cardfd < 0) exit(EXIT_FAILURE);
    lseek(cardfd, 7999, SEEK_SET);
       /* Write a '.' in position 7999. Previous positions     */
       /*  will be filled with nulls.                          */
    write(&ending, cardfd, 1);
    close(cardfd);
    exit(EXIT_SUCCESS);
  }

RELATED FUNCTIONS

afopen