CheckLog Arguments

Given its capabilities, CheckLog has a number of arguments. The arguments generally fall into three categories: input, reporting, and operational arguments. All arguments are optional. If no options are specified, the macro checks the current log, outputs issues to Log_issues, and issues a pop-up message with the status of the log.

For users new to macro programs, positional arguments do not require the use of the argument name when specifying a value, but they have to be in the same order specified by the macro program. Keyword arguments require the use of the argument name followed by an equal sign and the desired value (e.g., pm=Y). In my macros, any arguments that are “binary” (“yes” and “no”), can be specified with the full length value or 1 character (“yes” or “y” or even “yup” work). Here are three examples of the use of positional and keyword arguments using CheckLog:

/* Positional argument */
%CheckLog(C:\dir\example.log);
/* Keyword arguments */
%CheckLog(pm=E, abort=Y);
/* Both types of arguments */
%CheckLog(C:\dir\example.log, abort=Y, pm=E);

Input Arguments

The following arguments manage what is sent to CheckLog to include or exclude from the review.

• LOG – The log to check, either blank (current log), a specific file (with the directory), or a directory that contains logs. Note that the extension “log” is searched for in a directory, and can be overwritten by the EXT= argument (see below).
• EXT= – When reviewing directories, this argument specifies the extension to use to identify files to include in the review, defaulted to LOG. Another common alternative is simple TXT.
• SUBDIR= – Search subdirectories using the DirList macro. This macro can only be used on Microsoft Windows. N = No, do not search subdirectories (default); Y = Yes, search subdirectories (requires DirList macro).
• KEYWORD= – This argument can be used to list additional keywords to include in the search for issues. Keywords used in non-SAS logs or in user-specified issues can be added. For example, the terms CAUTION or ALERT may be used in non-SAS logs or user-specified issues. Note: The order of the words listed matters. The words listed first will be searched for last and will overwrite any other words found prior. Thus, the first word should have the highest priority. Of course, the keywords in the macro program will overwrite user-specified keywords (e.g., "ERROR" will always trump the words in the KEYWORD= argument).
• EXCLUDE= – As noted above, this argument can be used to exclude specific phrases as issues. The user specifies a data set that contains a variable named LogText, which contains specific messages to exclude. If the variable name is not LogText, specify the variable named after the data set name in the argument, followed by a space (e.g., work.exclusions list).

Initially, I used the EXCLUDE= option to exclude SAS’s expiration warnings, but I eventually wrote that exclusion into CheckLog. The variable named selected by default, LogText, is the same variable name used in the output data set from CheckLog. Therefore, once a user identifies a false issue, they can use the output from CheckLog to write those messages out to a permanent data set to use as an exclusion data set.

The EXCLUDE= argument can be used when non-issues are encountered that cannot be filtered based on a simple rule (e.g., a data set name unavoidably contains the word “error”). It is NOT recommended that this feature be used to circumvent code revision for easily-avoided issues. Note that data set options can be applied with this argument, so a master file with exclusions can be used and filtered:

%CheckLog( C:\dir\test.log, Share.Log_exclusions(where=(Program="Claims")) Text );

Reporting Arguments

The following are reporting arguments, in which the macro notifies the user (e.g., via a data set or a pop-up message) whether any issues were found. Some of these arguments require simple Yes/No values, but some have a third option, E, which indicates that the behavior should occur only when issues (Errors) are found.

