Planet MVS Planet MVS Dave's IPCS Page VERBEXIT

Dave's IPCS page :: Verbexit
Dierdre: What exactly were you doin' back here?
Sam: Lady, I never walk into a place I don't know how to walk out of.
-- From the movie Ronin

Writing IPCS Verbexits in Assembler



I guess most sane people write dump analysis code in Rexx and if you're one of them, this isn't the page for you. If you don't know what an IPCS verbexit is, read no further.

The Assembler samples and source programs here will probably not work without tweaking. They are meant to be examples and not guaranteed even to assemble succesfully. They are provided to help you see ways to use the IBM APIs.

The Basics

You communicate with IPCS using the ABDPL control block which is passed in register 1 on entry to your verbexit. It is mapped by the BLSABDPL macro in SYS1.MACLIB. You will use this control block when you write messages out to IPCS output, read storage, do symbol processing, etc.

Hello World

The dreaded "Hello World" program. This is the most basic IPCS verbexit: it prints one line on the IPCS output area. This isn't meant to be useful, it just shows how you put text into the IPCS output.

Source is ivxHello.

Access Storage

Now we add accessing storage in the dump by displaying the system name from the MVS CVT.

Source is ivxSName.

I've found that each time you invoke the ADPLSACC service, it uses the same buffer as before. So you will want to save any information obtained from the ADPLSACC call before calling the service again.

Process the VERBEXIT parameter list

You can optionally give some text to a verbexit: 
IP VERBX MYEXIT 'parameters'
Here is same sample code to get to the parameters: 
        L     R1,X_ABDPL                  Locate ABDPL                     
        SLR   R3,R3                                                
        ICM   R3,B'0011',ADPLOPLN-ABDPL(R1) Get length of parms
        JZ    none               
        L     R1,ADPLEXT-ABDPL(R1)       ABDPL Extension          
        ICM   R2,B'1111',ADPLOPTR-ADPLEXTN(R1) Get addr of parms     
        JZ    none

Sample subroutines

Here are some helpful subroutines to use in your IPCS verbexits. Some of these examples work because of assistance of Bob Wright, the author of IPCS, who was very helpful in personal emails to me and to the IBM-Main newsgroup. I share these to help others.

These are examples and may not be the optimum way of doing things, they are a way of doing this. They will take tweaking to work in your program.



Create_Equate

 You can create your own equates to save values for easy access later in the dump analysis. You use IBM's ADPLSEQS service routine to create equates in the dump.

Get_Literal

 Your dump will have a number of equates and your IPCS verb exit can get their value by calling IBM's ADPLSGTS service routine followed by calling the ADPLSSYM service routine.

Get_Dataspace_Storage

 Retrieving storage from a dataspace into a local data area so you can process it.

I probably figured out how to do this from this Robert Wright post on IBM-Main.

Get_NTPair

 IBM has a nice API for sharing pointers to data with the Name/Token pair. These pairs are at the system, home (address space) and task levels.

Although I've had good luck find the name/token pairs when not setting the NTKPLCODE value, it's probably best to set it to the task, home or system level in case there is a pair with the same name at an unintended level.

Invoke_Command

 Sometimes you would like to invoke IPCS commands to include their output in your verb exit's output area. This is done by calling the IBM ADPLSECT service routine.

CB_Format

 You can create control block models for your own data areas that display like the "CBF" command, for example: "CBF CVT". When you want to display them in your verbexit, you can use the ADPLSFMT service


Return to the main IPCS page.

Last Updated: 2009-06-19
This web page is © 2009+ by David Alcock. All Rights Reserved.