Last update: 2019-02-14                                                         
                                                                                
z/VM and z/OS IODF Cooperative cheat sheet                                      
------------------------------------------                                      
                                                                                
If your z/OS side of the house creates IODFs for your z/VM systems,             
and you want to enable z/VM's "Dynamic I/O" so that z/VM can dynamically        
load new IODFs into z/VM without an outage (i.e. a POR and IPL), then           
this cheat sheet is for you.                                                    
                                                                                
                                                                                
1) Ensure that the target z/VM CEC is set on the HMC.                           
                                                                                
   From the target CEC HMC, access the "Customize/Delete Activation             
   Profiles" screen.                                                            
                                                                                
   a) On the "Dynamic" tab, check the box for "Allow dynamic                    
      changes to the channel subsystem input/output (I/O)                       
      definition".  This is "Supported only if the selection IOCDS              
      allows Dynamic I/O."   If this box was NOT already checked,               
      then a POR and IPL will need to be performed on this CEC                  
      before z/VM can dynamically load new IODFs.  But complete the             
      remaining tasks in this step before performing a POR and IPL.             
                                                                                
   b) On the "Security" tab for the partition dynamically loading               
      new IODF files, check the box for "Input/Output Configuration             
      Control".                                                                 
                                                                                
   c) On the "Security" tab for **all other** partitions (LPARs)                
      ensure that the box is NOT checked for "Input/Output                      
      Configuration Control".  This reduces the chances of                      
      accidentally dynamically loading a wrong IODF file from                   
      a non-standard LPAR.                                                      
                                                                                
                                                                                
2) Have the z/OS side of the house create the new IODF, and stage               
   it (write it to an open IOCDS slot) on the z/VM CEC for use at the           
   next POR and IPL.  For specific steps, see the "z/VM I/O                     
   Configuration" manual (SC24-6198), Chapter 15, Step 5, Alternative 1.        
                                                                                
   Background: Even if z/VM dynamically loads new IODFs at IPL time             
   from an IODF file on the minidisk containing the "SYSTEM CONFIG"             
   file, if the CEC is powered off the subsequent POR will require the          
   current IODF written to an IOCDS slot before any operating system            
   can be loaded over the IODF configuration in the IOCDS.                      
                                                                                
                                                                                
3) Exchange the IODF file between z/OS and z/VM.                                
                                                                                
   For specific steps, see the                                                  
   "z/VM I/O Configuration" manual (SC24-6198), Chapter 15,                     
   "How to Exchange IODF or IOCP Files Between z/VM and z/OS" under:            
                                                                                
      - to transfer an IODF from z/OS to z/VM, you can use the z/OS             
        HCD function Export IODF:                                               
                                                                                
   Alternative means to transfer the resulting z/OS-produced "Exported"         
   sequential dataset (PS, LRECL F, LRECL 4096) include:                        
                                                                                
      a) The TSO "TRANSMIT" or "XMIT" command (analogous to z/VM's              
         "SENDFILE").  This requires an NJE connection between the              
         source z/OS and target z/VM systems.                                   
                                                                                
      b) z/VM's "MOVEFILE" command, as documented in the "z/VM I/O              
         Configuration" manual.  This requires access from the                  
         target z/VM system to the source z/OS sequential dataset and           
         the DASD upon which it resides.                                        
                                                                                
      c) FTP, dependent on your site network configurations.                    
         Hint: the FTP transfer will require FTP command: BIN F 4096            
                                                                                
   On z/VM the file should be saved to the minidisk containing the              
   active "SYSTEM CONFIG" file (e.g. on z/VM 5.4, the MAINT CF1; on             
   z/VM 6.3 the PMAINT CF0) as:                                                 
                                IODFnn PRODIODF                                 
   (where 'nn' is the IODF number specified when the IODF was created           
   on z/OS and written to the z/VM CEC IOCDS slot.                              
                                                                                
                                                                                
4) If the check box for "Allow dynamic changes to the channel subsystem         
   input/output (I/O) definition" had not been checked, and was newly           
   checked in step 1.a above, then a POR and IPL will be required before        
   proceeding to actually use Dynamic I/O.                                      
                                                                                
   If you choose to POR and IPL at this time, to prove that z/VM has            
   loaded a new IODFnn at the next IPL below, you may not want to               
   POR at this time with the newest IODF.  By POR'ing with the current          
   IODF, the change to the SYSTEM CONFIG file below will prove that             
   the IPL to the new IODFnn took place before a later POR being                
   set to that matching IODFnn.                                                 
                                                                                
