Chapter 13

AutoCall Macros

AutoCall Macros

SAS supplies libraries of autocall macros to each SAS site. The libraries that you receive depend on the SAS products licensed at your site. You can use autocall macros without having to define or include them in your programs.

Dictionary

%CMPRES and %QCMPRES Autocall Macros

Compress multiple blanks and remove leading and trailing blanks.

Type:	Autocall macros
Requirement:	MAUTOSOURCE system option

Syntax

%CMPRES (text | text-expression)

%QCMPRES (text | text-expression)

Details

Note: Autocall macros are included in a library supplied by SAS Institute. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

The CMPRES and QCMPRES macros compress multiple blanks and remove leading and trailing blanks. If the argument might contain a special character or mnemonic operator, listed below, use %QCMPRES.

CMPRES returns an unquoted result, even if the argument is quoted. QCMPRES produces a result with the following special characters and mnemonic operators masked, so the macro processor interprets them as text instead of as elements of the macro language:

& % ' " ( ) + − * / < > = ¬ ^ ~ ; , # blank
AND OR NOT EQ NE LE LT GE GT IN

Examples

Example 1: Removing Unnecessary Blanks with %CMPRES

%macro createft;
   %let footnote="The result of &x &op &y is %eval(&x &op &y).";
   footnote1 &footnote;
   footnote2 %cmpres(&footnote);
%mend createft;
data _null_;
   x=5;
   y=10;
   call symput('x',x);    /* Uses BEST12. format */
   call symput('y',y);    /* Uses BEST12. format */
   call symput('op','+'), /* Uses $1. format     */
run;
%createft

The CREATEFT macro generates two footnote statements.

FOOTNOTE1 "The result of 5 + _________10 is _________15.";
FOOTNOTE2 "The result of 5 + 10 is 15.";

Example 2: Contrasting %QCMPRES and %CMPRES

%let x=5;
%let y=10;
%let a=%nrstr(%eval(&x  +  &y));
%put QCMPRES: %qcmpres(&a);
%put CMPRES: %cmpres(&a);

The %PUT statements write the following lines to the log:

QCMPRES: %eval(&x + &y)
CMPRES: 15

%COMPSTOR Autocall Macro

Compiles macros and stores them in a catalog in a permanent SAS library.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%COMPSTOR(PATHNAME=SAS-data-library)

Required Argument

SAS-data-library

is the physical name of a SASdata library on your host system. The COMPSTOR macro uses this value to automatically assign a libref. Do not enclose SAS-data-library in quotation marks.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

The COMPSTOR macro compiles the following autocall macros in a SAS catalog named SASMacr in a permanent SAS library. The overhead of compiling is saved when these macros are called for the first time in a SAS session. You can use the COMPSTOR macro as an example of how to create compiled stored macros. For more information about the autocall macros that are supplied by SAS or about using stored compiled macros, see “Storing and Reusing Macros” on page 117.

%CMPRES	%QLEFT
%DATATYP	%QTRIM
%LEFT	%TRIM
%QCMPRES	%VERIFY

%DATATYP Autocall Macro

Returns the data type of a value.

Type:	Autocall macro
Restriction:	Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel.
Requirement:	MAUTOSOURCE system option

Syntax

%DATATYP (text | text-expression)

Details

The DATATYP macro returns a value of NUMERIC when an argument consists of digits and a leading plus or minus sign, a decimal, or a scientific or floating-point exponent (E or D in uppercase or lowercase letters). Otherwise, it returns the value CHAR.

Note: %DATATYP does not identify hexadecimal numbers.

Example: Determining the Data Type of a Value

%macro add(a,b);
%if (%datatyp(&a)=NUMERIC and %datatyp(&b)=NUMERIC) %then %do;
    %put The result is %sysevalf(&a+&b).;
%end;
%else %do;
   %put Error:  Addition requires numbers.;
%end;
%mend add;

You can invoke the ADD macro as:

%add(5.1E2,225)

The macro then writes this message to the SAS log:

