Dictionary

BYTE Function

Returns one character in the ASCII collating sequence

Category: Character

UNIX specifics: Uses the ASCII collating sequence

See: BYTE Function in SAS Language Reference: Dictionary

Syntax

BYTE ( n )

n

• specifies an integer that represents a specific ASCII character. The value of n can range from 0 to 255.

Details

If the BYTE function returns a value to a variable that has not yet been assigned a length, by default the variable is assigned a length of 1.

CALL SLEEP Routine

Suspends the execution of a program that invokes this CALL routine for a specified period of time

Category: Special

UNIX specifics: All

See: CALL SLEEP Routine in SAS Language Reference: Dictionary

Syntax

CALL SLEEP ( n <, unit >);

n

• is a numeric constant that specifies the number of units of time for which you want to suspend execution of a program.

unit

• specifies the unit of time, as a power of 10, which is applied to n . For example, 1 corresponds to a second, and .001 corresponds to a millisecond. The default is .001.

Details

CALL SLEEP puts the DATA step in which it is invoked into a non-active wait state, using no CPU time and performing no input or output. If you are running multiple SAS processes, each process can execute CALL SLEEP independently without affecting the other processes.

Note  

Extended sleep periods can trigger automatic host session termination based on timeout values set at your site. Contact your host system administrator as necessary to determine the timeout values used at your site.

CALL SYSTEM Routine

Submits an operating system command for execution

Category: Special

UNIX specifics: Command must evaluate to a valid UNIX command

See: CALL SYSTEM Routine in SAS Language Reference: Dictionary

Syntax

CALL SYSTEM ( command );

command

• specifies any of the following: a UNIX command enclosed in quotation marks, an expression whose value is a UNIX command, or the name of a character variable whose value is a UNIX command.

Details

The CALL SYSTEM routine issues operating system commands. The output of the command appears in the window from which you invoked SAS.

The value of the XSYNC system option affects how the CALL SYSTEM routine works.

Note  

The CALL SYSTEM routine can be executed within a DATA step. However, neither the X statement nor the %SYSEXEC macro program statement is intended for use during the execution of a DATA step.

In the following example, for each record in answer.week , if the resp variable is y , the CALL SYSTEM routine will mail a message.

 data _null_;      set answer.week;      if resp='y' then         do;            call system('mail mgr < $HOME/msg');         end;      run; 

See Also

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

COLLATE Function

Returns an ASCII collating sequence character string

Category: Character

UNIX specifics: Uses ASCII collating sequence

See: COLLATE Function in SAS Language Reference: Dictionary

Syntax

COLLATE ( start-position <, end-position >) ( start-position <,, length >)

start-position

• specifies the numeric position in the collating sequence of the first character to be returned.

end-position

• specifies the numeric position in the collating sequence of the last character to be returned.

length

• specifies the number of characters in the collating sequence.

Details

The COLLATE function returns a string of ASCII characters. The ASCII collating sequence contains 256 positions , referenced with the numbers 0 through 255. Characters above 127 correspond to characters used in European languages as defined in the ISO 8859 character set.

Unless you assign the return value of the COLLATE function to a variable with a defined length less than 200, the ASCII collating sequence string is padded with blanks to a length of 200. If the ASCII collating sequence is greater than 200 characters, you must specify the length for the return string in a LENGTH statement; otherwise , the returned string will be truncated to a length of 200 characters. For more information, see the following examples.

Examples: How SAS Determines the Length of the Return String

Example 1: Truncating the Variable Length to 200 Characters

Since the following code does not include a LENGTH statement, the length attribute for the Address variable is truncated to 200 characters.

 data sales;      Address=collate(1,241);   run;   proc contents;   run; 

Output 12.1: Portion of PROC CONTENTS Output

 Alphabetic List of Variables and Attributes #      Variable      Type      Len 1      Address       Char      200 

 

Since length for Address is limited to 200 characters, the returned string from the COLLATE function will be limited to 200 characters.

Example 2: Specifying a Length Greater Than 200 Characters

To specify a length greater than 200 characters for a specific variable, you can use the LENGTH statement. In the following code, the length of Address is specified as 240 characters.

 data sales;      length Address 0;      Address=collate(1,241);   run;   proc contents;   run; 

