Description of CPQUERY

Download count: 15 this month, 10769 altogether.
Downloads for CPQUERY :
  VMARC archive: v-349K

From Guy De Ceulaer and Kris Buelens, IBM Belgium

CPQUERY

CPQUERY is a CMS GUI application written in REXX. Click here to download CPQUERY.
It issues more than 20 CP commands to query the real VM system and presents the results on the desktop in an attractive manner. The program can display results for querying real and expanded storage use, DASD usage, Saved Segments.

If the user does not have the CP Privilege classes to issue the commands,dummy data is shown so that one can test the program.

REXX programmers wanting to experiment with the CMS GUI API may find some useful comments in the CPQUERY EXEC, as well as convenience routines helping to build CMS GUI windows in an easy way. Create_Screen for example makes building frames much easier, and Create_MenuBar does the same for a frame's Menu Bar.

Versions

CPQUERY Version 2.0 highlights

The main enhancement to CPQUERY Version 2 is the information shown for Saved Segments available to users with the appropriate CP Class for QUERY NSS and/or PURGE NSS. The enhancements:

  • For saved segments: the list of segments can be sorted on Name, Address and Type. For each segment, more details are available, such as how many versions do exist and who uses the segments. Authorized users can even PURGE saved sements.
  • General usability enhancements: the position of some windows is saved in GLOBALV, some windows react on function keys or have a HELP window.
  • Programming enhancements: the convenience routine that can build frames supports more DT objects: push buttons, menu bars, listboxes and layers. Some other convenience routines were refreshed to the same level as used by the GUISKEL and PRFGUI packages.
  • Some coding errors were fixed, avoiding REXX abends in exceptional conditions.

CPQUERY Version 2.1 highlights

The main change is that authorized users can FORCE and XAUTOLOG users of a given NSS. This is for example very useful to restart the last few users of an NSS in purge pending state.

Aditionally, some other minor changes are applied, and the Create_Screen subroutine is shorter and even much better (for example it now supports color attributes for all objects).

CPQUERY Version 2.2 highlights

The most important addition is the selection of NSS'es: one can now select to be listed by Class, Type and Usage. On the NSS details panel, one can either see the users of a segment, or the storage used by it.

The Create_Screen subroutine is a bit enhanced: support Radio buttons and Image objects.

CPQUERY Version 2.2.1 corrections

  • don't show dummy information when QUERY JOURNAL is not generated in SYSTEM CONFIG.
  • avoid a REXX error when no V=R area is generated.
  • send the syntax checked version of the CPQRYNSS HELPCMS file.

CPQUERY Version 2.3 highlights

