SAS Companion for the OS/390 Environment

Accessing UNIX System Services Files

IBM's UNIX System Services implements a directory-based file system that is very similar to the file systems used in UNIX. The SAS System under OS/390 enables you to read and write UNIX System Services files and to pipe data between SAS and UNIX System Services commands.

Allocating UNIX System Services Files

You can allocate a UNIX System Services file either externally (using a JCL DD statement or the TSO ALLOCATE command) or internally (using the SAS FILENAME statement or FILENAME function). For information about allocating UNIX System Services files externally, see your IBM documentation.

There are four ways to specify that a file is in UNIX System Services when you use the FILENAME statement or FILENAME function:

Include a slash or tilde in the path name:

filename input1 '/u/sasusr/data/testset.dat';
filename input2 '~/data/testset2.dat';

Specify HFS (for hierarchical file system) as the file type:
```
filename input hfs 'testset.dat';
```
Specify HFS as the file prefix:
```
filename input 'HFS:testset.dat';
```
Rely on the setting of the FILESYSTEM= system option:
```
options filesystem=HFS;
filename 'testset.dat';
```

You can also use these specifications in combination. For example, you can specify the UNIX System Services file type and use a slash in the pathname.

If you do not specify the entire pathname of a UNIX System Services file, then the directory component of the pathname is the working directory that was current when the file was allocated, not when the fileref is used. For example, if your working directory was /usr/local/sasusr when you allocated the file, then the following FILENAME statement associates the INPUT fileref with the following path:

/usr/local/sasusr/testset.dat

filename input hfs 'testset.dat';

If you change your current working directory to /usr/local/sasusr/testdata then the following statement still refers to /usr/local/sasusr/testset.dat, not to /usr/local/sasusr/testdata/testset.dat:

infile input;

Allocating a UNIX System Services Directory

To allocate a UNIX System Services directory, create the directory if necessary, then allocate the directory using any standard method, such as a JCL DD statement, a TSO ALLOCATE command, or a FILENAME statement such as those listed in Allocating UNIX System Services Files.

To open a particular file in a directory for input or output, you must specify the file name in the SAS INFILE or FILE statement, as described in Accessing a Particular File in a UNIX System Services Directory.

Specifying File-Access Permissions and Attributes

How you specify file-access permissions and attributes depends on which method you use to allocate a UNIX System Services file:

When you use a JCL DD statement or a TSO ALLOCATE command to allocate a UNIX System Services file, you can use the PATHMODE and PATHOPTS options to specify file-access permissions and attributes for the file. If you later use the file's DDname in a SAS session, SAS uses the values of those options when it opens the file.
For example, if you use the following TSO ALLOCATE command to allocate the DDname INDATA and SAS attempts to open it for output, then SAS issues an "insufficient authorization" error message and does not permit the file to be opened for output. (The ORDONLY value of PATHOPTS specifies "open for reading only.")
```
alloc file(indata) 
   path('/u/sasusr/data/testset.dat')
   pathopts(ordonly)
```
In other words, you could use the DDname INDATA in a SAS INFILE statement, but not in a FILE statement. Similarly, if you specify OWRONLY, then you can use the DDname in a FILE statement but not in an INFILE statement.

CAUTION:
PATHOPTS values OAPPEND and OTRUNC take precedence over FILE statement options OLD and MOD. If you specify OAPPEND ("add new data to the end of the file"), the FILE statement option OLD does not override this behavior. Similarly, if you specify OTRUNC ("if the file exists, erase it and re-create it"), the FILE statement options OLD and MOD do not override this behavior. (See Standard Host Options for the FILE Statement under OS/390 for details about these FILE statement options.)
If you use the FILENAME statement or FILENAME function to allocate a UNIX System Services file, or if you use a JCL DD statement or a TSO ALLOCATE command but do not specify values for PATHMODE and PATHOPTS, then SAS uses the following values for those options:
- For PATHMODE, SAS uses the file-access mode -rw-rw-rw-; however, this mode may be modified by the current file-mode creation mask. (For detailed information about the file-mode creation mask, see your IBM documentation.)
- For PATHOPTS, the file-access mode that SAS supplies depends on how the fileref or DDname is being used:
  - If the fileref or DDname appears only in a FILE statement, SAS opens the file for writing only, and if the file does not exist, SAS creates it.
  - If the fileref appears only in an INFILE statement, SAS opens the file for reading only.
  - If the fileref appears in both FILE and INFILE statements within the same DATA step, SAS opens the file for reading and writing. For the FILE statement, SAS also creates the file if it does not already exist.

Using UNIX System Services File Names in SAS Statements and Commands

To use an actual UNIX System Services filename (rather than a fileref or DDname) in a SAS statement or command, include a slash or tilde in the pathname, or use the HFS prefix with the filename. You can use a UNIX System Services file name anywhere that an external file name can be used, such as in a FILE or INFILE statement, in an INCLUDE or FILE command in the windowing environment, or in the SAS Explorer window. If the file is in the current directory, specify the directory component as ./. For example:

include './testprg.sas'

Concatenating UNIX System Services Files

To associate a fileref with a concatenation of UNIX System Services files or directories, enclose the pathnames in parentheses. The fileref can be opened only for input. For example:

filename test ('data/test1.dat' 'data/test2.dat');

All of the pathnames in the concatenation must be for UNIX System Services files or directories. If your program reads data from different types of files in the same DATA step, you can use the EOF= option in each INFILE statement to direct program control to a new INFILE statement after each file has been read. (See SAS Language Reference: Dictionary for more information about the EOF= option of the INFILE statement.)

Accessing a Particular File in a UNIX System Services Directory

If you have associated a fileref with a UNIX System Services directory or with a concatenation of UNIX System Services directories, you can open a particular file in the directory for reading or writing by using an INFILE or FILE statement in the form shown below:

