Decisions, Decisions: Templates Or Snippets?

July 30, 2014 Susan Gantner

All you RSE (a.k.a., RDi, RDP, WDSC) users out there: Do you prefer templates or snippets?

For some of you, the response may be “What’s a Template?” Or “What’s a Snippet?” For those readers, I’ll direct you to first learn more about the basics of both topics via earlier tips from Paul Tuohy, when he wrote about creating templates and creating snippets. If your answer to my original question about templates vs. snippets is “Yes” (meaning you like both), perhaps you don’t need to read the rest of this tip.

As with several capabilities of the Rational toolset, these are two features that serve a very similar purpose. Both allow you to store a (usually) small piece of code that can be easily inserted into a new or enhanced program at any time with a few keystrokes. Both can be big time savers to avoid either re-coding the same stuff over and over again or searching for another program that has the same code in it so you can copy it (yet again.) They can also go a long way to making standardization easer–using exactly the same code in many situations.

But it begs the question: “Are templates or snippets better?” As you may have already guessed by my earlier comments, I find both very useful. Each has its own unique capabilities that can give it an edge in a specific situation.

First, let’s look at the differences between them.

The primary benefit of templates, in my view anyway, is that they are more “built in” to the editor. That is, I don’t need to find and interact with a separate view while “in the flow” of my coding to insert the logic of a template. I can simply do Control, Space, and Page Down (or begin keying the name of my template) to get to it directly from the editor. After selecting the template from the list, my cursor will be positioned to the first location where specific code is required to customize the use of the template.

The big deficiency of templates? They only work with free-format code. For logic, that’s probably no big hardship these days, since in my experience, most developers who are modern enough to use RSE are also modern enough to code at least their new logic in free-format. But what if the code I want to insert includes F, D, or P specs? Well, in that case, I can use snippets. Of course, the recent availability of free-format D, F, and P specs means this limitation is alleviated to a great extent, at least once you are running at least V7.1.

The other primary benefit of snippets is the ability to contain and be used within fixed-format code, particularly F, D, or P specs. But there is another benefit of snippets that still holds even after 7.1. Snippets have substitution variables. So if the bit of code you want to insert could benefit from one or more details that can be supplied via filling in variable values, then snippets may still be the way to go, even after you go completely free format with your logic.

Maybe a couple of examples would be help to illustrate what I mean.

One example of a template that I sometimes use is one that checks the value of SQLSTATE (or alternatively SQLCODE). In this case, there are no places where replacement variables are necessary. However, placement of the cursor (which templates allow) is very useful. I have a group of templates I use for different circumstances with SQL, but one of the simpler ones looks like this:

Select;
   when %SubSt(SQLState:1:2) >= '03';
       ${CURSOR}// Error
   when %SubSt(SQLState:1:2) = '02';
      // No More Rows
   when %SubSt(SQLState:1:2) = '01';
      // Warning
   other;
      // Process Row
EndSL;

An example of where a snippet best meets my needs is my standard trigger program skeleton. I originally created this as a snippet because it required D specs, which were still fixed-format at the time. But even now that I can convert my D specs to free-format and include them in templates, I still believe this particular bit of code is best utilized as a snippet because there are several places where I can make good use of substitution variables. So when the template is inserted, I am first prompted to supply values for the name of the trigger program, the file “being triggered” and the number of fields in the file. For each substitution variable, you also have the option of supplying a default value. So my trigger skeleton snippet looks like this (substitution variables are in red):

Dcl-Pi ${TriggerPgmName} ExtPgm('${TriggerPgmName}');
  TrgBuffer              LikeDS(TrgBuffer_T);
  TrgBufferLen Int(10);
End-Pi;

Dcl-Ds TrgBuffer_T      Template;
        TFileName    Char(10);
        TLibraryName Char(10);
        TMemberName  Char(10);
        TEvent       Char(1);
        TTime        Char(1);
        TCommitLock  Char(1);
        *N           Char(3);
        TCCSID       Int(10);
        TRRN         Int(10);
        *N           Int(10);
        TOldOffset   Int(10);
        TOldLength   Int(10);
        TOldNullOff  Int(10);
        TOldNullLen  Int(10);
        TNewOffset   Int(10);
        TNewLength   Int(10);
        TNewNullOff  Int(10);
        TNewNullLen  Int(10);
End-Ds;

// Before and After Record Images

Dcl-Ds OldImage     ExtName('${TriggerOnFile}')
                    Based(OldImgPtr)
                    Qualified;
End-Ds;

Dcl-Ds NewImage     ExtName('${TriggerOnFile}')
                    Based(NewImgPtr);
End-Ds;

// The OldNullMap and the NewNullMap DSs may be omitted if you have
// no null-capable fields in your record format

Dcl-Ds OldNullMap       Based(OldNullPtr);
  ONField Char(1)       DIM(Fields);
End-Ds;

Dcl-Ds NewNullMap       Based(NewNullPtr);
  NNField Char(1)       DIM(Fields);
End-Ds;

// The "Fields" constant value is set to the number of columns
// in the record format - This variable may be omitted if you have
// no null-capable columns in your record format

Dcl-C Fields ${NumFields};

// Map Ext DS to Trigger Buffer using Pointers

OldImgPtr = %ADDR(TrgBuffer) + TrgBuffer.TOldOffSet;
NewImgPtr = %ADDR(TrgBuffer) + TrgBuffer.TnewOffSet;

OldNullPtr = %ADDR(TrgBuffer) + TrgBuffer.TOldNullOff;
NewNullPtr = %ADDR(TrgBuffer) + TrgBuffer.TNewNullOff;

// Logic can refer to any field name in the table (file)
// The updated values use the regular column (field) name
// The old (before) values use the column name qualified by OldImage.
//  e.g., If column name = MYFIELD, before image = OldImage.MYFIELD

*INLR = *On;

So which is better: Templates or snippets? The answer, as in so many other cases, is “it depends.” I have some code that is in both forms, just in case!

Susan Gantner is half of Partner400, a consulting company focused on education on modern programming and database techniques and tools on the IBM i platform. She is also a founding partner in System i Developer, a consortium of System i educators and hosts of the RPG & DB2 Summit conferences. Susan was a programmer for corporations in Atlanta, Georgia, before joining IBM. During her IBM career, she worked in both the Rochester and Toronto labs, providing technical support and education for application developers. Susan left IBM in 1999 to devote more time to teaching and consulting. Together with Jon Paris, she now runs Partner400, and appears regularly at many technical conferences, including System i Developer’s RPG & DB2 Summit. Send your questions or comments for Susan to Ted Holt via the IT Jungle Contact page.