Chapter 18: Functions and CALL Routines under Windows

SAS Functions and Call Routines under Windows

A SAS function returns a value from a computation or system operation. SAS CALL routines are used to alter variable values or perform other system functions. Most SAS functions and CALL routines are completely described in the SAS functions and CALL routines portion of SAS Language Reference: Dictionary . The functions and CALL routines that are described here have syntax or behavior specific to the Windows operating environment.

BYTE Function

Returns one character in the ASCII collating sequence

Category: Character

Windows specifics: Uses the ASCII code sequence

See: BYTE Function in SAS Language Reference: Dictionary

Syntax

BYTE ( 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.

Because Windows is an ASCII system, the BYTE function returns the n th character in the ASCII collating sequence. The value of n can range from 0 to 255.

Any programs using the BYTE function with characters above ASCII 127 (the hexadecimal notation is ' 7F'x ) may return a different value when used on a PC from another country as characters above ASCII 127 are national characters and they vary from country to country.

CALL SOUND Routine

Generates a sound with a specific frequency and duration

Category: Special

Windows specifics: all

Syntax

CALL SOUND ( frequency , duration );

frequency

specifies the sound frequency in terms of cycles per second. The frequency must be at least 20 and no greater than 20,000.

duration

specifies the sound duration in milliseconds . The default is -1.

Example

Example 1: Producing a Tone

The following statement produces a tone of frequency 523 cycles per second (middle C) lasting 2 seconds:

 data _null_;     call sound(523,2000);  run;

CALL SYSTEM Routine

Submits an operating system command or a Windows application for execution

Category: Special

Windows specifics: command must be a valid Windows command

See: CALL SYSTEM Routine in SAS Language Reference: Dictionary

Syntax

CALL SYSTEM ( command );

command

can be any of the following:
- an operating system command enclosed in quotes or the name of a Windows application that is enclosed in quotes.
- an expression whose value is an operating system command or the name of a Windows application.
- the name of a character variable whose value is an operating system command or the name of a Windows application.

Details

If you are running SAS interactively, the command executes in a command prompt window. By default, you must type exit to return to your SAS session.

Comparison

The CALL SYSTEM routine is similar to the X command. However, the CALL SYSTEM routine is callable and can therefore be executed conditionally.

The values of the XSYNC and XWAIT system options affect how the CALL SYSTEM routine works.

Examples

Example 1: Executing Operating System Commands Conditionally

If you want to execute operating system commands conditionally, use the CALL SYSTEM routine:

 options noxwait;  data _null_;     input flag $ name .;     if upcase(flag)='Y' then        do;           command='md c:\'name;           call system(command);        end;     cards;  Y mydir  Y junk2  N mydir2  Y xyz  ;

This example uses the value of the variable FLAG to conditionally create directories. After the DATA step executes, three directories have been created: C:\MYDIR, C:\JUNK2, and C:\XYZ. The directory C:\MYDIR2 is not created because the value of FLAG for that observation is not Y .

The X command is a global SAS statement. Therefore, it is important to realize that you cannot conditionally execute the X command. For example, if you submit the following code, the X statement is executed:

 data _null_;     answer='n';     if upcase(answer)='y' then        do;           x 'md c:\extra';        end;  run;

In this case, the directory C:\EXTRA is created regardless of whether the value of ANSWER is equal to ' n' or ' y' .

Example 2: Obtaining a Directory Listing

You can use the CALL SYSTEM routine to obtain a directory listing:

 data _null_;     call system('dir /w');  run;

In this example, the /W option for the DIR command instructs Windows to print the directory in the wide format instead of a vertical list format.

COLLATE Function

Returns an ASCII collating sequence character string

Category: Character

Windows specifics: Uses the ASCII code 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 returned collating sequence.

Details

The COLLATE function returns a string of ASCII characters that range in value from 0 to 255. The string that is returned by the COLLATE function begins with the ASCII character that is specified by the start-position argument. If the end-position argument is specified, the string returned by the COLLATE function contains all the ASCII characters between the start-position and end-position arguments. If the length argument is specified instead of the end-position argument, then the COLLATE function returns a string that contains a value for length . The returned string ends, or truncates, with the character having the value 255 if you request a string length that contains characters exceeding this value.

The default length of the return string value is 200 characters. To return a length of 201 to 256 ASCII characters, use a format such as $256 for the return string variable or explicitly define the variable s length, such as length y $260 .

Any programs using the COLLATE function with characters above ASCII 127 (the hexadecimal notation is ' 7F'x ) may return a different value when used on a PC from another country. Characters above ASCII 127 are national characters and they vary from country to country.

Examples

Example 1: Returning an ASCII String Using the Return Variable Default String Length

In this example, the return code variable y uses the default return string length of 200. Therefore, the COLLATE function returns 200 characters of the collating sequence.

 data _null_;     y = collate(1,256);     put y;  run;

Example 2: Returning an ASCII String Larger Than the Default Return Variable String Length

By formatting the return code variable to a length greater than 256, the COLLATE function returns 256 characters of the collating sequence.

 data _null_;     format y 0.;     y = collate(1,256);     put y;  run;

Example 3: Returning an ASCII String of a Specific Length

In this example, the return code variable y uses a return string length of 56, and the COLLATE function returns the first 56 characters of the collating sequence.

 data _null_;     y = collate(,,56);     put y;  run;

DINFO Function

Returns information about a directory

Category: External Files

Windows 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 directory information items. Use DOPTNUM to determine the number of directory information items available.

Under Windows, the only info-item that is 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.

Example of Obtaining Directory Information

 data a;    rc=filename("tmpdir", "c:");    put "rc = 0 if the directory exists: " rc=;    did=dopen("tmpdir'');    put did=;    numopts=doptnum(did);    put numopts=;    do i=1tonumopts;      optname = doptname(did,i);      put i= optname=;      optval=dinfo(did,optname);      put optval=;    end;  run;

Output 18.1: The SAS Log Displays the Directory Information

 NOTE: PROCEDURE PRINTTO used (Total process time):        real time           0.03 seconds        cpu time            0.00 seconds  446  data a;  447    rc=filename("tmpdir", "c:");  448    put "rc = 0 if the directory exists: " rc=;  449    did=dopen("tmpdir");  450    put did=;  451    numopts=doptnum(did);  452    put numopts=;  453    do i = 1 to numopts;  454      optname = doptname(did,i);  455      put i= optname=;  456      optval=dinfo(did,optname);  457      put optval=;  458    end;  459  run;  rc = 0 if the directory exists: rc=0  did=1  numopts=1  i=1 optname=Directory  optval=C:\TEMP\elimal  NOTE: The data set WORK.A has 1 observations and 6 variables.  NOTE: DATA statement used (Total process time):        real time           0.08 seconds        cpu time            0.04 seconds  460  proc printto; run;

DOPEN Function

Opens a directory and returns a directory identifier value

Category: External Files

Windows specifics: fileref can be assigned by using an environment variable

See: DOPEN Function in SAS Language Reference: Dictionary

Syntax

DOPEN ( fileref )

fileref

specifies the fileref that is 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

Windows 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 option.

Details

Under Windows, the only directory information item that is available is Directory, which is the pathname of 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.

Example

For an example of using DOPTNAME, see Example of Obtaining Directory Information on page 390.

DOPTNUM Function

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

Category: External Files

Windows 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 Windows, 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 .

Example

For an example of the DOPTNUM function, see Example of Obtaining Directory Information on page 390.

FDELETE Function

Deletes an external file or an empty directory

Category: External Files

Windows specifics: fileref can be assigned by using 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. Under Windows, fileref can be an environment variable. The fileref or the environment variable that you specify must be enclosed in quotation marks.

Details

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

FEXIST Function

Verifies the existence of an external file by its fileref

Category: External Files

Windows specifics: fileref can be assigned with an environment variable

See: FEXIST Function in SAS Language Reference: Dictionary

Syntax

FEXIST ( fileref )

fileref

specifies the fileref that is assigned to an external file. Under Windows, fileref can also be an environment variable. The fileref or the environment variable that you specify must be enclosed in quotation marks.

Details

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

Example

For an example of using the FINFO function, see Example of Obtaining File Information on page 397.

FILEEXIST Function

Verifies the existence of an external file by its physical name

Category: External Files

Windows 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 Windows, filename can also be an environment variable. The filename or environment variable that you specify must be enclosed in 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

Windows specifics: device types 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 the 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. (See SAS Language Reference: Dictionary for details.)

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

filename

specifies the external file. Specifying a blank filename clears the fileref that was previously assigned.
Under Windows, the filename differs according to the device type. Table 5.2 on page 155 shows the information that is appropriate to each device. The filename that you specify must be enclosed in quotation marks.

device-type

specifies 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 that are listed in FILENAME statement device-type argument on page 446. DISK is the default device type.

host-options

are options that are specific to Windows. You can use any of the options that are available in the FILENAME statement. See the FILENAME statement host-option-list on page 447.

dir-ref

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

Details

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

Example

For an example of using the FILENAME function, see Example of Obtaining File Information on page 397.

FILEREF Function

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

Category: External Files

Windows specifics: the fileref argument can specify a Windows environment variable

See: FILEREF Function in SAS Language Reference: Dictionary

Syntax

FILEREF ( fileref )

fileref

specifies the fileref to be validated . Under Windows, fileref can also be a Windows environment variable. The fileref or the environment variable that you specify must be enclosed in 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.

Example

For an example of using the FILEREF function, see Example of Obtaining File Information on page 397.

FINFO Function

Returns the value of an information item for an external file

Category: External Files

Windows specifics: available info-items

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 that contains a file information name or the file information name that has been enclosed in quotation marks.

info-item for disk files can be one of these file information items:
- File Name
- RECFM
- LRECL
info-item for pipe files can be one of these file information items:
- Unnamed pipe access device
- PROCESS
- RECFM
- LRECL

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.

Example of Obtaining File Information

 data a;  /* Does fileref "curdirfl" exist?  No = 0 */  rc=fexist ("curdirfl");  put;  put "Fileref curdirfl exist? rc should be 0 (no); " rc=;  /* assign fileref */  rc=filename("curdirfl", "c:\tmp333");  /* RC=0 indicates success in assigning fileref */  put "Fileref assigned - rc should be 0; " rc=;  rc=fexist ("curdirfl");  /* Does file which "curdirfl" points to exist?  No = 0 */  /* Assigning a fileref doesn't create the file. */  put "File still doesn't exist - rc should be 0; " rc=;  rc=fileref ("curdirfl");  /* Does fileref "curdirfl" exist?  */  /* Negative means fileref exists, but file does not */  /* Positive means fileref does not exist            */  /* Zero means both fileref and file exist           */  put "Fileref now exists - rc should be negative; " rc=;  put;  /* Does the file that the fileref points to exist?  Should be no. */  if ( fileexist ("./tmp333") ) then      /* if it does, open it for input */        do;          put "Open file for input";          fid=fopen ("curdirfl", "i") ;        end;     else       /* most likely scenario */        do;          put "Open file for output";          fid=fopen ("curdirfl", "o");        end;  /* fid should be non-zero.  0 indicates failure. */  put "File id is: " fid=;  numopts = foptnum(fid);  put "Number of information items should be 3; " numopts=;  do i = 1 to  numopts;  optname = foptname (fid,i);  put i= optname=;  optval  = finfo (fid, optname);  put optval= ;  end;  rc=fclose (fid);  rc=fdelete ("curdirfl");  put "Closing the file, rc should be 0; "  rc=; run;

Output 18.2: The Resulting SAS Log

 NOTE: PROCEDURE PRINTTO used (Total process time):       real time           0.36 seconds       cpu time            0.00 seconds 291  data a; 292 293  /* Does fileref "curdirfl" exist?  No = 0 */ 294 295  rc=fexist ("curdirfl"); 296  put; t297  put "Fileref curdirfl exist? rc should be 0 (no); " rc=; 298 299  /* assign fileref */ 300 301  rc=filename("curdirfl", "c:\tmp333"); 302 303  /* RC=0 indicates success in assigning fileref */ 304 305  put "Fileref assigned - rc should be 0; " rc=; 306  rc=fexist ("curdirfl"); 307 308  /* Does file which "curdirfl" points to exist?  No = 0 */ 309  /* Assigning a fileref doesn't create the file. */ 310 311  put "File still doesn't exist - rc should be 0; " rc=; 312  rc=fileref ("curdirfl"); 313 314  /* Does fileref "curdirfl" exist?  */ 315  /* Negative means fileref exists, but file does not */ 316  /* Positive means fileref does not exist            */ 317  /* Zero means both fileref and file exist           */ 318 319  put "Fileref now exists - rc should be negative; " rc=; 320  put; 321 322  /* Does the file that the fileref points to exist?  Should be no. */ 323 324  if ( fileexist ("./tmp333") ) then 325      /* if it does, open it for input */ 326        do; 327          put "Open file for input"; 328          fid=fopen ("curdirfl", "i") ; 329        end; 330     else       /* most likely scenario */ 331        do; 332          put "Open file for output"; 333          fid=fopen ("curdirfl", "o"); 334        end; 335 336  /* fid should be non-zero.  0 indicates failure. */ 337  put "File id is: " fid=; 338  numopts = foptnum(fid); 339  put "Number of information items should be 3; " numopts=; 340  do i = 1 to  numopts; 341  optname = foptname (fid,i); 342  put i= optname=; 343  optval  = finfo (fid, optname); 344  put optval= ; 345  end; 346  rc=fclose (fid); 347  rc=fdelete ("curdirfl"); 348  put "Closing the file, rc should be 0; " 349  rc=; run; Fileref curdirfl exist? rc should be 0 (no); rc=0 Fileref assigned - rc should be 0; rc=0 File still doesn't exist - rc should be 0; rc=0 Fileref now exists - rc should be negative; rc=-20006 Open file for output File id is: fid=1 Number of information items should be 3; numopts=3 i=1 optname=File Name optval=c:\tmp333 i=2 optname=RECFM optval=V i=3 optname=LRECL optval=256 Closing the file, rc should be 0; rc=0 NOTE: The data set WORK.A has 1 observations and 6 variables. NOTE: DATA statement used (Total process time):       real time           0.12 seconds       cpu time            0.09 seconds 350  proc printto; run;

FOPTNAME Function

Returns the name of an information item for an external file

Category: External Files

Windows specifics: available information items

See: FOPTNAME Function in 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 for single and concatenated files under Windows operating environments.

nval	Single File	Pipe Files	Concatenated Files
1	File Name	Unnamed pipe access device	File Name
2	RECFM	PROCESS	RECFM
3	LRECL	RECFM	LRECL
4		LRECL

Details

FOPTNAME returns a blank if an error occurred.

Example: File Attributes When Using the Pipe Device Type

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

 data fileatt;     filename mypipe pipe 'dir';     fid=fopen("mypipe","s");     /* fid should be non---zero. 0 indicates failure */     put "File id is: " fid=;     numopts=foptnum(fid);     put "Number of information items should be 4; " numopts=;     do i=1 to numopts;        optname=foptname(fid,i);        put i= optname=;        optval=finfo(fid,optname);        put optval=;     end;  rc=fclose(fid);  run;

Output 18.3: The SAS LOG Displays Pipe File Information

 NOTE: PROCEDURE PRINTTO used (Total process time):        real time           0.03 seconds        cpu time            0.01 seconds  6    data fileatt;  7       filename mypipe pipe 'dir';  8       fid=fopen("mypipe","s");  9       /* fid should be non-zero. 0 indicates failure */  10      put "File id is: " fid=;  11      numopts=foptnum(fid);  12      put "Number of information items should be 4; " numopts=;  13      do i=1 to numopts;  14         optname=foptname(fid,i);  15         put i= optname=;  16         optval=finfo(fid,optname);  17         put optval=;  18      end;  19  20   rc=fclose(fid);  21   run;  File id is: fid=1  Number of information items should be 4; numopts=4  i=1 optname=Unnamed Pipe Access Device  optval=  i=2 optname=PROCESS  optval=dir  i=3 optname=RECFM  optval=V  i=4 optname=LRECL  optval=256  NOTE: The data set WORK.FILEATT has 1 observations and 6 variables.  NOTE: DATA statement used (Total process time):        real time           9.64 seconds        cpu time            1.16 seconds  22   proc printto; run;

FOPTNUM Function

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

Category: External Files

Windows 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

Three information items are available for files:

File Name
RECFM
LRECL

These information items are available for pipes:

Unnamed pipe access device
PROCESS
RECFM
LRECL

FOPTNUM returns the following values:

For files:	3
For pipes:	4

Example

For an example of the FOPTNUM functions, see Example of Obtaining File Information on page 397.

LIBNAME Function

Assigns or clears a libref for a SAS data library

Category: SAS File I/O

Windows specifics: behavior of the libref (a space between single 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 Windows, the value of libref can be an environment variable.

SAS-data-library

specifies the physical name of the SAS data library that is associated with the libref.

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 Windows, if you do not specify a SAS-data-library or if you specify a SAS-data-library as (a space between single quotation marks) or (no space between single quotation marks), SAS deassigns the libref.

MCIPISLP Function

Causes SAS to wait for a piece of multimedia equipment to become active

Category: Special

Windows specifics: all

Syntax

MCIPISLP ( number-of-seconds )

number-of-seconds

specifies the number of seconds you want SAS to wait. This number must be an integer.

Details

The MCIPISLP function is especially useful when you have used the MCIPISTR function to open a piece of equipment, but you know it is going to take a few seconds for the equipment to be ready.

The number-of-seconds argument must be an integer and represents how many seconds you want to wait. The return value is the number of seconds slept.

The MCIPISLP function can be used in the DATA step and in SCL code.

Example

This example uses both the MCIPISTR and MCIPISLP functions to play a CD and a video. The PUT statements display the return values of these functions. This allows you to see in the SAS log whether there was a problem with any of your equipment.

 data _null_;    /* Open a CD player. */    msg=mcipistr("open cdaudio alias mytunes");    put msg=;    /* Wait one second for the CD player     */    /* to become active.                     */    slept=mcipislp(1);    /* Begin playing your favorite tunes     */    /* from the beginning of the CD.         */    msg=mcipistr("play mytunes");    put msg=;    /* Now open a video file. */    msg=mcipistr("open c:\movies\amovie.avs                  alias myshow");    put msg=;    /* Begin the show and wait for it to     */    /* complete.                             */    msg=mcipistr("play myshow wait");    put msg=;    /* When the show is complete,            */    /* close the instance.                   */    msg=mcipistr("close myshow");    put msg=;    /* Stop and close the instance of the CD */    /* player.                               */    msg=mcipistr("stop mytunes");    put msg=;    msg=mcipistr("close mytunes");    put msg=;  run;

MCIPISTR Function

Submits an MCI string command to a piece of multimedia equipment

Category: Special

Windows specifics: all

Syntax

MCIPISTR ( MCI-string-command )

MCI-string-command

is any valid SAS string; that is, a character variable, a character literal enclosed in quotes, or other character expression.

Details

The MCIPISTR function submits an MCI (Media Control Interface) string command.

You can use MCI to control many types of multimedia equipment, such as CD players, mixers, videodisc players, and so on. Windows provides MCI support. For more information about valid MCI string commands, refer to the Windows multimedia SDK documentation in the MSDN Library and your MCI-compliant device documentation.

The return value is a string that contains return information from the MCI string command. Examples of return information include "invalid instance" and "1".

Note: Not all MCI commands supply return codes that are usable from SAS.

The MCIPISTR function can be used in the DATA step and in SCL code.

Example

To use a CD player, you could submit the following statements in your DATA step:

 msg=mcipistr("open cdaudio alias cd");  msg=mcipistr("play cd");  msg=mcipistr("stop cd");  msg=mcipistr("close cd");

MODULE Function

Calls a specific routine or module that resides in an external dynamic link library ( DLL )

Category: External Routines

Windows 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 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 MODULE function and to the requested DLL routine before and after the DLL 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 mesages. 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, specified as a DLL name and the routine name or ordinal value, separated by a comma. The module must reside in a dynamic link library (DLL) and it must be externally callable. For example, the value 'KERNEL32,GetProfileString' specifies to load KERNEL32.DLL and to invoke the GetProfileString routine. Note that while the DLL 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 DLL supports ordinal-value naming, you can provide the DLL name followed by a decimal number, such as ' XYZ,30' .

You do not need to specify the DLL 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).

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. Using incorrect arguments or attributes for a DLL function can cause SAS, and possibly your operating system, to fail.

Details

The MODULE functions execute a routine module that resides in an external (outside SAS) dynamic link 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 DLL 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 DLL routine.

PEEKLONG Function

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

Category Special

Windows specifics: all

See: PEEKLONG Function and PEEKCLONG Function in SAS Language Reference: Dictionary

Syntax

PEEKLONG( address <, length )>

address
- specifies a character string that is the memory address.

length
- specifies the length of the character data.

Details

CAUTION:

The PEEKLONG functions can directly access memory addresses. Improper use of the PEEKLONG functions can cause SAS, and your operating system, to fail. Use the PEEKLONG functions only to access information that is returned by one of the MODULE functions.

The PEEKLONG function returns a value of length length that contains the data that start 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.

RANK Function

Returns the position of a character in the ASCII collating sequence

Category: Character

Windows specifics: Uses the ASCII sequence

See: RANK Function in SAS Language Reference: Dictionary

Syntax

RANK ( 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 Windows uses the ASCII character set, the RANK function returns an integer that represents the position of a character in the ASCII collating sequence.

Note: Any program that uses the RANK function with characters above ASCII 127 (the hexadecimal notation is ' 7F'x ) is not portable because these are national characters and they vary from country to country.

SLEEP Function

Suspends execution of a SAS DATA step for a specified period of time

Category: Special

Windows specifics: all

See: SLEEP Function in SAS Language Reference: Dictionary

Syntax

SLEEP ( n <, unit >)

specifies the number of seconds that you want to suspend execution of a DATA step. The n argument is a numeric constant that must be greater than or equal to 0. Negative or missing values for n are invalid.

unit

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

Details

The SLEEP function suspends execution of a DATA step for a specified number of seconds. When the SLEEP function uses the default unit value, a pop-up window appears that indicates how long SAS is going to sleep.

The return value of the n argument is the number of seconds slept. The maximum sleep period for the SLEEP function is 46 days.

When you submit a program that calls the SLEEP function, the SLEEP window appears telling you when SAS is going to wake up. You can inhibit the SLEEP window by starting SAS with the NOSLEEPWINDOW system option. Your SAS session remains inactive until the sleep period is over. To cancel the call to the SLEEP function, use the CTRL+BREAK attention sequence.

You should use a null DATA step to call the SLEEP function; follow this DATA step with the rest of the SAS program. Using the SLEEP function in this manner enables you to use the CTRL+BREAK attention sequence to interrupt the SLEEP function and to continue with the execution of the rest of your SAS program.

Example

The following example tells SAS to delay the execution of the program for 12 hours and 15 minutes:

 data _null_;     /* argument to sleep must be expressed in seconds */     slept= sleep((60*60*12)+(60*15));  run;  data monthly;     /*... more data lines */  run;

TRANSLATE Function

Replaces specific characters in a character expression

Category: Character

Windows specifics: Required syntax; pairs of to and from arguments are optional

See: TRANSLATE Function in SAS Language Reference: Dictionary

Syntax

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

source

specifies the SAS expression that contains the original character value.

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

from

specifies the characters that you want TRANSLATE to replace.

Details

Under Windows, you do not have to provide pairs of to and from arguments. However, if you do not use pairs, you must supply a comma as a place holder.

WAKEUP Function

Specifies the time a SAS DATA step begins execution

Category: Special

Windows specifics: all

Syntax

WAKEUP ( until-when )

until-when

specifies the time when the WAKEUP function will be executed.

Details

Use the WAKEUP function to specify the time a DATA step begins to execute. The return value is the number of seconds slept.

The until-when argument can be a SAS datetime value, a SAS time value, or a numeric constant, as explained in the following list:

If until-when is a datetime value, the WAKEUP function sleeps until the specified date and time. If the specified date and time have already passed, the WAKEUP function does not sleep, and the return value is 0.
If until-when is a time value, the WAKEUP function sleeps until the specified time. If the specified time has already passed in that 24- hour period, the WAKEUP function sleeps until the specified time occurs again.
If the value of until-when is a numeric constant, the WAKEUP function sleeps for that many seconds before or after the next occurring midnight. If the value of until-when is a positive numeric constant, the WAKEUP function sleeps for until-when seconds past midnight. If the value of until-when is a negative numeric constant, the WAKEUP function sleeps until until-when seconds before midnight.

Negative values for the until-when argument are allowed, but missing values are not. The maximum sleep period for the WAKEUP function is approximately 46 days.

When you submit a program that calls the WAKEUP function, a the SLEEP window appears telling you when SAS is going to wake up. You can inhibit the SLEEP window by starting SAS with the NOSLEEPWINDOW system option. Your SAS session remains inactive until the waiting period is over. If you want to cancel the call to the WAKEUP function, use the CTRL + BREAK attention sequence.

You should use a null DATA step to call the WAKEUP function; follow this DATA step with the rest of the SAS program. Using the WAKEUP function in this manner enables you to use the CTRL+BREAK attention sequence to interrupt the waiting period and continue with the execution of the rest of your SAS program.

Examples

Example 1: Delaying Program Execution until a Specified Date or Time

The code in this example tells SAS to delay execution of the program until 1:00 p.m. on January 1, 2004:

 data _null_;     slept=wakeup('01JAN2004:13:00:00'dt);  run;  data compare;     /* ...more data lines */  run;

The following example tells SAS to delay execution of the program until 10:00 p.m.:

 data _null_;     slept=wakeup("22:00:00"t);  run;  data compare;     /* ...more data lines */  run;

Example 2: Delaying Program Execution until a Specified Time Period after Midnight

The following example tells SAS to delay execution of the program until 35 seconds after the next occurring midnight:

 data _null_;     slept=wakeup(35);  run;  data compare;     /* ...more data lines */  run;

Example 3: Using a Variable as an Argument to the WAKEUP Function

This example illustrates using a variable as the argument of the WAKEUP function:

 data _null_;     input x;     slept=wakeup(x);     datalines;  1000  ;  data compare;     input article1 $ article2 $ rating;     /* ...more data lines */  run;

Because the instream data indicate that the value of X is 1000, the WAKEUP function sleeps for 1,000 seconds past midnight.

SAS Functions and Call Routines under Windows

BYTE Function

Syntax

Details

CALL SOUND Routine

Syntax

Example

Example 1: Producing a Tone

CALL SYSTEM Routine

Syntax

Details

Comparison

Examples

Example 1: Executing Operating System Commands Conditionally

Example 2: Obtaining a Directory Listing

See Also

COLLATE Function

Syntax

Details

Examples

Example 1: Returning an ASCII String Using the Return Variable Default String Length

Example 2: Returning an ASCII String Larger Than the Default Return Variable String Length

Example 3: Returning an ASCII String of a Specific Length

DINFO Function

Syntax

Details

Example of Obtaining Directory Information

See Also

DOPEN Function

Syntax

Details

DOPTNAME Function

Syntax

Details

Example

DOPTNUM Function

Syntax

Details

Example

FDELETE Function

Syntax

Details

FEXIST Function

Syntax

Details

Example

FILEEXIST Function

Syntax

Details

FILENAME Function

Syntax

Details

Example

FILEREF Function

Syntax

Details

Example

FINFO Function

Syntax

Details

Example of Obtaining File Information

See Also

FOPTNAME Function

Syntax

Details

Example: File Attributes When Using the Pipe Device Type

FOPTNUM Function

Syntax

Details

Example

LIBNAME Function

Syntax

Details

MCIPISLP Function

Syntax

Details

Example

See Also

MCIPISTR Function