The result is 735.

Similarly, you can invoke the ADD macro as:

%add(0c1x, 12)

The macro then writes this message to the SAS log:

Error:  Addition requires numbers.

%KVERIFY Autocall Macro

Returns the position of the first character unique to an expression.

Category:	DBCS
Type:	Autocall macro for NLS
Requirement:	MAUTOSOURCE system option

Syntax

%KVERIFY(source, excerpt)

Required Arguments

source

text or a text expression. This is the text that you want to examine for characters that do not exist in the excerpt.

excerpt

text or a text expression. This is the text that defines the set of characters that %KVERIFY uses to examine the source.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel.

%KVERIFY returns the position of the first character in the source that is not also present in excerpt. If all the characters in source are present in the excerpt, %KVERIFY returns a value of 0.

%LEFT Autocall Macro

Left-align an argument by removing leading blanks.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%LEFT(text | text-expression)

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

The LEFT macro and the QLEFT macro both left-align arguments by removing leading blanks. If the argument might contain a special character or mnemonic operator, listed below, use %QLEFT.

%LEFT returns an unquoted result, even if the argument is quoted. %QLEFT produces a result with the following special characters and mnemonic operators masked so that the macro processor interprets them as text instead of as elements of the macro language:

& % ' " ( ) + − * / < > = ¬ ^ ~ ; , # blank
AND OR NOT EQ NE LE LT GE GT IN

Example: Contrasting %LEFT and %QLEFT

In this example, both the LEFT and QLEFT macros remove leading blanks. However, the QLEFT macro protects the leading & in the macro variable SYSDAY so that it does not resolve.

%let d=%nrstr(  &sysday  );
%put *&d* *%qleft(&d)* *%left(&d)*;

The %PUT statement writes the following line to the SAS log:

*  &sysday  * *&sysday  * *Tuesday  *

%LOWCASE and %QLOWCASE Autocall Macros

Change uppercase characters to lowercase.

Type:	Autocall macros
Requirement:	MAUTOSOURCE system option

Syntax

%LOWCASE text | text-expression()

%QLOWCASE (text | text-expression)

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

The %LOWCASE and %QLOWCASE macros change uppercase alphabetic characters to their lowercase equivalents. If the argument might contain a special character or mnemonic operator, listed below, use %QLOWCASE.

%LOWCASE returns a result without quotation marks, even if the argument has quotation marks. %QLOWCASE produces a result with the following special characters and mnemonic operators masked so that the macro processor interprets them as text instead of as elements of the macro language:

& % ' " ( ) + − * / < > = ¬ ^ ~ ; , # blank
AND OR NOT EQ NE LE LT GE GT IN

Example: Creating a Title with Initial Letters Capitalized

%macro initcaps(title);
   %global newtitle;
   %let newtitle=;
   %let lastchar=;
   %do i=1 %to %length(&title);
      %let char=%qsubstr(&title,&i,1);
      %if (&lastchar=%str( ) or &i=1) %then %let char=%qupcase(&char);
      %else %let char=%qlowcase(&char);
      %let newtitle=&newtitle&char;
      %let lastchar=&char;
   %end;
   TITLE "&newtitle";
%mend;
%initcaps(%str(sales: COMMAND REFERENCE, VERSION 2, SECOND EDITION))

Submitting this example generates the following statement:

TITLE "Sales: Command Reference, Version 2, Second Edition";

%QCMPRES Autocall Macro

Compresses multiple blanks, removes leading and trailing blanks, and returns a result that masks special characters and mnemonic operators.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%QCMPRES (text | text-expression)

Without Arguments

See “%CMPRES and %QCMPRES Autocall Macros” on page 179.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

%QLEFT Autocall Macro

Left-aligns an argument by removing leading blanks and returns a result that masks special characters and mnemonic operators.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%QLEFT text | text-expression()

Without Arguments

See “%LEFT Autocall Macro” on page 183.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