infile fileref(file);
file   fileref(file);

If you do not enclose file in quotes, then SAS appends a file extension to the file name. In the windowing environment commands INCLUDE and FILE, the file extension is ".sas". In the INFILE and FILE statements, the file extension is ".dat".

If the file is opened for input, SAS searches all of the directories that are associated with the fileref in the order in which they appear in the FILENAME statement or FILENAME function. If the file is opened for output, SAS creates the file in the first directory that was specified. If the file is opened for updating but does not exist, SAS creates the file in the first directory.

Piping Data between SAS and UNIX System Services Commands

To pipe data between SAS and UNIX System Services commands, you first specify the PIPE file type and the command in a FILENAME statement or FILENAME function. Enclose the command in single quotes. For example, this FILENAME statement assigns the command ls -lr to the fileref OECMD:

filename oecmd pipe 'ls -lr';

To send the output from the command as input to the SAS System, you then specify the fileref in an INFILE statement. To use output from SAS as input to the command, you specify the fileref in a FILE statement.

You can associate more than one command with a single fileref. Commands are executed in the order in which they appear in the FILENAME statement or FILENAME function. For example:

filename oecmd pipe ('ls *.sas' 'ls *.data');

Piping Data from a UNIX System Services Command to SAS

When a pipe is opened for input by the INFILE statement, any output that the command writes to standard output or to standard error is available for input. For example, here is a DATA step that reads the output of the ls -l command and saves it in a SAS data set:

filename oecmd pipe 'ls -l';
data dirlist;
   infile oecmd truncover;
   input mode $ 1-10 nlinks 12-14 user $ 16-23
         group $25-32 size 34-40 lastmod $ 42-53
         name $ 54-253;
run;

Piping Data from SAS to an UNIX System Services Command

When a pipe is opened for output by the FILE statement, any lines that are written to the pipe by the PUT statement are sent to the command's standard input. For example, here is a DATA step that uses the UNIX System Services od command to write the contents of the file in hexadecimal format to the UNIX System Services file dat/dump.dat, as follows:

filename oecmd pipe 'od -x -tc - >dat/dump.dat';
data _null_;
   file oecmd;
   input line $ 1-60;
   put line;
cards;
The SAS System is an integrated system of software
products, enabling you to perform data management,
data analysis, and data presentation tasks.
;
run;

Host-Specific Options for UNIX System Services Files

Host-Specific Options for UNIX System Services Files and Pipes shows which host-specific options are recognized by the FILENAME, FILE, and INFILE statements for UNIX System Services files and pipes. No other options are recognized, including such options specific to OS/390 as DISP, CLOSE, and DCB. Descriptions of the options follow the table.

Host-Specific Options for UNIX System Services Files and Pipes
Option FILENAME FILE INFILE

OLD X X

MOD X X

LRECL= X X X

RECFM= X X X

***Host-Specific Options for UNIX System Services Files and Pipes***
Option	FILENAME	FILE	INFILE
OLD	X	X
MOD	X	X
LRECL=	X	X	X
RECFM=	X	X	X

OLD

replaces the previous contents of the file. This is the default. This option has no effect on a pipe.

MOD

appends the output lines to the file. This option has no effect on a pipe.

LRECL=value

specifies the maximum number of characters in a line (unless the file has been opened with RECFM=N). The default is 255. Lines longer than value are truncated. value must be between 1 and 32,767, inclusive.

RECFM=record-format

specifies the record format of the file. Valid values are

F	specifies that all lines in the file have the length specified in the LRECL option. In output files, lines that are shorter than the LRECL value are padded on the right with blanks.
V \| D	specifies that the lines in the file are of variable length, ranging from 1 character to the number of characters specified by LRECL=. This is the default.
P	specifies that the file has variable-length records and is in print format.
N	specifies that the file is in binary format. The file is treated as a byte stream; that is, line boundaries are not recognized.

Using the X Statement to Issue UNIX System Services Commands

To start the UNIX System Services shell, issue the following X statement:

x omvs;

Note: UNIX System Services commands are case sensitive. [cautionend]

You can also use the X statement to issue any of three UNIX System Services commands:

x cd directory;

changes the current working directory to directory. If directory is omitted, the current working directory is changed to the working directory that was initially assigned to your login name.

x umask mask;

changes the current file-mode creation mask value to mask. According to UNIX conventions, mask is a one- to three-digit octal number. The file-mode creation mask modifies the file mode of new files. Each 1 bit in the file-mode creation mask causes the corresponding permission bit in the file mode to be disabled. If a bit is 0 in the mask, the corresponding file-mode bit can be enabled. For UNIX System Services files that are created by SAS, the file mode for new files is "-rw-rw-rw-"; however, this mode is modified by the current file-mode creation mask. For example, x umask 022 ensures that each newly created file can be written to only by its owner. (For detailed information about the file-mode creation mask, see your IBM documentation.)

The new value is displayed in the SAS log. If mask is not specified, the current value is simply displayed in the SAS log; the current file-mode creation mask value remains unchanged.

x pwd;

displays your current working directory in the SAS log.

To issue other UNIX System Services commands, use the PIPE access method.

To issue a TSO command or CLIST that has the same name as one of the case-sensitive commands (a CLIST named CD, for example), either enter the command using uppercase characters, or use the TSO: prefix and enclose the command in quotes, as in the following examples:

x CD option1 option2 ...;
x 'tso:cd option1 option2 ...';

For more information about the X statement, see X.

Restrictions in SAS System Support for UNIX System Services

It is not possible to run SAS under the UNIX System Services shell. However, you can run the shell after you initialize SAS by using the x omvs; statement.

Chapter Contents
Previous
Next
Top of Page