Major changes

  • A command dialog has been added to execute any CP or CMS command
  • The help panel shows a "table on contents" where you can select from
  • You can list the segments without separators. The implementation required a change to the selection order:
        changed from
          Class, Type, Usage, Name
        to
          Class, Usage, Type, Name
    
  • Pressing a button on CPQUERY's first frame now refreshes the information when the desired frame is already shown.
  • The procedure to obtain the segment map information is improved (we save 3 IO's per NSS that is not open)

For the minor changes, refer to online change history (or read CPQUERY CHANGES).

Changes for programmers:

  • the Create_Screen subroutine now also supports Combo boxes.
  • We use the DtEditClear and DtEditAppend attributes (first time in my life)
  • We use the AttrCvt convenience routine, saves quite some source lines

CPQUERY Version 2.4 highlights

The changes for 2.4 are not that important.

  • CPQUERY's main frame is now busy while starting an other function. This is important on slower systems where the user now sees he has to wait.
  • We no longer update LASTING GLOBALV for unchanged variables.
  • Avoid a REXX syntax error when the user can QUERY segments but not PURGE segments or FORCE users.
  • The segment list frame was sometimes closed unexpectedly. This is corrected now.
  • When the NSS details frame is refreshed after FORCE of users, the same segment remains selected (instead of the segment selected in big NSS List).
Changes for CPQUERY's command shell:
  • It is no longer required to prefix commands with CP to get the output of CP commands displayed in the CMSGUI window.
  • Users that like the new command output to precede the existing output get better performance (we no longer need to send the complete concatenated output from VM to the workstation; a DtAdapter08 does the concatenation work on the workstation).

CPQUERY Version 3.0 highlights

With Version 3.0 there are two major changes:

  1. CPQUERY shows much more information about real storage. For example we try to tell what is using your precious central storage: how much is used by end-users, how much is occupied by pages of shared segments, which users have many pages resident, etc.
  2. The CPQUERY EXEC became very big. To make it easier to add new functions (such as the extra info for real storage), a method has been developped by which other execs can co-operate with the main CPQUERY EXEC. Some day we hope to explain how it works in the GUISKEL package.

    But, thanks to this restructure, we can plan to add new functions in a CPQUERY 3.1: provide extra information about your disks.

Version 3.0.A corrects the panel showing IND USER for one userid:

  in V3.0 a bug made that always the first userid you ever selected
  was shown (the dialog contents did not get refreshed).

CPQUERY Version 3.1 highlights

Two area's got functional enhancements:
  • information panels about real storage
  • saved segment panels
  1. The 'real storage' information panels
    • a double click on a V=R user or a user with RESERVED storage will refresh the user's details panel.
    • on most lines where storage numbers are shown, the number is also expressed as a percent of the total real storage installed
           Example: Total for users   :   49218 or  192.2 Meg   64%
                    Total for segments:    6256 or   12.7 Meg    4%
    
  2. The main change for the saved segment panels is a more dynamic behavior. This is best noticed when dealing with segments for which more than one copy exists in the spool (e.g. a class A and some class P copies)
    • When selecting a segment from the NSS map panel, details are shown in a NSS details panel (the users of it, or the paging information for it). With V3.1 the same copy (i.e. the same spoolid) will be preselected in the NSS details panel, and, the details shown handle only about that copy.
    • In the NSS details panel, all copies of a segment are placed in a list box. With V3.1 for each copy we show the number of users. Also new in V3.1 is that a double click on a copy of the segment refreshes the segment details info.
    • When you open the "Force users" panel (to restart users of a given copy), the users of that copy of the segment are listed. New in V3.1: when you select another copy of the NSS in the NSS details panel, the "Force users" panel is automatically refreshed to list the users of that particular copy.
    For LSEGs, some changes in the NSS details panel were made too:
    • two new push buttons allow you the LOAD and RELEASE an LSEG
    • when execs are found in an LSEG, next to the LSEG info we add the information obtained from EXECMAP.
    Notes:
    • The EXECMAP usage information can only show how often YOU used the execs, we can't obtain usage information for the other VM users.
    • If many copies exist of the PSEG hosting the LSEG you are looking at, the LSEG information shown is for the copy you loaded, what may be an other one than the copy you selected in the NSS map panel.
A few bugs were removed as well; as I don't know when these bugs were introduced, you maybe never had a copy of CPQUERY with these bugs,
  • Refresh NSS map via F5 did no longer work
  • Refresh the "Force Users" panel via F5 didn't work
Some panels became a bit nicer: since the first version of CPQUERY, DT changed as well, with as result that some objects were no longer aligned nicely:
    We often used a Row with TEXT objects and (read-only) ENTRY fields.
       example:   Details for DCSS CMS14HI   Versions:   2  Users : 124
     
    With the earlier DT levels, the objects in the row were well aligned. The newer DT levels resulted in misalignments. We now use OUTPUT objects
Quite a few changes "behind the scenes": while building yet another CMS/GUI application, we learned a few new tricks and now we applied them in CPQUERY. If you try to code your own DT applications, this section is useful for you.
  • To assure that panels float to the top of your workstation's desktop, in the past the only trick we knew was to close and open the frame again. This did not give a nice result (the dis- and re-appearance of the frame was visible).
    The new trick it to set keyboard focus to an object in the frame. The new behavior is both faster and nicer to look at.
  • On some panels, 'frame minimize' buttons did exist. This could cause end-user problems: when you minimize a frame, I as REXX programmer have no way to restore the frame. An example:
    • you ask for help: my REXX code opens a HELP frame, and you see it
    • you minimize the help frame
    • you ask again for help: my REXX code updates the info in the help frame and I ask to open the frame again. But, as the frame is minimized you won't see the updated frame; you have to perform some workstation action to make the frame appear.
    To avoid these problems, I disable the "minimize frame" buttons.
  • Another feature I detected makes it possible to improve they way message boxes work. Up to now, when a message box was shown, the first frame of CPQUERY was locked; the frame for which the error was shown wasn't locked. When the message box was closed, DT set focus on that first frame. We had some REXX code (close & open the frame) to set the focus back to frame from which the error originated. We detected a way to lock any frame, and, when the message box is closed, the focus automatically returns the the frame that was locked (but, we still can't lock more than one frame). The attributes to use are DtAFrameCluster and DtMessageCluster
  • The newest level of the GUISKEL convenience routines has been included in CPQUERY.
  • The last new feature used in CPQUERY is a trick by which we can select list box entries after updating the list box list lines: we use a DtTimer object, so that a short while after the update of the list box, VM is called to make the appropriate list box selection. The same trick can be used when dealing with combo boxes.

Version 3.1.A corrects a small problem:

  • If a PSEG exists twice in spool (eg Class A and Class P) we only expanded the LSEGs for the first copy encountered (most often the class P version). The other copies were listed as if it were ordinary segments.

CPQUERY Version 3.2 highlights

