SAS 9.1 Companion For Unix Enivronments

ABORT Statement

Stops executing the current DATA step, SAS job, or SAS session

Valid: in a DATA step

UNIX specifics: values of n

See: ABORT Statement in SAS Language Reference: Dictionary

Syntax

ABORT <ABENDRETURN>< n >;

Details

The n option enables you to specify the value of the exit status code that SAS returns to the shell when it stops executing. The value of n can range from 0 to 255.

See Also

• "Determining the Completion Status of a SAS Job in UNIX Environments" on page 22

ATTRIB Statement

Associates a format, informat, label, and/or length with one or more variables

Valid: in a DATA step

UNIX specifics: length specification

See: ATTRIB Statement in SAS Language Reference: Dictionary

Syntax

ATTRIB variable-list- 1 attribute-list -1 <... variable-list-n attribute-list-n >;

attribute-list

• LENGTH=<$> length

  • specifies the length of the variables in variable-list . The minimum length that you can specify for a numeric variable depends on the floating-point format used by your system. Because most systems use the IEEE floating-point format, the minimum is 3 bytes.

See Also

• Chapter 8, "Data Representation," on page 197

FILE Statement

Specifies the current output file for PUT statements

Valid: in a DATA step

UNIX specifics: valid values for file-specification , host-options , and encoding-value

See: FILE Statement in SAS Language Reference: Dictionary

Syntax

FILE file-specification <ENCODING=' encoding-value '>< options >< host-options >;

file-specification

• can be any of the file specification forms that are discussed in the "Accessing an External File or Device in UNIX Environments" on page 133.

ENCODING=' encoding-value '

• specifies the encoding to use when writing to the output file. The value for ENCODING= indicates that the output file has a different encoding from the current session encoding.

  When you write data to the output file, SAS transcodes the data from the session encoding to the specified encoding.

  For valid encoding values, see "Encoding Values in SAS Language Elements" in SAS National Language Support (NLS): User 's Guide .

options

• can be any of the options for the FILE statement that are valid in all operating environments. See the SAS Language Reference: Dictionary for a description of these options.

host-options

• are specific to UNIX environments. These options can be any of the following:

• BLKSIZE=

• BLK=

  • specifies the number of bytes that are physically written in one I/O operation. The default is 8K. The maximum is 1G-1.

• TERMSTR=

  • controls the end-of-line/record delimiters in PC and UNIX formatted files. This option enables the sharing of UNIX and PC formatted files between the two hosts .

    The following are values for the TERMSTR= option:

    CRLF	Carriage Return Line Feed. This parameter is used to create PC format files.
    NL	Newline. This parameter is used to create UNIX format files. NL is the default format.

    Use TERMSTR=CRLF when you are writing to a file that you want to read on a PC. If you use this option when creating the file, then you do not need to use TERMSTR=NL when reading the file on the PC.

• LRECL=

  • specifies the logical record length. Its meaning depends on the record format in effect (RECFM). The default is 256. The maximum length is 1G.

  • If RECFM=F, then the value for the LRECL= option determines the length of each output record. The output record is truncated or padded with blanks to fit the specified size .

  • If RECFM=N, then the value for the LRECL= option must be at least 256.

  • If RECFM=V, then the value for the LRECL= option determines the maximum record length. Records that are longer than the specified length are divided into multiple records.

• MOD

  • indicates that data written to the file should be appended to the file.

• NEW OLD

  • indicates that a new file is to be opened for output. If the file already exists, then it is deleted and re-created. If you specify OLD, then the previous contents of the file are replaced . NEW is the default.

• RECFM=

  • specifies the record format. Values for the RECFM= option are

    D	default format (same as variable).
    F	fixed format. That is, each record has the same length. Do not use RECFM=F for external files that contain carriage-control characters .
    N	binary format. The file consists of a stream of bytes with no record boundaries.
    P	print format. SAS writes carriage-control characters.
    V	variable format. Each record ends with a newline character.
    S370V	variable S370 record format (V).
    S370VB	variable block S370 record format (VB).
    S370VBS	variable block with spanned records S370 record format (VBS).

• UNBUF

  • tells SAS not to perform buffered writes to the file on any subsequent FILE statement. This option applies especially when you are writing to a data collection device.

Details

The ENCODING= option is valid only when the FILE statement includes a file specification that is not a reserved fileref. If the FILE statement includes the ENCODING= argument and the reserved filerefs Log or Print as the file-specification , then SAS issues an error message. The ENCODING= value in the FILE statement overrides the value of the ENCODING= system option.

You can set the permissions of the output file by issuing the umask command from within the SAS session. For more information, see "Executing Operating System Commands from Your SAS Session" on page 13.

See Also

• Chapter 5, "Using External Files and Devices," on page 131

FILENAME Statement

Associates a SAS fileref with an external file or output device

