Transcription

1

2

3

4

5

6 rc = libname( mylib, /nosuch ); if rc ne 0 then %fatal; OR if libname( mylib, /nosuch ) then %fatal;

7 Select (flag); when (1) when (2) otherwise %fatal(text= Unexpected flag value, syscodes=n); end;

8

9 %macro fatal(text=,syscodes=y); do;... end; %mend %fatal;

10 _sysrc = sysrc(); _sysmsg = sysmsg(); put _all_; call display( fatal.frame,_sysrc, _sysmsg,,&text, &syscodes,&errnum );

11 %macro %fatalin; %global _errnum; %let _errnum = 0; %mend %fatalin %let _errnum = %eval(&_errnum + 1);

12

13

14

15 call execcmd( build!!pgm!! ; ); if scan(pgm,4,. ) eq FRAME then call execcmd( src; ); cmd= find %fatalin ; ; call execcmd(cmd); do i=1 to errnum; call execcmd( find %fatal ; ); end;

16

17

18

19

20 Andrew Ratcliffe, Ratcliffe Technical Services Limited It seems that, no matter how much experience one gains, no matter how much planning one completes, bugs are still an inevitability in software development. So, if bugs can t be eradicated during the analysis, design, or programming stages, how can we make the investigation and resolution of them easier during the testing stage? This brief paper describes some simple, practical tools for ensuring that the debugging process is less painful and more efficient. Two are specifically for use in SAS/AF applications, the third can be used in both SAS/AF and base SAS environments. One of the ways that the task of bug fixing can be enhanced is to catch the problem as soon as it occurs. Unless every single return code is checked, a problem can continue until it causes a bigger problem at a later stage. This paper describes a quick and convenient method for testing and capturing every return code - and presenting meaningful information should a failure occur. Introduction A large proportion of SCL-coding involves calling functions. Each function returns a value that can be tested for success. In some cases, the application logic will want to perform alternative actions dependant upon the return value, but in many cases the application is left with no way it can reasonably continue if the return code indicates failure. Examples include failure to open data sets, to allocate librefs, and to manipulate lists. Where the application has no sensible option but to terminate gracefully, the maintenance programmer would like some information regarding why the error occurred so that he/she may attempt to fix the underlying problem. Often, these return codes are not checked by the program so that a) the program continues until it fails big-time, and b) the maintenance programmer's task is harder because the debugging information has been muddied by the subsequent program activity. The reason that programmers don't write return code checks is that it involves a great deal of repetitive, space-consuming code. I use a simple macro to do this. Using the macro takes away the repetition from me, and does not result in my source code being elongated by reams of checking code. Because my source code is no longer, I can still see the same amount of functional code on my screen.

21 What it does The macro is based upon the Error Handler described by John Watts[1] at SEUGI 94. The macro is used as shown below. rc = close(d_rawpeg); if rc ne 0 then %fatal; On the face of it, it adds one extra line of code for each call. However, it can be called as follows. if close(d_rawpeg) then %fatal; Using the above style results in no extra lines of source code. The macro generates SCL code (at compile-time) that performs the following tasks: Gather values of SYSRC() and SYSMSG() Gather the name of the executing module Issue a PUT _ALL_ to write all SCL variables to the log Pass the items gathered above, together with a unique serial number to help locate the line of source, to a frame The frame displays the information given to it together with some standard text to guide the user through handling this application failure. An example is shown below.

22 Notice that the frame does not offer an option to continue. The fatal error handler is only used for non-recoverable errors. The fact that no option to continue is offered means the programmer can simply continue coding after using %fatal - no ELSE statement is required. Without the need for an ELSE statement, the program does not tend to get so heavily indented as might otherwise be the case. As described, the fatal error handler is useful. However, it has additional functionality. When it detects that it is being run by a development programmer (based upon the value of a global macro variable, see "Conditional Debugging Messages"), it offers extra toolbar buttons. These buttons permit two valuable operations: the ability to open the failing module in edit mode at the failing line, and the ability to continue execution. The ability to be taken to the point of failure in the source code permits quick and easy understanding of the context of the problem, and an instant fix to the code (if appropriate). The ability to continue can be useful to the development programmer if %fatal has been called in error, perhaps due to a mis-coded IF statement. How it does it The fatal error handler consists of three components: the frame, the fatal macro, and the fatal initialisation macro. A listing of the basic (simplified) fatal macro follows. %macro fatal(text,frame=system.seugi99.fatal.frame ) ; pgm = screenname(); %if %length(&text) gt 0 %then %do; apptxt = &text; %end; %else %do; apptxt = ; %end; sysmsg = sysmsg(); sysrc = sysrc(); put "FATAL&_fat_id_:" " SYSRC=" sysrc " SYSMSG=" sysmsg " Application message=" apptxt " Program=" pgm ;

