Dynamic Macro Invocation Utility Paul D Sherman, San Jose, CA

Transcription

1 Paper Dynamic Macro Invocation Utility Paul D Sherman, San Jose, CA ABSTRACT Often times it is necessary to repeatedly call a macro with only minor differences in its argument list. Most common is the application of producing multiple graphs panelized into an aggregate. The following simple macro %invoke() builds an argument list with a collection of index number suffixed positional parameters and calls a desired macro with a subset of these parameters as needed until all parameters have been accomodated. Resulting is a set of output having identical structure with customized content, all for the price of a single macro call. Skill Level: Intermediate to Advanced, familiarity with SAS/MACRO, SAS/GRAPH and Base/SAS. INTRODUCTION The SAS macro language is a powerful, important facility for coding in object-oriented style. Common code can be separated from a main application and encapsulated forming lots of little stand-alone subroutines. Macros can be nested, one may invoke another which invokes another, and so on. Good coding style dictates that no routine, method or function body should be longer than one typed page in length. The use of SAS macros help achieve this goal such as exemplified below %macro main; %bloknote(start, main); %init; %dothis; %macro init;... %dealwith(1.9); %macro dothis;... %dealwith(3.2); %macro dealwith(args); %dealwith(7.4); %bloknote(open, dealwith(&args.)); %cleanup; %put handling &args.; %bloknote(end); %bloknote(close); However, there is no easy way to repeatedly invoke the same object macro with differing argument values. One may copy/paste macro invocations and hard-wire argument values into each call, but this solution is static to run-time and not easily adaptable or maintainable. Non-identical macro re-invocation is often used when one desires to perform the same operations on varying content - such as creating a collection of similar looking web pages. HOW IT WORKS The heart of %invoke() is a double nested loop, the outer most iterating target macro calls while the inner most spins through each call's parameter list. Supposing i is the outer loop index while j is the inner loop index, at any time the target parameter is simply i+j do i=0; this many macro calls... do j=0;... with this many parms/call process (i+j)th parameter here... end; end; It is the user's responsibility to make sure their target macro handles the appropriate quantities of positional parameters. Because many SAS procedures expect and produce the first of a series of output content un-suffixed, without any numeric index, %invoke() handles this special occurance by skipping the argument index concatenation during the very first loop iteration. It is also critically important to make sure there are no spaces between base name and index suffix. Thus, we must trim and take only the non-trivial substring. Further, in order to preserve the constant length object name we must shorten the base name string by as many characters as are the length of the index number. In other words, index numbers zero through nine remove only the last base name character, while index numbers 10 through 99 remove the last two base name characters, and so on. This default SAS naming convention follows from the legacy eight character maximum dataset name length. For all but the last argument in each invocation we must also append the argument delimeter, being a single comma. The last step of each iteration is the macro call itself. A single de-reference of both base name and assembled argument list is prepended with a percent symbol, telling SAS that it is to be interpreted as a macro name. Once again, there will be serious errors (i.e., macro un-resolution) if the user's target macro does not handle the same quantity of arguments which % invoke() builds.

2 EXAMPLE: MULTI-GRAPH PANEL Assume one has a library macro which takes six parameters and produces a 3x2 graphics catalog layout. %macro plot3x2(one, two, three, four, five, six); %bloknote(open, plot3x2(&one.,&two.,&three.,&four.,&five.,&six.)); proc greplay igout=sugi29.graphs gout=sugi29.slides tc=sugi29.templt template=day3by2 nofs ; template day3by2; %* see appendix for coords *; treplay 1:&one. 2:&two. 3:&three. 4:&four. 5:&five. 6:&six. ; run; quit; %bloknote(close); Further suppose there are routinely seven sets of individual pictures created, one set per day, which are to be presented weekly as a single page. Arranging each picture to have successive numbers, the weekly task of producing panelized plots is easy %invoke(plot3x2, pix, 7, 6); SAS will execute automatically the following seven calls to %plot3x2() %plot3x2(pix, pi1, pi2, pi3, pi4, pi5); %plot3x2(pi6, pi7, pi8, pi9, p10, p11);... %plot3x2(p36, p37, p38, p39, p40, p41); One then finds seven entries in the graphics catalog, each of which look something like greplay grepla pi6 pi7 pi grepla pi9 p36 p37 p p39 p40 p EXAMPLE: WEB PAGE BUILDER It is nice to have up-to-date web content, and for the content to look and feel as similar as possible from one day to the next. One therefore has a library macro which takes three parameters and creates an html file precisely placing these three items on the web page. Furthermore, it is desired for example that the first item be shown as a thumbnail, the second only as a link (since its highly detailed) and the last as full size in the web page body. %macro makepage(thumb, link, body); %bloknote(open, makepage(&thumb., &link., &body.)); filename foo ""; data _null_; file foo; output <html>; output <body>; output <p><a href="&thumb..html">; output <img src="&thumb..gif">; output </a></p>; output <p><a href="&link..html">the link</a></p>; output <p><img src="&body..gif"></p>; output </body>; output </html>; run; filename foo clear; %bloknote(close); Using the %invoke() utility the summary pages are easily created %invoke(makepage, pix, 7, 3);