Valid: anywhere

UNIX specifics: device-type , external-file , host-options , and encoding-value

See: FILENAME Statement in SAS Language Reference: Dictionary

Syntax

FILENAME fileref < device-type >' external-file ' <ENCODING=' encoding-value '> < host-options >;

FILENAME fileref device-type <' external-file '> <ENCODING=' encoding-value '> <' host-options '>;

FILENAME fileref (' pathname-1 ' ... 'pathname-n ') <ENCODING=' encoding-value '> <' host-options '>;

FILENAME fileref directory- name <ENCODING=' encoding-value '>;

FILENAME fileref < access-method >' external-file ' access-information ;

FILENAME fileref CLEAR _ALL_ CLEAR;

FILENAME fileref LIST _ALL_ LIST;

fileref

• is the name by which you reference the file. Under UNIX, the value of fileref can be an environment variable. See "Using Environment Variables to Assign Filerefs in UNIX Environments" on page 139 for more information.

device-type

• specifies a device for the output, such as a disk, terminal, printer, pipe, and so on. The device-type keyword must follow fileref and precede pathname . Table 16.1 on page 296 describes the valid device types. DISK is the default device type. If you are associating the fileref with a DISK file, then you do not need to specify the device type.

  Table 16.1: Device Information in the FILENAME Statement

  Device or Access Method	Function	External-file
  CATALOG	references a SAS catalog as an external file	is a valid two-, three-, or four-part SAS catalog name followed by catalog options (if needed). See SAS Language Reference: Dictionary for details.
  DISK	associates the fileref with a DISK file	is either the pathname for a single file or, if you are concatenating filenames, a list of pathnames separated by blanks or commas and enclosed in parentheses. The level of specification depends on your location in the file system. Table 4.6 on page 115 shows character substitutions that you can use when specifying a UNIX pathname.
  DUMMY	associates a fileref with a null device	None. DUMMY enables you to debug your application without reading from or writing to a device. Output to this device is discarded.
  EMAIL	sends electronic mail to an address	is an address and e-mail options. See "Sending Electronic Mail Using the FILENAME Statement (EMAIL)" on page 143 for details.
  FTP	reads or writes to a file from any machine on a network that is running an FTP server	is the pathname of the external file on the remote machine followed by FTP options. See the SAS Language Reference: Dictionary and "Assigning Filerefs to Files on Other Systems (FTP and SOCKET Access Types)" on page 137 for details. If you are transferring a file to UNIX from the z/OS operating environment and you want to use either the S370V or S370VB format to access that file, then the file must be of type RECFM=U and BLKSIZE=32760 before you transfer it. If you FTP to an z/OS machine, only one member of an z/OS PDS can be written to at a time. If you need to write to multiple members at the same time, an z/OS PDSE or a UNIX System Services directory should be used.
  PIPE	reads input from or writes output to a UNIX command	is a UNIX command. See Chapter 6, "Printing and Routing Output," on page 153 for details.
  PLOTTER	sends output to a plotter	is a device name and plotter options. See "Using PRTFILE and PRINT with a Fileref" on page 160 and "Using the PRINTTO Procedure in UNIX Environments" on page 161 for details.
  PRINTER	sends output to a printer	is a device name and printer option. See "Using PRTFILE and PRINT with a Fileref" on page 160 and "Using the PRINTTO Procedure in UNIX Environments" on page 161 for details.
  SOCKET	reads and writes information over a TCP/IP socket	depends on whether the SAS application is a server application or a client application. In a client application, external-file is the name or IP address of the host and the TCP/IP port number to connect to followed by any TCP/IP options. In a server application, external-file is the port number to create for listening, followed by the SERVER keyword, and then any TCP/IP options. See the SAS Language Reference: Dictionary for details.
  TAPE	associates a fileref with a tape	is the pathname for a tape device. The name specified should be the name of the special file associated with the tape device. See "Processing Files on TAPE in UNIX Environments" on page 149 for more information.
  TEMP	associates a fileref with an external file stored in the Work data library	None
  TERMINAL	associates a fileref with a terminal	is the pathname of a terminal.
  UPRINTER	sends output to the default printer that was set up through the Printer Setup dialog box	None
  URL	enables you to use the URL of a file to access it remotely	is the name of the file that you want to read from or write to on a URL server. The URL must be in one of these forms: http:// hostname / file http:// hostname : portno / file

' external-file '

• differs according to device type. Table 16.1 on page 296 shows the information appropriate to each device. Remember that UNIX filenames are case sensitive. See "Specifying Pathnames in UNIX Environments" on page 133 for more information.

ENCODING=' encoding-value '

• specifies the encoding to use when reading from or writing to the external file. The value for ENCODING= indicates that the external file has a different encoding from the current session encoding.

  When you read data from an external file, SAS transcodes the data from the specified encoding to the session encoding. When you write data to an external file, SAS transcodes the data from the session encoding to the specified encoding.

  For valid encoding values, see "Encoding Values in SAS Language Elements" in SAS National Language Support (NLS): User's Guide .

