CICS User Group | July 2025
Understanding Transaction Debugging for CICS COBOL Programs
This presentation will cover a Transaction Abend resulting in an ASRA abend code issued by CICS.
It will discuss the layout and description of the relevant parts of a Transaction Dump and explain the important pieces of information.
It goes on with how to interpret the information and use it to locate the failing statement in the COBOL Program. He will analyse what situations can cause a Program interrupt such as an S0C4 and an S0C7. The statement will be located in the COBOL program and the Working Storage elements in the failing instruction will also be found in the dump. He will cover the 4 items that are needed to locate these data items, such Base, Displacement, Length and Picture clause.
He will then relate this information back to the dump and use the dump information to find these Working Storage areas.
In addition, he will explain the role of a Save Area that every task must follow and how to interrogate a CICS Trace and use this Save Area information to determine how to locate the last time that the Process left the Program. Finally, he will also show how to use the Trace and the Save Area to find any API command in the program and its statement number.
Read the Transcription
[00:00:00] – Amanda Hendley, Host
If we haven’t met, I am managing editor at Planet Mainframe, and I want to welcome you to our virtual user group session today. We’re talking about CICS, C-I-C-S, or whatever flavor you like to put on that. We’re here today with Colin Pearce, who I’ll introduce momentarily.
[00:00:18] – Amanda Hendley, Host
I want to thank our partners, Broadcom and DataKinetics, for their partnership of the event in this series. If you know another company that may want to to partner with us, please let me know. Give them my information. Let them know we should talk.
[00:00:37] – Amanda Hendley, Host
Our agenda is pretty brief. I just did our introduction, and we’re going to move on to our presentation momentarily. Then afterwards, we’ll talk about news and articles and when our next session is. So first, I do want to invite you all to come stop by the booth for Planet Mainframe at SHARE. If you’re going to be there in a few weeks, we will be there. We’re going to have Planet Mainframe Trivia. If you joined us in DC, then you got to compete for gift cards and prizes at Planet Mainframe Trivia. But we will be there doing that on Tuesday and do have some other fun stuff while we’re in town.
[00:01:24] – Amanda Hendley, Host
For today’s session, we’re going to do questions after the presentation, if there’s time, but Colin has been also share his contact information, so you can follow up with anything that you need additional support with. And with that, we’re here for Understanding Transaction Debugging for CICS COBOL programs, I’m going to stop my share so that Colin can start his share and get my introduction. So if you haven’t met Colin Pearce, he’s got 30 years experience as a mainframe systems programmer and has deep expertise in zOS and CICS, particularly within financial institutions. He is a seasoned expert, our seasoned instructor and technical expert, and delivers training worldwide on topics like CICS, transaction, debugging, and COBOL programming. With that, Colin, are you set to go on your share?
[00:02:27] – Colin Pearce, Presenter
Yes, Amanda, I think we’re all good to go. Okay. Yeah.
[00:02:33] – Amanda Hendley, Host
I don’t see your screen up yet, but I’m not sure if it’s just me.
[00:02:38] – Colin Pearce, Presenter
Yeah, no, I haven’t shared anything yet. Okay. I’m just going to introduce myself. Okay. I I see some familiar names here, so it’s nice to see some people that I know very well. So that’s good. Welcome. Good morning, good afternoon, good evening, wherever you are in the world. Nice to Nice to have you here. We’re going to talk about… Debugging transactions within a CICS COBOL environment. I’ve got a nice lab, a nice lab for us to look at. Excuse me. A nice lab for us to look at. Without much ado, let’s get started because when we get to the bugging, there’s so many different types of the bugging that I’ve had to limit what I can teach because we’ve only got probably an hour and a quarter, hour and 20 minutes to show you the way I debug, just to help you understand some of the the intricacies, and also take you a little bit deeper in terms of getting underneath COBOL, getting into some, but not many, some assembler techniques, but not many. Just to give you an idea of what is shown to us and how we can use it. I’m not going to, hopefully, show you things that I can’t, or tell you things that I can’t show you.
[00:04:23] – Colin Pearce, Presenter
We’ll stop a few minutes early. I think we’re going to stop around 10: 00, 5: 00 to 6: 00, BST, and I’ll take any questions then, and I’ll give you my contact details. I know some of you, I can see that, like I today. I know you, so it’s nice to have you here. All right, so let’s get started and let’s do some screen share here. Let me show you what I’ve got for you. If you If you can’t see my screen, then it’s best to probably let me know. The first thing I’m going to do is I’m going to assume that you need to at least understand what we’re looking at here. Some of you may have seen a CICS transaction dump before and so familiar with it. Forgive me if I tell you things that you already know, but I think I’ve got everything I need at my fingertips here. We’ll just see how it goes, and hopefully, we can then show you a few things as we move forward. Firstly, this is a CICS transaction dump, and we’ve got then on the top left-hand side is the Apple ID of CICS. This is essentially we know which region this is what happened in.
[00:06:00] – Colin Pearce, Presenter
If you weren’t sure it’s a CICS transaction dump, then it tells you here. I’m not going to show you absolutely everything here because we’ll be here till over the weekend. I want to just pick out the salient points that I think lead to a resolution. You can see here it says Code=ASRA. Always remember that the middle two characters of an event code tell you who issued the event. In this case, it’s the error handler routine that’s within the application domain, and this is SRP, System Recovery Program. So it’s dealt, it’s handled the event. An ASRA is something that a lot of us, if you haven’t seen it or been involved with it, you’ve probably heard about it. Tells us the name of the transaction here, in this case, BRSJ. Then we’ve got an ID, left and right, which tells us the number of times The read has been brought up since the last cold start, and then the number of events that have happened in this case, too. Then the date and time that it happened. Then we get the symptoms on the left-hand side moving across. Not much to really specify here, but this one is significant because this is the program that CICS determines that we are currently in or that’s currently executing.
[00:07:28] – Colin Pearce, Presenter
In this case, CICSBRSJ is our program. We can see, well, this is the program CICS says we’re in, but it may not be the program that we are in. It could be that if we’ve called a non-CICS subroutine, then CICS would have no idea that we’re in that subroutine. So it’ll still tell us that you’re in this particular program. So until we prove differently, I always believe what I’m told here, until I’m proving differently. And proving differently can be quite straightforward, as we’ll see as we go forward. The CICS release level, this is 6. 1 of CICs. We’ve got here then what we’re going to spend most of the time involved is the PSW and register is at the time of the interrupt. So if we understand the program status word, it actually is quite a neat little what we call a a hardware register. It does a number of things, but it loads the next instruction to be executed while the current instruction is being executed. So it is a very clever piece of hardware, hardware software, you could probably say. And the next line is… It says here it’s the PSW. This is not all the PSW.
[00:08:56] – Colin Pearce, Presenter
The PSW in 31 bit mode is only two words. It’s just that whether you’re looking at a batch dump in zOS, you’re looking at a CICS dump, it always includes these fields afterwards. This is really what we really call system control information. It tells us things like the storage protect key that we are allowed to operate in. It tells us things like whether we’re allowed to do dynamic address translation. It gives us the condition code, whether we’re supervisor state or problem state. It has a number of different functions here. Then this is then the address of the next instruction that would have executed. This can be a little bit difficult to work out, but if you understand that this is actually what we call an active address. And so this is then, remember, we’re in 31-bit mode. So this address also includes the 32-bit. 32nd bit is known primarily as a parity bit. And because it’s an A here, it means then that the 8 bit of this A, which is 1010, what it means is that we’re in 31-bit mode. So if we subtract 8 from this value, obviously A is 10, Bear in mind, you got to be in Hex for this particular discussion.
[00:10:35] – Colin Pearce, Presenter
That leaves us with 2. We don’t take any notice of that left-hand bit, the 32nd bit. We subtract 8 from A here. If this was a B, we would subtract 8 from B and we get a 3. In this case, we’ve got a 234005DA. This is the instruction that has been loaded but hasn’t yet been executed. This is the address of the next instruction. Then we get to another word which is broken up into two half words. This is the length of the instruction that’s failed. It’s the instruction length code or the ILC. So instructions come in 2 bytes, 4 bytes, and 6 bytes. So what this is telling us is that the length of the instruction that’s failed is 6 bytes. And then this tells us the type of instruction or the type of, I should say, the type of program interrupt, which in this case is a 0C7 or a data exception. Again, I’m not going to go through all of these values here. There’s so much I could talk about, but I want to move on. We’re in 31-bit mode, as we can see here, and we’ve got then our registers.
[00:11:58] – Colin Pearce, Presenter
When we looked at the interrupt code, this is the PSW and registers at the time of interrupt. These registers are going to be very important to us. I want to pick out two or three registers as we go forward and as we come to them in analyzing this, there’s some registers here that do become very important. Execution key is nine. We’re in storage protection mode, which is the default. We’ve got key eight and key nine. All our user programs that are running in key nine here, as we would expect. Transaction is in base space mode. What that basically means is that we do not have transaction isolation enabled for this transaction. If this said this transaction was in subspace mode, then we could say, Okay, well, we’re in transaction isolation. One of the main reasons for that is maybe we’ve got a storage violation that we want to try and capture or we want to find more information about. Okay, as we move down, then what we’ve got here, sorry, what we’ve got here then is the transaction environment which means that this is how the transaction is defined in the CSD. It’s quite good to…
[00:13:25] – Colin Pearce, Presenter
Sorry, my scrolling key is a little bit worrying. This So this tells us what’s this transaction defined as? What’s its values? Is it defined correctly? And quite often I’ll talk to a programmer whose transaction this is. I’ve got the user ID here with the programmer, so I can always find out who it is. And I’ll just say, look, can you have a look at this and make sure that everything is fine the way it is? So that will help us greatly in order to to achieve that. Come on down. We’ve got then another control block because I want to introduce the way we read the dump, what are the important areas. The Task Control area, the TCA, is a representation of the task to the application domain. It’s acquired on first dispatch from the dispatcher domain, and it then is goal or its role is to look after the task as it runs. It has some important information there, and we can see here, the TCA is in two parts. We’ve got then a user part at the beginning training, and then we’ve got a system part which follows it, and we can see the other system part here.
[00:14:52] – Colin Pearce, Presenter
Those two are very important. Let’s have a look and see how we look at and interpret the values here. Essentially, I always think we’ve got four columns. We’ve got this column, which is actually the offset listing, or this is the offset, I should say, down this piece of storage. This is really the first column. Then I’d like to think that this is the next column, although there’s eight columns in here. These are really the way storage is within our CICS transaction. Each of these rows then is Hex zero because we’re obviously in hexadecimal mode here. We can see here, so this becomes in the storage area. Then over here, I’ll just come across a little bit more. This is then any storage values or any interpretation in EPSIDIC or character that the storage values are that we’ve just looked at. Mostly we’ll see We’ll see dots because it can’t print Hex values. Then right on the right-hand side is the absolute addresses of where this particular storage is. All right, so just to just to understand how we interpret these. When we look at an offset, we’re either looking at a value within that offset or we’re looking at an address in that offset.
[00:16:27] – Colin Pearce, Presenter
What we can see is that we have the ability then to work out where we are within that particular storage area. As we’re counting across, it’s best to count zero, four, eight, C, and then zero, four, eight, C. Rather than take individual bite setting, it’s just to count your way across to a particular value to see how would how we’ve got that access there. I want to come down to another piece of storage here. It’s not too far down, but I want to come down to this one, the Exec interface block. The EIB is created for the transaction. So if you had program one, link to program two, link to program three, link to program four, and so on, there would be one EIB, and each of those programs would have the same address of that have the address of the same EIB there. So the EIB is gotten by CICS at the beginning of the transaction’s execution, and it’s there to really help kick look after the transaction. It has a date and time. This is the time, this is the date the transaction started. This then is the transid. This is the task number.
[00:17:56] – Colin Pearce, Presenter
This is the term ID. There’s a number of very important fields here, but the one I want to concentrate is on this one here. This is the EIB function, and this says it’s 0208. If I can show you what a 0208 is, just give me a second, and I’ll show you that. Just make sure you can see my… Just a second, and I’ll make sure you can see my screen on that one. You can easily go into CICS or into knowledge center or Google it and see what is 0208 is. We can see here the EIB function code, 0208 is an assigned. That tells us the last command that was executed by the application. Let’s go back into our dump. That was executed by the application before everything fell over. That can be quite useful. There are two other fields here. This is EIBRESP. This is the response code that’s filled in, and then this is EIB-RESP 2. These It’s going to be tested in the application because the application has addressability to the EIB. We’re going to see that shortly. It has addressability to this, so it can make changes, although I very rarely see that, but it can certainly access any fields within this environment here.
[00:19:33] – Colin Pearce, Presenter
Just to give you a brief look at what we’re going to be dealing with. There’s many other fields here and a lot, but there’s at least more than 100 pages, so I’m not going to spend my time on things that aren’t going to be relevant. In this case, we’ve got then to find the statement number that’s wrong. We take the PSW. Now, the PSW, as you remember, has really two things associated with it. Not only has it loaded the next instruction would have executed, which is this offset, it’s actually currently executing the previous instruction. And the previous instruction is six six bytes long. We can say, okay, if I get the statement number here or I get the offset, then I can just subtract six to get the actual statement number. Let’s find out how we find out what… Let’s see how we find out what the actual statement number is. Now I want to max to the bottom. You can see here that we’ve got then the module index. The module index is always at the end of the transaction done. We can see here we’ve got the load point heading, we’ve got the name of the module, and we’ve got the entry point.
[00:20:58] – Colin Pearce, Presenter
We’ve also got the length. And so when we look at this, this would be the load point and entry point of every program, including all the supplied DFH modules that are within this address space. So we’re looking for our program here. So we can see load point is 23400000, CICSRRSJ, entry point 2340000, and the length the load module is 000022CC. Always good to check this whenever you’re dealing with a transaction done. You want to make sure that this is the right program. If I’m working with an application group or I want to make sure that this is the right program, if I’m not sure, I can always do a CNT enquire on the program, or I can do a “CICY” load of the program, “C-I-C-Y” load of the program, that’ll give me the length. I’m assuming, and hopefully the programmer can verify that this is the length of the program that we’re dealing with. There’s no point looking at a program that’s been subsequently changed or updated because obviously this would have no meaning. What we need to do is take 234000, and we need to subtract that from this address here because a PSW, remember, is pointing to the address of the next instruction.
[00:22:34] – Colin Pearce, Presenter
In our case, very easy to understand, we got 5DA is our particular offset. Whenever we’re looking at storage areas, we’ve got two values that have become very important. There’s the base address of that storage area, and then there’s the offset or displacement down that storage area where we’re currently at. And what I always say to system programmers, if you’re debugging, don’t be afraid to draw boxes out on a piece of paper and put an X inside the box and say, Well, this is where the PSW is pointing, and then you can always put down the address on the starting point of the program. Just one more thing before we leave this, and that is that you’ve got both the load address and the entry point address, and it’s always good to ask the question, is the load point and the entry point the same? If they are, then it doesn’t matter which one you take, but you can’t always guarantee it. In the past, the DfH exec interface dub was always loaded first in the procedure, so that always was the beginning of the load module. You can’t always guarantee that it’ll be the same, but what I always suggest is always take the entry point of the program and then you can’t get it wrong.
[00:24:05] – Colin Pearce, Presenter
But if they are the same, it doesn’t necessarily matter which one you take. Let’s just come to the top. So 5DA then is where we are in the program. Let’s go to the program. Just give me a second to bring that up here. Now, what I always do, I always compile programs or I make a I make an edict out to all the programmers, please compile your program with the map offset or the map option, I should say, and the offset option. If you’ve got List, that includes offset. List will be ignored and offset will be taken. If you got both of these, then I think you’re pretty good to go because what it means is that I can do a HexLock find on HexLocation and I get this particular values. Let me just get rid of the yellow here. This is the Hex location. There’s three columns here, and in each column, there are three columns. We tend to follow, I tend to follow the one under hex location here, and you read it left to right, top to bottom. We’re looking for an offset that’s just lower than 5DA. Well, we’ve got here 5 E0.
[00:25:33] – Colin Pearce, Presenter
If I move across, again, I’m reading it left to right, top to bottom. I’ve got 5 E0, but that’s too high. I’ve got 5 CE, but remember, we’re 5DA. Therefore, our statement that’s failed is 0003063. So find 0003063. This will give us the statement that’s failed here. Add insult to injury. How many times have we had that happen to us? Let me just bring this back up to a little bit more central here. So just reset. Finding the statement number, fairly straightforward, but we’ve got two data item values here, insult and injury. And with an add instruction, it’s quite likely, as we’ve got an OC7, it’s quite likely we’ve got a pack decimal problem here. Until we get everything validated, we can’t absolutely be 100 %, but usually an OC7 is a pack decimal failure. And so we as system programmers or as programmers, you’re going to need to know what a packed decimal field looks like. So in this case, then, It’s really important to understand that. But I want to cover a few different things before I get into finding these working storage items. Let’s go back to our DUM.
[00:27:11] – Colin Pearce, Presenter
Let me know if you can’t see my screen. I’m hoping that this Zoom will follow me wherever I go. Okay, so let’s move forward. I want to come down here and I want you I’m going to look at the Exec interface block. We’re going to go to the right-hand side here. If you’ve got a pen and paper, that’ll help. I want you to write down this address, 21D00100. Because this is available to the COBOL programmer in the COBOL programmer’s linkage section. This is put there through the CICS translator where it translates the API calls, the Exec CICS calls into call statements. And what it does, it builds a linkage section for the EIB, and we’ll have a look at that in a moment, but make sure you’ve got that down, 21D00100, because we’re going to find this in storage too, in our dump, to make sure we are looking at the link it section. So because the EIB is the first address in the link it section, or at least the first address of the control block EIB in the link it section, we want to validate that when we find it, then it’s good to go.
[00:28:36] – Colin Pearce, Presenter
Let’s talk about some other things here. Let’s come across. I want to talk about this particular register here. We’re going to talk about some registers, but I want to talk about this one in particular. When we count our way across, you can see we’ve got registers 0 to 3, we’ve got 4 to 7, 8 to B, and we’ve got C to F. We can see here that this is Register E or Register 14. It depends how you want to view it, but we’ll call it Register 14. Register 14 is a very, very powerful register for us because what it does, it is actually used within Within the call statement, it’s used to contain the return address into the program. If I issue a call to a subroutine, within that subroutine or within that call process, then a number of things happen. Register 15 is loaded with the entry point of the program we’re going to, but this is Register 15, but it can’t stay like this because it’s used for other things as well, but it is the address of the program that we’re going to. Register 13 here is used only as a Save Area address.
[00:30:12] – Colin Pearce, Presenter
We’re going to look at Save areas when we come to look at the trace table, and I’ve got a layout of the trace table for you to have a look at as well. But Register 14 is really important in your debugging. Let’s supposing that we know that the last exec CICS KICs command, we know the last exec CICS command issued, as noted in the EIB, was the Exec KICs assigned. Okay, well, it can say to the programmer, because I like to help the programmer not only give them the statement that’s failed, but also give him as much surrounding information as possible. So I can say to the programmer, Oh, your last exec kick statement was an exec CICS a sign. And you say, Well, that’s great. He said, But I’ve got three assigned in the program. So which one are we talking about? Okay, so therefore then I can say, Well, with Register 14, whenever we leave the program, and this takes you a little bit deeper, if you know Assembler, then you’ll understand what I’m about to say, but if you don’t, just take it on board. Register 14 is always used as the return address.
[00:31:33] – Colin Pearce, Presenter
So if I do a call to a subroutine, then within that call statement and knowing Assembler, I know how difficult it is to code a call statement. It’s probably one of the hardest macros to actually code. But register 14 is then loaded with the return address back into, let’s call it the mainline program, or in this case, CICS BRSJ. Okay. Okay, so I can then say, well, look, if I’ve got the return address back into the program, then I’ve got the address of the last API command, or rather the last time we left the program. Every time we leave the program, whether it’s calling API, whether it’s calling a subroutine, a non-CICS subroutine, Register 14 will be loaded with a return address back into the program. If I say call and I load Register 14 back into the statement after the call, it wouldn’t matter if I’ve got 100 COBOL statements before the next call. Register 14 will We all point back to the last time I left the program. In our case, then, raise to 14 can be very useful because if the program is saying I got three assigned in the program, I can say, Well, let me tell you which one this actually is.
[00:33:00] – Colin Pearce, Presenter
I look at 5B8 here, and we know then the entry point address to the program is 23400000, so therefore, the displacement is 5b8. If we go back into our… Just give me a second here. We go back into our COBOL program. Okay, let’s max to the top, and we find HexLock. Okay, and we come down to here, we reset, and we come down, and we’re looking for 5B8. All right, so we’re looking for… We’re 5F6, too high. 5BC, that’s too high. So we’re looking at this one, 576. And if it’s Register 14, you’re finding it must be a call statement because Register 14 is not used in any other way other Other than the return address. Although I must agree. I must say that after writing assembler code for decades, I’ve seen Rage to 14 being used for other things, but that’s not its purpose. Its purpose is to point to the statement so we can do a return. We come to him and say, Okay, well, this statement then is 000295. So Okay, I should put a find in front of that. Let me do that.
[00:34:35] – Colin Pearce, Presenter
Find 000295. Preve. Okay, so register 14. Let me just bring this up a little bit. A few, sorry, a few statements. You can see here that we were 295. Okay, let me just put that back, and you can see we’re on an exec CICS a sign. It’s very straightforward. I can say to the programmer, Yeah, if you have three assigns in the program, the one is the statement number that we found in the offset is statement 295. If he’s got his output from the translator listing that the CICS has produced, then he’ll be able to see that this EXEC CICS assign here. Depending on what he’s looking at. We can see here then we’ve got EXEC CICS assign, and then we’ve got all the values of that assigned. Again, I can’t really tell him what the failure is here, what’s caused it, but I can just tell him that this particular statement has gone down with an OC7. We’re going to look at this in more detail as we go forward, but I’ve got some more things to talk about in the COBOL listing. So let’s just max to the top, and let’s do a find on BLL.
[00:36:09] – Colin Pearce, Presenter
And so this then is our linkage section. Let me just get rid of the yellow here. In the linkage section, dfheiblk is always what we call the base locator for linkage section number one. It’s always number one. It’s always first in the Linkage section. COBOL programming get a bit… They don’t really quite understand this because when they code the linkage section, they don’t see this one here. I mean, it is there and it’ll be taken care of by CICS, but they don’t see it, so they don’t always understand, how come the EIB is in my linkage section? So we need to understand that. If I go forward, and I’ll just come forward here, what CICS also does within the translator listing. It loads a one-bit DfH com area. It gives it one bite. And this will happen if the com area doesn’t exist, and it will give it BLL number 2. So really what we can say is that the EIB is always BLL number one, and the COM area is always BLL number two, even if it doesn’t exist. If it doesn’t exist, then it will have low values in its address. But if it does exist because we’ve been linked to by a higher program, so we’re running it level two, and the program above us is running at level one, it’s passed as a COM area, Then this will be a valid address of that COM area because we would have coded DFH COM area in our linkage section.
[00:37:53] – Colin Pearce, Presenter
Now, of course, the COM area can be up to 32K. If we do have a very large COM area passed to us, and we We often see this these days because COM areas have a ceiling in terms of the size. Then what we find is that the first 4K of the comm area will be the LL2, the next 4K will be BLL3 and so on, depending on the size of the comm area. The reason for this is that the comm area then, in terms of linkage section, is broken up into 4K chunks. The reason for this is that when we address the comm area in storage, we address it via a register, and a register can only address up to a length of FFF, which is 4095. So 0 to 4095 is 4K. So that’s why we break up our comm areas into separate chunks because of the limitations, you could say, on a register. And that’s the same with coding an assembler program. A base register of an assembler program can only address up to FFF in terms of the location counter and what it can address it. Anything over FFF, then the assembler would have a problem with it unless we allocate a second base register.
[00:39:18] – Colin Pearce, Presenter
Okay, so what I want to do then, I want to come back to the top here, and we’ll come to then our dump again. Because we’re on enterprise COBOL version 6. 3. 4, then we have to think about a different way that we find both the linkage section and the working storage. I mean, once upon a time, when we were enterprise COBOL 4.2, which was the last time, we had a nice control block called the Task Global table. And that was a great control block because it allowed me to find working storage, the linkage section, address of the program, all contained in the one control block. When they went to enterprise COBOL version 5 and version 6, we lost the TGT, so therefore we had to find another way. So what they did, they actually announced PPAs. These are the program prolog areas, and there’s four of them. So what they do, they’re assigned to the program. So you’ll see PPAs. We’ll look at them briefly as we go through the the debugging here. They’re there to finally give you all the information about the program. But the problem with CICS is that it’s a multitasking system.
[00:40:54] – Colin Pearce, Presenter
So whenever a task comes in and the program is loaded, it, then the working storage that sits with the program, CICS takes a copy of it and assigns it to the first task. If Task 2 comes in and wants to execute the same physical copy of the program, then CICS takes a copy of that particular working storage and assigns it to task 2. So every task then has its own copy of working storage. And this really gives us the idea of what we call re-entrancy, the ability to execute the the same physical copy of the code whilst making any changes into our own version of working storage. So therefore, the physical copy of working storage that resides with the program is never, ever used other than to take a copy of it. So CICS can then maintain its multitasking environment, and in a sense, it’s a multi-threading environment as well. So we can have, depending on max task, We can have many tasks all running through the same program, but any changes they make are made in its own copy of work of work storage. So therefore, because the PPA, the program prolog is an assigned to the program, we can’t use those in a CICS manner.
[00:42:24] – Colin Pearce, Presenter
I must admit, it took me a while to figure out, well, if we can’t use PPAs because they’re assigned to the physical program. When we want to find working storage, we might have 1, 2, 10, 20. We could have many tasks all executing the same physical copy of the program, But in actual fact, they’ve all got their own working storage. So any changes they make are done in their copy of working storage, not in the physical copy. So therefore, I thought about this and thought, well, how does… And I I tried to find some seminars and that that would show me how it’s done. I thought, Well, how does CICS find it? I thought, because I took some dumps home with me and I spent some weekends trying to figure out, how do we find working storage when there’s so many different working storage in that? And then it suddenly hit me, Well, if CICS can find it, then how is that done? And that is done because, again, my assembler knowledge came to the fore is that CICS uses the registers then to address that particular tasks working storage, that particular tasks, linkage section.
[00:43:40] – Colin Pearce, Presenter
So when we’re looking at our working storage and our linked section, let’s take the linkage section first. Register 8 here points to the address of the linkage section in storage. So this address would point to the EIB address. Remember, the EIB is at its base locator for link in section 1. So if we take this address, and let me just show you this address. We want 2, 3, 4, just a second here. I’ll get my notes together. We want 234. Okay, 234, 0, 0. Where are we? Just a second. I got the wrong page up here. Yeah, so 2340DBF0 234. Now, what I’ve done already, I’ve set up a page number, which is down here, which is number 16, so that we don’t have to look for it on the right-hand side of our absolute. So I hit Enter here. I’m looking for page 89. So again, I’ve already done some work here to help you understand. So let’s go to the right-hand side. So let’s go to the right-hand side here, and we want 2340DBF0. Again, you’ll need some practice if you’re not used to looking at addresses. But always understand there’s 2,0 between these addresses, hext 2,0 here.
[00:45:21] – Colin Pearce, Presenter
I bring this up to the top. I hit the wrong button here. I’m sorry. If I bring this up to the top, this one here. Okay, let’s do that again, and let’s bring that across to the left-hand side. Keep hitting the wrong numbers here. I’ve got the wrong address here. Just give me a second. 2340D. Sorry, I hit Register 7. 0DBF0. Sorry, 0DBF0. I beg your pardon. 0DBF0. It’s this one. This is C0. We want 0DBF0. 0DBF0. 0DBF0. 0dbf0. We got to We go back a little ways here. 0DBF0
[00:46:41] – Colin Pearce, Presenter
. We come down to this one, bring this one up to the top. So 2, 3, 4, 0, D, B, F, 0. Well, we want B, E. This is B, E, 0. We’re bringing this up to the top, and I come across to the left-hand side. We can see this is E0, where this is F0. You would have taken down 21D00100. This is the address of the EIB. This is bll1. And Moving along, this is low values because this is our comm area. As we don’t have a comm area at this point in time, then, of course, we can see it’s just been allocated in order for CICS to maintain addressability.
[00:47:30] – Colin Pearce, Presenter
That if sometime in the future we are linked to this program and a comm area is passed, then we’ll have the addressability filled in here by CICS in order to achieve that. That’s then our value. Then let me just go back to the top. Let’s come down to our program now. Now, remember, let’s just take a… Let’s just We come back to here, find 000306. Remember, this is the ad for insult and injury. Now we need to think about, well, how do we find working storage? We found linked section. So if we had multiple BLLs, we could simply work our way across for each address to find that address or that address. And again, you get OC4s, then always think about the linkage section, always think about low values, and think about addressability. What it means is that we’ve tried to move data into an address where it’s invalid. And when we look at a protection exception, always remember that every 4K page is loaded with seven bits. There’s a three bit and there’s a four bit. Let’s concentrate on the four bit. The four bit deters determines the storage key that that page is available in.
[00:49:06] – Colin Pearce, Presenter
So if we’ve got something like zero, zero, zero, well, that is key 0. If we’ve got one, zero, zero, that’s key 8. If we’ve got 1001, that’s key 9. So if I want to move a value, move field A to field B, and I want to move field B into that page, then the The storage protection key of that page, for example, 1001, that’s key nine, will be compared to the actual storage protection key that’s in the PSW. If we’re running in key nine, which we should be, then Key9 compares to Key9, that move will allow to occur. However, if it is 0000 because you don’t have a proper address, then 0 doesn’t match 9, we’ll get down with an OC force. But let’s go back to then add insult to injury here. And what we find is we need to really know four things about these two values. We need to know, for example, the base address of our working storage. We need to know the displacement down that storage. So we need to know how far down the storage is both insult and injury. So that’s the second thing we need. There are four things.
[00:50:34] – Colin Pearce, Presenter
The third thing is we need to know how many bytes are each of these working storage values? How many bytes are they? So we know When we get there in storage, we know how many bytes to count across. And then finally, as the fourth item that we need or the fourth element is then we need to know the picture clause. How is this field defined? All right, so if we’ve got the base, if we can find the base address, if we can find the displacement, if we can find the length of the field, and we can find the picture clause, then I think we can find this working storage. So let’s go back up to the top here, and let’s do a find on insult just to see how it’s defined. And we can see here it’s defined as PICS97. Com3. Well, this is a 4 bytes packed decimal field, and we can see over on the right-hand side, it’s 4 bytes and it’s packed. Injury here is coded as a PIC S97 comp3, and again, this is 4 bytes packed. Why I’ve got injury X here is because when I set this dump up, COBOL gets a bit smart these days.
[00:51:53] – Colin Pearce, Presenter
It won’t let me move values into a S97 comp3 field unless I have a a redefined here. So really, injury X and injury are exactly the same. So let’s look and see. If we go back to the beginning and we’ve got then an option of map. Now, Remember, we want the base, we want the displacement, we want the value of the field, we know it’s four bytes, and we want the picture clause. How is it defined, which is packed decimals? So if we We got to know, what does a packed decimal field look like? Because when we get there, when we finally get there in the dump, it’s not going to jump out to us and say, Yeah, you got me. Here I am. I mean, we got to know what we’re looking for. So in a packed decimal, in its simplest way, it must have the very right-hand half-bite set to a C, if it’s positive, set to a D, if it’s negative, or set to an F, still packed decimal, but not used arithmetically. What we’re looking for then is two four-bit fields. In this case, with the add instruction, and they’re both supposed to be packed decimal.
[00:53:16] – Colin Pearce, Presenter
One or both of these fields is incorrect or has been corrupted. Let’s look at our map and see how we find what we’re looking for here. Our maximum to the bottom and I’ll come back up. This is what map gives us here. Firstly, let me look at this one. Come back to here. By the way, the PPAs are here. You got PPA 4, all right? But again, I don’t use them. Ppa 2 is PPA 1 and PPA 3, so there are four of them. Let’s just go down to here. What we see here, this is the map option. We get the offset in hex, we get the length, and we get the BLL pointers. Okay, so because we got the BLL pointers, this set aside as eight bytes, and as each BLL is four bytes each, if you divide this value by four, you’ll get the number of BLLs. If this was one zero, and I divided by four, I would get four BLLs. If it was the CICS program, I get the first one would be the EIB, second one would be the COM area, and the next two could well be what the user has coded as BLL3 and BLL4, and I can validate that in the code itself.
[00:54:48] – Colin Pearce, Presenter
It also says here the working storage base address. I could use this address, but it’s a0 down. I’ve got to go to this address, and I’ve got to then add a zero to find this address. That’s one way of doing it. It’s not the way that I do it. What I do, I come down to this one. What I’m looking for is in the working storage, and there are reasons why we’ve got this here, I won’t go into them now, but if we go to working storage, I’m looking for insult, and I’m looking for, in this case, injury X, which is injury. Now, we know they’re four bytes each, we know they’re packed decimal. So therefore, if I bring this up, and I come down to here, if I can find this address, and then I can add, as we go down, just give me a second, if I find that address and I can add 118 to that address, that will take me to insult. If I can find the same base address and add then the displacement of 120, this will take me to injury. Therefore, I’ve got three of my four values.
[00:56:14] – Colin Pearce, Presenter
I’ve got the displacement, 118, 120. I’ve got the length, 4 bytes on each of them, and I’ve got the picture clause that they both must have signed values on the right-hand side, the very right-hand half-bite, must be a sign if it’s not OC7. So the only thing we’re missing in this case is how do we find working storage? Therefore, how do we find this address in order then to add our displacements to it? So let’s go back to our dump. I thought to myself, myself, as I said to you earlier, how does CICS find working storage if we can’t use the PPA? Well, CICS finds working storage. As we’ve seen, the linkage section is the address in Register 8. Working storage is found in Register 9. So 2340DCF0. But I don’t want those two values. I want to add 2340DCF0. I want to add 118 to that address on the basis that is the beginning of working storage. And I want to add 120 onto 2340 dcf0. In a sense, to find insult, I’ve got the address of 2340 d e08 and 2340 0DE10. If I can find these two values, these two addresses in storage, then I can find my working storage.
[00:58:12] – Colin Pearce, Presenter
Let’s go back to our trusty page number here. It is on the same page, so that makes it a lot easier. All right, so let’s go to this page. All right, so coming down to the right-hand side. All right, let’s I’ll come down to here. So let’s come down to this one. You won’t believe it, but I’ve hit the wrong thing again. Okay, let’s just try it once more. So number 2, I got to be very careful with my fat fingers here, come across to the right-hand side. And we’ve got then we want 2, 3, 4, 0, D, E, E, 0, 8. 2, 3, 4, 0, D, E, 0, 8. You may have done the arithmetic in any way. This will point us to an insult. I bring this up to the top. I bring this up to the top, bring this across to the left-hand side, and we can see here, this is zero, this is four, so this is eight. Because it’s four bytes, we can see here that this is 2340DE08, is this one. So this is insult. And so we want to come across here the 2340DE10. That’s just 8 bytes away.
[00:59:52] – Colin Pearce, Presenter
So we come to here and this is injury. So injury is incorrect. Insult Which is fine. It’s got a sign at the end of that field. Injury doesn’t have a sign, so that means we got an OC7. Because what happens is with an add instruction, add insult to Injury, we’re actually using a machine instruction of an ad-packed instruction. If we went to the machine code, I’m not going to do that, but we went to the machine code, we’d have an AP command and we’d have a base displacement, a base displacement displacement because the AP command is 6 bytes long, and we will be able then to find the same displacement of both insult and injury. We’re able to find that simply because we understood we got to find the base address, the base address, the displacement, the working storage values such as how long are those storage, what’s the length, and also the picture clause so we know what we’re looking for there. Just to help you understand on a basis. If we go to something like a link or a COBOL call, there are a little bit more detail that we have to think about.
[01:01:19] – Colin Pearce, Presenter
Unfortunately, I won’t have time to do a link, although I’ve got Dumps to do that, and I won’t have time to do a COBOL call, and I’ve got Dumps to do that, too. But they do follow a similar pattern, but I thought, let’s at least walk before we can run, and let’s do it this way. Okay, so let’s come back here, and let’s go down to then this one here. Let me just think, I want this. Sorry, I want this one here. Okay, so now let’s look at Let’s look at the trace table because the trace table can provide some very useful information. Let’s go into CICS. Okay, so let’s just stop the screen share and we’ll go into CICS and I’ll start the screen share again. Just give me a second here. Okay. All right, now I’ll share the screen. Here’s my screen share? It’s this one. Okay. What I tend to do is that because I’m working with the programmer, if I leave the trace as a default, it’s going to trace a lot of data in CICS. A lot of the data that the programmers won’t really be interested in. Where I’m based at the moment, I do a lot of work with programmers, and if I’m going to solve a problem, sometimes I’ll have to stand up in in front of the programming group and show them how I found the particular problem.
[01:03:05] – Colin Pearce, Presenter
Some of I’ll do it in front of my boss as well. What I do, I do a CTR, which is the Trace Transaction. I can start and stop the trace anytime I like, so all these are over-typed. But what I tend to do, if I’m working with programmers, the programmers are really only interested in the exec interface. They’re not really interested in transaction manager domain running through the attach process to create the new task and assign a task number. It’s a lot of data that will have very little meaning, if anything at all to them. So I like to set up the trace where I’m working with their testing and development environments, and I can set up the trace and teach them how to read the trace when there’s only their commands in the trace. So if I go to components, you see components here, pf4, you may have seen this before. If I go to PF4, you can see here that I’ve already set two of the components set to off. I’ve done that. Let me just show you where I’ve done that. I’ll have to bounce you back again to this one. Just Give me a second here.
[01:04:33] – Colin Pearce, Presenter
Just give me a second here, and now I’ll share the screen. Just a second, and I’ll share the screen here so you can see where I am. Share. Here, and this one. So what I do, I can either set it up the way I want. If I go here, if I select this one, and I come down with my overrides, you can see here, I’ve I’ve set up my standard tracing for the AP domain and my standard tracing for the asynchronous services here. I’ve set them up, both to off. I’ve set up my standard tracing for the exec interface to two, and I’ve set up my standard tracing for storage manager I’ve set to number two because number two gives me a little bit more information that I’m looking at. If I wanted to set them all up here, I’d have to type them all in here. You’d have to go to knowledge center to help you do that. It’ll take you a while, but it just shows you what you can do. If I do it online, let’s come back out of here. If I do it online, let’s come back to my Where are we?
[01:05:47] – Colin Pearce, Presenter
If I do it online here, share the screen, and I come down to this one and this one. So therefore, I can type in my off here. I can type off, as you can see, all the way down. So I like to do an off to all of them, except for the exec interface. I like to have number 2 because then I get the exception conditions. If they’re valid, I get more information about the API commands. So I’ve turned all the others off. I won’t do it now, but I’ll just show you that you I can do it. If I go forward, if I go forward with an eight all the way down, I like to have storage manager number 2. Not always, but if I’ve got a storage violation, then I like to know what was the address of storage. Because in a storage violation, CICS will give me an exceptional condition. It’ll write it into the trace table. Even if the trace table is stopped, it’ll write it in. It’ll give me the address address of the storage that it found violated. So therefore, if I got storage manager set up here and I go back in the trace and all I’ve got is API command, then I can find the get_main with not the exact address, but with a very similar address.
[01:07:19] – Colin Pearce, Presenter
It’s not the exact address because when I ask CICS for, say, 100 bytes, CICS gives me 116 because it’ll give me 8 bytes in front of my storage, my 100 bytes, and 8 bytes at the end of storage, and they’re called storage check zones. And those storage check zones, when CICS comes to clean up the storage, those storage check zones must match if they don’t match storage violation. So therefore, it’s important for I need to go back into my trace table, find the get_main that has that address, but the get_main will give me the address with the storage check zone. So then I can use I’ll use that address and I’ll show you what I can do with that as we come towards the end here. I want to show you what I can do. Let’s just come out of here. I want to come stop the screen share here. I want to show you Just give me a second, and I want to show you this one. Just a second here. Just a second. What I’ve got here, let me share the screen. What I’ve got here is… Where’s my screen share? One of these, one of these, and one of these.
[01:08:58] – Colin Pearce, Presenter
What I’ve got here is the trace table, but I’ve got storage manager here. This is the storage manager get_main_free_main_gate. All entry points into a domain are done through four character gates here. So I come all the way down, and what I’m looking for is the beginning of my storage. Again, if I didn’t have all the get_mains here, I would have this as my first. This would be the first execCICS command with my transaction. You can see here for each trace entry, there’s two entries per API command. There’s one going in and one going out. You can see the receive here and the receive here. So this is the one going in and the one coming out of the trace. You can see here the ask time and format time, one going in and one going out. Format time, one going in and one going out. Write queue. Because I’ve got an exec interface, sorry, the exec interface number 2, I get good things like, what’s the transient data queue that I’m looking at here? I’ll come all the way down here and you’ll notice that I could show this to the programmer, and he could follow the the logic path of the programmer without all the other kicked noise getting in the way.
[01:10:29] – Colin Pearce, Presenter
He You can say, Oh, I did a receive. Then I did an ask time to go and get the date, formatted it, wrote some data to transient data. Then I did an assign and then crash. You can see the program check here. This is an exception entry. Remember, the exception entry goes into the trace, even if the trace table is not valid. But what I can do, I’ve already done this, but let me show you something really neat with the trace. I’m looking I’m looking at the abbreviated trace here. For every abbreviated trace, there’s an associated extended trace. And so the associated extended trace gives us much more information. So for example, I can come down, I can come to the assign here, and if you’re going to do this, always look at the exit one, not the entry one. If I go to the assign here, let me to the right-hand side, and let me pick up this number here, because in order to get from the abbreviated to the extended, I’m going to need the link, which is this one. If I do a find on this particular one, and then I’ll do a repeat find, it will bring me down to the extended entry address.
[01:11:56] – Colin Pearce, Presenter
If I go F10 and I come across, we can see the the layout then of our extended. I want to pick up three values here. In each of these API commands, the Exit one, this is the EIB address at this point in time. So this is our 0208 because I’m looking at the assign. Again, we’ve gone to our knowledge center and we’ve looked at the EIBFN So I can see a lot of good information here. Number 5, this is Register 13. This is the address of the save area. So bear in mind a little bit of background here. If I’m calling a subroutine, the language environment will save the registers in my save area before it passes control to the subroutine, because the subroutine is going to want to use registers. There’s only 16 of them in every central processing unit, so they’ve got to be saved. But let me show you what a save area looks like. Let me come down to here, pick up this one, and share the screen again. Come to this one, share the screen, and come to here. This is what a save area looks like. A save area, the way it’s laid out, the way we use it’s convention.
[01:13:37] – Colin Pearce, Presenter
It’s cast in stone. You can’t change it. In fact, the assembler instruction, the store multiple, saves the registers in a save area in a particular order, and it saves them. All of these squares here are each four bytes. So you can see here 14, 15, zero 0, 1, 2, 3, 4, all the way through to Register 12, and Register 13 is pointing to the beginning of this save area here. So therefore, because I can’t change this, because the Assembler Instruction, store multiple, stores the registers, it always starts to store those registers at 12 bytes away from where Register 13 is pointing. So we always know when we’re looking at a save area, the fourth word in is going to be Register 14, the fifth word is 15, then zero, one, two, all the way along. So if I’m calling a subroutine, then each subroutine may well call another subroutine. In each case, a save area will be created, and the registers of the calling program will be saved in that save area for the called I could be five, six deep in called subroutines, and there will be a Save Area built between each one.
[01:15:10] – Colin Pearce, Presenter
So if I can find the Save Area in the Dump and language environment in its CE message stores all of the addresses of the save areas, then I can find through Register 8 and Register 9, the linkage section and the working storage of any Any value that I want within that whole application. But let’s just take this one step further. We’ll be breaking in a few minutes. Register 14 is the fourth one along. Let’s come down here. We’ll share the screen. Give me a second. We’ve got this one and we’ll share the screen. This one and this one. This is then the save area. This is the save area at the time we left the program to do the API call to the assign. Of course, every save area per API command will be slightly different. Register 14 will point to the return address. In this case, when we look at this, we can say 048C. This is Register 14. This is the return address into the program from where that assign came from. Now, if you remember, we’ve already checked in the dump this particular offset, which means then that I can look at any of my API commands within the trace because the programmer usually says to me when it fails with the program check, how did I get here?
[01:17:03] – Colin Pearce, Presenter
And so it may be that I would have to find not only the assign, but any previous command. And as long as I’ve got the COBOL source with all my call statements in my Hex location there, then I can find wherever I left the program for that API call. Therefore, Register 14 provides me with this very important information that I can say to the programmer, This is the statement of the assigned. This is the statement that executed before your program fell over. If I show you this, I’ll show you this one more time from one of my courses, just to show you, where are we? Just to show you this one. Give me a second Come down to this one. I want to just show you this. Let me just show you this. Just to consolidate what I’ve shown you, let me just show you this one. I’m talking about register save areas here, and I’m talking about the value of register 14. As you can see here, register 14 can contains the return address into the program from where the last call came. By issuing register 14, the last call statement can be ascertained.
[01:18:39] – Colin Pearce, Presenter
As you can see here, I’ve got call routine 1, register 14, point is back into statement after the call. It’s actually within the call, but it’s the last statement in the call. It’s not a statement that gets executed until we come back. You can see on a call routine 2, register 14 comes back here. I call routine 3, register 14 comes back here. So register 14 then is a really important address. Just to finish up, let me just come back into my notes. Okay, let’s come back into here, share the screen to finish up. All right, so when I find my save area, and like I say, if you look at CEE message, again, I do that in my transaction, the bugging, but I won’t do it here because time will not allow. But then language environment has got all the addresses of the save area. It’s got not only the address of the save areas, it’s got all the save areas as well. If I can find a save area, I can find the last time we left the program, then I can count along and I can go 14, 15, 0, 1, 2, 3, 4, 5, 6, 7, 8.
[01:20:17] – Colin Pearce, Presenter
This is the address of the linkage section, and we’ve already validated that. This is the address of working storage. So if I can I find a save area, I can find anything I want within that whole application. Okay. Okay. How is everybody? I think we might bring this to a close. We’re getting past 10: 00 to 6: 00, BST. If there’s any questions, I’m happy to take them. If not, I’ll give you my contact details and you can always email me if you have any questions or anything you want me to look at or don’t send me dumps. That’s not the best way. Gdpr might have something to say about that as well as security. But yeah, so I’ll hand it back to Amanda. If you need to finish up, Amanda, hopefully that was of good value. Again, if there are any questions, my contact, let me put it in the chat so that you can see it there. Just a second. I’ll just type in my contact details, and you’re most welcome to contact me. I get lots of emails from people I teach all over the world. There’s my email address. Again, if you have anything I can help you with, I’m happy to do that.
[01:22:15] – Colin Pearce, Presenter
And hopefully that was of some value to you, the last hour and a half or hour and 20 minutes.
[01:22:22] – Amanda Hendley, Host
Thank you, Colin.
[01:22:25] – Colin Pearce, Presenter
Oh, you’re welcome, Amanda.
[01:22:30] – Amanda Hendley, Host
Yeah, if anyone’s got any questions, you can put them in chat and maybe drop your contact information to Colin, and that we…
[01:22:38] – Colin Pearce, Presenter
Or just email me. Or just email him. Yeah, I’m happy to tell. I get lots of emails for questions. I do a lot of teaching. I get a lot of emails, so I like to help people out. I may not be able to ask you in a day. It might take me a couple of days to get back to you, but I’m happy to help you in any way I can.
[01:23:01] – Amanda Hendley, Host
That’s great. Well, thank you. So thanks, everyone, for being here today. I’ve just got a couple of things before we wrap up, and then we might be able to get you out before the top of the hour. I do want to thank our partners, Broadcom and DATA-Cnetics for their sponsorship of this series. If you are not a customer of either, I would encourage you to reach out and say, hey. Tell them you found them here. Articles and news. There’s not Well, I say there’s not a lot. There’s a lot of CICS news out there. But on Planet Mainframe this past month, we’ve been publishing quite a few CICS articles. So you can find those at planetmainframe. Com and search CICS, or you can scan this QR code Here on our job board, I did notice that several of the major financial institutions, Citi, J. P. Morgan, and others are hiring with CICS skills. So if you’re looking to make that move, that QR code will take you to jobs. Planetmainframe. Com. We have a YouTube presence, if you aren’t familiar with it, but we’re going to be adding some new things and revamping it. So I want to let you all know that we have a YouTube presence where you can find all these videos.
[01:24:16] – Amanda Hendley, Host
But as always, virtualusergroups. Com is where you can find the videos and the articles and the transcripts. And lastly, we’re always looking for contributors for Planet Mainframe. And I will say the Our next upcoming themes, if anything strikes your fancy and you want to write on it, we’ll be talking about observability, and then we’ll be talking about security and COBOL. And that will ship round us out for the rest of the year. If you’re interested in writing, if you’re interested in presenting a session for one of our user groups, you can reach out to me. Again, my name is Amanda Hemley. It was great to host you today. Our next session on September ninth is going to be about open telemetry and more actual TIDAL TBD, but it’ll be a joint session with presentations from IBM and Broadcom. We’ve got Dave Dalton, Mark Hauker, and Todd Gagel involved. I look I look forward to seeing you in September. And if we don’t talk between now and then, I hope you’ll have a great August and end of summer. All right. Thank you, everyone.
[01:25:27] – Colin Pearce, Presenter
Thank you, everyone. And take care. Thank you.