The LEFT macro and the QLEFT macro both left-align arguments by removing leading blanks. If the argument might contain a special character or mnemonic operator, listed below, use %QLEFT.

%LEFT returns an unquoted result, even if the argument is quoted. %QLEFT produces a result with the following special characters and mnemonic operators masked so that the macro processor interprets them as text instead of as elements of the macro language:

& % ' " ( ) + − * / < > = ¬ ^ ~ ; , # blank
AND OR NOT EQ NE LE LT GE GT IN

Example: Contrasting %LEFT and %QLEFT

In this example, both the LEFT and QLEFT macros remove leading blanks. However, the QLEFT macro protects the leading & in the macro variable SYSDAY so that it does not resolve.

%let d=%nrstr(  &sysday  );
%put *&d* *%qleft(&d)* *%left(&d)*;

The %PUT statement writes the following line to the SAS log:

*  &sysday  * *&sysday  * *Tuesday  *

%QLOWCASE Autocall Macro

Changes uppercase characters to lowercase and returns a result that masks special characters and mnemonic operators.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%QLOWCASE(text | text-expression)

Without Arguments

See “%LOWCASE and %QLOWCASE Autocall Macros” on page 184.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

%QTRIM Autocall Macro

Trims trailing blanks and returns a result that masks special characters and mnemonic operators.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%QTRIM (text | text-expression)

Without Arguments

See “%TRIM and %QTRIM Autocall Macro” on page 192.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

%SYSRC Autocall Macro

Returns a value corresponding to an error condition.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%SYSRC(character-string)

Required Argument

character-string

is one of the mnemonic values listed in Table 13.1 on page 188 or a text expression that produces the mnemonic value.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

The SYSRC macro enables you to test for return codes produced by SCL functions, the MODIFY statement, and the SET statement with the KEY= option. The SYSRC autocall macro tests for the error conditions by using mnemonic strings rather than the numeric values associated with the error conditions.

When you invoke the SYSRC macro with a mnemonic string, the macro generates a SAS return code. The mnemonics are easier to read than the numeric values, which are not intuitive and subject to change.

You can test for specific errors in SCL functions by comparing the value returned by the function with the value returned by the SYSRC macro with the corresponding mnemonic. To test for errors in the most recent MODIFY or SET statement with the KEY= option, compare the value of the _IORC_ automatic variable with the value returned by the SYSRC macro when you invoke it with the value of the appropriate mnemonic.

The following table lists the mnemonic values to specify with the SYSRC function and a description of the corresponding error.

Table 13.1 Mnemonics for Warning and Error Conditions