' host-options '

• are specific to UNIX environments. These options can be any of the following:

• BLKSIZE=

• BLK=

  • specifies the number of bytes that are physically written or read in one I/O operation. The default is 8K. The maximum is 1G-1. If you specify RECFM=S370VBS, then you should specify BLKSIZE=32760 in order to avoid errors with records longer than 255 characters.

• TERMSTR=

  • controls the end of line/record delimiters in PC and UNIX formatted files. This option enables the sharing of UNIX and PC formatted files between the two hosts.

    The following values for the TERMSTR= option:

    CRLF	Carriage Return Line Feed. This parameter is used to read and write PC format files.
    NL	Newline. This parameter is used to read and write UNIX format files. NL is the default format.

    If you are working on UNIX and reading a file that was created on a PC, specify TERMSTR=CRLF unless the file was created with the TERMSTR=NL option. If you are writing a file that will be read on a PC, specify TERMSTR=CRLF.

    If you are working on a PC and reading a file that was created on UNIX, specify TERMSTR=NL unless the file was created with the TERMSTR=CRLF option. If you are writing a file that will be read on UNIX, specify TERMSTR=NL.

• LRECL=

  • specifies the logical record length. Its meaning depends on the record format in effect (RECFM). The default is 256. The maximum length is 1G.

    • If RECFM=F, then the value for the LRECL= option determines either the number of bytes to be read as one record or the length of each output record. The output record is truncated or padded with blanks to fit the specified size.

    • If RECFM=N, then the value for the LRECL= option must be at least 256.

    • If RECFM=V, then the value for the LRECL= option determines the maximum record length. Records that are longer than the specified length are divided into multiple records on output and truncated on input.

    • If RECFM=S370VBS, then you should specify LRECL=32760 in order to avoid errors with records longer than 255 characters.

• MOD

  • indicates that data written to the file should be appended to the file.

• NEW OLD

  • indicates that a new file is to be opened for output. If the file already exists, then it is deleted and re-created. If you specify OLD, then the previous contents of the file are replaced. NEW is the default.

• RECFM=

  • specifies the record format. Values for the RECFM= option are

    D	default format (same as variable).
    F	fixed format. That is, each record has the same length. Do not use RECFM=F for external files that contain carriage-control characters.
    N	binary format. The file consists of a stream of bytes with no record boundaries.
    P	print format. On output, SAS writes carriage-control characters.
    V	variable format. Each record ends with a newline character.
    S370V	variable S370 record format (V).
    S370VB	variable block S370 record format (VB).
    S370VBS	variable block with spanned records S370 record format (VBS). If you specify RECFM=S3270VBS, then you should specify BLDSIZE=32760 and LRECL=32760 in order to avoid errors with records longer than 255 characters.

    The RECFM= option is used for both input and output.

• UNBUF

  • tells SAS not to perform buffered writes to the file on any subsequent FILE statement. This option applies especially when you are reading from or writing to a data collection device. As explained in SAS Language Reference: Dictionary ,it also prevents buffered reads on INFILE statements.

'pathname-1'...'pathname-n'

• are pathnames for the files that you want to access with the same fileref. Use this form of the FILENAME statement when you want to concatenate filenames. Concatenation of filenames is available only for DISK files, so you do not have to specify the device-type . Separate the pathnames with either commas or blank spaces. Enclose each pathname in quotation marks. Table 4.6 on page 115 shows character substitutions you can use when specifying a pathname. If the fileref that you are defining is to be used for input, then you can also use wildcards as described in "Using Wildcards in Pathnames (Input Only)" on page 134. Remember that UNIX filenames are case-sensitive.

directory-name

• specifies the directory that contains the files that you want to access. For more information, see "Assigning a Fileref to a Directory (Using Aggregate Syntax)" on page 138.

access-method

• can be CATALOG, SOCKET, FTP, or URL. Table 16.1 on page 296 describes the information expected by these access methods .

access-information

• differs according to the access method. Table 16.1 on page 296 shows the information appropriate to each access method.

CLEAR

• clears the specified fileref or, if you specify _ALL_, clears all filerefs that are currently defined.

  Note	You cannot clear a fileref that is defined by an environment variable. Filerefs that are defined by environment variables are assigned for the entire SAS session.

_ALL_

• refers to all filerefs currently defined. You can use this keyword when you are listing or clearing filerefs.

LIST

• prints to the SAS log the pathname of the specified fileref or, if you specify _ALL_, lists the definition for all filerefs that are currently defined. Filerefs defined as environment variables appear only if you have already used those filerefs in a SAS statement. If you are using the Bourne shell or the Korn shell, SAS cannot determine the name of a preopened file, so it displays the following string instead of a filename:

  <File Descriptor number >