Output 12.2: Portion of PROC CONTENTS Output

 Alphabetic List of Variables and Attributes #      Variable      Type      Len 1      Address       Char      240 

 

Since the length of Address is set to 240 characters, the returned string from the COLLATE function will contain 240 characters.

See Also

• "LENGTH Statement" on page 300

DINFO Function

Returns information about a directory

Category: External Files

UNIX specifics: Directory pathname is the only information available

See: DINFO Function in SAS Language Reference: Dictionary

Syntax

DINFO ( directory-id , info -item )

directory-id

• specifies the identifier that was assigned when the directory was opened, generally by the DOPEN function.

info-item

• specifies the information item to be retrieved. DINFO returns a blank if the value of info-item is invalid.

Details

Directories that are opened with the DOPEN function are identified by a directory-id . Use DOPTNAME to determine the names of the available system-dependent information items. Use DOPTNUM to determine the number of directory information items available.

Under UNIX, the only info-item available is Directory, which is the pathname of directory-id .If directory-id points to a list of concatenated directories, then Directory is the list of concatenated directory names.

See Also

• "DOPEN Function" on page 242

• "DOPTNAME Function" on page 242

• "DOPTNUM Function" on page 243

DOPEN Function

Opens a directory and returns a directory identifier value

Category: External Files

UNIX specifics: fileref can be assigned with an environment variable

See: DOPEN Function in SAS Language Reference: Dictionary

Syntax

DOPEN ( fileref )

fileref

• specifies the fileref assigned to the directory.

Details

DOPEN opens a directory and returns a directory identifier value (a number greater than 0) that is used to identify the open directory in other SAS external file access functions. If the directory could not be opened, DOPEN returns 0. The directory to be opened must be identified by a fileref.

DOPTNAME Function

Returns the name of a directory information item

Category: External Files

UNIX specifics: Directory is the only item available

See: DOPTNAME Function in SAS Language Reference: Dictionary

Syntax

DOPTNAME ( directory-id , nval )

directory-id

• specifies the identifier that was assigned when the directory was opened, generally by the DOPEN function.

nval

• specifies the sequence number of the information item.

Details

Under UNIX, the only directory information item available is Directory, which is the pathname of the directory-id . The nval , or sequence number, of Directory is 1. If directory-id points to a list of concatenated directories, then Directory is the list of concatenated directory names.

DOPTNUM Function

Returns the number of information items that are available for a directory

Category: External Files

UNIX specifics: Directory is the only item available

See: DOPTNUM Function in SAS Language Reference: Dictionary

Syntax

DOPTNUM ( directory-id )

directory-id

• specifies the identifier that was assigned when the directory was opened, generally by the DOPEN function.

Details

Under UNIX, only one information item is available for a directory. The name of the item is Directory; its value is the pathname or list of pathnames for directory-id , and its sequence number is 1. Since only one information item is available for a directory, this function will return a value of 1.

FDELETE Function

Deletes an external file or an empty directory

Category: External Files

UNIX specifics: fileref can be assigned with an environment variable

See: FDELETE Function in SAS Language Reference: Dictionary

Syntax

FDELETE (" fileref ")

fileref

• specifies the fileref that is assigned to the external file or directory. The fileref cannot be associated with a list of concatenated filenames or directories. If the fileref is associated with a directory, the directory must be empty. You must have permission to delete the file. Refer to the UNIX man page for chmod for more information about permissions.

  Under UNIX, fileref can also be an environment variable. The fileref must be enclosed in double quotation marks.

Details

FDELETE returns 0 if the operation was successful, or a non-zero number if it was not successful.

FEXIST Function

Verifies the existence of an external file by its fileref

Category: External Files

UNIX specifics: fileref can be assigned with an environment variable

See: FEXIST Function in SAS Language Reference: Dictionary

Syntax

FEXIST (" fileref ")

fileref

• specifies the fileref assigned to the external file or directory. Under UNIX, fileref can also be an environment variable. The fileref or the environment variable you specify must be enclosed in double quotation marks.

Details

The FEXIST function returns a value of 1 if the external file that is associated with fileref exists, and a value of 0 if the file does not exist.

FILEEXIST Function

