About CheckLog‎ > ‎Documentation‎ > ‎

Example Usage

The following examples demonstrate how CheckLog can be used.

Current Log

Note: Checking the current log in Enterprise Guide is a bit different than in Base SAS. See the Enterprise Guide page for details.

Simply leave the first argument blank to check the current log.

%CheckLog;

The macro can also be set to a keyboard shortcut by defining a keyboard shortcut (hit F9 on Windows) to the following:

gsubmit '%checklog;'

Using the keyboard shortcut (I use SHIFT+F6, since F6 is the shortcut for the log window) will always check the current log. This is very useful for development or review of another programmer's code.

External Log

Specify the specific directory, file name, and extension of the log to check in the first argument:

%CheckLog(C:\Dir\SubDir\Test.log);

It may also be helpful, when checking non-SAS logs, to specify additional keywords to search for:

%CheckLog(C:\Dir\SubDir\Test.txt, keyword=caution);

For more examples on the KEYWORD= argument, see below.

Directory of Logs

Specify the directory to check in the first argument:

%CheckLog(C:\Dir\SubDir\);

Depending on what you want to do with the output, it may be useful to see the actual file names instead of the SAS data set names of the logs that are imported and have issues. Use the DIREXT=Y argument to switch to the full path and file name.

%CheckLog(C:\Dir\SubDir\, dirext=Y);

By default, the macro searches for files with the LOG extension when searching a directory. To change that, use the EXT= argument.

%CheckLog(C:\Dir\SubDir\, ext=txt);

To also scan for subdirectories within a directory (Window only), specify the SUBDIR=Y argument.

%CheckLog(C:\Dir\SubDir\, subdir=Y, ext=txt);

Specify the Output Data Set Name

Use the OUT= argument to change the output data set name.

%CheckLog(out=Current_Log);

%CheckLog(C:\Dir\SubDir\Test.txt, out=Test_Log);

Note: This will not work when reviewing a directory. Each imported log will take the name of the original file name, modified to work as a SAS data set name (e.g., dashes and spaces convert to underscores).

Add Custom Keywords

Users may wish to review non-SAS logs or user-defined issue keywords (e.g., CAUTION). Use the KEYWORD= argument to specify additional keywords.

%CheckLog(C:\Dir\SubDir\External.log, keyword=CAUTION);

More than one word can be specified.

%CheckLog(C:\Dir\SubDir\External.log, keyword=CAUTION ALERT);

Exclude Phrases

In order to exclude specific phrases, store the phrases in a data set. It would be wise to use a permanent data set.

%CheckLog(exclude=Share.Log_Exclusions);

By default, the macro looks for a column named LogText. To override this, specify the variable name after the data set name:

%CheckLog(exclude=Share.Log_Exclusions ExcludePhrases);

Note: Data set options can be used. For example, if a data set with phrases to exclude is shared between programs, the user could filter the excluded phrases by program:

%CheckLog(exclude=Share.Log_Exclusions(where=(program="ParticularProgram.sas")) );

WARNING: Do not exclude phrases searched for by the CheckLog program. This feature is best used for phrases that cannot be excluded in general, like when data set names include the word "ERROR" in the name. To exclude the phrases that CheckLog searches for would be to circumvent the purpose of the macro. Nonetheless, this can be done and it is best to do so in the actual macro code. Simply comment out the particular search to exclude.

Notifications

It's not always necessary to pop-up a message about the status of the log for the user to review.

To turn the pop-up message off, use the PM= argument.

%CheckLog(PM=N);

To turn it on only when issues are present, use PM=E (short for "errors only"):

%CheckLog(PM=E);

Additionally, the user can output sound (Microsoft Windows only) using the SOUND= argument. This accepts the same arguments as the PM= argument.

%CheckLog(sound=E);

The particular sounds were selected to sound like "hurray!" and "uh-oh!", depending on the results.

Users can also send an email as part of the notification. Simply specify a TO= address and optionally a CC= address. BCC is not available.

%CheckLog(to=me@example.com);

Here are samples of what the email would look like, depending on the type of check: Sample Emails.

Reviewing the Results