See "Using Environment Variables to Assign Filerefs in UNIX Environments" on page 139 for more information.

See Also

• Chapter 5, "Using External Files and Devices," on page 131

• Chapter 6, "Printing and Routing Output," on page 153

FOOTNOTE Statement

Prints up to ten lines of text at the bottom of the procedure output

Valid: anywhere

UNIX specifics: maximum length of footnote

See: FOOTNOTE Statement in SAS Language Reference: Dictionary

Syntax

FOOTNOTE < n ><' text '" text ">;

Details

The maximum footnote length is 255 characters. If the length of the specified footnote is greater than the value of the LINESIZE option, SAS truncates the footnote to the line size.

%INCLUDE Statement

Includes and executes SAS statements and data lines

Valid: anywhere

UNIX specifics: source , if a file specification is used; valid values for encoding-value

See: %INCLUDE Statement in SAS Language Reference: Dictionary

Syntax

%INCLUDE source-1 <...source-n> </<SOURCE2> <S2=length><ENCODING='encoding-value'><host-options>>;

source

• describes the location you want to access with the %INCLUDE statement. The three possible sources are a file specification, internal lines, or keyboard entry. The file specification can be any of the file specification forms that are discussed in "Accessing an External File or Device in UNIX Environments" on page 133.

  Note	When using aggregate syntax, if the member name contains a leading digit, enclose the member name in quotation marks. If the member name contains a macro variable reference, use double quotation marks.

ENCODING= 'encoding-value'

• specifies the encoding to use when reading from the specified source. The value for ENCODING= indicates that the specified source has a different encoding from the current session encoding.

  When you read data from the specified source, SAS transcodes the data from the specified encoding to the session encoding.

  For valid encoding values, see "Encoding Values in SAS Language Elements" in SAS National Language Support (NLS): User's Guide .

host-options

• consists of statement options that are valid under UNIX. The following options are available:

• BLKSIZE= block-size

• BLK= block-size

  • specifies the number of bytes that are physically read or written in an I/O operation. The default is 8K. The maximum is 1M.

• LRECL= record-length

  • specifies the record length (in bytes). Under UNIX, the default is 256. The value of record-length can range from 1 to 1,048,576 (1 megabyte).

• RECFM= record-format

  • specifies the record format. The following values are valid under UNIX:

    D	default format (same as variable).
    F	fixed format. That is, each record has the same length.
    N	binary format. The file consists of a stream of bytes with no record boundaries.
    P	print format.
    V	variable format. Each record ends with a newline character.
    S370V	variable S370 record format (V).
    S370VB	variable block S370 record format (VB).
    S370VBS	variable block with spanned records S370 record format (VBS).

  The S370 values are valid with files laid out as z/OS files only. That is, files that are binary, have variable-length records, and are in EBCDIC format. If you want to use a fixed-format z/OS file, first copy it to a variable-length, binary z/OS file.

Details

If you specify any options on the %INCLUDE statement, remember to precede the options list with a forward slash (/).

See Also

• Chapter 5, "Using External Files and Devices," on page 131

INFILE Statement

Specifies an external file to be read with an INPUT statement

Valid: in a DATA step

UNIX specifics: valid values for encoding-value , file-specification , and host-options

See: INFILE Statement in SAS Language Reference: Dictionary

Syntax

INFILE file-specification <ENCODING=' encoding-value '> < options >< host-options >;

file-specification

• can be any of the file specification forms that are discussed in the "Accessing an External File or Device in UNIX Environments" on page 133.

ENCODING= 'encoding-value'

• specifies the encoding to use when reading from the external file. The value for ENCODING= indicates that the external file has a different encoding from the current session encoding.

  When you read data from an external file, SAS transcodes the data from the specified encoding to the session encoding.

  For valid encoding values, see "Encoding Values in SAS Language Elements" in SAS National Language Support (NLS): User's Guide .

host-options

• are specific to UNIX environments. These options can be any of the following:

• BLKSIZE=

• BLK=

  • specifies the number of bytes that are physically read in one I/O operation. The default is 8K. The maximum is 1G-1.

• TERMSTR=

  • controls the end of line/record delimiters in PC and UNIX formatted files. This option enables the sharing of UNIX and PC formatted files between the two hosts.

    The following are values for the TERMSTR= option:

    CRLF	Carriage Return Line Feed. This parameter is used to read PC format files.
    NL	Newline. This parameter is used to read UNIX format files. NL is the default.

    Use TERMSTR=CRLF to read a file that was created on the PC. If this PC format file was created using TERMSTR=NL, then the TERMSTR option is unnecessary.