Verifies the existence of an external file by its physical name

Category: External Files

UNIX specifics: filename can be assigned with an environment variable

See: FILEEXIST Function in SAS Language Reference: Dictionary

Syntax

FILEEXIST (" filename ")

filename

• specifies a fully qualified physical filename of the external file. In a DATA step, filename can be a character expression, a string in quotation marks, or a DATA step variable. In a macro, filename can be any expression.

  Under UNIX, filename can also be an environment variable. The filename or the environment variable you specify must be enclosed in double quotation marks.

Details

FILEEXIST returns 1 if the external file exists and 0 if the external file does not exist.

FILENAME Function

Assigns or deassigns a fileref for an external file, directory, or output device

Category: External Files

UNIX specifics: fileref can be assigned with an environment variable; valid values of device-type and host-options

See: FILENAME Function in SAS Language Reference: Dictionary

Syntax

FILENAME (" fileref ", " filename "<, device-type <, host-options <, dir-ref >>>)

fileref

• in a DATA step, specifies the fileref to assign to an external file. In a macro (for example, in the %SYSFUNC function), fileref is the name of a macro variable (without an ampersand) whose value contains the fileref to assign to the external file. (For details, see the FILENAME function in SAS Language Reference: Dictionary .)

  Under UNIX, the fileref can also be a UNIX environment variable. The fileref or the environment variable you specify must be enclosed in double quotation marks.

filename

• specifies the external file. Specifying a blank filename ("")deassigns a fileref that was previously assigned.

  Under UNIX, the filename differs according to the device type. Table 16.1 on page 296 shows the information appropriate to each device. Remember that UNIX filenames are case-sensitive. The filename you specify must be enclosed in double quotation marks.

device-type

• specifies the type of device or the access method that is used if the fileref points to an input or output device or location that is not a physical file. It can be any one of the devices listed in Table 16.1 on page 296. DISK is the default device type.

host-options

• are options that are specific to UNIX. You can use any of the options that are available on the FILENAME statement. See "FILENAME Statement" on page 293 for a description of the host options.

dir-ref

• specifies the fileref that is assigned to the directory in which the external file resides.

Details

FILENAME returns a 0 if the operation is successful, and a non-zero number if it was not successful.

FILEREF Function

Verifies that a fileref has been assigned for the current SAS session

Category: External Files

UNIX specifics: fileref can be assigned with an environment variable

See: FILEREF Function in SAS Language Reference: Dictionary

Syntax

FILEREF (" fileref ")

fileref

• specifies the fileref assigned to be validated .

  Under UNIX, fileref can also be a UNIX environment variable. The fileref or the environment variable you specify must be enclosed in double quotation marks.

Details

A negative return code indicates that the fileref exists but the physical file associated with the fileref does not exist. A positive value indicates that the fileref is not assigned. A value of zero indicates that the fileref and external file both exist.

See "FILENAME Function" on page 245 for more information.

FINFO Function

Returns the value of a file information item for an external file

Category: External Files

UNIX specifics: info-item s available

See: FINFO Function in SAS Language Reference: Dictionary

Syntax

FINFO ( file-id , info-item )

file-id

• specifies the identifier that was assigned when the file was opened, generally by the FOPEN function.

info-item

• specifies the name of the file information item to be retrieved. This is a character value. Info-item is either a variable containing a valid value or the valid value in quotation marks.

  Under UNIX, info-item for disk files can have one of the following values:

  • File Name

  • Owner Name

  • Group Name

  • Access Permission

  • File Size (bytes)

• If you concatenate filenames, then an additional info-item is available: File List.

  If you are using pipe files, then the only valid value for info-item is Pipe Command.

Details

The FINFO function returns the value of a system-dependent information item for an external file that was previously opened and assigned a file-id by the FOPEN function. FINFO returns a blank if the value given for info-item is invalid.

For an example of how to use the FINFO function, see "Example: File Attributes When Using the Pipe Device Type" on page 248.

See Also

• "FOPEN Function" in SAS Language Reference: Dictionary

FOPTNAME Function

Returns the name of an information item for an external file

Category: External Files

UNIX specifics: Information items available

See: FOPTNAME Function in SAS Language Reference: Dictionary SAS Language Reference: Dictionary