5) Update the "SYSTEM CONFIG" file to include the "IODF" statement.             
                                                                                
   Best practices, especially in an SSI cluster where one SSI member            
   system may be brought up with the new "IODFnn PRODIODF" file for             
   testing before other SSI cluster member systems would be to                  
   use "Record Qualifiers" in the SYSTEM CONFIG to limit which system           
   will use which IODF file at IPL.  See the "CP Planning and                   
   Administration Guide", chapter "The System Configuration File" for           
   complete "record qualifier" documentation, but as an EXAMPLE:                
                                                                                
   - in an SSI environment:                                                     
        System_Identifier LPAR lparname TESTZ1                                  
        System_Identifier LPAR lparname TESTZ2                                  
        TESTZ1: IODF IODF77    /* The IODEF we should come up with */           
        TESTZ2: IODF IODF77    /* The IODEF we should come up with */           
                                                                                
   - in a non-SSI environment:                                                  
        System_ID mmmm %%ssss TEST                                              
        TEST:   IODF IODF77    /* The IODEF we should come up with */           
     (where 'mmmm' is a CEC model, e.g. 2827; %% are wildcards, and             
      ssss is the right four characters of the CPU serial number).              
                                                                                
                                                                                
   Regarding the IODF statement: when z/OS is creating the file                 
   'IODFnn PRODIODF', the 'osconfig' parameter is still optional.               
   If 'osconfig' is not specified, HCD will only control the                    
   hardware config, permitting the systems programmer to dynamically            
   enter commands to create new devices for testing or other reasons.           
                                                                                
   Also update SYSTEM CONFIG to contain new records (all these                  
   are ignored if there is a previous "IODF" statement with an                  
   'osconfig' name specified), trailing line-comments are optional:             
                                                                                
     FEATURES ENAble ,                                                          
       SET DYNamic_I/O ,  /* Allow Dynamic I/O changes            */            
       NEW_DEVices_initialized_when_added ,  /* Create rdev CtlBk */            
       SET_DEVICES ,      /* Allow users to: CP SET DEVICES       */            
       SET_DYNamic_IO     /* Allow users to: CP SET DYNAMIC_IO    */            
                                                                                
                                                                                
6) Before you shut down and IPL, gather some documentation to                   
   compare before and after IPL, and help ensure that Dynamic I/O is            
   actually working, enter:                                                     
                                                                                
   CP QUERY TOKEN CURRENT                                                       
   CP QUERY TOKEN TARGET                                                        
   CP QUERY HCD                                                                 
   CP QUERY CONFIGMODE                                                          
   CP QUERY DYNAMIC_IO STATUS                                                   
   CP QUERY DYNAMIC_IO STORAGE                                                  
                                                                                
                                                                                