• LRECL=

  • specifies the logical record length. Its meaning depends on the record format in effect (RECFM). The default is 256. The maximum length is 1G.

    • If RECFM=F, then the value for the LRECL= option determines the number of bytes to be read as one record.

    • If RECFM=N, then the value for the LRECL= option must be at least 256.

    • If RECFM=V, then the value for the LRECL= option determines the maximum record length. Records that are longer than the specified length are truncated.

• RECFM=

  • specifies the record format. The following values are valid under UNIX:

    D	default format (same as variable).
    F	fixed format. That is, each record has the same length.
    N	binary format. The file consists of a stream of bytes with no record boundaries.
    P	print format.
    V	variable format. Each record ends with a newline character.
    S370V	variable S370 record format (V).
    S370VB	variable block S370 record format (VB).
    S370VBS	variable block with spanned records S370 record format (VBS).

Details

The ENCODING= option is valid only when the INFILE statement includes a file specification that is not a reserved fileref. If the INFILE statement includes the ENCODING= argument and the reserved filerefs DATALINES or DATALINES4 as a file-specification , then SAS issues an error message. The ENCODING= value in the INFILE statement overrides the value of the ENCODING= system option.

See Also

• Chapter 5, "Using External Files and Devices," on page 131

LENGTH Statement

Specifies the number of bytes that SAS uses to store a variable's value

Valid: in a DATA step

UNIX specifics: valid numeric variable lengths

See: LENGTH Statement in SAS Language Reference: Dictionary

Syntax

LENGTH < variable-1 >< ...variable-n ><$> length <DEFAULT= n >

length

• can range from 3 to 8 for numeric variables under UNIX. The minimum length you can specify for a numeric variable depends on the floating-point format used by your system. Because most systems use the IEEE floating-point format, the minimum is 3 bytes.

DEFAULT= n

• changes the default number of bytes that are used for storing the values of newly created numeric variables from 8 to the value of n . Under UNIX, n can range from 3 to 8.

See Also

• Chapter 8, "Data Representation," on page 197

LIBNAME Statement

Associates or disassociates one or more SAS data libraries with a libref; lists the characteristics of a SAS data library

Valid: anywhere

UNIX specifics: engine , library , and engine/host-options

See: LIBNAME Statement in SAS Language Reference: Dictionary

Syntax

LIBNAME libref < engine >' SAS-data-library '< options >< engine/host-options >;

LIBNAME libref < engine >(' library-1 '<,...' library-n '>) < options >;

LIBNAME libref (' library-1 ' libref-1 ,...,' library-n ' librefn );

LIBNAME libref CLEAR_ALL _ CLEAR;

LIBNAME libref LIST_ALL _ LIST;

libref

• is any valid libref as documented in SAS Language Reference: Dictionary . SAS reserves some librefs for special system libraries. See "Librefs Assigned by SAS in UNIX Environments" on page 118 for more information.

engine

• is one of the library engines supported under UNIX. See "Details" on page 303 for a description of the engines. If no engine name is specified, SAS determines which engine to use as described in "Omitting Engine Names from the LIBNAME Statement" on page 304.

' SAS-data-library '

• differs according to the engine that you specify and according to your current working directory. Table 16.2 on page 303 describes what each engine expects for this argument. Specify directory pathnames as described in "Specifying Pathnames in UNIX Environments" on page 114. You cannot create directories with the LIBNAME statement. The directory that you specify here must already exist, and you must have permissions to it. Enclose the data library name in quotation marks. Remember that UNIX pathnames are case-sensitive.

  Table 16.2: Engine Names and Descriptions

  Engine Type	Name (Alias)	Description	SAS-data-library
  default	V9 (BASE) V8	enables you to create new SAS data files and access existing SAS data files that were created with Version 8 or SAS 9. The V8 and V9 engines are identical. This engine enables read access to data files that were created with some earlier versions of SAS, but this engine is the only one that supports SAS 9 catalogs. This engine allows for data set indexing and compression and is also documented in SAS Language Reference: Dictionary .	is the pathname of the directory containing the library.
  sequential	V9TAPE (TAPE) V8TAPE	accesses SAS data files that were created in a sequential format, whether on tape or on disk. This engine requires less overhead than the default engine because sequential access is simpler than random access. This engine is also documented in SAS Language Reference: Dictionary .	is the name of the special file (see "Introduction to External Files and Devices in UNIX Environments" on page 132) associated with the sequential device, such as /dev/rmt/0mn .
  	V6TAPE	accesses V6 SAS data files that were created in a sequential format. This engine is read-only.	is the name of the special file (see "Introduction to External Files and Devices in UNIX Environments" on page 132) associated with the sequential device, such as /dev/rmt/0mn .
  compatibility	V6	accesses any data file that was created by Releases 6.09 through 6.12. This engine is read-only.	is the pathname of the directory containing the library.
  servers	SPDS	enables communication between a client session and a data server. You must have the Scalable Performance Data Server licensed on your client machine to use this engine. Refer to Scalable Performance Data Server User's Guide, Version 2 for more information.	is the logical LIBNAME domain name for an SPDS data library on the server machine. The name server resolves the domain name into the physical path for the library.
  	MDDB	enables communication between a client session and an MDDB server. You must have SAS/MDDB Server licensed either or your client machine or on your server machine to use this engine. Refer to SAS MDDB Server Software: Administration Guide for complete information.
  transport	XPORT	accesses transport data sets. This engine creates machine-independent SAS transport files that can be used under all hosts running Release 6.06 or later of SAS. This engine is documented in Moving and Accessing SAS Files .	is the pathname of either a sequential device or a disk file.
  XML	XML	generates (writes) and processes (reads) any XML document, which is an application- and machine-independent file.	is the pathname of the XML document.
  interface	BMDP	provides read-only access to BMDP files. This engine is available only on AIX, HP-UX, and Solaris.	is the pathname of the data file.
  	OSIRIS	provides read-only access to OSIRIS files.	is the pathname of the data file.
  	SPSS	provides read-only access to SPSS files	is the pathname of the data file.