Syntax

FOPTNAME ( file-id , nval )

file-id

• specifies the identifier that was assigned when the file was opened, generally by the FOPEN function.

nval

• specifies the number of the file information item to be retrieved. The following table shows the values that nval can have in UNIX operating environments for single, pipe, and concatenated files.

Information Items Available For...
nval	Single File	Pipe Files	Concatenated Files
1	File Name	Pipe Command	File Name
2	Owner Name		File List
3	Group Name		Owner Name
4	Access Permission		Group Name
5	File Size (bytes)		Access Permission
6			File Size (bytes)

Details

FOPTNAME returns a blank if an error occurs.

Example: File Attributes When using the Pipe Device Type

The following example creates a data set that contains the name and value attributes returned by the FOPTNAME function when you are using pipes:

 data fileatt;      length name $ 20 value $ 40;      drop fid j infonum;      filename mypipe pipe '  UNIX-command  ';      fid=fopen("mypipe","s");      infonum=foptnum(fid);      do j=1 to infonum;         name=foptname(fid,j);         value=finfo(fid,name);         put 'File attribute' name 'has a value of ' value;         output;      end;   run; 

The following statement should appear in the SAS log:

 File attribute Pipe Command has a value of  UNIX-command  

UNIX-command is the UNIX-command or program where you are piping your output or where you are reading your input. This command or program must be either fully qualified or defined in your PATH environment variable.

See Also

• "FINFO Function" on page 247

• "FOPTNUM Function" on page 249

• "FOPEN Function" in SAS Language Reference: Dictionary

FOPTNUM Function

Returns the number of information items that are available for an external file

Category: External Files

UNIX specifics: Information items available

See: FOPTNUM Function in SAS Language Reference: Dictionary

Syntax

FOPTNUM ( file-id )

file-id

• specifies the identifier that was assigned when the file was opened, generally by the FOPEN function.

Details

Under UNIX, five information items are available for all types of files:

• File Name

• Owner Name

• Group Name

• Access Permission

• File Size (bytes).

If you concatenate filenames, then an additional information item is available: File List.

If you are using pipe files, then the only information item available is Pipe Command.

The open-mode specified in the FOPEN function determines the value that FOPTNUM returns.

Open Mode	FOPTNUM Value	Information Items Available
Append	6 for concatenated files	All information items available.
Input	5 for single files
Update
Output	5 for concatenated files	Since the file is open for output, the File Size information type is unavailable.
	4 for single files
Sequential (using Pipe Device Type)	1	The only information item available is Pipe Command.

For an example of how to use the FOPTNUM function, see "Example: File Attributes When Using the Pipe Device Type" on page 248.

See Also

• "FINFO Function" on page 247

• "FOPTNAME Function" on page 247

• "FOPEN Function" in SAS Language Reference: Dictionary

LIBNAME Function

Assigns or deassigns a libref for a SAS data library

Category: SAS File I/O

UNIX specifics: Behavior of the ' ' libref (with a space between the quotation marks)

See: LIBNAME Function in SAS Language Reference: Dictionary

Syntax

LIBNAME (' libref '<,' SAS-data-library '<, engine <, options >>>)

libref

• specifies the libref that is assigned to a SAS data library. Under UNIX, the value of libref can be an environment variable. libref must be enclosed in single or double quotation marks.

SAS-data-library

• specifies the physical name of the SAS data library that is associated with the libref. The value of SAS-data-library must be enclosed in single or double quotation marks.

engine

• specifies the engine that is used to access SAS files opened in the data library.

options

• names one or more options honored by the specified engine, delimited with blanks.

Details

If the LIBNAME function returns a 0, then the function was successful. However, you could receive a non-zero value, even if the function was successful. A non-zero value is returned if an error, warning, or note is produced. To determine if the function was successful, look through the SAS log and use the following guidelines:

• If a warning or note was generated, then the function was successful.

• If an error was generated, then the function was not successful.

Under UNIX, if you specify a SAS-data-library of ' '(with a space between the quotation marks), SAS deassigns the libref .

MODULE Function

Calls a specific routine or module that resides in a shared executable library

Category: External Files

UNIX specifics: All

Syntax