Mnemonic	Description
Library Assign or Deassign Messages
_SEDUPLB	The libref refers to the same physical library as another libref.
_SEIBASN	The specified libref is not assigned.
_SEINUSE	The library or member is not available for use.
_SEINVLB	The library is not in a valid format for the access method.
_SEINVLN	The libref is not valid.
_SELBACC	The action requested cannot be performed because you do not have the required access level on the library.
_SELBUSE	The library is still in use.
_SELGASN	The specified libref is not assigned.
_SENOASN	The libref is not assigned.
_SENOLNM	The libref is not available for use.
_SESEQLB	The library is in sequential (tape) format.
_SWDUPLB	The libref refers to the same physical file as another libref.
_SWNOLIB	The library does not exist.
Fileref Messages
_SELOGNM	The fileref is assigned to an invalid file.
_SWLNASN	The fileref is not assigned.
SAS Data Set Messages
_DSENMR	The TRANSACTION data set observation does not exist in the MASTER data set.
_DSEMTR	Multiple TRANSACTION data set observations do not exist in MASTER data set.
_DSENOM	No matching observation was found in MASTER data set.
_SEBAUTH	The data set has passwords.
_SEBDIND	The index name is not a valid SAS name.
_SEDSMOD	The data set is not open in the correct mode for the specified operation.
_SEDTLEN	The data length is invalid.
_SEINDCF	The new name conflicts with an index name.
_SEINVMD	The open mode is invalid.
_SEINVPN	The physical name is invalid.
_SEMBACC	You do not have the level of access required to open the data set in the requested mode.
_SENOLCK	A record-level lock is not available.
_SENOMAC	Member-level access to the data set is denied.
_SENOSAS	The file is not a SAS data set.
_SEVARCF	The new name conflicts with an existing variable name.
_SWBOF	You tried to read the previous observation when you were on the first observation.
_SWNOWHR	The record no longer satisfies the WHERE clause.
_SWSEQ	The task requires reading observations in a random order, but the engine that you are using allows only sequential access.
_SWWAUG	The WHERE clause has been augmented.
_SWWCLR	The WHERE clause has been cleared.
_SWWREP	The WHERE clause has been replaced.
SAS File Open and Update Messages
_SEBDSNM	The filename is not a valid SAS name.
_SEDLREC	The record has been deleted from the file.
_SEFOPEN	The file is currently open.
_SEINVON	The option name is invalid.
_SEINVOV	The option value is invalid.
_SEINVPS	The value of the File Data Buffer pointer is invalid.
_SELOCK	The file is locked by another user.
_SENOACC	You do not have the level of access required to open the file in the requested mode.
_SENOALL	_ALL_ is not allowed as part of a filename in this release.
_SENOCHN	The record was not changed because it would cause a duplicate value for an index that does not allow duplicates.
_SENODEL	Records cannot be deleted from this file.
_SENODLT	The file could not be deleted.
_SENOERT	The file is not open for writing.
_SENOOAC	You are not authorized for the requested open mode.
_SENOOPN	The file or directory is not open.
_SENOPF	The physical file does not exist.
_SENORD	The file is not opened for reading.
_SENORDX	The file is not radix addressable.
_SENOTRD	No record has been read from the file yet.
_SENOUPD	The file cannot be opened for update because the engine is read only.
_SENOWRT	You do not have Write access to the member.
_SEOBJLK	The file or directory is in exclusive use by another user.
_SERECRD	No records have been read from the input file.
_SWACMEM	Access to the directory will be provided one member at a time.
_SWDLREC	The record has been deleted from file.
_SWEOF	End of file.
_SWNOFLE	The file does not exist.
_SWNOPF	The file or directory does not exist.
_SWNOREP	The file was not replaced because of the NOREPLACE option.
_SWNOTFL	The item pointed to exists but is not a file.
_SWNOUPD	This record cannot be updated at this time.
Library/Member/Entry Messages
_SEBDMT	The member type specification is invalid.
_SEDLT	The member was not deleted.
_SELKUSR	The library or library member is locked by another user.
_SEMLEN	The member name is too long for this system.
_SENOLKH	The library or library member is not currently locked.
_SENOMEM	The member does not exist.
_SWKNXL	You have locked a library, member, or entry, that does not exist yet.
_SWLKUSR	The library or library member is locked by another user.
_SWLKYOU	You have already locked the library or library member.
_SWNOLKH	The library or library member is not currently locked.
Miscellaneous Operations
_SEDEVOF	The device is offline or unavailable.
_SEDSKFL	The disk or tape is full.
_SEINVDV	The device type is invalid.
_SENORNG	There is no write ring in the tape opened for Write access.
_SOK	The function was successful.
_SWINVCC	The carriage-control character is invalid.
_SWNODSK	The device is not a disk.
_SWPAUAC	Pause in I/O, process accumulated data up to this point.
_SWPAUSL	Pause in I/O, slide data window forward and process accumulated data up to this point.
_SWPAUU1	Pause in I/O, extra user control point 1.
_SWPAUU2	Pause in I/O, extra user control point 2.

Comparisons

The SYSRC autocall macro and the SYSRC automatic macro variable are not the same. For more information, see “SYSRC Automatic Macro Variable” on page 220.

Example: Examining the Value of _IORC_

The following DATA step illustrates using the autocall macro SYSRC and the automatic variable _IORC_ to control writing a message to the SAS log:

data big;
   modify big trans;
   by id;
   if _iorc_=%sysrc(_dsenmr) then put 'WARNING: Check ID=' id;
run;

%TRIM and %QTRIM Autocall Macro

Trim trailing blanks.
Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%TRIM(text | text-expression)

%QTRIM(text | text-expression)

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

The TRIM macro and the QTRIM macro both trim trailing blanks. If the argument contains a special character or mnemonic operator, listed below, use %QTRIM.

QTRIM produces a result with the following special characters and mnemonic operators masked so that the macro processor interprets them as text instead of as elements of the macro language:

& % ' " ( ) + − * / < > = ¬ ∘ ~ ; , #  blank
AND OR NOT EQ NE LE LT GE GT IN

Examples

Example 1: Removing Trailing Blanks

In this example, the TRIM autocall macro removes the trailing blanks from a message that is written to the SAS log.

%macro numobs(dsn);
%local num;
data _null_;
   set &dsn nobs=count;
   call symput('num', left(put(count,8.)));
   stop;
   run;
    %if &num eq 0 %then
       %put There were NO observations in %upcase(&dsn).;
    %else
       %put There were %trim(&num) observations in %upcase(&dsn).;
%mend numobs;
%numobs(sample)

Invoking the NUMOBS macro generates the following statements:

DATA _NULL_;
SET SAMPLE NOBS=COUNT;
CALL SYMPUT('num', LEFT(PUT(COUNT,8.)));
STOP;
RUN;

If the data set Sample contains six observations, then the %PUT statement writes this line to the SAS log:

There were 6 observations in SAMPLE.

Example 2: Contrasting %TRIM and %QTRIM

These statements are executed January 28, 1999:

%let date=%nrstr(  &sysdate  );
%put *&date* *%qtrim(&date)* *%trim(&date)*;

The %PUT statement writes this line to the SAS log:

*  &sysdate  * *  &sysdate* *  28JAN99*

%VERIFY Autocall Macro

Returns the position of the first character unique to an expression.

Type:	Autocall macro
Requirement:	MAUTOSOURCE system option

Syntax

%VERIFY(source, excerpt)

Required Arguments

source

is text or a text expression that you want to examine for characters that do not exist in excerpt.

excerpt

is text or a text expression. This is the text that defines the set of characters that %VERIFY uses to examine source.

Details

Note: Autocall macros are included in a library supplied by SAS. This library might not be installed at your site or might be a site-specific version. If you cannot access this macro or if you want to find out if it is a site-specific version, see your on-site SAS support personnel. For more information, see “Storing and Reusing Macros” on page 117.

%VERIFY returns the position of the first character in source that is not also present in excerpt. If all characters in source are present in excerpt, %VERIFY returns 0.

Example: Testing for a Valid Fileref

The ISNAME macro checks a string to verify that it is a valid fileref and prints a message in the SAS log that explains why a string is or is not valid.

%macro isname(name);
    %let name=%upcase(&name);
    %if %length(&name)>8 %then
       %put &name: The fileref must be 8 characters or less.;
    %else %do;
       %let first=ABCDEFGHIJKLMNOPQRSTUVWXYZ_;
       %let all=&first.1234567890;
       %let chk_1st=%verify(%substr(&name,1,1),&first);
       %let chk_rest=%verify(&name,&all);
       %if &chk_rest>0 %then
          %put &name: The fileref cannot contain
              "%substr(&name,&chk_rest,1)".;
       %if &chk_1st>0 %then
          %put &name: The first character cannot be
              "%substr(&name,1,1)".;
       %if (&chk_1st or &chk_rest)=0  %then
          %put &name is a valid fileref.;
    %end;
  %mend isname;
%isname(file1)
%isname(1file)
%isname(filename1)
%isname(file$)

When this program executes, the following is written to the SAS log:

FILE1 is a valid fileref.
1FILE: The first character cannot be "1".

FILENAME1: The fileref must be 8 characters or less.
FILE$: The fileref cannot contain "$".