CNCLPG - ALTERING AN ADDRESS SPACE - FOR FREE (c) Copyright 2020 by Sam Golob. All rights reserved. I am very much in favor of our companies making money. We help them run their computers, and their computers, in turn, help them make money. That's the name of the game. So "up-time" is very important, especially in the middle of the day, at peak production hours. This entire story was motivated by the failure to be able to set one bit, in common storage, and the result was that a company's computer needed an IPL in the middle of a working day, with a loss of many tens of thousands of dollars. An expensive OEM software package would have solved the problem, but this company couldn't afford that. I never forgot the incident. Twenty years later, I set about to write a free program to do this same job, so that no company in the future, would ever need to fall prey to the same problem. And every company would be able to "afford" the tool that provided the solution. The name of the new program (which is a TSO command) is CNCLPG. Of course, CNCLPG has to run APF-authorized. See CBT Files 185, 797, and 731 for more hints about how to achieve that in your environment. THE PROBLEM The problem was our inability to make JES2 "cancelable". JES2 is marked non-cancelable in the PPT, and at our level (in 1986), which was JES2 1.3.6, you simply could not cleanly get rid of JES2. And you couldn't FORCE it. The JES2 command $PJES2,ABEND which was the only way that JES2 was able to "get rid of itself", left enough old junk in the system, so that the very bizarre problem we were having with JES2 was not solved. I finally had no choice but to IPL MVS in the middle of the day, causing the company a great loss. The company where I had previously worked, a large bank, had bought one of the multi-utility OEM add-on products for MVS, which could make a "non-cancelable" job "cancelable". My (then) current company didn't have such a product. Twenty years later, I set about researching and writing the CNCLPG multi-utility, to do this (necessary job) for free. If I had had this problem with JES2 today, with the latest version of the CNCLPG program now available, I probably would have used its BURN or KILL option against the JES2 address space, instead of making it cancelable using the CNCL option, and then CANCEL-ing it. Then I'd start JES2 again with the command: S JES2,PARM='WARM,NOREQ' which would force a JES2 hot start, and restore its former status. But more on this, later. THE CSCB CHAIN AND ITS MAPPING MACRO IEECHAIN The bit we had to set, belonged in the CSCB entry for our job, which in our old case was JES2, and which in our current case could be any job or STC. All active jobs, STC's etc. have an entry in the CSCB chain of control blocks (Command Scheduling Control Block), and the job's CSCB entry has a lot of the "scheduling info" for the job, including the information as to whether or not it is "cancelable". (See Figure 6.) You can get to the job's CSCB entry, either directly from its ASCB (ASCBCSCB address pointer), or you can run the entire CSCB chain from the beginning, and you can look for a match on both the jobname and asid together. This helps you to close in on the proper entry for the job you want to change. On all recent systems (XA and above), the CSCB chain resides above the 16M line, so you need AMODE 31 in your program to address it. In writing my program, I chose to run the entire CSCB chain and look for a "match" to determine the job I wanted to change. The reason for that, is that I could access the CSCB entry for any job that way, without knowing its ASCB first. I don't always use (IBM's) IKJPARSE, so in this case, I wrote my own command parser. The syntax required either the jobname (right after the CNCLPG command) and/or the keyword ASID(hhhh) with the hhhh being the hex value of the ASID. In the CSCB chain, you can have multiple entries with the same jobname, and multiple entries with the same ASID. So when you use BOTH keywords TOGETHER if you want to change something, you're pretty safe. But I also coded a DISPlay, keyword, which will show all matches for all combinations, and using DISP will allow you to find and select the exact CSCB entry that you want to alter. You usually have to use DISP together with BOTH the jobname and the ASID(hhhh) keyword, to make sure that the entry you want to change is unique. See Figure 1, Figure 2, and Figure 3 for an illustration of this process. First we use the jobname alone with DISP to find ALL hits, then we use BOTH the jobname and the ASID(hhhh) together, to get to the unique and exact entry which we want to change. THINGS GET COMPLICATED If all I wanted to do, was to write a program to make a job cancelable or non-cancelable, it would have been an easy task. The CSCB is accessible in common storage (above the 16M line), and you could do all of your business from your own address space, just flipping the cancelable/non-cancelable bit CHCL for the appropriate CSCB entry. (See Figure 6 below.) However, there is some more control to be had here in the CSCB. And we also have to note that these types of programs can often be made to change jobs to be "swappable" and "non-swappable. That's not so easy to do. Before attacking "swappable" and "non-swappable", there was one other change that I could easily make. There is a bit CHAFORCE, which, when it is on, does not require you to attempt to CANCEL a job, before you try and FORCE it. So I coded the FORC and NFRC functions in CNCLPG to turn this bit on or off. CNCL and NCNC turn the "cancelable" bit on or off. So now I had two functions available in CNCLPG. SWAP and NSWP ("swappable" and "non-swappable") properties of an address space (determined in the PPT), are not easily switched "on" or "off". Several operations have to be done on the system, and these are executed using a SYSEVENT macro, which performs all of these multiple operations which are necessary. When some task requests that a JOB or STC should become non-swappable, there is also a "count" field in the OUCB for the address space (pointed to by ASCBOUCB in the ASCB), telling the address space how many times it was requested to be non-swappable. You can't make an address space swappable unless this count field is equal to 1. Whenever a request for that address space to be non-swappable is removed, then the "count" field in the OUCB for that job (or STC) is reduced by one. This makes sense, because if a task wants a certain address space to remain in memory, and not be swapped out, and another task no longer needs that JOB or STC to remain in memory, we still have to honor the request of the first task. So there has to be a COUNT field. CNCLPG will report on the status of this COUNT field, if SWAP, NSWP, TSWP, or FSWP functions are involved, and you want to inquire about the job's SWAP status first. Just execute CNCLPG against the CSCB entry using the COUNT function. See Figures 7 and 8. Let's get back to SWAP and NSWP (swappable or non-swappable) status of a JOB or STC, and what's involved in changing it. I mentioned previously, that you need to execute a SYSEVENT macro, but what I didn't mention, is that the SYSEVENT macro has to execute in the target address space--the address space whose status you want to change. To do that, you (usually) have to SCHEDULE (or IEAMSCHD) some SRB code (which runs the SYSEVENT macro) to run in the target address space, and then you need to report the result of that execution. In other words, you use the SRB to go across address spaces to the target address space whose status has to be changed, and then you report the result of the change in your own program's address space. Again, see Figure 7 for an illustration of this. To see further details about this process, you have to look at the CNCLPG source code in CBT File 826. See label SWAPXMEM, and then look at the code to set up the SRB, which comes just before it, in the source code for CNCLPG. The SYSEVENT macro can be run with DONTSWAP, OKSWAP, or TRANSWAP keywords. BURN AND KILL IBM provides a way to forcibly terminate an address space, using its FORCE console command. The "business end" or mechanism of the FORCE command is the CALLRTM macro with TYPE=MEMTERM. However, IBM does not want people to terminate address spaces arbitrarily or erroneously, so they make it hard to use FORCE directly. One way of doing that, is to require an attempt to CANCEL the JOB or STC before executing a FORCE. CANCEL removes a job from the system more cleanly (and with better cleanup) than FORCE. Once you have tried CANCEl, and it does not work, then the system will throw the CHAFORCE bit in the CSCB (see Figure 6), and you'll be able to issue the FORCE. CNCLPG using the FORC function, will throw this bit, without your having to execute the CANCEL first. Since the information is out there, I coded for it. Some address spaces, such as JES2, contain internal code which resists an effort to do a FORCE on the address space. And finally, there are the "non-memtermable" bits in the ASCB for the address space: ASCBNOMT and less importantly, ASCBNOMD. If the first of these is on, then the address space can not be FORCE'd using a FORCE console command. Sometimes, you just have to get around this. We are the "system doctors", and we are obligated to "fix whatever ails the system". We need to pull any trick in our power (sometimes) to get this done. So therefore, I coded the BURN keyword to immediately do a CALLRTM with TYPE=MEMTERM against the address space. And if the address space was "stubborn", with the "non-memtermable" bit(s) turned on, so that CALLRTM with TYPE=MEMTERM won't work, I coded the KILL keyword to first turn these bits off, and then issue the CALLRTM TYPE=MEMTERM. That should ALWAYS work.!!!! We've got to have some big guns at our disposal. There are some safeguards built into CNCLPG so that an arbitrary programmer can't execute it. If you want, you can build more safegurards into it, yourself. However, you should keep this program isolated from the general public. It is there for your use, as the "doctor for the system". A doctor doesn't let a layman use his/her prescription pad. You shouldn't, either. TRANSWAP Usually, when the system is starting an address space, it will try and load its code neatly, in contiguous storage. However, if you run a SYSEVENT macro with the NOSWAP option, to make the address space non-swappable, the system just fixes its pages where they are. This works, but it is not a neat way to do things. The OTHER way to do this is to run the SYSEVENT macro with the TRANSWAP option. This will (logically) rearrange the storage of the address space neatly, before page-fixing it. However, you see that this can be dangerous, and although I coded the TSWP function into CNCLPG, you shouldn't use it unless you need to. TSWP can move code from one storage location to another, and if one program needs it in the earlier place where the storage was, there might be problems created by TSWP. So it's there, but use it carefully. USING CNCLPG AS A WAY OF EXPLORING THE CSCB You can run the entire CSCB chain by executing CNCLPG with a dash "-" after it. Like this: CNCLPG - . By doing that, and by capturing the (long) output, you can get a very good idea about what is running in the system. You can also see the current settings (for each CSCB entry) of the CHACT and CHSTS flags. Such information can be useful, if you want to explore or monitor the status of the various system address spaces. Again, you can restrict this display by using the jobname and/or ASID(hhhh) parameters with the DISP function. The dash was coded as an easy way to run DISP for the entire CSCB chain. ACKNOWLEDGEMENTS I have to give a big "shout out" to my friend and colleague Joe Reichman, who wrote all the SRB code. Once Joe got the code to work initially, I was able to enhance it to put in extra features. But Joe did the hard work, and he deserves great credit for it. ILLUSTRATIONS Figure 1. CNCLPG JES2 DISP Run of CNCLPG to find the correct entry for the JES2 address space. Note that any CSCB entry starting with the letters "JES2" will cause a match. This is the way that the DISP(lay) subcommand is coded. However, if you would issue an "action" command against the entry, such as CNCL, you would affect the FIRST entry in the chain. Therefore you should be careful, when changing any entry, to use BOTH the jobname and the ASID keyword, and MAKE SURE YOU HAVE ONLY ONE HIT, WHEN YOU USE THE DISP FUNCTION. The following DISPLAY run has 3 hits. CNCLPG 1.2.10F - Alter Characteristics of a Running Address Space ------ ------- - ----- --------------- -- - ------- ------- ----- Search Jobname: JES2 ---------------------------- Action code : CSCB (DISPlay) This is a run of the CSCB Chain only ... ---------------------------- Job ID : JES2AUX Proc ID : JES2AUX ASID : 0021 Current CHSTS Flags: 40 Current CHACT Flags: 00 Job Status: Non-Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Non-Memtermable ---------------------------- Job ID : JES2MON Proc ID : JES2MON ASID : 0025 Current CHSTS Flags: 00 Current CHACT Flags: 08 Job Status: Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable ---------------------------- Job ID : JES2 Proc ID : JES2 ASID : 0020 Current CHSTS Flags: 00 Current CHACT Flags: 00 Job Status: Non-Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable ---------------------------- Return code is 0 Figure 2. CNCLPG JES2 ASID(20) DISP Here we use both the jobname and the ASID(hhhh) keyword in the DISP(lay), to make sure that we have only one unique CSCB entry here. This is because we next want to issue a command to change this (unique) combination of jobname and ASID to make it cancelable. We do not want to make a mistake and change a different address space. CNCLPG 1.2.10F - Alter Characteristics of a Running Address Space ------ ------- - ----- --------------- -- - ------- ------- ----- Search Jobname: JES2 ---------------------------- ASID parm entered : 20 Search ASID : 0020 ---------------------------- Action code : CSCB (DISPlay) This is a run of the CSCB Chain only ... ---------------------------- Job ID : JES2 Proc ID : JES2 ASID : 0020 Current CHSTS Flags: 00 Current CHACT Flags: 00 Job Status: Non-Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable ---------------------------- Return code is 0 Figure 3. CNCLPG JES2 ASID(20) CNCL Command to make the JES2 address space (and ONLY the JES2 address space) "cancelable". After doing this, you can CANCEL JES2 "more cleanly". (You still have to enter "END" to the JES2 termination request.) CNCLPG 1.2.10F - Alter Characteristics of a Running Address Space ------ ------- - ----- --------------- -- - ------- ------- ----- Search Jobname: JES2 ---------------------------- ASID parm entered : 20 Search ASID : 0020 ---------------------------- Job ID : JES2 Proc ID : JES2 ASID : 0020 Previous CHACT Flags: 00 Job Status: Non-Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable ---------------------------- Job ID : JES2 Proc ID : JES2 ASID : 0020 Modified CHACT Flags: 08 ---------------------------- Action code : CNCL Cancel Indicator Flag : 08 Current CHSTS Flags: 00 Current CHACT Flags: 08 Job Status: Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable Return code is 0 Figure 4. Full syntax of the CNCLPG TSO command Syntax: TSO Command: APF-authorized. CNCLPG |jobid [ASID(hhhh)] |CNCL|NCNC (cancelable, non-canc) |ASID(hhhh) |FORC (force w/o cancel first) | |NFRC (force needs cancel first) | |NSWP|SWAP (non-swap, swappable) | |TSWP (transwap) | |FSWP (force swappable immediately) | |CSCB or DISP (display CSCB blks) | |BURN (memterm the address space) | |KILL (memterm after turning off | | the non-memtermable bits) | |NMEM|MEMT (turn on/off | | non-memtermable bits) | |COUNT (display DONTSWAP count) |- (displays the entire CSCB chain) |? (displays help) Figure 5. CNCLPG internal HELP prompt, issued when you enter an invalid function code, like "?". CNCLPG 1.2.10F - Alter Characteristics of a Running Address Space ------ ------- - ----- --------------- -- - ------- ------- ----- * ----- ALWAYS DO A DISPLAY FIRST ----- * Syntax: CNCLPG jobname ASID(hhhh) FUNCtion Function is: CNCL, NCNC, FORC, NFRC, NSWP, SWAP, MEMT, NMEM, TSWP, or COUNT. FSWP, BURN, or KILL are dangerous. TSWP will do a TRANSWAP. Or code CSCB or DISP to just display CSCB entries. DISPlay or CSCB will display CSCB chain entries, without changing them. ----------------------------------------------- When affecting a job, we must affect the CORRECT job, therefore you should use the DISPlay option first. ----------------------------------------------- To display the whole CSCB, code - (dash) for JOBNAME. To see this help message, code ? for JOBNAME. ----------------------------------------------- ** NOTES (IMPORTANT) : ** BE SURE TO READ THIS ** ----------------------------------------------- CSCB (DISP) display for an ASID shows ALL occurrences for that ASID, regardless of JOBNAME. CSCB (DISP) display for a JOBNAME shows ALL occurrences for those JOBNAME characters, regardless of ASID. CNCL, NCNC, FORC, NFRC, NSWP, SWAP changes the FIRST entry in the CSCB chain that matches, if multiple entries exist. But DISP will display ALL applicable matching entries in the CSCB chain, so you can see which one you want to change specifically. When you code BOTH jobname AND asid, to CHANGE it, then ONLY that specific job and asid gets changed. ----------------------------------------------- * ----- ALWAYS DO A DISPLAY FIRST ----- * Return code is 0 Figure 6. Description of the CHACT flags and CHSTS flags of the CSCB, in its mapping macro, IEECHAIN. Setting CHCL on, will MAKE the job cancelable, but CHSWAP is just an "indicator" as to whether the job is swappable. To MAKE a job swappable or non-swappable, you need to execute a SYSEVENT macro in the address space that you want to affect. This would usually require scheduling an SRB in that address space, if it is different from yours. Of course you can make your own TSO session non-swappable by running a SYSEVENT macro in your own address space without needing to schedule an SRB. (You're already there, and you don't need to go cross-memory.) CHSTS DS B - STATUS FLAGS CHAP EQU X'80' - ASSIGNMENT PENDING CHINFMT EQU X'40' - CSCB IN PRE-INTERPRETATION (INPUT) FORMAT * @ZMB0266 CHSOUT EQU X'20' - CANCEL ALL SYSOUT CHQSPC EQU X'10' - INSUFFICIENT QSPACE CAUSING ABEND 422 CHAD EQU X'08' - ADD THIS CSCB TO CHAIN CHDL EQU X'04' - DELETE THIS CSCB FROM CHAIN CHFC EQU X'02' - FREE THIS CSCB'S CORE CHABTERM EQU X'01' - EXECUTE BRANCH ENTRY TO ABTERM * CHACT DS B - FLAGS INDICATING ACTIVITY INVOLVED CHSWAP EQU X'80' - SWAPPABLE JOB CHTERM EQU X'40' - TERMINAL JOB CHDISC EQU X'20' - CANCEL IMPLIES DISCONNECT CHDSI EQU X'10' - ON MEANS NO DATA SET INTEGRITY (OS/VS1) MDC045 CHCL EQU X'08' - CANCELABLE JOB STEP CHCLD EQU X'04' - CANCEL COMMUNICATION SWITCH CHAIFX EQU X'02' - CANCELABLE (OS/VS1) CHPOSTSS EQU X'02' - POST EARLY ADDRESS SPACE (MDC313) @G38EP2L CHIFY EQU X'01' - SYSTEM ASSIGNED PROCEDURE (OS/VS1) CHAFORCE EQU X'01' - CANCEL ISSUED FOR THIS CSCB (FORCE COMMAND * CAN BE ACCEPTED) (OS/VS2) (MDC301) @G17FP9A Figure 7. CNCLPG IBMUSER ASID(51) NSWP We request that my TSO address space be made non-swappable. Please note from the COUNT field "Outstanding DONTSWAP requests" that this address space had been made non-swappable once before. Therefore, to make it swappable again, we would have to issue a SWAP function against it, twice, or issue FSWP (careful..!!) to set the count to 1, and then to issue the SWAP. CNCLPG 1.2.10F - Alter Characteristics of a Running Address Space ------ ------- - ----- --------------- -- - ------- ------- ----- Search Jobname: IBMUSER ---------------------------- ASID parm entered : 51 Search ASID : 0051 ---------------------------- Function NSWP was called for. Job ID : IBMUSER Proc ID : SPFPROCE ASID : 0051 Previous CHACT Flags: 48 Job Status: Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable ---------------------------- Outstanding DONTSWAP requests: 0002 Job IBMUSER for ASID 0051 already non-swappable. Current CHSTS Flags: 00 Current CHACT Flags: 48 Job Status: Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable Return code is 0 Figure 8. CNCLPG IBMUSER ASID(51) COUNT CNCLPG 1.2.10F - Alter Characteristics of a Running Address Space ------ ------- - ----- --------------- -- - ------- ------- ----- Search Jobname: IBMUSER ---------------------------- ASID parm entered : 51 Search ASID : 0051 ---------------------------- Function COUNT was called for. Job ID : IBMUSER Proc ID : SPFPROCE ASID : 0051 Outstanding DONTSWAP requests: 0002 ---------------------------- Final Job Status Report. Current CHSTS Flags: 00 Current CHACT Flags: 48 Job Status: Cancelable Job Status: Cancel + Force Job Status: Non-Swappable Job Status: Memtermable Return code is 0