CALL MODULE (< cntl >, module , arg-1 , arg-2 ..., arg-n );

num = MODULEN (< cntl >, module , arg-1 , arg-2 , arg-n );

char = MODULEC (< cntl >, module , arg-1 , arg-2 , arg-n );

Note  

The following functions permit vector and matrix arguments; you can use them only within the IML procedure.

CALL MODULEI (< cntl >, modulearg-1 , arg-2 ..., arg-n );

num = MODULEIN (< cntl >, module , arg-1 , arg-2 ..., arg-n )

char = MODULEIC (< cntl >, module , arg-1 , arg-2 ..., arg-n );

cntl

• is an optional control string whose first character must be an asterisk (*), followed by any combination of the following characters:

  I	prints the hexadecimal representations of all arguments to the ODULE function and to the requested shared library routine before and after the shared library routine is called. You can use this option to help diagnose problems that are caused by incorrect arguments or attribute tables. If you specify the I option, the E option is implied .
  E	prints detailed error messages. Without the E option (or the I option, which supersedes it), the only error message that the MODULE function generates is "Invalid argument to function," which is usually not enough information to determine the cause of the error.
  S x	uses x as a separator character to separate field definitions. You can then specify x in the argument list as its own character argument to serve as a delimiter for a list of arguments that you want to group together as a single structure. Use this option only if you do not supply an entry in the SASCBTBL attribute table. If you do supply an entry for this module in the SASCBTBL attribute table, you should use the FDSTART option in the ARG statement in the table to separate structures.
  H	provides brief help information about the syntax of the MODULE routines, the attribute file format, and the suggested SAS formats and informats.

  For example, the control string '*IS/' specifies that parameter lists be printed and that the string '/' is to be treated as a separator character in the argument list.

module

• is the name of the external module to use. The module can be specified as a shared library and the routine name or ordinal value, separated by a comma. You do not need to specify the shared library name if you specified the MODULE attribute for the routine in the SASCBTBL attribute table, as long as the routine name is unique (that is, no other routines have the same name in the attribute file).

  The module must reside in a shared library, and it must be externally callable. Note that while the shared library name is not case sensitive, the routine name is based on the restraints of the routine's implementation language, so the routine name is case sensitive.

  If the shared library supports ordinal-value naming, you can provide the shared library name followed by a decimal number, such as 'XYZ,30'.

  You can specify module as a SAS character expression instead of as a constant; most often, though, you will pass it as a constant.

arg-1, arg-2, ...arg-n

• are the arguments to pass to the requested routine. Use the proper attributes for the arguments (that is, numeric arguments for numeric attributes and character arguments for character attributes).

Caution  

Be sure to use the correct arguments and attributes. If you use incorrect arguments or attributes for a shared library function, you can cause SAS to crash, or you will see unexpected results.

Details

The MODULE functions execute a routine module that resides in an external (outside SAS) shared library with the specified arguments arg-1 through arg-n .

The MODULE call routine does not return a value, while the MODULEN and MODULEC functions return a number num or a character char , respectively. Which routine you use depends on the expected return value of the shared library function that you want to execute.

MODULEI, MODULEIC, and MODULEIN are special versions of the MODULE functions that permit vector and matrix arguments. Their return values are still scalar. You can invoke these functions only from PROC IML.

Other than this name difference, the syntax for all six routines is the same.

The MODULE function builds a parameter list by using the information in arg-1 to arg-n and by using a routine description and argument attribute table that you define in a separate file. Before you invoke the MODULE routine, you must define the fileref of SASCBTBL to point to this external file. You can name the file whatever you want when you create it.

This way, you can use SAS variables and formats as arguments to the MODULE function and ensure that these arguments are properly converted before being passed to the shared library routine.

Caution  

Using the MODULE function without defining an attribute table can cause SAS to crash, produce unexpected results, or result in severe errors. You need to use an attribute table for all external functions that you want to invoke.

See Also

• "The SASCBTBL Attribute Table" on page 170

• "PEEKLONG Function" on page 254

MOPEN Function

Opens a file by directory ID and by member name, and returns either the file identifier or a 0

Category: External Files

UNIX specifics: Open-modes

See: MOPEN Function in SAS Language Reference: Dictionary

Syntax