3 SAS executes these seven calls to %makepage() %makepage(pix, pi1, pi2); %makepage(pi3, pi4, pi5);... %makepage(p18, p19, p20); The summary pages are then always available and automatically customized and annotated specifically for each group of picture content. An example of the last page is shown below / \ p18.gif \ / the link p20.gif ADVANCED OPTIONS SHOWZERO= { true false } When one's target macro expects the first argument index to be explicitly numbered, the default SAS behavior can be overridden via keyword variable SHOWZERO=true. Although some SAS procedures leave off the 'zero' when creating and naming a series of objects, a very common macro programming paradigm is the &&var&i style of dynamically creating names. Clearly, all values of index variable i are treated equally; it is rare to see code such as %do i=0; %to 15; %if i eq 0 %then; %do; &var %else; %do; &&var&i The SHOWZERO= parameter value is not case sensitive, but must be only either true or false. Any other value is ignored, reverting to the default (i.e. false) parameter numbering scheme. SHOWZERO=false SHOWZERO=true aname aname0 aname1 aname1 aname2 aname2 SAMESIZE= { true false } Some SAS procedures such as those which create graphics catalog objects preserve the length of their constituent object names while creating and consecutively numbering them. Depending upon how many digits are in the index number, that many characters are taken away from the base name, going from right to left. A series of plots may have been named and labeled this way, for which we must accomodate when %invoke() looks for its parameter argument values. As above, the value is not case sensitive, but must be only either true or false. Any other value is ignored, reverting to the default (i.e. true) parameter name length preservation scheme. SAMESIZE=false SAMESIZE=true aname aname aname1 anam1 aname2 anam aname56 ana aname243 an243 PASSTHRU= There may be desired a common argument delivered identically to each target macro call. One therefore supplies keyword variable PASSTHRU= which by default is undefined. When supplied, it's value is the first positional parameter to each target macro invocation. With minor changes to %invoke()'s code, however, one may place this optional pass-through value at the end of the dynamically numbered arguments. OUTNAME= Sometimes there is need to uniquely and explicitly name the iterated output content. Such is not necessary in the case of the graphics catalog - items are given system generated names. When creating files, for example html (text) files, one might not want to over-write existing files or control explicitly a file naming scheme. Using the optional OUTNAME= keyword parameter, each invocation of the target macro receives this value, suffixed with incrementing index corresponding to each iteration. As described above, the default SAS behavior of invisible zero follows here, and can be overridden by using the SHOWZERO= option as well. We assume input parameters and output names follow the same numbering scheme; if this is not the case (rare), minor easy code revisions to %invoke() can be made.