23 put _all_; call display("&frame", sysrc, sysmsg, apptxt,&_fat_id_, pgm ); %let _fat_id_ = %eval(&_fat_id_ + 1); %mend fatal; You will see that it increments a global macro variable named _FAT_ID_. The value of this macro variable is the unique identifier for the failing line of SCL, i.e. each invocation of %fatal within an SCL entry has a unique number. The macro variable is initialised and defined as global in the fatal initialisation macro. The fatal initialisation macro is listed following. %macro fatalin(start=1) ; %global _fat_id_; %let _fat_id_ = &start; %mend fatalin; The fatal initialisation macro must be invoked once in each module that uses the fatal macro. It must be invoked before the first invocation of %fatal. It contains no executable SCL statements, so it may be placed before any executable section of your SCL code. The final component is the fatal frame. Initially it places its parameters in the appropriate fields on the screen, and then it displays the appropriate toolbar. The "user toolbar" and the "programmer toolbar" are stored as SLISTs. At run-time, the fatal frame checks the value of the debug macro variable and instructs the toolbar widget to use the appropriate SLIST. When the Exit toolbar button is clicked, the fatal frame terminates the application by performing a GOTO to a null piece of SCL, i.e. an SCL module that contains only an INIT label and a RETURN statement. If the programmer s toolbar is available and the toolbar s go to error button is clicked, the fatal frame finds the failing line of SCL using the following code (where PROGRAM was passed by the caller of the frame). cmd = build!! program!! ; ; call execcmd(cmd); if scan(program,4) eq FRAME then do; call execcmd( src; ); end; cmd = find %fatalin ; ; call execcmd(cmd); do i=1 to errnum; cmd = find %fatal ; ;

24 call execcmd(cmd); end; The preceding code opens the SCL entry (via the frame entry if appropriate) and issues sufficient FIND commands for the string %fatal. The number of FIND commands is determined by the unique identifier number given to this particular invocation of %fatal - this was passed by the caller as ERRNUM. Those who haven t seen the fatal error handler before are often quite startled at the speed and simplicity with which an error can be solved using this go to error facility. Additional features The code for %fatal shown earlier is a cut-down version, for reasons of ease of understanding. The version that I use has a number of other optional parameters. Fatal errors in an application can occur due to a breakdown in the application s logic or assumptions. In these instances, the display of SYSRC and SYSMSG will not be appropriate, but the programmer would like the ability to supply his/her own message. The positional TEXT parameter of the macro (shown) provides the ability to add a message. If this value is not blank then an additional field is displayed near the bottom of the fatal frame (if not, the field is hidden). The full version of the macro also has a SYSCODES=Y parameter. This is used to indicate whether the values of SYSRC and SYSMSG should be gathered and displayed (by the macro and the frame). SYSCODES is passed to the frame. Usage in an object-oriented environment The fatal error handler can easily be incorporated into an object-oriented environment. In the root class for your application s classes, add a method named FATAL_ERROR. This method should be defined to run the fatal frame. The frame can pick-up parameters passed to the method using its ENTRY statement. The fatal macro now calls the FATAL_ERROR method on _SELF_ in order to invoke the frame. When the application is terminated, the _TERM_ method for each active object will execute. To prevent multiple displays of the fatal frame, I place a flag in the local list when the fatal macro is called. In subsequent calls, i.e. when the flag is already set, the fatal frame is not invoked. The following code begins the fatal macro. The ITEMNAME value is a parameter for the fatal macro that I default to TERMINATING_DUE_TO_FATAL_ERROR. if not nameditem(envlist( L ),"&itemname" ) then do; /* Handle fatal error */ /* Set our flag to avoid repeated calls */ if envlist( L ) ne insertc(envlist( L ), Y

25 ,-1,"&itemname" ) then put ERROR: FATAL could not set flag in local list ; continue with fatal macro Conclusion For me, the fatal error handler is "must have" in all applications. It provides benefits during development by capturing information and permitting a fast-path to the point of failure; and it provides benefits whilst the application is in production-use by presenting the user with a friendly and informative interface for handling fatal errors. As an alternative to using debug mode (in either SAS/AF or base SAS software) I often prefer to use copious PUT statements to tell me what's happening. This is fine until they have to be taken-out as the code nears completion. At that time, the task of removing them can be tedious, and I cannot be certain that I won't need each one any longer. To overcome this problem I use the technique described by Watts[1] as the Debug Flag. A global macro variable is used to indicate whether debugging messages and activities are required. Differing values can indicate the level of debugging required, for example 0 can indicate that no debugging information is required, 1 can indicate that messages are required, 2 can indicate that data sets should not be deleted. With respect to messages, I have a little macro that issues the PUT statement dependant upon the value of the macro variable. %macro dput(msg = /* Parms for PUT */,lvl = 0 /* Priority level of msg */,dmv = debug /* Name of debug macro var */ ); %global &dmv; %if &&&dmv ge &lvl %then %do; put &msg; %end; %mend dput; The default name of the macro variable is set to DEBUG, and the default comparison value is set to zero so that messages are always issued unless the value is less than zero (or has never been set). Three sample invocations are shown following /* DEBUG macro variable not yet set at all */ 14 data _null_; x = 10; %dput(msg= hello world x); 17 run;