' library-n ' libref-n

• are pathnames or librefs (that have already been assigned) for the data libraries that you want to access with one libref. Use these forms of the LIBNAME statement when you want to concatenate data libraries. Separate the pathnames with either commas or blank spaces. Enclose library pathnames in quotation marks. Do not enclose librefs in quotation marks. See "Assigning a Libref to Several Directories (Concatenating Directories)" on page 115 for more information.

options

• are LIBNAME statement options that are available in all operating environments. See SAS Language Reference: Dictionary for information about these options.

engine/host-options

• can be any of the options described in "Engine/Host Options" on page 305.

_ALL_

• refers to all librefs currently defined. You can use this keyword when you are listing or clearing librefs.

CLEAR

• clears the specified libref or, if you specify _ALL_, clears all librefs that are currently defined. Sasuser, Sashelp, and Work remain assigned.

  Note	When you clear a libref defined by an environment variable, the variable remains defined, but it is no longer considered a libref. You can still reuse it, either as a libref or a fileref. See "Using Environment Variables as Librefs in UNIX Environments" on page 117 for more information.

  SAS automatically clears the association between librefs and their respective data libraries at the end of your job or session. If you want to associate an existing libref with a different SAS data library during the current session, you do not have to end the session or clear the libref. SAS automatically reassigns the libref when you issue a LIBNAME statement for the new SAS data library.

LIST

• prints to the SAS log the engine, pathname, file format, access permissions, and so on, that are associated with the specified libref or, if you specify _ALL_, prints this information for all librefs that are currently defined. Librefs defined as environment variables appear only if you have already used those librefs in a SAS statement.

Details

There are two main types of engines:

View engines

• enable SAS to read SAS data views that are described by SAS/ACCESS software, the SQL procedure, and DATA step views. The use of SAS view engines is automatic because the name of the view engine is stored as part of the descriptor portion of the SAS data set.

Library engines

• control access at the SAS data library level. Every SAS data library has an associated library engine, and the files in that library can be accessed only through that engine. There are two types of library engines:

  • native engines

    • access SAS files created and maintained by SAS. See the following table for a description of these engines.

  • interface engines

    • treat other vendors ' files as if they were SAS files. See the following table and "Accessing BMDP, OSIRIS, or SPSS Files in UNIX Environments" on page 125 for more information.

Omitting Engine Names From the LIBNAME Statement

It is always more efficient to specify the engine name than to have SAS determine the correct engine. However, if you omit an engine name in the LIBNAME statement or if you define an environment variable to serve as a libref, SAS determines the appropriate engine.

If you have specified the ENGINE= system option, SAS uses the engine name that you specified. See "ENGINE System Option" on page 327 for a discussion of the ENGINE= system option.

If you did not specify the ENGINE= system option, SAS looks at the extensions of the files in the given directory and uses these rules to determine an engine:

• If all the SAS data sets in the library were created by the same engine, the libref is assigned using that engine.

  Note	If the engine used to create the data sets is not the same as the default engine, then you will not be able to create a view or stored program. See "Using Multiple Engines for a Library in UNIX Environments" on page 116 for more information.

• If there are no SAS data sets in the given directory, the libref is assigned using the default engine.

• If there are SAS data sets from more than one engine, the system issues a message about finding mixed engine types and assigns the libref using the default engine.

Engine/Host Options

The LIBNAME statement accepts the following options:

FILELOCKS=NONE FAIL CONTINUE

• specifies whether file locking is on or off for the library that you are defining. This LIBNAME statement option works like the FILELOCKS system option, except that it applies only to the library that you are defining. See "FILELOCKS System Option" on page 329 for more information.

  You can also specify any of the options supported by the SPDS engines. SPDS is the Scalable Performance Data Server. Refer to Scalable Performance Data Server User's Guide, Version 2 for a description of these options.