7) When it is safe to do so, CP SHUTDOWN REIPL                                  
                                                                                
   As soon as practical after the IPL, enter the commands listed in             
   Step 6 above (a best practice might include them in OPERATOR's               
   "PROFILE EXEC") and compare the results.                                     
                                                                                
   Note: Below, you should expect to see the cecname and DataSetName            
   (e.g. "SYS0    IODFnn") as specified by the z/OS HCD run.                    
   You should see the same IODFnn matching the one specified in                 
   SYSTEM CONFIG "IODF" statement.  For example:                                
                                                                                
   CP QUERY TOKEN CURRENT                                                       
   The current HCD configuration token is:                                      
   cecname ....6...................yy-mm-ddhh:mm:ssSYS0    IODFnn               
                                                                                
   CP QUERY TOKEN TARGET                                                        
   The target HCD configuration token is:                                       
   cecname ....6...................yy-mm-ddhh:mm:ssSYS0    IODFnn               
                                                                                
   Note: Below, you should expect to that HCP is currently active, and          
         the "IODF = IODFnn PRODIODF" matching that in SYSTEM CONFIG.           
                                                                                
         You should also expect to see in the last three lines of               
         the reply that HCD is disabled for dynamic hardware changes            
         (it is controlled by the z/OS HCD); that HCD is NOT                    
         controlling the software configuration (which is controlled            
         by SYSTEM CONFIG's "IODF" statement); and that HCD recovery            
         is not currently required.                                             
                                                                                
   CP QUERY HCD                                                                 
   HCD is currently active: IODF = IODFnn PRODIODF                              
   HCD is disabled for dynamic hardware changes                                 
   HCD is not controlling the software configuration                            
   HCD recovery is not currently required                                       
                                                                                
                                                                                
   Counter-intuitively (given the above reply "HCD is disabled for              
   dynamic hardware changes") you should expect to see in replies               
   from the next two commands that Dynamic I/O changes *are* being              
   controlled by HCD.  This is because these changes are the dynamic            
   software configuration changes provided by the SYSTEM CONFIG's "IODF"        
   statement and the matching "IODFnn PRODIODF" file on the same                
   minidisk.                                                                    
                                                                                
   CP QUERY CONFIGMODE                                                          
   HCPCCO6816E Dynamic I/O changes are being controlled by HCD                  
                                                                                
   CP QUERY DYNAMIC_IO STATUS                                                   
   HCPZQY6816E Dynamic I/O changes are being controlled by HCD                  
                                                                                
   CP QUERY DYNAMIC_IO STORAGE                                                  
   Remaining Channel Subsystem Resources for Dynamic I/O Changes:               
   Number of Control Units:        nnnn                                         
   Number of Subchannel Elements for CSS 0:  nnnnn                              
   Number of Channel Paths for CSS 0:        nnnn                               
   Number of Subchannel Elements for CSS 1:  nnnnn                              
   Number of Channel Paths for CSS 1:        nnnn                               
   ...and so on for your Channel Subsystem...                                   
                                                                                
                                                                                
8) If you did not POR with the new IOCDS slot, and if you still have            
   time, this would be a good time to change the IOCDS pointer on the           
   HMC to the new IOCDS slot, shutdown z/VM, POR and IPL, then                  
   compare the same commands from Step 6 above.                                 
                                                                                
                                                                                
If everything was successful, from this point on:                               
                  ------------------------------                                
                                                                                
A) The z/OS side of the house can load a new IODF into the IOCDS and            
   change the active IOCDS pointer for the next POR (no longer needed           
   for IODF changes!).                                                          
                                                                                
                                                                                
B) The z/OS side of the house can "Export" the new "IODFnn PRODIODF"            
   file (perhaps by another DSN), making it available for you to                
   write on the "SYSTEM CONFIG" minidisk as: IODFnn PRODIODF                    
                                                                                
                                                                                
C) You update the "SYSTEM CONFIG" statement "IODF" with the new IODFnn.         
   Of course, you will, **AS ALWAYS**, run the CPSYNTAX command (on the         
   MAINT 193 disk) against the updated "SYSTEM CONFIG"... **right**!!?          
                                                                                
                                                                                
D) Bring the new "IODFnn PRODIODF" online to the target CEC (all LPARs).        
                                                                                
   a) On the z/VM System running in the LPAR configured on the HMC for          
      "Input/Output Configuration Control" (see Step 1.c above),                
      logon to z/VM userid: CBDIODSP                                            
                                                                                
   b) Gain access to the desired: IODFnn PRODIODF                               
                                                                                
   c) Enter: CBDSACT IODFnn                                                     
                                                                                
   d) Check the bottom entry in the "CBDSACT MSGLOG"                            
      to make sure the Return Code is 0.                                        
                                                                                
      If there are any errors, correct and re-run the CBDSACT command.          
      Issue CP QUERY HCD to verify that the IODFnn is now active.               
                                                                                
   CBDSACT will update the software I/O config for the CEC (all LPARS),         
   leaving the hardware I/O config in the IOCDS slot written by z/OS            
   unaffected, and containing the same "Input/Output Configuration              
   Data Set" label written by z/OS on the HMC "Power-on Reset: General"         
   screen.  If done properly, that IOCDS will be ready for the next             
   POR, while z/VM may dynamically update the software I/O config               
   with new "IODFnn PRODIODF" files as needed before the next POR.              
                                                                                
Updates:                                                                        
2015-11-18: minor editorial updates, no technical changes.                      
2019-02-14: more editorial updates to correct typos/dups reported by Chip Davis.