Virtual IMS User Group Sponsors
Virtual IMS User Group | December 2024
Understanding What IMS Applications Can Do and How You Can Benefit From REST APIs
Suzette Wendler (Suzie)
IMS Support
Washington Systems Center – IBM
IMS clients worldwide have a wealth of assets in the form of IMS applications. These business-critical apps have been running your business for decades, at performance levels hard to rival. Their durability, reliability, and scalability are legendary. IMS continues to add rich function for applications in every release. So how are you taking advantage of them NOW? Whether you are an Enterprise Architect, Application Architect, or Application Developer, you will learn something valuable in this session.
Suzette (Suzie) Wendler, IMS Support
Suzie Wendler is a member of the IMS team – Washington Systems Center. Over the past several years, her major responsibilities have included areas such as customer support, critical situation analyses, design implementations for IMS connectivity as well as integration projects in support of the API economy. Additionally, she has presented at several User Groups, including Share and the IMS regional user groups; has been involved in IBM-sponsored activities such as z Technical University and multiple webcasts; and has provided both technical and teaching support for IMS education and hands-on workshops.
Read the Transcription
[00:00:00] – Amanda Hendley
Welcome, everyone. My name is Amanda Hendley. I’m your host for today. I’ve turned off the waiting room, so we should not have anyone stuck in there while we get started. I want to make sure we have plenty of time for Suzie today, so let me make sure I’ve got my slides up in front of me. Hopefully, you can all share my screen. As always, if you have questions throughout our session today, you can put them in chat, and we’ll try to make sure we get to all of them. If you have any audiovisual issues during our presentation today, I hate to give the most basic tech advice, and that is to essentially turn it off and turn it back on if you log out and log back in from Zoom a lot of times those issues get fixed. But I think we’re ready to get started today. Our brief agenda, as always, just introductions. My name is Amanda Hendley. I’m with Planet Mainframe. Glad you’re here today. We have our presentation. Then we’ll have some time for Q&A. We’ll talk about some news articles, and then we’ll talk about our next session. So pretty quick and easy there.
[00:01:13] – Amanda Hendley
After our session, there is a two-second survey that’ll pop up. I’d love for you to just tell us if you learned anything today in that survey, and that’s when you exit today. I do want to take a moment to thank our partner and our sponsor of the IMS series, BMC. BMC empowers businesses to innovate and thrive by delivering cutting-edge mainframe solutions. In other news, Planet Mainframe. Sorry, my slides aren’t advancing. Planet Mainframe is planning to be at Share 25 in February. There, we will kick off nomination period for our influential mainframer program, so start preparing for who you might want to nominate. We’ll also be coordinating the release of our 2025 Arcadi Mainframe Navigator. You might know it as the Arcadi Mainframe Yearbook. And then we’ve got a lot of fun prizes and activities planned for our boot there. I did mention the Arcadi Mainframe Report. This user survey is going to be released this week. We want to give you plenty of time over the holidays to log in and be a part of one of the most referenced mainframe surveys out there. So check social, check email, you’ll get a notice about it, and we want your feedback.
[00:02:46] – Amanda Hendley
We want to know what’s going on in your shop. And as a gift back to you for letting us know what’s going on in your shop, we will share the early complete results with you. Now we’re ready for our session. I want to thank Suzie Wendler for being here today. She’s going to present on understanding what IMS applications can do and how to benefit from REST APIs. She’s with IMS support at the Washington System Center. She’s a member of the IMS team, and her responsibilities have included customer support, critical situation analysis, and design implementations for IMS connectivity. Suzie is a wealth of information. She’s frequently a speaker and instructor on these topics. With that, Suzie, I promised I would do that earlier, but I’m going to stop my share and let you start yours.
[00:03:40] – Suzie Wendler
Okay, let me see if I can do that now. I’m going to try to set it up to where I am doing slideshow. Okay. Can you see that clearly?
[00:03:57] – Amanda Hendley
Looks great.
[00:03:58] – Suzie Wendler
Okay. Well, thank you, Amanda, and thank you for inviting me to present today. I was looking at several of our folks who are joining today’s session, and this looks like IMS Home Week. I know several of you and I thank you so much for coming in today and listening to my topic. I’m going to talk about IMS, mostly the applications in a transaction management system and some of the things that you can do with APIs, and more importantly, the things you can do in IMS applications if you’re going to open up your environment to APIs. I’m just going to skip my abstract and I’m going to go to my topic. What I wanted to do is start out this presentation with the first few slides, really discussing some just foundational ideas and then bringing into perspective zOS Connect and the IMS code inside zOS Connect to assist you in creating APIs to access your IMS resources. Then we’ll talk about the application patterns and the support IMS has in case you want to modify your programs. We’ll talk about those scenarios where you might need to modify your application programs, such as when you’re going from an IMS application out into the internet environment or into the cloud to access resources there. Then I’ll wrap with a few other things that I want to discuss. One is the ability to issue HTTP calls directly from your IMS application. Then I’ll also talk about an IMS capability that IMS provides you which is synchronous call out, which is an IMSDL1 call. Then I’m going to wrap up with just telling you a little bit about transaction orchestration, which is new for the IMS environment.
[00:05:58] – Suzie Wendler
Let’s just go forward a a little bit and talk about the IMS environment. As you look at this visual, I show you on the right-hand side of the visual information about the transaction manager, access to the IMS apps through OTMA and IMS Connect, and additionally, from IMS Connect through OpenDatabase Manager into IMS databases directly. With the infrastructure that IMS has provided, you’re able to come in with both transaction request and database request from the cloud for analytics, for mobile environments, and we positioned ourselves for the future. At the top of the visual, on top of IMS, I have zOS Connect, and I’m going to talk a little bit about the differences between OpenAPI 2 and OpenAPI 3 as far as accessing the IMS resources.
[00:06:59] – Suzie Wendler
Let’s first Let’s talk about what’s happening in today’s world. We do have, obviously, a digital evolution, a transformation evolution, and that is now driving access to your assets that are hosted in IBM Z. I have examples here. For example, if you are using your mobile device to get to your accounts or online apps to get your IMS resources. A key part of this digital transformation is application programming interfaces, APIs, and there are several of them. But the idea behind the API evolution is to allow applications, regardless of where they are in the Cloud, on Z, or wherever they are, to be able to interoperate easily and in a standard fashion. One of the things that I want to talk about is the API architecture itself. This is a framework. The API architecture actually provides a standardization. Rules and structures within a framework to allow these interfaces to be created so your applications can easily integrate. I’ve listed here the popular types of these architectures. An older one is Simple Object Access Protocol. Then you’ve got GraphQL, Apache Kafka, Async API, remote procedure call, many others. But what I’m going to talk about today is REST, and that stands for representational state transfer API.
[00:08:40] – Suzie Wendler
That is indeed a type of a web API, and it has a standardized format. It’s called the OpenAPI specification that actually identifies the protocols and the definitions for the interface so that applications can enable these interfaces to interoperate very smoothly. Restful APIs with the OpenAPI specification. There is a client app that invokes a RESTful API, and this provides both an identifier for the target resource. This is the URL for the resource, also known as the endpoint. My example here in the yellow, I’ve got an HTTP call, and it specifies the host we’re going to and the port on that host because we’re going across a TCPIP HTTP link all the way to the target where we’re going. Then we also have the operation for the server to perform in that resource, and that’s the HTTP method, get, put, post, and delete. Once the server, and for example, for us, it’s going to be zOS Connect and IMS, the server gets that. It’ll get the request, process it, transfers a representation of the state of the request, so the response, and it’s typically in a JSON JavaScript Object Notation Format. I do want to point out that JSON tends to be the most commonly used, but it can be JSON, HTML, XML, or plain text.
[00:10:24] – Suzie Wendler
Let’s look at the zOS environment. When the API environment became very popular, the Z platform created zOS Connect, and this is so that you can allow your Z resources to be part of the API economy. So zOS Connect provides seamless integration with our Z subsystems and provides that capability as RESTful APIs. The value of the Z environment, it’s fast, secure, it’s reliable, and we provide connectors to reach any of the zOS assets, including IMS. Let’s take a little bit closer look at this. In this visual, I have someone sitting at a terminal and sending in, or it could be an application that sends in an HTTP request to the zOS Connect address space. In there, the request is mapped, and it’s mapped from the JSON format or whatever format you’re using into something our subsystem understands, like IMS, something IMS understands, so our format. My example here is I’ve got a HTTP request, and it sends in the URL, sends it into the zOS Connect address space. It is transformed into something our IMS system, for example, would understand or use the zOS subsystem. And sends a response back in a JSON format.
[00:12:04] – Suzie Wendler
The question is, why would we want to do this? That is because, as I mentioned earlier, it’s becoming very popular to use REST, and it’s a simple protocol. It integrates applications very easily. What is it? It is, as I mentioned, the software architecture style of the web environment. Then let’s put IMS on top of that. I’m going to go back once. Here is the standard capability coming in where we do the mapping inbound and outbound with zOS, zOS Connect. If I put IMS on top of this, on the right side of the visual, zOS Connect communicates with the architecture infrastructure that IMS already has in place. That is our TCP/IP Socket server, which is IMS Connect into IMS for IMS applications or it can also come in with a database provider to go into ODBM directly to get to the IMS database. In my example here, I’m coming in to our transaction, IVTNO. Note that on the IMS side, it’s business as usual. It’s LLZZ train code data. But the distributed side doesn’t understand that. They simply send in an API request that that is then transformed into something that IMS understands. When the program sends its response back, that is also transformed back into JSON format by the IMS code that sits inside the zOS Connect address space.
[00:13:49] – Suzie Wendler
By the way, it’s the same thing for CICS, for DB2, or if you’re coming into MQ. The value of zOS Connect, therefore, is that it opens up your zOS resources into this new evolving world. Let’s talk a little bit more about zOS Connect and the open APIs. As I mentioned, zOS Connect adheres to the open API, the specifications that are provided. ZOS Connect lives on top or is built on top of a Liberty profile. The Liberty profile provides that integrated REST endpoint and supports the JSON notification, the JSON capability. Now, the other thing that I also want to point out is that zOS Connect is, as I mentioned, very fast, secure, scalable, and it understands all of the different components and connectors for zOS assets. It is a singular approach for all your system Z clients. Now, Sorry, I’m getting a notification here. The IMS service provider. There are two open API specifications. There’s one called Open API 2 and another one called Open API 3. I’m going to talk a little bit more about those on the next visual. But IMS has provided the code, the provider code, inside zOS Connect to understand interaction with IMS regardless of whether your zOS Connect provides OpenAPI 2 or OpenAPI 3 specifications.
[00:15:39] – Suzie Wendler
Again, on the IMS side, it’s just standard capabilities for IMS. How do we do this? zOS Connect supports those two OpenAPI standards. It’s one product, and you can define which specification you want to use. OpenAPI 2 was around for a few years, has been around for a few years. It’s called Swagger 2. 0. OpenAPI 3 is a more recent specification, also known as OAS 3. I want to point out, though, many of you have started out, if you have started out with open APIs, with the specification of API 2, the Swagger 2. I just want to point out that it is not required for you to migrate from 2 to 3. It is a choice based upon the use case. We do have knowledge centers, and I have links to information to both specifications. I want to point out that if you’ve already done APIs with OpenAPI 2, it is a bottom-up development. zOS Connect provides you with a tooling where you start with IMS, you would start with your COBOL your copy book or your PL1 include file, and we would use our tooling to generate everything that you need to expose that resource as an API.
[00:17:12] – Suzie Wendler
For OpenAPI 3, that is the meet in the middle, or first you start out with the API itself, what it looks like. Then you meet in the middle by matching what the IMS application or CICS or whichever one you’re using can provide as far as our copy book to match what the OpenAPI is expecting, both for inbound and outbound. Openapi 3, I just want to point out, has a lot more capabilities It’s much more flexible. It’s also a little bit more complex, but we support both. From an IMS perspective, I just want to show you what we already have. For OpenAPI 2, Swagger 2 with zOS Connect, iMS supports inbound to both transactions as well as large messages, and I’m going to explain what that means, as well as access to IMS databases, as well as access from IMS applications out into the distributed environment. OpenAPI 3 for IMS today supports what we call the IMS provider, which is access to the transactions and large messages and access from IMS transactions outbound. We do not yet for OpenAPI 3 support the database service provider for IMS, but I hear that’s coming and hopefully sooner than later.
[00:18:43] – Suzie Wendler
But I just I’m going to point out what is there today. Then the question is, do you need to modify your IMS applications? I put in green that in most cases, if you’re coming inbound to IMS, no, but it depends upon the application access patterns. It’s always…It depends. In red, I have yes, this requires modifications to the program. If you’re going from an IMS application outbound to invoke a transaction, excuse me, a resource that is distributed. Then the IMS database service provider, we don’t have… IMS applications aren’t involved. So you don’t have any requirement to modify the IMS application. At this point, I also want to point out that for the rest of the presentation, since I do have a limited amount of time, I’m really going to talk about the service providers for IMS transactions. If you need more information about the specifics of the database service provider, let me just say this. You can contact me. You will get my email from the PDF file that Amanda is going to send to you. You can contact me and I’ll spend more time with you on the database service provider in OpenAPI 2.
[00:20:09] – Suzie Wendler
But just to let you know, the tooling for the IMS database service provider specifies that you give us an SQL call to access the IMS database because we’re going directly to the database. Under the covers, we have all the IMS code that we’ll interpret I’ll put that to a deal when call. How you can create the SQL call to access that IMS database to put into the tooling is through another tool that IMS provides you, which is the IMS Explorer for Development, which has a query builder in it and that can build the SQL calls. But again, that’s all I’m going to say about the database service provider today, but you can always contact me and I can spend more time with you on that. The question was, do your applications require modifications? Well, it depends. The questions are, do you need to or want to streamline your existing program since you’re exposing the application to REST APIs and maybe you want to make it a lot better performer than what you have today or you just want to modernize it? Then you can modify it, and I’ll tell you about a couple of things you can do.
[00:21:28] – Suzie Wendler
However, you don’t have to in most cases. But if you want to leverage enhancements for new functionality, like send in a data structure request for greater than 32K or large message, again, that might depend. I’m going to show you that. If you’re going to call out from your IMS application to an API, then absolutely, you’re going to need to modify that application. I’ll show you the tooling and what you’ll need to do with that. Let’s first talk about large data structures. At the bottom here, I just want to show you that the idea is to allow an API to send a large message in. Let’s say it’s 96k inbound and then receive 64K outbound. So one large request in and one large request out. The idea here is to allow our service providers for IMS to be able to take that large message and segment it into the max segment size that IMS supports, which is 32K. So send that in. And then when the response comes back out, also in 32K chunks, our provider will de-segment it into a large message it’s sent back to the REST API. What happens in the IMS application environment?
[00:22:58] – Suzie Wendler
First of all, if your IMS application is already multi-segment, so message type multi-seg, and issues get unique and get next to retrieve a large message, then you don’t have to change it. Because remember, in the message queue, those messages have already been de-segmented. On the outbound side, you just issue insert, insert, and our code will de-segment that into a 64K chunk. Otherwise, if it is not, if it’s single segment, then you’re going to have to modify the program, either define it as multi-segment and issue the getUnique getNext calls, or an alternative is to leverage the utilities that are provided with zOS Connect and IMS for COBAL or PL1. What you would do is just call those sub-routines, that code to issue the getUnique getNext for as well as to insert and to do the insert. If you do that, then obviously, you can change your program. But more information about that. I have links to how you would do large messages for OpenAPI 3 specifications or for OpenAPI 2, and those are at the bottom of the visual. If you’re going to do that, if you’ve got large data structures, here are some recommendations. First, review your IMS application environment to determine the value of what you’re going to be doing.
[00:24:36] – Suzie Wendler
Because what we’ve discovered is sometimes people were complaining because they said, oh, because IMS is 32K chunks, I have to do send, send, send of 32K chunks. Well, let’s just send it as one large API message, inbound and outbound. Also, ensure the IMS application is multi-segment. It has to be defined as multi-seg, and your application does get_unique, get_next_calls, or replace with the code that’s provided with zOS Connect for IMS. Again, use these for large messages. Here’s another question. I’m going to go back to here, and those are the recommendations for large message structures. Again, if you have questions about that or want more information, just please let us know, and we’re always happy to help you with those. Here’s another one where we do require modifications. This is if your application program in IMS is the client. I’ve got two visuals here, one for API 2 and one for API 3. If you are going to call from your IMS application outbound, we do have tooling. zOS Connect provides a command-line build toolkit called ZCONBT. It can either run on a Windows environment or it can run on your zOS environment. But the point is that the tooling allows us to generate all the code that is going to be needed for the IMS application program as far as copybooks and the information to understand that we’re going outbound.
[00:26:30] – Suzie Wendler
ZCONBT will generate the request and response copybooks for COBAL and or PL1, and then information about the API, a copybook about that, and then a configuration file the ARA file that you’re going to put in a zOS Connect. Once that’s done, you have to take all of that, bring it up to your mainframe environment to where your IMS application is, and update the IMS application program program to be able to use those copy books and to issue the calls. Then we’d have to compile and bind the program and then set up the IMS dependent region. I’ll show you that shortly, because you have to have LE-run time options and specify a POSIX to be turned on. Then we would need to deploy the ARA file that was generated by ZCONBT and deploy it directly into zOS Connect and then from there also configure the endpoint from zOS Connect to the external API. Those are the major steps that you would need to do for OpenAPI 2. If you’re OpenAPI 3, there’s a different tooling. It’s a little bit more complex because there is a lot more flexibility that is provided with OpenAPI 3.
[00:27:57] – Suzie Wendler
First of all, you would generate the code that we would need with a Gradle plugin. It’s a zOS Connect Gradle plugin, and it generates not an AR file, but a WAR file, a web archive file for zOS Connect, and the API code from the OpenAPI document. Once that’s done, that’s brought up to the application program, and the application program would actually have to issue a few more calls than we would in the OpenAPI to specification. We actually have the ability to do the initialization, the execution, get next of the data coming in. Then we would have to set up the IMS, dependent region, LE Runtime, and options and POSIX. By the way, this would be the same region that we would have for OpenAPI 2, configure the HTTPS endpoint and from zOS Connect. If you want more information about this, there is a lot of information that our zOS Connect folks provide. There are classes and workshops for both OpenAPI 2 and OpenAPI 3. The dependent region setup. First of all, when you compile and bind, and I have your COBOL version for or creator, make sure you include in the yellow highlight here on the left, your zOS Connect library.
[00:29:38] – Suzie Wendler
Then include, if it’s OpenAPI 2, B-A-Q-C-Stub, or for OpenAPI 3, it’s going to be B-A-Q-H-A-P-I-W. Those are the API, the different calls. I just show you at the bottom here what is in SBAQ Live that your application program is going to need. Then the dependent region set up. You have to specify LE Runtime Options, either in C-E-E-O-P-T-S. Either a DD statement that we point to a member, you have it in your LE Runtime library, or you can do in-stream, like I show you here with a CEEOPTS DD asterisk. The one Another thing that I do want to point out is that while you are testing, make sure that you specify in the environment variables, BAQ verbose on. That is just so that you can see what’s happening, so you’re not surprised if you get a different admin code or a different condition code. Baq verbose will provide for you information information about what your application program was doing. Then, of course, you have to specify POSIX on. Very, very key. Let’s talk about some recommendations here. Pre-loading Note the program that issues the API request or call out. Note that your run time option of your COBOL, RTE reuse, should not be used.
[00:31:25] – Suzie Wendler
There are problems when that happens. Set TLIM equals 1, if there are any abends, then the NPR is automatically terminated. Because if you have TLIM greater than 1, a pseudo-abend could cause some issues. Make sure you’re up to date on maintenance. Very important. Because you enable POSIX in these regions, you might want to seriously consider creating new regions for this environment. Management. The reason for that is that if you have transactions that are non-POSIX, like your more traditional IMS transactions, that run with this new program now that requires POSIX, you can run into problems. Just fence this environment, create some new dependent regions, and also a COBOL run time option of reuse causes problems with POSIX. With all other IMS applications that go outside and API requestor being no different than synchronously calling out. Consider creating a class and specific dependent regions for this program, as I mentioned, to facilitate also problem determination if the program stays hum. Any database calls that were issued prior to the API request, remember, it’ll hold locks. Even if it’s a read, it’ll hold a read lock. If it’s an update, obviously, it will hold an update lock. If you are doing database calls and then issue the call out, regardless of how you do this, you could hang other applications that are trying to get to that data.
[00:33:18] – Suzie Wendler
If the database call was a read, consider using the release call, the DL1 release call, which releases database read locks. If you bear with me, I talk about more of that later in the example. Those are the considerations for API requesters. By the way, that’s true also if you’re doing iCall or if you’ve opened up your application program and are doing MQ, open, then put, and get, if you send a message and then wait for a response. Anything that’s going to hold the dependent region occupied. The other thing is, as I mentioned earlier, BAQVERBOSE allows you to see what’s going on. Here’s my example. I have it on the right. I specified BAQVERBOSE. On the right side, when I look at the dependent region, it shows me exactly what’s going on. That could be very beneficial if you’re doing problem determination. That was what we have for API requestor. But now, what about inbound? How about the implications for applications? If all you’re doing is creating an API to access an IMS transaction resource. The question is, what can you do in this environment? And how can you really make sure that if you have the ability to modify the environment, if you’re running into problems, what you maybe should consider doing?
[00:34:56] – Suzie Wendler
First of all, let’s look at the access patterns. See, your existing application integration patterns. There are several. I’m going to go through these and the implications of these. If you have a distributed program issuing an API call to access an IMS transaction. Very simply, if it does a send receive, so it’s waiting for a reply, what I have in yellow here are the different patterns of your IMS transactions, since your IMS transactions probably have been around for a while. One of the things that I do want to point out at the very bottom here on the send receive CM0 in red is IMS introduced, and you may or may not realize this, a function called send ALTP, so that if you have a distributed API or distributed program coming in waiting for a reply, and your IMS transaction simply does a get_unique_ALT_PCB and insert_ALT_PCB. What you can do is with this function is you can tell IMS to send that ALTPCB output back to the waiting program. Otherwise, you’ll get some an error condition that you terminated this transaction, didn’t send anything back out. This will allow us to send the ALTPCB output to the waiting program.
[00:36:35] – Suzie Wendler
Let’s talk about the simplicity or complexity of the IMS transaction interaction. First of all, if you have a simple interface that’s simply where the application in IMS receives the program, does it get unique, and then insert IOPCB. Or if you do get unique, insert ALTPCB, but the The person that receives the ALTPCB doesn’t insert IO-PCB, that’s fine. Your receiving program will send the message into this environment and receive a response. The note that I want to put out is that when we’re creating the API response or when we’re using our tooling, the tooling is going to ask you to provide a layout of the input message and an output message. In the example on the left, that’s easy enough, it’s easy enough. It’s the same program. For the answer in the right, you have to have the output response layout from the second program, the one we switched to. Also, for this simple interaction where you don’t have to change anything, your RMS transaction needs to be non-conversational. We have access to the input/output message layouts, and any program-to-program switches, like the example on the right, is done with a non-Express ALTPCB, and that last transaction does respond to the IOPCB.
[00:38:09] – Suzie Wendler
What could cause complexity in this environment? No available copy books. Well, Hopefully, you can create it or you have those copy books. If you don’t, then you’ll have to analyze the messages in order to create a copy book that we can give to the tooling. What about if you’re going to do program-to-program switches? How do you determine the flow as to which program is going to be the final switch to program for the output? First of all, very important, your IMS application architects need to be involved in this flow. What can be done if you’re not really sure, then you can execute a transaction flow in test and analyze the 03 log records, take a trace, analyze the trace records, or use tooling. Here’s how we do this. If you’re going to do it by hand, so log record analysis, run the IMS utility, DFSERA10, Exit, DFSERA30. I’ve got examples here of the options that you would useA when you run that program to get the 03 log records. Then you get the log records, you will also have to assemble the IMS Log Rec desec so that you get the record layout and then use the record layout to analyze the log records.
[00:39:40] – Suzie Wendler
I know a lot of people have done that, but if you have a tool like problem investigator that can analyze the log records, then it is much easier to go through the output because it just really lays everything out. The examples I use in this presentation on the tooling are IBM tools like IBM IMS problem investigator. But that’s not to say that other tools from other vendors can’t be used, and they definitely can. Just whatever tooling you have to analyze those records. To make it easier. Here’s another complex problem. If there are problems and the application advance or does this, get Unique IOPCB terminates, your REST API may receive an unexpected response response, and you’ll get a DFS2082 message. So your API, when you’re building it, needs to anticipate the fact that it can get error indicators rather than the output message. So design your REST API for those conditions. Always designed for error. Another area that we looked at and that we had some issues were with what if your API sends a message into your IMS application and your IMS application needs an outtern name? It has code in it because it was written in the days of the 3270 interaction world, which still is there, like, for example, the Telnet, but your application is now also going to be implemented to support APIs, then determine if it can use a generic L term name.
[00:41:31] – Suzie Wendler
Ims and zOS Connect providers provide you with the ability to provide a generic override name coming in from zOS Connect into IMS with a generic override name. If you can use that generic name, that’s great. Otherwise, you would have to maybe consider something like this, a little bit more complex, but I know there are a couple of you on this call that have done this in your shops, and that is to put information in the API as part of the payload. Maybe right after the trancode, you have some indicator, like an asterisk, something asterisk with a name. Then what you would do is put in the connection profile for zOS Connect a name, a generic name that can be recognized by one of our exit routines to come in, take that L term name out of the payload and put it into the control block for L term name, and then shorten that message by the amount of that L term name to pass into the this application program. That is a possibility. If you need more information about that, let me know. Here’s another one. We discovered people were saying, I’m just doing a very simple TRAN_C to TRAN_D program to program switch.
[00:43:06] – Suzie Wendler
I’m following the rules. You said in the simple interaction, this would be supported. But now I’m seeing that I’m just hanging. Nothing everything’s coming back. In that case, check and see if that ALTPCB is an ExpressPCB. If it is, change it to Non-Express, and it’ll work just fine. The Express-PCB It says that it’s sent, and that application, TRAN_D, can start processing even before TRAN_C has been able to pass a responsibility for the response forward to TRAN_D. Don’t use ExpressPCB if you have this scenario. Then we have this other scenario, very typical in your IMS world. Which transaction, if you’re doing multiple program-to-program switches, which one should respond to the outstanding receive because only one IOPCB output reply, the insert, will be sent to the waiting program. We have a parameter called OTMA-AS Y in IMS to determine which transaction, C or D, in my example here, should respond to the outstanding wait. If you say Y, then it is the first response program scheduled. If neither C or D is a response mode, they’re both non-response, then you can specify N, which is a default. It’s the first program, response or non-response, response that’s scheduled that will respond to the IOPCB outstanding weight.
[00:44:51] – Suzie Wendler
Or S is the first message inserted to a non-express of PCB. This is from the insert from the trend D side, will be scheduled synchronously. So consider using OTMAASY. One of the things that I mentioned here, for example, if you say Y, it’s the first response mode, or you can say whichever is the response or non-response. What you can do in IMS, remember, you could have multiple Transact codes for an application program. For example, if you see C and D are both non-response, but you do want C to also be both response and non-response. You can create a new transaction code, let’s say CX, and that would be used for the insert ALTPCB from TRAN_D and create TRAN_CX to be a response mode in your definitions. We also have a DFSMSCE0 exit routine, can change a destination TRAN code. If you don’t want to change a C program.
[00:46:02] – Suzie Wendler
Overall recommendations. Make sure you understand the application architecture. It’s simple. You have to anticipate complexity or potential show stoppers. We do have log records, traces, or tools that can be used for tooling. You have IMS Connect extensions or other vendor products that are equivalent to this. You’ve got problem determination tools. Again, I’m mentioning the IBM tools here, but other vendors provide different tools. For zOS Connect, there’s a Omegamotn for JVM, can monitor your zOS Connect API utilization. z APM Connect can be used to determine target or problem areas. There are a lot of tools in this environment. Also, zOS Connect, they’re different log files. Openapi 3, when you’re creating things, it does have a log file, but the servers themselves also have the ability to trace and to create logs as far as the ability to provide you with the ability to figure out what’s going on. I do this a lot when I’m running into different problems just to help me do problem determination. Now, let’s look at what IMS has had for a while for transactions for applications. This has been around a long time, SETS, SETU, and ROLS. I just want to remind you it’s there. If you’re opening up your IMS application, just remember, we do provide intermediate backup points for IMS resources. If you have unsupported PCBs, like a DDB or access to DB2, set-you will set an intermediate backup point, and then you can back out to that backup point with a role as.
[00:48:06] – Suzie Wendler
Set as is for IMS full function databases. Consider if you have logical units of work within your IMS application. Here’s my example. I’ve got a program. I can do a SETU with token A. The program updates your IMS resources and also then issues a DB2 call. When it tries to get to DB2, DB2, it gets an error. Then what will happen or it gets an error, it attempts to back out. What your application program can do is do a row less to token A, and it backs up to that point. Then you can decide what you want to do because now the program realizes it can’t call DB2. Again, it gives the program control back and continues processing. How about the release? I mentioned this earlier. This provides you with the ability to release an IMS database read lock. If your application program has read IMS databases and then is doing an API requestor or an I call or some other call outbound that suspends a program waiting for a reply to come in. The release call will set you up to be able… I apologize for that. I didn’t turn off my speaker.
[00:49:32] – Suzie Wendler
But anyway, the program… Here’s my example here. You’ve got a program, it reads IMS databases, and then prepares the message for call out, whether you’re using API requester IMS ICAL, MQPUT, MQGET, which will hold the dependent region occupied. If you issue the release call, it releases the read locks and also the positions in the database. If you need that position again, make sure you keep the information on the positioning, then release the database read locks so that you’re not holding those locks for other application programs that are running. Then after you get the message back, reposition back on the database and continue processing. But remember, when you’re doing all of this, especially if you’re going outbound, it’s not just your program that’s accessing those databases. There are also other IMS application programs, and you don’t want to impact them. How about determining availability of IMS resources? We’ve had these for a while, and people sometimes forget application developers, if they haven’t done this in a long time, forget that these are available. But if you’re going to open up your IMS application in order to provide greater performance capabilities or to streamline those, then you can do a couple of things.
[00:51:02] – Suzie Wendler
Automatically, add IMS program entry. IMS, under the covers, issues a DBQUERY and initializes the status code for each DB PCB, and you can look at those. Also, if you have an IMS application program and you’re not sure if it’s going to be accessing a database and you don’t want the user 3303. abend when the database is unavailable, you could issue an in its status Group A or Net Status Group B. Net Status Group B also takes into consideration the IMS Deadlock. You’ll either get a BA or BC status code, but the application program still has control. If you’ve done database versioning, then you can find out what version of the database you’re trying to access. If you need to know other information, IMS is the inquiry call, and we keep adding information to the inquiry call. First of all, if you do an inquiry, and it’s just blanks, it’ll be related to either the I/O or ALT PCB, and it includes information, for example, TPIPE, member name, user ID, user ID indicator. If it’s ALTPCB, it will provide you information as to whether there’s a status of started or stopped. A lot of information about your I/O or ALTPCB.
[00:52:32] – Suzie Wendler
You can also issue the DBQUERY call from the inquiry call. After a DBQUERY, then you would do a find to get the PCB address in order to analyze that code. Now, the ENVIRON and ENVIRON2, these are the ones that we’ve added a lot of information to. If you issue inquiry ENVIRON, it’s about the execution environment of your application program program. You have things like IMS ID, control region type, region identifier, PSB name, whether a Group A or Group B was requested, a lot of information about the environment. The ENVIRON2, is newer, and it includes information from environment, but then it also includes the application parameter string in your dependent region If you specify APARM, that is a parameter that can be passed to the application program, make me unique to this execution environment. The ENVIRON can access that, which is really critical for some environments where they want to process something differently depending upon where the dependent region, whether or not the dependent region specifies that. We can also find out about the LE Runtime options. You can do an Inquiry LE run up, and you can do an Inquiry program. More importantly, another new thing is we’ve got Inquiry message info regarding the current input message.
[00:54:15] – Suzie Wendler
In IMS 15, you can actually request if you have enabled Network Security Credential Support, which is a distributed client’s end user identity. This It can be passed into the input message. I’m not talking about your RACF user ID. I’m talking about the distributed identity once we have enabled a network security credential support. This can provide that information to the application program. If they need to do that, you can do things like log it or have different code based upon where that message came from. Again, many things to consider with the inquiry call. I know I’m going pretty fast through all this, but the point is there’s so much to consider. Again, and I’ll keep mentioning this throughout. If you have more questions or want more information, please let me know. The AIB. AIB has been around for a long time. I think it was since IMS version 3 days. This is used when a function does not use a PCB, like inquiry ENVIRON, or when the application does not have a PCB address. This is simply the fact that you can access that resource, like even a database resource, if you’ve given it a label, the AIB call will be able to access a resource by its label.
[00:55:55] – Suzie Wendler
Again, remember, the application interface block is a way that IMS is provided for the application to communicate with IMS about information in its environment. There’s a lot of information that I’ve given you, again, in the application program. Do you have to change your application program? No. Unless you want to take advantage of the fact that the application is now being called from new environments. I think that’s really important to understand what can be done. I’m actually also going to address a question that came in prior to this presentation. Someone had asked if I was going to talk about change data capture. And the answer is no, not today. I’m going to mention it, so I don’t have any visuals on it. But again, that’s an entire topic in itself. But change data capture exits can be written in in high-level languages. It doesn’t have to be an assembler, but they can be written in COBOL, cetera. They are an extension to your application program. They are called if you have modified data, like a segment, you can define the exit routine in your DBD, for example, either globally for all segments or on a segment.
[00:57:25] – Suzie Wendler
If information in the segment has changed, we’ll call that exit routine, and that exit routine itself can issue different things. It can even issue a call to DB2, it can issue another IMS application call, or in CDC, a lot of times, we’ll just log the information, and you have a lot of different products that can take that changed information and send it outbound. Let’s talk about other things that you might want to consider. Syncronous program switch. The IMS introduced the ICAL to go outbound, but it also introduced the ICAL a support to do a program-to-program switch to call another IMS application program. My idea here is if you’re coming in from a different environment, let’s say an API coming in to an IMS dependent region, and that IMS dependent region recognizes that it needs information for another IMS application program, you can just do an IMS synchronous program switch, which calls the IMS transaction and it suspends the calling program, runs the IMS application, and then comes back. This is the format of the ICAL. It’s the AIB interface. But now instead of going outbound, we’re just calling another IMS application program, waiting for it to complete, getting the output response back to this waiting IMS program, and then continue on.
[00:59:14] – Suzie Wendler
We do have a sample program in the SDFS iSource library, and the sample is DFSYSYPS, synchronous program switch. A couple of design considerations. If I have an IMS application program, and now I’m going to call another application program, then there are a couple of design considerations. If I spawn it, which one should have the responsibility? Do I have a specific LTERM need that I have to mask the IOPCB to determine what to do if there’s a late reply? We can control all of that with the OTMA destination descriptors. So I don’t want to belabor the point here. I put a lot of information on this visual to address each of these design considerations. Again, this is for the synchronous program switch. I know a lot of people have implemented synchronous program switches very successfully. But why do I want to point it out in this presentation? Because it can enhance your IMS application infrastructure, and it can allow you to create a process server or broker app inside IMS itself. This would be a new one. It would be relatively simple in the sense that we’re not calling databases here. We’re simply retrieving a message, calling another IMS app, getting the message from the other IMS MPP, and determining what we want to do with that, and then calling other programs.
[01:00:55] – Suzie Wendler
In my visual here, I’ve got someone coming in with a a single API call or a single call to IMS Connect with an input copy book for this new program, and it could be the input copy book for the first MPP, like MPP1. This new broker program would issue the ICAL, send the exact message to MPP1, receive the reply, and then decide if it needed to call MPP1 again, or it could call another MPP, and it could be another IMS in a shared cues environment or even across an MSC link to get the response back. Then what this program can do is determine what the output should look like and send it back. In the design of this, you would have to design what the initial input message should look like and what the expected output message should also look like. Again, we can create this concept inside IMS. I think I want to also briefly discuss. I’ve got a few minutes here. I want to briefly discuss other things for this environment. First of all, zOS has provided added as part of zOS, a Client Web Enablement Toolkit. If you have folks in your shop that like to code to HTTP verbs, are familiar with it, or if you want to learn how to do it yourself, your The IMS Application Program can itself be the HTTP client and go out into the cloud, out into somewhere, an HTTP server, and get the response back.
[01:02:41] – Suzie Wendler
The toolkit provides application lightweight APIs to allow our program to issue the HTTP calls and also a JSON parser. What I also want to point out, if you look at this picture, the HTTP toolkit, just to let you know is what is the underlying factor underneath zOS Connect API requestor. This is the same idea, but it is more bare bones. This is one that you would have to code yourself. Your client, your IMS application, would issue an HTTP request to a server, get put, post, or delete, define the headers and the request body, either put or post, and then receive and reply. Including understanding status codes, response headers, and response bodies. If we open up that web enablement toolkit, it consists of both a protocol enabler, and I have a link to a shortcut link, an IBM Bizlink to explain the protocol enabler, as well as another shortcut to the zOS JSON Parser. I have here on the right side the APIs that calls to all these different services. This supports your programs that are written in C, C++, COBOL, PL1, REX, and Assembler. Do we give you samples? Absolutely. In SYS1.SAMPLIB depending upon what language you want to issue this from, we give you samples.
[01:04:26] – Suzie Wendler
Then we also give you detailed instructions to get you started. I have a link to GitHub that shows you how to get you started and enabled with HTTP calls directly. What’s the value? It’s delivered as part of zOS. You don’t have to install anything else. HTTP might be familiar to some of your distributed developers or some of your mainframe developers. We do have assistance with callable services, and we do a direct connection to the remote server. No intermediate hops. We don’t go through IMS Connect, we don’t go through zOS Connect. We go directly. So your considerations is your application will need to be coded to make the calls. It does run with POSIX enabled. So that same thing we talked about before is that you might want to fence this application and put it in its own set of dependent regions. Application is in a blocked weight. So if you’ve got database calls, be aware of the implications of those, and understand that IMS doesn’t know what’s going on in this environment. It is unaware of the interaction. I also want to mention, I talk about program to program switch, but I just wanted to remind you that for a long time now, IMS has the ability to be a full partner in integrated hybrid clouds or the DL/1 ICAL.
[01:06:00] – Suzie Wendler
This is a call that is issued with an AIB to DL ICAL. The IMS app is unaware, really, of what’s going on in this environment. I’m sorry, the IMS app, it just sends it out. Ims takes that ICAL, creates a correlation token, sends it out, and waits for the response to come back with a correlation token. Because you have multiple IMS application programs that can be provided at the same time, we have to have that correlation token. When the message comes back, we know which specific instance of a dependent region application program running in the dependent region to send that back. It is issued with an AIB call, send, receive, or receive. Let me just show you this with the AIB call. We do have documentation, and I have a shortcut, IBM Biz shortcut to the doc and to samples. There are samples. Your IMS application program which is modified to do this, uses the neratinib interface. My example here is a COBOL example, where in the AIB, we define that the resource name, the destination is test out. What that means is that you will have to have an OTMA descriptor in the DFSYDT member of IMS PROCLIB.
[01:07:37] – Suzie Wendler
My example here shows you that I’m going to test out. It is going out to an IMS Connect to a team member, HWS1 in a specific TPIPE. Then the rest of the structure here is the call-out message and the response. Now, I want to show you this example. I have an example here, and this is just broad examples. I do an I call with a sub function of send receive, and I get a message back that says, oh, you got the message, but you have an AIB return code reason code of 100.0 Charlie that says, The message came back. It’s too big for the length area that you provided. IMS will keep that message in extended region private. Then that allows It allows you to issue another ICAL, if you get that AIB return code reason code, to issue a receive. We don’t go back out into the network. We simply receive the message with a larger response area length from our extended region private where IMS has kept the response reply. Then for the remote client, I do have an example here. I’ve got doc that shows you how you can either write your own client at the very bottom or depending upon what you’re using, we have different links for the different types of clients that are provided that understands this functionality.
[01:09:21] – Suzie Wendler
If you’re writing your own, then you can take advantage of the IMS Connect API Java support. But basically, you do a resume TPIPE, you get the message, act back, and then preserve that correlation token. When your client is ready to send back a response, it has to add that correlation token back into the response message so that we know how to deliver it properly. I have one more thing I need to tell you. I know I’m telling you a lot of stuff, but one more thing. We have a new function, and it’s called transaction orchestration. This is the ability. We’ve been talking about synchronously an IMS application, synchronously going out waiting for a response and then sending the response back. There are different ways you can do this, asynchronous call, but IMS has provided the transaction orchestration support. Here’s my example. I come in from a distributed client, send, receive, and it’s sent to IMS to a transaction A. Transaction A says, I need to go outbound asynchronously. I’m not going to sit here and wait for the reply. I’m going to go outbound asynchronously, get the response process. If the response comes back, and since TRAN_A is gone, it could be another instance of TRAN_A, it’s probably TRAN_B, it comes back.
[01:11:02] – Suzie Wendler
But IMS cannot send that reply back to the waiting IMS Connect client on the left side. What transaction orchestration provides, and these are the APARs and associated PTFs. By the way, definitely, since this is new, we can provide you more information, more presentations on transaction orchestration. This is just an example. This just says that when transaction orchestration is defined, and we have specifications and definitions and even exit routines that can support this, when the message is sent into IMS, let’s say MPP1, it issues an ALTPCB, and we go outbound, let’s say through IMS Connect to an external processing system. When the message comes back, we understand that this destination is going to be back for the initial client. This can be done via descriptors or a destination resolution exit after we have implemented this functionality. I know this is very sketchy as far as giving you the examples. We have different scenarios for this. The point is that your IMS MPP can asynchronously send a message out, and that reply somewhere outside IMS can come back to an IMS environment, and IMS can send a message back to the waiting client on the left side.
[01:12:42] – Suzie Wendler
This does support MQ. It does support IMS Connect environments. It supports shared queues, front-end, back-end. We have a full function capability, full functionality capability for transaction orchestration. Again, we are happy to spend more time with you on this if you’re interested in the transaction orchestration solution. I am seeing that I’m getting to the end of this presentation. I just want to let you know that my intent was to provide you a focus on the IMS application programming environment. Now, what’s important here is that please note that we continue to evolve. IMS is constantly evolving the functionality in the product as well as integration into the product for new environments. You can leverage the old, which, as I said, is still very applicable. Set us, set you, roll us, release, ICAL, OTMAASY exit routines. A lot of that is still there and can definitely be leveraged in today’s environment, and the new, which continues to expand to REST API. Sorry, to REST API functionality. That really brings me to the end of this presentation. I’m going to stop sharing. There are some questions, right? Okay, Denise, VAQVERBOSE. Maybe I’m not really sure what the question is. Are you still on?
[01:14:40] – Suzie Wendler
Suzie, it wasn’t really a question. It was a comment. You said to turn it on, and we have it set the error. Okay, so you’re only turning it on for error. Actually, that’s really good. Thank you. That’s actually really good, Denise. I really appreciate that.
[01:14:58] – Suzie Wendler
No problem.
[01:15:02] – Amanda Hendley
If anyone else has any questions, you can drop them into chat.
[01:15:11] – Suzie Wendler
Okay, so Amanda, I will send you the PDF files and then you… Is the deal that you ship it out to everybody?
[01:15:18] – Amanda Hendley
We post it online.
[01:15:20] – Suzie Wendler
We post it online. Okay.
[01:15:22] – Amanda Hendley
Once the video is ready, we post it online and we let everyone know that they can access it. And we do a recap newsletter, which you all should be getting since you have participated in the session.
[01:15:38] – Amanda Hendley
Well, thank you.
[01:15:40] – Amanda Hendley
Yeah. Well, thank you, Susie, for this session. I hope my screen is sharing appropriately. It looks like it is. Thank you for providing this information and then for offering the DAK app. I think it’ll be really valuable for people since you walk through a lot of in-depth content. I don’t have I have a lot of new news or articles for you. I did pull, if you’re… I just realized I’m not screen sharing correctly. Hold on one second. I did pull a documentation from IBM on REST API Basics. If you’re interested in going down that rabbit hole further and just seeing all the things you can do. And then if you are looking, there is J. P. Morgan is hiring for multiple jobs requiring some IMS skills, so you can check that out. As always, and let me make sure if any final questions are coming in that we’re seeing those.
[01:16:41] – Amanda Hendley
As always, we ask that you connect with us. We are on X, Facebook, LinkedIn, and YouTube, but LinkedIn is going to be your best place for up-to-date information and conversation, back and forth. Let’s see. Our partners for this session again is BMC. Suzie, I see a note from Pete coming in.
[01:17:10] – Suzie Wendler
You can check that out. Yes. If you come in for… What I’m IMS Connect supports a message coming in, and that message can be EMH. Where a lot of people get confused is MSDBs, and we don’t really support MSDBs with a lot of our different our new integration capabilities. I will say hi to him. Thanks, John.
[01:17:41] – Amanda Hendley
The last thing I have is our next session. We’ll meet February 11th, where we’re going to talk about the IMS catalog implementation using Ansible playbooks. I hope to see you all in a couple of months. If we don’t talk in the meantime, Suzie, everyone attending, you all have a wonderful holiday season.
[01:18:04] – Suzie Wendler
Thank you. All right. Have a good one.
Upcoming Virtual IMS Meetings
February 11, 2025
Virtual IMS User Group Meeting
Deal with growing cybersecurity risks and do Real-time and after-the-event IMS analytics, all at the same time
Sahil Gupta
Senior Product Developer
BMC
Santosh Belgaonkar
Staff Specialist Product Developer
BMC
June 10, 2025
Virtual IMS User Group Meeting