This article explores several features of IBM’s Rational Developer for System z applied to the problem space and value of “code reuse”

By Chris Leland, Royal Cyber

There have been many, many, many, many attempts throughout the history of software development to provide frameworks, languages, and tools that assist programmers in building applications from reusable parts – usually tested/production-ready code.  Reuse is a linchpin of Object Orientation  (the Inheritance construct) – and it’s hard in theory to argue against it.  So we won’t.

However, COBOL/Assembler/PL1  aren’t – in general practice O-O languages.  Please, please, please don’t drag O-O COBOL onto the dance floor.  We’ve tangoed with it– and when you get up close … when you actually study an O-O COBOL program?  It resembles an off-label Botox treatment, applied to an aging Hollywood actor.

Anyway… so, if no Inheritance, then what’s the value of code reuse?   Actually two things?  1. Common code functionality and 2. complex “plumbing” functionality.  We’re betting that both of these are currently implemented in your production systems via COPY or INCLUDE statements – with some “advanced reuse” provided by “COPY REPLACING”.  These are effective, traditional options that; save time, cut down on systems-development errors (both build and run-time errors) and standardize your code base.

There’s an unofficial but common 3^rd option for code reuse which is the ISPF command line COPY <External Source File>  command.  Often developers utilize command line copy to snare fragments, bits of code – even sometimes entire program or file skeletons.  This practice is widespread, but would be enhanced by more copy-into flexibility (i.e. the means to implement the paste operation substituting strings or variable values).  It’s also done at a block level – in other words line(s) at a time are copied into your program – you can’t copy within a statement.   It is this ISPF command line COPY functionality that RDz’s reusable code features most resembles.  Except the two options (Snippets and Templates) surmount the limitations of ISPF’s command line COPY.

 

Code Snippets

Code Snippets are fragments of code, typically in some programming language (COBOL, PL/I, Assembler, JCL, CLIST, REXX, C/C++, Java, SQL, MFS, CA-Ezytrieve, SAS,  etc.)  that are inserted into a file.  The file would most likely be a program – ostensibly the same language as the Snippet – but there are relatively few exceptions / limitations to Code Snippet use.  So in theory you could use Snippets as building blocks for virtually any plain-text z/OS software resource.

You create a snippet by:

1. Copying a select of code
2. Right-clicking over the appropriate “palette/drawer” in the Snippets view (see Figure 1)
3. And selecting Paste as Snippet…

In the COBOL/PL1 Editors an “Add to Snippets…” option exists off of the Context Menu – within edit.

The use or consumption of an existing Snippet is just as straightforward.

From within an LPEX, COBOL or PL/I editor session:

1. Place your cursor at the exact focal point (position in the source) where you want a code snippet inserted;

• This includes at the beginning of a line or anywhere  inside the line or statement.

2. Locate the Code Snippet within the Snippets view, and inside the Snippet palette/drawer (see Figure 1)
3. Double-Click the Snippet

Figure 1 – Snippet Palette/Drawers within the Snippets View – and setting the Snippet insertion point

The code in the Snippet will be added into your file at the insertion point (see Figure 1) – either verbatim, or if there are variables in the Snippet you can:

4   Accept default values for the variable

4   Over-ride the values before the code is inserted

 

What are these Snippet Variables?

Snippet Variables are placeholders in the Snippet artifact where the user is prompted for a value, which is substituted into the Snippet at a defined location.  From Figure 2 you can see that there’s a JCL Job Card Snippet which contains a standard z/OS JOB statement.  The Snippet developer has built two variables into the Snippet: JobName and MsgClass.  When the user opens a JCL file, inserts his cursor on top (blank) line in the file and double-clicks the JobCard Snippet, the Snippet code will be inserted into the JCL. But first the user is prompted for JobName and MsgClass.  Whatever the user enters into the values table for JobName and MsgClass will be added into the final Snippet code (again, see Figure 2).  So it’s this “variables” feature of RDz’s Snippets that provides more flexibility,  functionality and in general more choices and options for reuse.  A technical (best practice) note that if your snippet begins with a new line of code, begin your snippet with a blank line. This ensures that the inserted code begins at the correct column position.

Figure 2 – Variables substituted for JobName and MsgClass in a JCL Code Snippet

Code Templates in RDz

An alternative to Snippets are RDz “Code Templates”.  Code Templates are pieces of reusable code that are defined in RDz’s Preferences as shown in Figure 3 – RDz’s COBOL Templates).

Code Templates are (to a degree) language sensitive, and available for; Assembler, PL/I, JCL, COBOL, and SQL.  They can be used for small/granular development components such as single statements or keywords (that’s what’s shipped with RDz).

Or Code Templates could potentially be defined for:

• COBOL,
  • Statement combinations and common code – such as logging, audit or ABEND routines
  • Paragraphs/sections
  • Embedded SQL Cursor routines
  •  Entire programs

• Template functionality is also shipped for other RDz-supported language elements, features and structures:
  • PL/1
  • Assembler
  • SQL
  • Java
  • C/C++
  • JCL – JCL keywords are shipped with RDz, but you can add to the JCL functionality by creating Templates for:
    • Jobcard
    • Parms
    • Common DD cards
    • MVS Utilities
    • Etc.

