|
All VM users know about CP commands such as SPOOL and LINK and even LOGOFF. These commands are the way that users communicate with CP. But did you know that VM provides a mechanism for programs to interface with CP? This application programming interface (API) is implemented by means of the assembly-language Diagnose instruction, but you don’t need to know Assembler to use it.
"Diagnose" is an instruction provided by the IBM hardware architects to allow processor service diagnostics, and its function is largely undocumented. However, the instruction is unused when running in a virtual machine (no hardware to service!) and so was coopted by the VM designers for use as an API. If you open the CP Programming Services manual for your release of VM, you’ll see an entire chapter explaining the various interesting things that you can do with this API.
Diagnose gives you access to system information like the precise release of VM that you’re running, your VM userid and amount of virtual storage, and even what timezone you’re in. It allows you to generate your own system accounting records, manipulate spool files, and discover the characteristics of any virtual device available to you. You can have CP format error messages that your program issues, and even change the language of system messages. In fact, there are around 80 different Diagnose functions available.
Some Diagnose codes are available to all users, and some require very specific directory (or external security manager) authorization, as might be expected.
In particular, Diagnose function code 8 allows a program to issue any CP command and get the command output back in a buffer. Knowing that, you can write a program to do anything that you now do from your terminal. This is particularly useful when implementing service virtual machines. In fact, to communicate with CP all you really need to know is Diagnose!
What makes Diagnose an even more powerful tool is that there are a pair of REXX built-in functions to access some of the more generally useful codes. HELP REXX DIAGRC will give you an explanation of what’s available. You will want to read the explaination in the CP Programming Services guide along with the REXX function description in order to decode the result from the call.
Once you’ve familiarized yourself with what this powerful API provides, you’ll be able to make your applications and processes much more robust, flexible, and secure.
|