CA Allocate DASD Space and Placement Using

Transcription

1 CA Allocate DASD Space and Placement Using Exported on: 08-Aug-2018

2

3 This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the Documentation ) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. If you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections , , and (c)(1) - (2) and DFARS Section (b)(3), as applicable, or their successors. Copyright 2018 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

4 Contents Using Product Integration CA Vantage...13 Operational Considerations for Communicating with CA Vantage...13 Set Up the Communication Interface Free Space Threshold Violations Send Messages to a Specific CA Vantage User Using VANTKEY Send Messages to a Specific CA Vantage User from your ASR Send Messages to CA Vantage Using the Message Control Facility Undelivered Messages to a Specific CA Vantage User CA Auditor Interface...16 Operational Considerations for Activating the CA Auditor Interface Activate the CA Auditor Interface...17 Access the PDM Describing DASD and Placement...17 Troubleshooting the CA Auditor Interface Activate CA Service Desk Support...18 About CAISDI CAISDI Implementation Special Considerations for Using CA Allocate with Other Programs or Products (A-F)...20 ACS Environment Processing...21 Bypassing Allocations...21 CA Compress...21 CA Database Organizer CA Disk Backup and Restore, ROSCOE, and WIZARD COBOL II Users DATACLAS Sub-Parameter Override Space DB DFDSS...23 DFSORT Workfiles...23 Dormant Operation...23 Extended Addressability Volumes...23 Contents 4

5 Enqueue for the CQT...24 Enqueue Propagation for the DQT...24 FTP...24 Special Considerations for Using CA Allocate with Other Programs or Products (G-P) HFS Unix File Systems...25 IAM...25 IDCAMS BLDINDEX Workfiles...25 Initializing Tapes...25 IODF...26 ISAM...26 MainView SRM (formerly STOP-x37)...26 MVS System Logger Data Sets...26 PDSE Data Sets...26 Special Considerations for Using CA Allocate with Other Programs or Products (Q-Z) SMS-Managed GDGs SMS-Managed Non-VSAM Data Sets SMS Subsystem Interface...29 SnapShot...29 SVC and DADSM Branch Entry Interface...29 Virtual Tape Systems...29 VTS Redirection Issues...29 XCOM...30 XPEDITER...30 ZFS UNIX File Systems...30 Concepts and Facilities Basics...31 Environments ACS Environment...35 ALLOC Environment DEFINE Environment...38 EOV Environment...39 EOV_VSAM Environment EXTEND Environment OLD Environment...43 Contents - 5

6 PREALLOC Environment...45 QREBUILD, QSCAN, QUOTA Environments...47 RELEASE Environment...47 RENAME Environment...48 SCRATCH Environment...49 SPACE Environment CA Health Checker Interface...51 ALLOC_VRFY_ACT_ASR_IS_EXPECTED...52 ALLOC_VRFY_EOV_X37_SVCS_STATUS - VAMH0061E...53 ALLOC_VRFY_PLSOPT10_SNA_X37_SVCE - VAMH0091E...53 ALLOC_VRFY_PLSOPT94_USE_STUB - VAMH0101E...54 ALLOC_VRFY_PLSZSEC_EOV_X37_SVCE - VAMH0081E...54 Life Cycle of a Data Set Propagate Variables Between Environments Volume Selection Options for New Data Sets...56 Subpooling of SMS-managed Storage Groups...57 Key Data Set Separation...58 Volume Selection Logic for Non-SMS-managed...58 Propagate Volume Selection Failure Return Code...59 End-of-volume Support...60 EOV Technical Overview and Restrictions Understand When EOV is Entered...62 Use EOV and EOV_VSAM Environments with a SMS-Managed Data Set...64 VSAM EOV with Media Manager Data Sets...65 EOV Support for VSAM Data Sets with Unused Candidate Volumes...66 EOV_VSAM Data Sets with Additional Volume Amount=Secondary...67 EOV Support for Zero Secondary...68 DOES IT FIT (DIF) Support...68 DIF Overview...71 Volume Level DIF Storage Group Level DIF...74 DIF Special Considerations...74 NOT CATLGD 2 Support Use the SNC2 Option Sample ASR Statements...79 Contents 6

7 ACS Support...80 Enhanced DATACLAS Support...81 IBM DATACLAS Support DATACLAS Support...82 Tape Allocation Support...84 Device-Type Conversions...84 Volume Referbacks/Unit Affinity and Disk-only Allocations...86 SMF Interfaces Track Successful EOV Recovery Activities...88 Track Successful Reduce to Fit (RTF) Activities...88 DFSMShsm Support...89 SMS Construct Names Used During DFSMShsm RECALL and RECOVER Operations New Logic Required in the ACS Environment Data Set Names Generated by DFSMShsm During MIGRATE and BACKUP DFSMShsm During RECALL/RECOVER...92 ASR Variables for HSM RECALL and RECOVER Operations...92 The DFSMShsm RECALL Exit (ARCRDEXT)...94 Control Only RECALL and RECOVER Operations...94 FDR Support...95 Limitations...96 Space Type Conversions LSPACE Support for Primary and Secondary Allocation...98 Options How Other Variables Can Affect the Process Special Notes for LSPACE Processing Message Control Facility Macro Definitions Keyword Operands Message Control Facility Example Specifications Assembling and Linking Message Control Specifications Implementation Override the Default Value of Sysparms SUPLS Sysparms PLS Sysparms Contents - 7

8 PLSOPTnn Sysparms Multiple Systems - Parmlib Considerations Configure Parmlib Member CONFIG Use Pattern Matching Characters Create a Storage Group Definition Volume Serial Number Free-Space Threshold Percentage Include/Exclude Flag Storage Group Names List Syntax for Storage Group Definitions Sample Storage Group Definition Create a Key Data Set Names Member Create an Allocation Selection Routine ASR Statements ASR Constants ASR Operators ASR Functions Create an Exclude Jobs Names Member Operation Testing Parameter Files Operator Command Parameters START Command MODIFY Command STOP Command Action Parameters CLEANUP DECOMP INSTALL PARMREF REFRESH REMOVE STATUS QREBUILD Subcommand QRESETWM Contents 8

9 QSYNC Change Parameters ACTIVE ALIASLVL= ASRSIZE= CONFIG= DIAGS= DORMANT HSMDIAG HSMOFF HSMON NOHSMDIAG PROG= QCONFIG= QCONFIGSZ= RESIDENT= STORGP= VANTKEY= VSYS= User Exits Sample User Exits Install User Exits with SMP/E Quota How Quota Works Quota System Overview The Importance of QUOTAFUNC The QREBUILD Process The QSYNC Process Water Mark Thresholds Operation Environments Quota Files Disk Quota Table Quota Configuration File Contents - 9

10 Allocation Selection Routines and Environments Reporting Options QSTAT CLIST Batch Reports Running Quota Across Multiple CPUs Sharing Disk Volumes QUOTA and PLSQFACT QUOTA and PLSQUOGM Logically Disabling Quota Processing Exposures of Sharing IGGPRE00 and IGGPOST RENAME and MANAGEMENT CLASS API for Dynamically Changing Quota Limits Invoking the API Calling Parameters VAMSRV10 Return Codes Reports The History Data Set Modify the Default History Period JCL for Reports JCL to Allocate the Reporting Data Sets JCL to Run the VTOC Reader JCL to Generate the Reports JCL to Report on PTF/RMID Module Levels External Called Programs Manage the Report Output Control Which Volumes Are Reported Control Which Storage Groups Are Reported Chart and Plot Compared to Print History Reports Current Snapshot Reports Trend Reports Sample Reports Volume Summary Detail Report Storage Group Detail Report Storage Group Summary Report Contents 10

11 Current Disk Space Allocated-Storage Group Current Disk Space Allocated-Unit Name Current Disk Space Allocated-System-Wide History of Disk Space Allocated-Storage Group=ABOVEUCB CA Support and Diagnostics CA Support Services Before You Contact Us When You Contact Us After You Contact Us Diagnostic Tracing Legacy Optional Features Troubleshooting Activate Diagnostic Tracing Contents - 11

12 Using Using provides a view into CA Allocate from basic concepts such as storage groups to environments to integration with other CA products. Here you will find key information about implementation and operations, using the Quota option, and reporting. Product Integration (see page 13) Concepts and Facilities (see page 31) Implementation (see page 108) Operation (see page 163) User Exits (see page 175) Quota (see page 177) Reports (see page 204) CA Support and Diagnostics (see page 217) Legacy Optional Features (see page 220) Troubleshooting (see page 222) Using 12

13 Product Integration CA Allocate DASD Space and Placement can integrate with the following products. When integrating with these products, or with other programs and products, review the following items. CA Vantage (see page 13) CA Auditor Interface (see page 16) Activate CA Service Desk Support (see page 18) Special Considerations for Using CA Allocate with Other Programs or Products (A-F) (see page 20) Special Considerations for Using CA Allocate with Other Programs or Products (G-P) (see page 24) Special Considerations for Using CA Allocate with Other Programs or Products (Q-Z) (see page 26) CA Vantage CA Allocate DASD Space and Placement can communicate with CA Vantage on several levels. The following list describes the various levels of communication: The started task or batch job that controls the operating system interfaces can unconditionally notify CA Vantage about INSTALL, REFRESH, and REMOVE operations. The volume selection programs can notify CA Vantage whenever they select a volume whose free space threshold has been exceeded. The started task can conditionally send a copy of every message it issues to a specific CA Vantage user. The customer-written Allocation Selection Routine (ASR) can send messages to a specific CA Vantage user. The Message Control Facility (MCF) can reroute messages from the started task and operating system interfaces to the CA Vantage started task log or to a specific CA Vantage user. Note: Sending messages to CA Vantage requires a limited amount of overhead. Operational Considerations for Communicating with CA Vantage Review the following items when preparing for CA Allocate DASD Space and Placement to communicate with CA Vantage. System Requirements The VANAPI01 API that CA Vantage provides must reside in a linklist library. Product Integration 13

14 Limitations and Assumptions Most CA Allocate DASD Space and Placement messages can be routed to CA Vantage. The following messages cannot be routed: Messages that are issued during INSTALL operations before the communication interface has been established Messages that are issued during shutdown after the communication interface has been disabled Messages that are issued outside the internal message programs Set Up the Communication Interface CA Vantage runs as a subsystem. Subsystems have unique four-character names. For CA Allocate DASD Space and Placement to communicate with CA Vantage, it must know the subsystem name for the CA Vantage started task. The CA Vantage SUBSYSN system parameter contains the subsystem name, and has a default value of SAMS. If you assign a different subsystem name, specify the new name in the VKGPARMS member of your CA Allocate DASD Space and Placement parmlib. Specify SUBSYSN (xxxx), in which the xxxx is the new subsystem name. Free Space Threshold Violations As delivered, the volume selection process notifies CA Vantage whenever it selects a volume whose free space threshold has been exceeded. Turn off this automatic notification by overriding the default value (N) of sysparm PLSOPT14 with (Y). When this notification is active, a message is issued to the MSGExxxx output files associated with the CA Vantage STC: VANPLS01 Threshold Violation from Allocate for sg-name sg-name Specifies the name of the CA Allocate DASD Space and Placement storage group that contains the volume whose freespace threshold has been exceeded. Send Messages to a Specific CA Vantage User Using VANTKEY When someone logs in to the CA Vantage Graphical User Interface (PcGUI), CA Vantage issues this message: VAN0484I LU TCPnnnn User <uid> Type PcGUI nnnn Specifies the network identifier that is associated with uid. Product Integration 14

15 uid Represents the TSO Userid of the PcGUI User. The TSO Userid that is associated with a PcGUI User is considered a VANTKEY by CA Allocate DASD Space and Placement. VANTKEY is the CA Allocate DASD Space and Placement parameter that can be used to send copies of messages that are issued by the CA Allocate DASD Space and Placement STC to a specific PcGUI User. If you specify VANTKEY=<uid> as a change parameter on START or MODIFY commands, most messages that CA Allocate DASD Space and Placement STC issues are propagated to that specific PcGUI User. Send Messages to a Specific CA Vantage User from your ASR The WRITE Statement in your ASR can be used to send messages to a specific PcGUI user. Prefix the PcGUI user with '@#@'. For example, this WRITE statement: WRITE '@#@USERID msg-text' Results in the following message: sysid/subsysn msg-text sysid Represents the four character system identifier of the z/os system that the CA Vantage STC is running on. subsysn Represents the unique identifier of the subsystem that is associated with the CA Vantage STC the user is logged onto. Send Messages to CA Vantage Using the Message Control Facility The Message Control Facility (MCF) can be used to route most messages issued by CA Allocate DASD Space and Placement to VANTLOG or to the CA Vantage User previously defined by the VANTKEY parameter. To locate the messages the MCF has sent to VANTLOG, go to the OBJ Tree in the PcGUI and select CA Vantage Management, System Activity, CA Vantage Messages. This creates a Message Window pop up labeled System Activity Log / Msg that contains the messages that the MCF sent to VANTLOG. These messages are numbered PLS0001I. To locate messages the MCF sent to the PcGUI User, go to the Message Window pop up labeled CA Vantage SRM System Messages. It contains the messages that were prefixed with sysid/subsysn -, where sysid is the system identifier of the z/os system the CA Vantage STC is running on, subsysn is the unique identifier of the subsystem associated with the CA Vantage STC the user is logged into. Product Integration 15

16 Undelivered Messages to a Specific CA Vantage User If the PcGUI user is not logged in to CA Vantage when the message is delivered, undeliverable messages are not saved. Use SYSPARM PLSOPT78 to redirect these messages to the mailbox of the user. The user can retrieve the messages the next time they log in to the PcGUI. CA Auditor Interface Activate the the Product Validation Interface (PVI) of CA Auditor, which provides an installation verification service. This interface helps verify that software products are correctly installed and to verify runtime integrity. PVI audits the z/os operating system and reports it findings to its users, auditors, systems security administrators, and so on. The PVI allows direct queries to acquire information about CA Allocate DASD Space and Placement, its intercepts, exits, and other attributes of concern to the security and audit community. This capability is possible by using an encrypted Product Description Module (PDM) which is shipped with CA Allocate DASD Space and Placement. Once installed, the PVI uses the information that is described in the PDM to verify that CA Allocate DASD Space and Placement is correctly installed and running properly. Operational Considerations for Activating the CA Auditor Interface System Requirements The PDM for CA Allocate DASD Space and Placement is CAIXXGF$ and requires 18K of ECSA. CAIXXGF$ is loaded into SP241 and moved into the Link Pack Area (LPA) during the first INSTALL or REFRESH operation that occurs when running with 'PLSEXAMI (Y)'. Once loaded, the PDM remains in system memory until the next IPL. Verify that the following APIs used with this interface are in a linklist library: VAMEXIR2 VAMEXRE2 VAMEXRH2 VAMEXRP2 VAMEXVE2 VAMEXVH2 VAMEXVP2 VAMPDMIR VAMPDMRR VAMPDMVR Product Integration 16

17 Limitations and Assumptions Once this interface has been physically activated, outside of an IPL, it can only be logically deactivated. The minimum CA Allocate DASD Space and Placement release required for running the RR and VR APIs associated with the Hook Records: VAMEXRH2 and VAMEXRV2, is r11.5. The PDM is essentially inaccessible when running during CLEANUP, INSTALL, REMOVE, and STOP operations, and when running with 'PLSEXAMI (N)'. The APIs access the PDM only when called by an entity they recognize. The APIs will only be able to recognize those entities that they have been officially certified as being compatible with. Currently this is limited to all r11.5 and the ISPF Interface of CA Auditor Release 3.5. Two of the attributes of an Exit that are of interest to the PVI are whether or not an exit is active and if the exit has been called. The following assumptions have been made: With regards to the ten documented User Exits, VDSEXIT0 - VDSEXIT9: If a customer installs a User Exit it is identified as both active and being called. Otherwise it is considered inactive and not being called. With regards to the three undocumented Hook Exits, VDSHKXT0 - VDSHKXT2; VDSHKXT0 will be identified as being both active and having been called because it is unconditionally being called from several hook points. VDSHKXT1 and VDSHKXT2 are being distributed with executable code but are not being called from anyplace. Both are identified as inactive and never having been called until we learn of their use. With regards to the six undocumented Maintenance Exits, VDSEXITA - VDSEXITF, they are identified as inactive until we learn of their use. Activate the CA Auditor Interface Sysparm PLSEXAMI is used to activate the CA Auditor Interface. To activate the interface, change the value of PLSEXAMI from its default value of (N) to (Y) and then do an INSTALL or PARMREF operation, which ever is appropriate. Output from STATUS operations is augmented with a new message indicating when CA Auditor Interface is active: VAM0254 CA Allocate IS RUNNING WITH AN ACTIVE e-trust CA-Examine INTERFACE Access the PDM Describing DASD and Placement The PDM contains one Product record, 12 Hook records, 19 Exit records, and seven Application Programming Interfaces (APIs). Each of the APIs contained in CAIXXGF$ call another API, which need to reside in a linklist library that is accessible from PVI. These APIs are VAMEXIR2, VAMEXRE2, VAMEXRH2, VAMEXRP2, VAMEXVE2, VAMEXVH2, and VAMEXVP2 and are built in a separate load module library during the SMP/E installation process. Product Integration 17

18 After the PDM has been loaded, it can be accessed from the PVI, where each of the records can be viewed individually, or from one of the batch jobs that are distributed in the CCTVJCL library: VAMPDMIR Executes the VAMPDMIR program which needs to reside in a linklist library. VAMPDMIR executes the APIs that comprise the Initialization Routine. VAMPDMRR Executes the VAMPDMRR program which needs to reside in a linklist library. VAMPDMRR first executes the APIs that comprise the Runtime Routines (RR) associated with the PDM when it is accessed from the PVI. Then VAMPDMRR executes the APIs that comprise Verification Routines (VR). In contrast to the PVI, that calls the RRs and VRs for each record individually, VAMPDMRR calls the RRs and VRs for all records in the PDM. Troubleshooting the CA Auditor Interface Before contacting CA Technical support, run the VAMPDM*R batch jobs on the same system the PDM is being accessed on through the PVI. Review any messages issued by these jobs. Activate CA Service Desk Support Use of the CA Service Desk interface feature of is optional. To activate this feature you must have installed the CA Common Services CAISDI components CAISDI/soap and CAISDI/els as described in the CA Common Services documentation. Copy the CA Allocate DASD Space and Placement event members from the CCTVJCL library to the event library, CAI.CAIEVENT. CAI.CAIEVENT is created as part of the CA Common Services CAISDI/els component installation. A sample job, XGFCOPY, can be found in the CCTVJCL library. If necessary, edit the member and change the data set names to reflect the names used in your installation and submit the job. The CAI.CAIEVENT library includes control members used to define CA products to the CAISDI/els interface. Each event member contains text and other control information used in opening USD request tickets by one of the CA products supporting this interface. CA Allocate DASD Space and Placement event members begin with GF. The product control member is named XGFCNTL and can be found in the CCTVJCL library. For information on activating and customizing the USD interface, see the CA Common Services documentation. About CAISDI A new CA Common Services component, CAISDI (Service Desk Integration), enables CA mainframe z/ OS products to automatically open request tickets in CA Service Desk for serious conditions that have been detected. You can optionally have the request tickets assigned to specific individuals. Thus, important problems are brought to the attention of the selected individual only seconds after they have been detected. Many CA products are using the Service Desk Integration for centralizing the management of serious mainframe problems. A complete list of these products can be found in the CA Common Services documentation. Product Integration 18

19 The additional installation steps required for this feature are described in Activate CA Service Desk Support (see page 18). Copy the event definition members for CA Allocate DASD Space and Placement to the CAI.CAIEVENT library and add a control statement to the CAISDI/els control parameter member, ELSSTART. Each event member defines a specific event for CA Allocate DASD Space and Placement. The event members contain the text to be used for the summary and description sections of the request ticket. Because these are ordinary source members, you can change the textual content to meet your specific requirements. In fact, the interface supports multiple languages, so you can optionally translate the text into one of the supported languages. The details of customizing CAISDI for this product and other CA products are described in the CA Common Services documentation. The CAISDI API call is conditional, so it does nothing until all the elements are in place and CAISDI is properly configured to communicate with your CA Service Desk server. If there is an event for which you never want a request ticket opened, remove that event definition member from the CAI.CAIEVENT library. The CAISDI component also provides a batch utility that can artificially trigger one of the events for CA Allocate DASD Space and Placement. While this utility was designed for testing the CAISDI connections, you can also use it to trigger events that you create. Simply define new events for your own purposes and store the event member in CAI.CAIEVENT. You can then use the utility as a conditional step in a JCL procedure to trigger the event you created. CAISDI uses web services technology to access CA Service Desk. To activate the interface, install and configure the following components : CA Service Desk r11 server accessible to the mainframe using TCP/IP TCP/IP on your z/os system CA Common Services r11 CAISDI on your z/os system CA Common Services r11 CAICCI on your z/os system For more information about activating this interface, see the CA Common Services documentation. CAISDI Implementation When one of the following conditions occurs, CA Allocate DASD Space and Placement calls the CAISDI API to open a CA Service Desk request ticket: ASR Compile Failure during INSTALL Operation Pool Table Build Failure during INSTALL Operation Quota Initialization Failure during INSTALL Operation Hook Installation Failure Hook Removal Failure When an SDUMP is taken Each of the above events is preceded by a specific message detailing the subevent condition that generated the CA Service Desk request ticket. ASR Compile Failure Subevents: VAM0005, VAM0026, VAM0506 Product Integration 19

20 Pool Table Build Failure Subevents: VAM0008, VAM0023, VAM0506 Quota Initialization Failure Subevents: VAM0024, VAM0025, VAM0309, VAM0327, VAM0353, VAM0355, VAM0358, VAM0362, VAM0418, VAM0506, VAM0524, VAM0525 Hook Installation Failure Subevents: VAM0001, VAM0015, VAM0018, VAM0057, VAM0063, VAM0202, VAM0203, VAM0204, VAM5011, VAM6002, VAM6003, VAM6004, VAM6005 Hook Removal Failure Subevents: VAM0015, VAM0019, VAM0058, VAM0065, VAM0363, VAM5025, VAM5028 When an SDUMP is taken: VAM0252 If the CAISDI component is installed and configured properly, a CA Service Desk request ticket is opened for the problem that was detected. While the call to the CAISDI API is made for each of these errors, the event definitions for many of these events include a MINTIME setting that might prevent the creation of more request tickets. Unless you change the CA Allocate DASD Space and Placement product control member, XGFCNTL, the request is tied to a CA Service Desk software asset named CA Allocate DASD Space and Placement and is assigned to a pseudo contact named System_Allocate_User. Optionally change the XGFCNTL member to specify a person as the assignee so the event is directed immediately to that specific person. Special Considerations for Using CA Allocate with Other Programs or Products (A-F) The following list describes special considerations for using CA Allocate DASD Space and Placement with other products. ACS Environment Processing (see page 21) Bypassing Allocations (see page 21) CA Compress (see page 21) CA Database Organizer (see page 22) CA Disk Backup and Restore, ROSCOE, and WIZARD (see page 22) COBOL II Users (see page 22) DATACLAS Sub-Parameter Override Space (see page 22) DB2 (see page 23) DFDSS (see page 23) DFSORT Workfiles (see page 23) Dormant Operation (see page 23) Extended Addressability Volumes (see page 23) Enqueue for the CQT (see page 24) Enqueue Propagation for the DQT (see page 24) FTP (see page 24) Product Integration 20

21 ACS Environment Processing The ACS environment is the earliest interface point in the allocation process. If CA Allocate DASD Space and Placement writes messages during JCL allocations, they are displayed before normal job startup messages. Because it is too early to scan for DDs in the ACS environment at batch JCL allocation time, DDs cannot be used as switches. For example, VDSBYPAS and #VAMTST# DDs are not detectable or usable. If the ACS environment must be bypassed for Batch JCL allocations, code the following value in the ASR: IF &VAMENVIR = 'ACS' THEN EXIT CODE(0) To get diagnostics, CA Allocate DASD Space and Placement must be running in ACTIVE mode and the DIAGS= option must be used. Bypassing Allocations To bypass CA Allocate DASD Space and Placement for all allocations in a step, allocate DDNAME VDSBYPAS to the step or TSO session. In a batch job step: //VDSBYPAS DD DUMMY For a TSO session: ALLOC FI(VDSBYPAS) DUMMY DD statements cannot always be seen in the ACS environment. To bypass all CA Allocate DASD Space and Placement processing for a job, including the ACS environment, modify your ASR. For example, add the following at the beginning of your ASR: IF &JOBNAME = 'MYJOB' THEN EXIT CODE(0) CA Compress Use the SHRINKTASK variable to verify that CA Compress is active on the system before CA Allocate DASD Space and Placement redirects the restore of a CA Compress data set. If CA Compress is not active, CA Allocate DASD Space and Placement should deny such restore requests. Failure to do so results in the loss of the CA Compress Safeguard Information. Product Integration 21

22 CA Database Organizer For CA Database Organizer, optional feature PLSEOV65 or PLSEOV69 is required to intercept non- VSAM DBO data sets in the EOV environment. CA Disk Backup and Restore, ROSCOE, and WIZARD These products are known to use internal parameters to control JCL step termination disposition. These parameters are inaccessible. Unpredictable results occur if CA Allocate DASD Space and Placement is used to change JCL step termination disposition (&DISPN) for non-vsam data set allocations requested by any of these products. For data sets cataloged for auto-restore (DMSAR), the variable &IFALREADYCAT specifies a 'Y'. PLSOPT16 (Y) is required for CA Disk operations to be considered eligible for the EOV support of CA Allocate DASD Space and Placement. COBOL II Users As delivered, the non-vsam End-Of-Volume support excludes data sets that have an ABEND or EOV exit coded in their DCB's exit parameter list. Some COBOL II allocations are considered to be ineligible for EOV processing for this reason. One of the following Optional Maintenance features can be used to disable such exclusions: PI PI DATACLAS Sub-Parameter Override Space Introduced with z/os 1.10, the DATACLAS sub-parameter Override Space can be used to stop users from overriding the Space Primary and Space Secondary DATACLAS sub-parameters in their original allocation request. Your ASR has the ability to selectively enforce DATACLAS sub-parameters with the Enhanced DATACLAS Support (see page 81). If you set Override Space to Y, the space amounts in the original allocation request will be changed to reflect the space amounts in the DATACLAS before the ALLOC environment launches. The space amounts from the original allocation request are lost forever. The PRIMARY and SECONDARY variables that would ordinarily reflect the space amounts in the original allocation request instead reflect the space amounts in the DATACLAS, duplicating information already available in the DC_PRIMARY and DC_SECONDARY variables. Your ASR would then be limited to two choices: Use the DATACLAS values Specify new values to be determined by the ASR Product Integration 22

23 DB2 The VSAM support in the EXTEND environment does not intercept requests associated with DB2 LSDS clusters, or KSDS clusters with either the KEYRANGE or IMBED attribute. DFDSS CA Allocate DASD Space and Placement is unable to successfully redirect non-sms-managed DFDSSrequested allocations. Unpredictable results can occur if the bypass DD statement, default name VDSBYPAS, is not used to exempt such allocations from processing. DFSORT Workfiles Do not use CA Allocate DASD Space and Placement to change the unit and space amount that is requested for DFSORT Workfiles. Specify PLSOPT32 (Y) in the sysparm override member of the data set that the PARMS DD statement references. The data set is referenced in the JCL that is used to install operating system interfaces for this product. Dormant Operation CA Allocate DASD Space and Placement can operate in a dormant mode, meaning it is installed and fully functional, but affecting only selected jobsteps and TSO sessions. Dormant mode is useful in many situations: beta release testing, installation testing, testing new ASR logic, and so on. To turn on CA Allocate DASD Space and Placement for a jobstep, allocate the ddname specified in the PLSDRMNT parameter. As shipped PLSDRMNT is #VAMTST#. After the operating mode is changed to DORMANT, add the #VAMTST# DDname to any jobstep or TSO session that CA Allocate DASD Space and Placement controls. For a batch job step, use: //#VAMTST# DD DUMMY For a TSO session, use: ALLOC FI(#VAMTST#) DUM Extended Addressability Volumes CA Allocate DASD Space and Placement supports the IBM Extended Addressability Volumes (EAV). IBM provides an operator command, SETSMS USEEAV(YES NO), to control whether to use EAV volumes for new allocations. If the SETSMS USEEAV command is issued to change from YES to NO, and CA Product Integration 23

24 Allocate DASD Space and Placement is in the process of selecting a volume for an allocation, then unpredictable results might occur. It is recommended that you should issue the SETSMS USEEAV(NO) command, when CA Allocate DASD Space and Placement is not selecting a volume for an allocation. Note: It is recommended that you should issue the SETSMS USEEAV(NO) command, when CA Allocate DASD Space and Placement is not selecting a volume for an allocation. Enqueue for the CQT The historical exclusive ENQ on the CSA QUOTA TABLE (CQT) has been changed to a conditional one to eliminate the possibility of an ENQ deadlock condition. This might result in QUOTA processing being bypassed if the ENQ on the CQT cannot be obtained after maximum time duration of two (2) seconds. Enqueue Propagation for the DQT The Disk Quota Table (DQT) is periodically synchronized with the CSA Quota Table (CQT) to ensure that both contain the same information. This synchronization occurs during the QSYNC process. During the QSYNC, a SYSTEMS enqueue serializes access to the quota tables across all systems using qname STERLING. To avoid corruption, do not make changes to GRS or MIM that might prevent cross system enqueues using the STERLING qname. In particular, do not change the scope from SYSTEMS to SYSTEM. FTP FTP allocation releases unused space by default. CA Allocate DASD Space and Placement can be used to prevent this in one of the following two ways: EXIT CODE(8) in the RELEASE environment SET &RLSE = 'N' in the ALLOC environment Special Considerations for Using CA Allocate with Other Programs or Products (G-P) The following list describes special considerations for using CA Allocate DASD Space and Placement with other products. HFS Unix File Systems (see page 25) IAM (see page 25) IDCAMS BLDINDEX Workfiles (see page 25) Initializing Tapes (see page 25) IODF (see page 26) ISAM (see page 26) Product Integration 24

25 MainView SRM (formerly STOP-x37) (see page 26) MVS System Logger Data Sets (see page 26) PDSE Data Sets (see page 26) HFS Unix File Systems The ALLOC environment intercepts requests associated with new UNIX data sets. The DSN variable has no meaning for these UNIX files as it simply contains something that looks like this: '...PATH=' Features that require an actual data set name, such as SNC2 support or optional EXIT08, are not applicable for new UNIX data sets. The EXTEND environment does not intercept requests associated with the physical PDSE data sets that are a logical component of HFS UNIX File Systems. IAM CA Allocate DASD Space and Placement can successfully redirect IAM allocations after the IAM Global Change Facility has been configured to specify 'ENABLE=VAM.' Also, start IAM before starting CA Allocate DASD Space and Placement. Note: Review the IAM documentation for information about activating the IAM VSAM Interface (VIF) and coexisting with other software products. PLSOPT6 (Y) must be specified in the parmlib to activate the new EOV support for IAM file update operations, which is only applicable to releases V6.4/07P and above of IAM. Activating this support for earlier releases of IAM results in C03 abends when those data sets are closed. IDCAMS BLDINDEX Workfiles CA Allocate DASD Space and Placement cannot modify the unit and volume that is coded for the IDCUT1 and IDCUT2 work files. Code the actual UNIT and VOL=SER parameters. In the DEFINE environment, you cannot redirect such allocations. Storage group Level DOES IT FIT (DIF) or LSPACE support has no meaning for these kinds of allocation requests. Initializing Tapes When executing IEHINITT to initialize tapes use a VDSBYPAS DD statement in the job. Alternatively, add code in the VDSPROG to bypass these jobs. If &PGM='IEHINITT' THEN EXIT CODE(0). We recommend adding a statement in the VDSPROG to exclude any other program that initializes the tapes. Product Integration 25

26 IODF Use caution when using the ACTIVATE IODF command that could create EDT problems if PLSOPT80 is activated. In such cases, perform an immediate VAM REFRESH command to rebuild the internal EDT and be in synch with the new EDT. ISAM CA Allocate DASD Space and Placement cannot recover ISAM data sets from end-of-volume conditions. Defining ISAM data sets as multi volume ones might prevent end-of-volume conditions. MainView SRM (formerly STOP-x37) MainView SRM can change the secondary extent size of a data set. Unpredictable results occur, if both products attempt to do this for the same allocation. MVS System Logger Data Sets System Logger data sets can be either SMS-managed or NonS-MS. Both are VSAM data sets allocated through SVC99. To make them SMS-managed, redirect them in the ACS environment to a DFSMS storage group. To make them non-sms-managed, redirect them in the ALLOC environment to a non- SMS storage group. PDSE Data Sets The VSAM support in the EXTEND environment does not intercept requests associated with PDSE data sets. Special Considerations for Using CA Allocate with Other Programs or Products (Q-Z) The following list describes special considerations for using CA Allocate DASD Space and Placement with other products. SMS-Managed GDGs (see page 27) SMS-Managed Non-VSAM Data Sets (see page 27) SMS Subsystem Interface (see page 29) SnapShot (see page 29) SVC and DADSM Branch Entry Interface (see page 29) Virtual Tape Systems (see page 29) VTS Redirection Issues (see page 29) Product Integration 26

27 XCOM (see page 30) XPEDITER (see page 30) ZFS UNIX File Systems (see page 30) SMS-Managed GDGs The pair of major/minor enqueues associated with DFSMS's automatic scratch of the oldest generation of an SMS-managed GDG (following the successful creation of a new generation of that same GDG) are identical to but gotten in precisely the opposite order as the pair of major/minor enqueues IBM code associates with the SVC26 requests that the product issues when it is retrieving the IFCAT variables. To avoid a possible deadly embrace, CA Allocate DASD Space and Placement has stopped issuing IFCATrelated SVC26 requests for SMS-managed GDGs. This often results in an IFCAT value of? Additionally, because those automatic scratches are actually a function of DFSMS's GDG ROLLIN process, and as such must complete successfully, they are now considered ineligible for SCRATCH environment processing. SMS-Managed Non-VSAM Data Sets In the "DADSM Pre- and Post processing Installation Exits" section of their z/os V1R7.0 DFSMS Installation Exits guide (SC ), IBM specifically states "For a create request on an SMS-managed volume, if the pre-processing exit changes the primary space amount, it has no effect." This means that you are not able to use CA Allocate DASD Space and Placement to alter the primary allocation amount in either the SPACE environment or in the EXTEND environment (when EXTENDVOL=NEW only). IBM spreads across several sections in their z/os V1R12.0 DFSMSdfp Storage Administration Guide (SC ) some of the details about how their SMS component allocates new multi-stripe PSE data sets. Allocations of new multi-stripe PSE data sets look as follows: 1. Space is allocated on all volumes that are associated with a stripe when the data set is initially allocated. 2. The amount of primary space that is requested for the data set is actually the total amount of primary space that is allocated across all the stripes. This means that the actual amount of primary space that is required for each stripe: Is calculated by dividing the primary amount requested in the allocation request by the total number of stripes. Rounding up of the quotient to the next whole number might result in a bit larger total allocation amount than the allocation requestor specified. ISPF I statistics reflect the following: First extent <in units of space type> represents the actual size of each stripe. Number of volumes allocated (shown when accessing the details on the Volume Information) represents the number of stripes. The number of stripes shows in the STRIPE-COUNT field in the output from a LISTC ENT ALL of the data set. Current Allocation Allocated <in units of space type> represents the total amount that is allocated across all stripes. The number is the first extent that is multiplied by the number of volumes allocated. 3. Allocation of the first stripe can be intercepted in the ALLOC environment when running with PLSOPT10 (Y). The default of PLSOPT10 is (N). Product Integration 27

28 4. Allocation of the first strip can be intercepted in the SPACE environment when running with PLSLSPA (Y). The default value of PLSLSPA is (Y). Target volume can be seen by displaying the value of the ANYVOL variable. 5. Allocation of the first stripe can be intercepted in the QUOTA environment when running with SUPLSQ (Y). The default of SUPLQ (N). Target volume can be seen by displaying the value of the VOLSER variable. In addition, the value displayed in the QUOTAFUNC variable is ALLOC. 6. If the allocation of the first stripe on the target volume is not successful, SMS checks if any other potential volumes are available in the associated storage group. When it finds a volume, SMS redrives the allocation request. 7. Re-driven allocation requests can be intercepted in the ALLOC environment when running with PLSOPT31 (Y). The default of PLSOPT31 is (N). 8. Re-driven allocation requests for the first stripe can still be intercepted in the SPACE environment when running with PLSLSPA (Y). 9. Once allocation of the first stripe on the target volume is successful, SMS starts allocating the same amount of space for each additional stripe. 10. Allocation of each of the remaining stripes can be intercepted in the EXTEND environment when running with PLSLEXT (Y). The default value of PLSLEXT is (Y). Target volume can be seen by displaying the value of the VOLSER variable. In addition, the value displayed in the EXTENDVOL variable is NEW. 11. Allocation of each of the remaining stripes can be intercepted in the QUOTA environment when running with SUPLSQ (Y). The value displayed in the QUOTAFUNC variable is EXTEND. 12. If one of the allocations of one of the additional stripes on the target volume that SMS chose fails, SMS deletes all the stripes that it had already allocated, and starts over again at (7). 13. Any deletions of the stripes of a partially allocated data set done in (12) can still be intercepted in the SCRATCH environment when running with PLSLSCR (Y). The default value of PLSLSCR is (Y). 14. Any deletions of the stripes of a partially allocated data set done in (12) can still be intercepted in the QUOTA environment when running with SUPLSQ (Y). The value displayed in the QUOTAFUNC variable is SCRATCH. Part of the internal processing that SMS does in Step 12 may result in SMS decreasing the number of stripes. The action results in a larger primary amount that is required for each stripe. Sometimes this internal adjustment by SMS is enough to get the PSE data set allocated with multiple stripes, sometimes it is not. The additional actions SMS might be able to do on its own to downgrade a PSE data set to a PS one, in the event there is insufficient available free space for even a single striped PSE, can be found in various sections of IBM z/os V1R12.0 DFSMSdfp Storage Administration Guide (SC ). The Does It Fit (DIF) support can be deployed in the ALLOC environment launches to detect possible Space Not Available conditions and reduce the primary amount that is required for each strip. This action will likely: Reduce the number of times a potential target volume that SMS choses is found to be lacking sufficient free space. Reduce the number of times that SMS needs to scratch a partially allocated multi-striped data set, possibly decrease the stripe count, and then re-drive the allocation request. Increase the likelihood that the new PSE data set gets allocated as a multi-striped one, even though the total primary amount is smaller than originally requested. Product Integration 28

29 SMS Subsystem Interface For CA Allocate DASD Space and Placement to redirect allocations during DFSMShsm RECALLs and RECOVERs, which are not SMS-managed, the IBM SMS (System Managed Storage) subsystem must be installed and active on your system. You do not have to configure the IBM SMS to do anything in particular. SnapShot Exclude SnapShot target data sets from the EOV, EOV_VSAM, and EXTEND environments and do not process them with either the DIF support or the LSPACE support. According to IBM, the SIBBATCH program cannot handle any space change or volume redirection done by any other OEM product at this time. To exclude in the EOV and EOV_VSAM environments: IF &VAMENVIR = 'EOV_VSAM' AND &PGM = 'SIBBATCH' THEN EXIT CODE(0) IF &VAMENVIR = 'EOV' AND &PGM = 'SIBBATCH' THEN EXIT CODE(0) SVC and DADSM Branch Entry Interface CA Allocate DASD Space and Placement intercepts all accesses to DADSM allocation routines. When installed, it replaces the address to DADSM and SVC 32 with its own DADSM routine address. It interfaces to DADSM and informs allocation routines when it is performing a modified allocation. After the DADSM interface is complete, normal DADSM processing continues. Virtual Tape Systems To redirect to a Virtual Tape System (VTS), SET a VTS unit in the ALLOC environment. If converting a non-vts tape allocation to a VTS tape system, when VOL=REF= and/or UNIT=AFF= are coded, these attributes should be kept, not shut off as is common for TAPE to DISK conversions. VTS Redirection Issues Failure to a set a VTS unit in the ALLOC environment might generate these error messages: IEF344I jobname step DD - ALLOCATION FAILED DUE TO DATA FACILITY SYSTEM ERROR IGD17207I VOLUME SELECTION HAS FAILED - THERE ARE NO ACCESSIBLE VOLUMES FOR DATA SET IGD17277I THERE ARE (0) CANDIDATE VOLUMES Product Integration 29

30 XCOM Optional feature PLSEOV65 or PLSEOV69 is required to intercept non-vsam XCOM data sets in the EOV environment. XPEDITER For XPEDITER allocations, the variable &IFALREADYCAT specifies a 'Y'. ZFS UNIX File Systems The VSAM support in the EXTEND environment does not intercept requests associated with the physical LSDS VSAM data sets that are a logical component of ZFS UNIX File Systems. VSAM EOV support for these data sets is limited to dynamically allocating an additional candidate volume to these data sets. The PRIMARYD and SECONDARYD values in EOV_VSAM are taken from the LSDS clusters catalog entry, just as they are for all other VSAM EOV conditions, and may not accurately reflect the amount of space UNIX is actually looking for. Since any changes to the PRIMARYD variable in the EOV_VSAM environment are ignored by UNIX, CPU cycles would be wasted for the ASR to invoke either LSPACE support or DIF support. Product Integration 30

31 Concepts and Facilities CA Allocate DASD Space and Placement performs these important functions: Simplifies the task of allocating data sets for end users. Enables you to use the system to enforce installation standards. Enables you to establish DASD space limits for individuals or groups of users. The system automatically monitors the limits and optionally enforces them. Depending on the function, the Storage Administrator can determine the appropriate level of enforcement. This level might be simply to issue a warning message and let the allocation continue. Another option is to cancel the allocation whenever a violation takes place. The product can be configured to correct the violation automatically whenever it can and to continue with the allocation process. Without the product, the data center must rely on its users to put their data sets on the right volumes. As more volumes are brought online, data set placement becomes unmanageable. Volume pooling simplifies this process by reducing the number of items that must be managed. Instead of managing 1,000 volumes, the Storage Administrator can decide to manage ten pools or, in terms of the product, storage groups. This product can enforce the standards and DASD space limits that users often forget. The product can enforce standards and DASD space limits automatically, freeing the Storage Administrator from having to correct violations. These topics present some guidelines to consider during implementation. The topics are not intended as an exhaustive study. Rather, they are presented as an aid in understanding the facilities that this product offers. Each of the concepts is presented under its own heading to assist you in finding a specific area of interest. Basics CA Allocate DASD Space and Placement allows the Storage Administrator to associate one or more volumes logically to form a common grouping. The grouping is known as a storage group. The volumes typically share common characteristics. For example, they might all be 3390 devices that are used for production jobs by the accounting department. After these logical pools have been defined and implemented, users can remove the JCL VOLUME parameter. Before the product can control allocation of data sets, several parameter files must be created. They must be stored as members of a partitioned data set resembling in function SYS1.PARMLIB, as follows: CONFIG Used during Allocate startup to a point to desired member for VKGPARMS. QCONFIG Quota Configuration File that defines the Quota processing options and optional manually defined Quota Groups. Concepts and Facilities 31

32 QREBUILD Quota Volume Selection ASR that is executed for every volume that is online at the time the Quota Table is rebuilt. This file is for the QREBUILD environment. QSCAN Quota VTOC Scan ASR that is executed for every data set in each Volume Table of Contents (VTOC). This file is for the QSCAN environment. VDSPROG Allocation Selection Routine (ASR) that is executed for every new allocation request. This member contains the logic for ACS, ALLOC, DEFINE, EOV, EOV_VSAM, EXTEND, OLD, QUOTA, RELEASE, RENAME, SCRATCH, and SPACE environments. VDSTORGP Storage group definitions that assign names to groups of disk volumes (storage pools). VKGPARMS This member allows the Storage Administrator to customize the data set names, member names, special DD names, and alter other operational parameters. For more information about these members, see the sections Implementation (see page 108) and Quota (see page 177). Note: The QREBUILD, QSCAN, and QCONFIG members are only needed if the Quota selectable unit is present. After these members are created, the MVS operator can start the product by entering the following command: S VAM During startup, it does the following items: Reads system parameters. Compiles the ASRs. Reads and validates the storage group definitions. Reads and validates the Quota Configuration File. If all parameters processed in steps 1 through 4 are satisfactory, then the product loads its components into CSA and SQA memory and intercepts: DADSM SVC (SVC 32) The DADSM pre-allocation and post-allocation exits (IGGPRE00 and IGGPOST0) Allocation (SVC 99) Catalog Management SVC (SVC 26) End-of-Volume DASD Output (SVC 55) Unit Allocation (IEFAB435) IBM ACS Processing Routine Concepts and Facilities 32

33 Environments The environment indicates what allocation action is causing CA Allocate DASD Space and Placement code to be entered. Depending on the environment, the ASR takes different actions. For example, the NEWNAME variable is checked only for a RENAME operation, because only RENAME causes a new name to be created. Likewise, for a new space allocation you are checking different variables and taking different actions than for a scratch operation. The following environments are used during data set operations: Environment Name ACS ALLOC DEFINE EOV EOV VSAM EXTEND OLD PREALLOC QUOTA RELEASE RENAME SCRATCH SPACE Launch sysparm PLSACS PLSLALLO PLSLDEF PLSLEOV PLSLEOVV PLSLEXT PLSLOLD PLSLPREA SUPLSQ PLSLREL PLSLRENM PLSLSCR PLSLSPA The launch sysparm allows you to disable environment launches logically. This method results in a runtime performance improvement because the overhead associated with the physical launch of those environments is not needed. The default value of each of the launch sysparms is (Y), which causes each Environment to launch for applicable allocation requests. To disable any particular environment from launching logically, specify a value of (N) in your sysparm override member before either an INSTALL or PARMREF operation. Sysparm SUPLSQ has a default value of (N), which prevents the launch of the Quota Features. The Quota Feature has three environments: QUOTA Concepts and Facilities 33

34 QSCAN QREBUILD Note: We recommend that you set SUPLSQ to (Y) with proper LMP licensing. Sysparm PLSEXJOB can be used to allow a specific batch job, started task, or TSO User to be exempt from any logical global bypass that might be in effect by one of the launch sysparms. If your ASR does nothing with any specific environment, consider deactivating that environment. Set the appropriate launch sysparm to (N). The following environments are used while the Quota Table is rebuilt during a QREBUILD operation. These environments receive control from the started tasks: QREBUILD QSCAN For more information about these started tasks, see the section Quota (see page 177). The code is entered at the following points in data set processing: Where Environments Data Set TYPES In front of the Common Allocation routine(svc 99) PREALLOC, ALLOC, OLD Non-VSAM and VSAM (JCL define only). IGDACS00 ACS All IGGPRE00 (IBM-provided exit point) RELEASE, RENAME, SCRATCH, SPACE EXTEND, QUOTA Non-VSAM only Non-VSAM and VSAM IGGPOST0 (IBM-provided exit point) None Non-VSAM and VSAM In front of Catalog Management (SVC 26) End-of-Volume DASD Output (SVC 55) DEFINE, EOV_VSAM EOV VSAM only Non-VSAM only. The preceding information is summarized in a slightly different manner; see the variable description VAMENVIR in Implementation (see page 108). The following topics contain a brief description of each of the environments: ACS Environment (see page 35) ALLOC Environment (see page 37) DEFINE Environment (see page 38) Concepts and Facilities 34

35 EOV Environment (see page 39) EOV_VSAM Environment (see page 40) EXTEND Environment (see page 41) OLD Environment (see page 43) PREALLOC Environment (see page 45) QREBUILD, QSCAN, QUOTA Environments (see page 47) RELEASE Environment (see page 47) RENAME Environment (see page 48) SCRATCH Environment (see page 49) SPACE Environment (see page 50) ACS Environment The ACS environment receives control for any Automatic Class Selection (ACS) processing that any system component requests. ACS processing is used to select or remove any of the following four SMS constructs. For more information about the four IBM SMS constructs, see the IBM DFSMSdfp Storage Administration Reference documentation. Data class DATACLAS Storage class STORCLAS Management class MGMTCLAS Storage group STORGRP CA Allocate DASD Space and Placement receives control after the normal IBM ACS processing. The product then runs through the ASR routine of the user. The ASR routine can look at, set, or can remove any of the four SMS constructs. The original user request, or the IBM ACS processing (if any) might have set the SMS constructs. No IBM ACS processing is required. The ACS environment can act as a direct replacement for the IBM ACS routines. This replacement lets the Storage Administrator use the greater power of the ASR rules language. This replacement also provides a single point for control of SMS and non-sms-managed allocations. The following items apply: The values of any data set attributes made available as read-only in the product's ACS environment reflects the same value that is displayed for those attributes in the IBM ACS environments. IBM procedures might require some minimum ACS routine setup. For more information, see the IBM documentation. All four constructs in the ASR rules can be set for each request that is made for ACS processing. If a particular construct is not requested, setting it has no effect. We recommend that you have one set of ACS logic in your ASR rules that sets all the constructs that are needed, all at one time. Doing so simplifies rules writing. ASR rules can also set return and reason code information, to be returned to the ACS requestor. The variables &ACSRC and &ACSRSN contain the values of the return code and reason code respectively. Concepts and Facilities 35

36 Upon entry to the ACS environment, these two variables contain the values set by the IBM ACS processing. They can be looked at and overridden. For example, if the JCL DATACLAS is bad, and no IBM ACS processing is involved, at entry into the ACS environment, &ACSRC sets to return code 8 and &ACSRSN sets to reason code These return and reason codes are documented in the IBM DFSMSdfp Diagnosis Reference documentation. For more information, see the sections SMS Subsystem Interface Return Codes and ACS Services Reason Codes. To keep the allocation from failing, the ASR routine can set a valid data class name, or can remove the bad data class name by setting it to null, set variables &ACSRC and &ACSRSN to zero, and can exit the ASR with an EXIT CODE(0). Any system component that requests ACS processing for any of the four SMS constructs sees the returned construct names simply as if the normal IBM ACS processing had set them. In a single request for ACS processing, a system component can request the return of any or all of the four SMS constructs. The following list shows the most common requestors of ACS processing and the constructs that each requestor requests: BATCH JCL ACS activity - This type of activity can be for VSAM or non-vsam, including dynamic allocations (SVC 99), such as TSO ALLOC, ISPF 3.2, and others. One ACS call is made. This call requests all four constructs. IDCAMS ACS activity - This type of activity can be for VSAM or non-vsam, including File-Aid VSAM allocations. For SMS or non-sms-managed, the system makes one ACS call for the three classes to determine if a data set is SMS-managed. For SMS-managed only, the system makes 1 more ACS call for the storage group only. DFDSS ACS activity - This type of activity can be for VSAM or non-vsam. For SMS or non-smsmanaged, the system makes 1 ACS call for STORCLAS and MGMTCLAS, but no DATACLAS is requested. For SMS-managed only, the system makes 1 more ACS call for storage group only. The ACSENVIR variable is equal to RECOVER. CA Disk Backup and Restore ACS activity - For non-vsam it works the same as batch JCL and dynamic allocation activity that is described earlier. For VSAM, it works the same as IDCAMS activity described earlier. DFHSM ACS activity - This activity can be for VSAM or non-vsam and includes RECOVER and RECALL. For SMS or non-sms-managed, the system makes one ACS call for STORCLAS and MGMTCLAS only, but no DATACLAS is requested. For all but PO RECALLs, it works as the same as the preceding DFDSS. During a PO RECALL, ACS is entered one time for the &DSN real name and a second time for &DSN HSM name. The following illustration shows an example of an ACS environment ASR code: Concepts and Facilities 36

37 Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(ACS) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'ACS' THEN DO SET &DATACLAS = '' /* DEFAULT TO NO DC */ IF &DSORG = 'PO' THEN SET &DATACLAS = 'PODC' /* DEFAULT FOR PO */ IF %HLQ = 'SYS1' THEN SET &STORCLAS = ' ' /* NOT SMS-MANAGED */ ELSE DO SET &SC = 'SMSVOL1' /* SMS-MANAGED */ SET &MC = 'MANCL1' /* MANAGEMENT CLASS */ SET &SG = 'SMSGRP1' /* SMS STORAGE GROUP */ END SET &ACSRC = 0 /* GOOD RETURN CODE */ SET &ACSRSN = 0 /* GOOD RETURN CODE */ EXIT CODE(&ACSRC) /* GOOD RETURN CODE */ END ******************************** Bottom of Data ******************************* ALLOC Environment The ALLOC environment is entered for every new non-vsam space allocation request, either batch or dynamic (SVC 99), and VSAM data sets allocated through SVC 99. For example, for JCL VSAM defines, use &DSORG to detect VSAM. This environment is NOT entered for direct DADSM space requests (SVC 32) that some utilities like IBM IEHMOVE use. The SPACE environment is entered for direct SVC 32 requests. The ALLOC environment is special and provides the most powerful functions. This environment is not restricted to the capabilities of the IBM-provided DADSM preallocation exit (IGGPRE00), as are all the rest of the environments. Most of the output variables (changeable variables) can be changed in the ALLOC environment. The following illustration shows an example of ALLOC environment ASR code. Concepts and Facilities 37

38 Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(ALLOC) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'ALLOC' THEN DO IF &DSTYPE = 'PERM' AND /* FOR PERMANENT DATA SETS */ &DSORG = 'PS' THEN /* THAT ARE SEQUENTIAL */ SET &RLSE = 'Y' /* FREE UNUSED SPACE AT CLOSE */ IF &DSTYPE = 'TEMP' THEN /* TEMPORARY DATA SETS ARE TO BE */ SET &STORGRP = 'SCRATCH' /* REDIRECTED TO SCRATCH POOL */ ELSE IF &PGM = 'ADSMI002' AND /* IF CA DISK IS EXECUTING AND */ &DSN = *.DMS*.D*.T* THEN /* THE DATA SET IS AN ARCHIVE */ SET &STORGRP = 'ARCHIVE' /* REDIRECT TO THE ARCHIVE POOL */ ELSE SET &STORGRP = 'PRIMARY', /* ALL OTHERS GO TO PRIMARY POOL */ 'OVERFLOW' /* ANY EXTRA TO OVERFLOW POOL */ END ******************************** Bottom of Data ******************************* One of the most important output variables (from a pooling standpoint) is the storage group (STORGRP, SG) variable. For a non-sms-managed allocation, setting a storage group causes the product to go through its automatic volume selection routines. The routines select the best volumes from the pools of volumes that are defined in the VDSTORGP member. All allocations that are seen by the ALLOC environment are also seen by the SPACE environment; unless they are explicitly failed in the allocation in the ASR with an EXIT CODE(4) statement. DEFINE Environment Enter the DEFINE environment for every non-sms Managed VSAM DEFINE request to Catalog Management (SVC 26) for a Cluster or Alternate Index. You can change most output variables within the DEFINE environment. For more information, see ASR Variables by Environment 1 and Enhanced DATACLAS Support (see page 81). To intercept SMS Managed new VSAM data set allocations in this environment, run with PLSOPT10 (Y). VSAM data sets, that either JCL DD statements or SVC99 requests created, enter the ALLOC environment before they enter the DEFINE environment. IBM SYSTEM LOGGER log stream data sets are allocated this way. Do any redirection of non-sms Managed VSAM in the ALLOC environment where these data sets can be identified when the value of the MODULE variable is IEFIIC. Do modification of VSAM-specific data set attributes in the DEFINE environment. If you have defined Free-Space Threshold for the storage groups you are assigning in this environment, consider running with PLSOPT41 (Y). If an unexpected Space Not Available condition occurs with the volume that was chosen, set PLSOPT41 to (Y). You can redrive the volume selection process. The following illustration shows an example of DEFINE environment ASR code. 1 Concepts and Facilities 38

39 Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(DEFINE) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'DEFINE' THEN DO SET &CATONDEFOK = 'N' /* DISALLOW CAT NAME ON DEFINE */ SET &STEPCATOK = 'N' /* DISALLOW STEPCAT (IF ANY) */ SET &JOBCATOK = 'N' /* DISALLOW JOBCAT (IF ANY) */ SET &OWNERID = &USER /* OWNER OF VSAM DATA SETS */ IF &HLQ = 'ONLINE'THEN /* IF ONLINE DATA SET */ DO SET &INDEXSEP = 'Y' /* PUT INDEX COMPONENT ON A */ SET &STORGRP1 = 'CACHEDB' /* HIGH PERFORMANCE VOLUME AND */ SET &STORGRPD = 'DATABASE' /* REDIRECT DATA COMPONENT */ END ELSE /* ALL OTHER VSAM DATA SETS */ IF &HLQ Ø= SYS% /* EXCEPT FOR SYSTEM ONES */ THEN SET &SG = 'PRIMARY', /* ARE TO BE REDIRECTED */ 'OVERFLOW' END ******************************** Bottom of Data ******************************* You can also enter this environment for DEFINE GENERATIONDATAGROUP requests. For more information, see the PLSGDGBA parameter (see page 109). EOV Environment Within the EOV environment, volumes can be dynamically added to a non-vsam output DASD data set that has exhausted its space allocation. For more information about VSAM data sets, see EOV_VSAM Environment (see page 40). This environment is entered whenever a job is about to fail for a system B37 or E37 type abend condition. As with the EXTEND environment, EOV is entered only for data sets that have a secondary space amount defined. The product becomes involved because the operating system tried to allocate secondary space to the data set but failed. If no secondary space amount was coded in the initial allocation JCL, the operating system would never try to add space. Some situations that can cause the EOV environment to be entered include: The current output volume is full and no more volumes are allocated to the data set. The current output volume lacks enough space to allocate the requested amount of secondary space, and no more volumes are allocated to the data set. The data set already has 16 extents that are allocated on the current volume and no more volumes are allocated to the data set. The EOV environment lets you control and save the job by coding ASR statements that set the STORGRP or POOLSUB variable. Any defined STORGRP name that is appropriate for the current situation might be used. Non-SMS-managed data sets are not restricted at end-of-volume time to the STORGRP specified in the original allocation. When a STORGRP is set for non-sms-managed data sets, an attempt is made to pick a volume from the storage pool that: Is not currently allocated to the data set Is of the same device type Concepts and Facilities 39

40 Has sufficient free space to hold the requested allocation amount Maintains free-space threshold requirements The product tries to maintain the percentage of free space that is defined for a volume in the VDSTORGP parameter file. This percentage is referred to as the free-space threshold and is specified in the VDSTORGP parameter file. Volumes that can be used for allocating the required space amount are seen as being either first or second choice volumes. First choice volume The required space amount can be allocated without exceeding the freespace requirement. Second choice volume The free-space requirement must be exceeded to allocate the required space amount. The EOV_VSAM environment lets you control and save the job by coding ASR statements that set the STORGRP variable. Any defined STORGRP name that is appropriate for the current situation might be used. Non-SMS-managed data sets are not restricted at end-of-volume time to the STORGRP specified in the original allocation. When a STORGRP is set for non-sms-managed data sets, an attempt is made to pick a volume from the storage pool that: Is not currently allocated to the data set Is of the same device type Has sufficient free space to hold the requested allocation amount Maintains free-space threshold requirements If no first choice volume can be found within the storage group, a second choice volume is selected. If the product cannot find a volume within the storage group that can satisfy the requested space amount, it cannot add a volume. In this case, the allocation proceeds to the original B37 or E37 condition. Because volumes can be dynamically added on demand, the Storage Administrator can select to force initial multivolume allocations to a single volume (SET &NVOL=1, &NUNIT=1 in the ALLOC environment). If a data set runs out of space, the product can add volumes as needed. For SMS-managed data sets, SMS picks the volume from the SMS STORGRP associated with the data set. For more information, see Use EOV and EOV_VSAM Environments with a SMS-Managed Data Set (see page 64). EOV_VSAM Environment Within the EOV_VSAM environment, candidate volumes can be dynamically added to a VSAM output data set. For non-vsam data sets, see EOV Environment (see page 39). The EOV_VSAM environment is entered whenever the VSAM EOV requests the next candidate volume, and VSAM indicates that there are no more candidates. The environment becomes involved because the operating system tried to allocate a new output volume and could not. Some situations that can cause the EOV_VSAM environment to be entered include: The current output volume is full and no more candidate volumes are available. The current output volume does not have enough space to allocate the requested amount of secondary space. No more candidate volumes are available. Concepts and Facilities 40

41 CA Allocate DASD Space and Placement tries to maintain the percentage of free space that has been defined for a volume. This percentage is referred to as the free-space threshold and is specified in the VDSTORGP parameter file. Volumes that could be used for allocating the required space amount are seen as being either first or second choice volumes. First choice volume The required space amount can be allocated without exceeding the freespace requirement. Second choice volume The freespace requirement must be exceeded to allocate the required space amount. If no first choice volume can be found within the storage group, a second choice volume is selected. If it cannot find a volume within the storage group that can satisfy the requested space amount, it cannot add a volume. Because volumes can be dynamically added on demand, the Storage Administrator can decide to force initial multivolume VSAM defines to a single volume (SET &NVOLD=1 in the DEFINE environment). If a data set runs out of space, CA Allocate DASD Space and Placement can then add volumes as needed. For SMS-managed data sets, SMS picks the volume from the SMS STORGRP associated with the data set. For more information, see Use EOV and EOV_VSAM Environments with a SMS-Managed Data Set (see page 64). EXTEND Environment This topic includes both non-vsam and VSAM processing in the EXTEND environment. Non-VSAM Processing in EXTEND This environment is entered whenever a data set must grow out to another extent (that is, needs more disk space). Non-VSAM data sets need a secondary amount to continue to grow after they have exhausted their primary amount. The EXTEND environment is launched before the allocation of each additional extent. To get to this environment, the data set must either have been originally allocated with secondary amount or CA Allocate DASD Space and Placement must be running in a PLSZSEC (Y) configuration. See EOV Support for Zero Secondary (see page 68) and the SECONDARY_HAD_ZERO 2 variable description for how to avoid D37 abends and how then to detect that they had been avoided. In this environment, the Storage Administrator can decide to examine the current number of extents to which the data set has grown, and perhaps increase the secondary allocation amount to decrease the chance of getting an abend for an allocation that is too small. The following illustration shows this method. Another way to avoid an out-of-space abend is to add a volume to the data set in the EOV environment dynamically. The following illustration is a sample EXTEND environment ASR: 2 Concepts and Facilities 41

42 IF &VAMENVIR = 'EXTEND' THEN DO IF &EXTENDVOL = 'CURRENT' THEN DO /* INVOKE DIF SUPPORT */ /* TO KEEP DATA SET ON SAME VOLUME */ /* AS LONG AS POSSIBLE */ SET &REDUCE_BY = 10 SET &MINIMUM_PERCENT = 25 END Note: If a non-vsam extend request is rejected in the ASR, the job requesting the extension abends with a system code E37-0C. This situation is a restriction of the DADSM IGGPRE00 exit. The value of SECONDARY variable in EXTEND typically reflects the current secondary allocation amount which might not be the original secondary allocation amount. For more information, see the SECONDARY_ORG 3 variable description to obtain access to the secondary allocation amount specified for the data set when it was first allocated. VSAM Processing in EXTEND This environment is entered whenever a cluster must grow into another extent. However, this support is deactivated by default. For activation procedures, see PLSOPT11 in the section PLSOPTnn Sysparms (see page 126). End of Volume (EOV) processing is typically the cause for entering this environment, as long as the cluster definition has secondary allocation. The following items apply: The difference between this support and that for non-vsam is that with non-vsam, the space that is allocated for a new volume extent is associated with the secondary allocation amount of the data set. VSAM, typically the primary allocation amount of the cluster, is used for new volume extents. This can be changed, for SMS-managed data sets only, using the ADDITIONAL VOLUME AMT DATA CLASS attribute. Restrictions to VSAM Processing in EXTEND The following VSAM data sets are not supported: VSAM clusters that are defined to IMS KSDS clusters that are defined with either the KEYRANGE or IMBED attributes VSAM clusters that are associated with SNAPSHOT copies VSAM clusters that are associated with the zfs UNIX File Systems VSAM allocations that are made by the IBM Media Manger Services, including, but not necessarily limited to, those allocations of the DB2 DBM1 STC and the BMC LOAD+ Utility. 3 Concepts and Facilities 42

43 OLD Environment The OLD environment is entered for any batch job's allocation request for an old, cataloged data set that might be specifying invalid unit information which, if ignored, terminates the request with an IEF210I UNIT FIELD SPECIFIES INCORRECT DEVICE NAME JCL error. This condition most often occurs when CA Allocate DASD Space and Placement is instructed to redirect the original allocation to a different device type without changing the UNIT type in the JCL to reflect the change. For performance reasons, this support by default is limited to only cataloged data sets. To include DISP=OLD allocations without a DSN, set PLSGSNOL(Y). In addition, the following data set types are automatically bypassed: VSAM SMS-managed Non-SMS-managed without any UNIT value Archived or migrated data sets Two variables are available: UNITMISMATCH (UMM) is a yes or no flag indicating whether there is an inconsistency between what is specified in the JCL and what is in the catalog entry. FIXUNITMISMATCH (FUMM) contains the name of a valid UNIT that prevents the JCL error. For disk data sets, FUMM always contains 'SYSALLDA'. For tape data sets, FUMM contains the generic unit name that is associated with the device type in the catalog entry (for example, '3480', '3420', and so on). Note: The OLD environment compares the unit information in the catalog against what is coded in the JCL. If the product thinks there is a difference, it is a UNITMISMATCH (UMM). When you originally allocate a data set with an esoteric (for example, VAULT) UNIT=VAULT, the generic, rather than the esoteric, is stored in the catalog (3490). If you reference it again with the esoteric, the UNIT=VAULT (esoteric) does not equal the CATALOGUED UNIT=3490 (generic), thus the UNITMISMATCH condition and it is resolved to a generic name (3490). The following illustration shows an example of an Allocation Selection Routine for the OLD environment that detects and corrects a unit mismatch condition: Concepts and Facilities 43

44 Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(VDSPROG) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'EXTEND' AND &EXTENTS > 8 THEN /* IF RUNNING OUT OF EXTENTS, */ SET &SECONDARY = 2 * &SECONDARY /* INCREASE SIZE OF ALLOCATION */ IF &VAMENVIR = 'OLD' THEN DO IF &UNITMISMATCH = 'Y' /* IF UNIT MISMATCH DETECTED */ THEN /* CORRECT IT TO PREVENT */ SET &UNIT = &FIXUNITMISMATCH /* JCL ERROR & JOB FAILURE */ IF &NUNIT > &CAT_VOL_COUNT /* EXCESS UNIT-COUNT IN JCL*/ THEN /* REDUCE TO INSURE */ SET &NUNIT = &CAT_VOL_COUNT /* EOV SUPPORT ELIGIBILITY*/ END IF &VAMENVIR = 'RELEASE' THEN DO IF &HLQ = SYS% THEN /* IF SYSTEM DATA SET */ DO WRITE 'YOU MAY NOT RELEASE SPACE FROM A SYSTEM DATA SET' EXIT CODE(8) /* THEN DISALLOW THE RELEASE */ END END ******************************** Bottom of Data ******************************* In addition to the UMM and FUMM variables, the OLD environment has access to most of the inputonly ones available in the ALLOC environment, as shown in ASR Variables by Environment 4. Like the UNIT parameter that is shown in the previous illustration, the Allocation Selection Routine can examine others (for example, Data Set Name, User, Job Name) to decide whether to fix the unit mismatch. If volumes are specified in the allocation request, they must match the ones in the catalog entry exactly, in both number and sequence. When they do not, the allocation request is considered to be for an uncataloged data set, and the OLD environment is bypassed. If it is not possible to determine the catalog status of the data set, as happens with specific allocation requests on DFP Release 2 systems, the OLD environment is bypassed. Uncataloged data sets are skipped to avoid the significant overhead that is involved in accessing individual DASD VTOCs or Tape Management System control files. Note: Results are unpredictable when UNIT is set to anything but &FIXUNITMISMATCH in the OLD environment. Another feature of the OLD environment is to allow reduction of unit-count values that are specified in the JCL UNIT parameter that might otherwise render allocations ineligible for NonVSAM EOV Recovery. Details can be found in the CAT_VOL_COUNT variable description. The following illustration includes an example of applicable ASR code. 4 Concepts and Facilities 44

45 PREALLOC Environment The PREALLOC environment allows for the detection and elimination of potential 'NOT CATLGD 2' conditions that might occur for new, non-vsam, non-gdg permanent data set allocations. These conditions might occur if there is already an existing catalog entry for the data set containing the CA Disk archived pseudo volume or the DFSMShsm migrated pseudo volume. DELETE NOSCRATCH (DELNOS) Support DELNOS support available in PREALLOC 5 enables the catalog entry for the archived or migrated data set to be deleted without triggering either Auto Restore or RECALL of the archived or migrated data set. For data sets that CA Disk has archived, only the catalog entry is deleted. For data sets that DFSMShsm has migrated, an HDELETE request is issued. The request deletes the migrated data set itself and the catalog entry. Warning! The HDELETE request deletes any migrated data set whose name is the same one as the new data set being allocated. DELNOS support has the following system parameters: PLSARCVL Contains the archived pseudo volume that is used by CA Disk. PLSHSMVL Contains the migrated pseudo volume that is used by DFSMShsm. DELNOS support has four variables: ARCIVED MIGRATED DELETE_NOSCRATCH DELETE_NOSCRATCH_RC ARCIVED and MIGRATED are both 'Y' or 'N' flags indicating whether the data set is cataloged to either the archive pseudo volume specified in the PLSARCVL sysparm or the migrate pseudo volume that is specified in the PLSMIGVL sysparm. DELETE_NOSCRATCH is 'Y' or 'N' flag. When set to 'Y' and used with the ARCIVED and DELETE_NOSCRATCH_RC variables, it generates an attempt to remove the existing catalog entry for a data set cataloged to the CA Disk pseudo volume specified in the PLSARCVL sysparm. When set to 'Y' and used with the MIGRATED and DELETE_NOSCRATCH_RC variables, it dynamically issues an HDELETE request for a data set cataloged to the DFSMShsm migrated pseudo volser specified in the PLSHSMVL sysparm. 5 Concepts and Facilities 45

46 DELETE_NOSCRATCH_RC indicates the success or failure of the DELNOS function. Referencing this variable invokes DELNOS support real time. In the event you are running both CA Disk and DFSMShsm, the HDELETE attempt is made first. PURGE_UNEXPIRED_DATA_SET is another 'Y' or 'N' variable shared by PREALLOC and SPACE. It is used to allow PREALLOC to uncatalog the pseudo-volume entries for SMS-controlled archived or migrated data sets which have not reached their retention period or expiration date. Setting PURGE_UNEXPIRED_DATA_SET to 'Y' allows the DELNOS processing to complete normally for unexpired SMS data sets. If PURGE_UNEXPIRED_DATA_SET is set to 'N' (default), then DELNOS processing will fail and the catalog entry for the unexpired SMS data set will not be scratched. Note: In the PREALLOC environment, PURGE_UNEXPIRED_DATA_SET only affects SMS data sets. The catalog entry for archived or migrated non-sms data sets does not contain the expiration date. These non-sms entries are deleted by DELNOS processing regardless of the PURGE_UNEXPIRED_DATA_SET setting. The following illustration is a sample PREALLOC environment ASR invoking the DELETE NOSCRATCH support: Concepts and Facilities 46

47 IF &ENV = 'PREALLOC' THEN DO IF &DISPN = 'CATLG' THEN DO IF &MIGRATED = 'Y' OR &ARCHIVED = 'Y' THEN DO WRITE 'POTENTIAL NOT CATLGD 2 CONDITION DETECTED FOR &DSN' IF &MIGRATED = 'Y' THEN DO WRITE '&DSN ALREADY CATALOGED TO DFSMSHSM PSEUDO VOLUME &VOLSER' SET &DELNOS = 'Y' WRITE 'ATTEMPTING TO REMOVE CATALOG ENTRY FOR &DSN' IF &DNOSRC = 0 THEN DO WRITE 'REMOVAL SUCCESSFUL; POTENTIAL NOT CATLGD 2 AVOIDED' END IF &DNOSRC > 0 THEN DO WRITE 'REMOVAL UNSUCCESSFUL; POTENTIAL NOT CATLGD 2 NOT AVOIDED' END END IF &ARCIVED = 'Y' THEN DO WRITE '&DSN ALREADY CATALOGED TO CA DISK PSEUDO VOLUME &VOLSER' SET &DELNOS = 'Y' WRITE 'ATTEMPTING TO REMOVE CATALOG ENTRY FOR &DSN' IF &DNOSRC = 0 THEN DO WRITE 'REMOVAL SUCCESSFUL; POTENTIAL NOT CATLGD 2 AVOIDED' END IF &DNOSRC > 0 THEN DO WRITE 'REMOVAL UNSUCCESSFUL; POTENTIAL NOT CATLGD 2 NOT AVOIDED' END END END EXIT CODE (0) END END QREBUILD, QSCAN, QUOTA Environments These environments, applicable only to the Quota selectable unit, are described in the section Allocation Selection Routines and Environments (see page 189). RELEASE Environment The RELEASE environment is entered whenever a request is made to release unused space from a non- VSAM data set. The request can be made from a batch job with the RLSE parameter of the DD statement, or in the TSO ALLOC command using the RELEASE operand. Concepts and Facilities 47

48 In this environment, the Storage Administrator can decide to stop the release of space from certain data sets through the ASR shown in the following sample RELEASE environment ASR illustration. Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(VDSPROG) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'EXTEND' AND &EXTENTS > 8 THEN /* IF RUNNING OUT OF EXTENTS, */ SET &SECONDARY = 2 * &SECONDARY /* INCREASE SIZE OF ALLOCATION */ IF &VAMENVIR = 'OLD' AND &UNITMISMATCH = 'Y' /* IF UNIT MISMATCH DETECTED */ THEN /* CORRECT IT TO PREVENT */ SET &UNIT = &FIXUNITMISMATCH /* JCL ERROR & JOB FAILURE */ IF &VAMENVIR = 'RELEASE' THEN DO IF &HLQ = SYS% THEN /* IF SYSTEM DATA SET */ DO WRITE 'YOU MAY NOT RELEASE SPACE FROM A SYSTEM DATA SET' EXIT CODE(8) /* THEN DISALLOW THE RELEASE */ END END ******************************** Bottom of Data ******************************* Note: If the decision is made to stop the release, it usually issues an appropriate WRITE statement to tell the offender why the release was denied. The IBM system messages are not clear and do not point to CA Allocate DASD Space and Placement. RENAME Environment The RENAME environment is entered whenever a request is made to rename a non-vsam data set. Assume that an installation wants to maintain control over which data set names can be allocated to which volumes. This environment can be used to prevent a user from renaming a good data set name to a bad data set name. This process is shown in the following sample RENAME environment ASR illustration. Concepts and Facilities 48

49 Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(VDSPROG) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'RENAME' DO IF &HLQ = SYS% THEN /* IF SYSTEM DATA SET */ DO WRITE 'YOU MAY NOT RENAME A SYSTEM DATA SET' EXIT CODE(8) /* THEN DISALLOW THE RENAME */ END END IF &VAMENVIR = 'SCRATCH' THEN DO IF &HLQ = SYS% THEN /* IF SYSTEM DATA SET */ DO WRITE 'YOU MAY NOT SCRATCH A SYSTEM DATA SET' EXIT CODE(8) /* THEN DISALLOW THE SCRATCH */ END END ******************************** Bottom of Data ******************************* Note: If the decision is made to stop the rename, it usually issues an appropriate WRITE statement to tell the offender why the rename was denied. The IBM system messages are not clear and do not point to CA Allocate DASD Space and Placement. SCRATCH Environment The SCRATCH environment is entered whenever a request is made to delete a non-vsam data set. In this environment, the Storage Administrator can decide to stop the deletion of certain important data sets through the ASR. This method is shown in the following sample SCRATCH environment ASR illustration. For more information about the SCRATCH environment, see SMS-Managed GDGs (see page 26). The following illustration is a sample SCRATCH environment ASR: Concepts and Facilities 49

50 Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(VDSPROG) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'RENAME' DO IF &HLQ = SYS% THEN /* IF SYSTEM DATA SET */ DO WRITE 'YOU MAY NOT RENAME A SYSTEM DATA SET' EXIT CODE(8) /* THEN DISALLOW THE RENAME */ END END IF &VAMENVIR = 'SCRATCH' THEN DO IF &HLQ = SYS% THEN /* IF SYSTEM DATA SET */ DO WRITE 'YOU MAY NOT SCRATCH A SYSTEM DATA SET' EXIT CODE(8) /* THEN DISALLOW THE SCRATCH */ END END ******************************** Bottom of Data ******************************* Note: If the decision is made to stop the scratch, it usually issues an appropriate WRITE statement to tell the offender why the scratch was denied. The IBM system messages are not clear and do not point to CA Allocate DASD Space and Placement. SPACE Environment The SPACE environment is entered for every new non-vsam space allocation request, either batch, dynamic (SVC 99), or direct DADSM space request (SVC 32). This environment is required in addition to the ALLOC environment, because some utilities (for example, the IBM IEHMOVE) directly issue an SVC 32 (DADSM space request) to allocate disk space, and bypass the normal flow of allocations. Allocations that are made by these utilities are not seen by the ALLOC environment, but can be checked in the SPACE environment. Only a limited number of output variables can be set in the SPACE environment, as shown in SPACE 6. Most notably, it is not possible to select volumes in the SPACE environment. That is, the ASR cannot set a storage group (STORGRP). The only function that the IBM IGGPRE00 exit allows is to accept the volume (EXIT CODE(0)), reject the current volume (EXIT CODE(4)), or fail the allocation request immediately (EXIT CODE(8)). The following sample SPACE environment ASR illustration shows this situation. Any specific volume allocation fails if any volume was rejected (so EXIT CODE(4) and EXIT CODE(8) acts the same). For a nonspecific volume allocation (no VOL=SER= or equivalent), MVS presents a list of all volumes within the specified unit name (UNIT=) that are mounted with a mount attribute of STORAGE. 6 Concepts and Facilities 50

51 Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(SPACE) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = 'SPACE' THEN DO /* SPACE ENVIRONMENT */ IF &HLQ = SYS% THEN /* IF SYSTEM DATA SET */ DO WRITE 'YOU MAY NOT RESTORE OR COPY A SYSTEM DATA SET' EXIT CODE(8) /* CANCEL THE ALLOCATTION */ END IF &ANYVOL = SY* THEN /* IF SYSTEM VOLUME */ DO WRITE 'YOU MAY NOT RESTORE OR COPY A SYSTEM DATA SET' EXIT CODE(4) /* REJECT THE CURRENT VOLUME */ END END ******************************** Bottom of Data ******************************* The following rules apply: If you set storage group (STORGRP) in the ALLOC environment, the product makes the allocation request specific. MVS issues messages IEF344I, IGD17037I, or both when the ASR exits with a return code of 8. To avoid confusing end users, document your action with an appropriate WRITE statement. Optional PI is required to have EXIT CODE(8) cause the allocation to be canceled. For more information about the feature, see Legacy Optional Features (see page 220). When allocations are deferred using PLSOPT9 (Y), and the ASR exits with a nonzero return code, no special MVS messages are issued. Therefore, to avoid confusing end users, it is recommended to have the ASR issue some sort of message indicating that it is choosing to deny this allocation. CA Health Checker Interface The IBM Health Checker for z/os allows you to identify potential problems in your z/os environment. System or product parameters and system status are checked against recommended settings. The IBM Health Checker for z/os is structured as a framework that includes a health check started task and various separate check routines that are provided by IBM or other vendors. CA Allocate DASD Space and Placement provides health checks for system parameter settings or real-time processing conditions that could result in a problem. The CA Allocate DASD Space and Placement health checks also make best practice recommendations for using the product. The health check owner is CA_ALLOC. Monitoring the health checks generated for CA Allocate DASD Space and Placement is a best practice. Health Checks alert you of conditions that could prevent the product from running properly, if left uncorrected, and they guide you in addressing the problem. The following health checks are provided: ALLOC_VRFY_EOV_X37_SVCS_STATUS - VAMH0061E (see page 53) EOV support automatically prevents SNA failures. If EOV support is disabled, reenable EOV support to recover data sets from SNA conditions. Concepts and Facilities 51

52 ALLOC_VRFY_ACT_ASR_IS_EXPECTED (see page 52) If you make changes to your ASR, ensure that those changes are executed at the next opportunity. Syntax errors, which are reported to you in the SYSPRT file, are the most common reason for the rejection of an ASR. Discover and resolve the cause of the error so that your new ASR can carry out your new directives. ALLOC_VRFY_PLSZSEC_EOV_X37_SVCE - VAMH0081E (see page 54) EOV support for Zero Secondary gives your ASR the ability to give secondary space to data sets to prevent D37-04 abends. Set PLSZSEC to (Y) to avoid the D37-04 abends. ALLOC_VRFY_PLSOPT10_SNA_X37_SVCE - VAMH0091E (see page 53) The ALLOC and DEFINE environments are where your ASR detects and prevents potential SNA failures. Set PLSOPT10 to (Y) to give your ASR the ability to detect and correct any potential SNA failures for new DFSMS-managed data sets. ALLOC_VRFY_PLSOPT94_USE_STUB - VAMH0101E (see page 54) This Health Check advises you if the product is not running with PLSOPT94 to (N), use the STUB methodology. Operating System Interfaces at IFG0EX0B, IGGPRE00, IGGDAC02, IGGPOST0, and SVC26 are not removed during a shutdown outside of an IPL. You eliminate compatibility problems with other OEMs who can also intercept at these locations. ALLOC_VRFY_ACT_ASR_IS_EXPECTED Description This check monitors CA Allocate DASD Space and Placement to ensure that a new Allocation Selection Routine (ASR) is successfully activated. An ASR is checked for syntax errors prior to activation, and will be considered not eligible for activation when a syntax error is found. When a new ASR is not able to be activated, the product continues to run with the previously activated ASR. Best Practice If you make changes to your ASR, you want to ensure that those changes will be executed at the next opportunity. The most common reason an ASR is rejected is syntax errors which are reported to you in the SYSPRT file. It is important to discover and resolve the cause of the error so that your new ASR can carry out your new directives. Parameters Accepted None Debug Support Yes Verbose Support Yes Reference Refer to the Messages 7 for a detailed explanation and action statements for the error messages that you received. Messages VAMH0071E The last REFRESH to your CA Allocate DASD Space and Placementsystem failed to activate a new Allocation Selection Routine (ASR). 7 Concepts and Facilities 52

53 ALLOC_VRFY_EOV_X37_SVCS_STATUS - VAMH0061E Description This check monitors CA Allocate DASD Space and Placement to ensure that the End-Of-Volume support (EOV) is successfully activated when it is requested. When the EOV support fails to initialize, you are without a critical tool your Allocation Selection Routine (ASR) uses to recover your data sets from Space-Not-Available (SNA) conditions. Best Practice EOV support gives you the means to automatically prevent SNA failures from occurring. If EOV support is disabled for any reason, it is important to re-enable EOV support to recover data sets from SNA conditions. Parameters Accepted None Debug Support Yes Verbose Support Yes Reference Refer to the Messages 8 for a detailed explanation and action to be taken for the error messages that you received. Messages VAMH0061E Your CA Allocate DASD Space and Placement system failed to initialize End-of- Volume support. ALLOC_VRFY_PLSOPT10_SNA_X37_SVCE - VAMH0091E Description This check monitors CA Allocate DASD Space and Placement to ensure that the ALLOC and DEFINE environments are able to intercept the allocation requests for new SMS-managed data sets. When you are running with PLSOPT10 (N), New SMS-managed data sets will be excluded from the ALLOC and DEFINE environments. This means that your Allocation Selection Routine (ASR) is unable to detect and prevent Space-Not-Available (SNA) failures for new SMS-managed data set allocations. Best Practice The ALLOC and DEFINE environments are where potential SNA failures are detected and prevented by your ASR. Set PLSOPT10 to (Y) to give your ASR the ability to detect and correct any potential SNA failures for new SMS-managed data sets. Parameters Accepted None Debug Support Yes Verbose Support Yes 8 Concepts and Facilities 53

54 Reference Refer to the Implementation (see page 108) section for a description of PLSOPT10. Messages VAMH0091E Your CA Allocate DASD Space and Placement system is not configured to recover new SMS-managed data sets from Space-Not-Available abends because PLSOPT10 is set to (N). ALLOC_VRFY_PLSOPT94_USE_STUB - VAMH0101E Description This check monitors CA Allocate DASD Space and Placement to ensure you are running with PLSOPT94 set to its default value of (N) which allows utilization of available STUB methodology. Running with PLSOPT94 (Y) causes the product to attempt to remove the hooks it has at IGGPRE00, IGGDAC02, IGGPOST0 and SVC26 during a REMOVE operation in the order in which they were set. This process is referred to as LIFO (last-in-first-out). LIFO removal of one or more of these hooks is likely to fail because of other OEM products you are running with may also hook at these locations. Best Practice By setting PLSOPT94 to (N), you will be using the STUB methodology. Hooks at IGGPRE00, IGGDAC02, IGGPOST0 and SVC26 are not removed during a shutdown outside of an IPL and this will eliminate compatibility problems with other OEMs who may also hook at these locations. Parameters Accepted None Debug Support Yes Verbose Support Yes Reference Refer to the Implementation (see page 108) section for descriptions of PLSOPT94. Messages VAMH0101E CA Allocate DASD Space and Placement is not configured to utilize available STUB Methodology. ALLOC_VRFY_PLSZSEC_EOV_X37_SVCE - VAMH0081E Description This check monitors CA Allocate DASD Space and Placement to ensure that End-of-Volume (EOV) support for non-vsam data sets allocated with zero secondary space is enabled. When you are running with PLSZSEC (N), this support is disabled and your Allocation Selection Routine (ASR) is not able to prevent any of the non-vsam data sets that had not been allocated with any secondary space from encountering D37-04 abends. Best Practice EOV support for Zero Secondary gives your ASR the ability to give secondary space to data sets to prevent D37-04 abends. Set PLSZSEC to (Y) to avoid the D37-04 abends effectively. Parameters Accepted None Concepts and Facilities 54

55 Debug Support Yes Verbose Support Yes Reference Refer to the Implementation (see page 108) section for the PLSZSEC description. Messages VAMH0081E Your CA Allocate DASD Space and Placement system is not configured to recover non-vsam data sets from D37-04 abends that will occur for data sets allocated with zero secondary space because PLSZSEC is set to (N). Life Cycle of a Data Set The following table shows the sequence of ASR environments that are entered during the lifecycle of a data set, from the time it is originally allocated, through open, close, extension, rename, and finally deletion, assuming the optional Quota feature is not installed. Operation non-vsam VSAM Allocate a new single-volume data set. Write to the data set so that an extent is required. Release unused space in the data set when it is closed. ACS, ALLOC, and SPACE EXTEND RELEASE ACS & DEFINE (cluster) EXTEND Not applicable Rename the data set. OLD and RENAME Not applicable Write to the data set so that an extra volume is required. EOV EOV_VSAM (component) Scratch the data set. SCRATCH (volume 1) SCRATCH (volume 2) Not applicable Note: F or the table showing the lifecycle of a data set with Quota, see Quota System Overview (see page 178). That table shows the points in which the QUOTA environment is entered during a similar data sets lifecycle. Propagate Variables Between Environments The D0 to D9 character and M0 to M9 numeric variables can be propagated. The values of these variables (p-vars) are kept in a table that is accessible from all supported environments using the IBM name/token services. For more information about the variables, see ASR Variables Concepts and Facilities 55

56 Once these variables are established for a data set, failure to continue to reference them for the life of the STEP might introduce data integrity problems with the variable values should the data set be deleted and reallocated in the same STEP on the same volume. For example, consider two data sets, A and B, with the same name getting created on the same volume in the same STEP. Data set B is not created until after data set A is deleted because both have resided on the same volume and have had the same name. Data set A is created on volume xyz and gets p-vars associated with it in the ALLOC environment. Data set A gets deleted from volume xyz, without referencing the p-vars in the SCRATCH environment. Because the p-vars were not referenced in SCRATCH, the data record containing them is not updated and flagged as dead record as it would have been had the p-vars been referenced. Data set B gets created on volume xyz without any p-vars getting associated with it in the ALLOC environment. Because the p-vars were not referenced in ALLOC, the data record containing the p-vars for data set A is not located and flagged as a dead record as it would have been had the p-vars been reference data set B gets deleted from volume xyz and has p-vars associated with it in the SCRATCH environment. The data record for data set A gets retrieved for data set B. Initial values of the p-vars given to data set B are not the documented default values but rather the values data set A had last changed them to. This is the data integrity problem alluded to previously. Had the p-vars been referenced in either (2) or (3) no data integrity problem would have arisen because the data record for data set A would have gotten flagged as a deadrecord. Volume Selection Options for New Data Sets CA Allocate DASD Space and Placement is involved in determining which volumes are selected for SMS-managed data sets. The involvement consists of: Specifying what DFSMS STORGRP IBM SMS subsystem is to use. Creating logical subpools of SMS-managed storage groups that the SMS subsystem is limited to when selecting volumes for new VSAM data sets. Allowing for Key Data Set Separation for new VSAM data sets. The product is also involved in determining which volumes are selected for non-sms-managed data sets. The involvement consists of: Logically grouping non-sms volumes into non-sms storage groups. Selecting the actual non-sms volumes the non-sms data set is allocated to. Allowing for Key Data Set Separation for new VSAM data sets. Concepts and Facilities 56

57 More Information: Subpooling of SMS-managed Storage Groups (see page 57) Key Data Set Separation (see page 58) Volume Selection Logic for Non-SMS-managed (see page 58) Propagate Volume Selection Failure Return Code (see page 59) Subpooling of SMS-managed Storage Groups An existing DFSMS Storage Group can be logically separated into one or more SMS subpools. The SMS subpools are defined in the CA Allocate DASD Space and Placement storage group table, using the rules in Create a Storage Group Definition (see page 144). SMS subpools are only applicable in the DEFINE environment. The following sample ASR code shows how the SMS_SUBPOOL_SG, EXCLUDE_VOLS, and EXCLUDE_RC variables can be used. They can influence which subset of volumes in an SMS-managed storage group is considered eligible for a new VSAM data set allocation: IF &ENV = 'DEFINE' THEN DO IF &SMS_MANAGED = 'Y' THEN DO IF &SG = 'SMSPROD' THEN DO IF &DSN = &GRP1DSN THEN SET &SMS_SUBPOOL_SG = 'SMSSG1' IF &DSN = &GRP2DSN THEN SET &SMS_SUBPOOL_SG = 'SMSSG2' IF &DSN = &GRP3DSN THEN SET &SMS_SUBPOOL_SG = 'SMSSG3' IF &SMS_SUBPOOL_SG NE '' THEN SET &EXCLUDE_VOLS = 'Y' IF &EXCLUDE_RC = 0 THEN DO WRITE 'VAM000I SMS subpooling in effect' END END END END You are responsible for ensuring that the subpool your ASR associates with the new data set allocation actually contains a subset of the volumes in the DFSMS storage group that have previously been associated with the data set. Once the subpooling of SMS storage groups process starts, there is no going back. If all volumes in the storage group are rejected, the new data set allocation fails. The product unconditionally issues a VAM0074 EXCLUDE_VOLS PROCESSING IN EFFECT message whenever the ASR requests this processing. The message clarifies the misleading DADSM RC messages that IBM code issues in the event all volumes are rejected. Warning! This feature is resource-intensive. Only use the feature after you consider the system impact. Concepts and Facilities 57

58 Key Data Set Separation The optional KEYDSN install member lets you identify a list of Key Data Sets in your environment. These key data sets are never placed on the same volume as any other data set in the list. The list of data sets in KEYDSN is loaded into CSA upon INSTALL and can be updated dynamically using the REFRESH modify command. The actual volumes that are associated with a KEYDSN entry are only retrieved from an existing data set's catalog entry. The KEYDSN member is only applicable in the DEFINE environment. The member must reside in the same data set as your ASRs: the one noted as the value of sysparm PLSPRGDS in the sysparm override member of your parmlib. For non-sms-managed, this constraint means only those data sets which are eligible for redirection in the DEFINE environment are eligible for Key Data Set Separation. Non-SMS-managed VSAM data sets allocated by JCL DEFINE or SVC99 that are redirected in the ALLOC environment are ineligible for the KEYDSN support. The following sample ASR code shows using the KEY_DSN and EXCLUDE_VOLS variables to achieve key data set separation. IF &ENV = 'DEFINE' THEN DO IF &KEY_DSN = 'Y' THEN DO SET &EXCLUDE_VOLS = 'Y' IF &EXCLUDE_RC = 0 THEN DO WRITE 'VAM000I key data set separation in effect' END END END Once the key data separation process starts, there is no going back. Sometimes all volumes in the storage group are rejected because they all already contain another data set in the KEYDSN list. In this case, the new VSAM data set allocation fails. For this reason, The product unconditionally issues a VAM0074 EXCLUDE_VOLS PROCESSING IN EFFECT message whenever the ASR requests this processing. This message is an effort to clarify the misleading DADSM RC messages that IBM code issues in the event all volumes are rejected. For non-sms VSAM only, support is limited to those allocations that are redirected in the DEFINE environment. Warning! This feature is resource-intensive. Only use the feature after considering the system impact. Volume Selection Logic for Non-SMS-managed Set the STORGRP variable to one or more storage group names to activate the volume selection process. A list is then made of all volumes that are online for the unit name that is specified in the UNIT variable. If you specify a nonexistent unit or a specific unit address like 1A0, a VAM0030 message is Concepts and Facilities 58

59 issued and volume selection is bypassed. Any volumes with no free DSCBs or duplicate data set names are also excluded from the volume selection process. The product selects from the volumes that are in the primary storage group. Next, the product passes this list of volumes to the System Resource Manager (SRM). SRM selects the volume on the least-used channel with the fewest users. Use PLSOPT20 to change the volume selection process for first-choice volumes. You can also use the variable VOLUME_SELECTION_BY_LEAST_FREESPACE to change the volume selection process in the primary storage group. For more information, see PLSOPT20 in PLSOPTnn Sysparms (see page 126). After a volume is selected, a call is made to the security interface to verify that the user is authorized to allocate a data set on the selected volume. If the user is authorized, the selected volume is checked for enough space. If the volume contains insufficient space for the primary quantity, it is deleted from the list and SRM is invoked again. If the volume contains sufficient space, but the free-space threshold would be violated, the volume is marked as a second choice volume. This process continues until the allocation has been satisfied or the first storage group is exhausted. The remaining storage groups in the STORGRP variable are checked, if necessary, one after another for first-choice volumes. If all storage groups are exhausted, CA Allocate DASD Space and Placement uses second choice volumes in the order in which SRM selected them. Use PLSOPT22 to change the volume selection process of the Second choice volumes. For more information, see PLSOPT22 in PLSOPTnn Sysparms (see page 126). Propagate Volume Selection Failure Return Code The product can conditionally make the Volume Selection Failure (VSF) return code (RC) available to the OEM application that requested the allocation through the IBM name-token services. Token creation upon VSF in ALLOC, DEFINE, EOV, and EOV_VSAM primarily depends on the values of sysparms: PLSVSFAL, PLSVSFDF, and PLSVSFEV. The 16-byte IEANT_NAME field contains: VSFALLOC (left justified). The 16-byte IEANT_TOKEN field contains: xxxx CA-ALLOCATE. The xxxx is the VSF RC in hexadecimal format. Know that the fifth byte in the IEANT_TOKEN field is a blank (X'40'). If the VSF was due to a limitation/restriction of the IBM DADSM services, then the RC is the actual DADSM RC. For example, a space requested not available condition has an RC of 14 and the IEANT_TOKEN field contains 0014 CA-ALLOCATE. The product assumes that the OEM application retrieving the token deletes it. What action an OEM application can decide to take after retrieving the token is the responsibility of that OEM application. The token that is created upon VSF in the ALLOC environment is known to be retrieved by the EMC TimeFinder product (release/patch): 4.1/ST410D5, 5.0/ST50094, 5.1/ST51081, 5.2/SF More information: PLS Sysparms (see page 109) Concepts and Facilities 59

60 End-of-volume Support MVS JCL permits users to allocate multivolume data sets. The product extends this support by allowing the ASR to change the allocation to or from a multivolume request in the ALLOC and DEFINE environments. All data sets, whether multivolume or not, can have special processing items to consider: The data set might not actually use or need extra volumes that are coded in the initial allocation (wasted space to avoid a B37 abend). The user might not correctly estimate the amount of space or number of volumes that are required to run a job. By the time that the data set must go to a secondary extent or volume, that space might not be available. If the space is unavailable, the job abends with a B37. Jobs that reference the data set can also allocate new volumes (resources) even if the data set does not actually use them. Free-space thresholds are not maintained because the extra volumes are allocated before they are written to. By the time the data set spans to the additional volumes, the original amounts of free space no longer apply. This EOV support enhances the process of controlling multivolume data sets and data sets that are not multivolume. From the product's point of view, it makes no difference whether the initial allocation was for multiple volumes. The EOV and EOV_VSAM environments get control when a data set has run out of space. Within these environments, more volumes can be dynamically added on an as-needed basis. Using the EOV support means: You do not need to preallocate all required volumes. More volumes are selected, as they are needed. If you add a volume and you allow the job to continue, you prevent B37 and E37 type abends. Free-space threshold requirements are easier to maintain, because they are considered when you select new volumes. The default configuration results in most messages being issued to the SYSLOG and the JESMSGLG and JESYSMSG DDs allocated to the applicable batch job or started task. When PLSOPT98 (Y) is specified in parmlib, these messages are only issued to the JESYSMSG DD. The default value of this parameter is (N). Using (N) results in these diagnostics being issued in triplicate as they historically have been issued. If you are running with PLSOPT98 (N), consider changing to PLSOPT98(Y). You confirm the messages that the product issues to a single place in the job log. If you are running with PLSOPT37 (N), consider changing to PLSOPT37(Y). The V messages are issued conditionally only when diagnostics have been activated. Concepts and Facilities 60

61 More information: EOV Technical Overview and Restrictions (see page 61) Understand When EOV is Entered (see page 62) Use EOV and EOV_VSAM Environments with a SMS-Managed Data Set (see page 64) VSAM EOV with Media Manager Data Sets (see page 65) EOV Support for VSAM Data Sets with Unused Candidate Volumes (see page 66) EOV_VSAM Data Sets with Additional Volume Amount=Secondary (see page 67) EOV Support for Zero Secondary (see page 68) EOV Technical Overview and Restrictions EOV and EOV_VSAM environments get control when a data set has run out of space on the current volume and no more volumes are available from which to get space. For those VSAM data sets that are created with only primary allocation and an EOV_VSAM environment is coded in the VDSPROG, The product allocates another volume using the primary allocation space. For certain VSAM data sets that do not have secondary space and you do not want them entering the EOV_VSAM environment, exclude them from the product's allocation routine by checking for secondary space and then exit code (0). If excluded from the product and the data set exceeds the primary allocation, the IBM message IEF070I is issued. The message reveals an error in EOV processing when attempts to extend were made, but no secondary space was specified. Setting the STORGRP within these environments allows the extension of an output data set onto multiple volumes, even when those volumes were not coded in the original allocation. Any defined STORGRP name that is appropriate for the current situation can be used. Non-SMS-managed data sets are not restricted at end-of-volume time to the STORGRP specified in the original allocation. When the ASR sets STORGRP, STORGRPD or STORGRPI for non-sms-managed data sets, an attempt is made to pick a volume from the storage group that: Is not currently allocated to the data set Is of the same device type Has sufficient free space to hold the requested allocation amount Maintains free-space threshold requirements The product tries to maintain the percentage of free space that has been defined for a volume. This percentage is referred to as the free-space threshold. Available volumes are seen as being either first or second choice volumes: First choice volume The required space amount can be allocated without exceeding the freespace requirement. Second choice volume The free-space requirement must be exceeded to allocate the required space amount. If no first choice volume can be found within the storage group, a second choice volume is selected. Concepts and Facilities 61

62 Restrictions Not all data sets can be extended to multivolume data sets. For the following data set types and conditions, the EOV and EOV_VSAM environments are not entered: VIO data sets are allocated in page spaces, not volumes. IBM does not support multivolume PO and PDSE data sets. Data sets that have either an ABEND or EOV exit that is coded in the exit parameter list of their DCB are not processed. For more information about disabling these exclusions, see PIs and in the Legacy Optional Features (see page 220). Data sets with more than one open DCB. The EOV Recovery operation is done in the address space that is adding records to the data set that requires an extra volume to continue adding more records. Sometimes a data set security profile allows making updates to it but not allocation of more volumes. If you set PLSOPT45 to (Y), such data sets are recovered. Otherwise, the source is an unrecovered Space Not Available condition that limits the number of records that you could add. Understand When EOV is Entered The EOV environment allows output data sets to extend onto multiple volumes. Nothing seems more frustrating than watching a long running job abend because one of its output data sets has run out of space. The abend can be avoided within this environment, allowing the job to continue by allocating more volumes. The nature of multivolume data sets is complex and as such requires the ASR writer to be careful about when to correct such a situation. With that in mind, some prescreening of the data sets is done. This prescreening ensures making them multivolume does not cause problems. Consider the following JCL (although strange, it is also perfectly valid): Concepts and Facilities 62

63 //JOB JOB //STEP1 EXEC PGM=IEFBR14 //AFILE DD DSN=THE.SAME.OLD.FILE, // DISP=(NEW,CATLG),VOL=SER=(PVOL01,PVOL02),UNIT=..,SPACE=.. //BFILE DD DSN=THE.SAME.OLD.FILE, // DISP=(NEW,KEEP),VOL=SER=PVOL03,UNIT=..,SPACE=.. //CFILE DD DSN=ANOTHER.FILE, // DISP=(NEW,KEEP),VOL=SER=PVOL03,UNIT=..,SPACE=.. //STEP2 EXEC PGM=IEBGENER //SYSUT1 DD DSN=FILEIN,DISP=SHR //SYSUT2 DD DSN=THE.SAME.OLD.FILE,DISP=OLD,VOL=SER=PVOL02,UNIT=.. //... //STEP3 EXEC PGM=IEBGENER //SYSUT1 DD DSN=FILEIN,DISP=SHR //SYSUT2 DD DSN=THE.SAME.OLD.FILE,DISP=(OLD,CATLG),VOL=SER=PVOL03,UNIT=.. //... //STEP4 EXEC PGM=IEBGENER //SYSUT1 DD DSN=FILEIN,DISP=SHR //SYSUT2 DD DSN=THE.SAME.OLD.FILE, // DISP=(NEW,CATLG),VOL=SER=PVOL04,UNIT=..,SPACE=.. //... //STEP5 EXEC PGM=IEBGENER //SYSUT1 DD DSN=FILEIN,DISP=SHR //SYSUT2 DD DSN=THE.SAME.OLD.FILE,DISP=OLD //... //STEP6 EXEC PGM=IEBGENER //SYSUT1 DD DSN=FILEIN,DISP=SHR //SYSUT2 DD DSN=ANOTHER.FILE,DISP=(OLD,CATLG),VOL=SER=PVOL03,UNIT=.. //... //STEP7 EXEC PGM=IEBGENER //SYSUT1 DD DSN=FILEIN,DISP=SHR //SYSUT2 DD DSN=ABRAND.NEW.FILE, // DISP=(NEW,CATLG),VOL=SER=PVOL03,UNIT=..,SPACE=.. //... //STEP8 EXEC PGM=IEBGENER //SYSUT1 DD DSN=FILEIN,DISP=SHR //SYSUT2 DD DSN=ANOTHER.BRAND.NEW.FILE,DISP=(NEW,KEEP),UNIT=.. //... STEP1 - creates both cataloged and uncataloged versions of the same data set. Assuming each of the output data sets runs out of space and needs more volumes, on what basis is the EOV ASR be invoked? In the following paragraphs, the filtering that is done by EOV is described for each step. STEP2 - references the second volume of the cataloged data set created in STEP1. In this case, the EOV environment is not entered, because UNIT and VOL reference the data set, rather than through the catalog. If this data set are multivolume, the catalog would no longer point at the appropriate volumes. Future jobs or steps that referenced the data set would not be able to find the data set correctly. STEP3 - is referencing the uncataloged data set created in STEP1. Also, when the step has completed, the data set is to be cataloged. Because the data set is already cataloged, the system returns a NOT CATLGD 2 at step termination. The EOV routines detect that a cataloged version of the data set exists and does not enter the EOV ASR, because no new volume can be cataloged. Thus, no future job can find it. STEP4 - is attempting to create yet another cataloged version of the same file that STEP1 creates and catalogs. The system returns a NOT CATLGD 2 at step termination because the data set is already cataloged. The EOV routines detect that data set is already cataloged and does not enter the EOV ASR, because future jobs or steps are unable to find any added volume. STEP5 - references the cataloged data set created in STEP1 and is not volume-specific. In this case, the system locates the data set using the catalog and inserts the appropriate volumes automatically. EOV processes this data set because EOV can correctly recatalog the data set. Concepts and Facilities 63

64 STEP6 - references the uncataloged data set allocated by STEP1, intending to catalog the data set at the end of the step. Because this data set is not currently cataloged, and it can be correctly cataloged at step termination, EOV processes this data set. STEP7 - is creating a data set to be cataloged at step termination. Because this data set is not currently cataloged, and it can be correctly cataloged at step termination, EOV processes this data set. STEP8 - is creating a permanent uncataloged data set, which is typically not eligible for EOV processing. The active value of Sysparm PLSOPT47 determines if permanent uncataloged data sets are eligible for EOV processing. Use EOV and EOV_VSAM Environments with a SMS-Managed Data Set When the EOV and EOV_VSAM environments are entered for a data set that is not SMS-managed, another volume can be added to the data set. Have the product select one (that is, by setting a STORGRP). When the EOV and EOV_VSAM environments are entered for a SMS-managed data set, the product only prepares a data set to receive another volume. SMS allocates another volume to the data set only if it can do so without violating SMS restrictions: SMS can only select from the SMS STORGRP that is already associated with the data set. SMS cannot select a volume that is outside of that STORGRP. If the data set is already allocated to every volume in that STORGRP, it is not possible for another volume to be added, even though the EOV or EOV_VSAM environment has specified to add one. Note: For complete limits and restrictions on SMS-managed multivolume data sets, refer to the appropriate IBM documentation. SMS can allocate a candidate volume at initial allocation time for both VSAM and non-vsam data sets. The actual candidate volume, indicated by an * in the volume list of the catalog entry, is not chosen before needed. When it is needed, SMS replaces the candidate volume with a real volume from within the SMS STORGRP that is associated with the data set. The product can take advantage of this process with its ability to add a candidate volume. The product dynamically updates the necessary control blocks and the catalog. The update makes it appear to SMS that the candidate volume was present when the original allocation occurred. Any data set that has a STORCLAS not equal to null (&STORCLAS NE '') is SMS-managed. When processing SMS-managed data sets in the EOV and EOV_VSAM environments, the associated DATACLAS, MGMTCLAS, and STORCLAS construct information is available as read-only: the information cannot be modified. To add a candidate volume to an SMS-managed data set, either the &STORGRP variable must be set to the keyword SMSEOV (that is, SET &STORGRP = 'SMSEOV'), or the &POOLSUB variable set to Y, and an EXIT CODE(0) statement must be used. This setting causes the product to make a series of changes. The changes make the data set appear to SMS as one that has a candidate volume. If the &STORGRP variable is set to any value other than 'SMSEOV', these changes are not made and the out of space condition occurs. This includes setting it to a valid storage group that has previously been Concepts and Facilities 64

65 defined to either SMS or the product. Also, the EOV and EOV_VSAM environments cannot be exited with EXIT CODE(x), where x is nonzero. The following sample EOV ASR illustration has sample ASR code for the EOV and EOV_VSAM environments. Menu Utilities Compilers Help BROWSE ASR.PARMLIB(EOV) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* FILTLIST &SMSPROD INCLUDE('SCPROD01','SCMAST01') FILTLIST &PROD INCLUDE(PROD.**,,ASTER.**) IF &VAMENVIR = 'EOV' OR &VAMENVIR = 'EOV_VSAM' THEN DO IF &SC = &SMSPROD /* SMS-MANAGED PRODUCTION */ OR &DSN = &PROD /* NONSMS-MANAGED PRODUCTION */ THEN /* GIVE IT ANOTHER VOLUME */ SET &POOLSUB = 'Y' /* FROM THE SAME POOL */ ELSE DO /* FOR NON PRODUCTION JOBS */ WRITE '&DSN IS NOT PRODUCTION AND OUT OF SPACE' EXIT CODE(4) /* DO NOT ADD A VOLUME */ END END ******************************** Bottom of Data ******************************* This code does the following processing: Checks to see if the data set is SMS-managed by checking if a &SC (or &STORCLAS) is present. Checks to see if the data set is non-sms-managed production. Recovers only a production data set from the out of space condition. VSAM EOV with Media Manager Data Sets Media Manager Services (MMS) is the latest generation of IBM access methods. Until recently, MMS was primarily used with DB2 Table Spaces, which are a special type of linear data set (LSDS). SMS-managed multistriped Extended Format (EF) data sets were introduced in OS/390 Release MMS was used instead of the traditional Virtual Storage Access Method (VSAM) used with all other ESDS, KSDS, RRDS, non-sms or SMS-managed, and single striped SMS-managed EF data sets. Starting with z/os 1.3, all SMS-managed ESDS, KSDS, RRDS, LSDS, and striped EF data sets use MMS. Non-SMS ESDS, KSDS, RRDS, and non-db2 LSDS data sets continue to use the VSAM access method. Some fundamental differences exist between the MMS and VSAM access methods. VSAM waits until the extent is 100 percent full before checking if there is an available candidate volume that is associated with the data set. MMS checks when the extent is less than 100 percent full. These checks for candidate volumes trigger the VSAM EOV support. As a result, there are occasions when MMS does not determine the need to extend onto the candidate volume that MMS requested. Another difference is that MMS gets the primary and secondary allocation amounts from a different control block than VSAM. This action does not prevent changes from being made to the applicable space amounts in the EOV_VSAM environment. However, MMS starts using the new value immediately. If MMS decides to defer spanning onto the additional candidate volume that is recently provided by the VSAM EOV support, and the secondary amount was changed in EOV_VSAM, subsequent extents on the current volume are with the new size. Concepts and Facilities 65

66 Special Notes for DB2 Tablespaces For SMS-managed only, VSAM EOV support for DB2 tablespaces is limited to dynamically allocating an extra candidate volume to these data sets. Depending on the DB2 version, from 3 to 5 DB2 started tasks can be running. When coding in the VDSPROG for DB2 allocations, use the &JOB variable for keying on the DB2 started task name. The DB2 started job task is doing the allocation, not the batch job with the DB2 commands. When having problems with DB2, before calling CA Support, modify the CA Allocate DASD Space and Placement started task to get the diagnostics. /F VAMSTC,DIAGS=xxxxDBM1 xxxxdbm1 = is the DBM started task name. The ending suffix is usually DBM1. The prefix varies. Once this command is issued, a large volume of diagnostics is issued. If you are running with PLSOPT98 (Y), diagnostics are confined to the JESMSGLG DD portion of the xxxxdbm1 started task. If you are running with PLSOPT98 (N), these diagnostics are written to the SYSLOG and system operator console. Diagnostics are also written to the JESMSGLG and the JESYSMSG DD portions of the xxxxdbm1 started task, Rerun the failing job and have ready the diagnostics from the DB2 started task and the complete failing job log. To stop the diagnostics, issue the following command: /F VAMSTC,DIAGS= Special Notes for the zfs UNIX File System VSAM EOV support for zfs UNIX File Systems is limited to dynamically allocating an extra candidate volume to these data sets. Allocation requests are made by the zfs started task that usually has zfs as part of its name. Obtain the diagnostics detailing possible problems with these allocations before calling CA Support in a manner similar to the way they are obtained for DB2. EOV Support for VSAM Data Sets with Unused Candidate Volumes The purpose of intercepting these allocations is to enable the ability to alter the initial primary, secondary, or both space allocation amounts to use when a VSAM data set extends onto an already existing candidate volume. Because the data set is already open, the space amounts that are used are what are indicated in the applicable system control blocks associated with the opened data set. When a data set is opened, the values in these control blocks contain the initial creation information. If an EOV condition is encountered after the data set is opened, the product was used to change these space amounts. For example, during an EXTEND environment invocation, these values reflect the new Concepts and Facilities 66

67 space amounts. When EOV_VSAM is launched, the &PRIMARYD/I and &SECONDARYD/I variables contain the originally defined VSAM data set information. These values might not be the same as the current space amounts contained in the applicable system control blocks. The current values of the space amounts associated with the failing VSAM data or index component are available in the CURRENT_PRIMARYD/I and CURRENT_SECONDARYD/I variables. These four CURRENT_* variables are only applicable in the EOV_VSAM environment, regardless of whether they have available candidate volumes, or whether they are SMS-managed. So, for a failing VSAM component, there are four values to select from for adjusting the space allocation amounts: The value the data set was originally defined with contained in the applicable PRIMARYD/I and SECONDARY/I variables. The new value the data set has been given because it was opened, contained in the applicable CURRENT_PRIMARYD/I and CURRENT_SECONDARY/I variables. The maximum available extent size in the storage group, which the LSPACE support retrieved into the applicable LARGEST_EXT* variable. Whatever amount a customer wants to set it to (up to the current IBM-documented maximum). An example of first value (the value the data set was originally defined with) is shown in the following illustration. The current values are reinitialized to the original ones by setting the applicable &variable to itself (as in a 'SET &PRIMARYD = &PRIMARYD' statement). The following sample is an ASR for VSAM EOV With Candidate Volumes: IF &VAMENVIR = 'EOV_VSAM' /* VSAM END-OF-VOLUME */ THEN DO IF &CANDIDATE_VOLUMES = 'Y' * AVAILABLE CANDIDATE VOLUMES */ THEN DO IF &ABENDCOMP = 'DATA' /* EOV ON DATA COMPONENT */ THEN DO SET &PRIMARYD = &PRIMARYD /* RESET TO ORIGINAL VALUE */ SET &SECONDARYD = &SECONDARYD /* RESET TO ORIGINAL VALUE */ END IF &ABENDCOMP = 'INDEX' /* EOV ON INDEX COMPONENT */ THEN DO SET &PRIMARYI = &PRIMARYI /* RESET TO ORIGINAL VALUE */ SET &SECONDARYI = &SECONDARYI /* RESET TO ORIGINAL VALUE */ END END END EOV_VSAM Data Sets with Additional Volume Amount=Secondary End-of-Volume support for VSAM data sets with the Additional Volume Amount=SECONDARY data class attribute requires no special Allocation Selection Routine (ASR). IBM services update the primary allocation amount in the pertinent MVS control blocks with the applicable secondary allocation amount from the catalog entry of the cluster before checking for an available candidate volume for the data set to extend onto. VSAM_EOV is still using what is indicated in the primary allocation amount (that it finds Concepts and Facilities 67

68 in the applicable MVS control blocks) to make the first extension to an extra volume. For more information, see the variable descriptions of PRIMARYD 10 and PRIMARYI 11. EOV Support for Zero Secondary Non-VSAM data sets allocated with no secondary space fall victim to D37-04 abends when their primary space is exhausted. Running with a PLSZSEC(Y) configuration temporarily changes the 0 secondary allocation amount to 1. This change results in the EXTEND environment being launched exactly as if it would have been launched had the data set originally been allocated with a nonzero secondary. For more information about PLSZSEC, see PLS Sysparms (see page 109). EXTEND support for these 'Z SEC' allocations is identical to what is available to original 'NZ SEC' allocations. This includes changing the secondary value or even denying the extend request by exiting the environment with something other than the default return code of (0). They can be identified by the EXTEND environment ASR by querying the value of the SECONDARY_HAD_ ZERO variable. For more information, see SECONDARY_HAD_ZERO 12. DOES IT FIT (DIF) Support DIF support prevents Space Not Available (SNA) job failures. DIF is a functional equivalent to the legacy LSPACE Feature that is documented later in the section Space Type Conversions (see page 97). CA Allocate DASD Space and Placement has a feature that lets you alter the original space allocation unit and quantity. You can change non-vsam allocations and either at the cluster or component level for VSAM ones. A space type conversion can involve up to as many as ten variables. All Non-VSAM and all VSAM AVGBLK AVGRECSIZE AVGRECTYPE BLKSIZE OPTBLK SPACCVT Non-VSAM and VSAM Clusters PRIMARY SECONDARYD SPACTYPED UNITTYPED VSAM Data Components PRIMARYD SECONDARYD SPACTYPED UNITTYPED VSAM Index Components PRIMARYI SECONDARYI SPACTYPEI UNITTYPEI Concepts and Facilities 68

69 The values in the AVGRECTYPE, AVGRECSIZE, AVGBLK, BLKSIZE, OPTBLK, UNITTYPE, UNITTYPED, and UNITTYPEI variables are not changed. The values, and the value of the SPACTYPE, SPACTYPED, and SPACTYPEI variables, have an impact on how the variables dealing with the primary and secondary allocation quantities (PRIMARY, PRIMARYD, PRIMARYI, SECONDARY, SECONDARYD, and SECONDARYI) are modified. The remainder of this topic contains a general overview of how and why space type conversions are done. Detailed information about each of the preceding variables and examples on how each one participates in a space type conversion is found in the section ASR Variables 13. Allocation requests can be made in units of tracks, cylinders, blocks, average records, and sometimes kilobytes or megabytes. Disk devices have different storage capacities. Storage Administrators want to use available disk space efficiently. You can simplify the usage by converting various allocation units to one standard. For example, a primary allocation quantity of ten, without knowing whether it is in blocks, tracks, or cylinders, does not give the Allocation Selection Routine enough information. The routine cannot make a pooling decision that is based on the actual number of bytes requested. The following statements allow the ASR to make pooling decisions that are based on the actual amount of space being requested. File Edit Confirm Menu Utilities Compilers Test Help EDIT.ASR.PARMLIB(POOLDESC) Columns Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* SET &UNITTYPE = '3390' SET &SPACTYPE = 'TRK' SET &PRIIMARY = &PRIMARY SET &SECONDARY = &SECONDARY SET &N0 = (( &PRIMARY ) + (&SECONDARY = 15)) IF &N0 > 100 THEN SET &STORGRP = 'LARGE' ELSE IF &N0 > 25 THEN SET &STORGRP = 'MEDIUM' ELSE IF &NO > 5 THEN SET &STORGRP = 'SMALL' ELSE SET &STORGRP = 'TINY' The preceding ASR code initiates a real-time conversion of whatever the original allocation unit was (that is, BLK, CYL, and so on) to the equivalent number of 3390 tracks. The conversion is the default action of the SPACCVT variable, 'Y': do the space type conversion. Note: To convert to BLK, a BLKSIZE must be available. If no BLKSIZE is specified, the conversion is to the appropriate allocation in TRK. The conversion releases space on track boundaries as expected. In this case, TRK allocations are unchanged and CYL is converted to TRK Concepts and Facilities 69

70 Sometimes, the Storage Administrator wants to set both the allocation unit and quantity to a fixed amount. In such cases and conversions are not required, set 'N' as the value of the SPACCVT variable. The following ASR code converts all temporary data set allocation requests to SPACE=(TRK,(25,25)). IF &DSTYPE = 'TEMP' THEN DO SET &SPACCVT = 'N' SET &SPACTYPE = 'TRK' SET &PRIMARY = 25 SET &SECONDARY = 25 END DIF is: Easier to understand Requires fewer ASR statements to use Costs less, performance-wise, to execute The ASR is no longer responsible for correctly retrieving, converting, comparing, and reducing the space amounts. DIF does all the actions automatically and does it quicker than any series of ASR statements. DIF also does not need to look at every volume in storage group but only as many as necessary to find one that has enough available free space. For the non-sms data sets that CA Allocate DASD Space and Placement actually does the volume selection for, an even greater savings of CPU cycles are possible. In these instances, the most resourceintensive portions of DIF processing are not needed. Any necessary space reduction will be deferred until after the Volume Selection Logic (VSL) has checked all volumes without finding sufficient available free space on any of the volumes. If the VSL already included free space checking at the volume level, the VSL remembers which volume had the largest amount of available free space. DIF does not need to duplicate the free space checking before applying the ASR specified reduction criteria to the original allocation amount. The SMS-Managed Non-VSAM Data Sets (see page 26)section details the environments that you see during the allocation of a new multistriped PSE data set. The values that are displayed for the PRIMARY and SECONDARY variables in the ALLOC, SPACE, and EXTEND environment launches for redriven allocation requests always reflect the total allocation amount for all the associated stripes as it was following the original ALLOC environment launch. The value is consistent with the before amount noted in any additional VAM0096 messages denoting multiple instances RTF activity occurring as SMS redrives the allocation of the multistripe data set multiple times as it adjusts the stripe count. DIF Analysis done in the ALLOC environment for new multistripe PSE data sets is always done against the estimated size of the allocation request for the first stripe, which can only be seen when running with DIAGS=<jobname> activated in the following manner: In the xxxxxxxx portion of the messages that VAMDIF04 issues, where???? is either TRKS or CYLS: VAM000I...CALC_TRUE_WANTED VAM000I...CALC_ESC_WANTED VAM000I...SEEKING xxxxxxxx???? In the xxxxxxxx portion of the messages that VAMDIF03 issues, where???? is either TRKS or CYLS, and the xxxxxxxx matches the nonzero value that is displayed for ESC_WANTED: Concepts and Facilities 70

71 VAM000I...WANTED_????( xxxxxxxx) In the nonzero value that is displayed for ESC_WANTED in the messages that VAMDIF05 issues before the first of possibly five VAM0096 messages are issued. In the xxxxxxxx portion of the messages that VAMDIF00 issues, where???? is either TRKS or CYLS. The yyyyyyyy is the total primary amount for all stripes that are always both larger than xxxxxxxx and are, excluding rounding, a multiple of xxxxxxxx with the multiplier being the estimated stripe count that is shown in the nonzero value that is displayed for EST_SC: VAM000I...SEEKING xxxxxxxx???? VAM000I...JFCBPQTY IN???? yyyyyyyy More information: DIF Overview (see page 71) Volume Level DIF (see page 73) Storage Group Level DIF (see page 74) DIF Special Considerations (see page 74) DIF Overview DIF is available at either storage group level (SGL) or the volume level (VL) or both depending on the environment: Environment ALLOC DEFINE EOV EOV_VSAM EXTEND Level Available SGL and VL SGL and VL SGL only SGL only VL Only DIF has the same range limitations as the LSPACE Feature: SGL for SMS-managed in ALLOC for GUARANTEED_SPACE=N only SGL for SMS-managed in DEFINE for GUARANTEED_SPACE=N only SGL limited to primary SG only SGL limited to primary volume only VL for SMS-managed in ALLOC for GUARANTEED_SPACE=Y only VL for SMS-managed in DEFINE for GUARANTEED_SPACE=Y only Concepts and Facilities 71

72 The ASR invokes DIF by referencing the following variables: Variable Name &DOES_IT_FIT &MINIMUM_PERCENT &REDUCE_BY Alias &DIF &MP &RB The DOES_IT_FIT variable is only applicable to VL DIF. A value of Y indicates that sufficient free space is available on the target volume. A value of N indicates that there is not enough free space on the target volume. A value of? indicates that DIF terminated prematurely due to an unrecoverable error. Details on the error are available in the documentation. The documentation is associated with one or more VAM0093 messages that are unconditionally issued in such instances. Both the MINIMUM_PERCENT and REDUCE_BY variables are optional for volume level DIF and required for storage group Level DIF. The values of these variables control how DIF makes any necessary space reductions to the allocation request. The request can then be successful on either the target volume or on one of the volumes in the target storage group. MINIMUM_PERCENT is used to indicate at what percentage of the original space request the automatic space reductions stop. REDUCE_BY is the iterative percentage that DIF reduces the original space request by. The range for both MINIMUM_PERCENT and REDUCE_BY is 1 through 99. Space requests have essentially seven different types: &SPACTYPE Value AVR BLK CYL KB MB REC TRK Definition Average Record Block Cylinder Kilobyte Megabyte Record Track Space requests that do not require a Reduce To Fit (RTF) adjustment do not have any changes that are made to the allocation type or amounts. A space request that is in TRK or CYL that requires an RTF adjustment only sees the reduction that is made to the applicable allocation amount. A space request that is in Blocks, Bytes, Kilobytes, or Megabytes that requires an RTF adjustment undergoes a Virtual Conversion (VC) to TRK or CYL for DIF analysis and possible RTF adjustment. When the adjusted RTF amount is converted back to the original space type, the amount is rounded down to the nearest whole unit. This rounding results in shrinkage of the RTF amount from less than 1 Concepts and Facilities 72

73 percent to as high as 50 percent. The amount of shrinkage depends on the capacity of the original space type and the number of whole units of the RTF amount. Generally, the smaller the allocation amount the higher the possible shrinkage percentage. All space requests for old data sets requiring an RTF adjustment that went through a VC is reconverted back into their original space type. For new data sets requiring an RTF adjustment, the VC can become permanent if sysparm PLSOPT76 is overridden to (Y). This value indicates that the VC is to become permanent following any RTF adjustment. PLSOPT76 does not have any meaning for: VSAM data set allocations because the operating system converts all new VSAM data set allocations to either TRKs or CYLs even if the original allocation requests were made in units of KB, MB, or REC. Non-SMS managed AVR allocations that are converted to TRKs so that CA Allocate DASD Space and Placement can redirect them. Old non-vsam data sets are converted to TRKs or CYLs by the operating system as they span volumes even if the operating system had originally left a BLK request in BLKs and an AVR request in bytes, kilobytes, or megabytes. New non-vsam AVR data set allocations that RTF requirements have reduced to the TRK equivalent of less than one of the original AVR units. Set both PLSOPT10 and PLSOPT31 to (Y) to use the DIF support in the ALLOC environment for SMSmanaged data sets. Volume Level DIF Volume Level (VL) DIF occurs real time when DOES_IT_FIT variable is referenced in an ASR statement in either ALLOC, DEFINE, or EXTEND. When DOES_IT_FIT variable is not referenced in an ASR statement, VL DIF processing occurs post-asr time only if the ASR had specified values for both REDUCE_BY and MINIMUM_PERCENT variables and only as follows: For SMS-managed: In EXTEND, only when EXTENDVOL=CURRENT In DEFINE, only when GUARANTEED_SPACE=Y In ALLOC, only for non-vsam only when GUARANTEED_SPACE=Y For non-sms: Always in EXTEND In DEFINE, only for non-sms data set allocation requests that the ASR has not requested the VSL to redirect that had not been made by either JCL statements or SVC99. In ALLOC, only for non-sms data set allocations that the ASR has not requested the VSL to redirect that already have a specific volume that is associated with them. VL DIF is conditionally and implicitly invoked post-asr time in ALLOC, DEFINE, and EXTEND if the ASR had specified values for both REDUCE_BY and MINIMUM_PERCENT. The same logic flow is followed during implicit VL DIF as been detailed previously for explicit VL DIF. Concepts and Facilities 73

74 Storage Group Level DIF Storage Group Level (SGL) DIF only occurs post-asr time when the ASR had specified values for both REDUCE_BY and MINIMUM_PERCENT and only as follows: For SMS-managed: Always in EOV, EOV_VSAM In DEFINE, only when GUARANTEED_SPACE=N In ALLOC, only for non-vsam only when GUARANTEED_SPACE=N For non-sms: Only if the ASR had specified to use the VSL Only after the VSL has failed to find a volume in the target storage group with sufficient free space Sometimes, the REDUCE_BY and MINIMUM_PERCENT variables specify criteria that does not allow enough reduction in the space amount to ensure that allocation is possible in the storage group. In this case, the applicable VAM0093 message is issued indicating this fact. The following example is DIF sample ASR code: FILTLIST &DIFENVIR INCLUDE(AL*,D*,E*) IF &VAMENVIR = &DIFENVIR THEN DO SET &MINIMUM_PERCENT = 25 SET &REDUCE_BY = 10 END DIF Special Considerations The Allocation Selection Routine determines which requests are eligible for DIF and RTF. The primary responsibility for determining which requests are eligible for either feature rests with you. Not every data set allocation can benefit: Any allocation request that does not currently support redirection must not undergo Storage Group Level DIF processing. Two known types of allocation requests that fall into this category are the DFDSS and IDCAMS BLDINDEX work files limitations that are detailed in the section Special Considerations for Using CA Allocate with Other Programs or Products (A-F) (see page 20). Any allocation request that is made by an application that does not currently support changes to the amount of space being requested must not undergo RTF processing. Three known types of allocation requests that fall into this category are SNAPSHOT, zfs UNIX, and DFSMShsm Limitations. Any internal exclusions about not honoring redirection or changes in the allocation amount are extended to the criteria checks that are internally made to determine RTF eligibility. One known type of allocation request that falls into the latter category is FDR support (see page 95). Concepts and Facilities 74

75 DIF eligibility in both the ALLOC and DEFINE environments for new VSAM data sets allocated by either JCL statements of SVC99 is programmatically determined to minimize CPU cycles: 1. SMS-managed: In ALLOC, not eligible for either VL or SGL DIF 2. Non-SMS-managed: a. In ALLOC, if redirected, only eligible for SGL DIF b. In DEFINE, where redirection is not permitted, only eligible for VL DIF DIF support is insurance against SNA job failures. One example of this insurance is the preceding item 2b. Following up the SGL DIF in 2a with VL DIF on 2b can prevent what otherwise would be an SNA failure in the event some other job grabs the free space between 2a and 2b. To minimize CPU cycles further, VSAM data set eligibility for DIF support in the EXTEND environment is limited to more extents on the current volume. An EOV_VSAM environment launch immediately precedes EXTEND environment launches for VSAM onto new volumes. Any RTF processing that is done in that EOV_VSAM launch is remembered by the subsequent EXTEND environment launch. This method assumes that you are running with PLSOPT24 set at its documented default value of (N). This setting allows the EOV_VSAM environment to launch for VSAM data sets with available candidate volumes. Both DIF and RTF processing are based on the free space availability on a volume or in a storage group at a particular point in time. There is no certainty that the free space found earlier during DIF and RTF processing is still available later at the time that allocation is made. The larger the window, the greater likelihood that some other data set has taken the space. The smallest window is in the EXTEND environment. The largest window is in the DEFINE environment. Typically these windows are small enough that the space is likely still available, but there can be no absolute certainty. DIF processing requires I/O, which causes extra overhead. The amount of overhead is directly proportional to the number of volumes that have to be checked before one is found with sufficient free space. This checking means that DIF processing of large allocations requests where available space is at a premium takes longer than it takes for small allocations where there is an abundance of available space. Sometimes, the allocation quantity that is seen in the optional diagnostics either: Does not exactly match the size that actually gets allocated, or The size that is allocated is a bit less than the requested MINIMUM_PERCENT These differences are due to programmatic assumptions, estimates, and rounding that is made during DIF analysis and RTF processing. Depending on how the ASR is coded, it is possible that the same data set allocation would be considered eligible for both Volume Level DIF and Storage Group Level DIF, with or without RTF. Unlike most CA Allocate DASD Space and Placement messages, the VAM0093 messages, and any supporting VAM0093x messages detailing the reason for the DIF or RTF failure, are issued unconditionally. This process might result in what initially might appear to be duplicate error messages for the same allocation request. This effect is magnified in jobs with multiple allocation requests. The default configuration results in most messages being issued to the SYSLOG and the JESMSGLG and JESYSMSG DDs allocated to the applicable batch job or started task. When PLSOPT98 (Y) is specified in parmlib, these messages are only issued to the JESMSGLG DD. The default value of this parameter, (N), results in these diagnostics being issued in triplicate as they historically have been issued. Concepts and Facilities 75

76 If you are running with PLSOPT98 (N), consider changing to PLSOPT98(Y). CA Allocate DASD Space and Placement messages are confined to a single place in the joblog. If you are running with PLSOPT38 (N), consider changing to PLSOPT38(Y). The VAM0096 messages are issued conditionally only when diagnostics have been activated. If you are running with PLSOPT39 (N), consider changing to PLSOPT39(Y). The VAM0093 messages are issued conditionally only when diagnostics have been activated. Important! Using DIF support with Key Data Set Separation support is resource-intensive. Consider the system impact before using it. NOT CATLGD 2 Support Allocating a new non-vsam data set using the same name as an already cataloged data set results in a NOT CATLGD 2 condition. This condition means that the data set was successfully allocated, but the catalog action failed. CA Allocate DASD Space and Placement provides the following variables to avoid this condition: STOP_NOT_CATLG2 STOP_NOT_CATLG2_NODE STOP_NOT_CATLG2_RC The variables allow for the deletion (SNC2=D), rename (SNC2=R), or uncataloging (SNC2=U) of the existing cataloged data set when a potential NOT CATLGD 2 condition is detected in the following environments: OLD: SNC2=U only SPACE: SNC2=D, SNC2=R, SNC2=U Special Considerations when using the SNC2=D Option You can stop the SNC2=D option in the SPACE or PREALLOC Environment for cataloged, unexpired, non-vsam data sets. In this case, using the default value of N for PURGE_UNEXPIRED_DATA_SET causes the original dataset to stay cataloged and the allocation will fail. If your ASR does not assign a value to the STOP_NOT_CATLG2 variable before invoking the SNC2 process, then a WTOR message is issued. The message provides real-time input to the ASR. The WTOR asks which option of the SNC2 support the ASR is to invoke or if the ASR is to cancel the new data set allocation request. In the SPACE environment, the WTOR message is as follows: VAM0513 DSN - dsname VAM0513 JOB - jobname; STEP - stepname VAM0513 DUPLICATE DATASET ALREADY CATALOGUED Concepts and Facilities 76

77 VAM0513 REPLY R (RENAME), D (DELETE), U (UNCATALOG) OR C (CANCEL ALLOCATION REQUEST) If the response is invalid, the WTOR is reissued after the following message: VAM0513 RESPONSE INVALID In the OLD environment, the message is as follows: VAM0513 DSN - dsname VAM0513 JOB - jobname; STEP - stepname VAM0513 DUPLICATE DATASET ALREADY CATALOGUED VAM0513 REPLY U (UNCATALOG) OR C (CANCEL ALLOCATION REQUEST) If the response is invalid, the WTOR is reissued after the following message: VAM0513 RESPONSE INVALID The minor differences in the messages that are issued between the SPACE and OLD environments reflects the SNC2 options that are applicable in each environment. More information: Use the SNC2 Option (see page 77) Sample ASR Statements (see page 79) Use the SNC2 Option Use the SNC2=R Option (see page 77) Use the SNC2=C Option (see page 78) Use the SNC2=U Option (see page 78) Use the SNC2RC Variable (see page 78) Restrictions (see page 78) Use the SNC2=R Option The Rename option renames the existing cataloged data set by appending the new node that is specified in the STOP_NOT_CATLG2_NODE variable at the end of the existing name. The value of the STOP_NOT_CATLG2_NODE variable can be 1-8 characters in length. Also, the ASR can change the default value of SNC2N. The length of the new node is the number of characters in STOP_NOT_CATLG2_NODE plus a period to separate the appended node from existing nodes. If the new name exceeds the 44-character limitation that the operating system imposed, the Rename option automatically removes the lowest existing low-level-qualifiers of the existing data set name. The option makes room for the new low-level-qualifier. Concepts and Facilities 77

78 Use the SNC2=C Option If you use the SNC2=C option, specify PLSQUOF8 (Y) in your sysparm override member before either an INSTALL or PARMREF operation. VKGPARMS is the default name of the sysparm override member and the default value of PLSQUOF8 is (N). You can use the SNC2=C option in the SPACE environment for new, non-sms-managed non-vsam data sets redirected in the ALLOC environment. In this case, assign a value of Y to the FAILIFNOVOLSEL variable in the redirection logic that is deployed in the ALLOC environment. Use the SNC2=U Option SNC2=U requests can be optionally deferred until step termination in the SPACE environment by using the DEFER_SNC2_U variable. Deferring the SNC2=U processing until step termination means that the ASR does not know whether the SNC2=U request is successful. Coding your ASR to defer any SNC2=U requests until step termination time lets you avoid losing a catalog entry. If the step that is attempting to create a new cataloged data abends, you prevent a NOT CATLG 2 condition. DEFER_SNC2_U is an ASR variable rather than a global system parameter. You can selectively apply the variable to your SNC2=U requests. If you process the SNC2=U request real time and the SNC2=U fails, the ASR can cancel the new data set allocation request. The processing occurs before the allocation of the new data set. You prevent the NOT CATLG 2 condition. If you defer SNC2=U requests until the step termination time and the SNC2=U request fails, the NOT CATLG 2 condition applies. The new data set had been allowed to get allocated. Use the SNC2RC Variable You can redrive the NOT CATLGD 2 support multiple times during the same environment invocation. Every time your ASR references the STOP_NOT_CATLG2_RC variable, the NOT CATLGD 2 support reinvokes. If you want to include the value of STOP_NOT_CATLG2_RC in a WRITE statement, change how your ASR references it. The SNC2 support does not reinvoke when you execute the WRITE statement. The following ASR fragment shows how to reference multiple times the return code. You receive the return code from a single invocation of the NOT CATLGD 2 support: SET &N0 = &STOP_NOT_CATLG2_RC WRITE 'RC FROM THE SNC2 SUPPORT IS &N0 IF &N0 = 0 THEN EXIT CODE(0) WRITE 'ASR CANCELLING ALLOCATION REQUEST DUE TO' WRITE 'NON-ZERO RC (&N0) RECEIVED BY THE SNC2 SUPPORT' EXIT CODE(8) Restrictions Consider the following restrictions before using this support: New data sets that are allocated from a TSO session are not supported. Concepts and Facilities 78

79 The UNCATALOG option cannot be performed against an existing SMS-MANAGED data set, because SMS does not permit uncataloged data sets. The existing data set has more than 255 volumes that are allocated to it. To be eligible for this support, non-sms-managed non-vsam data sets must have been either redirected by CA Allocate DASD Space and Placement (that is, a STORGRP must be set in the ALLOC environment) or you must be running with PLSOPT27 (Y). Existing data sets cataloged to a pseudo-volser are ignored. The UNCATALOG option is not performed when the existing cataloged data set is on the same volume where the new data set is being allocated. The DELETE option cannot be performed on a data set referenced by a SUBSYS DD statement, because SUBSYS data sets are considered SYSIN/SYSOUT data sets. IBM prevents these data sets from getting deleted. Sample ASR Statements The following illustrations show sample ASR code using the NOT CATLGD 2 support: Sample NOT CATLGD 2 ASR to DELETE ASR Specifies SNC2 Option IF &VAMENVIR = 'SPACE' THEN DO IF &DISPN = 'CATLG' AND &IFALREADYCAT = 'Y' THEN DO SET &STOP_NOT_CATLG2 = 'D' IF &STOP_NOT_CATLG2_RC > 0 THEN EXIT CODE(8) END END Sample NOT CATLGD 2 ASR to RENAME ASR Requests WTOR to Ask Console Operator to Specify SNC2 Option IF &VAMENVIR = 'SPACE' AND &IFALREADYCAT = 'Y' THEN DO SET &N0 = &STOP_NOT_CATLG2_RC IF &N0 = 0 THEN EXIT CODE(0) IF &STOP_NOT_CATLG2 = 'C' THEN DO WRITE 'REPLY TO THE VAM0513 WTOR MESSAGE WAS "C"' END ELSE DO WRITE 'SNC2=&SNC2 OPERATION FAILED, ERROR CODE &N0' END WRITE 'ASR CANCELLING ALLOCATION REQUEST' EXIT CODE(8) END Concepts and Facilities 79

80 Sample NOT CATLGD 2 ASR to UNCATALOG IF & VAMENVIR = 'OLD' THEN DO IF &DISPN = 'CATLG' THEN DO IF & IFALREADYCATVOL NE &VOLSER THEN DO IF &DISPN = 'CATLG' AND &IFALREADYCAT = 'Y' THEN DO SET &STOP_NOT_CATLG2 = 'U' IF &STOP_NOT_CATLG2_RC > 0 THEN WRITE 'NOT ABLE TO RESOLVE POTENTIAL NOT CATLGD 2 CONDITION' END END END END IF &VAMENVIR = 'SPACE' THEN DO IF &DISPN = 'CATLG' AND &IFALREADYCAT = 'Y' THEN DO SET &STOP_NOT_CATLG2 = 'U' IF &STOP_NOT_CATLG2_RC > 0 THEN DO WRITE 'NOT ABLE TO RESOLVE POTENTIAL NOT CATLGD 2 CONDITION' WRITE 'ASR CANCELLING ALLOCATION REQUEST' EXIT CODE(8) END END END Sample NOT CATLGD 2 ASR to defer UNCATALOG until step termination time IF &VAMENVIR = 'SPACE'AND &IFALREADYCAT = 'Y'AND &SMS_MANAGED = 'N' THEN DO SET &STOP_NOT_CATLG2 = 'U' SET DEFER_SNC2_U = 'Y' END ACS Support The ACS environment can be used as a direct replacement for IBM ACS routines. Because the CA Allocate DASD Space and Placement ASR language can be used to manage both SMS-managed and non-sms-managed data sets, there is no need for ACS routines or ACS exits. Concepts and Facilities 80

81 Note: IBM procedures might require some minimum ACS Routine setup. See the appropriate IBM documentation. Any of the four SMS constructs can be changed: DATA CLASS, STORAGE CLASS, MANAGEMENT CLASS, or STORAGE GROUP. Normal ISMF setup is done to create and define the constructs. CA Allocate DASD Space and Placement gets control after all IBM ACS processing is complete, but before returning to the original requestor of the ACS services. It can be used to change or remove any of the four SMS construct names. The ACS environment is entered any time ACS processing is required for any of the four SMS constructs. The variables available are: DATACLAS DC or DATACLASS STORCLAS SC or STORAGECLASS MGMTCLAS MC or MANAGEMENTCLASS STORGRP SG or STORAGEGROUP Storage group can be defined for either SMS or CA Allocate DASD Space and Placement. If a storage class is set, the data set becomes SMS-managed. The STORGRP must be a valid SMS storage group name. If the storage class is not set, the data set becomes non-sms-managed. The STORGRP must be a valid CA Allocate DASD Space and Placement storage group. Enhanced DATACLAS Support This feature relieves the SMS limitation that values specified for the DATACLAS subparameters is used only if others are not explicitly coded in the JCL. Currently, this support is limited to new data set allocations that are intercepted in the ALLOC and DEFINE environments. As delivered, the product automatically exempts new SMS-managed data set allocations from ALLOC and DEFINE environments processing. For implementation procedures, see PLSOPT10 in PLSOPTnn Sysparms (see page 126). IBM DATACLAS Support Either JCL or the IBM ACS routines can set the SMS Data Class parameter (DATACLAS). The subparameters that are associated with a DATACLAS are propagated to the data set unless that same parameter is specified in the JCL. The subparameters include RECORG, LRECL, SPACE, RETPD, and so on. The JCL information overrides what was defined in the DATACLAS. The problem with this method is two-fold: Sometimes, a change is needed to a particular parameter in many jobs. You might have to change the JCL everywhere because the JCL overrides the ACS DATACLAS. Any user can override DATACLAS specifications that are coded by the installation in the IBM ACS routines. The user can specify their own DATACLAS information in the JCL. Concepts and Facilities 81

82 DATACLAS Support In the ALLOC environment, the ASR can interrogate both the DATACLAS and JCL information and can select from either one or can specify an entirely different value. The JCL information is what is used to allocate the data set when CA Allocate DASD Space and Placement does the volume selection. This method means that any DATACLAS information must be propagated to the related JCL parameter if a STORGRP is set for a non-sms-managed allocation. The following illustration is a sample Allocation Selection Routine. The sample has ASR code addressing VSAM JCL DEFINEs that are intercepted in the ALLOC environment. Note the following items: There are two different types of processing that are done for allocations with an associated DATACLAS. For the 'ISPDATA1' Data Class, the ASR writer knows which subparameters have values that are defined, so there is no need to examine the associated DC_*_FLAG indicator. All allocations with this Data Class are converted to the same average records type and quantity. For any other Data Class, what action the ASR takes depends on what subparameters have been defined, which querying the associated DC_*_FLAG indicator determines. To check for encrypted data sets, use FILTLISTs for encryption key values and change to correct value. Use DC_DSKEYLBL_FLAG in the ALLOC or DEFINE environments to check if the data set has a valid SMS data class and the Data Class Key label was specified on the data class. Then determine whether to set a new Data Class. Use of 'EXIT CODE(0)'. VSAM JCL DEFINEs are intercepted first in the ALLOC environment and then in the DEFINE environment. Do the redirection in the ALLOC environment. Concepts and Facilities 82

83 FILTLIST &VSAM INCLUDE('DCKSDS','DCESDS','DCLSDS','DCRRDS') IF &VAMENVIR = 'ALLOC' THEN DO IF &DC = '' THEN EXIT CODE (0) /* IF NONE THEN EXIT */ IF &DC = &VSAM THEN EXIT CODE (0) /* VSAM DATACLAS EXIT */ IF &DSORG = 'VS' THEN EXIT CODE (0) /* VSAM JCL DEFINE EXIT */ IF &DC_RECFM = '' THEN EXIT CODE (0) /* VSAM JCL DEFINE EXIT */ IF &DC = 'ISPDATA1' THEN /* FOR THIS DATA CLASS */ DO COPYBOOK 'DC1' /* ENFORCE DC ATTRIBUTES */ END ELSE DO COPYBOOK 'DC2' /* ALL OTHER DATA CLASSES */ END END IF &VAMENVIR = SPACE AND &BLKSIZE = 0 THEN SET &BLKSIZE = &OPTBLK Copybook DC1: /* ENFORCE DATACLAS ATTRIBUTES */ IF &DC_PRIMARY_FLAG = 'Y' THEN SET &PRIMARY = &DC_PRIMARY IF &DC_SECONDARY_FLAG = 'Y' THEN SET &SECONDARY = &DC_SECONDARY IF &DC_RETPD_FLAG = 'Y' THEN SET &RETPD = &DC_RETPD IF &LRECL = 0 THEN DO IF &DC_LRECL_FLAG = 'Y' THEN SET &LRECL = &DC_LRECL ELSE SET &LRECL = 80 END SET &UNIT = 'SYSALLDA' SET &STORGRP = 'POOLB' Copybook DC2: /* ALL OTHER DATA CLASSES */ SET &SPACCVT = 'N' /* DON'T DO SPACE CONVERSION */ SET &SPACTYPE = 'AVR' /* SPACE TYPE AVERAGE RECORDS */ SET &AVGRECTYPE = &DC_AVGRECTYPE /* USE DATACLAS ATTRIBUTE */ SET &AVGRECSIZE = &DC_LRECL /* SET AVRSIZE */ SET &PRIMARY = &DC_PRIMARY /* USE DATACLAS ATTRIBUTE */ SET &SECONDARY = &DC_SECONDARY /* USE DATACLAS ATTRIBUTE */ SET &RETPD = &DC_RETPD /* USE DATACLAS ATTRIBUTE */ SET &LRECL = &DC_LRECL /* USE DATACLAS ATTRIBUTE */ SET &UNIT = 'SYSALLDA' /* SET UNIT */ SET &STORGRP = 'SSLDA' /* SET STORGRP */ /* IF AVGBLK SPECIFIED */ /* THEN USE IT */ IF &DC_AVGBLK_FLAG = 'Y' THEN DO SET &SPACCVT = 'N' /* DO NOT DO SPACE CONV */ SET &SPACTYPE = 'BLK' /* SPACE TYPE BLOCKS */ SET &AVGBLK = &DC_AVGBLK /* USE DATACLAS ATTRIBUTE */ SET &BLKSIZE = &DC_AVGBLK /* USE DATACLAS ATTRIBUTE */ END IF &DC_AVGRECTYPE=FLAG = 'Y' AND &DC_AVGRECSIZE_FLAG = 'Y' THEN DO /* DO NOT DO SPACE CONV */ SET &SPACCVT = 'N' SET &SPACTYPE = 'AVR' SET &AVGRECTYPE = &DC_AVGRECTYPE /* USE DATACLAS ATTRIBUTE */ SET &AVGRECSIZE = &DC_AVGRECSIZE /* USE DATACLAS ATTRIBUTE */ END Concepts and Facilities 83

84 Tape Allocation Support Tape Allocation support lets you enforce standards for new tape allocations. For example, data compression can be enforced, Label Types adhered to, and migration to new tape devices accomplished without the need for end users to make JCL changes. In addition, available disk space shortages can be avoided by redirecting large disk allocations to tape. Tape utilization might be made more efficient by redirecting identifiable small tape allocations to disk. More information: Device-Type Conversions (see page 84) Volume Referbacks/Unit Affinity and Disk-only Allocations (see page 86) Device-Type Conversions CA Allocate DASD Space and Placement intercepts allocation requests for new tape data sets in the ALLOC environment. The following tape-only variables exist to support tape allocations: &CMP3480 (data compression) &FILENUM (file sequence number) &LABEL (label type) All these variables are modifiable. Some internal validity checks are performed. For example, &LABEL can be changed to only one of the eight valid types that are specified in any MVS JCL Reference documentation, &FILENUM to only a positive integer, and &CMP3480 to only on or off. For more information, see ASR Variables 14. Even with the internal validation, carefully consider before modifying these variables. For example, globally forcing data compression on for all tapes is inadvisable when tapes might be shipped to other sites that do not support the compression feature on their 3480/3490 tape devices. Neither is it a good idea to change the label type to one that, although a valid MVS one, is unsupported at your particular installation. Finally, an incorrect value for &FILENUM can cause various errors, including unintentionally over writing an existing data set or failing with a 413 or A13 abend. TAPE-to-TAPE Conversions TAPE-to-TAPE conversions occur when a request is issued to change the tape unit type that is specified for the original allocation to another tape unit type. If no additional changes are explicitly requested for the data compression, file sequence number, label type, and expiration date (or retention period) variables, what was previously specified for the original allocation is used. Nothing is done to any volume referback or unit affinity that might have been originally specified for the allocation. These specifications are typically not an impediment in TAPE-to-TAPE conversions because the original and new device types are within the same device class Concepts and Facilities 84

85 The following sample ASR statements result in a TAPE-to-TAPE device-type conversion from round tapes to cartridges with data compression being turned on for the allocations unless TRTCH=NOCOMP has been explicitly specified in the JCL. IF &UNIT = '3420' THEN DO SET &UNIT = '3480' IF &CMP3480 EQ 'N' /* NO COMPRESSION ASKED FOR? */ THEN SET &CMP3480 = 'Y' /* IF NOT, TURN IT ON */ END TAPE-to-DISK Conversions TAPE-to-DISK conversions occur when a request is issued to change what was originally a tape allocation to disk. If no additional changes are requested for the expiration date (or retention period) variable, what was specified for the original allocation is used. Data compression is turned off and the file sequence number and label type is reset to 1 and SL, respectively. Allocation quantity has no default. BLK, CYL, or TRK can be specified as the allocation unit and failure to do so generally leads to message IEF127I. If CA Allocate DASD Space and Placement was requested to redirect the allocation but is unable to select a volume, it fails the allocation through the standard &FINVS='Y' route. Any volume referback or unit affinity that is originally specified for the allocation is disabled. These specifications typically have an adverse impact on TAPE-to-DISK conversions because the original and new device types are of a different device class. If either is found, and CA Allocate DASD Space and Placement is not requested to redirect the allocation, the conversion request is ignored. The following sample ASR statements result in a TAPE-to-DISK device-type conversion. When no space attributes had been specified for the original allocation, the default of SPACE=(CYL,(10,10),RLSE) is used. IF &UNIT = 'TAPE' THEN DO SET &UNIT = 'SYSALLDA' SET &STORGRP = 'DASD80' IF &SPACTYP = '' THEN DO SET &SPACTYPE = 'CYL' SET &PRIMARY = 10 SET &SECONDARY = 10 SET &RLSE = 'Y' END END DISK-to-TAPE Conversions DISK-to-TAPE conversions occur when a request is issued to change what was originally a disk allocation to a tape allocation. Any allocation unit and quantities that were previously specified for the original allocation are ignored. Unless new values are requested, the file sequence number and label type remain the same as they were either specified or implied in the original disk allocation (typically 1 and SL). No default data compression is assumed. Any expiration date (or retention period) that was specified for what was originally a DASD allocation is still used, unless a new date is requested. And lastly, the newly converted tape allocation is nonspecific. Concepts and Facilities 85

86 Any volume referback originally specified for the allocation is disabled. These specifications typically have an adverse impact on DISK-to-TAPE conversions because the original and new device types are of a different device class. The following sample ASR statements result in a DISK-to-TAPE device-type conversion: IF &UNIT = 'SYSDA' THEN DO SET &UNIT = '3480' END Volume Referbacks/Unit Affinity and Disk-only Allocations When redirection is requested, disable any volume referback or unit affinity that might have been originally specified for the allocation. This process is necessary to ensure the successful allocation on the volume chosen. Failure to do so causes IEF245I INCONSISTENT UNIT NAME AND VOLUME SERIAL and the allocation fails. To avoid allocation failures, requests to disable volume referback or unit affinity are ignored unless redirection is requested. Note: You can automatically disable unit affinity by specifying PLSOPT3 with a value of Y. For more information, see PLSOPT3 in the PLSOPTnn Sysparms (see page 126) section. The following sample ASR statements illustrate some of the flexibility that is allowed in this area. Volume referback and unit affinity are permitted for temporary data sets and tape, while permanent disk data sets are redirected, with volume referback and unit affinity disabled to prevent allocation failures. The following illustration is a sample of Referbacks and Unit Affinity ASR statements: Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(REFERBKS) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* FILTLIST &DASD INCLUDE('SYSDA','3380','3390','DISK') IF &UNIT = &DASD THEN DO IF (&UNITAFF = 'Y') OR (&VREFDDN = 'Y') OR IF (&VREFDSN = 'Y') OR (&VREFSTP = 'Y') THEN DO IF &DSTYPE = 'TEMP' THEN EXIT CODE(0) SET &UNITAFF = 'N' SET &VREFDSN = 'N' SET &VREFSTP = 'N' SET &VREFDDN = 'N' SET &UNIT = 'SYSALLDA' SET &STORGRP = 'POOL01','POOL02','POOL03' END END ******************************** Bottom of Data ******************************* Concepts and Facilities 86

87 Resolve Volume Referbacks and Unit Affinities DDs are processed one at a time. The operating system resolves volume referbacks and unit affinities immediately before its processing of a DD. This resolution removes any evidence of a device-type conversion. Consider the following JCL: File Edit Confirm Menu Utilities Compilers Test Help EDIT.ASR.PARMLIB(IEBCOPY) Columns Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* //JOB JOB //UNLOAD2 EXEC PGM=IEBCOPY //IN1 DD DSN=DSET.PO1,DISP=SHR //IN2 DD DSN=DSET.PO2,DISP=SHR //IN3 DD DSN=DSET.PO3,DISP=SHR //OUT1 DD DSN=UNLOADED.PO1,UNIT=3480,DISP=(NEW,PASS), // LABEL=(1,SL) //OUT2 DD DSN=UNLOADED.PO2,UNIT=AFF=OUT1,DISP=(NEW,PASS), // LABEL=(2,SL),VOL=REF=*.OUT //OUT3 DD DSN=UNLOADED.PO3,UNIT=AFF=OUT1,DISP=(NEW,PASS), // LABEL=(3,SL),VOL=REF=*.OUT //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(2,2)) //SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(2,2)) //SYSPRINT DD DUMMY //SYSIN DD * COPY INDD=IN1,OUTDD=OUT COPY INDD=IN2,OUTDD=OUT COPY INDD=IN3,OUTDD=OUT /* As written, OUT1 refers to a tape volume. If the ALLOC ASR changes the unit to a disk device, this device-type conversion is detected. The documented default actions are taken. Volume referbacks and unit affinities to OUT1 are no longer to a tape volume and unit, but rather to the disk one on which the allocation was made. As written, with both volume referbacks and unit affinities, OUT2-OUT3 refers to a tape volume and unit. Any changes that are made to the device type associated with OUT1, and any volume that becomes associated with OUT1, are propagated forward to OUT2-OUT3 as the operating system resolves each volume referback and unit affinity. Because this resolution occurs before the OUT2-OUT3 are processed, no device-type conversion is detected. These DDs are seen as disk allocations with volume referback and unit affinity that is specified, but no space. The unit affinity attribute is only disabled because it is not applicable to disk allocations. No default space attributes are set. The ALLOC ASR must set the default space attributes Failure to do so results in the job failing with a IEF127I NO SPACE PARAMETER JCL error. SMF Interfaces CA Allocate DASD Space and Placement can conditionally write SMF records to track various specific activities. Concepts and Facilities 87

88 Track Successful EOV Recovery Activities (see page 88) Track Successful Reduce to Fit (RTF) Activities (see page 88) Track Successful EOV Recovery Activities Use Sysparm PLSSMF01 to activate the writing of an SMF record upon successful completion of EOV recovery of a data set. If you use the default value of (000), no SMF records are written. Else, the value of PLSSMF01 is used as the SMF record number. To enable the writing of SMF records, specify a value between (128) and (255) for PLSSMF01 before an INSTALL or PARMREF operation. The values of (128) through (255) are the documented range of values that reflect IBM documentation for SMF user record numbers. Message VAM0090 is issued for invalid values. The data that is contained in the SMF record, as defined by IBM, is sysid, time, and date; the jobname, stepname, dsname, dsorg, and volser is stored in the SMFDATA field JOBNAME BLANK STEPNAME BLANK DSNAME BLANK DSORG BLANK VOLSER For VSAM files, dsname is the name of the VSAM component that encountered the EOV condition. Volser contains the volume that is selected to resolve the EOV condition. For SMS-managed VSAM files, volser is always '*' to reflect the candidate volume that was allocated to the VSAM component. Track Successful Reduce to Fit (RTF) Activities Use Sysparm PLSSMF02 to activate the writing of an SMF record upon successful completion of RTF recovery of a data set. By using the default value of (000), no SMF records are written. Else, the value of PLSSMF02 is used as the SMF record number. Note: The values set for PLSSMF01 and PLSSMF02 are mutually exclusive. To enable the writing of SMF records, specify a value between (128) and (255) for PLSSMF02 before an INSTALL or PARMREF operation. The values of (128) through (255) are the documented range of values that reflect IBM documentation for SMF user record numbers. The data that is contained in the SMF record, as defined by IBM, is sysid, time, and date; the SMFDATA field contains up to ten fields as follows: Concepts and Facilities 88

89 JOBNAME BLANK STEPNAME BLANK DSNAME BLANK ALLOCATION AMOUNT (PRI, PDC, PIC, SEC, SDC, SIC) BLANK ORIGINAL SPACE UNIT (AVR, BLK, CYL, KB, MB, REC, TRK) BLANK ORIGINAL SPACE AMOUNT (quantity original space unit, character format) BLANK AVERAGE RECORD TYPE (U, K, M) BLANK RTF SPACE UNIT (actual final unit: AVR, BLK, CYL, KB, MB, REC, TRK) BLANK RTP SPACE AMOUNT (quantity of actual final unit, character format) BLANK VAM0093* (8-character number of message issued denoting RTF failure) The SMF record is only written if the allocation request actually starts the interactive reduction process. This statement means that when another error terminates the DIF support before the need for RTF action is determined, no SMF record is written. Note: The VAM0093J message that can be noted in columns can be issued for SMSmanaged and non-sms-managed data sets. Assume that a VAM0039R message is scheduled to be issued for a non-sms-managed data set because volume selection failed due to the VAM0093J condition. In this case, the VAM0093J message is only issued when running with PLSOPT99 (Y). When RTF is invoked in the DEFINE environment, the allocation amount can be PRI, PDC, or PIC. The data set name that is put in the SMF record is always the cluster name. When RTF is invoked in EXTEND or EOV_VSAM, the allocation amount is either PDC or PIC, or SDC or SIC. The data set name is the VSAM component name actually requesting the space. DFSMShsm Support To activate HSM support, do the following things: Specify PLSOPT15(Y) Use HSMON command to activate Activating HSM support requires both of the preceding actions. The interface with DFSMShsm allows the data sets allocated by DFSMShsm to be handled like all other data sets. Creating a DFSMShsm RECALL exit is unnecessary. Volume pools are maintained in one central location (storage groups). This method eliminates the need to keep the DFSMShsm pools synchronized with CA Allocate DASD Space and Placement. DFSMShsm uses multiple data movers to move data around. DFSMShsm might move the data itself, or it might call DFSMSdss to move the data. The data mover that is used depends on the type of operation and the type of data. For more information, see the appropriate IBM documentation. Concepts and Facilities 89

90 In addition to the usual CA Allocate DASD Space and Placement ASR variables, the following specialpurpose variables are provided for DFSMShsm RECALL and RECOVER operations. These variables provide more information about the data set which DFSMShsm is operating on: &HSMDSN Indicates the real data set name. &HSMGROUP Indicates the security group name of requesting user. &HSMHLQ Indicates the real data set high-level qualifier. &HSMJOB Indicates the requesting job name. &HSMLLQ Indicates the real data set low-level qualifier. &HSMNQUAL Indicates the num qualifiers in real data set name. &HSMUSER Indicates the requesting user name. CA Allocate DASD Space and Placement can select a new volume (redirect) for allocations that are done by any of the following DFSMShsm functions: BACKUP MIGRATE RECALL RECOVER CA Allocate DASD Space and Placement recognizes that the allocation is being done by DFSMShsm. CA Allocate DASD Space and Placement modifies DFSMShsm control information as required to let DFSMShsm use the volume that was selected. Using CA Allocate DASD Space and Placement to reduce the primary allocation amount results in DFHMShsm terminating the RECALL or RECOVER operation with an "ADR729E UNABLE TO ALLOCATE SUFFICIENT SPACE" error. The following topics present the details of DFSMShsm operation as they relate to CA Allocate DASD Space and Placement: SMS Construct Names Used During DFSMShsm RECALL and RECOVER Operations (see page 91) New Logic Required in the ACS Environment (see page 91) Data Set Names Generated by DFSMShsm During MIGRATE and BACKUP (see page 91) DFSMShsm During RECALL/RECOVER (see page 92) ASR Variables for HSM RECALL and RECOVER Operations (see page 92) The DFSMShsm RECALL Exit (ARCRDEXT) (see page 94) Control Only RECALL and RECOVER Operations (see page 94) Concepts and Facilities 90

91 SMS Construct Names Used During DFSMShsm RECALL and RECOVER Operations When CA Allocate DASD Space and Placement manages a DFSMShsm RECALL or RECOVER that is not SMS-managed, it uses special SMS construct names: SMS Construct Data Class Storage Class Storage Group Value X0CAB2NC SAMSALSC SAMSALSG Do not define these SMS constructs names to your SMS configuration. All batch jobs, started tasks, and TSO users must have security package authorization to use these SMS constructs. If you want, you can customize these names. Set the PLSSC and PLSSG parameter values to the other unique storage class and storage group names. The previous table indicates the default values. New Logic Required in the ACS Environment CA Allocate DASD Space and Placement can operate on allocations that DFSMShsm performs during RECALL and RECOVER. Set the &STORCLAS variable to the PLSSC parameter value in the ACS environment. This setting tells CA Allocate DASD Space and Placement to manage the allocation. Failing to do so lets the allocation proceed as if CA Allocate DASD Space and Placement were not installed. IF &VAMENVIR = 'ACS' THEN DO IF &HSMFUNC = 'RECALL' OR &HSMFUNC = 'RECOVER' THEN DO IF &STORCLAS = '' THEN DO SET &STORCLAS = 'SAMSALSC' END END END Data Set Names Generated by DFSMShsm During MIGRATE and BACKUP DFSMShsm allocates non-vsam data sets for MIGRATE and BACKUP with names of the following form: prefix.function.thhmmss.dsnamefragment Where: Concepts and Facilities 91

92 prefix is installation-defined. function is BACKTAPE for BACKUP, HMIG for MIGRATE. Thhmmss is time of operation. dsnamefragment is a portion of the data set name. DFSMShsm During RECALL/RECOVER When DFSMShsm is the data mover during RECALL or RECOVER, it creates a temporary data set. The name has the following form: prefix.mdb.thhmmss.dsnamefragment Where: prefix is installation-defined. Thhmmss is time of operation. dsnamefragment is a portion of the data set name. DFSMShsm then moves the data into this temporary data set. When the data movement is completed, it renames the data set to the real name it is supposed to have. All these operations are visible to CA Allocate DASD Space and Placement. For example, for a non-vsam non-sms data set, CA Allocate DASD Space and Placement typically sees the following ASR environments: ACS for the real name ALLOC for the temporary name SPACE for the temporary name EXTEND for the temporary name during data movement RENAME during the rename from the temporary name to the real name ASR Variables for HSM RECALL and RECOVER Operations Like all DFSMShsm data set operations, RECALL and RECOVER occur in the DFSMShsm address space. Thus, CA Allocate DASD Space and Placement ASR variables &JOB, &USER, and &GROUP contain information about the DFSMShsm job, user, and group. Information for the requesting job, user, and group are provided in &HSMJOB, &HSMUSER, and &HSMGROUP, respectively. During a DFSMShsm RECALL or RECOVER when DFSMShsm is the data mover, a temporary data set is allocated. The data is moved, and then the data set is renamed to the real name. Because the original allocation occurs using the temporary name, CA Allocate DASD Space and Placement ASR variables in the ALLOC, SPACE, and EXTEND environments contain information about that name. Special variables are available for DFSMShsm RECALL and RECOVER operations to provide information about the real data set. Concepts and Facilities 92

93 The following variables are used during a DFSMShsm RECALL or RECOVER when DFSMShsm is the data mover: &DSN Indicates the data set name (temporary name). &LLQ Indicates the low-level qualifier (temporary name). &HLQ Indicates the high level qualifier (temporary name). &NQUAL Indicates the number of qualifiers (temporary name). &JOB Indicates the job name for HSM address space. &USER Indicates the user name for HSM address space. &GROUP Indicates the group name for HSM address space. &HSMDSN Indicates the data set name (real name). &HSMLLQ Indicates the low-level qualifier (real name). &HSMHLQ Indicates the high level qualifier (real name). &HSMJOB Indicates the job name of requesting job. &HSMUSER Indicates the user name for requesting job. &HSMGROUP Indicates the group name for requesting job. During a DFSMShsm RECALL or RECOVER when DFSMSdss is the data mover, no temporary name is created. All data set operations occur using the real data set name. For consistency, the special-purpose &hsmxxx variable names contain the following appropriate values that match their corresponding normal variable values. &DSN Indicates the data set name (real name). &LLQ Indicates the low-level qualifier (real name). &HLQ Indicates the hgh level qualifier (real name). &NQUAL Indicates the number of qualifiers (real name). &JOB Indicates the job name for HSM address space. Concepts and Facilities 93

94 &USER Indicates the user name for HSM address space. &GROUP Indicates the group name for HSM address space. &HSMFUNC Indicates the HSM function name: 'RECALL' or 'RECOVER'. &HSMDSN Indicates the data set name (real name). &HSMLLQ Indicates the low-level qualifier (real name). &HSMHLQ Indicates the high level qualifier (real name). &HSMJOB Indicates the job name of requesting job. &HSMUSER Indicates the user name for requesting job. &HSMGROUP Indicates the group name for requesting job. For more information about all these variables, see the section ASR Variables 15. The DFSMShsm RECALL Exit (ARCRDEXT) Installations currently running a DFSMShsm RECALL exit (module ARCRDEXT) must take some special care regarding the following items: A volume selected by overrides any volume that the RECALL exit selects. CA Allocate DASD Space and Placement is a better and complete way to control DFSMShsm allocations because it intercepts all requests and can redirect them to any volume. The DFSMShsm RECALL exit only intercepts nonspecific RECALL requests, ignoring those requests with a specified volume (directed RECALLs). The DFSMShsm RECALL exit is restricted to the subset of volumes that DFSMShsm gives it to select from. Control Only RECALL and RECOVER Operations An installation can operate only on DFSMShsm allocations that are done for RECALL and RECOVER operations and can leave MIGRATE and BACKUP alone. To stop CA Allocate DASD Space and Placement from controlling BACKUP and MIGRATION allocations, add the following statement to the beginning of your ASR: IF &DSN(2) = 'BACK' OR &DSN(2) = 'HMIG' THEN EXIT CODE(0) 15 Concepts and Facilities 94

95 Important! CA Allocate DASD Space and Placement redirects a DFSMShsm migration data set to any volume the ASR decides, and the MIGRATE works. However, if the volume is not defined to DFSMShsm as a migration volume, any subsequent recall fails with the following messages: ARC1010I SYSTEM ACTION AGAINST A MIGRATED DATA SET FAILED ARC1001I data.set.name RECALL FAILED, RC=0003, REAS=0008 ARC1103I MIGRATION/BACKUP/DUMP VOLUME NOT AVAILABLE If this problem occurs, you can define the volume as a migration volume. Follow these steps: 1. If the volume is defined to DFSMShsm as a PRIMARY or BACKUP volume, issue the DFSMShsm DELVOL command to remove the volume from DFSMShsm. 2. Issue the DFSMShsm ADDVOL command to define the volume to DFSMShsm as a MIGRATION volume. Any recalls against the migration data set now work. FDR Support CA Allocate DASD Space and Placement has a feature that allows the user to redirect data set allocations that are associated with the following Innovation FDR commands: FDRCOPY COPY and MOVE FDRDSF RESTORE To accomplish this, CA Allocate DASD Space and Placement invokes an FDR documented interface to control which volumes to use for these allocations. This API passes information about the current data set back and forth between FDR and CA Allocate DASD Space and Placement. This information is used to determine which volume to use. Note: Installation instructions are located in Override the Default Value of Sysparms (see page 108). When this support is activated, the following variables are available as INPUT in the ALLOC environment: &ACCT_JOB &IFALREADYCAT &LSPACE_PCTAFT_CYL &PROCSTEP &ACCT_STEP &IFALREADYCATVOL &LSPACE_PCTAFT_CYLNOT &PROGRAM &ALLVOL &JOB &LSPACE_PCTAFT_MB &SECONDARY &ANYVOL &JOBCLASS &LSPACE_PCTAFT_MBNOT &SPACTYPE &AVGBLK &LARGEST_EXTCYL &LSPACE_PCTAFT_TRK &STEPNAME &CONTIG &LARGEST_EXTCYL_NOT &LSPACE_PCTAFT_TRKNOT &SYSID &DISP &LARGEST_EXTMB &LSPACE_RETURN_CODE &TIME &DSN &LARGEST_EXTMB_NOT &MODULE &UNIT &DSORG &LARGEST_EXTTRK &NQUAL &VAMENVIR &DSTYPE &LARGEST_EXTTRK_NOT &NVOL &VAMRLSE &GROUP &LLQ &PGMRNAME &XMODE &HLQ &LSPACE_FREESPACE &PRIMARY Also, the following variables are available as OUTPUT in the ALLOC environment: Concepts and Facilities 95

96 &C0 - &C40 &LSPACE_STORGRP &LSPACE_VOLUME &N0 - &N40 &POOLSUB &STORGRP Limitations CA Allocate DASD Space and Placement is subject to any limitations imposed by FDR. The following list shows the known limitations: SMS-managed data sets are not supported. Redirecting a data set to the original source volume is not permitted. Fragmented data sets that have out of order extents cannot be moved to a smaller device type. RESTOREing from a 3390 device to a 3380 device is an FDR limitation. The following sample ASR statements show how to incorporate this FDR support into your environment. File Edit Confirm Menu Utilities Compilers Test Help EDIT.ASR.PARMLIB(FDR) Columns Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = ALLOC THEN DO IF &FDR = Y THEN DO SET &UNIT = SYSALLDA SET &LSPACE_STORGRP = SMALL IF &LSPACE_RETURN_CODE = 0 THEN DO IF &SPACTYPE = TRK AND IF &PRIMARY < &LARGEST_EXTTRK THEN SET &STORGRP = SMALL ELSE IF &SPACTYPE = CYL AND IF &PRIMARY < &LARGEST_EXTCYL THEN SET &STORGRP = SMALL ELSE SET &STORGRP = LARGE END END END The following illustration is a sample ASR for multivolume VSAM: IF &VAMENVIR = ALLOC THEN IF &FDR = 'Y' THEN DO IF &DSORG = 'VS' THEN /* <<< VSAM file <<<<< */ SET &SG = 'FDRVSAM' IF &DSORG = 'PS' THEN /* <<< non-vsam file <<<<< */ SET &SG = 'FDRNVSAM' END Concepts and Facilities 96

97 Space Type Conversions CA Allocate DASD Space and Placement has a feature that allows the original space allocation unit and quantity to be altered. This altering can be done for non-vsam allocations and either at the cluster or component level for VSAM ones. A space type conversion can involve up to as many as ten variables. All Non-VSAM and all VSAM AVGBLK AVGRECSIZE AVGRECTYPE BLKSIZE OPTBLK SPACCVT Non-VSAM and VSAM Clusters PRIMARY SECONDARYD SPACTYPED UNITTYPED VSAM Data Components PRIMARYD SECONDARYD SPACTYPED UNITTYPED VSAM Index Components PRIMARYI SECONDARYI SPACTYPEI UNITTYPEI The values in the AVGRECTYPE, AVGRECSIZE, AVGBLK, BLKSIZE, OPTBLK, UNITTYPE, UNITTYPED, and UNITTYPEI variables are not changed. Their values, and the value of the SPACTYPE, SPACTYPED, and SPACTYPEI variables, have an impact. They affect how the variables dealing with the primary and secondary allocation quantities (PRIMARY, PRIMARYD, PRIMARYI, SECONDARY, SECONDARYD, and SECONDARYI) are modified. The remainder of this section contains a general overview of how and why space type conversions are done. For more information about each of the preceding variables and examples on how each one participates in a space type conversion, see ASR Variables 16. Allocation requests can be made in units of tracks, cylinders, blocks, average records, and sometimes kilobytes or megabytes. Disk devices have different storage capacities. Storage Administrators want to use available disk space efficiently. Efficient usage is often made easier by converting various allocation units to one standard. For example, a primary allocation quantity of ten, without knowing whether it is in blocks, tracks, or cylinders, does not give the Allocation Selection Routine enough information to make a pooling decision that is based on the actual number of bytes requested. The following statements let the ASR make pooling decisions that are based on the actual amount of space being requested Concepts and Facilities 97

98 File Edit Confirm Menu Utilities Compilers Test Help EDIT.ASR.PARMLIB(POOLDESC) Columns Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* SET &UNITTYPE = '3390' SET &SPACTYPE = 'TRK' SET &PRIIMARY = &PRIMARY SET &SECONDARY = &SECONDARY SET &N0 = (( &PRIMARY ) + (&SECONDARY = 15)) IF &N0 > 100 THEN SET &STORGRP = 'LARGE' ELSE IF &N0 > 25 THEN SET &STORGRP = 'MEDIUM' ELSE IF &NO > 5 THEN SET &STORGRP = 'SMALL' ELSE SET &STORGRP = 'TINY' The preceding ASR code initiates a real-time conversion of whatever the original allocation unit was (that is, BLK, CYL, and so on) to the equivalent number of 3390 tracks. This conversion is the default action of the SPACCVT variable ('Y': do the space type conversion). Note: To convert to BLK, a BLKSIZE must be available. If no BLKSIZE is specified, the conversion is to the appropriate allocation in TRK, which causes space to be released on track boundaries as expected. In this case, TRK allocations are unchanged and CYL is converted to TRK. Sometimes, the Storage Administrator wants to set both the allocation unit and quantity to a fixed amount. When conversion is not required, set the value of the SPACCVT variable to 'N'. The following ASR code converts all temporary data set allocation requests to SPACE=(TRK,(25,25)). IF &DSTYPE = 'TEMP' THEN DO SET &SPACCVT = 'N' SET &SPACTYPE = 'TRK' SET &PRIMARY = 25 SET &SECONDARY = 25 END LSPACE Support for Primary and Secondary Allocation LSPACE support allows the Storage Administrator the opportunity to reduce primary or secondary space allocations to avoid X-37 type abends. The LSPACE function calculates the amount of space in the five largest extents (depending on the current number of extents) in one of the following allocation types: Concepts and Facilities 98

99 Cylinders Megabytes Tracks The ASR writer can determine whether the current allocation fits on the target volume. If "CONTIGUOUS" is specified in the non-vsam allocation, LSPACE returns the size of the largest extent. To support this function, several ASR variables are available within the ALLOC, DEFINE, EOV, EOV_VSAM, and EXTEND environments. The following table is a list of these variables. Variable Name &LARGEST_EXTCYL &LARGEST_EXTCYL_NOT &LSPACE_PCTAFT_CYLNOT &LSPACE_PCTAFT_MB &LARGEST_EXTMB &LARGEST_EXTMB_NOT &LARGEST_EXTTRK &LARGEST_EXTTRK_NOT &LSPACE_FREESPACE &LSPACE_PCTAFT_CYL &LSPACE_PCTAFT_MBNOT &LSPACE_PCTAFT_TRK &LSPACE_PCTAFT_TRKNOT &LSPACE_RETURN_CODE &LSPACE_STORGRP &LSPACE_VOLUME Alias &LEC &LECN &LPACN &LPAM &LEMB &LEMBN &LET &LETN &LFF &LPAC &LPAMN &LPAT &LPATN &LRC &LS &LV Note: LSPACE processing is available at the storage group or volume level. The following ASR statements are illustrations of each: Concepts and Facilities 99

100 SET &LV = 'vvvvvv' /* <<== volser */ SET &LS = 'ssssss' /* <<== storage group */ More information: Options (see page 100) How Other Variables Can Affect the Process (see page 101) Special Notes for LSPACE Processing (see page 102) Options Many options are available within the LSPACE function, and depending upon which CA Allocate DASD Space and Placement environment is active. The Storage Administrator must consider the following items before implementing this support: In the ACS environment, only the &LSPACE_VOLUME variable is allowed because the only LSPACE support available during ACS is to decide whether to remove the Guaranteed Space attribute. This decision depends on the space available on the current volume, not in the storage group as a whole. In the ALLOC and DEFINE environments, either the &LSPACE_VOLUME or the &LSPACE_STORGRP variables are allowed. Use the &LSPACE_VOLUME variable for either SMSmanaged allocations specifying the Guaranteed Space attribute, or for non-sms-managed specific volume requests that CA Allocate DASD Space and Placement is not redirecting. Use the &LSPACE_STORGRP variable whenever CA Allocate DASD Space and Placement is planning to redirect a non-sms-managed allocation or when an SMS-managed allocation has not been requested with the Guaranteed Space CA Allocate DASD Space and Placement attribute. The following items apply: To intercept SMS-managed data set allocations in the ALLOC and DEFINE environments, specify PLSOPT10(Y) in the VKGPARMS parmlib member. For more information about PLSOPT10, see the section PLSOPTnn Sysparms (see page 126). Before querying the &GUARANTEED_SPACE(&GSA) variable, ensure that the data set is SMS-managed. You can do this checking with the following statement: IF & SMS_MANAGED='Y' In the EOV and EOV_VSAM environments, only the &LSPACE_STORGRP variable can be used because it is too late for further processing on the current volume and the new volume is not yet known. In the EXTEND environment, only the &LSPACE_VOLUME variable is allowed because volume selection cannot be changed. After the &LSPACE_VOLUME or &LSPACE_STORGRP variables are set and one of the other variables is queried, the actual LSPACE process is performed. The &LFF variable is a flag that is set when the Freespace Threshold is violated. The flag only applies when a storage group (not a volume) is being processed. After the LSPACE process is complete, if &LSPACE_RETURN_CODE contains a nonzero return code, some or all the other variables might be invalid. If &LSPACE_RETURN_CODE is zero, all of Concepts and Facilities 100

101 the other variables were set to valid values. For more information, see the variable description for LSPACE_RETURN_CODE 17. The contents of &LEC, &LEMB, and &LET is the largest possible extents in cylinders, megabytes, and tracks respectively. What is the difference? Assume that a storage group has two volumes, a 3390 and a Also, assume that the 3390 has 140 available tracks, and a 3380 has 150 available tracks. The contents of &LET is 150 which is 6MB of data (7,121,400 bytes = 150 tracks * 47,476 bytes/track), but &LEMB contains 7 (7,932,960 bytes = 140 tracks * 56,664 bytes/track). &LPAC, &LPAM, and &LPAT contains the freespace percent after the allocation, assuming the &LEC, &LEMB, and &LET values were used respectively. &LFF is set to 'Y' when the values of the &LEC, &LEMB, and &LET variables reflect that the free space threshold has been violated. When &LFF= 'Y', then &LECN, &LETN, and &LEMN all have a value of zero. When &LFF= 'N', then &LECN, &LEMBN, and &LETN contain the largest possible extents in cylinders, megabytes, and tracks that would not violate the free space threshold. &LPACN, &LPAMN, and &LPAT contain the free space percent after the allocation, assuming the &LECN, &LEMBN, and &LETN values were used respectively. &LFF, &LPACN, &LPAMN, and &LPATN variables only have meaning for non-sms-managed allocations. How Other Variables Can Affect the Process Some variables can alter the LSPACE process. The following list includes the variables and the role they play: &UNIT CA Allocate DASD Space and Placement only picks a volume from a storage group if that volume belongs to &UNIT. For example, assume that a job allocates a data set with UNIT=3390. Also assume that MIXED is a CA Allocate DASD Space and Placement storage group with a mixture of 3380 and 3390 devices. The LSPACE process only examines the '3390' volumes. &GSA Guaranteed Space is only applicable to specific volume requests for SMS-managed allocations that are associated with a storage class specifying this attribute. The SMS volume selection routines fail such allocations when the target volume does not have sufficient free space. CA Allocate DASD Space and Placement offers the following choices in such cases: Change the storage glass to one without guaranteed space. Reduce the primary allocation amount to the largest available amount that the LSPACE LV process retrieves. Storage class changes must be done in the ACS environment. Changing the primary allocation amount must be done in either the ALLOC or DEFINE environment. Note: Before querying the &GUARANTEED_SPACE (&GSA) variable, ensure that the data set is SMS-managed. Use the following statement: IF & SMS_MANAGED='Y' 17 Concepts and Facilities 101

102 &CONTIG Under most circumstances, DADSM breaks an extent request into as many as five extents. The LSPACE process sums the five largest extents. However, if the allocation requires contiguous space, only the single largest extent is considered. This process is applicable to non-vsam only. &EXTENTS Under most circumstances, DADSM breaks an extent request into as many as five extents. Non- VSAM data sets can only have 16 extents to a volume. If an EXTEND of a non-vsam data set is being processed and the data set is already in more than 11 extents, DADSM cannot supply this secondary allocation in 5 extents. Therefore, if extents are greater than 11, then the N largest extents is used where N = 16-&EXTENTS. &POOLSUB In the volume selection environments (that is, ALLOC, DEFINE, EOV, and EOV_VSAM) the &POOLSUB variable allows an automatic storage group selection process. Because many sites use this feature, it might not be efficient to SET &LSPACE_STORGRP to a storage group name. Therefore, after &POOLSUB has been set to Y, then &LSPACE_STORGRP is set to the first storage group that &POOLSUB finds. For more information, see the variable description for POOLSUB 18. Special Notes for LSPACE Processing The following items are the special notes for LSPACE processing: LSPACE processing can be thought of as a picture of a volume at a particular point in time. Nothing ensures that the free space available at the time the LSPACE was issued is available for allocation. However, the time frame from when CA Allocate DASD Space and Placement does the LSPACE and the time the allocation is made is relatively small, so the space is likely to be available. LSPACE processing requires I/O and causes extra overhead when being used. When doing LSPACE processing for a storage group, all VTOCs within the storage group must be read before any variables can be returned to the ASR. As the number of volumes within the storage group grows, so does the overhead that is involved in obtaining the required information. VSAM space allocations are sometimes rounded up from the initial request. One example is when the request is for a KSDS data set and space is requested for the data component but not the index. To prevent some allocations from failing, the ASR writer might not want to use the entire &LEC, &LET, OR &LEMB value. No unique &LRC value is directly associated with an SG having exceeded its free space threshold but there is an indirect one. LSPACE support generates values for 12 numeric variables: &LEC, &LECN, &LET, &LETN, &LEMB, &LEMBN, &LPAC, &LPACN, &LPAT, &LPATN, &LPAM, &LPAMN. This generation means that if the value of any one of these variables is zero, the &LRC value is 4. The following illustrations have sample ASR code showing the LSPACE support: Sample LSPACE ASR, Part Concepts and Facilities 102

103 IF &VAMENVIR = 'ACS' THEN IF &SMS_MANAGED = 'Y' THEN DO IF &GSA ='Y' THEN /* GUARANTEED SPACE MUST USE THE */ SET &LV = &ALLVOL /* TARGET VOLUME FOR LSPACE */ END IF &VAMENVIR = 'ALLOC' OR &VAMENVIR = 'DEFINE' THEN DO IF &SMS_MANAGED = 'Y' THEN DO IF &GSA = 'Y' THEN /* GUARANTEED SPACE NEEDS */ SET &LV = &ALLVOL /* LSPACE LV PROCESSING */ ELSE SET &LS = &SG /* LSPACE FOR DFSMS STORGROUP */ END IF &SMS_MANAGED = 'N' THEN SET &LS = 'DASD80' /* NONSMS NEEDS THE ALLOCATE SG */ END Sample LSPACE ASR, Part 2 IF &LRC = 0 THEN /* INVOCATION OF THE LSPACE PROCESS */ DO IF &SPACTYPE = 'CYL' OR /* CYLINDERS? */ &SPACTYPED = 'CYL' OR &SPACTYPEI = 'CYL' THEN DO IF &VAMENVIR = 'EXTEND' OR &VAMENVIR = 'EOV' THEN /* INCREASE TO REDUCE DATA SET FRAGMENTATION OR... */ DO /* REDUCE TO PREVENT SPACE-NOT-AVAILABLE FAILURE */ IF &SECONDARY > 0 THEN SET &SECONDARY = &LEC IF &SECONDARYD > 0 THEN SET &SECONDARYD = &LEC IF &SECONDARYI > 0 THEN SET &SECONDARYI = &LEC END COPYBOOK 'LSPACE#3' /* FOR ACS, ALLOC, DEFINE, EOV_VSAM */ END END Sample LSPACE ASR, Part 3 IF &VAMENVIR = 'ACS' THEN IF &SMS_MANAGED = 'Y' THEN IF &GSA = 'Y' /* FOR GUARANTEED SPACE */ AND &HLQ = 'PROD' THEN /* WITH THESE DATA SETS */ Message Control Facility CA Allocate DASD Space and Placement issues messages at many different points to inform you of its actions. Some messages may seem unnecessary or only appropriate for specific individuals responsible for storage management. The Message Control Facility (MCF) lets you discard these messages or direct them to a specific user or MVS console routing code. You direct the MCF by creating a message preprocessing table using assembler macro specifications that you assemble and link with CA Allocate DASD Space and Placement. You can redirect most messages using the MCF. Some exceptions follow: Concepts and Facilities 103

104 Messages issued during the installation and removal of the Operating System Interfaces, either before the MCF itself has been initialized or after it has been shut down. Any message issued directly through the IBM WTO macro. This exception applies to only a small percentage of messages. The following diagram illustrates MCF: After implementation, the message control facility is active for all allocations. MCF can be temporarily deactivated in any job step by adding the VDSDIAGS DD statement or by allocating it to your TSO session. The VDSDIAGS DD statement in TSO or batch JCL causes all messages to be displayed in a normal manner. To use a different ddname for this purpose, specify the DEBUGDD= keyword on the SCANBEG macro. More information: Macro Definitions (see page 105) Keyword Operands (see page 105) Message Control Facility Example Specifications (see page 107) Assembling and Linking Message Control Specifications (see page 107) Concepts and Facilities 104

105 Macro Definitions Three macros, SCANBEG, SCANSTR, and SCANEND, define the message processing specifications. Except for the optional DEBUGDD= keyword of SCANBEG, the SCANSTR macro defines all specifications. SCANBEG is specified one time at the start of the member, and SCANEND is specified at the end. Descriptions of each macro follow: SCANBEG DEBUGDD=VDSDIAGS SCANBEG begins the start of the table. This instance must be the first and only instance of this macro within the assembly. Its optional operand (DEBUGDD=) defines the ddname that is used to bypass the message processing facility. If DEBUGDD is not specified, 'VDSDIAGS' is assumed. SCANSTR 'string', OPTIONS=(SUPPRESS,ONLYJCL,ONLYTSO,FORCEWTO,WAIT,JESLOG,VANKEY,VANTLOG), NOTIFY=userID, ROUTCDE(n,n,n), DESC=n SCANSTR defines a search string that is used to select messages for direction. Any number of separate SCANSTR statements can be specified. The message text of each message that is issued is compared to the search string. Messages matching the text specification are processed according to the parameters specified on the SCANSTR statement. There is one positional operand and several keyword parameters as follows: The positional operand defines the string that is used to identify messages that the keyword parameters apply to Patterns can be specified with the following characters '*' or '%' '*' meaning any number of preceding or trailing characters match '%' meaning any character in this position matches Keyword Operands The following keyword operands are described in this section: OPTIONS=(...,...) (see page 106) NOTIFY= (see page 106) ROUTCDE= (see page 106) Concepts and Facilities 105

106 DESC= (see page 106) OPTIONS=(...,...) Any combination of: SUPPRESS Discard the message. The message is not displayed. ONLYJCL Issue the message for batch jobs only. TSO users do not receive messages that are associated with this parameter. ONLYTSO Issue the message only when processing a TSO allocation request. Batch jobs do not receive messages that are associated with this parameter. FORCEWTO Write a copy of the message to the MVS operator console. WAIT Wait for messages that are issued to TSO to be placed in the terminal output buffer. If no buffers are available, the program is placed into a wait state until buffers become available and the output line is placed in them. CA Allocate DASD Space and Placement typically does not wait for messages. JESLOG Do not write the message to the operator console. The message is written to the job log and appears only in the user output. VANTKEY Send messages to the TSO userid of the CA Vantage user who is logged in to the SMS Plus GUI. VANTLOG Send the message to the CA Vantage log. NOTIFY= Send messages directly to the TSO USERID specified on this parameter. ROUTCDE= Write messages to the destination assigned to the route code specified on this parameter. For more information, see the IBM Supervisor Services and Macro Instructions documentation for the WTO macro to know more about the ROUTCDE parameter. DESC= In addition to a ROUTCDE for directing messages to consoles, you may also provide descriptor codes. These codes will be provided to the system Write To Operator facility. Refer to the IBM Supervisor Services and Macro Instructions (WTO macro) for more information about proper values for the DESC parameter. Concepts and Facilities 106

107 SCANEND End the table; it must be the last statement in this program. The SCANEND macro has no operands. Message Control Facility Example Specifications You can find sample specifications for the MCF in member VDSWTOI in the CCTVSAMP target library of your SMP/E Zone. Assembling and Linking Message Control Specifications You can find the JCL to assemble, link, and install the MCF changes in member WTOSMP in the CCTVJCL target library of your SMP/E Zone. When run, the job links your Message Control Specifications with each component of CA Allocate DASD Space and Placement. These specifications take effect with the next start-up of CA Allocate DASD Space and Placement. A REFRESH does not cause these specifications to take effect! REFRESH only implements ASR and pool definition changes. You must stop and start CA Allocate DASD Space and Placement for these specifications to take effect. Concepts and Facilities 107

108 Implementation Implementation topics describe how to use the product to enforce allocation standards and to monitor and optionally enforce allocation limits. Several sets of installation-defined parameters are used to accomplish these objectives. The parameters are members of the following partitioned data sets: Quota Configuration File (member QCONFIG) Quota Table Rebuild ASR (member QREBUILD) VTOC Scan ASR (member QSCAN) Data set Allocation Selection Routine (member VDSPROG) Storage Group (Pool) definitions (member VDSTORGP) Operations specifications definition (member VKGPARMS) More information: Override the Default Value of Sysparms (see page 108) Multiple Systems - Parmlib Considerations (see page 141) Use Pattern Matching Characters (see page 143) Create a Storage Group Definition (see page 144) Create a Key Data Set Names Member (see page 147) Create an Allocation Selection Routine (see page 147) Create an Exclude Jobs Names Member (see page 162) Override the Default Value of Sysparms You can override the default values of the system parameters that are used to customize CA Allocate DASD Space and Placement in the sysparm override member. The member is in the data set that the PARMS DD statement references in the JCL used for the operating system interfaces of this product. The default name of the override member is VKGPARMS. For descriptions of the sysparms, see SUPLS Sysparms (see page 109) PLS Sysparms (see page 109) PLSOPTnn Sysparms (see page 126) All system parameters must begin in column 1. If a column 1 is empty, the associated record is ignored. An example showing how to override the default value of a sysparm is in the SAMPVKGP member in the CCTVJCL target library of your SMP/E Zone. Implementation 108

109 The PARMREF modify command can change the sysparms after CA Allocate DASD Space and Placement has installed its operating system interfaces. You cannot refresh all sysparms with the PARMREF modify command. Each parameter is described in the following topics. They provide the valid values, default values, and whether you can update the parameter using the PARMREF option. SUPLS Sysparms Contact CA Technologies to get the license keys for these options. After you apply the license keys, you can implement these instructions, as you are licensed for the option. SUPLS Valid Values: (N) default, (Y) PARMREF: No If you are licensed to run the SMS Plus selectable unit of CA Vantage, specify (Y) to activate this functionality. SUPLSNV Valid Values: (N) default, (Y) PARMREF: No If you are licensed to run the Allocation Manager selectable unit of CA Allocate DASD Space and Placement, specify (Y) to activate this functionality. SUPLSQ Valid Values: (N) default, (Y) PARMREF: No If you are licensed to run the Quota selectable unit of CA Allocate DASD Space and Placement, specify (Y) to activate this functionality. PLS Sysparms The PLS Sysparms are divided into the following parts: PLS451 - PLSDRMNT (see page 109) PLSENQDS - PLSKBYTE (see page 113) PLSLALLO - PLSOLDNU (see page 118) PLSOPEN - PLSV37BY (see page 121) PLSVDSMB - PLSZSEC (see page 124) PLS451 - PLSDRMNT PLS451 Valid Values: (Y) default, (N) PARMREF: No The PLS451 parameter controls the installation of an optional intercept point that is used with the following features: JES3 tape support, which is also associated with parameter PLSJES3. Implementation 109

110 Redirecting new, non-sms, non-vsam data sets in the ALLOC environment. Retrieving the RECORG information that is associated with a new VSAM data set in the ALLOC environment. Retreiving information for BLKSIZE in the ALLOC environment. PLS451 is also associated with parameter PLSACS. PLS453 Valid Values: (Y) default, (N) PARMREF: No The PLS453 parameter is used to determine whether to install the operating system interface at IEFAB453. A value of (Y) for PLS453 is required to take advantage of the features available in the OLD environment. PLSACS Valid Values: (Y) default, (N) PARMREF: No This parameter indicates whether the CA Allocate DASD Space and Placement ACS environment operating system interface to the IBM DFSMS subsystem is installed. The default value of (Y) ensures that the ACS environment is available on any operating system running IBM DFSMS subsystem. Overriding the default value with (N) in the VKGPARMS parmlib member completely disables the ACS environment. Availability of the RECORG variable in the ALLOC environment is contingent on CA Allocate DASD Space and Placement having been installed with PLSACS (Y). For more information about RECORG, see ASR Variables 19. PLSACTN Valid Values: (INSTALL) default Specifies the action the CA Allocate DASD Space and Placement started task takes, described in the PLSSTCN parameter. PLSALLBO Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 002 is activated. For more information, see Legacy Optional Features (see page 220). PLSALLDA Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 092 is activated. For more information, see Legacy Optional Features (see page 220). PLSALLNS Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 025 is activated. For more information, see Lega 19 Implementation 110

111 cy Optional Features (see page 220). PLSALLNT Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 070 is activated. For more information, see Legacy Optional Features (see page 220). PLSALLPS Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 106 is activated. For more information, see Legacy Optional Features (see page 220). PLSALLPV Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 001 is activated. For more information, see Legacy Optional Features (see page 220). PLSALLSC Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 003 activates. This optional feature allows Volume-Level security checking to be done during the CA Allocate DASD Space and Placement non-vsam volume selection process. This optional feature calls to the security system to see whether the user is authorized to create a data set on a particular volume. This checking means that: On CA Top Secret for z/os systems, at least Allocate Authority on the volume On CA Top Secret systems, at least Create Authority for the DASDVOL class On RACF systems, at least Update Authority for the DASDVOL class If the security system reports that the user does not have the authority to create a data set, that volume is excluded from the volume selection process. PLSALLVL Valid Values: (1) default, (2), (3), (4) The default value can be overridden using the ALIASLVL= operator command. Specifies what MVS ALIASLVL to use. This option is only used in installations using the MVS/ESA Multi-Level Alias (MLA) facility. PLSARCVL Valid Values: (ARCIVE) default, name of archive pseudo volume, or blanks PLSARCVL is used to communicate to CA Allocate DASD Space and Placement the name of the archive pseudo volume that CA Disk uses. You can find the name in the value that is specified for the CA Disk sysparm RECATVOL. The default value for both sysparms is ARCIVE. If you are not running CA Disk at your installation, specifying a value of PLSARCVL ( ) in your sysparm override member saves CPU cycles. This information is used during criteria screening for eligibility for both the OLD and PREALLOC Implementation 111

112 environments. The information is also used with the ARCIVED, DELETE_NOSCRATCH, and DELETE_NOSCRATCH_RC variables that are associated with DELETE NOSCRATCH support. Notes: For more information about the DELETE NOSCRATCH support, see PREALLOC Environment (see page 45). For more information about the ARCIVED, DELETE_NOSCRATCH, and DELETE_NOSCRATCH_RC variables, see ASR Variables 20. PLSBYPAS Valid Values: (VDSBYPAS) default Specifies the DDname that is used to inactivate in a job step all CA Allocate DASD Space and Placement features except for features that are associated with the optional Quota selectable unit. If you want to inactivate an entire job, then either add the special bypass DDname to every step in the job or the job name to the optional EXCLJOB table. PLSDCEOV Valid Values: (N) default, (Y) Activates EOV (end-of-volume) support for CA DATACOM databases. PLSDDEVT Valid Values: No default value, (3380) or (3390), but only to a valid unit type Specifies the default device that CA Allocate DASD Space and Placement uses internally. No is the default value. CA Allocate DASD Space and Placement uses a varying number of device types. See also the descriptions of the SIZE, SIZEKB, SIZEMB, and UNITTYPE variables. PLSDIAGS Valid Values: ( ) default Specifies a jobname for the internal diagnostics that help diagnose a suspected problem with this product. No special DDNames are required to activate this diagnostic tracing. You can temporarily override the default value using the DIAGS= operator command (see page 171). To turn on diagnostic tracing (see page 218) in multiple jobs, you can use pattern masking characters in place of an explicit jobname. A large volume of diagnostics is likely to be generated. Running with PLSOPT98 (Y) confines these diagnostics to a single section of the JES Listing of the failing job. If you use the default value of (N) for PLSOPT98, the diagnostics is issued twice to the JES Listing and once to the SYSLOG. If you are running with PLSOPT98 (N) and you are turning on diagnostic tracing for an explicit jobname, consider changing to PLSOPT98(Y). The messages that CA Allocate DASD Space and Placement issues are confined to a single place in the job log. Any messages that the system issues when the diagnostic tracing is turned on using pattern masking characters are issued as if PLSOPT98 (Y) was also active. PLSDQTDS Valid Values: (VAM.DISKQTBL) default PARMREF: No Specifies the name of the physical sequential data set that contains the Disk Quota Table. This 20 Implementation 112

113 data set is used only if the SUPLSQ is (Y) and can be overridden by adding the DISKQTBL DD to the CA Allocate DASD Space and Placement started task. If your site is not licensed for the Quota feature, this parameter is meaningless. PLSDRMNT Valid Values: (#VAMTST#) default Specifies the DDname that is used to make CA Allocate DASD Space and Placement process when in dormant state (as described in the PLSMODE parameter). PLSENQDS - PLSKBYTE PLSENQDS Valid Values: (VAM.ENQ.DATA.SET) default If PLSOPT1 is set to Y, this parameter specifies the data set name that is used to serialize CA Allocate DASD Space and Placement termination process with CA Disk Auto-Restore jobs. The value set for this parameter is that of a dsname. Select an unused model data set and reference it in the DMSAR proc as follows: //anydd DD DSN=plsenqds.dsname,DISP=SHR Warning! CA Allocate DASD Space and Placement issues an exclusive SYSDSN ENQ to this data set. If the dsname you select is a real data set, ensure that this enqueue does not cause a resource lockout. Activating this facility instructs CA Allocate DASD Space and Placement to remove its system hooks in a serialized manner. This action prevents possible S0C4 abends from occurring within CA Disk Auto Restores. When this facility is activated and CA Allocate DASD Space and Placement is removed from the system, the following actions occur, as needed for each SVC 26 hook: Implementation 113

114 a. CA Allocate DASD Space and Placement determines whether a DMSAR STC is active before freeing the storage of each of the two SVC26 SVC intercepts. b. If a DMSAR is active, CA Allocate DASD Space and Placement issues a WTOR to the system console. The WTOR lets you wait for the DMSAR to complete. If you decide to wait, the value for PLSENQDS is enqueued to prevent any new DMSARs from initializing. Warning! A resource delay can possibly occur for an incoming DMSAR. The next DMSAR cannot completely initialize because of the SYSDSN ENQ held by CA Allocate DASD Space and Placement. If this situation occurs, the following options are available to you: c. When active DMSARs complete (or if none were active), CA Allocate DASD Space and Placement FREEMAINs the storage of the SVC hooks and continues removing the product. d. If you decide not to wait, CA Allocate DASD Space and Placement removes without FREEMAINing the storage that the SVC26 intercept points still occupy, and the IGDSSIRT intercept point. Doing so leaves up to 52 K not freed in noncontiguous extended CSA after the removal completes. This now obsolete storage is remembered and freed during the next INSTALL operation. PLSEOV65 Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 077 is activated. For more information, see Legacy Optional Features (see page 220). PLSEOV69 Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 081 is activated. For more information, see Legacy Optional Features (see page 220). PLSEXAMI Valid Values: (N) default, (Y) For more information, see the CA Auditor Interface (see page 16). When set to (Y), this system parameter activates the CA Auditor Interface. When running with 'PLSEXAMI (Y)', output from STATUS operations is augmented with a new message indicating that the interface has been activated: VAM0254 CA-Allocate IS RUNNING WITH AN ACTIVE CA Auditor INTERFACE Once activated, using PARMREF to change PLSEXAMI back to its default value of (N) only logically deactivates the interface. Complete physical deactivation requires an IPL. Inactivating a previously activated interface changes the text in the VAM0254 message that continues to be issued during STATUS operations to: VAM0254 CA-Allocate IS RUNNING WITH AN INACTIVE CA Auditor INTERFACE Implementation 114

115 PLSEXJOB Valid Values: (blank) default Specifies the name of a batch job, a started task, or a TSO User that is exempt from launch sysparms that can be in effect for all environments except for ACS and the QUOTA environments (QUOTA, QREBUILD, and QSCAN). Examples: PLSEXJOB(TESTJOB1) PLSEXJOB(VAM) PLSEXJOB(JOHNDOE) PLSF244I Valid Values: (N) default, (Y) When set to (Y), any volumes that are specified in the optional VOL=SER JCL parameter are checked to confirm that they are valid online volumes. If any invalid volumes are found, all volumes are removed to prevent the following JCL errors: IEF244I IEF877E IEF238D jobname stepname - UNABLE TO ALLOCATE 1 UNIT AT LEAST 1 OFFLINE UNIT(S) NEEDED. jobname NEEDS 1 UNIT(S) FOR stepname ddname FOR VOLUME vvvvvv OFFLINE, NOT ACCESSIBLE jobname - REPLY DEVICE NAME OR 'CANCEL'. PLSF244I (Y) only applies to the allocation requests specifying DISP=MOD. The parameter assumes that available volumes are on the system that is mounted with the storage or scratch attributes. When the data set name is a permanent one, the operating system seeks a storage volume. When the data set name is a temporary one, the operating system seeks a scratch volume. If your ASR directs CA Allocate DASD Space and Placement to select the volume, then it can use volumes that are mounted with either the private, storage, or scratch attributes. PLSGDGBA Valid Values: (N) default, (Y) PLSGDGBA controls whether DEFINE GENERATIONDATAGROUP (GDG) requests are intercepted in the DEFINE environment. Specifying a value of (Y) for PLSGDGBA before an INSTALL or PARMREF operation lets the DEFINE environment intercept the DEFINE GDG requests. During DEFINE environment launches: To add or remove the SCRATCH attribute from a DEFINE GDG request, use the SCRATCH_GDS_WHEN_UNCATLG variable. When the intercepted request is a DEFINE GDG, the DSTYPE variables have a value of GDG. For more information, see ASR Variables 21. PLSGENA2 Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 130 is activated Implementation 115

116 PLSGENAX Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 044 is activated. PLSGENLG Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 076 is activated. PLSGENRO Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 004 is activated. PLSGENST Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 066 is activated. PLSGENUI Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 009 is activated. PLSGENUN Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 015 is activated. PLSGSNOL Valid Values: (N) default, (Y) The OLD environment is normally restricted to cataloged data set names. When PLSGSNOL is set to (Y), the OLD environment will also accept allocations that do not specify a data set name. Example: //DD1 DD DISP=OLD, // UNIT=UNITNAME, // VOL=SER=GOODVL This type of DD is commonly required by system utility programs. In these allocations, the DSN appears as a system generated temporary data set name that is not cataloged. Setting PLSGSNOL to (Y) enables the old environment to update the value of &UNIT. The following sample ASR that checks whether the UNITMISMATCH is "?" or the UNIT value equals "ABCDA". If either match, then immediately SET the UNIT to "SYSALLDA". Implementation 116

117 IF &VAMENVIR = 'OLD' THEN DO WRITE 'ENVIRONMENT = &ENV' WRITE 'DSN = &DSN' WRITE 'UNIT = &UNIT' WRITE 'UMM = &UMM' IF &UMM = '?' OR &UNIT = 'ABCDA' THEN /* check for bogus unit name */ SET &UNIT = 'SYSALLDA' END EXIT CODE(0) PLSHSMVL Valid Values: (blanks) default or name of migrate pseudo volume PLSHSMVL is used to communicate to CA Allocate DASD Space and Placement the name of migrate pseudo volume that DFSMShsm uses. This information is used during criteria screening for PREALLOC environment eligibility. The information is also used with the MIGRATED, DELETE_NOSCRATCH, and DELETE_NOSCRATCH_RC variables that are uniquely associated with the DELETE NOSCRATCH support. Notes: For more information about the DELETE NOSCRATCH support, see PREALLOC Environment (see page 45). For more information about the MIGRATED, DELETE_NOSCRATCH, and DELETE_NOSCRATCH_RC variables, see ASR Variables 22. PLSJES3 Valid Values: (N) default, (Y) When redirecting TAPE allocations to DISK, JES3 does not free the tape device that JES3 originally reserved. JES3 SETUP reserves TAPE devices for every DD statement in the JOB that specifies a tape unit. Specifying (Y) ensures that unneeded tape devices are freed at step termination if they are not required later in the job. Note: Use this processing flag only in JES3 complexes. PLSKBYTE Valid Values: (1024) default, (1000) PARMREF: No Factor that is used internally in bytes => Kilobyte => Megabyte => Gigabyte => Terabyte => Petabyte quota calculations. Many software products use 1000 instead of 1024-in similar calculations. This option is provided for customers where consistency across products is more important than the loss of precision in the quota allocation statistics that result when 1000 is used Implementation 117

118 PLSLALLO - PLSOLDNU PLSLALLO Valid Values: (Y) default, (N) PLSLALLO is a launch sysparm for the ALLOC environment. The default value of (Y) results in the ALLOC environment launching for applicable allocation requests. If you are not referencing the ALLOC environment in your ASR, you can override the launch sysparm to (N). This override logically disables ALLOC environment launches. Deactivating the ALLOC environment launch results in a run-time performance improvement. The overhead that is associated with the launch of the ALLOC environment is not needed. You can launch the ALLOC environment with PLSLALLO set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLALLO (N) takes precedence over PLSALLBO (N), PLSALLDA (Y), PLSALLNT (N), and PLSOPT10 (Y) and has no impact on either FDR support or PLSOPT15 (Y). PLSLDEF Valid Values: (Y) default, (N) PLSLDEF is a launch sysparm for the DEFINE environment. The default value of (Y) results in the DEFINE environment launching for applicable allocation requests. If you are not referencing the DEFINE environment in your ASR, you can override the launch sysparm to (N). This override logically disables DEFINE environment launches resulting in a runtime performance improvement. The overhead that is associated with the launch of the DEFINE environment is not needed. You can launch the DEFINE environment with PLSLDEF set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLDEF (N) takes precedence over PLSOPT10 (Y). PLSLDEF (N) has no impact on either FDR support or PLSOPT15 (Y). PLSLEOV Valid Values: (Y) default, (N) PLSLEOV is a launch sysparm for the EOV environment. The default value of (Y) results in the EOV environment launching for applicable allocation requests. If you are not referencing the EOV environment in your ASR, you can override the launch sysparm to (N). This override logically disables EOV environment launches resulting in a run time performance improvement. The overhead that is associated with the launch of the EOV environment is not needed. You can launch the EOV environment with PLSLEOV set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLEOV (N) takes precedence over PLSDCEOV (Y), PLSEOV65 (Y), PLSEOV69 (Y), PLSOPT13 (Y), PLSOPT16 (Y), PLSSMSEV (N), PLSV37 (Y), and PLSZSEC (Y). PLSV37 (N) takes precedence over PLSLEOV (Y). PLSLEOVV Valid Values: (Y) default, (N) PLSEOVV is a launch sysparm for the EOV VSAM environment. The default value of (Y) results in the EOV VSAM environment launching for applicable allocation requests. If you are not referencing the EOV VSAM environment in your ASR, you can override the launch sysparm to (N). This override logically disables EOV VSAM environment launches resulting in a run-time performance improvement. The overhead that is associated with the launch of the EOV VSAM environment is not needed. Implementation 118

119 You can launch the EOV VSAM environment with PLSEOVV set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLEOV (N) takes precedence over PLSOPT24 (N), PLSSMSEV (N), and PLSV37 (Y). PLSV37 (N) takes precedence over PLSLEOVV (Y). PLSLEXT Valid Values: (Y) default, (N) PLSLEXT is a launch sysparm for the EXTEND environment. The default value of (Y) results in the EXTEND environment launching for applicable allocation requests. If you are not referencing the EXTEND environment in your ASR, you can override the launch sysparm to (N). This override logically disables EXTEND environment launches resulting in a runtime performance improvement. The overhead that is associated with the launch of the EXTEND environment is not needed. You can launch the EXTEND environment with PLSLEXT set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLEXT (N) takes precedence over PLSOPT11 (Y). PLSLOLD Valid Values: (Y) default, (N) PLSLOLD is a launch sysparm for the OLD environment. The default value of (Y) results in the OLD environment launching for applicable allocation requests. If you are not referencing the OLD environment in your ASR, you can override the launch sysparm to (N). This override logically disables OLD environment launches resulting in a run-time performance improvement. The overhead that is associated with the launch of the OLD environment is not needed. You can launch the OLD environment with PLSLOLD set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLOLD (N) takes precedence over PLSOLDNU (Y). PLS453 (N) takes precedence over PLSLOLD (Y). PLSLPREA Valid Values: (Y) default, (N) PLSLPREA is a launch sysparm for the PREALLOC environment. The default value of (Y) results in the PREALLOC environment launching for applicable allocation requests. If you are not referencing the PREALLOC environment in your ASR, you can override the launch sysparm to (N). This override logically disables PREALLOC environment launches resulting in a run-time performance improvement; because the overhead associated with the launch of the PREALLOC environment is not needed. You can launch the PREALLOC environment with PLSLPREA set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLREL Valid Values: (Y) default, (N) PLSLREL is a launch sysparm for the RELEASE environment. The default value of (Y) results in the RELEASE environment launching for applicable allocation requests. If you are not referencing the RELEASE environment in your ASR, you can override the launch sysparm to (N). This override logically disables RELEASE environment launches resulting in a runtime performance improvement; because the overhead associated with the launch of the RELEASE environment is not needed. You can launch the RELEASE environment with PLSLREL set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. Implementation 119

120 PLSLRENM Valid Values: (Y) default, (N) PLSLRENM is a launch sysparm for the RENAME environment. The default value of (Y) results in the RENAME environment launching for applicable allocation requests. If you are not referencing the RENAME environment in your ASR, you can override the launch sysparm to (N). This override logically disables RENAME environment launches resulting in a runtime performance improvement; because the overhead associated with the launch of the RENAME environment is not needed. You can launch the RENAME environment with PLSLRENM set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLSCR Valid Values: (Y) default, (N) PLSLSCR is a launch sysparm for the SCRATCH environment. The default value of (Y) results in the SCRATCH environment launching for applicable allocation requests. If you are not referencing the SCRATCH environment in your ASR, you can override the launch sysparm to (N). This override logically disables SCRATCH environment launches resulting in a runtime performance improvement; because the overhead associated with the launch of the SCRATCH environment is not needed. You can launch the SCRATCH environment with PLSLSCR set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLSPA Valid Values: (Y) default, (N) PLSLSPA is a launch sysparm for the SPACE environment. The default value of (Y) results in the SPACE environment launching for applicable allocation requests. If you are not referencing the SPACE environment in your ASR, you can override the launch sysparm to (N). This override logically disables SPACE environment launches resulting in a runtime performance improvement; because the overhead associated with the launch of the SPACE environment is not needed. You can launch the SPACE environment with PLSLSPA set to (N) for a batch job, a started task, or a TSO User by using the PLSEXJOB sysparm. PLSLSPA (N) has no impact on PLSOPT27 (Y). PLSLSPA (N) has no impact on PLSOPT95 (Y). PLSMODE Valid Values: (ACTIVE) default, (DORMANT) The default value can be overridden using the ACTIVE or DORMANT operator command. Indicates the operation mode of the CA Allocate DASD Space and Placement started task. Specify (ACTIVE) to set CA Allocate DASD Space and Placement to the active state, the normal mode of operation. Specify (DORMANT) to set CA Allocate DASD Space and Placement to the dormant state. When in dormant state, CA Allocate DASD Space and Placement processes an allocation only when the DD described in the PLSDRMNT parameter is present. PLSNDEL8 Valid Values: (N) default, (Y) When set to (Y), any volumes that are specified in the optional VOL=SER JCL parameter are removed when DISP=(MOD,DELETE,DELETE) is also specified in the same DD statement to prevent the following JCL errors: Implementation 120

121 IEF283I data.set.name 23 NOT DELETED 8 IEF283I VOL SER NOS= vvvvvv 1. PLSNDEL8 (Y) only applies to allocation requests specifying DISP=MOD. The parameter assumes that there are available volumes on the system that are mounted with the storage or scratch attributes. When the data set name is a permanent one, the operating system seeks a storage volume. When the data set name is a temporary one, the operating system seeks a scratch volume. If your ASR directs CA Allocate DASD Space and Placement to select the volume, it can use volumes that are mounted with either the private, storage, or scratch attributes. PLSOLDNU Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 126 is activated. For more information, see Legacy Optional Features (see page 220). PLSOPEN - PLSV37BY PLSOPEN Valid Values: (N) default, (Y) PARMREF: No Running with PLSOPEN (Y) ensures that BLKSIZE changes, made by your ASR during the allocation of a new physical sequential data, are enforced when that data set is opened. This support only applies to data sets: Opened in the same job step the data set is allocated Opened for the first time Opened for accessing though the Queued Sequential Access Method (QSAM) This support requires a hook at IFG0EX0B -- the DCB Open Exit. The VAM0EX0B hook is incompatible with any other third-party DCB Open Exit. Physical sequential data sets are not considered eligible for PLSOPEN(Y) support when any of the following conditions exist: If the data set names start with SYS1 If JFCNWRIT bit is ON in the Job Function Control Block (JFCB) If the data sets have an undefined record format (RECFM=U) If the BLKSIZE is specified in both the program DCB and the JCL "BLKSIZE=" parameter If the Task Input Output Table (TIOT) DD Entry indicates sysin, sysout, or terminal PLSPRGDS Valid Values: (VAM.CCTVJCL) default PARMREF: No Contains the name of the partitioned data set that contains the Allocation Selection Routines, storage pool definitions, and the Quota configuration file members. This data set cannot be overridden by adding the VDSPROG DD to the CA Allocate DASD Space and Placement started task because this data set must be dynamically allocated. If you do, an error message is issued telling you to remove it Implementation 121

122 PLSQCFMB Valid Values: (QCONFIG) default PARMREF: No Contains the member name containing the Quota Configuration File that resides in the partitioned data set in the PLSPRGDS parameter. If your site is not licensed for the Quota feature, ignore this parameter. PLSQFACT Valid Values: (B) default, (K) PARMREF: No Units the quota allocation amounts are kept in. Possible values are B (bytes) or K (kilobytes). Default value is B which results in the historical limitation or 9 TB as the maximum quota limit. Customers needing the 9 TB limit increased to 9 PB must use K. For more information, see the Quota (see page 177) topics. Note: PLSOPT7 no longer provides this function. Use the PLSQFACT (K) function. PLSQRBMB Valid Values: (QREBUILD) default This member name can be overridden using the QREBUILD OPTION in the Quota Configuration File (pointed by the PLSQCFMB). Contains the member name that contains the QREBUILD Allocation Selection Routine that resides in the partitioned data set in the PLSPRGDS parameter. If your site is not licensed for the Quota feature, ignore this parameter. PLSQSCMB Valid Values: (QSCAN) This member name can be overridden using the QSCAN OPTION in the Quota Configuration File (pointed to by the PLSQCFMB member). Contains the member name that contains the QSCAN Allocation Selection Routine that resides in the partitioned data set in the PLSPRGDS parameter. If your site is not licensed for the Quota feature, ignore this parameter. PLSQUOF8 Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 129 is activated. For more information, see Legacy Optional Features (see page 220). PLSQUOGM Valid Values: (N) default, (Y) Indicates whether to track the quota allocation statistics using Greenwich Mean Time (Y) or Local Time (N). PLSQUOGM (Y) is recommended under certain conditions that are detailed in QUOTA and PLSQUOGM (see page 196). PLSRES Valid Values: (Y) default, (N) The PLSRES parameter is used to specify the residency mode of the active communications interface which can be either a started task or a batch job. Specify (Y) to keep the communications interface running waiting for operator commands. Specify (N) to terminate the communications interface after the last requested command has finished being processed. The value of PLSRES can be overridden using the RESIDENT= change parameter with other Implementation 122

123 parameters with the START or MODIFY Commands when running resident as a started task. The value can be overridden using the optional PARM=parameter on the EXEC PGM=VDSST451 statement when running as a batch job. The active value of PLSRES is retrieved and set during INSTALL operations. The active value can be explicitly changed during a PARMREF operation. The active value can also be implicitly changed by specifying either the RESIDENT=NO or RESIDENT=YES change parameter. You can specify the parameters either by itself with a MODIFY Command if running resident or before any of the following Action Commands if running nonresident: PARMREF, REFRESH, STATUS, QREBUILD, QRESETWM, QSYNC. PLSRES (Y) is required for QSYNC operations when running with the optional Quota selectable unit on multiple LPARS with the same Disk Quota Table. PLSRES (Y) is ignored after the following exception conditions occur: VAM0010, VAM0011, VAM0022, VAM0047, VAM0245, VAM0362, VAM0369, VAM5021. PLSSABDS Valid Values: (VAM.SYSABEND) default Contains the name of the physical sequential data set where the SYSABEND data is written. To route this data to an output class, instead of a data set, specify SYSOUT=x, where x is a SYSOUT class. Sample DCB attributes can be found in member PLSSABDS in the installation library. This data set can be overridden by adding SYSABEND, SYSUDUMP, or SYSMDUMP DD to the CA Allocate DASD Space and Placement started task. PLSSC Valid Values: (SAMSALSC) default Contains the name of the SMS storage class that CA Allocate DASD Space and Placement uses internally during the processing of a DFSMShsm RECALL or RECOVER which is not SMS managed. Defining this storage class to your SMS configuration is not required. Override the default value only if already using the default in the installation for another purpose. PLSSG Valid Values: (SAMSALSG) default Contains the name of the SMS storage group that CA Allocate DASD Space and Placement uses internally during the processing of a DFSMShsm RECALL or RECOVER that is not SMS managed. Override the default value only if already using the default in the installation for another purpose. PLSSMF01 Valid Values: (000) default The default value of (000) indicates not to write any SMF records. Specifying a valid three-digit numeric value for this sysparm before INSTALL or PARMREF activates writing an SMF record upon successful completion of the EOV Recovery process. Information about the data that these SMF records contain can be found in the SMF Interfaces (see page 87). PLSSMF02 Valid Values: (000) default, (128) through (255) excluding any value that is specified for PLSSMF01 The default value of (000) indicates not to write any SMF records. Specifying a valid three-digit numeric value for this sysparm before INSTALL or PARMREF activates writing an SMF record upon successful completion of the RTF Recovery process. For more information, see SMF Interfaces (see page 87). PLSSMSEV Valid Values: (Y) default, (N) Special processing flag that is only changed from the default value when you want to disable the Implementation 123

124 CA Allocate DASD Space and Placement End-of-Volume support for SMS-managed data sets. Specify (Y) to process SMS-managed data sets in the EOV and EOV_VSAM environments. Specify (N) to prevent the processing of SMS-managed data set in the EOV and EOV_VSAM environments. PLSSPRDS Valid Values: (VAM.SYSPRT) default Contains the name of the physical sequential data set where the SYSPRINT (DDname SYSPRT) output is written. To route this data to an output class, instead of a data set, specify SYSOUT=x, where x is a SYSOUT class. Sample DCB attributes can be found in member PLSSPRDS in the installation library. This data set can be overridden by adding the SYSPRT DD to the CA Allocate DASD Space and Placement started task. PLSSTCN Valid Values: (VAM) default Contains the name of the CA Allocate DASD Space and Placement started task. This parameter is required if you want to submit commands to CA Allocate DASD Space and Placement from within the CA Vantage GUI. If your site is not licensed for CA Vantage, then this parameter can be ignored. PLSSTRMB Valid Values: (VDSTORGP) default This member name can be overridden by using the STORGP= operator command. Contains the member name that contains the storage group definition table that resides in the partitioned data set in the PLSPRGDS parameter. PLSV37 Valid Values: (Y) default, (N) PARMREF: No Only change this processing flag from the default value when you want to disable the CA Allocate DASD Space and Placement End-of-Volume support. Specify (Y) to install the EOV intercept points into the operating system. Specify (N) to prevent the installation of the EOV intercept points into the operating system. PLSV37BY Valid Values: (V37BYPAS) default The DDname, that you can test for in the ASR, to determine whether to process data sets with DCB EXITS in the EOV (non-vsam) environment. See the descriptions of sysparms PLSEOV65 and PLSEOV69. Instead of specifying //PI DD DUMMY or //PI DD DUMMY to perform their functions as described for PLSEOV65(Y) or PLSEOV69(Y), specify the default value: //V37BYPAS DD DUMMY. The default value has the same effect as PI DD or PI DD. To change the default of V37BYPAS DDname specify the sysparm PLSV37BY(yourddname). When either PLSEOV65(Y) or PLSEOV69(Y) is active, code //YOURDDNAME DD DUMMY in the job step to accomplish the same effect as described for PI DD or PI DD. PLSVDSMB - PLSZSEC PLSVDSMB Valid Values: (VDSPROG) default Implementation 124

125 This member name can be overridden by using the PROG= Operator Command. Contains the member name of the VDSPROG Allocation Selection Routine that resides in the partitioned data set in the PLSPRGDS parameter. PLSVSFAL Valid Values: (N) default, (Y) Only change this processing flag from the default value of (N) when you want to create a token containing the reason the CA Allocate DASD Space and Placement Volume Selection Logic failed to select a volume in the ALLOC environment. For more information about this token, see Volume Selection Logic for Non-SMS-managed (see page 58). Specify (Y) to create the token when running with &FINVS=Y. Specify (N) to bypass creation of the token that is detailed in the previous section. PLSVSFDF Valid Values: (N) default, (Y) PLSVSFDF is a special processing flag that is only changed from the default value of (N) when you want to create a token containing the reason the CA Allocate DASD Space and Placement Volume Selection Logic failed to select a volume in the DEFINE environment. For more information about this token, see Volume Selection Logic for Non-SMS-managed (see page 58). Specify (Y) to create the token when running with &FINVS=Y. Specify (N) to bypass creation of the token that is detailed in the previous section. PLSVSFEV Valid Values: (N) default, (Y) PLSVSFEV is a special processing flag that should only be changed from the default value of (N) when wanting to create a token containing the reason the CA Allocate DASD Space and Placement Volume Selection Logic failed to select a volume in the EOV environment or the EOV_VSAM environment. For more information about this token, see Volume Selection Logic for Non-SMS-managed (see page 58). Specify (Y) to create the token when running with &FINVS=Y. Specify (N) to bypass creation of the token that is detailed previously. PLSVSMPV Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 128 is activated. For more information about this feature, see Legacy Optional Features (see page 220). PLSVSMSC Valid Values: (N) default, (Y) When set to (Y), Optional Maintenance ID (MID) 008 is activated. For more information about this feature, see Legacy Optional Features (see page 220). PLSXRFDS Valid Values: (VAM.XRF) default Contains the name of the partitioned data set that contains the Cross Reference data (XRF), the Cross Reference of each COPYBOOK statement for each ASR. To route this data to an output class, instead of a data set, specify SYSOUT=x, where x is a SYSOUT class, instead of the name of a PDS. Sample DCB attributes can be found in member PLSXRFDS in the installation library. This data set cannot be overridden by adding the XRF DD to the CA Allocate DASD Space and Implementation 125

126 Placement started task because this data set must be dynamically allocated. If you do, an error message is issued telling you to remove it. PLSZSEC Valid Values: (N) default, (Y) Activates the additional EOV support that is detailed in EOV Support for Zero Secondary (see page 68). PLSOPTnn Sysparms The PLSOPTnn Sysparms are divided into the following parts: PLSOPT1 - PLSOPT11 (see page 126) PLSOPT12 - PLSOPT30 (see page 130) PLSOPT31 - PLSOPT76 (see page 133) PLSOPT77 - PLSOPT99 (see page 136) PLSOPT1 - PLSOPT11 PLSOPT1 Valid Values: (N) default, (Y) Activates the abend prevention facility that is described in parameter PLSENQDS. If you specify Y, CA Allocate DASD Space and Placement serializes the removal of its SVC hooks with jobs that reference the data set name that is specified in the PLSENQDS parameter. For more information, see the parameter description for PLSENQDS (see page 113). Note: This flag is a special processing flag that is typically used only with CA Disk. PLSOPT2 Valid Values: (N) default, (Y) Supports the RACF Discrete profiles during DFSMShsm RECALL and RECOVER operations. If you specify Y, the CA Allocate DASD Space and Placement non-vsam volume selection routine looks for a data set with a RACF Discrete Profile. When it finds one, the routine issues the appropriate RACROUTE requests to prevent errors when CA Allocate DASD Space and Placement redirects such allocations. PLSOPT3 Valid Values: (N) default, (Y) This parameter can change the default action that is taken during tape to disk conversion regarding the UNIT=AFF=ddname JCL parameter. When (Y) is specified: All DD statements that have UNIT=AFF=ddname have UNIT AFFINITY automatically disabled. Space type and space quantities are automatically propagated from the JFCB associated with the UNIT=AFF=ddname. Implementation 126

127 PLSOPT4 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT5 Valid Values: (N) default, (Y) With the default value of (N), CA Allocate DASD Space and Placement activates the OLD environment when encountering JCL references to relative GDGs. To prevent CA Allocate DASD Space and Placement from activating the OLD environment when encountering JCL references to relative GDGs, set the value of PLSOPT5 to (Y). PLSOPT6 Valid Values: (N) default, (Y) PLSOPT6 (Y) must be specified in the CA Allocate DASD Space and Placement parmlib to activate the new EOV support for IAM file update operations, which is only applicable to releases V6.4/07P and above of IAM. Activating this new support for earlier releases of IAM results in C03 abends when those data sets are closed. PLSOPT7 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT8 Valid Values: (N) default, (Y) Lets you retain the current Quota Water Mark (QWM) values during a QREBUILD operation. If you specify (Y), the CA Allocate DASD Space and Placement quota table rebuild operations do not reset the QWM values of a quota group to the current allocation amount. PLSOPT9 Valid Values: (N) default, (Y) Defers the actual allocation of new non-vsam, non SMS-managed data sets. We only recommend its use when step termination processing fails to delete data sets that had been redirected in a step that fails with a JCL error. Some of the data sets may be left uncataloged on the volumes they were redirected to, regardless of the abnormal disposition specified in the JCL. Deferring these allocations increases the window between the time CA Allocate DASD Space and Placement selects a volume with sufficient free space and the time the new data set is allocated on that volume. This deferral can increase the frequency of IEF SPACE REQUESTED NOT AVAILABLE JCL errors because another job has taken the space during this window. Note: When PLSOPT9 (Y) defers allocations, and the ASR exits with a nonzero return code, no special MVS messages are issued. To avoid confusion among end users is the importance of having the ASR issue some sort of message indicating that it is choosing to deny this allocation. PLSOPT10 Valid Values: (N) default, (Y) Allows SMS-managed data set allocations to be intercepted in the ALLOC and DEFINE environments. Specifying a value of 'Y' gives new SMS-managed data set allocations access to both the DIF and LSPACE support features, either one of which can be used to prevent space not Implementation 127

128 available job failures. Support for the following variables, except as noted after the list, is the same for both SMS and non-sms-managed data sets: &BLKSIZE &DEVCLAS &DIRBLOCKS &DSORG &EXPDT &LRECL &NUNIT &PRIMARY &RECFM &SECONDARY &SPACTYPE &UNIT &VLCT The following items are the differences in support between nonsms-managed and SMSmanaged data sets for the preceding variables: Except for DIF and LSPACE processing, &UNIT is not an OUTPUT variable in the ALLOC environment for SMS-managed data sets. &DEVCLAS is not an INPUT variable in the ALLOC environment for SMS-managed data sets. &NUNIT is not an OUTPUT variable in the ALLOC environment for SMS-managed data sets. Use &VLCT instead. The &UNIT variable is available for output in the ALLOC environment only when converting from DASD to SMS virtual tape. The &UNIT variable is available as input for SMS allocation in the ALLOC environment. Note: Other variables are not supported for SMS-managed data sets in the ALLOC and DEFINE environments. PLSOPT11 Valid Values: (N) default, (Y) Controls whether VSAM support in the EXTEND environment is active. The default value is (N), which deactivates the support. If you specify (Y), it intercepts VSAM extend processing. When this support is activated, the following variables are available as INPUT except for NVOLD, SECONDARYD and SECONDARYI, which are available as INPUT and OUTPUT: &ALLVOLD &ALLVOLI &ANYVOLD &ANYVOLI &C0-&C40 &CISIZE &CISIZED &CISIZEI &DD &DDD &DDI &DSN &DSND &DSNI Implementation 128

129 &EXTENDCOMP &EXTENTS &EXTENTSD &EXTENTSI &EXTENDVOL &HLQ &HLQD &HLQI &IMBED &LLQ &LLQD &LLQI &N0-&N40 &NQUAL &NQUALD &NQUALI &NVOL &NVOLD (Read and Update) &NVOLI &PRIMARYD &PRIMARYI &RECORG &REPLICATE &SECONDARYD (Read and Update) &SECONDARYI (Read and Update) &SPACTYPED &SPACTYPEI &UNITD &UNITI &UNITTYPED &UNITTYPEI Note: Before you use these variables, see the ASR Variables 24 to determine any limitations or availability between SMS-managed and non-sms-managed data sets. For more information, see VSAM Processing in EXTEND (see page 41) Implementation 129

130 PLSOPT12 - PLSOPT30 PLSOPT12 Valid Values: (N) default, (Y) Controls whether the Application Programming Interface for FDR Redirection support is active. The default value deactivates the support. If you specify (Y), CA Allocate DASD Space and Placement redirects FDR data set allocations. After PLSOPT12 has been set to (Y), then activate the API within FDR. Select one (1) of the following methods to activate: Use the FDR installation dialog on ISPF to set the ALCRSTIN option to YES on panel x.i.4.2 Execute program FDRZAPOP with the command ZAP ENABLE=ALCRSTIN Note: The CA Allocate DASD Space and Placement load library must be added to STEPLIB in all FDR jobs. Otherwise, you receive an S806 for PLDRSTIN. CA Allocate DASD Space and Placement can be installed from a system LINKLIST data set. If this method is being done, adding the STEPLIB DD for FDR jobs is not required. Finally, to activate this support, simply include the FDR variable in your ASR. For more information, see the variable description of FDR in ASR Variables 25. For more information, see FDR Support (see page 95). PLSOPT13 Valid Values: (N) default, (Y) Controls whether the Multiple DSCB Open Support for ISPF Allocations is activated. Without this support, ISPF allocations that have more than one open DSCB are bypassed in the EOV environment. The default value of (N) prevents CA Allocate DASD Space and Placement from using this support. PLSOPT14 Valid Values: (N) default, (Y) Prevents CA Allocate DASD Space and Placement from notifying CA Vantage of threshold violations. The default value of (N) allows CA Allocate DASD Space and Placement to notify CA Vantage of all violations when they occur. Specifying a value of (Y) causes CA Allocate DASD Space and Placement to bypass the notification process. PLSOPT15 Valid Values: (N) default, (Y) PARMREF: No (Y) installs the HSM recall/recover support. PLSOPT16 Valid Values: (N) default, (Y) Logically enables non-vsam EOV support for CA Disk z/os RESTOREs. PLSOPT17 Valid Values: (N) default, (Y) Activates security on the special bypass DDName described in parameter PLSBYPAS. If (Y) is 25 Implementation 130

131 specified, CA Allocate DASD Space and Placement queries the security system when finding the DDName in a job step, checking the current userid for authorization to use that DDName. If the userid does not have authorization, a VAM0038 message is issued. CA Allocate DASD Space and Placement processes the job step the same as if the bypass DDName was not there. Identify the bypass DDName to your security system before activating this support with the following process: a. Define the specified or default value in the CA Allocate DASD Space and Placement PLSBYPAS system parameter as a generic data set class to the security system with universal access of NONE. For example, if the default value is used, the generic data set class is 'VDSBYPAS.**' b. CA Allocate DASD Space and Placement simulates the allocation of a data set with the DSN comprised of the value of PLSBYPAS and a second node of X. For example, if PLSBYPAS is at the default, the DSN would be 'VDSBYPAS.X.' See your security package documentation for granting the necessary access. Note: The bypass ddname might be any valid ddname, 1-8 characters in length. Do not define the ddname as any element (such as an ALIAS) in the master or any other user catalog. PLSOPT18 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT19 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT20 Valid Values: (N) default, (Y) This parameter activates the volume selection process to pick a volume randomly. Volume selection is done using the IBM SYSEVENTS DEVALLOC Service. Note: When the VOLUME_SELECTION_BY_LEAST_FREESPACE variable is assigned a value of Y by your Allocation Selection Routine, PLSOPT20 (Y) configurations are logically set to (N). This setting is for the current allocation request only. PLSOPT22 Valid Values: (N) default, (Y) This parameter causes second choice volumes to be chosen from volumes with the lowest threshold setting in the VDSTORGP parmlib member. The default setting of PLSOPT22 (N) causes the second choice volumes to be chosen as described in Volume Selection Logic for Non-SMSmanaged (see page 58). Note: When the VOLUME_SELECTION_BY_LEAST_FREESPACE variable is assigned a value of Y by your Allocation Selection Routine, PLSOPT22 (Y) configurations are logically set to (N) This setting is for the current allocation request only. PLSOPT23 Valid Values: (N) default, (Y) Implementation 131

132 This parameter enables EOV recovery even when the TCBTCT field is zeros. The default setting of PLSOPT23 (N) continues to bypass EOV recovery when TCBTCT is zeros. PLSOPT24 Valid Values: (N) default, (Y) This parameter prevents the launching of EOV_VSAM environment when a Candidate volume is available. The default setting of PLSOPT24 (N) continues to Launch EOV_VSAM regardless of presence of a candidate volume. PLSOPT25-PLSOPT26 Valid Values: (N) PARMREF: No Reserved for future development PLSOPT27 Valid Values: (N) default The value of sysparm PLSOPT27 determines whether a legacy limitation that is associated with the NOT CATLGD 2 (SNC2) support is globally lifted. This limitation required that CA Allocate DASD Space and Placement must have redirected the non-sms-managed non-vsam data sets (that is, a STORGRP must be set in the ALLOC environment) to be considered eligible for the SNC2 support in the SPACE environment. The default value of (N) for PLSOPT27 keeps the limitation remaining in effect. To disable this legacy limitation, specify a value of (Y) for PLSOPT27 in the sysparm override member of your CA Allocate DASD Space and Placement parmlib. PLSOPT28 Valid Values: (N) default, (Y) The default value (N) issues the V37237I messages unconditionally. If you want to issue the messages only when diagnostics have been activated, set the value to (Y). PLSOPT29 Valid Values: (N) default, (Y) The default value (N) issues the V37285I messages unconditionally. If you want to issue the messages only when diagnostics have been activated, set the value to (Y). PLSOPT30 Valid Values: (N) default, (Y) Set this parameter to (Y) if you: Are using the CA JCLCheck. Encounter any security package access violation messages such as "ACF99913 ACF2 VIOLATION-08,06,jobname,dsn". Are using the OEM product ASG-JOB/SCAN. You might need to apply an extra compatibility PTF to ASG-JOB/SCAN. If you do not know whether to set this option to (Y), contact CA Support for assistance at ca.com/support. Implementation 132

133 PLSOPT31 - PLSOPT76 PLSOPT31 Valid Values: (N) default, (Y) Set this parameter to (Y) if you are running with PLSOPT10 set to (Y) and you are using the DOES IT FIT support in the ALLOC environment. The purpose of the PLSOPT31 sysparm is to control the launch of the ALLOC environment for any redrive allocation requests that SMS can decide to make for new data sets. The default value of (N) results in the launch of the ALLOC environment being bypassed. A value of (Y) disables the exclusion and allows the ALLOC environment to be launched for any redrive allocation requests that SMS can decide to make for new non-vsam nontape data sets. Your ASR is able to identify redrive the ALLOC environment launches by querying the value of the REDRIVE_BY_SMS variable: a value of Y indicates a re-drive launch. Support for most variables remains unchanged, but there are some exceptions: &CMP3480, &FILENUM, and &LABEL are not supported because these variables are specific for new tape data set allocations. &DIRBLKS, &DSORG, &LIKE, &NUNIT, &NVOL, &UNIT, &UNITAFF, &VLCT, &VREFDDN, &VREFDSN, and &VREFSTP are available for INPUT only. PLSOPT32 Valid Values: (N) default, (Y) Set this parameter to (Y) if you want to avoid the possible overallocation of dynamically allocated DF/SORT SORTWK data sets when they are assigned to a storage group in the ALLOC environment. The data sets must meet the following criteria to be eligible for the special handling that PLSOPT32 offers. DDname prefix must be SORTWK, or characters 5&6 must be 'WK' Must be dynamically allocated by program name of SORT* or ICE* Temporary data set Primary space is '0' Allocation space type is AVGLBK+ROUND PLSOPT33 Valid Values: (N) default, (Y) Specifying a value of (Y) changes the default action for JES3 users when an unknown value of UNIT= is detected when allocating a new data set. CA Allocate DASD Space and Placement does not perform JES3 TAPE setup processing, which allows the new data set to be redirected to a disk unit. With the default value of (N), it is assumed that the new data set is directed to a TAPE unit and CA Allocate DASD Space and Placement performs JES3 TAPE setup processing PLSOPT34 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT35 Valid Values: (N) default, (Y) Implementation 133

134 Specifying a value of (Y) results in the calling the legacy VDSHKXT0 exit from applicable hook programs. The VDSHKXT0 Exit, which was never documented, was the precursor to the documented VDSBYPAS DDName Security optional feature controlled by sysparm PLSOPT17. PLSOPT36 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT37 Valid Values: (N) default, (Y) The default value (N) causes the V messages to be issued unconditionally. If you do not want them issued unconditionally and issued only when diagnostics are activated, set the value to (Y). PLSOPT38 Valid Values: (N) default, (Y) The default value (N) causes the VAM0096 messages to be issued unconditionally. If you do not want them issued unconditionally and issued only when diagnostics are activated, set the value to (Y). PLSOPT39 Valid Values: (N) default, (Y) The default value (N) causes the VAM0093 messages to be issued unconditionally. If you do not want them issued unconditionally and issued only when diagnostics are activated, set the value to (Y). PLSOPT40 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT41 Valid Values: (N) default, (Y) When set to (Y) and if an unexpected Space Not Available condition occurs with the volume that was chosen, the volume selection process is redriven. PLSOPT41 only applies to nonsmsmanaged new VSAM data sets that are redirected in the DEFINE environment to a storage group that has been defined with a Free-Space Threshold. PLSOPT42-PLSOPT43 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT44 Valid Values: (N) default; (Y) Set PLSOPT44(Y) if you do not want to invoke stop-not-catlgd2 (SNC2) processing for JCL where old data set is referenced as (OLD,DELETE) or (OLD,UNCATLG) and new data set is (NEW,CATLG) in the same step. Example: Implementation 134

135 //STEP2 EXEC PGM=IEFBR14 //OUTPUT1 DD DSN=DSN.TEST,DISP=(OLD,DELETE) //OUTPUT1 DD DSN=DSN.TEST,DISP=(NEW,CATLG) Set (or default) PLSOPT44(N) when you want to invoke stop-not-catlgd2 (SNC2) processing for this type of JCL. PLSOPT45 Valid Values: (N) default, (Y) Specify PLSOPT45 (Y) in the CA Allocate DASD Space and Placement parmlib to override any specific data set access authority conditionally. The access authority would otherwise prevent the End-Of-Volume support from recovering both SMS-managed non-vsam and VSAM data set from a Space Not Available (SNA) condition. An unresolved SNA condition results in the premature termination of the operation that was successfully adding records to the data set. The action was in progress until all space had been exhausted on the current volume. An extra volume was required to continue with the load operation. PLSOPT46 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT47 Valid Values: (N) default, (Y) Controls the activation of the End-Of-Volume support for permanent, uncataloged, non-vsam data sets. Without this support, SMS-managed non-vsam data sets allocated with DISP=(NEW,KEEP) are considered ineligible for the EOV environment. The default value of (N) prevents CA Allocate DASD Space and Placement from using this support. PLSOPT48 Valid Values: (N) default, (Y) This parameter provides an alternative code path for SMS-managed non-vsam end-of-volume processing. It is designed for IMS online OSAM databases that have experienced a U764 abend when CA Allocate has added a volume to the OSAM database. Set this parameter to Y only on the advice of CA Allocate support. PLSOPT49-PLSOPT75 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT76 Valid Values: (N) default, (Y) PLSOPT76 is used with DOES IT FIT (DIF) support (see page 68). The default value is (N), which indicates not making a Virtual Conversion (VC) permanent when an adjustment of the space amount was required to avoid a Space Not Available (SNA) condition. The optional value of (Y) indicates that the VC is to become permanent if an adjustment of the space amount was required to avoid a SNA condition. Implementation 135

136 PLSOPT77 - PLSOPT99 PLSOPT77 Valid Values: (N) default, (Y) Specifying a value of (Y) directs CA Allocate DASD Space and Placement not to determine the catalog status of a data set when a STEPCAT DD statement is present in a job step. Current attempts to do so result in AN S0C4-11 abend in IBM code at IGG0CLAH+1A34 on systems running z/os 1.4 at FMID=HDZ11G0/MAINT=UA IBM reference numbers are PMR 28016, BRANCH 111, and APAR OA Remember that because the catalog status of the data set cannot be determined when a STEPCAT DD statement is included in a job step, any product features, or ASR statements that rely on the catalog status are not effective. One example of this result is the OLD environment, which is bypassed. For this reason, only set PLSOPT77 to (Y) on those systems that have experienced the abend in IBM code in job steps with STEPCAT DD statements. When running with PLSOPT77 (Y), these conditional diagnostic messages display in job steps that do not include a STEPCAT: VAM000I VAMACAT -QOxxxxx SVD5300 hh.mm 26 yyyymmdd VAM000I PLSOPT77 (Y) VAM000I NO STEPCAT DD FOUND IN STEP When running with PLSOPT77 (Y), these conditional diagnostic messages display in job steps that do include a STEPCAT: VAM000I VAMACAT -QOxxxxx SVD5300 hh.mm 27 yyyymmdd VAM000I PLSOPT77 (Y) VAM000I STEPCAT DD FOUND IN THIS STEP VAM000I IBM REFERENCE NUMBERS ARE: VAM000I...'PMR BRANCH 111' AND 'APAR OA07078' VAM000I CANNOT CONTINUE DUE TO UNRESOLVED PROBLEM IN IBM CODE VAM000I...LEAVING CHECK_FOR_STEPCAT, RC= We have found that manually allocating the user catalog to the Catalog Address Space using an 'F CATALOG,ALLOCATE(ucat-name)' operator command fixes whatever problem IBM code is having so that the abend does not occur. PLSOPT78 Valid Values: (N) default, (Y) When a CA Vantage user is not logged on to the GUI, messages sent by CA Allocate DASD Space and Placement to that user are lost. Overriding the default value of (N), which means not saving the messages, by specifying a value of (Y) saves any messages that CA Allocate DASD Space and Placement sent to the mailbox of that user. The next time that the user logs in to the PcGUI, the following message window appears: Implementation 136

137 sysid/subsysn STC-name YOU HAVE nnn MAIL(S) IN YOUR MAILBOX Where sysid is the four-character system identifier of the z/os system the CA Vantage STC is running on. subsysn is the unique identifier of the subsystem that is associated with the CA Vantage STC the user is logged in to. STC-name is the name of the CA Vantage started task the user is logged in to. nnn is the number of messages in the mailbox of the user. PLSOPT79 Valid Values: (N) default, (Y) Use of the IBM documented Common VTOC Access Facility (CVAF) to detect items that renders a specific volume ineligible for a particular new, non-sms, non-vsam data set allocation has a finite amount of overhead. This overhead can be avoided by deferring the detection of ineligible volumes until a later point in the volume selection process; after the launches of the SPACE and QUOTA environments. But each environment launch has a finite amount of overhead that is associated with it, the execution of the ASR consuming the largest part. As a result, the same methodology in this area might not be the best for all users. Running with PLSOPT79 (N) makes the CVAF calls and in all but the most unusual circumstances, a single call to the SPACE and QUOTA environments. Running with PLSOPT79 (Y) skips the CVAF calls and can result in duplicate SPACE and QUOTA environment launches. If you are not running with the optional Quota Feature and have minimal or no special ASR processing to do in the SPACE environment, we recommend running with PLSOPT79 (Y). PLSOPT80 Valid Values: (N) default, (Y) The volume selection process (VSP) ordinarily accesses the Eligible Device Table (EDT) twice; first to determine the number of devices that are associated with the value the ASR specified for the UNIT variable and then to retrieve the details on the location of the device information that is stored in the EDT. Accessing the EDT has a finite amount of overhead. A portion of this overhead can be avoided by using the device count of 3390 devices CA Allocate DASD Space and Placement internally tracks. Initially this device count is determined during an INSTALL operation and is recalculated during REFRESH operations. Running with PLSOPT80 (N) causes VSP to access the EDT to determine the number of devices that are associated with the value the ASR specified for the UNIT variable. Running with PLSOPT80 (Y) uses the device count CA Allocate DASD Space and Placement internally tracks. If all your DASD devices are 3390s and all are defined in your EDT as belonging to the 3390 generic group, we recommend running with PLSOPT80 (Y). PLSOPT81 Valid Values: (N) default, (Y) The active copy of the ASR is updated during a REFRESH operation. If REFRESH operations are done while CA Allocate DASD Space and Placement is actively processing allocation requests, there is a possibility that the storage occupied by the old ASR might be freed while it is still being Implementation 137

138 used by allocation requests that started before the REFRESH operation started. This operation causes the allocation request to abend. Running with PLSOPT81 (N) serializes access to the ASR so that the old copy is not freed after a 30-second wait if it was still being used by any allocation request. WTOR message VAM0072 is issued with the option of canceling the wait. This results in the old ASR storage not being freed. A finite amount of overhead is associated with running this configuration. If you do not invoke REFRESH operations during periods of high system activity, running with PLSOPT81 set to (Y) frees the old ASR after a 30-second wait. PLSOPT82 Valid Values: (N) default, (Y) Existing IBM documentation regarding the need for system resource serialization during readonly access advises you to weigh possible system performance loss because of serialization against the potential loss of data integrity. Running with PLSOPT82 (N) serializes access to the volume while its free space information is being gathered. Running with PLSOPT82 (Y) does not serialize access to the volume while its free space information is being gathered. If you have many volumes in each storage group available for allocation and you are running with PLSOPT20 (Y) "volume selection process Random", an improvement in run-time performance might be seen when SYSPARM PLSOPT82 is set to (Y). However, unless a tangible performance improvement is seen when running with PLSOPT82 (Y), we recommend running with PLSOPT82 (N). The downside of running with PLSOPT82 (Y) is that inaccurate free space information might be gathered. Remember that the inaccurate information can be either under reporting free space or over reporting free space. Also, if the free space is over reported, the potential for a space not available condition exists. PLSOPT83-PLSOPT93 Valid Values: (N) default PARMREF: No Reserved for future development PLSOPT94 Valid Values: (N) default, (Y) Used to control the removal of the CA Allocate hooks from the system when a REMOVE command is used. STUB process The default value causes CA Allocate DASD Space and Placement to leave the hooks at IGGPRE00, IGGDAC02, IGGPOST0, and SVC26 during a REMOVE operation. As shown within the following messages during a REMOVE: Implementation 138

139 VAM000I PLSOPT94(N) : LEAVING VAMPRE00 'IN' VAM000I PLSOPT94(N) : LEAVING VAMPOST0 'IN' VAM000I PLSOPT94(N) : LEAVING VAMAB4A2 'IN' VAM000I PLSOPT94(N) : LEAVING VAMAB490 'IN' VAM000I PLSOPT94(N) : LEAVING VAM0EX0B 'IN' VAM000I PLSOPT94(N) : LEAVING VAM0002F 'IN' VAM000I PLSOPT94(N) : LEAVING V37VSAM 'IN' VAM000I PLSOPT94(N) : LEAVING VAMDAC02 'IN' This process is referred to as the STUB process. The STUBs provide anchor points for CA Allocate DASD Space and Placement and are effectively dormant when the system is not active. LIFO process A value of Y causes the system to remove the hooks in the order that they were set, as shown in the following messages: VAM000I PLSOPT94(Y) : REMOVING VAMPRE00 VAM000I PLSOPT94(Y) : REMOVING VAMPOST0 VAM000I PLSOPT94(Y) : REMOVING VAMAB4A2 VAM000I PLSOPT94(Y) : REMOVING VAMAB490 VAM000I PLSOPT94(Y) : REMOVING VAM0EX0B VAM000I PLSOPT94(Y) : REMOVING VAM0002F VAM000I PLSOPT94(Y) : REMOVING V37VSAM VAM000I PLSOPT94(Y) : REMOVING VAMDAC02 This process is referred to as LIFO (last-in, first-out). Installations running other OEM products that also hook at IGGPRE00, IGGDAC02, IGGPOST0, and SVC26 must ensure that PLSOPT94 is set to N. N eliminates the LIFO requirement for removal of the system at these locations. SMPE HOLD data considerations Any PTF where there is a HOLD for an IPL, the IPL can be circumvented if Vkgparm PLSOPT94 =Y (active) at the time of the last shut down, prior to starting up with the updated Loadlib. With PLSOPT94 set to Y, eight additional hooks are removed at shut down that would have been left installed by default. If these hooks (modules) are not removed at shutdown, then they cannot be updated with the new modules being applied. If Vkgparm PLSOPT94 (Y) is not currently specified, follow these steps so it is active before the shut down prior to restarting with the updated Loadlib. - Add or update your Vkgparms member with PLSOPT94 (Y) - Issue the console command: F vam,parmref When this command is complete, VAM is shutdown and the additional VAM hooks are removed. After you verify that those hooks are all removed, then you can restart VAM after applying the maintenance. You can leave this parameter in the Vkgparms member. PLSOPT95 Valid Values: (N) default, (Y) Implementation 139

140 Setting PLSOPT95 (Y) allows the Stop-Not-Cataloged-2 feature to be implemented for non-sms managed TAPE data sets. See the description of STOP_NOT_CATLG2 variable in ASR Variables 28. The STOP-NOT-CATLG2 variable can be set to U, R, or D, but if the existing data set is on tape, the only valid option is U. If it is R or D, the SNC2RC variable is set to 20. When running with PLSOPT95 (Y), the SPACE environment for TAPE data sets is entered for the sole purpose of allowing an existing tape data set to be uncataloged. Therefore, any of the variables that typically are referenced in the SPACE environment for DASD data sets might not be applicable for TAPE data sets, and should not be referenced. Also, any of the variables that can be set in the SPACE environment for DASD data sets cannot be set for TAPE data sets in the SPACE environment. The single exception to this rule is the STOP_NOT_CATLG2 (SNC2) variable, which can be set as indicated previously. PLSOPT96 Valid Values: (N) default, (Y) If you set PLSOPT96 to (Y) when running with the SUPLSQ (Y), the Quota Feature uses the allocation size that Quota environment computes. The feature updates the CQT at VDSPOST0 instead of the size that is recomputed during VDSPOST0 processing. VDSPOST0 also issues more conditional diagnostics. PLSOPT97 Valid Values: (N) default, (Y) Running with the default of (N), creates an SDUMP and other required diagnostic messages when an unusual condition is encountered during End-of-Volume processing for VSAM data sets. If an SDUMP occurs, prepare to send the DUMP, complete Allocate STC JES listing, and complete job listing where the V37xxxx messages appear to CA Support. After you have opened an issue, you can change this parameter to Y to suppress the dump. Setting PLSOPT97 to (Y) suppresses the SDUMPs and unconditional messages. Do not suppress the generation of such documentation until at least one set has been captured and sent to CA Technical Support. Without such basic DOCs, it is virtually impossible to diagnose the cause of such problems which may result in abends in other vendors' software later on in the job, long after CA Allocate has completed its EOV Recovery Process. PLSOPT98 Valid Values: (N) default, (Y) The default (N) value of PLSOPT98 results in most messages being issued in triplicate: to the SYSLOG, to the JESMSGLG, and to the JESYSMSG DDs that are allocated to the applicable batch job or started task. A (Y) value for PLSOPT98 results in messages being issued only once to the JESMSGLG DD. This behavior also applies to messages that are issued by the WRITE statement in your ASR. Messages that PLSOPT98 does not control include: Messages that are issued by any of the JCL distributed in the CCTVJCL target library of your SMP/E zone. Any WRITE messages that your ASR issues to any allocation requests made by any of the 28 Implementation 140

141 CCTVJCL JCL members. Any messages that the CA Auditor Interface issues. Any messages that detect an unexpected error condition in any program. When you turn on the diagnostic tracing with pattern masking characters, PLSOPT98-controlled messages that are issued to the affected jobs are issued only once. The messages issue to the JESMSGLG DD, regardless of the active value of PLSOPT98. PLSOPT99 Valid Values: (N) default, (Y) When PLSOPT99 (Y) is specified in PARMLIB, and DIAGS= tracing has been activated for a job or STC, extensive optional diagnostics are generated. Multiple Systems - Parmlib Considerations You have two basic approaches for handling your local parameter settings for multiple CA Allocate DASD Space and Placement systems: Use a different local parmlib for each system This approach lets you use the default member names in all your local parmlibs, one for each system. Each local parmlib has a CONFIG member, a VKGPARMS member, and so on. But the contents of these members are different in each library. They contain the options specific to their respective systems. One of the drawbacks to this approach is the existence of several local parmlibs. Another drawback is that you have to jump around from one library to the next to examine and modify configurations. Use the same local parmlib for all systems In this approach, the configuration members must have unique names for each system. For example, assume that you have four CA Allocate DASD Space and Placement systems. You cannot have four VKGPARMS members in the same library. So instead, you might name them VAMPSYS1, VAMPSYS2, VAMPSYS3, and VAMPSYS4. Now you need a way to tell each system which VKGPARM member it is to use. You can provide the information from the CONFIG member in two ways. The EXEC statement in the started task JCL for each system contains the CONFIG=mbrname and VSYS=sysname parameters. The CONFIG= parameter identifies the config member for that system. A <VSYS=sysname > statement must be inside this member. This name is a section name that defines the components of the named system. The first line under the <VSYS=sysname > statement usually says VKGPARMS=VKGPARMS, which provides the true name of the VKGPARMS member. This place is where you specify VKGPARMS=VAMPSYS1 to direct system 1 to its correct system parameters. To configure your four systems, you have three choices. You can: Use four different config members. Use four different sysname sections within a single config member. Other combinations, like two config members with perhaps two sysname sections in each. The benefit, for at least some Storage Administrators, is that it keeps all CA Allocate DASD Space and Placement configurations in a single library. With a good system for naming the config Implementation 141

142 members, sysname sections, or both, this naming might even improve the ability to keep them organized. The system can also be useful for managing or assisting remote sites. That is, a central Storage Administrator can configure all CA Allocate DASD Space and Placement systems for an enterprise in one library. The Storage Administrator can simply distribute that one library to all the remote sites. Implementing Method 1 (unique parmlibs per system) Create a separate started task procedure (VAM proc) for each CA Allocate DASD Space and Placement system. Configure the parmlib that is specified on the //PARMS DD for its associated system. Implementing Method 2 (common parmlib, different members per system) This method also requires that you create a separate started task procedure (VAM proc) for each system. Instead of changing the local parmlib, change the CONFIG=, VSYS=, or both parameters on the EXEC statement to identify the proper member name, section name, or both. Configure the appropriate members and sections for each system. More information: Configure Parmlib Member CONFIG (see page 142) Configure Parmlib Member CONFIG This example assumes an approach of creating multiple <VSYS=sysname> sections within the same CONFIG member. The EXEC statement in the supplied procedure looks like the following example: //VAM PROC //VAM EXEC PGM=VDSST451,REGION=0M,TIME=1440, // PARM='CONFIG=CONFIG,VSYS=ALLOCATE' The config member is CONFIG, and the VSYS section is named ALLOCATE. As seen in the SAMPCONF member in the CCTVJCL target library of your SMP/E Zone, the <VSYS=ALLOCATE> section looks like the following example: <VSYS=ALLOCATE> VKGPARMS=VKGPARMS VSYS SECTION FOR CA ALLOCATE PARMLIB MEMBER WITH YOUR SYSTEM PARAMETER OVERRIDES You can define another CA Allocate DASD Space and Placement system, to run on System 1. Perform the following steps: 1. Duplicate the entire <VSYS=ALLOCATE> section within the CONFIG member. 2. Give an appropriate name to the second copy, such as <VSYS=VAMSYS1>. 3. Modify the copied VKGPARMS statement to VKGPARMS=VAMPSYS1. For example, the result of previous steps 1-3, the config member would look like this example: Implementation 142

143 <VSYS=VAMSYS1> VSYS SECTION FOR CA-ALLOCATE ON SYSTEM 1 VKGPARMS=VAMPSYS1 PARMLIB MEMBER WITH SYSPARM OVERRIDES FOR THIS SYSTEM 4. Create member VAMPSYS1 by copying member VKGPARMS, and customize it for the new system. 5. Repeat the previous steps for each CA Allocate DASD Space and Placement system. Note: Blank lines are allowed in the CONFIG member, as are comment lines. Comment lines must start with an asterisk in column 1. Use Pattern Matching Characters Patterns are formed by specifying non-blank characters. The patterns are delimited by blanks, not quotes. Any ASR constant that is not numeric (that does not begin with digits 0 through 9), or a string (that is not contained within single quotation marks), is considered a pattern, even if it does not contain pattern-matching characters. A pattern without pattern-matching characters works like a string constant, but goes through a slightly longer code path. Patterns can contain the following special characters: percent sign (%) Takes the place of any single character during a comparison. single asterisk (*) Takes the place of any number of characters (including 0) during a comparison. double asterisk (**) Takes the place of any number of data set name nodes (including 0) during data set name comparisons. question mark (?) Takes the place of any single numeric digit (in the range '0' through '9') during a comparison. Examples SYS%.**.PROCLIB Matches any PROCLIB that starts with SYS and one character SYS?.**.PARMLIB Matches any PARMLIB that starts with SYS and one digit **.*DMS*.** Matches any data set with DMS in it MVS* Matches any volume that starts with MVS *RES Matches any volume that ends with RES Implementation 143

144 Create a Storage Group Definition A storage group is a named set of disk volumes, that is, a pool of volumes. Storage groups are formed based on volume serial numbers so that instead of managing hundreds of volumes, the Storage Administrator can oversee a handful of storage groups. Every volume included in a pool (storage group) must be defined within the storage group definition member. CA Allocate DASD Space and Placement does not manage volumes that are undefined to any pool. A volume can be defined to more than one pool. The following two kinds of volume pools can exist: Non-SMS-managed volumes Non-SMS-managed volumes are contained in non-sms pools. The CA Allocate DASD Space and Placement non-sms volume selection process uses these volumes. SMS-managed volumes Only the Subpooling of SMS-managed Storage Groups feature uses these volumes. SMS pools contain a subset of the volumes belonging to an existing DFSMS storage group. CA Allocate DASD Space and Placement uses these to influence the DFSMS volume selection process. Storage groups are defined by creating a member in a library. The default name for the member is VDSTORGP. Each 80-byte record contains the following four column-dependent parts: Volume Serial Number (see page 144) Free-Space Threshold Percentage (see page 145) Include/Exclude Flag (see page 145) Storage Group Names List (see page 145) Volume Serial Number In columns 1 through 6, code the volume serial number, left justified, filled with blanks to the right if it is shorter than six characters. The volume serial can contain an asterisk (*), percent sign (%), or a question mark (?) as pattern matching characters. The question mark can only match one numeric digit in the range 0 through 9. The asterisk can match any number of characters from zero to six. The percent sign can only match one character. The following table is a sample of how pattern matching works (where x is any valid character): Pattern ISP* LABS5% *RES VOLSERs Matched ISP, ISPx, ISPxx, and ISPxxx LABS5x RES, xres, xxres, and xxxres Implementation 144

145 Pattern VOLSE? VOLSERs Matched Matches if volser is VOLSE0, VOLSE1, VOLSE9 Free-Space Threshold Percentage In columns 10 and 11, code the two-digit free-space threshold percentage. The percentage number can be from 00 to 99. The percentage is the target free-space threshold that CA Allocate DASD Space and Placement tries to maintain on the volume. For more information, see Volume Selection Logic for Non- SMS-managed (see page 58). CA Allocate always chooses to allocate to a volume on which the free-space threshold can be maintained before it chooses one that would violate the target free-space threshold. Maintain some level of free space on volumes with data sets that must grow into secondary extents. The presence of such a free-space threshold, maintained during primary space allocations, increases the likelihood that space is available when the data sets extend into their secondaries. If either column contains a blank, a zero is used in its place. This zero means that a free-space threshold of 5 is equivalent to 05. A free space threshold of 5 followed by a blank is equivalent to 50. Free Space Threshold values are not applicable to the SMS subpools that might optionally be defined in the CA Allocate DASD Space and Placement storage group table. Free Space Threshold values are not applicable when the VOLUME_SELECTION_BY_LEAST_FREESPACE variable is assigned a value of Y by your Allocation Selection Routine. Include/Exclude Flag In column 15, code a blank or I to include a volume (or pattern) in a STORGRP. In column 15, code an E to exclude a volume (or pattern) from a STORGRP. If a volume (or pattern) is both included and excluded from a STORGRP, the exclude volume overrides the include volume. Storage Group Names List In columns 21 through 72, code a list of one or more storage group names to which the volume or volume pattern belongs. Each name must be separated from the next by a comma (no blanks). If you need more room to add names, simply start another entry with the same volume serial number or pattern. A storage group name can be from 1 to 8 characters in length. Some other CA products recognize storage group names. CA Disk can recognize them through the VAMPOOL parameter, and CA Vantage recognizes them through the INCLVAMS parameter. If a storage group contains SMS-managed volumes, CA Disk will ignore these volumes in its VAMPOOL processing. Storage group names have no connection with esoteric or generic unit names, volume serial numbers, or anything else outside of CA Allocate. Storage groups can be named with esoteric or generic unit names, or with volume serial numbers. See Sample Storage Group Definition (see page 146). A storage group name can be used in the ASR in either the STORGRP or SMS_SUBPOOL_SG variables by using the SET statement. For non-sms, after a storage group is set in the ASR, only those volumes in that STORGRP are considered eligible for selection. For SMS, after a subpool is set, only those volumes Implementation 145

146 in that SMS_SUBPOOL_SG are considered eligible for selection. For more information, see the description of SMS_SUBPOOL_SG 29. More information: Syntax for Storage Group Definitions (see page 146) Sample Storage Group Definition (see page 146) Syntax for Storage Group Definitions A blank space in column 1 turns the whole record into a comment. A blank space after a storage group list changes the rest of the record into a comment. Note: An asterisk in column 1 is considered a leading pattern-matching character of the volume serial field. Sample Storage Group Definition The following illustration shows the sample storage group definition that is contained in installation library member VDSTORGP. ***************************** Top of Data ********************************* =COLS> VOLUME FREESPACE STORAGE SERIAL THRESHOLD GROUP(S) ISP* 10 ISPDA COMMENTS MAY BE PUT HERE ISP801 E ISPDA EXCLUDE ISP SCR* 20 SCRATCH SCR500 E SCRATCH EXCLUDE SCR LABS8% 20 PRIMARY, LABS9% 20 PRIMARY, *RES 00 SYSTEM PRF* 00 CACHEDB WRK00% 30 SCRATCH,MULTI WRK SCRATCH,OVERFLOW, MVS* 00 OVERFLOW CAT* 00 SYSTEM DBS* 20 DATABASE DMS%%% 20 I TEST DMS9* E TEST EXCLUDE DMS9** ***************************** Bottom of Data ********************************* In the previous illustration, 11 storage groups that can later be used (SET) in the ASR are defined. When defining a storage group, a volume serial number (or pattern) is related to a storage group name or names Implementation 146

147 Create a Key Data Set Names Member The optional KEYDSN parmlib member lets you identify a list of Key Data Sets in your environment. These Key Data Sets must never be placed on the same volume as any other data set in the list. Put one data set name per line, starting in column 1. The sample that is provided in the CCTVJCL library member KEYDSN is: PROD.DATA.SET PROD.DATA.SET PROD.DATA.SET3 Warning! This feature is resource-intensive. Carefully consider the system impact before using the feature. Create an Allocation Selection Routine An Allocation Selection Routine (ASR) lets Storage Administrators write simple logic statements. The statements define.and enforce the standards of their installation for data set allocations and disk space quota limits. The ASR employs a CLIST-like language that gives great flexibility and simplicity in defining how CA Allocate DASD Space and Placement operates. This CLIST-like language allows a simple program with IF-THEN-ELSE logic statements to be created. The approach makes obsolete the old-style macros and fixed-field control statement method of specifying options to a software package. Across all 14 environments, more than 250 variables can be checked. Many of these variables can be modified. For example, during data set allocations, the ASR can change the block size, primary allocation quantity, secondary allocation quantity, and expiration date. Also, 102 user variables are provided for use as work areas or arguments to a user exit, or to remember the original values of variables you are changing in case you want to cancel the change. The ASR supports the following statements: FILTLIST name INCLUDE(list) [EXCLUDE(list)] IF expression THEN statement [ELSE statement] DO END SET &variable = expression WRITE 'text &variable' EXIT [CODE(number)] COPYBOOK 'member' CALL VDSEXIT? CALL QUOTACHK For more information about each ASR statement, see ASR Statements (see page 148). Implementation 147

148 More information: ASR Statements (see page 148) ASR Constants (see page 157) ASR Operators (see page 158) ASR Functions (see page 160) ASR Statements ASR statements are made up of different parts or components. The first component is always a keyword, such as FILTLIST, IF, and SET. The keyword tells CA Allocate DASD Space and Placement what this statement does. The remaining components of an ASR statement are constants (see page 157), operators (see page 158), functions (see page 160), and variables 30. The general syntax for all ASR statements is as follows: Each statement must begin with a keyword, and the keyword must be entered entirely in uppercase characters. Statements can be entered in free format in columns 1 through 72. Wherever one blank is allowed, any number of blanks can be used. Column 72 of a given line is logically connected to column 1 of the next line. Comments are started with a /* and ended with an */. Comments can span multiple lines before reaching the ending delimiter (*/). Note: If a comment (/*) is started but not ended, ALL characters on ALL lines through to the next */ or the end of all statements are considered a single long comment. Lowercase characters are unequal to their uppercase counterparts; a and A are not the same. Important! All names (variables, keywords, functions) must be entered in uppercase, or they are not recognized. Filter list names (FILTLIST), and string (character) constants can be either uppercase, lowercase, or mixed, but they must be consistent throughout, or they are considered different variables and errors occur Implementation 148

149 More information: The COPYBOOK Statement (see page 149) The FILTLIST Statement (see page 150) The IF Statement (see page 151) The DO Statement (see page 152) The SET Statement (see page 152) The WRITE Statement (see page 153) The EXIT Statement (see page 155) The CALL Statement (see page 157) The COPYBOOK Statement COPYBOOK 'name' The COPYBOOK statement allows identical blocks of ASR statements to be referenced in multiple places in your ASRs. Use the COPYBOOK statement when the same logic is needed in multiple environments, or to increase the readability of your ASRs. A COPYBOOK is a member in the partitioned data set referenced by the PLSPRGDS statement in VKGPARMS. The COPYBOOK can contain other COPYBOOKs, up to 20 levels. Recursive COPYBOOKs are not allowed. For example, COPYBOOK 'A' cannot use COPYBOOK 'B' if COPYBOOK 'B' uses COPYBOOK 'A'. The following examples show one way COPYBOOKs can be used: VDSPROG ASR statements COPYBOOK 'POOLING' statements COPYBOOK 'FILTERS' statements Sample COPYBOOK ASR Statement: ASR.PARMLIB VDSPROG COPYBOOK 'FILTERS' IF &USER NE &USERS THEN EXIT CODE (0) IF &VAMENVIR = 'ALLOC' THEN DO COPYBOOK 'POOLING' IF &DSTYPE = 'PERM' THEN SET &RLSE = 'Y' END IF &VAMENVIR = 'DEFINE' THEN DO COPYBOOK 'POOLING' SET &INDEXSEP = 'Y' END Sample COPYBOOK ASR Statement: POOLING Implementation 149

150 File Edit Confirm Menu Utilities Compilers Test Help EDIT.ASR.PARMLIB POOLING Columns Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &ANYVOL = &VOLS THEN DO \ SET &FINVS = 'Y' \ SET &POOLSUB = 'Y' \ SET &UNIT = 'SYSALLDA' \ COPYBOOK END --> 'POOLING' ELSE / Statements DO / SET &STORGRP = 'SSLDA' / SET &FINVS = 'Y' / SET &UNIT = 'SYSALLDA' END ***************************** Bottom of Data ********************************* Sample COPYBOOK ASR Statement: FILTERS File Edit Confirm Menu Utilities Compilers Test Help EDIT.ASR.PARMLIB FILTERS Columns Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* FILTLIST &USERS INCLUDE(ISP*) FILTLIST &VOLS INCLUDE(SSL*,DMS9*) \ COPYBOOK EXCLUDE(DMS903) -> FILTERS FILTLIST &PROD INCLUDE(SYS1.**,SYS2.**) / Statements FILTLIST &QVOLS INCLUDE(SSL*) ***************************** Bottom of Data ********************************* Note: Do not use a FILTLIST statement if the COPYBOOK is inside a DO-END group. The FILTLIST Statement FILTLIST name INCLUDE(list) [EXCLUDE(list)] The FILTLIST statement allows the creation of a list of volumes, users, groups, data set names, and so on, to be used in a comparison expression. Whenever multiple comparisons are being done against the same variable (like checking USERID against all system programmer names), a FILTLIST statement can simplify and clarify the comparison, making it easier to maintain. The name of the filter list must start with a letter and have no more than 31 alphanumeric characters. Do not use names that conflict with system unit names or ASR variable names. The FILTLIST INCLUDE keyword includes items that are contained in its list, while EXCLUDE excludes items contained in its list. The lists are composed of constants (strings or patterns only) separated by commas. Null values cannot be used. If the variable matches items in both INCLUDE and EXCLUDE lists, it is excluded. For example, consider the following statement: Implementation 150

151 FILTLIST &WORK INCLUDE(WRK*,SCR*) EXCLUDE('WRK004',SCR00%) IF &ALLVOL=&WORK THEN EXIT CODE(0) In the preceding example, the ASR is exited when all the volumes start with WRK or SCR, but continues when it encounters volume WRK004 or any volumes beginning with SCR00. The following example shows how to continue a filter to multiple lines: FILTLIST &NEWV INCLUDE (WRK*, MEM*) EXCLUDE (WRK80*,'MEM001','MEM002','MEM003', 'MEM999') IF &ALLVOL=&NEWV THEN EXIT CODE(0) The ASR is exited when all the volumes specified on the allocation request begin with WRK or MEM, except when it encounters a volume beginning with WRK80, or the volumes MEM001, MEM002, MEM003, or MEM999. The ampersand (&) before the filter list name is optional when defining the filter list, but is required when using it in a comparison expression. Notice in the preceding examples that the patterns do not have single quotes around them, and string constants do. For more information about patterns and constants, see ASR Constants (see page 157). The following rules apply: The FILTLIST statement is not executable; it merely declares a list. The statement must appear in the ASR before its first use in an IF statement. Do not use a FILTLIST statement within any IF construct or DO-END group. You cannot code a COPYBOOK inside a DO-END group if that COPYBOOK includes a FILTLIST statement. In general, to avoid problems, place FILTLIST statements first in the ASR. The ASR does not compile for the following situations: ** in the EXCLUDE portion of the FILTLIST If ** is not the only item in the INCLUDE portion of the FILTLIST, for example: INCLUDE(**, SYS1.PARMLIB). The IF Statement IF expression THEN statement [ELSE statement] The IF statement first evaluates the expression. If the expression is true (evaluates to a nonzero number), the statement following the THEN keyword is executed. If the expression is false (evaluates to zero), the statement is skipped and an optional ELSE statement is executed. The statement that is placed after the THEN and ELSE keywords can be simple or compound. A simple statement is one executable statement (such as IF, SET, WRITE, EXIT, or CALL). A compound statement is one or more statements that a DO-END combination surrounds. For more information, see The DO Statement (see page 152). Implementation 151

152 The Boolean operators (AND, OR), and comparison operators (equal, not equal, and so on) that can be used in an expression are described later in this section. The IF statement is the only flow of control statement that is supported. Because no GOTO or WHILE construct exists, the flow always runs from the top to the bottom one time during each invocation of the ASR. The DO Statement DO END The DO statement begins a compound statement. The compound statement ends with the END keyword. Use this construct to do more than one action in an IF statement. Without the DO-END, only one action can take place (a simple statement) in an IF statement. You can actually use DO-END all the time, because one statement within the DO-END delimiters is exactly as valid as hundreds of statements. An example of the DO-END is shown in the following illustration: File Edit Confirm Menu Utilities Compilers Test Help EDIT.ASR.PARMLIB DO-END Columns Command ==> Scroll ==> CSR ******************************** Top of Data ********************************* IF &DSN = SYS1.** THEN DO WRITE 'ALLOCATING SYSTEM DATA SET &DSN' SET &STORGRP = 'SYSTEM' END ELSE DO WRITE 'ALLOCATING NON-SYSTEM DATA SET &DSN' SET &STORGRP = 'PRIMARY' END *************************** Bottom of Data ********************************* The SET Statement SET &variable = expression The SET statement assigns a new value to a variable. Only output variables can be set. The output variables are those variables that are designated with an 'O' in one or more environments in Implementation (see page 108). A numeric variable can be set only to a numeric expression. A character variable can be set only to a character expression. The following examples are valid SET statements: Implementation 152

153 SET &N0 = /* numeric */ SET &C0 = 'SYSALLDA' /* character */ SET &EXPDT = &N0 /* numeric */ SET &UNIT = &C0 /* character */ N0 and C0 are user work variables, described later in this section. The output variable STORGRP is special, because it can be set to a list of storage group names. Multiple storage group names can be assigned to the STORGRP variable by separating each name with a comma. For example: SET &STORGRP = 'PRIMARY','SCRATCH' The WRITE Statement WRITE 'text &variable' The WRITE statement issues a message to the job or userid requesting the allocation. This message enables the ASR to warn users about violations or to tell them about redirections or other changes to their allocations. TSO users receive the message at the terminal. For other jobs and started tasks, the message appears in the job log. Also, it is possible to direct a message to specific TSO users logged on to TSO when the message is sent. User-specific messages are not saved. The message to be displayed must be enclosed within single quotation marks ( ' ). The message can contain text, variables, or both and can span multiple lines, but every character between the quotation marks counts, even blanks. The text is displayed as written. A variable must begin with a single ampersand. Any variable found in the WRITE statement is replaced with the value contained in the variable. Only as many character positions as are necessary to display the value are taken up on the message line. Important! The total number of characters in the output message line cannot exceed 79 characters. Anything after the first 79 characters is ignored meaning that WRITE statements spanning multiple lines are likely to be truncated because each line of an ASR member contains 72 characters. Consider the following WRITE statements: WRITE 'A NORMAL ONE LINE MESSAGE' WRITE 'AN UNUSUAL MULTI LINE MESSAGE THAT GOES TO COLUMN 72 HERE ====>X AND CONTINUES ON TO THE NEXT LINE. ONLY FIRST 79 CHARS ARE DISPLAYED' WRITE '' WRITE '' WRITE 'A WRITE STATEMENT THAT CONTINUES TO MULTIPLE LINES GIVES THE IMPRESSION IT IS NOT WORKING' Implementation 153

154 Each WRITE statement is syntactically correct and does not generate compile errors. But the last two lines are truncated after the 79th character of text which includes the blanks after CONTINUES and before TO. The statement: WRITE 'DSN = &DSN, DISP = &DISP' Might expand to: DSN = TIM1.VERY.VERY.VERY.VERY.LONG.DATASET.NAME, DISP = NEW The maximum length of each character variable is listed in the variable description. For numeric variables, the maximum length is always ten characters (although for variables like TODAY, which contains a date (89198), the length is always five characters). To display an ampersand (&), or a single quotation mark (') in the output message line, put two ampersands (&&), or two single quotation marks ('') in the WRITE statement text. The statement: WRITE '&&DSN = ''&DSN''' Can expand to: &DSN = 'TIM1.DATASET.NAME' Warning! Subscript operators and the SUBSTR (see page 160) function are not permitted in the WRITE string. They can, however, be referenced as follows: SET &C0 = &DSN(3) /*SUBSCRIPTED DATA SET NAME*/ WRITE 'THIS IS A &C0 TYPE DATA SET' SET &C1 = &SUBSTR(3:3,&USER) /*SUBSTR FUNCTION*/ WRITE 'YOU ARE NOT ALLOWED ON THAT PACK, &C1' The format for sending a message to a specific TSO USERID is: WRITE '@@&USER message text...' WRITE '@@&HSMUSER message text...' WRITE '@@userid message text...' Where &USER or &HSMUSER is the USERID that these &variables reference, and userid is a specific TSO USERID. The format for sending a message to a CA Vantage user is: Implementation 154

155 write message text...' Where userid is the TSO USERID of a CA Vantage user. For messages to reach a user TSO session, set the following parameters: Sysparm: PLSOPT98 (N) The users of TSO profile must set the operand "WTPMSG". The default of this operand is "NOWTPMSG". To change this operand, use the TSO command PROFILE WTPMSG. The EXIT Statement EXIT [CODE(number)] The EXIT statement causes the ASR to stop executing immediately. When CA Allocate DASD Space and Placement exits the ASR, it writes changed variables back to MVS. CA Allocate DASD Space and Placement then returns to the calling environment with any return code that was specified (the default return code is 0). Following the last statement in the ASR, an implied EXIT CODE(0) is executed automatically. If the CODE keyword is omitted, a zero return code is assumed. Only specify the code values in the following table. Enviro nment RC Description ACS 0 Change SMS constructs. Ot her Do not change SMS constructs, return code &ACSRC, reason code &ACSRSN. ALLOC 0 Continue with allocation. 4 Cancel the allocation. DEFIN E 0 Continue with the VSAM define. Ot her Cancel the request. Return the specified return code as the error return code to the issuer of the Catalog Management request. EOV EOV_V SAM 0 Attempt to select another volume from the storage group that has either been implied (&POOLSUB) or explicitly specified (&STORGRP). If the volume selection is successful, the original out of space condition is avoided. 4 Allow the job to fail for the original out of space condition. Implementation 155

156 Enviro nment RC Description EXTEN D 0 Allow extend. 4 Abend E37-0C. OLD 0 Make variable changes. Ot her Ignore all other variable change requests. QREBU ILD 0 Add this volume to the list of volumes scanned. 4 Do not add this volume to the list of volumes to be scanned. QSCA N An y The return code is not used for QSCAN. QUOT A 0 Continue with request. 4 This volume serial is rejected. 8 Cancel the request. Only available when Optional Maintenance PI is installed. RELEA SE RENA ME SCRAT CH Same as SPACE. Same as SPACE. Same as SPACE. SPACE 0 Continue with request. 4 This volume is rejected. 8 Cancel the request. Only available if Optional Maintenance PI is installed. Unsupported values are handled as follows: 1, 2, and 3 result in a 0 5, 6, and 7 result in a 4 All other numbers result in the highest valid return code. For example, 9 becomes 8 in SPACE and 4 in ALLOC. Implementation 156

157 For the SPACE, EXTEND, RELEASE, SCRATCH, and RENAME environments, IBM defines the meaning of the return code for the IGGPRE00 DADSM preallocation exit. This place is the hook point where CA Allocate DASD Space and Placement receives control for these environments. In the DEFINE environment, an EXIT CODE(0) statement causes the volume selection to take place. Any exit code other than zero causes CA Allocate DASD Space and Placement to return this value to the issuer of the catalog management request as the error return code. If a nonzero exit code is specified, variables REASON and FAILMOD might also have been set before the EXIT statement to qualify further the reason for failing the allocation. In the ACS environment, an EXIT CODE(0) causes any of the four SMS constructs that were set in the ASR and requested for this ACS invocation to be returned to the requestor of the ACS processing. An exit code other than 0 is returned to the requestor of the ACS processing, with the ACS reason code that is set in variable &ACSRSN. None of the four SMS constructs set in the ASR is returned to the requestor. Regardless of the exit code value, the values in the ACS return code variable (&ACSRC) and the ACS reason code variable (&ACSRSN) are returned to the requestor of the ACS processing. They are returned whether they are set in the ASR or left as they were upon entry to the ASR. Note: When using CA Allocate DASD Space and Placement to deny allocations of other program products, exiting with anything other than EXIT CODE(0) can cause unpredictable results. The CALL Statement CALL VDSEXIT? CALL QUOTACHK The CALL statement can invoke any one of ten possible User Exits (VDSEXIT0 through VDSEXIT9) in any ASR environment and the QUOTACHK internal routine in the QUOTA environment. For more information, see User Exits (see page 175). For more information about QUOTACHK, see VDSPROG ASR and the QUOTA environment in the Allocation Selection Routines and Environments (see page 189). ASR Constants Three kinds of constants can be specified in an Allocation Selection Routine: numbers, strings, and patterns. Numbers Numbers must be unsigned and less than or equal to Strings Strings can contain any character, and single quotation marks(') delimit them. Two adjacent single quotation marks ('') result in a single quotation mark in the string. Two adjacent ampersands (&&) result in an ampersand in the string. Strings can be up to 255 characters in length. Implementation 157

158 Note: An empty or null string is designated as follows: ' '. ASR Operators ASR statements can include Boolean, comparison and subscript types of operators. Boolean Operators AND or && OR or Designate a logical AND. Designate a logical OR. All AND comparisons are evaluated before OR comparisons. Parentheses are used to override this normal order of evaluation. If multiple parentheses are used, the condition within the innermost set of parentheses is tested first, and evaluation proceeds outward. For example: IF (&USER='TIM' OR &USER='LAL') AND &HLQ='SYS1' THEN EXIT Without the parentheses, the AND operation is done before the OR operation. In other words, the AND operator has a higher precedence than the OR operator. Comparison Operators The abbreviations that are shown in the following table or the mathematical symbols can be used interchangeably throughout the ASR. Abbreviation Symbol Description EQ = Equal NE = Not equal LT < Less than GT > Greater than LE <= Less than or equal GE >= Greater than or equal Numeric comparisons are done unsigned. String comparisons are done in EBCDIC collating sequence. Pattern comparisons return either equal or not equal, because it is impossible to tell whether a pattern is greater than or less than a string. The same applies to list comparisons. (ANYVOL, ALLVOL, and STORGRP can be lists of items.) Patterns and filter lists can appear only on the right side of a comparison operator. Implementation 158

159 The following sample is not valid and the ASR compiler fails it: IF TEST* EQ &DSN(3) THEN... The following sample is valid: IF &DSN(3) EQ TEST* THEN... Subscript Operator Certain variables can take the subscript operator (numeric expression). A subscript that is out of range returns the first element of the subscripted variable. Subscript operators begin with the integer 1. The following variables can take the subscript operator: ACCT_JOB ACCT_STEP CATDSN DSN DSND DSNI HSMDSN LIKE NEWNAME QUOTAALLOCS QUOTALIMITS QUOTANAMES QUOTAPERCENTS QUOTASTATS QUOTAWPERCENTS REFDD SECMODEL In the following example, the DSN variable contains the value 'TIM1.SAMPLE.DATASET' which results in: &DSN(1) = 'TIM1' &DSN(2) = 'SAMPLE' &DSN(3) = 'DATASET' ACCT_JOB contains job accounting information from the JOB statement of a job. The ACCT_STEP variable contains step accounting information from the ACCT= parameter on the EXEC JCL statement Implementation 159

160 for the step that is executing. Both of these items can contain multiple pieces of data that can be picked up individually using the subscript operator. If no subscript operator is used on the ACCT_JOB or ACCT_STEP variables, only the first piece of information is picked up (as if the subscript of 1 were used). However, when the CATDSN, DSN, DSND, and DSNI variables are used without a subscript operator, the entire data set name (no default subscript), is picked up. Subscript operators cannot be used inside a WRITE statement (see page 153). Instead, a user variable (C0 to C40) can be assigned the subscripted value, and that in turn can be used in a WRITE Statement. ASR Functions Two functions are available in ASR, the &SUBSTR and the Arithmetic functions. The &SUBSTR Function &SUBSTR(position[:length],string expression) The &SUBSTR function returns a substring, beginning at position for the length when one is specified. Otherwise, it returns the rest of the string expression out to the end. The first position is 1, not 0. This example shows how a portion of a DSNAME can be set in a user variable. IF &DSN = LABS.DMS???.CCTVLOAD THEN DO SET &C0 = &SUBSTR(4,&DSN(2)) /* GET THE??? RELEASE NO.*/ WRITE 'THE RELEASE IS &CO' END The following example shows how the first three characters of the job name can be placed in a user variable for later use in the ASR: SET &CO = &SUBSTR(1:3,&JOB) IF &CO = 'XXX' THEN DO... END The &SUBSTR function can be used to look at any part of the character variables. The &SUBSTR function cannot be used inside a WRITE statement. Instead, a user variable (C0 31 to C40 32 ) could be assigned the substring value, and that in turn could be used in a WRITE statement Implementation 160

161 Arithmetic Expressions Arithmetic expressions can be substituted for any numeric variable in the ASR. Constants, numeric variables, and operators can be used in expressions to set values within an ASR. The ASR language supports the following arithmetic operations: + Symbol Specifies addition operation. - Symbol Specifies subtraction operation. * Symbol Specifies multiplication operation. / Symbol Specifies division operation (results in integer dividend of division). % Symbol Specifies modulo operation (results in integer remainder of division). A space must precede and follow arithmetic operators to distinguish them from pattern-matching operators. The ASR language uses the basic rules of algebra when evaluating expressions and is governed by the following: All expression results are calculated based on operator precedence as defined below: Multiplication, division, and modulo are carried out before addition and subtraction operations. Operations of equal precedence are evaluated left to right. Open parentheses "("and close parentheses")" are used to cluster operations. The operations within parentheses are evaluated first, starting with the innermost grouped functions when multiple sets of parentheses are used. Precision in all intermediate and final results is subject to the following: Signed 31-bit integer values that range from through Significant digits are lost in overflow conditions that exceed the 31-bit range Decimal values are lost Division by zero results in zero The following equation demonstrates the rules of precedence and the precision of calculations: 7 x x 4 = ((7 x 4 ) + (8 3 )) - (2 x 4) = (28 + 2) - 8 = 22 Implementation 161

162 In the preceding equation, the intermediate calculations for the multiplication and division operations are performed before the addition and subtraction operations are completed. Also, notice that the decimal portion of the intermediate result that is produced when 8 is divided by 3 is lost. The following ASR code fragment demonstrates the use of ASR arithmetic. IF &VAMENVIR = 'ALLOC' THEN /* IN THE ALLOC ENVIRONMENT */ DO SET &PRIMARY = &PRIMARY * 3 / 2 /* INCREASE PRIMARY ALLOCATION */ SET &BLKSIZE = ((4096 / &LRECL) * &LRECL) /* BY 50% AND ROUND THE BLKSIZE */ END /* TO THE NEAREST 4K BLKSIZE */ Create an Exclude Jobs Names Member The optional EXCLJOB member can be used to identify a list of batch job names, started task names, or TSO Userid names in your environment that are exempt from essentially all CA Allocate DASD Space and Placement processing. This feature is similar to the one available at a step level when using the special bypass DDname specified in the sysparm PLSBYPAS. The difference is that the deactivation of CA Allocate DASD Space and Placement applies to the entire job and no JCL changes are needed to the jobs themselves. The CCTVJCL library member SAMPEXCL contains the following example of what EXCLJOB entries look like: SAMPLE EXCLJOB MEMBER TESTEXCL * EXCLUDE EXPLICIT 8 CHARACTER JOB/STCNAME 'TESTEXCL' USER001 * EXCLUDE EXPLICIT 7 CHARACTER TSO ID 'USER001' ALL/ * EXCLUDE ALL JOBS, STC, TSO IDS STARTING WITH 'ALL' Put one job name per line, starting in column 1. Lines with a blank in the first column are considered comments and are not loaded into the system memory. All characters following the first blank on a line are also considered comments and are not loaded into the system memory. A forward slash (/) on a line indicates a job name prefix. In the preceding example, ALL/ represents a job name prefix, and any job, STC, or TSO Userid with ALL as the first three characters is considered exempt from essentially all CA Allocate DASD Space and Placement processing. The contents of the EXCLJOB member that CA Allocate DASD Space and Placement reads during INSTALL and REFRESH operations is written to the SYSPRT DDname that is associated with the JCL used for the INSTALL or REFRESH operation. The EXCLJOB member must reside in the same data set as your ASRs: the one noted as the value of sysparm PLSPRGDS in the sysparm override member of your parmlib. EXCLJOB entries are not able to bypass: Any processing that is associated with the optional Quota selectable unit. Any ACS environment processing of JCL DD statements that occurs during job initialization. Implementation 162

163 Operation The console operator interacts with CA Allocate DASD Space and Placement by using the START (see page 164), MODIFY (see page 164), and STOP (see page 165) commands. You can test your parameter files (see page 163) without installing the product into your operating system. These parameter files include VKGPARMS, VDSPROG, QSCAN, QREBUILD, QCONFIG, and VDSTORGP. When the QSYNC process of the Quota selectable unit is used, the started task must run always (RESIDENT=YES). For a detailed description of the important periodic actions that require this residency, see The QSYNC Process (see page 183). When Quota is not used, the started task does not need to run to let the interface control allocations. In this case, the started task only starts, modifies, and stops the interface. The RESIDENT= subcommand (see page 173) controls whether the started task remains running. More information: Testing Parameter Files (see page 163) Operator Command Parameters (see page 163) START Command (see page 164) MODIFY Command (see page 164) STOP Command (see page 165) Action Parameters (see page 166) Change Parameters (see page 169) Testing Parameter Files You can syntax check the parameter files before installing the product by using the TESTASRS member of the CCTVJCL library. TESTASRS executes the compiler in standalone batch, instead of from the started task. If your site is licensed for Allocation Manager and Quota, all parameter files are required. If your site is licensed only for the Allocation Manager, only VKGPARMS, VDSPROG, VDSTORGP, and CONFIG are required. Operator Command Parameters The START and MODIFY commands can be used with action parameters (see page 166) and change parameters (see page 169). Action parameters can have one or more associated change parameters. Change parameters usually, but not always, require an action parameter. If the started task is up, specify the START (S) command with the desired parameters. If the started task is already running, specify the MODIFY (F) command with the desired parameters. The START and MODIFY syntax is slightly different, as the following examples illustrate: Operation 163

164 START Command S VAM,PARM=('parameter1,parameter2,parameter3') MODIFY Command F VAM,parameter1,parameter2,parameter3 In both commands, the parameters are separated by commas. Spaces indicate the end of the data. Do not use anything except commas. Note: Throughout this section, the started task (STC) is referred as VAM. VAM is the default name that is distributed in the CCTVJCL library. START Command The START command can be used with action parameters (see page 166) and change parameters (see page 169). S VAM,PARM=('option1,option2,option3,...option') You can override the default options that are defined in the VKGPARMS parmlib member. Specify new values on the EXEC statement in the VAM cataloged procedure, or enter them at the console. The new values become the temporary default until another command (such as REFRESH or PARMREF) is issued. Important! When RESIDENT=YES is used, any START command, even one done to view status, leaves the started task running. If a started task is already running when the START command is entered, two started tasks run simultaneously. Both try to respond to future MODIFY or STOP commands. MODIFY Command The MODIFY command changes the configuration of the started task that remained active after it was started and installed with RESIDENT=YES. The START and MODIFY commands can be used with action parameters (see page 166) and change parameters (see page 169). The MODIFY and START parameters are identical, except where noted in the parameter descriptions. The MODIFY command can be used to switch to a new ASR. The new ASR must also reside in the data set that the PLSPRGDS parameter specifies in the VKGPARMS parmlib member. For example, the following command switches to the ASR in member NEWPROG: F VAM,REFRESH,PROG=NEWPROG The MODIFY command can generate diagnostic data for any job or started task without requiring special diagnostic DD statements. For example, the following commands turn on and turn off diagnostic tracing for the CA Disk Backup and Restore DMSAR (Auto Restore) started task: Operation 164

165 F VAM,DIAGS=DMSAR F VAM,DIAGS=DMS* F VAM,DIAGS= "on" "on" for jobs and tasks starting with "DMS" "off" The following MODIFY commands change the operating mode of this product from active to dormant, or dormant to active: F VAM,ACTIVE F VAM,DORMANT The MODIFY command is the recommended way to remove this product. Unlike the STOP command, MODIFY does not terminate the started task when the task fails to uninstall itself. The following command initiates the shutdown: F VAM,REMOVE STOP Command The STOP command uninstalls the CA Allocate DASD Space and Placement interface: P VAM After the STOP command is issued, the started task removes the allocation hooks and terminates after a short wait. This delay is intentional; it permits allocations that are in progress to finish using the storage that the product frees. Note: The STOP command is not the recommended method of removing the product from the system. Instead, use MODIFY REMOVE (see page 164) as follows: F VAM,REMOVE The STOP command stops the started task, even when an error occurs. With MODIFY REMOVE, the started task does not stop when an error occurs. Otherwise, the commands are identical. After the product successfully uninstalls, it issues the following message to the SYSLOG: VAM000I CA Allocate SHUTDOWN COMPLETED Operation 165

166 Action Parameters The START and MODIFY commands can be used with the following action parameters: CLEANUP (see page 166) DECOMP (see page 166) INSTALL (see page 167) PARMREF (see page 167) REFRESH (see page 167) REMOVE (see page 168) STATUS (see page 169) QREBUILD Subcommand (see page 169) QRESETWM (see page 169) QSYNC (see page 169) Action parameters can have one or more associated change parameters (see page 169). Change parameters usually, but not always, require an action parameter. CLEANUP The CLEANUP option recovers from failed INSTALL, REMOVE, or STOP operations. If the started task is not running with RESIDENT=YES, enter the following operator command: S VAM,PARM=('CLEANUP') START Command If the started task is running with RESIDENT=YES, enter the following operator command: F VAM CLEANUP MODIFY Command CLEANUP attempts to remove every hook. If CLEANUP runs after some of the hooks have been removed, it tries to remove hooks that are not there. You can ignore the resulting "cannot remove" messages. DECOMP The DECOMP option creates a snapshot report of the ASRs, pools, and Quota Configuration File. This decompiled diagnostic report displays the current status of CA Allocate DASD Space and Placement on the operator console. The status shows how CA Allocate DASD Space and Placement was set up the last time it was installed or refreshed. The report is dynamically allocated to a SYSPRT file in the started task DDname 'VAMPTR'. Operation 166

167 Enter one of the following operator commands: S VAM,PARM=('DECOMP') F VAM,DECOMP START command MODIFY command INSTALL The PLSACTN parameter in the VKGPARMS parmlib member specifies the default action for the started task to take. The default action is INSTALL, which dynamically installs the allocation interfaces into the operating system. If compiler errors occurred on the first installation attempt and RESIDENT=YES was specified, the REFRESH and REMOVE commands are not applicable. The interface did not install successfully. Correct the compiler errors and retry the installation by using the INSTALL command: F VAM,INSTALL If the compiler errors persist and you want to remove the started task from the system, issue the STOP command: STOP VAM Note: To avoid potential compile problems during CA Allocate DASD Space and Placement startup, use the TESTASRS batch compiler. (see page 163) PARMREF The PARMREF option rebuilds the active system parameter table from scratch in the following manner: 1. Retrieve default values. 2. Apply current active values. (These values are the cumulative changes that have been made to the active system parameter table since the last INSTALL.) 3. Apply current VKGPARMS override values. (PARMREF dynamically invokes the REFRESH option to perform this step.) REFRESH The REFRESH option updates any parameter files that are changed after installation. These files are: Storage group definitions PLSSTRMB (VDSTORGP) Allocation selection routines PLSVDSMB (VDSPROG), PLSQRBMB (QREBUILD), PLSQSCMB (QSCAN) Operation 167

168 Quota configuration file PLSQCFMB (QCONFIG) Key data set separation member optional KEYDSN member in your PLSPRGDS data set Exclude jobnames member optional EXCLJOB member in your PLSPRGDS data set For example, use REFRESH with STORGP= and PROG= to change the member names of these two parameter files: F VAM,REFRESH,PROG=MYRULES,STORGP=MYPOOLS The REFRESH option modifies the active system parameter table in the following manner: 1. Retrieve current active values. 2. Apply override values that are included on the REFRESH command. For example, propagate the STORGP= and PROG= values into PLSSTRMB and PLSVDSMB in the active system parameter table. Important! Do not use the REFRESH option during high activity periods. Select a time when few allocations occur. If a REFRESH is done during the volume selection process, unpredictable results can occur. Note: If you use the VAMSPARE feature of CA Vantage Storage Resource Manager, REFRESH removes the temporary additions of volumes to CA Allocate DASD Space and Placement STORGRPs. For more information about the VAMSPARE function, refer to the CA Vantage Storage Resource Manager documentation. REMOVE The REMOVE option uninstalls CA Allocate DASD Space and Placement. If an error is encountered, the REMOVE process stops. If the started task is running with RESIDENT=YES, the task ends only upon successful completion of the REMOVE process. If the started task is running with RESIDENT=NO, it ends when the REMOVE process stops, regardless of errors. If the started task is not running with RESIDENT=YES, use the following START operator command to uninstall the product: S VAM,PARM='REMOVE' START command If the started task is running with RESIDENT=YES, use the following MODIFY operator command to uninstall the product: F VAM,REMOVE MODIFY command Operation 168

169 STATUS The STATUS option shows the current status of CA Allocate DASD Space and Placement: S VAM,PARM=('STATUS') F VAM,STATUS START command MODIFY command If the product is not installed, the following message appears: VAM0011 CA Allocate IS NOT INSTALLED If the product is installed, the following messages appear: VAM0012 CA Allocate IS RUNNING WITH PARAMETERS AS FOLLOWS: VAM0366 STORGRP = <VDSTORGP member name> VAM0366 PROG = <VDSPROG ASR name> VAM0366 QREBUILD = <QREBUILD ASR name> VAM0366 QSCAN = <QSCAN ASR name> VAM0366 QCONFIG = <QCONFIG member name> VAM0366 DISK QUOTA TABLE DSN = <QT dataset name> VAM0012 ALIASLVL = <1 or 2 or 3 or 4> VAM0012 ASRSIZE = <1 or 2 or 3> QREBUILD Subcommand The QREBUILD subcommand rebuilds the quota table (see page 181). This option applies only to the Quota selectable unit. QRESETWM The QRESETWM subcommand initializes the water marks (see page 184) to the current allocation amount. This process is followed by a QSYNC operation that resynchronizes the CQT with the DQT. QRESETWM applies only to the Quota selectable unit. QSYNC The QSYNC subcommand synchronizes the DQT and CQT (see page 183). This option applies only to the Quota selectable unit. Change Parameters The START and MODIFY commands can be used with the following change parameters: ACTIVE (see page 170) Operation 169

170 ALIASLVL= (see page 170) ASRSIZE= (see page 170) CONFIG= (see page 171) DIAGS= (see page 171) DORMANT (see page 171) HSMDIAG (see page 172) HSMOFF (see page 172) HSMON (see page 172) NOHSMDIAG (see page 172) PROG= (see page 172) QCONFIG= (see page 172) QCONFIGSZ= (see page 173) RESIDENT= (see page 173) STORGP= (see page 173) VANTKEY= (see page 174) VSYS= (see page 174) Change parameters usually, but not always, require an action parameter (see page 166). Action parameters can have one or more associated change parameters. ACTIVE The ACTIVE subcommand sets CA Allocate DASD Space and Placement to the active state. This subcommand overrides the PLSMODE parameter in the VKGPARMS parmlib member. The default PLSMODE value is (ACTIVE). The active state is the normal mode of operation. ALIASLVL= The ALIASLVL= subcommand is needed only in installations that use the MVS/ESA Multi-Level Alias (MLA) facility. The default value is the PLSALLVL value in the VKGPARMS parmlib member. As delivered, the default value is (1). The MLA facility uses one to four levels of data set name qualifiers to point to different user catalogs. If MLA is set to use more than one qualification level, use ALIASLVL= to ensure that CA Allocate DASD Space and Placement selects the correct catalog. ASRSIZE= The ASRSIZE= subcommand specifies a size for the compiled length of the ASRs. Use this command for large or complex ASRs that cannot be compiled because of a VDSCOMP STACK OVERFLOW or SYNTAX ERROR: PROGRAM TOO LARGE error. The default value is (1), which allocates 256 KB for the compiled length. You can specify (2) or (3) to double or triple the amount to 512 KB or 1024 KB. Operation 170

171 Note: Increasing the ASRSIZE beyond the default value can require an increase of the REGION specified by the CA Allocate DASD Space and Placement started task. CONFIG= For a description of the CONFIG= parameter and the CONFIG member, see the parmlib considerations for multiple systems (see page 141). DIAGS= The DIAGS= subcommand activates diagnostic tracing for the specified jobname. Use these internal diagnostics to diagnose suspected problems with CA Allocate DASD Space and Placement. The PLSDIAGS system parameter (see page 109) defines the default value. As delivered, the default value is ( ), signifying no jobname. You can use this subcommand instead of changing the PLSDIAGS value. Specifying DIAGS= with no jobname is the default, and means that no jobname produces diagnostic messages. When you specify DIAGS=jobname, diagnostic messages are produced for the job until the DIAGS= with no jobname is specified. You can activate diagnostic tracing in multiple jobs by using pattern masking characters instead of an explicit jobname. Notes: A large volume of diagnostics is likely to be generated. We recommend running with PLSOPT98 (Y). Specifying (Y) confines these diagnostics to a single section of the JES listing of the failing job. Using the default value of (N) issues the diagnostics to both the JES listing and the SYSLOG. When using pattern masking characters, any messages that are typically subject to PLSOPT98 processing are issued as if PLSOPT98 (Y) was active. Most of the messages are then issued to the job logs and kept out of the SYSLOG. More information: Diagnostic Tracing (see page 218) DORMANT The DORMANT subcommand sets CA Allocate DASD Space and Placement to the dormant state. This subcommand is typically used for testing. This subcommand overrides the PLSMODE parameter in the VKGPARMS parmlib member. As delivered, the default PLSMODE value is (ACTIVE). When the product runs in DORMANT mode, a special DDname is required to process a job or TSO session. The DDname is specified in the PLSDRMNT parameter in the VKGPARMS parmlib member. As delivered, the default PLSDRMNT value is (#VAMTST#). Operation 171

172 HSMDIAG The HSMDIAG subcommand activates diagnostics in the DFSMShsm address space. The diagnostics remain active until the NOHSMDIAG subcommand is issued. Important! These diagnostics result in substantial spool output. Activate them only in special cases. HSMOFF The HSMOFF subcommand deactivates the DFSMShsm RECALL/RECOVER redirection feature. HSMOFF is mutually exclusive with HSMON. The default value is HSMOFF. HSMON The HSMON subcommand, when used with sysparm PLSOPT15, activates the DFSMShsm RECALL/ RECOVER redirection feature. HSMON is mutually exclusive with HSMOFF. More information: DFSMShsm during RECALL/RECOVER (see page 92) ASR Variables for HSM RECALL and RECOVER Operations (see page 92) PLS Sysparms (see page 109) NOHSMDIAG The NOHSMDIAG subcommand deactivates the diagnostics that HSMDIAG activated. The default value is NOHSMDIAG. PROG= The PROG= subcommand specifies which library member to compile and use as the ASR. The VDSPROG DD statement points to the library that contains the member. The PLSVDSMB parameter in the VKGPARMS parmlib member defines the default value. As delivered, the default value is VDSPROG. QCONFIG= The QCONFIG= subcommand specifies the member name that contains the Quota Configuration File. The PLSQCFMB parameter in the VKGPARMS parmlib member defines the default value. As delivered, the default value is QCONFIG. The following considerations apply: Operation 172

173 The statements in the Quota Configuration File (see page 186) control the actions of the Quota selectable unit. The default value for the QSCAN ASR is specified in the PLSQSCMB parameter in the VKGPARMS parmlib member. The QSCAN OPTION of the Quota Configuration File overrides the default name QSCAN. The default value for the QREBUILD ASR is specified in the PLSQRBMB parameter in the VKGPARMS parmlib member. The QREBUILD OPTION of the Quota Configuration File overrides the default name QREBUILD. QCONFIGSZ= The QCONFIGSZ= subcommand specifies how many 80-byte lines to provide when getting storage for the Quota Configuration File. Use this subcommand when you need substantially more than the default of 3,000. Because lines are typically compacted to less than 80 bytes, the acquired storage usually supports more lines than you specify. You can specify up to 99,999. RESIDENT= Valid Values: RESIDENT=YES (default), RESIDENT=NO The RESIDENT= change parameter specifies the residency mode of the active communications interface after executing the current series of commands. This communications interface can be a started task or a batch job. Specify RESIDENT=YES to keep the communications interface running and waiting for operator commands. Specify RESIDENT=NO to terminate the communications interface after the current command has been processed. The RESIDENT= change parameter is equivalent to the PLSRES system parameter (see page 109). Both parameters change the residency status of the communications interface. During an INSTALL operation, the optional RESIDENT= value takes precedence over the PLSRES parameter. When running resident, the residency can be changed to nonresident by specifying RESIDENT=NO with a MODIFY command. When running nonresident, the residency can be changed to resident by specifying RESIDENT=YES before one of these action commands: PARMREF, REFRESH, STATUS, QREBUILD, QRESETWM, or QSYNC. RESIDENT=YES is required for QSYNC operations when running with the optional Quota selectable unit on multiple LPARS that share the Disk Quota Table. RESIDENT=YES is ignored after these exception conditions occur: VAM0010, VAM0011, VAM0022, VAM0047, VAM0245, VAM0362, VAM0369, and VAM5021. STORGP= The STORGP= subcommand specifies which library member contains the storage group definitions to use. The PLSPRGDS sysparm points to the library that contains the member. The PLSSTRMB parameter in the VKGPARMS parmlib member defines the default value. As delivered, the default value is VDSTORGP. Operation 173

174 VANTKEY= If your site is not licensed for CA Vantage, this option is meaningless. VANTKEY specifies the TSO user ID of a CA Vantage user. The CA Allocate DASD Space and Placement started task will send all operation type messages to this user. For example, to send messages to user ISPKCH1, issue the following command: S VAM,PARM=('VANTKEY=ISPKCH1') START command F VAM,VANTKEY=ISPKCH1 MODIFY command If the user is logged onto CA Vantage, these messages appear in a popup window. If the user is not logged on, these messages are lost. VSYS= For a description of the VSYS= parameter, see the parmlib considerations for multiple systems (see page 141). Operation 174

175 User Exits CA Allocate DASD Space and Placement can call up to ten user exits or program routines. The CALL statement (see page 157) can invoke these user-written routines from any point in the Allocation Selection Routine (ASR). User exits return data to the ASR by storing it in user variables N0 to N40 33 and C0 34 to C The ASR then uses the new contents of the user variables. Keep the following items in mind when using user exits: Character variables are null-terminated (X'00'). A flag byte precedes each user variable. Do not change it. All exit routines must be reentrant. All exits must be named VDSEXITx, in which x is a number from 1 to 9. Because user exits gain control during the allocation process, functions like OPEN, CLOSE, PARTREL, and dynamic allocation are not supported. More information: Sample User Exits (see page 175) Install User Exits with SMP/E (see page 176) Sample User Exits The following sample user exits are provided in member SMPEXIT in the CCTVSAMP target library of your SMP/E zone: EXIT01 Provides an enhanced version of EXIT05. EXIT02 Sends a message to a specific logged on TSO user ID. EXIT03 Retrieves the 8-character ACF2 logon ID (User ID). EXIT04 Retrieves &CATDSN for non-vsam allocations. EXIT05 Reports which STORGRP a specific volume is within. EXIT06 Looks to see whether a specific data set is cataloged (pre-dfp Release 3 systems only) and returns the VOLSER User Exits 175

176 EXIT07 Allows concatenation of character strings. EXIT08 Performs a DSN-level security check. EXIT09 Writes SMF records. The default record ID is 213. EXIT10 Determines the CYL amount of a VSAM records allocation. EXIT13 Verifies that &C0 contains a valid UNIT. EXIT14 Issues a WTOR from an ASR. Install User Exits with SMP/E You can use SMP/E to install user exits. See the SMPEXIT member in the CCTVJCL target library of your SMP/E zone. This member contains the JCL to assemble, link, and install the sample user exits. Follow these steps: 1. Submit the JCL. The user exits are incorporated into the load library. 2. Recycle CA Allocate DASD Space and Placement. The load library changes take effect. Note: A REFRESH does not load user exits into CSA. REFRESH only implements ASR and pool definition changes. Load library changes require a full recycle of the product. User Exits 176

177 Quota Users who overuse their allocated disk space complicate storage Administration. These are most often developers and ad-hoc system users who do not have specific disk space needs and are allowed to allocate space from a shared disk pool. Since multiple users share the same pool, they must be good neighbors to assure everyone enough space. Unfortunately, cooperation in sharing disk pools does not work reliably. Users still use more space than planned and deplete the shared pool. Then other users of the pool demand a solution from the Storage Administrator. With the introduction of SMS, running out of shared pool space grew more serious because SMS storage groups are much larger and many more users share the same pool. Quota resolves this disk-sharing problem by monitoring pool usage by user, group, or department and by giving Storage Administrators absolute control over how much total at any level can allocate. Quota is not usually implemented for every user of storage space or for every application. Quota is intended for users and applications that require space monitoring. More information: How Quota Works (see page 177) The Importance of QUOTAFUNC (see page 181) The QREBUILD Process (see page 181) The QSYNC Process (see page 183) Water Mark Thresholds (see page 184) Quota Files (see page 185) Reporting Options (see page 192) Running Quota Across Multiple CPUs Sharing Disk Volumes (see page 195) QUOTA and PLSQFACT (see page 196) QUOTA and PLSQUOGM (see page 197) Logically Disabling Quota Processing (see page 197) Exposures of Sharing IGGPRE00 and IGGPOST0 (see page 197) RENAME and MANAGEMENT CLASS (see page 199) API for Dynamically Changing Quota Limits (see page 200) How Quota Works Quota can dynamically capture and track disk allocation statistics for individuals, groups of users, or groups of data. Such groups of users or data are called Quota Groups. Quota can also set and optionally enforce limits on the amount of space allocated to Quota Groups at any one time to ensure equitable access to disk space in common storage pools. These limits can be assigned in units of Quota 177

178 kilobytes, megabytes, tracks, or cylinders. The statistics are captured when the system allocates, extends, renames, deletes, or releases idle space. Quota tracks allocation statistics in three ways. Initial usage statistics are collected when Quota is brought up the first time. The impact a proposed change has on a group's allocation statistics is determined before the change is allowed. The actual allocation amount of the change is collected at the time it is made. Quota keeps the allocation statistics in real computer memory and periodically copies them to a disk file. Initial allocation statistics are collected by a subtask that scans online disk volumes. One parameter file determines which volumes are tracked. Another parameter file analyzes each data set on the selected volumes to determine which group is accountable for which data set's allocation amount. Quota uses two interfaces in the operating system to keep track of proposed and actual changes to disk allocation statistics. The first interface is just before the allocation change takes place. A subroutine determines the impact that the proposed change has on a group's allocation statistics. This is the point of control for how much space is used by any group. This is where Quota can be directed to disallow requests that let a group exceed its predefined limit. Quota's second interface in the operating system is after the allocation change has occurred. At this point, Quota updates the applicable group's allocation statistics. The memory copy of the allocation statistics is updated in real-time. The disk copy is updated periodically at whatever interval was specified in the configuration parameter file. Quota has three implementation modes: Silent mode monitors allocations and informs the storage administrator when quota limits are exceeded. Warning mode warns users when they exceed their quota limits. Fail mode disallows allocations that allow a group to exceed its predefined limit. Note: Running with PLSKBYTE (1000) instead of the default (1024) will introduce a loss of precision resulting in the quota allocation amounts overstating what will actually be allocated. If running in fail mode, this may result in allocations being erroneously denied because the quota limit has been, or would otherwise be, exceeded. More information: Quota System Overview (see page 178) Quota System Overview Quota tracks all DADSM Activity (CREATE, EXTEND, RELEASE, RENAME, SCRATCH) for all data sets, both VSAM and non-vsam, including SMS-managed. On pre-z/os 1.13 systems it installs intercept points at the static IGGPRE00 (DADSM pre-allocation exit) and IGGPOST0 (DADSM post-allocation exit) at the standard DADSM exit points that are provided by the operating system. On z/os 1.13 systems and above it installs intercept points at the now dynamic IGGPRE00_EXIT (DADSM preallocation exit) and IGGPOST0_EXIT (DADSM post-allocation exit) at the standard DADSM exit points that are provided by the operating system. Quota 178

179 The following illustration shows a simplified view of the relationship between these hooks, other hooks, and the entire allocation process. As the previous illustration shows, the QUOTA environment is entered for every DADSM data set operation for all types of data sets. It is called before the DADSM operation takes place from the CA Allocate DASD Space and Placement hook at IGGPRE00. This is the point of absolute control over how much space is used by any group of users. This is where an allocation can be denied to keep a group within its predefined limit. Although there is no environment at the IGGPOST0 hook point, a significant amount of Quota processing occurs there. Quota first sees whether the DADSM operation that just completed was successful. If it was, Quota updates the memory copy of the quota group's allocation statistics. The memory copy of these statistics is called the CSA Quota Table (CQT). The disk copy is called the Disk Quota Table (DQT). Quota 179

180 The following table shows the sequence of ASR environments entered during the life cycle of a data set with QUOTA, from the time it is originally allocated, through open, close, extension, rename, and finally deletion. OPERATION Non-VSAM VSAM Allocate a new single-volume data set. ACS ALLOC SPACE QUOTA (primary) ACS DEFINE (cluster) QUOTA (data component primary) QUOTA (index component primary) Write to the data set so that an extent is required. EXTEND QUOTA (secondary) EXTEND QUOTA (data component secondary) QUOTA (index component secondary) Release unused space in the data set when it is closed. RELEASE QUOTA not applicable Rename the data set. OLD RENAME QUOTA (data component) QUOTA (index component) Write to the data set so that an additional volume is required. EOV QUOTA (secondary) EOV_VSAM (data component) QUOTA (data component primary) EOV_VSAM (index component) QUOTA (index component primary) Scratch the data set. SCRATCH (volume 1) QUOTA (volume 1) QUOTA (data component volume 1) QUOTA (index component volume 1) Quota 180

181 OPERATION Non-VSAM VSAM SCRATCH (volume 2) QUOTA (volume 2) QUOTA (data component volume 2) QUOTA (index component volume 2) The Importance of QUOTAFUNC CA Allocate DASD Space and Placement has over two hundred ASR variables. Several of these variables are Quota only variables. One warrants special mention: QUOTAFUNC. Quota tracks all DADSM activities. The QUOTAFUNC variable identifies the DADSM function that called the QUOTA environment: ALLOC, EXTEND, RELEASE, RENAME, or SCRATCH. ASR writers must be aware of the DADSM function/activity/operation that called the QUOTA environment, particularly if they are coding rules to deny allocations to those groups that have exceeded their quota limits. Denying RELEASE or SCRATCH requests prevents such groups from reducing their allocated disk space so that they are again within their quota limits. RENAME requests might reduce the allocation statistics of one group and might increase the allocation statistics of another group. When tracking RENAME activities, the NEWNAME variable is the one to query and the NEWQUOTAGROUP is the one to set, not the DSN and QUOTAGROUP variables. Three other ASR variables are unique to RENAME operations: NEWNAMEHLQ, NEWNAMELLQ, and NEWNAMENQUAL. Two others might apply to them -- QLIMITIFNEW and QPARENTIFNEW. The QREBUILD Process QREBUILD is the process by which the initial disk allocation statistics are collected when Quota is brought up the first time. During a QREBUILD, the VTOCs of all available volumes subject to Quota processing are scanned and the allocation statistics are accumulated. Note: Non-shared DASD is not available to all systems, so if a QREBUILD is performed in a system that does not have access to all volumes, all information relating to the unavailable volumes is lost. If QUOTA is running on multiple systems with non-shared DASD, insure that QREBUILD is done only on a system having access to ALL the volumes you want to track. The Quota Limit, Parent Quota Group and Quota Warning Percent are initially specified when the Quota Group is created. Quota Groups can be created four different ways: Explicitly defining attributes in the QCONFIG file. Dynamically defining attributes in the QSCAN environment. Dynamically defining attributes in the QUOTA ASR environment when DASD allocation statistics are being tracked. Use the VAMSRV10 API from a batch job or APF-authorized REXX program. Quota 181

182 To change attributes to existing Quota Groups, explicit changes need to be defined in the Quota Group in a QUOTADEF statement in the QCONFIG file prior to initiating a QREBUILD operation or use the VAMSRV10 API through a batch job or APF-authorized REXX program. Note: The QREBUILD operation updates existing Quota Groups for the Quota Limit; Parent Quota Group and the Quota Warning Percent. The VAMSRV10 API is used only for changes in the Quota Limit and Quota Warning Percent. If ASRQUOTAGROUPS(YES) was specified on the OPTIONS statement in the Quota Configuration File, new Quota Groups are automatically generated as the QREBUILD process progresses. The following illustration shows a simplified view of this process. As the previous illustration illustrates, the QREBUILD Allocation Selection Routine (ASR) is the parameter file that determines which volumes are tracked. The QSCAN ASR determines which group is Quota 182

183 accountable for which data set's allocation amount. Only the memory copy of the statistics (the CQT) is updated. After the QREBUILD process is completed, a QSYNC (described below) is started to copy the allocation statistics from the CQT to the disk copy, the Disk Quota Table (DQT). A QREBUILD operation is automatically started whenever a QRESET or QUOTADEF statement is found in the Quota Configuration File during start-up or during a REFRESH operation. It may also be requested on demand by specifying QREBUILD in a MODIFY request. This is recommended whenever the product has been down for a long time (and significant DADSM activity has occurred), when volumes whose disk allocations are tracked by Quota are lost due to a hardware error and subsequently restored from backup, or whenever the Quota Group structure has been reorganized, thereby rendering the currently accumulated allocation statistics meaningless. The QSYNC Process The allocation statistics are maintained in two places: in real memory in the CSA Quota Table (CQT) and on disk in the Disk Quota Table (DQT). The QSYNC process ensures that the CQT and DQT contain the same information about the allocation statistics by periodically re-synchronizing them. This is important when running this product in multi-cpu environments with shared disk volumes. During start-up, the CQT is created by loading a copy of the DQT into real memory. As processing on the system continues, the QSYNCs periodically update the DQT with changes from the CQT. These changes were made to the CQT in real-time, following the completion of each successful DADSM operation. In a multi-cpu environment with shared disk volumes, a QSYNC also updates a CQT with changes that have been made in the DQT. The DQT changes came from the last QSYNC with the other CQTs in that multi-cpu environment. The following illustration shows a simplified view of this process. A QSYNC occurs at whatever frequency interval (SYNCINTERVAL) was specified in the QCONFIG parameter file. Additional QSYNCs are performed after a QREBUILD, during a REFRESH, and before uninstalling the product. You can also request a QSYNC at any time by specifying QSYNC in a MODIFY request. A SYSTEMS enqueue on QNAME STERLING and RNAME DQT-data-set-name is placed on the DQT for the duration of the QSYNC process. Quota 183

184 In a single CPU environment, QSYNCs are important when accurate reports on the allocation statistics are needed. Both reporting vehicles -- the QSTAT CLIST and the VDSQRPTS Batch job -- get their information from the DQT, which depends on the QSYNCs for its information. QSYNC frequency intervals are of greater importance in multi-cpu environments because that is how changes in the allocation statistics on one system are communicated to the CQTs on the other systems. Periodic synchronizations of the changes in the allocation statistics across all systems in a multi-cpu environment are critical for ensuring the accuracy of the information retrieved by the QUOTACHK Subroutine. QUOTACHK is used to determine whether a proposed DADSM operation (for example, allocating a new data set) results in a group exceeding its predefined limit. QUOTACHK gets the current group's allocation statistics from the CQT, which depends on the QSYNCs to reflect changes in the allocation statistics on other systems. How often QSYNCs should run depends on how the statistics are used. The QSYNC interval determines the accuracy of the quota allocation statistics. To deny allocations to groups of users who have exceeded their predefined limits requires far more accuracy than does daily reporting. Note: PLSRES (Y) is required when running with the optional Quota selectable unit. Water Mark Thresholds Water marks are allocation thresholds that provide the user with a historical perspective of a quota group. Their purpose is to help determine whether a predefined quota group limit can be exceeded. Depending on which variables are used, the user can establish: QHIWATERMARK QLOWATERMARK A combination of both Water mark thresholds are valid until the next QREBUILD operation. This is because the QSYNC process of QREBUILD resynchronizes the CQT, which in effect resets all water mark thresholds. They can also be reinitialized on demand by using the QRESETWM command. Note: To avoid having a QREBUILD reset the water marks, set PLSOPT8 to 'Y'. Operation The high and low water marks of a quota group are initialized to the allocation amount of the first data set associated with the quota group when the quota group is created. Whenever a quota group's allocation amount changes, the new value is compared against both the high and low water marks. The high and low water mark percentages are calculated as a percent of the group's predefined quota limit. This method is consistent with the QUOTAPERCENTS variable, representing the proposed total allocated amount (QUOTAALLOCS) as a percentage of a quota group's predefined limit (QUOTALIMITS), and with the percents included in the various product reports. Quota 184

185 Environments Quota groups can be created and updated in the QSCAN environment during a Quota Table Rebuild operation. Groups can also be created or updated after a successful DADSM operation that was processed in the Quota environment. More information: ASR Variables 36 QRESETWM (see page 169) Quota Files Quota utilizes the following file types: Disk Quota Table (see page 185) Quota Configuration File (see page 186) Allocation Selection Routines and Environments (see page 189) Disk Quota Table The Disk Quota Table (DQT) is a snapshot of the CSA Quota Table (CQT) taken at user-defined intervals. The QSYNC process is the camera. It is identified to the CA Allocate DASD Space and Placement started task by either the PLSDQTDS parameter in the VKGPARMS parmlib member or by the DISKQTBL DD statement in the started task itself. When the product is brought down, all changes in the CQT since the last QSYNC are propagated to the DQT. When the product is brought up, the CQT is created by the started task, which loads the DQT into CSA memory. The DQT must be allocated with the attributes listed in Table 7-3. Space allocation amounts are discretionary. For example, on a 3390 device with a block size of 27,984 bytes, 5 tracks will support 2,640 Quota Groups. This file should be protected by security software so that only the started task can write on it. All other jobs should be able to read it. ATTRIBUTE Organization Record Format Record Length Block Size Primary Amount VALUE Physical Sequential Fixed Blocked 106 bytes Multiple of 106 bytes. As large as possible. User discretion 36 Quota 185

186 ATTRIBUTE Secondary Amount VALUE User discretion You can find the JCL to allocate the DQT in member ALLOCDQT in the CCTVJCL target library of your SMP/E zone. Quota Configuration File The Quota Configuration File contains the general parameters that control the operation of Quota. The default member name is QCONFIG. It is not an Allocation Selection Routine. QCONFIG The file has three types of statements: QCONFIG (see page 186) OPTIONS Statement (see page 186) QUOTADEF Statement (see page 187) QRESET Statement (see page 187) Manual versus Automatic Quota Group Definition (see page 188) Sample Quota Configuration File (see page 188) OPTIONS Statement The OPTIONS statement specifies installation options. It is required and should be the first statement in the Quota Configuration File. The following associated keyword parameters are available: SYNCINTERVAL(NumberOfSeconds) [ASRQUOTAGROUPS({YES NO})] [DEFAULTQUOTAGROUP({DEFAULT QUOTA GROUP QuotaGroupName)] [QREBUILD({QREBUILD MemberName})] [QSCAN({QSCAN MemberName})] [SPACEUNIT({3390 Unit Type})] SYNCINTERVAL The number of seconds the Quota Table Synchronization task (QSYNC) should sleep between Disk and CSA Quota Table synchronizations. ASRQUOTAGROUPS Option to permit creation of new Quota Groups by the VDSPROG and QSCAN ASRs. If ASRQUOTAGROUPS(NO) is specified, CA Allocate DASD Space and Placement uses the default quota group whenever these ASRs select one that is not already defined in the Quota Table. DEFAULTQUOTAGROUP Default Quota Group if the VDSPROG ASR selects one not already defined in the Quota Table. Defaults to 'DEFAULT QUOTA GROUP'. Quota 186

187 QREBUILD The default value for the QREBUILD ASR is specified in the PLSQRBMB parameter in the VKGPARMS parmlib member. The QREBUILD OPTION of the Quota Configuration File overrides the default name. As delivered, the ASR name is QREBUILD. QSCAN The default value for the QSCAN ASR is specified in the PLSQSCMB parameter in the VKGPARMS parmlib member. The QSCAN OPTION of the Quota Configuration File overrides the default name. As delivered, the ASR name is QSCAN. SPACEUNIT The unit type to be used when quota limits are specified in TRK or CYL units in the QUOTADEF statements. The default is Tracks and cylinders equal the following numbers of bytes for quota processing for these SPACEUNIT values: SPACEUNIT TRACK CYLINDER , , , , , , , , , ,200 All but one of the keyword parameters that are described in the previous table have default values. The SYNCINTERVAL is the only required keyword parameter in the OPTIONS statement. SYNCINTERVAL does not specify how often QSYNC starts but rather the length of the sle between the time the current QSYNC ends and the next one starts. QUOTADEF Statement The QUOTADEF statement defines a Quota Group by specifying its name, quota limit, warning level, and parent. The following parameters are associated with the QUOTADEF statement: NAME(QuotaGroupName) [LIMIT(number{GB KB MB PB TB TRK CYL})] [WARNING(number[%])] [PARENT(QuotaGroupName)] Only the NAME parameter is required. The other three are optional. You might need to modify one or more of these parameters for an existing Quota Group. To do so, do a QREBUILD after making any changes to the appropriate QUOTADEF statement. QRESET Statement You might need to reorganize the quota group structure and remove groups that are no longer required. The QRESET statement tells the started task to delete the contents of the current CQT and rebuild it. The QRESET statement is optional and has no keyword parameters. Quota 187

188 It is recommended that the QRESET statement be placed after the OPTIONS Statement, but before any QUOTADEF statements. Placing the QRESET statement after the QUOTADEF statements causes the quota groups defined by the QUOTADEF statements to be deleted when the QRESET statement is processed. Manual versus Automatic Quota Group Definition The Quota Groups that are used can be defined manually, automatically, or by a combination of the two. Modify any Quota Group using the QUOTADEF statement in the Quota Configuration File. Typically, manual quota group definition is used when there are few quota groups. Automatic quota group definition is used when it is possible to directly relate a portion of a data set name to a specific quota group. The ASRQUOTAGROUPS parameter of the OPTIONS statement in the Quota Configuration File controls the generation of automatic quota group definitions. Two advantages to automatic quota group definition are: When there are many Quota Groups, it might not be feasible to maintain them manually. Quota can be installed quickly without expending much effort in defining the Quota Groups. Sample Quota Configuration File The following illustration is a Quota Configuration File that can be used to gather the initial allocation statistics the first time Quota is brought up. The format is free-form and blank lines are permitted. However, if a statement spans more than one line, the break cannot occur in the middle of a keyword or value pair and must be preceded by at least one space followed by a plus sign (+). File Edit Confirm Menu Utilities Compilers Test Help EDIT.PARMLIB(QCONFIG) Columns Command ==> Scroll ==> CSR ****** ************************** Top of Data ********************************* OPTIONS SYNCINTERVAL(60) ASRQUOTAGROUPS(YES) DEFAULTQUOTAGROUP(MISCELLANEOUS GROUP) QREBUILD(QREBUILD) QSCAN(QSCAN) SPACEUNIT(3390) QUOTADEF NAME(MAIN STREET COMPUTER CENTER) LIMIT(2000CYL) WARNING(70%) QUOTADEF NAME(AAA DEPT) LIMIT(700MB) WARNING(71%) PARENT(MAIN STREET COMPUTER CENTER) QUOTADEF NAME(BBB DEPT) LIMIT(600MB) WARNING(65%) PARENT(MAIN STREET COMPUTER CENTER) QUOTADEF NAME(CCC DEPT) LIMIT(500MB) WARNING(80%) PARENT(MAIN STREET COMPUTER CENTER) QUOTADEF NAME(AAAMAH) PARENT(AAA DEPT) LIMIT(200MB) WARNING(80%) QUOTADEF NAME(AAAMAI) PARENT(AAA DEPT) LIMIT(210MB) WARNING(81%) QUOTADEF NAME(AAAMAJ) PARENT(AAA DEPT) LIMIT(220MB) WARNING(82%) QUOTADEF NAME(BBBMAK) PARENT(BBB DEPT) LIMIT(230MB) WARNING(83%) QUOTADEF NAME(BBBMAL) PARENT(BBB DEPT) LIMIT(240MB) WARNING(84%) QUOTADEF NAME(BBBMAM) PARENT(BBB DEPT) LIMIT(250MB) WARNING(85%) QUOTADEF NAME(CCCMAN) PARENT(CCC DEPT) LIMIT(260MB) WARNING(86%) QUOTADEF NAME(CCCMAO) PARENT(CCC DEPT) LIMIT(270MB) WARNING(87%) QUOTADEF NAME(CCCMAP) PARENT(CCC DEPT) LIMIT(280MB) WARNING(88%) After the initial allocation statistics have been collected, the QUOTADEF statements should be removed from the active Quota Configuration File. During a REFRESH operation, the active configuration file is Quota 188

189 recompiled. If either a QUOTADEF or QRESET statement is found, CA Allocate DASD Space and Placement assumes that a QREBUILD operation is required and automatically starts one. Allocation Selection Routines and Environments The ASRs for Quota are essentially the same as those for the Allocation Manager. The two selectable units share the VDSPROG ASR. Two ASRs are unique to the QREBUILD process: QREBUILD and QSCAN. Three of the fourteen environments apply. The QREBUILD process uses the QREBUILD and QSCAN environments. The QUOTA environment is used when tracking proposed and actual changes to the allocation statistics. QUOTA ASR and SMS Constructs (see page 189) QREBUILD ASR and Environment (see page 189) QSCAN ASR and Environment (see page 190) VDSPROG ASR and the QUOTA Environment (see page 190) QUOTA ASR and SMS Constructs Sample ASR code: IF &VAMENVIR NE 'QUOTA' THEN EXIT CODE(0) WRITE 'DATA CLASS = &DATACLAS' WRITE 'MANAGEMENT CLASS = &MGMTCLAS' WRITE 'STORAGE CLASS = &STORCLAS' WRITE 'STORAGE GROUP = &STORGRP' IF &STORCLAS = 'DASD80' THEN SET &QUOTAGROUP = 'STORCLAS80' CALL QUOTACHK WRITE 'QUOTAGROUP = &QUOTAGROUP' EXIT CODE(0) QREBUILD ASR and Environment The QREBUILD ASR and environment filter volumes for Quota processing when the Quota Table is being built or rebuilt from data obtained by scanning the VTOCs during the QREBUILD process. For each volume that is online during the Quota Table rebuild, the QREBUILD ASR and environment receive control one time. An example of a QREBUILD ASR is: FILTLIST &QVOLS INCLUDE(SYS*,JES*) /* EXCLUDE THESE VOLUMES */ IF &VOLSER EQ &QVOLS THEN EXIT CODE(4) /* FROM QUOTA PROCESSING */ EXIT CODE(0) /* ELSE INCLUDE THIS VOL IN VTOC SCAN */ Sample QREBUILD ASR: Quota 189

190 IF &STORGRP = '' THEN EXIT CODE(4) /* CONSIDER ONLY SMS VOLUMES */ WRITE 'SMS STORGRP = &STORGRP' WRITE 'SMS VOLSER = &VOLSER' EXIT CODE(0) For QREBUILD, &STORGRP contains the SMS storage group name that the volume belongs to (non- SMS VDSTORPG storage groups are not returned to the &STORGRP variable). For QUOTA and QSCAN, &STORGRP contains the SMS storage group name of the volume that the data set is being allocated to, or currently resides on. QSCAN ASR and Environment The QSCAN ASR and environment determine which Quota Group is accountable for which data set's allocation amount when the initial statistics are being captured. They receive control one time for each data set found on each volume selected for processing during the QREBUILD process. An example of a QSCAN ASR is: SET &QUOTAGROUP = &HLQ /* QUOTA GROUP IS HIGH-LEVEL QUAL */ SET &C0 = &SUBSTR(1:3,&HLQ) /* IF NEW, PARENT IS 1ST THREE */ SET &QPARENTIFNEW = &C0 /* CHARACTERS OF HIGH-LEVEL QUAL */ SET &QLIMITIFNEW = 100 MB /* IF NEW, LIMIT IS 100 MB */ SET &QWARNINGIFNEW = 80 /* IF NEW, WARN AT 80% OF LIMIT */ VDSPROG ASR and the QUOTA Environment The QUOTA environment is entered for every DADSM data set operation for all types of data sets, both VSAM and non-vsam, including SMS-managed. The ASR logic in the QUOTA environment: Determines whether the volume on which the DADSM operation is to take place is subject to Quota processing. If not, the ASR exits. Determines which group is to be accountable for the amount involved in the DADSM operation (CREATE, EXTEND, RELEASE, RENAME, or SCRATCH). Calls the QUOTACHK internal routine, which has two functions. The first function is determining what impact the proposed DADSM operation has on the applicable group's allocation statistics. The second is building the record to update the CQT copy of the allocation statistics if the operation is successful. Decides whether to allow the operation, based on information returned by QUOTACHK, and optionally write messages to the user. Always use the &DSN variable for tracking DFSMShsm activities. The QUOTA environment ASR code is kept in the VDSPROG ASR, which also contains the code for the other eleven environments applicable to DADSM operations. These other environments comprise the Allocation Manager feature. The following illustration shows an example of a QUOTA environment ASR. When tracking changes in the allocation statistics, it is important to use the same criteria used to initialize or re-initialize the Quota Table. The accuracy of these statistics depends on it. Tracking changes to the allocation statistics is meaningless unless you know at the start how much space is allocated and by which group. Note the use of the COPYBOOK statement in the illustration for QUOTA environment ASR. It references Quota 190

191 the actual QSCAN ASR used by the QREBUILD process. This method is the most efficient way to ensure Quota consistency. Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(QUOTA1) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* IF &VAMENVIR = QUOTA THEN DO IF (&VOLSER EQ SYS*) OR (&VOLSER EQ JES*) THEN EXIT CODE(0) COPYBOOK 'QSCAN' CALL QUOTACHK IF (&QUOTAFUNC = 'RELEASE') OR (&QUOTAFUNC = 'SCRATCH') THEN EXIT CODE(0) IF &QUOTAFUNC = 'RENAME' THEN SET &NEWQUOTAGROUP = &NEWNAMEHLQ If &QUOTACC = 0 /* UNDER WARNING LIMIT? */ THEN EXIT CODE(0) /* THEN EXIT ASR NOW */ /* */ /* GROUPS WITHIN THEIR WARNING LIMIT OR THAT HAVE ALREADY EXCEEDED */ /* */ COPYBOOK 'QUOTA2' END ******************************** Bottom of Data ******************************* Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(QUOTA2) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* SET &C0 = &QUOTANAMES(1) /* CHILD QUOTA GROUP */ SET &N0 = &QUOTALIMITS(1) /* ITS QUOTA LIMIT */ SET &N1 = &QUOTAALLOCS(1) /* TOTAL ALLOCATED SPACE */ SET &N2 = &QUOTAPERCENTS(1) /* PERCENT OF LIMIT */ COPYBOOK 'QUOTA3' /* ISSUE WARNING MESSAGE */ SET &C0 = &QUOTANAMES(2) /* CHILD QUOTA GROUP */ SET &N0 = &QUOTALIMITS(2) /* ITS QUOTA LIMIT */ SET &N1 = &QUOTAALLOCS(2) /* TOTAL ALLOCATED SPACE */ SET &N2 = &QUOTAPERCENTS(2) /* PERCENT OF LIMIT */ COPYBOOK 'QUOTA3' /* ISSUE WARNING MESSAGE */ ******************************** Bottom of Data ******************************* Menu Utilities Compilers Help BROWSE.ASR.PARMLIB(QUOTA3) Line Col Command ==> Scroll ==> CSR ********************************* Top of Data ********************************* WRITE 'QUOTA GROUP... &C0 QUOTA LIMIT... &N0 KB' WRITE 'ALLOCATION AMOUNT... &N1 KB (AT &N2% OF LIMIT)' IF &QUOTASTATS(1) = 4 /* WITHIN WARNING LIMITS? */ THEN DO WRITE 'YOUR GROUP IS NEAR ITS QUOTA LIMIT' END ELSE DO /* MUST HAVE EXCEED LIMIT */ WRITE 'YOUR GROUP HAS EXCEEDED ITS QUOTA LIMIT.' WRITE 'PLEASE REDUCE YOUR DISK SPACE SO THAT YOU ARE' WRITE 'WITHIN YOUR QUOTA LIMITS. THANK YOU.' END ******************************** Bottom of Data ******************************* Quota 191

192 Reporting Options Quota has online and batch reporting options. Both reporting vehicles get their information from the DQT. The accuracy of the information retrieved by both reporting options depends on how much DADSM Activity has occurred since the last QSYNC. The following batch report jobs use stand-alone programs to produce detailed reports on all Quota Groups: VDSQRPTS Displays the quota limit, space allocated, and space remaining. VDSQRPT2 Displays the space allocated, high water mark, and low water mark. VDSQRPT3 Displays the limit, space allocated, space remaining, and high/low water marks. Ad-hoc reporting is possible with the availability of the DQT record description that is distributed in the AVDSMAC DDDEF data set. More information: QSTAT CLIST (see page 192) Batch Reports (see page 193) QSTAT CLIST QSTAT is a TSO CLIST that shows the status of a specific Quota Group. You can find it in member QSTAT in the CCTVJCL target library of your SMP/E zone. It must be copied to the standard SYSPROC library so that it can be used by all TSO users. The following is the QSTAT CLIST as it is distributed: PROC 0 GROUP(UNSPECIFIED) ALLOC FI(DISKQTBL) DA('VAM.Rvrm.DISKQTBL') SHR REUSE CALL 'VAM.Rvrm.CCTVLOAD(VAMQST1)' '&GROUP' FREE FI(DISKQTBL) END Tailor the CLIST to reference your Disk Quota Table and Load Library. The program VAMQST1 displays the current status of the quota group requested and the status of all its parents. If the VAMQST2 program is used, only the current status of the quota group is displayed. The syntax for using QSTAT is: QSTAT GROUP('Quota Group Name') The Quota Group Name must be enclosed in single quotation marks if it contains embedded blanks. The following illustration shows sample output from QSTAT. Quota 192

193 CA-Allocate Quota Status Information as of 06/13/ :29:23 QUOTA GROUP = TSOST LPAR QUOTA LIMIT GB 31,138,512,896 BYTES SPACE ALLOCATED MB (0%) 1,519,232 BYTES SPACE REMAINING GB (100%) 31,138,512,896 BYTES HIGH WATER MARK MB (0%) at 06/13/ :28:14 LOW WATER MARK MB (0%) at 06/13/ :28:14 PARENT QUOTA GROUP...COMPUTER ASSOCIATES QUOTA GROUP = COMPUTER ASSOCIATES QUOTA LIMIT GB 107,374,182,400 BYTES SPACE ALLOCATED MB (0%) 1,519,232 BYTES SPACE REMAINING GB (100%) 107,374,182,400 BYTES HIGH WATER MARK MB (0%) at 06/13/ :28:14 LOW WATER MARK MB (0%) at 06/13/ :28:14 PARENT QUOTA GROUP...NONE ---End of CA-Allocate Quota Status Information--- *** Batch Reports The batch report jobs use stand-alone programs to produce detailed reports on all Quota Groups. These programs are located in the CCTVJCL target library of your SMP/E zone as the following members: VDSQRPTS VDSQRPT2 VDSQRPT3 Sample VDSQRPTS Output The following example shows sample VDSDRPTS Output, Quota Groups Sorted by Name. This report displays information about the quota limit, space allocated, and space remaining. Quota 193

194 Menu Utilities Compilers Help BROWSE Line Col Command ==> Scroll ==> CSR STATUS as of MM/DD/YYYY 22:39:35 CA-Allocate QUOTA GROUP STATUS REPORT #1 PAGE 11 SORTED BY DESCENDING SPACE ALLOCAED ALLOCATED QUOTA GROUP NAME/PARENT QUOTA LIMIT SPACE ALLOCATED % SPACE REMAINING % LAB** DSETS ON VOL SSL KB KB 83% KB 17% SSL LAB** DSETS ON VOL SSL KB KB 83% KB 17% SSL CSL** DSETS ON VOL SSL KB KB 65% KB 35% SSL ALL OTHER* DSETS ON VOL SY9SY KB KB 56% KB 44% SY9SY STA* DSETS ON VOL SY9SY KB KB 1% KB 99% SY9SY ALL OTHER* DSETS ON VOL SMS KB KB 55% KB 45% Sample VDSQRPT2 Output The following example shows sample VDSQRPT2 Output, Quota Groups Sorted by Allocation Amount. This report displays information about the space allocated, high water mark, and low water mark. Menu Utilities Compilers Help BROWSE Line Col Command ==> Scroll ==> CSR STATUS as of MM/DD/YYYY 22:39:35 CA-Allocate QUOTA GROUP STATUS REPORT #2 PAGE 13 SORTED BY QUOTA GROUP NAME ALLOCATED QUOTA GROUP NAME/PARENT SPACE ALLOCATED HIGH WATER MARK LOW WATER MARK VAM* DSETS ON VOL SMS MB 222% MB 222% MB 222% SMS901 at 01/29/ :28 at 01/29/ : VAM* DSETS ON VOL SSL MB 152% MB 152% MB 152% SSL801 at 01/29/ :28 at 01/29/ : VAM* DSETS ON VOL SSL MB 174% MB 174% MB 174% SSL802 at 01/29/ :28 at 01/29/ : VAM* DSETS ON VOL SSL MB 362% MB 362% MB 362% SSL803 at 01/29/ :28 at 01/29/ : VAM* DSETS ON VOL SSL MB 20% 20.28MB 20% 20.28MB 20% SSL804 at 01/29/ :28 at 01/29/ : VAM* DSETS ON VOL SSL MB 149% MB 149% MB 149% Quota 194

195 Sample VDSQRPT3 Output The following example shows sample VDSQRPT3 Output, Quota Groups Sorted by Percentage of Limit. This report displays information about the limit, space allocated, space remaining, and high and low water marks. Menu Utilities Compilers Help BROWSE Line Col Command ==> Scroll ==> CSR STATUS as of MM/DD/YYYY 22:39:35 CA-Allocate QUOTA GROUP STATUS REPORT #3 PAGE 5 SORTED BY QUOTA GROUP NAME ABC WIDGET COMPANY QUOTA GROUP NAME/PARENT LIMIT SPACE ALLOCATED SPACE REMAINING HIGH/ LOW WATER MARKS ISP** DSETS ON VOL SMSSTG MB 3.24MB 0% MB 100% 3.24MB 0% at 01/29/ :20 SMSSTG 3.24MB 0% at 01/29/ : ISP** DSETS ON VOL SMS MB MB 15% MB 85% MB 15% at 01/29/ :20 SMS MB 15% at 01/29/ : ISP** DSETS ON VOL SMS MB MB 42% MB 58% MB 42% at 01/29/ :20 SMS MB 42% at 01/29/ : ISP** DSETS ON VOL SMS MB 96.48MB 13% MB 87% 96.48MB 13% at 01/29/ :20 SMS MB 13% at 01/29/ : ISP** DSETS ON VOL SMS MB MB 40% MB 60% MB 40% at 01/29/ :20 SMS MB 40% at 01/29/ : ISP** DSETS ON VOL SMS MB MB 35% MB 65% MB 35% at 01/29/ :20 Running Quota Across Multiple CPUs Sharing Disk Volumes In a multi-cpu environment where disk volumes are shared, Quota can effectively track the allocation statistics on the shared disk volumes. It can also concurrently track those volumes that are not shared. The only limitation is that the single DQT needs to reside on one of the shared volumes. This enables each QSYNC to update the DQT with the changes that have occurred on its system and, in turn, to Quota 195

196 receive information from the DQT about the changes that have occurred on the other systems. The following illustration shows a simplified view of this process in CA Allocate DASD Space and Placement (CA Allocate). The communication between the three CPUs in the illustration occurs as follows: 1. A started task runs on each CPU. 2. The necessary operating system hooks are installed on all CPUs. 3. A copy of the Disk Quota Table (DQT), named the CSA Quota Table (CQT), is maintained on each CPU. 4. The QSYNC operation is done on all CPUs. The frequency of this operation for each CPU is determined by the QSYNCINTERVAL parameter on the OPTIONS statement in the QCONFIG file on each CPU. 5. The QREBUILD operation is done on only one CPU, and the result is copied to DQT replacing its contents. This CPUs started task is designated as the master. The started tasks running on the other CPUs automatically load CQT changes from the DQT after the master started task writes them to the DQT. Note: In a shared DASD environment, a QREBUILD must not be done on any CPU other than the Master, as shown in the previous illustration. If QREBUILD is allowed to execute on a secondary CPU, and the secondary CPU does not have access to all DASD, the DQT may only report on a subset of your DASD volumes. QUOTA and PLSQFACT When PLSQFACT (K) is specified, all numeric values in quota are expressed in units of kilobytes. If a DADSM operation resulted in an allocation of 3120 bytes, this would be converted to kilobytes and rounded up. In this case, the resulting allocation value (as tracked by QUOTA) would be 4 kilobytes. Quota 196

197 Running with PLSKBYTE (1000) instead of the default (1024) will introduce a loss of precision resulting in the quota allocation amounts overstating what will actually be allocated. If running in fail mode, this may result in allocations being erroneously denied because the quota limit has been, or would otherwise be, exceeded. If a PARMREF is done, which changes the value of PLSQFACT, a subsequent QREBUILD is necessary to ensure the integrity of the QUOTA statistics. QUOTA and PLSQUOGM When PLSQUOGM(Y) is specified, Greenwich Mean Time (GMT) is used for all timestamp values in quota. The default value of PLSQUOGM is (N) which results in Local Time being used. Multiple systems using different time zones sharing DASD and the same Disk Quota Table should run with PLSQUOGM (Y). Logically Disabling Quota Processing Occasionally it can be necessary to disable all Quota processing activities temporarily. One example is during a Disaster Recovery operation, when the goal is to get the operating system and all critical applications up and running as quickly as possible. In a crisis, it may not be feasible to adhere to normal standards. To run the product with Quota effectively disabled, the following is needed: 1. The DISKQTBL DD statement in the started task must point to a valid DQT allocated as detailed in the section Disk Quota Table. 2. The QSCAN ASR need only contain an EXIT CODE(0) statement. 3. The QREBUILD ASR need only contain an EXIT CODE(4) statement. 4. The QCONFIG configuration file need only contain the sample QCONFIG from the CCTVJCL library created during the SMP/E install process, with one modification: SYNCINTERVAL(99999). 5. The ASRs and Configuration Files listed in (2), (3), and (4) must be in the partitioned data set referenced by the PLSPRGDS variable within VKGPARM in the parmlib. With the above, Quota is logically disabled. No tracking is done. The QSYNC Task runs one time every 28 hours. Exposures of Sharing IGGPRE00 and IGGPOST0 The information contained in this section only applies to the static IGGPRE00 and IGGPOST0 intercept points that exist on pre-z/os 1.13 systems. The dynamic IGGPRE00_EXIT and IGGPOST0_EXIT intercept points that exist on z/os 1.3 systems and above do not have this limitation. Quota is not unique in its use of the standard DADSM exits IGGPRE00 and IGGPOST0. Other program products use either one or both of them. Special care needs to be taken in bringing up CA Allocate DASD Space and Placement (CA Allocate) on systems where it co-exists with one of these other program products. An installation's MVS Systems Programming Staff knows of any other products. Quota 197

198 The QUOTACHK Subroutine, called from the QUOTA environment, has two functions. The first function is to determine the impact a proposed change has on a group's allocation statistics. The second is to build the record that is used to update the CQT copy of the allocation statistics if the proposed DADSM operation is successful. This record is built at VDSPRE00-time. The update occurs at VDSPOST0-time. DADSM has a parameter list that passes information from its IGGPRE00 exit to its IGGPOST0 exit. At VDSPRE00, after it has built the update record, Quota puts the location of that record in the IEXRSVWD field in the DADSM parameter list (DPL). At VDSPOST0, Quota retrieves the location of the update record from this field in the DPL, and then updates the CQT with it. The following illustration shows a simplified view of this process. The exposure arises because other program products can also use the IEXRSVWD field in the DPL. Quota has a good neighbor policy. At VDSPRE00-time, it saves the original contents of this field in the update record. At VDSPOST0-time, it restores it. Other program products cannot be relied on to do so. If they do not, and they are hooked before CA Allocate, the Statistics are lost. Even if other program products practice the good neighbor policy of saving the original contents of this field and restoring it when they are done, there is still an exposure. For example, consider the situation depicted in the following illustration. Suppose another program product, with hooks at both places, also uses this field in the DPL to pass information. If the installation order is IGGPRE00-xxxPRE00-VDSPRE00 and IGGPOST0-VDSPOST0-xxxPOST0, the Statistics are lost. When Quota gets the DPL at VDSPOST0-time, the IEXRSVWD field does not contain the pointer to the Statistics. It contains whatever information the other program product's hook put there at xxxpre00- time. The way to avoid such exposures is to adjust the startup times of both products to ensure that one of them completes its installation before the other one begins. Quota 198