technical: Why You Should Use Eyecatchers

If you look around the web, you'll see lots of articles and blogs with ideas on how to improve the resilience of your program. Indeed, you may find a couple of these on the Longpela Expertise website. But there's one technique that isn't really talked about, but can help in making programs more resilience, and debugging of errors easier. Eyecatchers. COBOL COPYRIGHT Have you ever used the COBOL COPYRIGHT compile option? Introduced in Enterprise COBOL 5.2, you can use it to insert a string of text into a program object. For example, suppose we start our COBOL code with:

CBL COPYRIGHT('LongExp Program1 Version 2.1 24-Mar-2021')
Identification Division.
Program-ID. DZSCICS.

If we browse the final program object after compiling, we will see something like:

BROWSE    DZS.LOAD.PDSE(DZSCICS)              Line 0000000000 Col 03536
Command ===>                                               Scroll ===> CSR
********************************* Top of Data ****************************
..........................................................................
...LongExp Program1 Version 2.1 24-Mar-2021..20210224014349060300...È..è..
.ì0C8ì00Ø..IGZXCMSG......ì0C8ì00...IGZXPRS ......å00..CEE...½...ðå00..¤x4.
..........................................................................
..........................................................................
.....Ø.......................................LDLDM.............Ø.....Ø....
....)Ø.......Ø..................@...u...@............LDLDM.............Ø..
.......Ø....¦Ø...Ø...Ø......................^................ERERL........
390  .....................................................................
...Ø......è....................Ø...Ø...Ø......ø............ .......Ø...Ø..
....s...................Ý.}....".........SYSLIB  ...Þ.......s.............
....á...Ö...................\L......ã...Ö....................L......å...Ì.
À...[.......................\SØ.À...¯........................SØ.À...´.....
..........................................................................
******************************** Bottom of Data **************************

The string we passed to the COPYRIGHT option appears in the program object. Or in other words, we've inserted an 'eyecatcher'. From the name of the option, it seems obvious that it was intended for software developers to be able to insert a copyright statement in their program object. But in our example, we've specified:

This can be really handy when debugging a problem. If we get strange results, we can take a dump, and confirm the version of the program we are using. This isn't limited to COBOL. For example, Enterprise PL/I also has a COPYRIGHT compiler option. In C and C++, the following pragma statement example can do the same thing:

#pragma comment(copyright,' LongExp Program1 v2.1 24-Mar-2021')

Assembler programmers have been doing this for years. They can use data constants, with a branch around it. For example:

DZSPGM1  CSECT
DZSPGM1  DS    0H
         USING *,R15 
         B     @PROLOG    Branch around eyecatcher
         DC    AL1(22)    Length of our eyecatcher
         DC    C'DZSPGM1 v2.1 &SYSDATC' Eyecatcher itself
         DROP  R15
@PROLOG  STM   R14,R12,12(R13)

We use the &SYSDATC to automatically put in the date the program was assembled. It's also good practice to include the length of the eyecatcher: this can help z/OS include eyecatcher information in formatted dumps.

In fact, this is so common for assembler programmers, that the SAVE macro that IBM has published to help in beginning assembler programmers includes parameters for eyecatchers. So, we could code:

DZSPGM1  CSECT                                              
DZSPGM1  DS    0H           
         USING *,R15 
         LA    R13,SAVEAREA
         SAVE  (R14,R12),,'DZSPGM1 v2.1 &SYSDATC'

Specifying basic program information (name, version, date compiled) is a very easy thing to do, which can make debugging far easier. But that's not all that eyecatchers can do.

Data Areas

Some assembler programmers will use an eyecatcher at the beginning and end of any work areas or storage used. For example:

WORKAREA  DS   0H
          DC   C'WORKAREA BEGIN**'
W-SAVE    DS   18F
W-WORD1   DS   F
          DC   C'WORKAREA END****'

Now, when they look at a dump,they can clearly see where their data area starts and ends. This can also be done for COBOL working and local storage:

       Data Division.                        
       Working-Storage Section.
       01 Filler           Pic X(16) Value'WORKAREA BEGIN**'.
             
       01 WS-TIME          Pic S9(15) Comp-3.
       01 WS-I             Pic S9(8).        
       01 WS-J             Pic S9(8).     

       01 Filler           Pic X(16) Value'WORKAREA END****'.

Other programming languages can provide similar results.

Control Blocks

A long time ago, we wrote an article introducing control blocks. These are areas in memory that hold information that we may want to see or use. IBM publish the formats of some control blocks to help us understand what they do, and why.

Let's look at a what IBM provide for one common control block: the Address Space Control Block (ASCB):

The control block has an eyecatcher. At offset 0 (i.e., right at the beginning) we would expect the four characters 'ASCB'. This is really handy when working with control blocks. If we have a program that is looking at an ASCB, and think there is an ASCB at address x'FB107745', we can look at the first four characters. If they are 'ASCB', then there's a good chance that this is indeed an ASCB.

Many IBM control blocks have eyecatchers. Not only can we check eyecatchers in a program, we can also check them in a dump. This makes problem diagnosis a lot easier.

Commareas

When putting a message onto an IBM MQ queue, we need to specify a data area with information and options about the message: the message descriptor (MQMD). This must be a specific format that IBM documents. The first field in the MQMD is a two-byte field called the structure identifier. This must be the characters 'MD': an eyecatcher. This field is followed by the version field: specifying the version of the MQMD (more recent version of IBM MQ have added fields).

And this is the same with all IBM MQ data areas; each has an identifier and version. And this is great. If you accidentally provide an MQMD where another field should be, MQ will tell you, rather than try process the incorrect data.

This is an invaluable way of improving the resilience of applications. Ideally, every COMMAREA or parameter area should include eyecatchers. The sending program must specify them, the receiving program must check them.

A lot of program products use eyecatchers in this way: confirming that the data passed to it is in the right format (and possibly version).

Other Uses

Eyecatchers certainly aren't new. But you may be surprised at how often they're already used. For example, if you look in an XML document, the first line will look something like:

<?xml version="1.0"?>

It identifies the document as XML, and the version of the XML standard that it follows. Similarly, for HTML:

<!DOCTYPE html>

How about PDFs? The first characters may well look something like:

%PDF-1.4

In this case, a PDF version 1.4 document.

How about JSON documents? Unlike HTML and XML, there's no requirement to code anything. But it wouldn't take much to include something like:

{
  "identifier": {
    "type": "App1Request",
    "version": "2.1"
  }
…

Not only can we check this in our receiving program, we can also dump out JSON messages and know quickly the purpose of that message.

Conclusion

When programming, the aim should be to produce fault-tolerant, resilience code. Using eyecatchers to identify program source and data areas, as well as for specifying and confirming incoming message, file, JSON, MQ or commarea formats, will got a long way to achieving this.

David Stephens

LongEx Quarterly is a quarterly eZine produced by Longpela Expertise. It provides Mainframe articles for management and technical experts. It is published every November, February, May and August.

The opinions in this article are solely those of the author, and do not necessarily represent the opinions of any other person or organisation. All trademarks, trade names, service marks and logos referenced in these articles belong to their respective companies.

Although Longpela Expertise may be paid by organisations reprinting our articles, all articles are independent. Longpela Expertise has not been paid money by any vendor or company to write any articles appearing in our e-zine.