• OUT= – The name of the output issues data set, defaulted to Log_issues. This argument is automatically set to Logs_w_issues when checking a directory of logs.
• PM= – A pop-up message is used when running SAS in interactive mode to notify the user of the status of the log. This argument determines the behavior of this pop-up. Valid values: N = No, never display a pop-up message; Y = Yes, always display a pop-up message (default); E = Error-only, display a pop-up only when issues are found.
• SOUND= – Optionally, a sound can be output, which varies depending on the status of the log. A sound like “Hurray!” and “Uh-oh” were selected based on the status of the log. This option can only be (successfully) used with Microsoft Windows©. Valid values: N = No, never display a pop-up message; Y = Yes, always display a pop-up message (default); E = Error-only, output a sound only when issues are found.
• RELOG= – This option recreates (“relogs”) the SAS log as if the current interactive SAS session had run the program. It overwrites the current log with the imported log, after CheckLog outputs notes regarding the status of the log. This is best used for reviewing logs output from batch mode. Valid values: N = No, do not overwrite the current log (default); Y = Yes, overwrite the current log with the imported log; E = Error-only, overwrite the log only when issues are found.
• PRINT= – Print the identified issues to the output, defaulted to No
• TO= – An email can be sent listing the types of issues encountered. Specify an email address in this field to output an email. Note that email addresses are not validated by CheckLog, and the user is responsible for gaining authorization to use email and permission to send email to the recipient. Email support must be set up in SAS to use this function.
• CC= – Specifies a CC email address. See above. Note that BCC is not supported for reasons regarding privacy noted below. The CC argument will not work without the TO argument.

A Warning Regarding Email and Privacy Laws

A warning regarding email and privacy laws, such as the Health Insurance Portability and Accountability Act of 1996 (HIPAA): Given the sensitivity of healthcare data and the transparency and ease-of-interception of plain-text emails, the CheckLog macro program, by design, does NOT included specific issue messages or related notes, nor does it include BCC recipients. Log lines with the term “error” can include patient information, and emailing this information would likely violate privacy laws, such as HIPAA. Any users who attempt to overcome this limitation risk personal responsibility for violating laws such as HIPAA. For more information on HIPAA, please visit the U.S. Department of Health and Human Services website at http://www.hhs.gov/ocr/privacy/.

Operational Arguments

The following arguments modify how CheckLog operates. Using these options, the user can fine-tune how CheckLog operates and output additional information.

• LOGDEF= – The setting for PROC PRINTTO log= when CheckLog turns the log back on, defaulted to LOG, which is the "default"
• DIREXT= – When reviewing directories, this argument specifies whether to include the full directory and extension of the file in the output data set. By default, only the name of the log (e.g., “test” for the file “C:\test.log”) is included in the output data set. When DIREXT is set to Y, it adds both the directory and extension. Valid values: N = No, do not add directory and extension (default); Y = Yes, add directory and extension.
• SHADOW= – Occasionally the user may wish to check a log for a program that is still running. In this situation, it is necessary to make a copy of the log before associating with it using the FILENAME function; thus a copy of the log is necessary before importing it. This argument is now set to Y by default, and to maintain backward-compatibility, it is left in the list of arguments. Users can still turn it off if desired, especially if the user is not allowed to execute operating system commands. Valid values: N = No, do not make a copy of the log; Y = Yes, make a copy of the log (default).
• ABORT= – Determines whether or not the following program is aborted. This is useful to halt a long program and alert the user that there are issues. Valid values: N = No, do not abort program when issues occur (default); Y = Yes, abort program when issues occur.
• TEST= – To test CheckLog, set the test argument to “test” (i.e., test=test). During normal usage, CheckLog turns off the log in order to avoid detecting issues and phrases within its own execution and to avoid outputting irrelevant processing in the log. In test mode, it leaves the log on and does not delete temporary data sets. Additionally, the extra data set Log_keywords is output for troubleshooting.

CAUTION: The ABORT= option may have undesirable results, especially in SAS 9.1. Please use it with care and thorough testing. In version 9.1.3, it has been identified that when the abort option is specified and used in a program, then the CheckLog macro program is used from a keyboard shortcut, SAS crashes. There is no known workaround and it appears to be a bug in SAS 9.1.3. To abort macro programs, it is much more stable to use the ISSUES macro variable that is output from CheckLog, as in the following statement, which ends the macro program but not the code that follows the macro call:

%if &ISSUES>0 %then %return;