See Also

• Chapter 4, "Using SAS Files," on page 101

SYSTASK Statement

Executes asynchronous tasks

Valid: anywhere

UNIX specifics: all

Syntax

SYSTASK COMMAND " host-command "

• <WAITNOWAIT>

• <TASKNAME= taskname >

• <MNAME= name-variable >

• <STATUS= status-variable >

• <SHELL<=" shell-command ">>

• <CLEANUP>;

SYSTASK LIST <_ALL_ taskname > <STATE> <STATVAR>;

SYSTASK KILL taskname < taskname ...>;

COMMAND

• executes the host-command .

LIST

• lists either a specific active task or all of the active tasks in the system. A task is active if it is running or if it has completed and has not been waited for using the WAITFOR statement.

KILL

• forces the termination of the specified task(s).

host-command

• specifies the name of a UNIX command (including any command-specific options) or the name of an X Windows or Motif application. Enclose the command in either single or double quotation marks. If the command options require quotation marks, repeat them for each option. For example:

  SYSTASK COMMAND "xdialog -m ""There was an error."" -t ""Error"" -o";

  Note	The host-command that you specify cannot require input from the keyboard.

WAIT NOWAIT

• determines whether SYSTASK COMMAND suspends execution of the current SAS session until the task has completed. NOWAIT is the default. For tasks that start with the NOWAIT option, you can use the WAITFOR statement when necessary to suspend execution of the SAS session until the task has finished. See "WAITFOR Statement" on page 308.

TASKNAME= taskname

• specifies a name that identifies the task. Task names must be unique among all active tasks. A task is active if it is running or if it has completed and has not been waited for using the WAITFOR statement. Duplicate task names generate an error in the SAS log. If you do not specify a task name, SYSTASK will automatically generate a name. If the task name contains a blank character, enclose it in quotation marks.

  Task names cannot be reused, even if the task has completed, unless you either issue the WAITFOR statement for the task or you specify the CLEANUP option.

MNAME= name-variable

• specifies a macro variable in which you want SYSTASK to store the task name that it automatically generated for the task. If you specify both the TASKNAME option and the MNAME option, SYSTASK copies the name that you specified with TASKNAME into the variable that you specified with MNAME.

STATUS= status-variable

• specifies a macro variable in which you want SYSTASK to store the status of the task. Status variable names must be unique among all active tasks.

SHELL<=" shell-command ">

• specifies that the host-command should be executed with the host shell command. If you specify a shell-command , SYSTASK uses the shell command that you specify to invoke the shell; otherwise , SYSTASK uses the default shell. Enclose the shell command in quotes.

  Note	The SHELL option assumes that the shell command that you specify uses the -i option to pass statements. Usually, your shell command will be sh , csh , ksh , or bash .

CLEANUP

• specifies that the task should be removed from the LISTTASK output when the task completes. You can then reuse the task name without issuing the WAITFOR statement.

Details

SYSTASK enables you to execute host-specific commands from within your SAS session or application. Unlike the X statement, SYSTASK runs these commands as asynchronous tasks, which means that these tasks execute independently of all other tasks that are currently running. Asynchronous tasks run in the background, so you can perform additional tasks while the asynchronous task is still running.

For example, to start a new shell and execute the UNIX cp command in that shell, you might use this statement:

systask command "cp /tmp/sas* ~/archive/" taskname="copyjob1" status=copysts1 shell;

The return code from the cp command is saved in the macro variable COPYSTS1.

The output from the command is displayed in the SAS log.

There are two types of asynchronous processes that can be started from SAS:

Task

• All tasks started with SYSTASK COMMAND are of type Task. For these tasks, if you do not specify STATVAR or STATE, then SYSTASK LIST displays the task name, type, and state, and the name of the status macro variable. You can use SYSTASK KILL to kill only tasks of type Task.

SAS/CONNECT Process

• Tasks started from SAS/CONNECT with the RSUBMIT statement are of type SAS/CONNECT Process. For SAS/CONNECT processes, SYSTASK LIST displays the task name, type, and state. You can use SYSTASK KILL to kill a SAS/CONNECT process. For information about starting SAS/CONNECT processes, refer to SAS/CONNECT User's Guide .

  Note	The preferred method for displaying any task (not just SAS/CONNECT processes) is to use the LISTTASK statement instead of SYSTASK LIST. The preferred method for ending a task is using the KILLTASK statement in place of SYSTASK KILL.

The SYSRC macro variable contains the return code for the SYSTASK statement. The status variable that you specify with the STATUS option contains the return code of the process started with SYSTASK COMMAND. To ensure that a task executes successfully, you should monitor both the status of the SYSTASK statement and the status of the process that is started by the SYSTASK statement.