If the log is checked automatically or in a batch file, it is difficult to read through the text file output for issues. To re-create the log in the current interactive SAS session, use the RELOG= option. (The PM argument is set to N since the user probably knows the log has issues and there's no need for the pop-up message.)

%CheckLog(C:\Dir\SubDir\Test1.log, pm=n, relog=Y);

Note that this feature does nothing when checking a directory of logs.

As noted above, during directory mode, the user has the option to output the name of the SAS data set name of the imported log (default) or the full directory and file name for the logs that have issues.

%CheckLog(C:\Dir\SubDir\, dirext=Y);

This option may be useful when completing additional processing on the logs. If the user needs the SAS data set name, it is available; however, the user may need the full directory, file name, and extension instead. For example, if the CheckLog macro is used to notify a non-SAS user about issues in the log when run in a batch program, the user may not use SAS to review the logs and would prefer to have a list of file names to review.

To test or review the macro itself, turn on the test feature using the TEST= argument.

%CheckLog(test=test);

Note: Typically this type of argument is simply a Yes/No flag (Y/N); however, given the nature of the macro, I wanted to use something longer and different in case of user error. Since the macro could actually find itself within the log, this would provide confusing or even meaningless results.

Conditional Processing

The user can abort the currently running SAS code if an issue is encountered. (Caution: This feature causes version 9.1.3 to crash when CheckLog is used from a shortcut after a prior run has aborted.)

%CheckLog(abort=y);

This is similar to using the ERRORCHECK=STRICT
and ERRORABEND options, but the CheckLog macro could provide more information instead of simply halting SAS. For example, instead of simply cancelling the code without any notification, CheckLog can send the user an email:

%CheckLog(abort=y, to=me@example.com);

If cancelling the program is necessary during the execution of a macro program, it is safer to do the following instead of using the abort option:

%if &ISSUES>0 %then %return;

The ISSUES macro variable contains the total number of issues encountered in the log(s) and can be used to write conditional code after the CheckLog macro executes. For example, if a program encounters an issue using one method for processing the data, the program could try to execute a different program to resolve the issue before continuing.

%CheckLog;
%macro ConditionalProcess;
    %if &ISSUES>0 %then %do;
        %include "C:\Dir\SubDir\OtherProgram.sas";
    %end;
%mend ConditionalProcess;
%ConditionalProcess;

"Buffered" Arguments

Specific arguments are "buffered" in the sense that they are scanned one item at a time by the CheckLog macro. These arguments allow for more than one value. For example, if the user wants to email two people, specify both email address in the TO= argument separated by spaces. Here are the buffered arguments:
  • KEYWORD=
  • TO=
  • CC=
The EXCLUDE= argument could be listed here, except it scans for two different things and only scans twice. The macro looks for the data set name and the variable name (if specified).

Note: I use the term "buffer" based on the common usage of a macro program option called PARMBUFF, the use of which usually requires the macro program to iterate through each value based on a set of delimiters (e.g., commas or spaces). Essentially, PARMBUFF can be used to replace all macro arguments. For more on this topic, read these articles: %MACRO statement, SYSPBUFF Automatic Macro VariableA PARMBUFF Parsing Macro
.

Flag Arguments

The following arguments are simply Y/N (for Yes/No) flags:
  • DIREXT
  • PM
  • SOUND
  • RELOG
  • ABORT

The TEST= argument is sort of a flag. As mentioned above, I wanted it to be more difficult to run the macro in test mode to avoid any confusion, so the "Yes" value is actually "test" (lower case).

Use Everything

It's not possible to use every feature in one piece of code, but here are two examples of using most of the features in one go:

/* Check a specific log */
%CheckLog(C:\Dir\SubDir\Test_Log.txt, keyword=Caution Alert, exclude=Share.Log_Exclusions(where=(program="TEST_LOG")) IgnorePhrase, pm=E, sound=Y, to=me@example.com you@example.com, cc=them@example.com, relog=Y, abort=Y, test=test);

/* Check a directory */
%CheckLog(C:\Dir\SubDir\, subdir=Y, ext=txt, dirext=Y, keyword=Caution Alert, exclude=Share.Log_Exclusions(where=(location="DIR\SUBDIR")) IgnorePhrase, pm=E, sound=Y, to=me@example.com you@example.com, cc=them@example.com, abort=Y, test=test);

Note that the abort option isn't really doing anything if you only submit the CheckLog macro.
Subpages (1): Sample Emails