Skip to main content

IBM Systems  >   z Systems  >   z/VM  >  

Description of CPGRAB

Download count: 12 this month, 3951 altogether.

Downloads for CPGRAB:
VMARC archive: v-13K

The essential files in this package are

  • CPGRAB ASSEMBLE -- Source code for a CP exit.
  • TDGMDLAT MACRO -- Extra xxxMDLAT MACRO for use in assembling CPGRAB ASSEMBLE.
  • GRABR REPOS -- Message repository used by CPGRAB ASSEMBLE.
  • CPGRAB TEXT -- Assembled version of CPGRAB ASSEMBLE.
  • CPGRAB DESCRIPT -- This file, a description and explanation.
The author of the program and documentation is Tim Greer.

The CPGRAB package is a demonstration of what I think is a really remarkable capability of VM: CP EXITS. (Added in Version 2, Release 1.0) Without changing CP code, or even re-IPLing the system, you can add and remove function to/from the guts of the operating system! In this package I give you a very simple do-nothing addition, but with a little imagination you can see ways to expand it. I put together this package because I have encountered several instances where I or some other person had a good application of CP exits, but lacked time to learn how to create and use them. We needed a cookbook at the "How to boil water" level.

The files included in this package allow a class A user to add the CP command GRAB to the system. GRAB gives you different responses depending on your input parameters (actually, just the first three letters). That's all GRAB does, but obviously you can change CPGRAB ASSEMBLE to make it do more. You would also want to change the message repository, GRABR REPOS. To assist in re-assembling CPGRAB ASSEMBLE, I have provided TDGMDLAT MACRO, so you will not have to modify HCPMDLAT MACRO (part of VM). One bit of warning -- fooling around with CP doesn't leave you a lot of tolerance for mistakes. Remember that a bad branch in your code can make the whole system abend. So try to do things right.

I originally wrote CPGRAB ASSEMBLE to test some function that depended on various locks in CP. Hence the name and structure of the code. I have removed all the specifics of that in order to make the remaining program shorter and clearer, but mostly in order to eliminate any legal concerns about what beans I might inadvertently be spilling. The hard part of writing the program, though, was learning to obtain an input parameter and print various messages. You'll see that I do various things in the messages (multiple lines, different message depending on the contents of a register, etc.), so you can copy the solution which suits your needs best.

Here are the instructions, copied out of CPGRAB ASSEMBLE:

To use, once you have assembled this file into CPGRAB TEXT and                  
created the message repository GRABR REPOS, put these files on                  
some Class A user's A (191) disk and invoke the following commands              
(Subsequent lines assume you chose filemode B on the second line):              
  GENMSG GRABR REPOS A TDG (margin 63 CP                                        
  CPACCESS userid 191 filemode RR                                               
  CPXLOAD GRABR  TEXT B NOCONTROL TEMP                                          
  CPXLOAD CPGRAB TEXT B NOCONTROL TEMP                                          
  ASSOC MESS COMP TDG EPNAME GRABR                                              
  ENABLE CMD GRAB                                                               
In order to undo some of your handiwork, you may want to be aware               
of a few other commands:                                                        
  DISABLE CMD GRAB   -- to disable the GRAB command                             
  QUERY CPXLOAD      -- find the identifier number of CPGRAB TEXT               
  CPXUNLOAD ID nn    -- unload CPGRAB TEXT (nn is the identifier)               

You may want to modify some of the above instructions. In particular, notice that I have defined the GRAB command to be usable ANYTIME (including before logon) and by everyone (PRIVCLASSANY). For more information, see VM/ESA CP Exit Customization. The first edition of this is for VM Version 2, Release 1.0, October 1995, IBM publication number SC24-5672-00. This book also contains more examples of CP exits.