4 COMPLETE EXAMPLE: ALL OPTIONS Using all available options to %invoke(), the following statement %invoke(amacro, thing, 5, 3, SHOWZERO=true, SAMESIZE=false, PASSTHRU=foo, OUTNAME=page ); will produce these SAS macro invocations %amacro(foo, page0, thing0, thing1, thing2); %amacro(foo, page1, thing3, thing4, thing5);... %amacro(foo, page4, thing12, thing13, thing14); where one might use the first two (required) positional parameters of %mymacro() as follows %macro amacro(uservars, outname, one, two, three); %bloknote(open, amacro(&uservars.,&outname.,&one.,&two.,&three.)); filename foo "&outname..html"; data _null_; file foo; output <html>; output <body>; output <h1>the &uservars. Page</h1>; output <p>args</p>; output <dl> output <dt>one</dt><dd>&one.</dd>; output <dt>two</dt><dd>&two.</dd>; output <dt>three</dt><dd>&three.</dd>; output </dl> output </body>; output </html>; run; filename foo clear; %bloknote(close); creating automatically these five web pages page0.html page1.html T page2.html T page3.html A T page4.html * A T * * A The foo Page * * * A +-- * * * Args +-- * * * one = thi * * two = thi * three = thi CONCLUSION We have shown two very common examples of repeatedly and dynamically streaming incrementally indexed parameter lists. With its available options the functionality of %invoke() is bound to be very widely used from handling graphics catalog content to creating files, sending or performing further and higher levels of content summarization. Although some assumptions have been made, we believe these are minor and easily customized in the utility's code. Together with the Log Manager, a SAS programmer will find their application code error-free and, if trouble should arise, easily debugged. REFERENCES Carpenter, Arthur L., Carpenter's Complete Guide to the SAS Macro Language, Cary, NC: SAS Institute, Inc., pp. Carpenter, Arthur L. and Shipp, Charles E., Quick Results with SAS/GRAPH Software, Cary, NC: SAS Institute, Inc., pp. Sherman, Paul, Intelligent SAS Log Manager, in Proceedings of the Twenty-Sixth Annual SAS User Group International Conference. Cary, NC: SAS Institute, Inc., p ACKNOWLEDGEMENTS With humble pleasure I thank Art Carpenter for giving me the insight and knowledge from which my understanding of the SAS Macro Language is derived. Mike Metts deserves significant credit for his brilliant and artistic style of presenting complex information in simple and intuitive ways - I would not have known the full range of possibilities of the graphics catalog without him. Lastly, I am grateful to IBM Corporation and Hitachi Global Storage Technology for providing the tools and opportunity which made this work possible.

5 TRADEMARK CITATION SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute, Inc. in the USA and other countries. indicates USA registration. Other brand and product names are registered trademarks or trademarks of their respective companies. CONTACT INFORMATION Your comments and questions are valued and encouraged. Contact the author at: Paul D Sherman 310 Elan Village Lane, Apt. 117 San Jose CA Phone: sherman@idiom.com SOURCE CODE options nosource; /* ========================================= */ /* INVOKE - Dynamic Macro Invocation Utility */ /* Repeatedly calls a desired macro using an */ /* equal size subset of number appended base */ /* name positional parameter arguments. */ /* Example: */ /* %invoke(foo, item, 12, 3); */ /* will produce */ /* %foo(item, ite1, ite2); */ /* %foo(ite3, ite4, ite5); */ /* %foo(ite6, ite7, ite8); */ /* Options: */ /* SHOWZERO= whether to show index number 0 */ /* SAMESIZE= keep each parm name same length*/ /* PASSTHRU= literal positional parm */ /* OUTNAME= number suffixed positional parm */ /* /19/2003 pds -Initial cut */ /* ========================================= */ %macro invoke(mname, base, num, step=4, SHOWZERO=false, SAMESIZE=true, PASSTHRU=., OUTNAME=.); %local args name i j n; %do i=0 %to %eval(&num. - 1) %by %step.; %let args = %str(); %do j=0; %to %eval(%step. - 1); %* append the item number... *; %let n = %eval(&i. + &j.); %if %lower(&showzero.) eq true %then %do; %if %lower(&samesize.) eq true %then %do; %let name = %trim(%qsubstr(&base., 1, %length(&base.) - %length(&n.))); %let name = &name.%left(%trim(&n.)); %else %if &n. eq 0 %then %do; %* default SAS doesnt suffix first item with numeric zero *; %let name = &base.; %else %do; %if %lower(&samesize.) eq true %then %do; %let name = %trim(%qsubstr(&base., 1, %length(&base.) - %length(&n.))); %let name = &name.%left(%trim(&n.)); %*... accumulate the arg list... *; %let args = &args.&name.;

6 %*... provide the parm delimeter... *; %if &j. lt %eval(&step. - 1) %then %do; %let args = &args.,; %*... prepend index numbered outname first if present... *; %if &OUTNAME. ne. %then %do; %if %lower(&showzero.) eq true %then; %do; %let args = &OUTNAME.%left(%trim(&i.)),&args.; %else %if &i. eq 0 %then %do; %let args = &OUTNAME.,&args.; %else %do; %let args = &OUTNAME.%left(%trim(&i.)),&args.; %*... then the literal pass through stuff *; %if &PASSTHRU. ne. %then %do; %let args = &PASSTHRU.,&args.; %&mname.(&args.); /* =============================== */ /* amacro - typical macro template */ /* =============================== */ %macro amacro(uvar, oname, one, two, three); %put amacro is processing &one., &two. and &three. for SUGI-&uvar. and creating &oname..htm; /* ================================== */ /* main - typical program entry point */ /* ================================== */ %macro main(args); %local basename nsugi nparms nstats; %* show Contrib, Invited and SAS papers for each SUGI section *; %let basename = Sugi ; %let nstats = 3; %put.; %put Long Beach, CA; %let nsugi = 26; %let nparms = 6; %invoke(amacro, &basename.&nsugi., &nparms., &nstats., OUTNAME=sugi, PASSTHRU=&nSugi.); %put.; %put Orlando, FL; %let nsugi = 27; %let nparms = 9; %invoke(amacro, &basename.&nsugi., &nparms., &nstats., OUTNAME=sugi, PASSTHRU=&nSugi.); %put.; %put Seattle, WA; %let nsugi = 28; %let nparms = 8; %invoke(amacro, &basename.&nsugi., &nparms., &nstats., OUTNAME=sugi, PASSTHRU=&nSugi.); %put.; %put Montreal, ON; %let nsugi = 29; %let nparms = 10; %invoke(amacro, &basename.&nsugi., &nparms., &nstats., OUTNAME=sugi, PASSTHRU=&nSugi.);