MOPEN ( directory-id , member-name <, open-mode <, record-length <, record-format >>>)

Note  

This is a simplified version of the MOPEN function syntax. For the complete syntax and its explanation, see the MOPEN function in SAS Language Reference: Dictionary .

open-mode

• specifies the type of access to the file:

  A	APPEND mode allows writing new records after the current end of the file.
  I	INPUT mode allows reading only (default).
  O	OUTPUT mode defaults to the OPEN mode specified in the host option in the FILENAME statement or function. If no host option is specified, it allows writing new records at the beginning of the file.
  S	Sequential input mode is used for pipes and other sequential devices such as hardware ports.
  U	UPDATE mode allows both reading and writing.
  W	Sequential update mode is used for pipes and other sequential devices such as ports.

Details

MOPEN returns the identifier for the file, or 0 if the file could not be opened.

PATHNAME Function

Returns the physical name of a SAS data library or of an external file, or returns a blank

Category: SAS File I/O

UNIX specifics: fileref or libref argument can also specify a UNIX environment variable

See: PATHNAME Function in SAS Language Reference: Dictionary

Syntax

PATHNAME ((" fileref "" libref ")< search-ref >)

fileref

• specifies the fileref assigned to the external file. The value of the fileref can be a UNIX environment variable.

libref

• specifies the libref assigned to a SAS library. The value of the libref can be a UNIX environment variable.

search-ref

• specifies whether to search for a fileref or a libref.

  F	specifies a search for a fileref.
  L	specifies a search for a libref.

Details

PATHNAME returns the physical name of an external file or SAS library, or a blank if filref or libref is invalid.

For more information about using an UNIX environment variable for fileref or libref , see "FILENAME Function" on page 245.

PEEKLONG Function

Stores the contents of a memory address in a numeric variable on 32-bit and 64-bit platforms

Category: Special

UNIX specifics: All

See: PEEKLONG Function in SAS Language Reference: Dictionary

Syntax

PEEKCLONG (addres s , length );

PEEKLONG ( address , l ength);

address

• specifies the character string that is the memory address.

length

• specifies the data length.

Details

Caution  

Use the PEEKLONG functions only to access information returned by one of the MODULE functions.

The PEEKLONG function returns a value of length length that contains the data that starts at memory address address .

The variations of the PEEKLONG functions are:

PEEKCLONG	accesses character strings.
PEEKLONG	accesses numeric values.

Usually, when you need to use one of the PEEKLONG functions, you will use PEEKCLONG to access a character string. The PEEKLONG function is mentioned here for completeness.

RANK Function

Returns the position of a character in the ASCII collating sequence

Category: Character

UNIX specifics: Uses ASCII collating sequence

See: RANK Function in SAS Language Reference: Dictionary

Syntax

RANK ( x )

x

• is a character expression (or character string) that contains a character in the ASCII collating sequence. If the length of x is greater than 1, you receive the rank of the first character in the string.

Details

Because UNIX uses the ASCII character set, the RANK function returns an integer that represents the position of a character in the ASCII collating sequence.

SYSGET Function

Returns the value of the specified environment variable

Category: Special

UNIX specifics: environment-variable is a UNIX environment variable

See: SYSGET Function in SAS Language Reference: Dictionary

Syntax

SYSGET (' environment-variable ')

environment-variable

• is the name of a UNIX environment variable.

Details

The SYSGET function returns the value of an environment variable as a character string. For example, this statement returns the value of the HOME environment variable:

 here=sysget('HOME'); 

TRANSLATE Function

Replaces specific characters in a character expression

Category: Character

UNIX specifics: to and from arguments are required

See: TRANSLATE Function in SAS Language Reference: Dictionary

Syntax

TRANSLATE ( source , to-1 , from-1 <, to-n , from-n >)

Note  

This is a simplified version of the TRANSLATE function syntax. For the complete syntax and its explanation, see the TRANSLATE function in SAS Language Reference: Dictionary .

source

• specifies the SAS expression that contains the original character value.

to

• specifies the characters that you want TRANSLATE to use as substitutes.

from

• specifies the characters that you want TRANSLATE to replace.

Details

Under UNIX, you must specify pairs of to and from arguments, and you can use a comma as a place holder.