If a SYSTASK statement cannot execute successfully, the SYSRC macro variable will contain a non-zero value. For example, there might be insufficient resources to complete a task or the SYSTASK statement might contain syntax errors. With the SYSTASK KILL statement, if one or more of the processes cannot be killed , SYSRC is set to a non-zero value.

When a task is started, its status variable is set to NULL. You can use the status variables for each task to determine which tasks failed to complete. Any task whose status variable is NULL did not complete execution. If a task terminates abnormally, then its status variable will be set to -1 . See "WAITFOR Statement" on page 308 for more information about the status variables.

Unlike the X statement, you cannot use the SYSTASK statement to start a new interactive session.

See Also

• "WAITFOR Statement" on page 308

• "X Statement" on page 310

• "Executing Operating System Commands from Your SAS Session" on page 13

TITLE Statement

Specifies title lines for SAS output

Valid: anywhere

UNIX specifics: maximum length of title

See: TITLE Statement in SAS Language Reference: Dictionary

Syntax

TITLE < n ><' text '" text ">;

Details

In interactive modes, the maximum title length is 254 characters; otherwise, the maximum length is 200 characters. If the length of the specified title is greater than the value of the LINESIZE option, the title is truncated to the line size.

WAITFOR Statement

Suspends execution of the current SAS session until the specified tasks finish executing

Valid: anywhere

UNIX specifics: all

Syntax

WAITFOR <_ANY _ALL_> taskname < taskname ...> <TIMEOUT= seconds >;

taskname

• specifies the name of the task(s) that you want to wait for. See "SYSTASK Statement" on page 305 for information about task names. The task name(s) that you specify must match exactly the task names assigned through the SYSTASK COMMAND statement. You cannot use wildcards to specify task names.

_ANY_ _ALL_

• suspends execution of the current SAS session until either one or all of the specified tasks finishes executing. The default setting is _ANY_, which means that as soon as one of the specified task(s) completes executing, the WAITFOR statement will finish executing.

TIMEOUT= seconds

• specifies the maximum number of seconds that WAITFOR should suspend the current SAS session. If you do not specify the TIMEOUT option, WAITFOR will suspend execution of the SAS session indefinitely.

Details

The WAITFOR statements suspends execution of the current SAS session until the specified task(s) finish executing or until the TIMEOUT= interval (if specified) has elapsed. If the specified task was started with the WAIT option, then the WAITFOR statement ignores that task. See "SYSTASK Statement" on page 305 for a description of the WAIT option.

For example, the following statement starts three different X Windows programs and waits for them to complete:

systask command "xv" taskname=pgm1; systask command "xterm" taskname=pgm2; systask command "xcalc" taskname=pgm3; waitfor _all_ pgm1 pgm2 pgm3;

The WAITFOR statement can be used to execute multiple concurrent SAS sessions. The following statements start three different SAS jobs and suspend the execution of the current SAS session until those three jobs have finished executing:

systask command "sas myprog1.sas" taskname=sas1; systask command "sas myprog2.sas" taskname=sas2; systask command "sas myprog3.sas" taskname=sas3; waitfor _all_ sas1 sas2 sas3;

The SYSRC macro variable contains the return code for the WAITFOR statement. If a WAITFOR statement cannot execute successfully, the SYSRC macro variable will contain a non-zero value. For example, the WAITFOR statement may contain syntax errors. If the number of seconds specified with the TIMEOUT option elapses, then the WAITFOR statement finishes executing, and SYSRC is set to a non-zero value if

• you specify a single task that does not finish executing

• you specify more than one task and the _ANY_ option (which is the default setting), but none of the tasks finishes executing

• you specify more than one task and the _ALL_ option, and any one of the tasks does not finish executing.

Any task whose status variable is still NULL after the WAITFOR statement has executed did not complete execution. See "SYSTASK Statement" on page 305 for a description of status variables for individual tasks.

See Also

• "SYSTASK Statement" on page 305

• "X Statement" on page 310

• SAS/CONNECT User's Guide

• "Executing Operating System Commands from Your SAS Session" on page 13

X Statement

Issues an operating system command from within a SAS session

Valid: anywhere

UNIX specifics: valid operating system command

See: X Statement in SAS Language Reference: Dictionary

Syntax

X <' host-command '>;

host-command

• specifies the UNIX command. If you specify only one UNIX command, you do not need to enclose it in quotation marks. Also, if you are running SAS from the Korn shell, you cannot use aliases.

Details

The X statement issues a UNIX command from within a SAS session. SAS executes the X statement immediately.

Neither the X statement nor the %SYSEXEC macro program statement is intended for use during the execution of a DATA step. The CALL SYSTEM routine, however, can be executed within a DATA step. See "CALL SYSTEM Routine" on page 239 for an example.

See Also

• "Executing Operating System Commands from Your SAS Session" on page 13