7 /* program execution starts here */ options nonotes noovp nomerror nomprint nomlogic nosymbolgen errors=max msymtab=max mvarsize=max mautosource mrecall sasautos=(sasautos) linesize=256 pagesize=1000 nocenter nodate yearcutoff=1920 cleanup serror nostimer dsnferr ; main(); EXAMPLE LOG. Long Beach, CA amacro is processing Sugi, Sugi 1 and Sugi 2 for SUGI-26 and creating sugi26.htm amacro is processing Sugi 3, Sugi 4 and Sugi 5 for SUGI-26 and creating sugi26.htm amacro is processing... amacro is processing Sugi_15, Sugi_16 and Sugi_17 for SUGI-26 and creating sugi26.htm. Orlando, FL amacro is processing Sugi, Sugi 1 and Sugi 2 for SUGI-27 and creating sugi27.htm amacro is processing Sugi 3, Sugi 4 and Sugi 5 for SUGI-27 and creating sugi27.htm amacro is processing... amacro is processing Sugi_24, Sugi_25 and Sugi_26 for SUGI-27 and creating sugi27.htm. Seattle, WA amacro is processing Sugi, Sugi 1 and Sugi 2 for SUGI-28 and creating sugi28.htm amacro is processing Sugi 3, Sugi 4 and Sugi 5 for SUGI-28 and creating sugi28.htm amacro is processing... amacro is processing Sugi_21, Sugi_22 and Sugi_23 for SUGI-28 and creating sugi28.htm. Montreal, ON amacro is processing Sugi, Sugi 1 and Sugi 2 for SUGI-29 and creating sugi29.htm amacro is processing Sugi 3, Sugi 4 and Sugi 5 for SUGI-29 and creating sugi29.htm amacro is processing... amacro is processing Sugi_27, Sugi_28 and Sugi_29 for SUGI-29 and creating sugi29.htm

8 EXAMPLE TEMPLATE day3by2 /* ====================================== */ /* DAY3BY2 - Weekly 3 across, 2 down */ /* Creates template DAY3BY2 in the */ /* TEMPLT catalog of library SUGI29 */ /* Layout: */ /* */ /* */ /* one two three */ /* */ /* */ /* four five six */ /* */ /* */ /* Coordinates: */ /* Panel L-left U-left U-right L-right */ /* 1 x: */ /* y: */ /* 2 x: */ /* y: */ /* 3 x: */ /* y: */ /* 4 x: */ /* y: */ /* 5 x: */ /* y: */ /* 6 x: */ /* y: */ /* ====================================== */ proc greplay nofs tc=sugi29.templt; tdef day3x2 des='weekly 3 across, 2 down' 1 / llx=0.0 ulx=0.0 urx=33.0 lrx=33.0 lly=50.0 uly=100.0 ury=100.0 lry= / llx=33.0 ulx=33.0 urx=66.0 lrx=66.0 lly=50.0 uly=100.0 ury=100.0 lry= / llx=66.0 ulx=66.0 urx=99.0 lrx=99.0 lly=50.0 uly=100.0 ury=100.0 lry= / llx=0.0 ulx=0.0 urx=33.0 lrx=33.0 lly=0.0 uly=50.0 ury=50.0 lry=0.0 5 / llx=33.0 ulx=33.0 urx=66.0 lrx=66.0 lly=0.0 uly=50.0 ury=50.0 lry=0.0 6 / llx=66.0 ulx=66.0 urx=99.0 lrx=99.0 lly=0.0 uly=50.0 ury=50.0 lry=0.0 ; run; quit;