By “language sensitive” what I mean is that the RDz tooling provides Context (see Figure 3) for the definition of Templates.  And what this (“context”) means is that you can specify that certain Templates will only be proposed in certain contexts; SQL code within embedded EXEC SQL statements, procedural statements in the PROCEDURE DIVISION, etc.

Figure 3 – RDz’s default COBOL Code Templates – defined in Preferences/shipped with the product

 

Using Code Templates

To use an existing Code Template you press the “Content Assist” hot-key combination (Ctrl+Spacebar) from inside of an RDz edit session (see Figures 4a, 4b and 4c).  This process works as follows:

1. Place your cursor (focal-point) in the code where you wish to use a Code Template
2. Press Ctrl+Spacebar – a list of proposals valid within  your coding context pops up (see Figures 4a, 4b and 4c)
3. Scroll through the list to find the Template you want.  Mouse-over to get any Comments that were added into the Template
4. Double-click to select and insert the Template code into your source file

Figure 4a – Inserting a COBOL PROCEDURE DIVISION statement from a Code Template

Figure 4b – Inserting an entire IEBCOPY Utility from a JCL Code Template

Figure 4c – Adding an Open Sysprint statement from a PL/I Code Template

 

Defining Code Templates

Figure 3 shows some of the default Templates in COBOL for RDz v9.0.1.  You can modify the default Code Templates; selecting and deleting ones you don’t like, editing/saving/modifying existing Templates.  And you can extend/augment and modify the list as follows:

• From Window > Preferences,   expand COBOL >
• Select Templates and click New…
• From New Template specify Template name, Context, (optional) Description and code Pattern
• Click OK – and your new code Template is ready to activate using Ctrl+Spacebar

 

Variables in Code Templates

You may notice that there are Variables available to insert into RDz Code Templates.  For the most part, these variables are not flexible/open-ended like those in RDz’s Code Snippets, so we rarely see them used.

However, there is one really nice variables option; cursor – which forces a cursor stop/point wherever you place it.  This stop/point allows you to press subsequent Ctrl+Spacebar actions, to bring program variables/paragraphs/section names/etc. into the Template-completed statement or pattern.

Figure 5 – Define a new COBOL PROCEDURE DIVISION Template

 

Managing and Administering Code Snippets and Code Templates

Both Code Snippets and Code Templates are Workspace-managed artifacts (they existing inside of the RDz Workspace you launch the product with).

Both Snippets and Templates can be shared among developer/development teams through standard Eclipse Export/Import actions.  The unit of Code Snippet Export/Import is the palette/drawer and the unit of Code Template Export/Import is the number of selected Templates in the Preferences dialog (you can select multiple Templates for Export by holding the Ctrl or Shift key).

However, Code Templates further allows you to manage/administer Code Templates using RDz’s “Push-to-Client” technology.  This feature provides z/OS LPAR-hosted (single-site) management of updates to RDz dependent artifacts; Workspaces and Workspace components such as Templates other Preferences, etc.

Best Practices dictate that a few dedicated developers setup and manage Snippet/Template content in a hierarchical distribution fashion for maximum ROI results – something like the design shown in Figure 6.

Figure 6 – Hierarchical Snippet/Template Model/Design

 

Our Take … Code Snippets vs. Templates

Whether you should use Snippets or Templates is largely a matter of development culture – and how you expose users to these powerful options via training.  It should be noted that Code Snippets and Templates are not incompatible (see Table 1).  You can use both in your RDz development environment – and some shops do just that.

The same shops/teams/individuals that don’t utilize ISPF command line COPY, probably won’t use Snippets or Templates.  But if you find value in / or use ISPF COPY consider taking a look at RDz Snippets and Templates.

Royal Cyber maintains robust, organized collections of both custom Snippets and Templates for our own in-house development engagements.  You can obtain a copy of them (they’re free!)  by contacting us:  http://royalcyber.com/contact-information/

Table 1 – Snippets vs. Templates Functional Comparison

 

Next steps…

RDz is one of the primary strengths of Royal Cyber.  In 2014 IBM chose Royal Cyber to manage its RDz “Distance Learning” program – out of all the RDz business partners world-wide.  We offer deep and quality service engagements in every phase or RDz – from Installation and Deployment, to Training/Mentoring and adoption, to administering and supporting both the RDz client and server – and finally, to evaluating your RDz Adoption and Return-on-Investment.

• For details on the Royal Cyber RDz Rollout and project/task usage modeling contact us: inquires@royalcyber.com
• To sign up for Royal Cyber RDz Free Distance Learning: http://royalcyber.com/royal-cyber-rdz-distance-learning-training-schedule/
• To get a copy of the January 2014 Newsletter  – including additional deep-dive articles on RDz and RAAi: http://royalcyber.org/mn/index.html

 

Chris Leland; Chris is Royal Cyber’s primary RDz technical instructor – having worked full-time with RDz for almost four years; developing applications in COBOL, teaching RDz classes and mentoring in COBOL and Assembler, installing and configuring RDz, delivering custom workspace design sessions, writing an RDz evaluation exam, and integrating RDz with Rational Asset Analyzer.  Chris passed the IBM/RDz Certification exam with flying colors in 2011.