There are only two real changes for V 3.2:

  1. The panel showing IND USER has gotten a REFRESH button. CPQUERY will clearly tell if the user consumes CPU or performs IO: note, as we use IND USER as input, the CPU consumption seen is in seconds... (the IND USER panel can be reached from CPQUERY's "Real Storage" usage panel)
  2. From the "FORCE NSS users" panel, with a double click one can reach the IND USER panel. This allows to see if a user is active before FORCEing it. Or, one can now easily see if your GCS users are short on storage (this was THE reason why I made this possible).
Version 3.2.a has one fix:
   the userid of the NSS creator was truncated at 7 characters.

Version 3.2.b has one fix:
   We give better msg when WSA not started, or communication broken
Useful for new users only

Version 3.2.c has one fix:
   Do not show dummy data when V=R area is unlocked

CPQUERY Version 3.3 highlights

With this version of CPQUERY, we added some frames that let you see/change the state of the CP Owned devices.

  • You can START and DRAIN devices
  • You can set the limits for VDISKs
  • You can check the state of the CP accessed disks
  • You can tell CP to ACCESS/RELEASE minidisks
  • On the main "CP Q OWN" panel, red flags tell you something should be looked at (e.g. PAGE Area's too full, CPCACHE not OK).

Have fun (it was fun to code it).

CPQUERY Version 3.4 highlights

All major changes in this version are for the "CP Owned Devices" panels

  • The CPCACHE FILES file can be updated from the GUI. If the CP LINK command needs a password, CPQUERY will prompt you.
  • A minidisk is CPACCESSed in RR mode and you try to CPACCESS it in SR/ER mode. If this re-access fails, CP no longer has the RR access. CPQUERY's interface is aware of this and will re-establish a RR access.
  • We display the initial CP Logo config file ID and allow to refresh it (that is: tell CP to reread this config file). If you have an SVM (VTAM Service Machine), you can refresh the logo it displays too.
  • We find the userid of your DUMP receiver in CP storage if we can use the DISPLAY HOST command, else we suppose it is OPERATNS.
  • When looking at the PAGE area panel, a new DETAILS panel can be opened to display various storage numbers of your VM users:
    • who uses how many pages on your page area's
    • how much of the user's virtual storage is being used.
    • ....

CPQUERY Version 3.5 highlights

There is one new function: when displaying the CP spool overveiw panel, a new "Spool details" panel can be opened.

  • It allows you to display a list of spool files selected by some criteria:
    • Age of the spool file.
    • Queue of the spool file (RDR, PUN, PRT)
    • List spool files on a given CP pack. (For this function, the RXDASD package must be installed, also available on www.vm.ibm.com/download/packages)
  • The details list can be sorted in various ways.
  • Displayed spool files can be purged (what allows you for example to free a CP spool pack).

CPQUERY Version 3.5.a fix

By accident almost all subpanels on the CPQUERY CP Owned devices were no longer accessable.

For example:

When selecting the "PARM" icon button, a panel is displayed to list all mdisks accessed by CP. No special functions were available. With the fix, panel listing the CP accessed mdisks provides extra functions:
  • Listfile of a CP disk
  • Re-ACCESS a CP disk
  • Refresh logo
  • ...
For the other CP owned items, similar functions were no longer displayed. E.g. on the PAGE area list, detailed paging usage was not available.

CPQUERY Version 3.6 highlights

I don't know why I didn't provide this earlier:
On the NSS panel, the address range occupied by segments can be displayed in HEX as well as in MB. This makes it easier to match the NSS addresses with CP DEF STOR or CP IND USER virtual machine sizes.

CPQUERY Version 3.7 highlights

When restarting users of a given NSS, you can now request that the restart be executed using an EXEC you specify. Such an EXEC has the advantage that you can make the user gracefully end instead of brutally CP FORCEing it.
Note: the EXEC(s) you specify should take care of stopping the selected user(s) as well as restarting it.
CPQUERY saves up to 10 different EXECs to restart users.

CPQUERY Version 3.8 highlights

You can specify a command to back/restore NSSes, and can run this for the selected segment.
It is also possible to limit the segments displayed to those named in a CMS file, or to those located on a given spool pack.
The combination of both enhancements make it easier to remove segments from a spool pack that you want to remove from the system.

CPQUERY Version 4.0 highlights

CPQUERY now supports z/VM 5.2.0 instead of abending due to changes to the CP Q FRAMES output.
Version 4.0.1
Fixes z/VM 5.2 support: LOCKED/WORKINGSET/RESERVED counts were wrong.
Version 4.0.2
Support bigger machines with more real and/or virtual storage sizes. Find standard CP help files, even is HELP saved segment cannot be used.
Version 4.0.3
Make it possible to tailor the size of the NSS map screen.
Version 4.0.4
When listing Spool details there now is a button to page back and forth in tke list of files.

ALLCHARS

ALLCHARS, is an extra exec that shows all 255 characters on the workstation (allows to see how the host codepage translates to the workstation). It is imbedded in the CPQUERY PACKAGE.

Both procedures are good starter examples for writing CMS GUI applications.

The first 3 frames created by CPQUERY are read-only, almost no communication with VM is performed. The frames used for saved segments allow for user interaction, hence more wiring to VM is coded, code that may help programmers to understand the DT principles.