26 NOTE: The DATA statement used 0.12 seconds %let debug=1; 21 data _null_; %dput(msg= hello world _n_); run; hello world 1 NOTE: The DATA statement used 0.09 seconds data _null_; 26 %dput(msg= hello Den Haag _n_, lvl=2); 27 run; NOTE: The DATA statement used 0.07 seconds. The first sample shows how no messages are output if the macro variable has not been set (such as would be the case in a production environment). The second example shows that the default message level results in the message being output if the macro variable is set to a positive number. The final example shows how the LVL parameter can be used to provide conditional outputting of messages. The sample macro I have shown does not work in a SAS/AF environment because it is resolved at compile-time. Thus, the PUT statement is included in the code if the DEBUG macro variable is set to a suitable value at compile-time. The value of the macro variable is not tested at run-time. To overcome this, you can use the following alternate macro with SAS/AF SCL. %macro dput(msg = /* Parms for PUT */,lvl = 0 /* Priority level of msg */,dmv = debug /* Name of debug macro var */ ); if symgetn("&dmv") ge &lvl then do; put &msg; end; %mend dput; Because the SYMGETN() function is used, the macro is SCL-specific, but if the IF statement were recoded as if inputn(symget("&dmv"), best. ) ge &lvl then then the macro would be universal, i.e. the same macro could be used in the SAS/AF and the base SAS environment. The drawback with this macro is that the IF statement must be evaluated at run-time, slowing down the application. Your particular circumstances will dictate whether you want two macros or one non-optimal version.

27 If performance is likely to be a problem in the production environment, you can "remove" the DPUT macro from your SCL and DATA steps by defining it as a null macro. You must then recompile your SCL. I have come across occasions where I ve shipped some amended code to a client and they subsequently say that they don t notice any difference in the behaviour of the code. On more than one of these occasions, the client had not installed the new version, or had installed it to the wrong location. To help me with remote analysis of such a situation, I developed a small and simple little SCL macro that would write the time of the module s compilation to the log at run-time. In the situation I have just described, it would immediately be clear that the old module was still being used. This diagnosis is achieved without guiding the client into viewing the SCL source code. I place the macro immediately following the INIT label of every frame, and in the _INIT_ method of every class. %macro sclinit (label=init); sn = screenname(); put "Running &label for" sn "compiled %sysfunc(datetime(),datetime.)"; put ; %mend sclinit; The macro is resolved into SCL at compile-time. The value of the DATETIME() function is also obtained and formatted at compile-time (by the %SYSFUNC() macro function). So, the SCL code at compile-time contains the hard-coded date/time of the compilation. Andrew Ratcliffe is a freelance SAS software consultant with over 15 years experience of SAS software. He specialises in object-oriented application development. Through his company (Ratcliffe Technical Services Limited), he is able to offer services including analysis and design consultancy, mentoring, training, and programming resources. Andrew can be contacted as detailed below: UK telephone: UK fax: International telephone: International fax: andrew@ratcliffe.demon.co.uk Web homepage:

28 [1] Watts, John An Application Development Application, SEUGI 94 Proceedings. SAS Institute.