LongEx Mainframe Quarterly - November 2021
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 AreasSome 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 BlocksA 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. CommareasWhen 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 UsesEyecatchers 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. ConclusionWhen 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. |
