COBOL Snippets

Beginning with this article all projects will be created using the Micro Focus Visual COBOL environment. 

Beginning with this article all articles that will contain coding examples will now be created using the Micro Focus Visual COBOL environment. Visual COBOL is a significant leap forward technically for integration within the Microsoft .NET environment and is targeted specifically for .NET. It is a part of the Visual Studio 2010 environment, the latest release from Microsoft. 

In this article I'd like to show you a time-saving technique that we as COBOL programmers have been doing for a long, long time. It's the concept of code libraries or having little pieces of code available in our toolboxes that we use over and over again. It can be anything from a simple date calculation to a read or compute statement. Anything we may have accumulated over the years and saved because we know at some point in time we'll use it again. In the Microsoft environment these little pieces of code are called 'snippets' and there is a process within Visual Studio that helps you create them, save them and even reuse them with a few simple mouse clicks. You can even share them within your development team or company so everyone can use them. The huge advantage here? Consistency in coding and technique to help ensure standards are defined and maintained. 

We'll go through the process of creating a new project, adding a new item (our snippet) to the project, updating the snippet and finally registering the snippet with the snippet manager (yep, Microsoft even has a manager for them!). 

We'll start with creating a new project. It can be any type of project you'd like, I used a managed Windows Form. Snippets can be used in both a managed and native environment. I chose the managed version for the article.

Let's begin then shall we?

Create a new Project

Create a new project in Visual Studio 2010. I called the solution and project 'Snippets'. In this way I have one solution for all my snippets and can keep adding new snippets as I require them. When you have created your project your screen should look like the following.




Add a new Item

The first step in our journey is to add a new item to the project. We're going to add a new XML file and to do that we select the project file, right mouse click and select 'Add' then 'New Item'.



When the screen below appears, select the 'XML File'. I'm going to create a snippet to read the next record in a file so I'm going to name it 'READNEXT'. I am also going to update the extension from 'XML' to 'snippet'. The 'snippet' extension is used to tell Visual Studio this is a special type of source code as well as to enable different functionality within Visual Studio.



After you have updated the Name field click the 'Add' button and you'll be returned to the Visual Studio screen with your new snippet opened and ready for editing.



Insert a snippet template

Remember the idea behind snippets is to save time and to that end Micro Focus has included a snippet template that provides the basic layout of a snippet with updateable fields for you to enter in your updates. To access that template do the following, in the editor window of your snippet, right click. Notice the first entry in the context menu? Select the 'Insert Snippet' entry.



The screen will change to show you are inserting a snippet and the available snippets will be displayed. While our display is rather short, imagine if you've been working with snippets for a while and a rather lengthy list appeared? You could have math calculations, file access routines, core business logic, the list is endless. For our example we're going to insert a basic snippet. If you select the entry snippet (single left mouse click) a tooltip help will appear showing a basic description of what this snippet is intended for. Double clicking on the 'snippet' entry will insert the code into your file. Double click on the 'snippet' entry now.



The following code is inserted into your snippet and the first entry field is highlighted. We are going to update the fields in the template next.



Modify the Snippet template



I've modified the template fields for Title, Author, Shortcut and Description. These are all pretty self-explanatory and I won't go into further detail only to mention to be very careful when modifying the XML template. XML is tag driven with an entry and exit (or closing) tag to denote information. Be very careful not to delete or in any way change or update the tags or you'll be spending quite a bit of time looking for errors in your code.

I've also updated the first field in the 'Literal' area of the template, defining the variable 'File' to the routine. This field will be used to prompt the user to enter in the file name of the file to be accessed. I need to prompt for another field though and that is the storage variable of where to place the data when I read in the record. To do that I position my cursor at the end of the </Literal> tag and press enter. Next I begin entering in a new tag definition by keying in '<'. Notice a context menu appear? The wonderful people at Microsoft have provided context sensitive menus that contain the tags associated with the area or level you are working at. For our exercise we need to select the 'Literal' value from the list and click 'Enter'. When you do the proper entry and exit tags are inserted in the source line and your cursor is positioned for update. Update your snippet to contain the following information:



There is an update we have to make to the template and that is highlighter below.



We need to update the language to enable the snippet to work in the Micro Focus environment. This is done by changing the value in quotes from "XML" to "Cobol".

Finally we need to create the actual line of code that will be inserted into a program whenever we use the snippet. The field "CDATA" contains the line of source code, if you notice though it isn't quite right. The statement we are working to create is "READ {filename} NEXT RECORD INTO {ws-variable} END-READ". To create our READ statement within the CDATA area, select the area between the inside square brackets and begin entering in the line of code. When you get to the filename area you have to use the literal we defined above for the filename and that is 'FILE'. To properly specify the variable we 'wrap it' in dollar signs ($) so that our statement becomes:

READ $FILE$ NEXT RECORD INTO $IDENT1$ END-READ

and should appear as below in your snippet.




I've become accustomed to using lower-case in my coding but you can use whatever case you'd like, as long as you're consistent. Once we have created and saved our snippet we need to register it with the Manager.

Register the new Snippet

From the Menu bar, select Tools -> Code Snippets Manager as shown



The following screen will appear. This is the Snippets Manager and will show you all the snippets, by language, that you have access to. Notice there is already a library of COBOL snippets provided for you. This is from Micro Focus and will be updated as more snippets are created.



You can either Add a new snippet location or import snippets into an existing location. I'm going to 'Add' a new location since I want to keep my snippets separate at this time. Click the 'Add' button and the following screen appears.



Navigate to the folder where your snippet is. In my example I created the project in the "C:\Temp\Snippet" folder so I navigated to that folder. Once I selected the folder I clicked the 'Select Folder' button. The manager identifies any snippets in the folder and adds them to the display, which is refreshed and displayed as below.



Using the new Snippet

Remember when we began, how we created our new snippet from a snippet template? Well to use our new snippet we do the same thing, we position our cursor in the module we are going to update (I inserted my code on a new line so I pressed 'Enter'), right mouse-click and select 'Insert Snippet'. This time when I do that there is a new entry in my list, Snippet.



Select the Snippet entry and the following screen is displayed.



Notice if I single click on Read Sequential a tooltip help appears telling me what the snippet is intended to accomplish. This is from the Description tag we updated in our snippet. Double click on READNEXT and the code is inserted into your program at the cursor location. Did you see the first variable is highlighted and waiting for you to update it? To move to the next field after you've updated the FileName entry, press the TAB key.



Summary

Snippets are an easy to use tool within Visual Studio. They enable a company to create standardized code for many different tasks and because it's managed by Visual Studio and Team Foundation Server, you can also add it to your source code repository and have versioning control so hopefully you won't lose an important piece of code. Work with snippets, experiment with them and adapt this technique to your repertoire. You'll find you can save a lot of time over the long haul by using them. And the best thing… it's all included in Visual Studio by default, no additional products to buy!

If you come up with useful snippets and would like to share them please feel free to send them to me. We're in the process of identifying a location to post the snippets and will publish them and any snippets provided, along with author recognition.
Happy Coding!