CA ACF2 for z/os. IMS Support Guide. r15. Third Edition

CA ACF2 for z/os IMS Support Guide r15 Third Edition

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 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors. Copyright 2013 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Contact CA Technologies Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At http://ca.com/support, you can access the following resources: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to techpubs@ca.com. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at http://ca.com/docs.

Documentation Changes The following documentation updates have been made since the last release of this documentation: Update IMS System Definition Removed text associated with the SECURITY macro. Changed all references CTBXPOOL field in the Storage record to IPBXPOOL. Security in IMS DBCTL (see page 323) Added new appendix.

Contents Chapter 1: IMS Interface Philosophy 17 Documentation Set... 17 Command Notation... 17 Design Concepts and Features... 19 CA ACF2 and the IMS Interface Validation Processing... 21 Protected IMS Resources... 23 Network Security... 25 IMS Security Options... 25 Chapter 2: Planning Considerations 27 Design Concepts and Features... 27 Default Logonid... 27 Region Logonids... 28 Reports... 28 User Logonids... 28 Planning Checklist... 29 Chapter 3: IMS Records 33 Design Concepts and Features... 33 ACF Subcommand... 33 IMS Record Key... 34 Creating and Modifying IMS Records... 35 EXITS Record-The IMS Interface Exit Specifications... 36 Field Descriptions... 37 Network Record - Network Security Specifications... 37 Field Descriptions... 38 OPTS Record-The IMS Interface Option Specifications... 39 Field Descriptions... 40 RESOURCE Record-Resource Validation Processing... 42 Field Descriptions... 44 SIGNON Record-Sign-on... 45 Field Descriptions... 46 Storage Record-Storage Options... 47 Field Descriptions... 47 SYSPLEX Record-IMS interface SYSPLEX feature... 48 Field Descriptions... 49 Contents 5

WTO Record-Write to Operator Messages... 49 Field Descriptions... 50 Chapter 4: Defining Logonids 51 Design Concepts and Features... 51 Region Logonids... 52 User Logonids... 54 Automatic Terminal Signon Logonids... 54 Default Logonids... 54 Logonid Records... 56 Chapter 5: System Control Options 69 Design Concepts and Features... 69 Control Region Access Authority... 69 Control Region Default Logonid... 69 Idle Time Reverification... 69 Logonid Suspension... 70 Multiple Sign-on Control... 70 New Password Verification... 70 Security Mode... 70 Sign-on Format... 70 Sign-on Message Delivery... 70 Successful Sign-on Format... 71 Terminal Messages... 71 Write To Operator Messages... 71 Interface Control Options... 72 Control Region Access Authority (AUTH)... 73 Control Region Default Logonid (DFTLID)... 73 Idle Time Reverification (IDLE)... 74 ISRT Transaction Validation (ISRTNVAL)... 74 Logonid Suspension (SUSPEND)... 75 Maximum Security Violations (MAXVIO)... 75 Message Driven BMP Validation (BMPMSG)... 76 MTO Default Logonid (MTOUSID)... 77 Multiple Sign-on Control (ENQNAME)... 77 New Password Verification (NPVERIFY)... 79 Non-Message Driven BMP Userid (BMPUSID)... 79 Password Reverification Limits (PWMAXVIO)... 80 Security Mode (MODE)... 80 Sign-on Format (FORMAT)... 81 6 IMS Support Guide

Sign-on Message Delivery (NOTIFY)... 81 Successful Sign-on Format (PSFORMAT)... 82 Terminal Messages (MSGBASE)... 82 Transaction Classification (FMTPTRAN)... 82 Unknown Logonid Processing (NLIDDFLT)... 83 Write To Operator Messages... 83 Chapter 6: Transaction Security 87 Design Concepts and Features... 87 IMS Transactions... 87 Implementing Transaction Validation... 89 Step 1: Validating Transactions... 89 Step 2: Protecting Transactional Sequences... 90 Step 3: Defining IMS RESOURCE Records... 94 Step 4: Writing Transaction Resource Rules... 95 Chapter 7: AGN and RAS Resource Security 99 Design Concepts and Features... 99 IMS and IMS Interface AGN Processing... 100 Defining Application Group Names to SMU... 101 Defining an IMS RESOURCE Record for AGN Validation... 101 Writing Application Group Name Resource Rules... 102 RAS Security... 103 Defining an IMS RESOURCE Record for RAS Transaction Validation... 103 Writing Resource Rules for RAS Transaction Security... 104 Defining an IMS RESOURCE Record for RAS PSB Validation... 104 Writing Resource Rules for RAS PSB Security... 105 Defining an IMS RESOURCE Record for RAS LTERM Validation... 105 Writing Resource Rules for RAS LTERM Security... 106 Chapter 8: IMS Command Security 107 Design Concepts and Features... 107 Default IMS Security... 107 Security Maintenance Utility (SMU)... 108 IMS Interface Validation of Terminal Commands... 108 IMS Interface Validation of Type 1 AOI Commands... 109 IMS Interface Validation of Type 2 AOI Commands... 111 AOI Commands in an IMS Shared Queues Environment... 113 Implementing Command Validation... 113 Step 1: Validating Commands... 114 Contents 7

Step 2: Defining IMS RESOURCE Records for Command Validation... 114 Step 3: Writing Command Resource Rules... 116 Exit Processing and IMS Command Keyword Security... 117 Chapter 9: PSB Security 119 Design Concepts and Features... 119 Defining IMS RESOURCE Records... 120 Writing PSB Resource Rules... 120 Chapter 10: MSC and ISC Link Security 123 Design Concepts and Features... 123 ISC Concepts... 123 MSC Concepts... 124 Default IMS Interface Security for MSC and ISC Links... 126 Default IMS Interface Security for ISC Links... 126 Default IMS Interface Security for MSC Links... 127 Extended IMS Interface Security for MSC and ISC Links... 128 IMS NETWORK Records... 129 Chapter 11: LOCK and UNLOCK Command Resource Security 133 Design Concepts and Features... 134 Transactions on the LOCK and UNLOCK commands... 134 Defining the IMS RESOURCE Record... 135 Writing the Resource Rules... 135 Programs on the LOCK and UNLOCK commands... 136 Defining the IMS RESOURCE Record... 136 Writing the Resource Rules... 137 Databases on the LOCK and UNLOCK commands... 137 Defining the IMS RESOURCE Record... 137 Writing the Resource Rules... 138 LTERMs on the LOCK and UNLOCK commands... 139 Defining the IMS RESOURCE Record... 139 Writing the Resource Rules... 139 Chapter 12: APPC Security 141 Design Concepts and Features... 141 APPC Processing... 142 System Authorization Facility (SAF)... 142 Program-to-Program (PTP) Message Switching... 142 8 IMS Support Guide

Security processing during APPC session establishment... 142 IMS Interface Network Security for APPC... 143 IMS NETWORK Records... 143 SAF Security for APPC/IMS... 145 Requesting APPC/IMS SAF security... 145 Implementing APPC/IMS SAF Security... 145 Choosing Your APPC Security Implementation... 148 Using IMS Interface NETWORK Security without APPC/IMS SAF... 149 Using APPC/IMS SAF and IMS Interface NETWORK Security... 150 Using APPC/IMS SAF without the IMS Interface NETWORK Security... 151 Not Using APPC/IMS SAF or the IMS Interface NETWORK Security... 152 DFSAPPC... 152 Chapter 13: OTMA Security 153 Design Concepts and Features... 153 OTMA Processing... 154 System Authorization Facility (SAF)... 154 Program-to-Program (PTP) Message Switching... 154 IMS Interface Network Security for OTMA... 154 IMS NETWORK Records... 155 SAF Security for IMS OTMA... 156 Requesting SAF security for IMS OTMA... 157 Implementing IMS OTMA SAF Security... 157 Choosing Your OTMA Security Implementation... 160 Using IMS Interface NETWORK Security without IMS OTMA SAF... 160 Using IMS OTMA SAF and the IMS Interface NETWORK Security... 161 Using IMS OTMA SAF without the IMS Interface NETWORK Security... 162 Not Using IMS OTMA SAF or the IMS Interface NETWORK Security... 163 TPIPE Security for the RESUME TPIPE Request... 163 Chapter 14: IMS Shared Queues and Security 167 Overview... 167 Design Concepts... 168 Shared Queues... 168 Front-end Region... 168 Back-end Region... 168 Program-to-Program Message Switching... 169 Automated Operator Interface Commands... 169 AUTH Calls... 169 Default Processing... 170 Contents 9

Design Features... 171 CA ACF2 IMS SYSPLEX Feature... 171 SYSPLEX Feature Processing... 173 CA ACF2 IMS Shared Queues NETWORK Record... 176 Choose Your Security Process... 178 Chapter 15: ACF Transaction 183 ACF Transaction... 183 END Request... 183 SET Request... 183 Parameters... 184 INSERT Request... 184 Parameters... 184 CHANGE Request... 185 Parameters... 185 DELETE Request... 186 Parameters... 187 LIST Request... 187 Chapter 16: ACF Command 189 Design Concepts and Features... 189 RELOAD Function... 190 Syntax... 190 Parameters... 190 Processing... 190 Response... 191 RESET CACHE Function... 191 Syntax... 191 Parameters... 191 Processing... 191 Response... 191 RESET LINK Function... 192 Syntax... 192 Parameters... 192 Processing... 193 Response... 193 SHOW LINK Function... 193 Syntax... 193 Parameters... 193 Processing... 194 10 IMS Support Guide

Response... 194 SHOW SIGNON Function... 195 Syntax... 195 Parameters... 195 Processing... 195 Response... 195 SHOW STATE Function... 195 Syntax... 195 Parameters... 196 Processing... 196 Response... 197 SHOW STORAGE Function... 198 Syntax... 198 Parameters... 198 Processing... 198 Response... 199 SHOW SYSPLEX Function... 200 Syntax... 200 Parameters... 201 Processing... 201 Response... 201 SYSPLEX CLEAR Function... 201 Syntax... 202 Parameters... 202 Processing... 202 Response... 202 SYSPLEX START Function... 202 Syntax... 202 Parameters... 203 Processing... 203 Response... 203 SYSPLEX STOP Function... 203 Syntax... 203 Parameters... 204 Processing... 204 Response... 204 The ACF Command in an IMSplex... 204 Chapter 17: Reports 205 Design Concepts and Features... 205 Report Generators... 205 Contents 11

ACFRPTEL-The Infostorage Update Log... 205 ACFRPTPW-The Invalid Access/Authority Log... 205 ACFRPTRV-The Generalized Resource Event Log... 206 ACFRPTRX-The Logonid Access Report... 206 ACFRPTXR-The Cross-Reference Report... 207 ACFRGP-The Resource Grouping Utility... 207 Chapter 18: Additional Considerations 209 Design Concepts and Features... 209 The /ACF Command... 209 The AUTH Call... 209 Idle Time... 209 Resource Rule Directories... 210 The VERIFY Keyword... 210 The Greeting Message Exit... 210 Using Password Reverification... 210 Idle Time Considerations... 211 VERIFY Considerations... 212 Using Rule Directories... 212 Loading and Reloading Globally Resident Directories... 213 Loading and Reloading Locally Resident Directories... 214 Maintaining IMS Records... 214 Signing On With The IMS Interface... 214 Requiring Terminals to Sign On... 215 Signing On With an MFS Format... 216 Verifying a New Password... 217 Changing Sign-on Messages... 218 Automatic Terminal Signon... 219 Understanding Security Implications of the ACF Transaction... 219 Supporting Transactions that Submit Jobs... 220 Supporting the AUTH Call with the IMS Interface... 221 AUTH Call... 221 Issuing the AUTH Call... 222 IMS Interface Processing of the AUTH Call... 223 Information Returned to the Application Program... 223 Chapter 19: Storage 225 Design Concepts and Features... 226 Pool Processing... 226 Types of Storage Area Pools... 227 12 IMS Support Guide

Storage Utilization... 228 CA ACF2 Storage Requirements... 228 IMS Interface Storage Requirements... 228 The Storage Record... 230 Tuning the IMS Interface Storage Allocations... 233 CACHENT# Option... 233 IMS Interface Storage Pools... 234 Chapter 20: Installation Procedure 237 Pre-Installation Requirements... 237 Packaging Considerations... 238 Design Concepts and Features... 239 Overview of the Installation Procedure... 239 ACFFDR Values Relevant to the IMS Interface... 239 How You Acquire the Product... 240 Installation Checklist... 240 Prepare the z/os System for the CA ACF2 IMS Installation... 241 Complete the CA ACF2 Requirements... 241 Install the IMS Interface in an IMS Control Region... 241 Detailed Installation Instructions... 242 Make IMS Interface APF-Authorized... 242 Create or Update the IMS Interface APPLDEF Records... 242 Customize ACFFDR... 243 Create or Update IMS User Messages Table... 245 Define ACF Command... 245 Update IMS System Definition... 246 Run IMS System Definition... 246 Modify IMS Command Table... 247 Provide CA ACF2 Logonid Maintenance... 247 Provide MFS Format... 247 Modify the IMS OM Command Table... 248 Create/Modify IMS Interface Options, Logonids, Rules... 249 Initialize IMS Interface... 250 Chapter 21: User Exits 251 Design Concepts and Features... 252 Exit Procedures and Considerations... 253 Defining the IMS Exits Record... 254 Initialization Exit (INITIAL)... 254 Exit Control Area DSECT... 255 Contents 13

Exit Control Area Fields that Can Be Supplied or Changed... 255 Presign-on Exit (PRESIGN)... 255 Exit Control Area DSECT... 256 Descriptions of Some Exit Control Area Fields... 256 Exit Control Area Fields that Can Be Supplied or Changed... 256 Sign-on Exit (SIGNON)... 257 Exit Control Area DSECT... 258 Descriptions of Some Exit Control Area Fields... 258 Exit Control Area Fields that Can Be Supplied or Changed... 259 Sign-off Exit (SIGNOFF)... 260 Exit Control Area DSECT... 261 Descriptions of Some Exit Control Area Fields... 261 Exit Control Area Fields that Can Be Supplied or Changed... 261 Prevalidation Exit (PREVAL)... 262 Exit Control Area DSECT... 263 Descriptions of Some Exit Control Area Fields... 265 Exit Control Area Fields that Can Be Supplied or Changed... 266 Postvalidation Exit (POSTVAL)... 268 Exit Control Area DSECT... 269 Descriptions of Some Exit Control Area Fields... 271 Exit Control Area Fields that Can Be Supplied or Changed... 271 Idle Time Exit (IDLE)... 271 Exit Control Area DSECT... 272 Exit Control Area Fields that Can Be Supplied or Changed... 272 Chapter 22: Migration 275 Migrating from Prior Releases of the CA ACF2 IMS Interface to r9 or Above... 275 Migrating from Prior Releases of the CA ACF2 for z/os to r9... 277 Appendix A: SMU Conversion 279 Converting Type 1 AOI Command Security to CA ACF2... 280 SMU Security for Type 1 AOI Commands... 280 CA ACF2 Security for Type 1 AOI Commands... 281 Implementation Steps for AOI=TRAN Security... 282 The ACFDCSM1 Utility... 283 Executing the ACFNRULE Statements... 289 Implementation Steps for AOI-YES Security... 290 The ACFDCSM3 Utility... 291 Converting AGN Security to RAS... 298 Application Group Names... 298 14 IMS Support Guide

Resource Access Security... 299 Converting Terminal Based Security to CA ACF2... 307 SMU Terminal-Based Security for Transactions and Commands... 307 CA ACF2 Security Transactions and Commands... 308 Converting SMU Terminal-Based Security to CA ACF2... 309 SMU Functionality Without CA ACF2 Equivalent... 318 SMU Signon Requirements... 318 Password for IMS Resources... 319 ACFDCSM5 Utility... 320 Appendix B: Security in IMS DBCTL 323 Overview... 323 Design Concepts... 323 CSL OM Environment... 324 IMS Commands... 324 IMS DBCTL Region... 324 MCS and EMCS Consoles... 324 Program Specification Block... 324 System Authorization Facility (SAF)... 325 Resource Security in DBCTL... 325 Program Specification Block... 325 Commands... 325 CA ACF2 IMS Security for DBCTL Resources... 325 Program Specification Block... 326 Commands from MCS/EMCS Consoles... 326 Commands from Application Programs... 326 Commands from the SCL OM Environment... 326 Implementing CA ACF2 IMS Security for DBCTL... 327 IMS Control Records for DBCTL... 327 Implementing CA ACF2 IMS Security for DBCTL... 328 The /ACF Command in DBCTL... 329 SAF Security for DBCTL Resources... 329 Program Specific Block... 329 Commands from MCS/EMCS Consoles... 329 Commands from Application Programs... 329 Commands from the SCL OM Environment... 330 Contents 15

Chapter 1: IMS Interface Philosophy The IMS Support Guide is both a tutorial and a reference guide for IMS users who install and implement the CA ACF2 IMS interface (IMS interface) in an IMS control region. The intended audience for this guide consists of security administrators, database administrators, and systems programmers. A working knowledge of the IMS TM (Transaction Manager) environment and of the CA ACF2 for z/os (CA ACF2) host product is required to understand this guide. This section contains the following topics: Documentation Set (see page 17) Documentation Set In addition to this guide, there are several other guides that comprise the CA ACF2 documentation set. For a complete list of the CA ACF2 documentation set and related documentation, see the Administrator Guide. The following publications are not produced by Computer Associates, but might be used for reference and are recommended reading: IMS Command Reference IMS Application Programming: Transaction Manager MVS Routing and Descriptor Codes Command Notation This guide uses the following command notation. Enter the following exactly as they appear in command descriptions: UPPERCASE Identifies commands, keywords, and keyword values that must be coded exactly as shown. MIXed Cases Identifies command abbreviations. The uppercase letters are the minimum abbreviation; lower case letters are optional. Symbols All symbols (such as equal signs) must be coded exactly as shown. Chapter 1: IMS Interface Philosophy 17

Documentation Set The following clarify command syntax; do not type these as they appear: lowercase Indicates that you must supply a substitution (a user-supplied value). [ ] { } Identifies optional keywords or parameters. Requires choosing one of the keywords or parameters listed. Underlining Shows default values that need not be specified.... Separates alternative keywords and parameters, choose one Preceding items or group of items can be repeated more than once. Sample Command DEComp {* ruleid Like(ruleidmask)} [Into(dsname)] Explanation: DEC Command abbreviation. * Required alternative keyword. ruleid Required alternative keyword. Like(ruleidmask) Required alternative keyword. Into(dsname) Optional parameter. This chapter provides a general description of the IMS security interface for the IMS TM (Transaction Manager) environment. Major IMS interface design concepts and features are introduced. A fundamental description of the IMS interface validation processing is provided, and the interaction of the IMS interface and CA ACF2 is described. A brief summary of IMS security options is also provided. This summary includes general information about other CA ACF2 and IMS interface products available to IMS users. 18 IMS Support Guide

Documentation Set Design Concepts and Features CA ACF2 IMS TM Interface The IMS TM (Transaction Manager) interface provides maximum security for IMS online resources and provides CA ACF2 product consistency. The following security concepts and features constitute the basis of the IMS TM Interface. There are several CA ACF2 security products. To install and implement the IMS TM Interface, CA ACF2 must also be installed. Unlike other security software products on the market, CA ACF2 protects data by default, meaning as soon as you install it in your system, data is automatically secured. After you install, you can discriminately grant access to data. In keeping with this CA ACF2 security philosophy, the IMS interface also provides protection by default. CA ACF2 and the IMS interface interact to provide maximum security. CA ACF2 provides data set security while the IMS interface protects resources such as IMS transactions. This interface protects IMS resources in the IMS TM (Transaction Manager) environment. Global System Options (GSO) Records IMS Records GSO records define CA ACF2 security options. Although you use GSO records to implement CA ACF2, you do not use them to implement the IMS interface. IMS records implement the IMS interface. IMS records have options similar to the GSO records, but they are tailored to the needs of IMS interface users. IMS records define the type and level of security that the IMS interface provides. They define the specific action the IMS interface takes in the event of an attempted access or use of an IMS resource. There are several types of IMS records: IMS OPTS Implements the IMS interface control functions. These control functions determine how the IMS interface processes validations for the entire IMS TM environment. IMS WTO Defines control options for write to operator (WTO) messages for the IMS interface. IMS EXITS Defines user exits for the IMS interface. Chapter 1: IMS Interface Philosophy 19

Documentation Set IMS SIGNON Specifies how the IMS interface validates sign-ons. IMS RESOURCE Defines the IMS resources that are protected by the IMS interface. Each type of resource has its own RESOURCE record. For example, IMS transaction validations are controlled by a transaction RESOURCE record. IMS NETWORK Defines options that control how the IMS interface provides security for network connections in an IMS system. These network connections include ISC and MSC links, and APPC and OTMA connections. A NETWORK record is also supported for the IMS Shared Queues (SQ) environment. IMS STORAGE Defines options that control the IMS interface use of storage. IMS SYSPLEX Control the IMS interface SYSPLEX feature, which uses a coupling facility structure in an IMS shared queues environment. IMS records are stored in the Infostorage database and retrieved from the database when the corresponding IMS region is initiated. Network Security The IMS interface protects IMS resources in IMS control regions that receive transactions from other control regions and systems in the network. Resource Rules The IMS interface uses standard CA ACF2 resource rules to secure IMS resources. A resource rule defines who or what can access a particular resource. It contains the following components: The name of the resource to be secured by the rule What the identified users can do with the resource named The conditions under which access is permitted (See the Administrator Guide for more information about resource rules. The glossary in this guide includes a definition of the UID.) 20 IMS Support Guide

Documentation Set Security Inheritance User Exits Validation Caching The IMS interface security functions for IMS online processing are built on a design foundation called security inheritance. The inherited element is the user's CA ACF2 logonid. Specifically, security inheritance is the method of associating a user with a transaction and all the transactions that it invokes. For example, when Jane Doe enters an IMS transaction code at her terminal, IMS interface uses her CA ACF2 logonid to determine whether to permit IMS to execute the transaction for Jane Doe. The correspondence between Jane Doe's logonid and the transaction remains intact until the transaction and all the transactions that it invokes are completely processed. Security inheritance ensures that IMS users execute only those transactions assigned to them in the CA ACF2 resource rules. The benefits of security inheritance are described in more detail in the IMS Security Options section. The IMS interface lets you use exits that interact with the interface to perform security functions of your own design. You can program these exits to override the IMS interface validations with a different type of validation. You can also program them to provide additional validations. Validation caching is a major performance feature of the IMS interface. It is the process of recording allowed accesses to resources and keeping this information in storage (a cache) for quick reference. After an access authority is recorded in the cache, the IMS interface can refer to the cache each time additional access attempts are made that are based on the recorded access authority. Use of the cache for validation references saves the IMS interface processing time. Without validation caching, it would need to perform a resource rule interpretation each time it processed a validation, which would be far more time consuming than referring to the more readily available cache. CA ACF2 and the IMS Interface Validation Processing Data Set Access Validations The IMS TM Interface interacts with CA ACF2 to secure IMS TM environments. Data set access validations are performed by CA ACF2. CA ACF2 and the IMS interface work in conjunction to perform system entry and resource access validations. Data set access validations are performed entirely by CA ACF2. When a user attempts access to a data set, CA ACF2 determines whether to permit or deny the requested access by consulting the Rules database. Chapter 1: IMS Interface Philosophy 21

Documentation Set System Entry Validations Resource Access Validations The method of validating data set accesses depends upon the CA ACF2 security mode. When CA ACF2 is in ABORT mode (the default mode), unauthorized access attempts are denied. When CA ACF2 is in WARN mode, all data set access attempts are permitted; however, the z/os console operator might be warned when an unauthorized access is made, and the unauthorized access is logged. When CA ACF2 is in LOG mode, all data set access attempts are permitted, but all unauthorized accesses are logged and can be easily traced by a security administrator. When CA ACF2 is in QUIET mode, data set access attempts are not validated. When system access is attempted (that is, sign-on), the IMS interface gathers pertinent user information such as the logonid, password, terminal ID, and, if specified, the group name, and it passes the information to CA ACF2. CA ACF2 checks the Logonid database to determine whether the user can perform the sign-on function. A user is authorized to sign on if CA ACF2 finds the user's logonid record, a matching password, and matching source and shift conditions. In addition, if a group name was specified at sign-on, CA ACF2 verifies that the user has the authority to use that group's access privileges. If all of the user information satisfies the requirements for system access, CA ACF2 passes to the IMS interface a recommendation to let the user access the system. The IMS interface then determines whether the user is authorized to access the particular IMS control region. If all CA ACF2 and IMS interface system entry requirements are met, the IMS interface permits the IMS system to process the sign-on request. If any of the requirements are not met, the sign-on request is terminated. When the IMS interface validates a resource access request (for example, an attempt to issue an IMS transaction), it passes the associated logonid, source, resource type code, and resource name to CA ACF2. CA ACF2 compares this information to the resource rule and to the source and shift conditions defined in the Infostorage database. If the information satisfies the access requirements, CA ACF2 recommends to the IMS interface that access be permitted. If the user information does not satisfy the access requirements, CA ACF2 recommends to the IMS interface that access to the resource be denied. The method of validating resource accesses depends upon the IMS security mode. If the IMS interface is in ABORT mode, it acts in accordance with the CA ACF2 recommendation. If it is in LOG mode, access to the resource is permitted, regardless of the CA ACF2 recommendation; however, all unauthorized accesses are recorded. When the subsystem is in QUIET mode, resource access attempts are not validated. The IMS TM Interface does not support WARN mode. 22 IMS Support Guide

Documentation Set Validation Caches and Exits Validation caches and user exits can alter the resource validation processing previously described. For IMS terminal users who are signed on, the IMS interface builds a validation cache when the user signs on. Whenever the user is granted access to a protected resource, the IMS interface records this fact in the cache and refers to the cache whenever these access requests are repeated during the same session. Referring to the cache for resource validations enables the IMS interface to bypass the CA ACF2 validation processing and eliminate some processing overhead. When the user signs off, the cache is erased. The next time this user signs on, the process begins again; the initial resource access requests are validated through CA ACF2 normal processing, and a new cache is built for the authorized accesses of the new session. If a successful access request comes from a terminal that is not signed on, the IMS interface creates and maintains a cache for the default logonid for that terminal. Cache and validation processing takes place as previously described. This cache, however, is scanned periodically. When the IMS interface determines that the terminal is no longer active, the associated cache is erased. User exit programs can be used to tailor validation processing to a site's unique security needs. The exit programs can change or override the CA ACF2 and the IMS interface resource validations. For more information about these exits, see the chapter Installation Procedures. Protected IMS Resources Transaction Security AGN Security The IMS TM Interface protects the following IMS resources. The IMS interface validates IMS transactions before they reach the message queue in the IMS control region. In general, transactions are validated when they are initiated directly from a terminal or indirectly from a BMP or another transaction. The IMS interface validates transactions by matching UIDs and access conditions with transaction resource rules. To ensure that a correct match of a UID to a resource rule is made, the IMS interface provides security inheritance. (See Design Concepts and Features earlier in this chapter for a description of security inheritance.) The IMS interface protects AGNs that are accessed by IMS dependent regions such as BMPs. AGN security lets you control the transactions, terminals, and PSBs a dependent region is permitted to access. Validation processing for AGNs is performed by matching the dependent region's UID and access conditions to AGN resource rules. Chapter 1: IMS Interface Philosophy 23

Documentation Set RAS Security for Transactions, PSBs, and LTERMs PSB Security Command Security In IMS release 9.1 and above, Resource Access Security (RAS) is available as a replacement for AGN security. If RAS security is enabled, AGN security cannot be used. The IMS interface performs security validations for the transactions, PSBs, and LTERMs that are accessed by IMS dependent regions. Validation processing for these resources is performed by matching the dependent region's UID and access conditions to the appropriate resource rules. The IMS interface protects PSBs that are used by BMPs. Validation processing for these PSBs is performed by matching the BMP region's UID and access conditions to PSB resource rules. The IMS interface protects IMS commands issued directly by a terminal user or indirectly by application programs using the ICMD communications call. For IMS release 9.1 and above, the IMS interface also protects IMS commands issued by applications programs using the CMD communications call. Validation processing for commands is performed by matching the user's UID and access conditions to command resource rules. Resources on the LOCK and UNLOCK Commands OTMA Transaction Pipes (TPIPEs) For IMS release 9.1 and above, the IMS interface performs security validations for transactions, programs, LTERMs, and databases that are specified on the IMS LOCK and UNLOCK commands. Validation processing for these resources is performed by matching the user's UID and access conditions to the appropriate resource rules. For IMS Version 10 and above, the IMS interface performs security validations for OTMA transaction pipes (TPIPEs) that are specified by an OTMA client on a RESUME TPIPE request. Validation processing for these resources is performed by matching the RETUME TPIPE requestor's UID and access conditions to the appropriate resource rules 24 IMS Support Guide

Documentation Set Network Security The IMS TM Interface secures IMS resources that can be accessed through a network communications link to the IMS region. The IMS interface validates all attempts to access a resource in an IMS control region at the receiving end of a link. These network validations are performed in one of three ways: Matching the UIDs of user logonids inherited from the sending IMS control region to resource rules Matching the UIDs of link default logonids and their access conditions to resource rules Matching the UID of the IMS control region default logonid to resource rules IMS Security Options IMS Security Functions The following options are available in providing security in the IMS environment: IMS security functions The IMS Batch Interface The IMS TM Interface IMS provides SMU and PSBs to protect commands, transactions, and databases. SMU (Security Maintenance Utility) protects commands and transactions, but it does not provide individual accountability among users because commands and transactions are validated against terminal IDs rather than user logonids. Particular terminals are permitted or denied the ability to execute a command or transaction, and all users working from the same terminal have the same privileges. To attain different privileges, the user can use another terminal that has the other privileges assigned to it. Another security problem IMS users encounter with SMU is the inability to protect secondary transactions. Terminals that are permitted to execute primary transactions are also permitted (indirectly) to execute associated secondary transactions. PSB security consists of permitting application programs access to particular database segments. To access a database segment, an application program requires a PSB that defines the database segments it is permitted to access. In batch and BMP environments, the most serious security problem with the PSB security is the user's ability to use any PSB with any application program. Therefore, security control provided by the PSB can be easily bypassed. Chapter 1: IMS Interface Philosophy 25

. Documentation Set IMS Batch Interface The IMS Batch Interface was developed specifically for the IMS batch environment. The interface protects database segments and PSBs by associating users with segment and PSB resource rules. The major advantage the IMS Batch Interface has over previous methods of securing IMS resources is that it provides individual accountability among users For more information about the IMS Batch interface, see the IMS Batch Support Guide. IMS TM Interface The IMS TM Interface was developed specifically for the IMS online or TM (Transaction Manager) environment. The IMS TM Interface protects IMS resources in the online environment and provides individual accountability by associating users (UIDs) with resource rules and access conditions. The IMS interface security inheritance enables this individual accountability to remain intact for both primary and secondary transaction validations. 26 IMS Support Guide

. Chapter 2: Planning Considerations This chapter gives you an idea of the scope of the decision-making and tasks required to install and implement the IMS TM Interface. You can use the step-by-step plan provided in this chapter as a checklist of things to do to ensure the smooth flow of your installation and implementation efforts This chapter also assists you by prioritizing and timing the tasks. The tasks on the checklist are presented in the order that they should be performed. For example, we recommend that even though you can install the IMS interface before any IMS record options are selected, you should select the options before you install the interface. This section contains the following topics: Design Concepts and Features (see page 27) Planning Checklist (see page 29) Design Concepts and Features The concepts and features included in this chapter reflect the major planning issues you must consider before you install and implement the IMS TM Interface. Default Logonid When no logonid is submitted or inherited with a request, the CA ACF2 IMS interface assigns a default logonid to the request to perform access validations. The IMS interface uses two kinds of default logonid: Control Region Default-Logonid to validate unknown users, that is, users who have submitted transaction requests without signing on, thereby rendering them as unknown to the IMS interface. Network Link Default Logonids-Link default logonid to validate a resource access attempt made from a link in an IMS network when the associated user logonid is not inherited. Chapter 2: Planning Considerations 27

Design Concepts and Features Region Logonids CA ACF2 uses region logonids to validate the initiation of IMS regions. Region logonids also validate data set and resource access attempts made by the region. These logonids are as follows: BMP Region Logonids-Determines if the BMP can be initiated. The IMS interface uses the BMP logonid to validate tasks initiated by the BMP, for example, transactions that the BMP places on the message queue. Control Region Logonid-Validates data set access attempts made by the control region. This logonid is also known as a MUSASS logonid. DBRC Region Logonid-Validates initiation of the IMS database recovery region and data set access requests made by the database recovery region. DLISAS Region Logonid-Validates initiation of the DLISAS region. Data set access requests made by the DLISAS region are validated with the DLISAS logonid. Fast Path Region Logonid-If your site is using IMS fast path regions, you must create fast path region logonids. CA ACF2 uses the fast path region logonid to determine whether to permit initiation of the IMS fast path region and to validate data set access attempts made by the fast path region. IMSRDR Region Logonid-Determines whether to permit initiation of the IMS reader and to validate data set access attempts Message Processing Region Logonid-Determines whether to permit initiation of the IMS message-processing region and to validate data set access attempts made by the message-processing region. Reports The IMS Interfaces use the CA ACF2 base product security reports that inform the security administrator of security violations. The reports also provide general status information about logonids, resources, and the Infostorage database. User Logonids You must define logonids for all IMS users. Users enter their logonids when they sign on to IMS. 28 IMS Support Guide

Planning Checklist Planning Checklist Administrators and security administrators can use this section to ensure the smooth flow of the IMS interface installation and implementation events. It can also be used to ensure that nothing is overlooked during the installation and implementation of the IMS interface. The items on the following list reflect the tasks you must complete to implement and install a single IMS TM Interface. If you must plan for more than one IMS TM Interface, you can make copies of this checklist so you can use it again. 1. Make sure that your site has the following IMS interface prerequisite software: IMS Release 9.1 or above CA ACF2 r15 or above Any supported release of z/os 2. Modify the CA ACF2 system generation to include macro definitions for the IMS interface. The systems programmer can modify the generation while the security administrator plans for the IMS records. Modify the following ACFFDR macros: @MUSASS @MLID @CFDEs 3. Determine the interface control functions for IMS interface processing: The OPTS record The WTO record The SIGNON record The NETWORK records The SYSPLEX record Chapter 2: Planning Considerations 29

Planning Checklist 4. Define your site's logonid requirements: Region logonids BMP regions Control region DBRC region DLISAS region Fast path regions IMSRDR region Message processing regions Default logonid Control region ISC links MSC links APPC OTMA User logonids 5. See the IMS RESOURCE records and determine your site's resource security requirements: Transactions Commands PSBs AGNs RAS security for transactions, PSBs, and LTERMs (IMS 9.1 and above) LOCK and UNLOCK resource security for transactions, programs, LTERMs, and databases (IMS 9.1 and above) OTMA TPIPE security for the RESUME TPIPE request (IMS Version 10 and above) 30 IMS Support Guide

Planning Checklist 6. Determine the types of exits you need. 7. Install the IMS interface: Ensure that you complete the most crucial IMS record planning before you install the IMS TM Interface. Ensure that you have made all migration decisions. See the IMS STORAGE record and determine the storage requirements for the IMS interface. See the IMS EXITS record, and determine the type of exits you want to use. Then, write whatever exit programs you have determined are necessary. Note: To create exits, the systems programmer and the security administrator must work together and understand the requirements. The exits' module names must be specified on the IMS EXITS record. Follow the procedures in the chapter Installation Procedures to install your site's IMS TM Interface 8. Create your IMS records at the terminal. 9. Set up or adjust CA ACF2 reports. 10. Create logonid records: Region logonids BMP regions Control region DBRC region DLISAS region Fast path regions IMSRDR region Message processing regions Default logonids Control region ISC link MSC link APPC OTMA User logonids Chapter 2: Planning Considerations 31

Planning Checklist 11. Create Resource Rules: Transaction Commands PSBs AGNs RAS security for transactions, PSBs, and LTERMs (IMS 9.1 and above) LOCK and UNLOCK resource security for transactions, programs, LTERMs, and databases (IMS 9.1 and above) OTMA TPIPE security for the RESUME TPIPE request (IMS Version 10 and above) 32 IMS Support Guide

Chapter 3: IMS Records This chapter provides a basic introduction to the IMS control records. It illustrates the various types of IMS records and describes generic procedural information. Detailed information regarding how to select and use specific options is provided in later chapters that discuss related security functions and features. This section contains the following topics: Design Concepts and Features (see page 33) Creating and Modifying IMS Records (see page 35) EXITS Record-The IMS Interface Exit Specifications (see page 36) Network Record - Network Security Specifications (see page 37) OPTS Record-The IMS Interface Option Specifications (see page 39) RESOURCE Record-Resource Validation Processing (see page 42) SIGNON Record-Sign-on (see page 45) Storage Record-Storage Options (see page 47) SYSPLEX Record-IMS interface SYSPLEX feature (see page 48) WTO Record-Write to Operator Messages (see page 49) Design Concepts and Features The IMS records are designed to provide a large assortment of security controls and features to let security administrators select the type of security most appropriate for your site's needs. This section describes how to use the ACF command facility to define the IMS records to the Infostorage database. ACF Subcommand Use the ACF command and its associated subcommands to create and modify all IMS records. You can issue the ACF command from TSO Ready mode or use the ACFBATCH utility, then enter the ACF subcommand to create an IMS record. For more information about the ACF command and the ACFBATCH utility, see your Administrator Guide. You must establish the ACF subcommand setting with the SET subcommand before you can execute any of the other ACF subcommands. The SET subcommand defines the infostorage record key that identifies the IMS records. After the ACF subcommand setting and the record key are established, you can execute the other ACF subcommands such as INSERT, CHANGE, and LIST. For more information about the ACF subcommands, see your Administrator Guide. Chapter 3: IMS Records 33

Design Concepts and Features IMS Record Key The record key for IMS records consists of the following identifiers: Infostorage Class Type A one-character ID that defines the CA ACF2 record class for all IMS records. All IMS records belong to the CONTROL class of CA ACF2 records; therefore, the one-character ID for all IMS records is the letter C. A three-character ID that defines the kind of record in the CA ACF2 record class. The letters IMS are specified for all IMS records. DIVISION(musid jobname) A one- to eight-character value defining the specific control region that uses this record. If you want to have more than one control region use this record, you can use the MDIVISION field instead of the DIVISION field and the standard CA ACF2 masking character, the asterisk (*). If you do not want to use masking, the DIVISION value must match the MUSID field value in the control region's logonid record. If you do not specify the MUSID field value, the DIVISION value must match the job name or the procname specified in the JOB statement in the region's startup JCL. Most security administrators prefer to use the MUSID field value because it is not affected by changes that are made to the startup JCL. If you use the job name or procname as the DIVISION value, any changes made to the JCL might require you to change the DIVISION value so that it matches the JCL. For more information about the DIVISION or MDIVISION field, see the explanations for SYSID and MSYSID in the Administrator Guide. For more information about the MUSID logonid record field, see the chapter Defining Logonids. Record ID An ID that defines the specific security function or feature that the IMS record implements. The following record IDs are available for IMS records: EXITS NETWORK OPTS RESOURCE SIGNON STORAGE SYSPLEX WTO 34 IMS Support Guide

Creating and Modifying IMS Records Qualifier A one- to eight-character ID that distinguishes one record from all others defined to the same infostorage class, type, DIVISION field, and record ID. The qualifier field provides a more specific naming convention. For example, a good analogy is the following: when several John Smiths are listed on an attendance list of a class, one way to distinguish them from each other is to add their middle names. Each middle name is the equivalent of a division field of a record key. If after you have added their middle names, you still have identical names, say, three John Joe Smiths, you might want to add a fourth name, such as Jr. or Sr. to distinguish them from each other. This name is the equivalent of the qualifier field of the record key. The qualifier is a mandatory part of the record key whenever you must create more than one of the same type of IMS record. For example, you must enter a qualifier if you are defining more than one IMS RESOURCE record to enable the IMS interface to distinguish one RESOURCE record from another. These IMS records can use qualifiers in their record keys: NETWORK RESOURCE Because each IMS control region can use only one of the following types of IMS records, these IMS records do not use qualifiers in their record keys: OPTS WTO EXITS SIGNON STORAGE SYSPLEX Creating and Modifying IMS Records This section describes how to enter IMS record keys and record options at a terminal. To create or modify an IMS record, enter the following commands from TSO Ready mode at your terminal: ACF SET C(IMS) {INSERT CHANGE} DIVISION(musid jobname) recid[qualifier] -. [option(value)] [ADD REP DEL] Chapter 3: IMS Records 35

EXITS Record-The IMS Interface Exit Specifications To insert an IMS OPTS record copying from one division to another, use the following syntax: INSERT USING(OPTS) SYS(TODIV) USYS(FROMDIV) If you use a value other than the option's default, enter the option and the value with the value enclosed in parentheses. If you use an option's default value, you do not need to enter the option with the INSERT subcommand. After you have established the control setting and the IMS record key, you can continue defining your IMS record by entering each option and its corresponding value. Use dashes at the end of each line to denote continuation. Leave the dash out at the end of the last line of the record to denote completion. Any modifications that you make to existing IMS records do not take effect until the IMS control region is restarted. For more information about the ACF command and subcommands, see your Administrator Guide. EXITS Record-The IMS Interface Exit Specifications The EXITS record specifies the module name for each user-written IMS interface exit. For complete information about each exit., see the chapter User Exits. The EXITS record is optional. It is required only if you are using exits. All exits are defined in one EXITS record. The /ACF SHOW STATE subcommand displays the IMS interface exits currently in effect. The EXITS record id and fields are shown in the following table: Record ID EXITS Fields IDLE(module) INITIAL(module) POSTVAL(module) PRESIGN(module) PREVAL(module) SIGNOFF(module) SIGNON(module) 36 IMS Support Guide

Network Record - Network Security Specifications Field Descriptions The following is a description of the fields of the EXITS record: IDLE(module) Specifies the name of the Idle Time exit module. INITIAL(module) Specifies the name of the Initialization exit module. POSTVAL(module) Specifies the name of the Postvalidation exit module. PRESIGN(module) Specifies the name of the Presign-on exit module. PREVAL(module) Specifies the name of the Prevalidation exit module. SIGNOFF(module) Specifies the name of the Sign-off exit module. SIGNON(module) Specifies the name of the Sign-on exit module. Network Record - Network Security Specifications The NETWORK record specifies security options for one or more network links. See the chapter MSC and ISC LinkNetwork Security, APPC Security, OTMA Security and IMS Shared Queues and Security for more information about network security. If you require more than one NETWORK record, you can append a qualifier to the record name in the format NETWORKqualifier to generate a unique record ID (for example, NETWORK001 or NETWORK.CARD). This optional qualifier can be up to eight characters, and must immediately follow the characters NETWORK. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters that can be used. The NETWORK record is optional. It is required only if you are using the IMS interface extended network security. The /ACF SHOW STATE subcommand displays the NETWORK record options in effect. The /ACF SHOW LINK subcommand displays the network links in an IMS system, the NETWORK record options in effect for each link, and some statistical information. Chapter 3: IMS Records 37

Network Record - Network Security Specifications The NETWORK record id and fields are shown in the following table: Record ID NETWORKqual Fields LINKNAME(linkname) TYPE(MSC ISC APPC OTMA SQ) DFTLID(linkdefaultlogonid) INBOUND NOINBOUND INHERIT NOINHERIT FORCSIGN NOFORCSIGN DEPTH(nn) TIMEOUT The fields of the NETWORK record are described in the IMS NETWORK Records topic. Field Descriptions The fields of the NETWORK record are described in the following: LINKNAME(linkname) With the TYPE field, this field specifies which IMS links this record controls. You can specify an individual link name or a mask. A dash (-) is not valid as a masking character for this field. If you wish to specify that this NETWORK record should apply to all links, type LINKNAME(********). TYPE(MSC ISC APPC OTMA SQ) With the LINKNAME field, this field specifies which IMS network links this record controls. DFTLID(linkdefaultlogonid) Use this field to specify a special default logonid for the link. This field is optional. INBOUND NOINBOUND Controls whether the IMS interface validates transactions received from a link. INBOUND validates the transactions. NOINBOUND does not validate the transactions. INHERIT NOINHERIT This field applies only when the TYPE field value is MSC, APPC, or OTMA. Controls whether the IMS interface validates with the originating logonid. INHERIT uses the logonid from the originating system. NOINHERIT ignores the originating logonid, and uses the link default logonid (if there) or the control region default logonid. 38 IMS Support Guide

OPTS Record-The IMS Interface Option Specifications FORCSIGN NOFORCSIGN This field applies only if the TYPE field value is MSC and you specify INHERIT. The field controls assumptions that the IMS interface makes about the sign-on status of the user in the originating system. DEPTH(nn) Use this field only when the TYPE field value is MSC, APPC, OTMA or SQ and you specify INHERIT. This field controls the amount of storage the IMS interface uses while securing network resource. OPTS Record-The IMS Interface Option Specifications The OPTS record specifies the options used to implement control functions of the IMS TM Interface. For more information about the OPTS record, see the chapter System Control Options." The OPTS record is required. All values are defined on one OPTS record. The /ACF SHOW STATE subcommand displays the OPTS record options currently in effect. The OPTS record id and fields are shown in the following table: Record ID OPTS Fields BMPUSID(USERID,PSBNAME) BMPMSG(BMPUSER,MSGUSER) DFTLID(IMSDFLT (dftlid) FMTPTRAN NOFMTPTRAN IDLE(IDLE (fieldname) ISRTNVAL NOISRTNVAL MAXVIO(10 nnnnn) MODE(QUIET LOG ABORT) MTOUSID(mtolid) MSGBASE(900 nnn) NLIDDFLT NONLIDDFLT PWMAXVIO(5 nnn) SUSPEND NOSUSPEND WTORUSID(wtorlid) Chapter 3: IMS Records 39

OPTS Record-The IMS Interface Option Specifications Field Descriptions The fields of the OPTS record are described in the following: BMPUSID(USERID,PSBNAME) Controls what is propagated as the userid for any transaction generated by a non-message driven BMP. If BMPUSID(USERID) is specified, the logonid for the BMP job is passed as the userid for transactions generated by the BMP. If the option is not specified, this is the default value. If BMPUSID(PSBNAME) is specified, the name of the PSB for the BMP job is passed as the userid for transactions generated by the BMP. Note: This option does not control the logonid used to validate commands and transactions generated directly by a non-message driven BMP. These commands and transactions are always validated using the logonid for the BMP job. However, when BMPUSID(PSBNAME) is specified and a transaction is generated by a non-message driven BMP, the PSBNAME is passed as the userid for the transaction. If the transaction generates other commands or transactions in turn, the generated commands and transactions are validated using the IMS default logonid. BMPMSG(BMPUSER,MSGUSER) Specifies the logonid used to validate commands and transactions generated by a message driven BMP. If BMPMSG(BMPUSER) is specified, the logonid for the BMP job is used to validate any commands or transactions generated by a message driven BMP. If the option is not specified, this is the default value. If BMPMSG(MSGUSER) is specified, the logonid associated with the last message read is used to validate any commands or transactions generated by a message driven BMP. Note: This option does not control the logonid propagated with transactions generated by a message driven BMP. For a transaction generated by a message driven BMP, IMS always passes the logonid of the last message read. If the transaction generates other commands or transactions, those commands and transactions are validated using this logonid. DFTLID(IMSDFLT (dftlid) Specifies a control region default logonid. The IMS interface uses a control region default logonid to ensure that all IMS resource accesses are validated, even if a user logonid is not provided. FMTPTRAN NOFMTPTRAN Specifies the transaction classification scheme to be used for terminal-entered transactions. 40 IMS Support Guide

OPTS Record-The IMS Interface Option Specifications IDLE(IDLE (fieldname) Specifies the symbolic name for a field in the logonid record that contains the maximum amount of time that can pass before idle time reverification forces revalidation of a user's password. You can create fields that let you define unique idle times for each control region that the user accesses. ISRTNVAL NOISRTNVAL Controls the validation for applications performing an ISRT call to a non-modifiable TP-PCB to generate a new IMS transaction. If NOISRTNVAL is specified, the CA ACF2 IMS interface performs a security validation for transactions generated by an ISRT call to a non-modifiable TP-PCB. This is the default. If ISRTNVAL is specified, the CA ACF2 IMS interface does not perform a security validation for transactions generated by an ISRT call to a non-modifiable TP-PCB. MAXVIO(10 nnnnn) Specifies the number of unauthorized access attempts that can occur before the IMS interface suspends a user's logonid. The default is 10. The maximum number you can enter is 32767. MODE(QUIET LOG ABORT) Defines the degree of security the IMS interface provides. MSGBASE(900 nnn) Specifies the number in the IMS User Messages Table that identifies the location of the IMS interface informational messages sent to an IMS terminal user. The maximum value you can specify in this field is 950. MTOUSID(mtolid) Specifies a special default logonid that will be used to validate commands and transactions from the IMS master terminal when no one is signed on to the master terminal. If the MTOUSID logonid is not defined, the IMS interface will use the IMS control region default logonid. NLIDDFLT NONLIDDFLT Controls what occurs when the CA ACF2 IMS interface is given a userid for validation that does not exist in the CA ACF2 logonid database. If NONLIDDFLT is specified, the CA ACF2 IMS interface issues an error message for the invalid logonid and denies access to the resource being requested. This is the default value. If NLIDDLFT is specified, the CA ACF2 IMS interface does not issue an error message for the invalid logonid. It performs the access validation using the IMS default logonid. Chapter 3: IMS Records 41

RESOURCE Record-Resource Validation Processing PWMAXVIO(5 nnn) Specifies the maximum number of password reverify attempts as a result of IDLE or resource rule VERIFY requests. SUSPEND NOSUSPEND SUSPEND is in effect after the maximum number of unauthorized access attempts are made (based on the number in the MAXVIO field). NOSUSPEND must be set to disable the logonid suspension. WTORUSID(wtorusid) Specifies a special default logonid that is used to validate commands and transactions from the IMS ready prompt on the z/os console when no one is signed on to the prompt. If the WTORUSID logonid is not defined, the IMS interface will use the IMS control region default logonid. Note: Signing on to the IMS console ready prompt should not be confused with signing on to the z/os console. Signing on to the console ready prompt is done by issuing a /SIGN command in response to the ready prompt RESOURCE Record-Resource Validation Processing The RESOURCE record specifies the validation processing performed for a particular type of IMS resource. For more information about this record see the chapters Transaction Security, AGN and RAS Resource Security, IMS Command Security, PSB Security, and LOCK and UNLOCK Command Resource Security. If you require more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.CARD). This optional qualifier can be up to eight characters, and must immediately follow the characters RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters that can be used. 42 IMS Support Guide

RESOURCE Record-Resource Validation Processing The RESOURCE record is required. Each type of IMS resource must be defined on a different RESOURCE record. The /ACF SHOW STATE subcommand displays the RESOURCE record options in effect. The RESOURCE record id and fields are shown in the following table: Record ID RESOURCEqual Fields NAME($PRITRAN $SECTRAN $AGN $CO MMAND $TRANCMD $PSB $TRANCM1 $RASTRAN $RASPSB $RAST ERM $LOCKTRN $LOCKPGM $LOCKTRM $LOCKDB$TPIPE) TYPE(type) VALIDATE NOVALIDATE Chapter 3: IMS Records 43

RESOURCE Record-Resource Validation Processing Field Descriptions The fields of the RESOURCE record are described in the following: NAME($PRITRAN $SECTRAN $AGN $COMMAND $TRANCMD $PSB $TRANCM1 $RASTRAN $RASPSB $RASTERM $LOCKTRN $LOCKPGM $LOCKTRM $LOCKDB $TPIPE)) Specifies the resource that is validated. Valid values are: $PRITRAN-Primary transactions $SECTRAN-Secondary transactions $AGN-Application group names $COMMAND-IMS commands from terminals $TRANCMD-IMS commands from ICMD calls $PSB-Program specification blocks that are used by BMPs $TRANCM1-IMS commands from CMD calls $RASTRAN-RAS security for transactions $RASPSB-RAS security for PSBs $RASTERM-RAS security for LTERMs $LOCKTRN-Security for transactions on the LOCK and UNLOCK commands $LOCKPGM-Security for programs on the LOCK and UNLOCK commands $LOCKTRM-Security for LTERMs on the LOCK and UNLOCK commands $LOCKDB-Security for databases on the LOCK and UNLOCK commands $TPIPE-Security for OTMA TPIPEs on the RESUME TPIPE request 44 IMS Support Guide

+ SIGNON Record-Sign-on TYPE(type) Specifies the resource rule type code used for validation. If no RESOURCE records are created, the default values are as follows: ITR-$PRITRAN ITR-$SECTRAN IAG-$AGN ICM-$COMMAND ICM-$TRANCMD IPS-$PSB ICM-$TRANCM1 ITR-$RASTRAN IPS-$RASPSB IRT-$RASTERM ILT-$LOCKTRN ILP-$LOCKPGM ILL-$LOCKTRM ILD-$LOCKDB ITP-$TPIPE VALIDATE NOVALIDATE VALIDATE causes resource validation. NOVALIDATE disables validation processing. Note: If you are not using AGNs, you must create an AGN RESOURCE record and specify NOVALIDATE. Failure to do this will cause errors in the IMS initialization process. AGN security and RAS resource security are mutually exclusive. If you request AGN security and any RAS resource security, errors will occur in the IMS initialization process. SIGNON Record-Sign-on The SIGNON record specifies options that impact access (sign-on) to the IMS online system. For more information, see the chapter System Control Options. The SIGNON record is required. Only one SIGNON record is permitted. The /ACF SHOW STATE subcommand displays the SIGNON record options currently in effect. Chapter 3: IMS Records 45

SIGNON Record-Sign-on The SIGNON record id and fields are shown in the following table: Record ID SIGNON Fields AUTH(IMS fldname) ENQNAME(SYSIKJUA name) FORMAT(formatname) NOTIFY NONOTIFY NPVERIFY NONPVERIFY PSFORMAT(formatname) Field Descriptions The fields of the SIGNON record are described in the following: AUTH(IMS fldname) Specifies the symbolic name for a field defined in the logonid record that determines whether a user is authorized for IMS access. For access to occur, the PRIVILEGES field on a user's logonid record must include the value of the AUTH option. ENQNAME(SYSIKJUA name) Specifies the major enqueue name used to prevent multiple sign-ons and limit logonid sharing and simultaneous access. FORMAT(formatname) Specifies the module name of the MFS sign-on screen format that is automatically delivered to terminals when they connect to IMS. NOTIFY NONOTIFY Specifies whether the CA ACF2 informational message is delivered after sign-on. NPVERIFY NONPVERIFY Specifies whether verification is required when a new password is entered during sign-on. PSFORMAT(formatname) Specifies the module name of the MFS format that is delivered to the terminal after successful sign-on. 46 IMS Support Guide

Storage Record-Storage Options Storage Record-Storage Options The STORAGE record specifies the IMS TM Interface options that affect the IMS interface storage usage. For more information see the chapter Storage. The STORAGE record is required. All values are defined on one STORAGE record. The /ACF SHOW STORAGE subcommand requests a display of the current IMS interface storage utilization statistics. The STORAGE record id and fields are shown in the following table: Record ID STORAGE Fields CACHENT#(10 nn) CACHPOOL(20,5 nn,mm) IPBXPOOL(20,5 nn,mm) DFTCIDLE(0 nn) DFTCPOOL(0.0 nn,mm) [DFTSCAN(0 nn,mm) [SAVEPOOL(20,5 nnnnn mmmmm)] - [WKA1POOL(20,5 nnnnn mmmmm)] - [WKA2POOL(20,5 nnnnn mmmmm)] - [WKB1POOL(20,5 nnnnn mmmmm)] - [WKB2POOL(20,5 nnnnn mmmmm)] REP The fields of the STORAGE record are described in the STORAGE Record topic. Field Descriptions The fields of the STORAGE record are described in the following: CACHENT#(10 nn) Specifies the number of 44-byte resource cache entries in the user cache area. CACHPOOL(20,5 nn,mm) Specifies the primary and secondary allocation of cache areas that are used for terminals that are signed on. IPBXPOOL(20,5 nn,mm) Specifies the primary and secondary allocation for IPB extensions. Chapter 3: IMS Records 47

SYSPLEX Record-IMS interface SYSPLEX feature DFTCIDLE(0 nn) Specifies the number of minutes that a non-signed on terminal can be idle before the IMS interface determines that the terminal is inactive and releases the associated cache. DFTCPOOL(0,0 nn,mm) Specifies the primary and secondary allocation of cache areas that are used for terminals that are not signed on. DFTSCAN(0 mm) Specifies the number of minutes that must elapse before the IMS interface scans terminals that are not signed on to determine whether their idle time has expired. SAVEPOOL(20,5 nn,mm) Specifies the primary and secondary allocation for save areas. WKA1POOL(20,5 nn,mm) Specifies the primary and secondary allocation for the 256-byte above-the-line work area for the IMS interface programs. WKA2POOL(20,5 nn,mm) Specifies the primary and secondary allocation for the 1024-byte above-the-line work area for the IMS interface programs. WKB1POOL(20,5 nn,mm) Specifies the primary and secondary allocations for 256-byte below-the-line work area for the IMS interface programs. WKB2POOL(20,5 nn,mm) Specifies the primary and secondary allocations for 1024-byte below-the-line work area for the IMS interface programs. SYSPLEX Record-IMS interface SYSPLEX feature The SYSPLEX record control the IMS interface SYSPLEX feature, which uses a coupling facility structure for security performance in an IMS shared queues environment. For more information, see the chapter "IMS Shared Queues and Security." The SYSPLEX record is optional. If it is not specified, the IMS interface SYSPLEX feature is not active. The /ACF SHOW SYSPLEX subcommand displays the current status of the SYSPLEX feature, information about the SYSPLEX structure, and statistics about the usage of the SYSPLEX structure from this IMS region. 48 IMS Support Guide

WTO Record-Write to Operator Messages The SYSPLEX record id and fields are shown in the following table: Record ID SYSPLEX Fields ACTIVE NOACTIVE PRIMNAME(structurename) The fields of the SYSPLEX record are described in the SYSPLEX Record topic. Field Descriptions The fields of the SYSPLEX record are described in the following: ACTIVE NOACTIVE Specifies whether IMS interface SYSPLEX feature is active or not. PRIMNAME(structurename) Specifies the name of the structure in the coupling facility to be used by the IMS SYSPLEX feature. If the ACTIVE option is specified, this field is required; otherwise, it is ignored. WTO Record-Write to Operator Messages The WTO record specifies whether informational and security violation messages are issued to z/os consoles, and the IBM Multiple Console Support (MCS) descriptor and route codes. See the chapter System Control Options for more information. The WTO record is required. All WTO options are specified on one WTO record. The /ACF SHOW STATE subcommand displays the WTO record options currently in effect. The WTO record id and fields are shown in the following table: Record ID WTO Fields INFOWTO NOINFOWTO WTO NOWTO DESC(0 descriptorcodes) Chapter 3: IMS Records 49

WTO Record-Write to Operator Messages Field Descriptions The fields of the WTO record are described in the following: INFOWTO NOINFOWTO Specifies whether some of the IMS interface informational messages are issued to z/os consoles. These messages are noted in the Messages Guide. WTO NOWTO Specifies whether security messages are issued to z/os consoles when a security violation occurs. DESC(0 descriptorcodes) Specifies the IBM MCS descriptor codes. ROUTE(1,9 routecodes) Specifies the IBM MCS routing codes. 50 IMS Support Guide

Chapter 4: Defining Logonids This chapter describes the various types of logonids CA ACF2 and the IMS interface use to perform validation processing. It describes the purpose of each type of logonid and the major decisions that you must make when you create logonid records. You should be familiar with the discussions on CA ACF2 logonids in the Administrator Guide. This chapter assumes that you know how to create CA ACF2 logonid records. In general, logonids identify a user or group of users during validation processing. Logonids are used for system entry, data set access, and resource access validations. You must create a logonid record for every logonid. The attributes, or fields, in a logonid record define the type of access privileges of the region or persons associated with the logonid. This section contains the following topics: Design Concepts and Features (see page 51) Design Concepts and Features This section describes the purpose of the various types of logonids. Information on how to define the corresponding logonid records is described later in this chapter. The following table shows the types of logonids used to support the IMS TM Interface. Types of Logonids Region Logonids (STC Batch Job) User Logonids Automatic Terminal Signon Logonids Control Access Requests For BMP Region Control Region DBRC Region DLISAS Region Fast Path Region IMSRDR Region Message Processing Region User Resources User Resources Chapter 4: Defining Logonids 51

Design Concepts and Features Types of Logonids Default Logonid Control Access Requests For Control Region ISC Links MSC Links APPC OTMA MTO WTOR Region Logonids CA ACF2 uses region logonids to determine whether to permit an IMS region to be started. Region logonids also validate data set access attempts made by an IMS region. If the region is started as a batch job, it should have a batch job logonid assigned to it. If the region is started as a started task, a started task control (STC) logonid must be defined for it. If no logonids are defined for the batch regions, CA ACF2 uses the CA ACF2 batch default logonid specified in the GSO OPTS record. However, the CA ACF2 default logonid should not be used to start up IMS regions because the access authority that is typically defined to a CA ACF2 default logonid record does not sufficiently provide for the regions' access requirements. If the region is running as a batch job, the logonid can be one of two types: production or non-production. In general, the production batch job logonid permits access to IMS data sets required by the region running in a controlled operations environment. Production batch job logonids should not have passwords assigned to them. They are known as restricted logonids. See the Administrator Guide for more information about logonids. A non-production batch job logonid should be assigned to a region that does not run in a scheduled operations environment. Therefore, it might not be permitted to access the data sets used in the normal production environment. Non-production batch job logonids usually have passwords assigned to them. If the region is running as a started task, it should have an assigned STC logonid that cannot have a password. The started task's name is used as the STC logonid. The STC logonid usually provides the same type of access authority as the production batch job logonid provides. 52 IMS Support Guide

Design Concepts and Features BMP Region Logonid Control Region Logonid DBRC Region Logonid DLISAS Region Logonid Fast Path Region Logonid IMSRDR Region Logonid CA ACF2 uses the BMP logonid to determine whether to permit the BMP to be initiated and to validate data set access requests made by the BMP. The IMS interface uses the BMP logonid to validate access to the PSB and AGN (if there) specified for the BMP and to validate transactions the BMP places on the message queue. CA ACF2 uses the control region logonid to determine whether to permit the IMS control region to be initiated. CA ACF2 also uses this logonid to validate data set access requests made by the IMS control region. The control region logonid is also called a MUSASS logonid, because the IMS control region is considered a multiple user single address space system (MUSASS). Important! Never use the control region logonid as the control region default logonid. Ensure that the logonid named for the DFTLID option of the IMS OPTS record is not the control region logonid. CA ACF2 uses the DBRC logonid to determine whether to permit the IMS database recovery region to be initiated and to validate data set access requests made by the database recovery region. If your site is using the IMS DLISAS region, you need a DLISAS logonid. CA ACF2 uses the DLISAS logonid to determine whether to permit initiation of the DLISAS region. Data set access requests made by DLISAS are validated with the DLISAS logonid. If your site is using an IMS fast path region, you must create a fast path region logonid. CA ACF2 uses the fast path region logonid to determine whether to permit initiation of the fast path region and to validate data set access attempts made by the fast path region. CA ACF2 uses the IMSRDR region logonid to determine whether to permit initiation of the IMS reader and to validate data set access attempts made by the IMS reader. Chapter 4: Defining Logonids 53

Design Concepts and Features Message Processing Region Logonid CA ACF2 uses the message processing region logonid to determine whether to permit initiation of the IMS message-processing region and to validate data set access attempts made by the message-processing region. The IMS interface uses the message processing region logonid to validate access to the AGN specified for the message-processing region. User Logonids The IMS interface uses these logonids to validate resource access requests initiated from IMS terminals. User logonids should be defined for all IMS online users. Your site can have users who run batch jobs and online transactions. These users normally use the same logonid for both. In this case, attributes for both the batch and online environments are defined in the same logonid record. Automatic Terminal Signon Logonids IMS provides the ability to automatically sign on a terminal when the terminal connects to the IMS region. This is done by specifying the OPTION=AUTOSIGN parameter on the TYPE or TERMINAL macro statement that defines the terminal in the IMS system definition (IMS stage 1). For more information about the AUTOSIGN parameter, see the IMS System Definition Guide. When OPTION=AUTOSIGN is specified for normal (non-isc) terminals, the LTERM name is used as the userid and is signed on. For ISC static terminals, the SUBPOOL name is used as the userid instead of the LTERM name. Default Logonids Control Region Default Logonid A default logonid is the logonid CA ACF2 or the IMS interface uses to process validations when a region or user logonid cannot be associated with an access request. A default logonid is never suspended by CA ACF2 or the IMS interface. The IMS interface uses a control region default logonid to validate IMS resource access requests when no other type of logonid can be associated with the request. This default logonid is named in the IMS OPTS record. For a description of the DFTLID option, see the chapter System Control Options." 54 IMS Support Guide

Design Concepts and Features ISC Link Default Logonid MSC Link Default Logonid APPC Default Logonid OTMA Default Logonid The IMS interface uses the ISC link default logonid to validate resource access attempts made from an ISC link that is not signed on. If you do not create an ISC link default logonid, the IMS interface uses the control region default logonid of the receiving IMS control region to validate access requests made from an ISC link that is not signed on. To implement an ISC link default logonid, you must create an ISC link default logonid record and specify the logonid in an IMS NETWORK record. For information about implementing ISC link security, see the chapter Network Security. If a user logonid cannot be inherited from an MSC link, the IMS interface uses an MSC link default logonid to validate the resource access requests made from the MSC link. MSC link default logonids verify the access authority of a user site rather than an individual user. When neither a user logonid nor an MSC link default logonid is available, the IMS interface uses the control region default logonid to validate access requests made from the MSC link. To implement an MSC link default logonid, you must create an MSC link default logonid record and specify the logonid in an IMS NETWORK record. For information about implementing MSC link security, see the Network Security. If a user logonid cannot be inherited for APPC connections, the IMS interface uses the APPC default logonid to validate the resource access requests made from any APPC connection. When neither the user logonid nor the APPC default logonid is available, the IMS interface uses the control region default logonid to validate access requests made from any APPC connection. To implement the APPC default logonid, you must create the APPC default logonid record and specify the logonid in the IMS NETWORK record for APPC. For information about implementing APPC security, see the chapter APPC Security. If a user logonid cannot be inherited for OTMA connections, the IMS interface uses the OTMA default logonid to validate the resource access requests made from any OTMA connection. Chapter 4: Defining Logonids 55

Design Concepts and Features MTO Default Logonid WTOR Default Logonid When neither the user logonid nor the OTMA default logonid is available, the IMS interface uses the control region default logonid to validate access requests made from any OTMA connection. To implement the OTMA default logonid, you must create the OTMA default logonid record and specify the logonid in the IMS NETWORK record for OTMA. For more information about implememting OTMA security, see the OTMA Security. If no one is signed on to the IMS master terminal, the IMS interface uses the MTO default logonid to validate the resource access requests made from the master terminal. When no one is signed on to the IMS master terminal and the MTO default logonid is not defined, the IMS interface uses the control region default logonid to validate access requests made from the master terminal. To implement the MTO default logonid, you must create the MTO default logonid record and specify the logonid in the MTOUSID parameter on the IMS OPTS record. If no one is signed on to the IMS console ready prompt, the IMS interface uses the WTOR default logonid to validate the resource access requests made from the ready prompt. When no one is signed on to the IMS console ready prompt and the WTOR default logonid is not defined, the IMS interface uses the control region default logonid to validate access requests made from the ready prompt. To implement the WTOR default logonid, you must create the WTOR default logonid record and specify the logonid in the WTORUSID parameter on the IMS OPTS record. Note: Signing on to the IMS console ready prompt should not be confused with signing on to the z/os console. Signing on to the console ready prompt is done by issuing a /SIGN command in response to the ready prompt. Logonid Records This section discusses the major decisions you must make when you create the various types of the IMS interface logonid records. It also provides an example of an INSERT subcommand statement for each type of logonid record. 56 IMS Support Guide

Design Concepts and Features Region Logonid Records Typically, the IMS interface logonid records are created from TSO with the standard CA ACF2 procedures: 1. From TSO Ready mode, enter the ACF command. 2. Enter the LID setting. 3. Enter the INSERT subcommand with the logonid record key and each logonid attribute you want to define. To review the ACF subcommands available with the LID setting, see your Administrator Guide. To determine the logonid record attributes you want to define for a region logonid, you must make the following decisions: Which IMS data sets the region needs to access. Whether the IMS region is initiated as a batch job or as a started task. Whether the IMS region is a MUSASS. (The only IMS MUSASS region is the IMS control region.) How powerful you want the region logonid to be, that is, whether to assign minimal or maximal access authority to the logonid and whether you want to write data set access rules for the region. Whether to ensure that a region is initiated only with a particular program, set of programs, or source. With the exception of the BMP region, the IMS regions can be started up as a batch job or a started task. Because the BMP region emulates the IMS batch environment, it must be initiated as a batch job. Due to restrictions in IMS architecture, the IMS facilities (DBRC, DLISAS, IMSRDR) are usually initiated as started tasks. The factors you must consider to determine the type of access authority to specify on a region logonid record are the same for each type of region logonid. By default, CA ACF2 requires rule validation for every data set access attempt made on behalf of any logonid. However, because it can be difficult to determine off the top of your head the data sets a region needs to access, and because the region can require access to many data sets, you can define the most powerful logonid attribute, NON-CNCL, for the region logonid record temporarily. The NON-CNCL attribute grants the region access to all data sets. It also provides a log of the data set accesses the region makes that would have been violations and, therefore, helps you determine the data sets the region requires. Chapter 4: Defining Logonids 57

Design Concepts and Features Batch Job Logonid Records You can lessen the access authority without having to write data set access rules by replacing the NON-CNCL attribute with the MAINT attribute. The MAINT attribute grants data set access without requiring rule validation, but it requires that the accesses be made only through a specific program that is executed only from a specific library. No data set accesses are logged in a MAINT environment. If you specify JOBCK in the CA ACF2 GSO, you must specify the JOB attribute on the batch job logonid record to start up the region as a batch job. Because the IMS control region is a MUSASS, you must also define the MUSASS attribute on the control region's logonid record. The MUSASS attribute permits multiple users to sign on concurrently to the control region, and it permits the IMS TM Interface, which resides in the control region, to perform resource access validations on behalf of multiple users. The MUSUPDT field authorizes the region logonid to issue database update calls on behalf of users updating the CA ACF2 databases. You must set this privilege to enable the use of the ACF command to update the CA ACF2 databases from within the IMS region. If you have a test environment that shares a database with the production environment, we strongly recommend that MUSUPDT privilege not be granted to the test region to prevent users from updating the CA ACF2 databases from the test environment. If you use the ACF transaction to perform logonid maintenance from IMS, you must define the MUSASS and MUSUPDT attributes on the logonid record for the logonid used to start up the message-processing region where the ACF transaction executes. These attributes permit the ACF transaction to check the authority of the person making the request and to update the CA ACF2 Logonid database. Because these attributes represent a significant level of privilege for the message processing region logonid, you should consider using the SUBAUTH and PROGRAM attributes to protect the logonid from unauthorized use. (For a description of the security implications of the ACF transaction, see the chapter Additional Considerations. ) If you determine that a region needs a batch job logonid record, you must decide whether to create a production or a non-production batch job logonid record. A production batch job logonid record can require different access authority than a non-production batch job logonid record. 58 IMS Support Guide

Design Concepts and Features Production Batch Job Logonids For regions initiated as production batch jobs, appropriate logonid attributes include RESTRICT, PROGRAM, SUBAUTH, and possibly SOURCE. JOBCK controls whether logonids submitting batch jobs are validated by checking the JOB attribute in the logonid record. These attributes control how the logonid can enter the system. Typically, production logonids are not assigned passwords. The RESTRICT attribute enables CA ACF2 to validate initiation of the region without the aid of a password. The PROGRAM and SUBAUTH attributes are used with RESTRICT to ensure that the region logonid is used only when the region is initialized through specific APF-authorized programs. You can also use RESTRICT with the SOURCE attribute to ensure that the region logonid is used only when the region is initialized from a specific logical or physical input device. Another important consideration to keep in mind when you create the control region logonid record is the use of the NO-SMC attribute. The NO-SMC attribute facilitates multitask processing. It enables IMS to continue processing tasks while CA ACF2 or the IMS interface performs validations. The following INSERT subcommand statement is an example of how a production batch job logonid record for a region might be defined (with the exception of the control region): INSERT logonid NAME(region) JOB RESTRICT SUBAUTH PROGRAM(pgmname) In the previous example, the logonid is the value specified on the USER= parameter on the JOB statement or from the //*LOGONID statement. The NAME is your way of further identifying the region. This name can consist of a maximum of 20 characters. The PROGRAM value is the APF program used to start up the IMS region. The following subcommand statement is an example of how the production batch job logonid record for the control region might be defined: INSERT logonid NAME(region) MUSASS MUSUPDT MUSID(id) - JOB RESTRICT SUBAUTH PROGRAM(pgmname) NO-SMC MAINT In the previous example, the logonid for the control region is used as the logonid record key. The NAME is your way of further identifying the control region. This name can consist of a maximum of 20 characters. The MUSID must match the value specified for the DIVISION field of the control region's IMS records. This value can consist of a maximum of eight characters. The PROGRAM value is the APF program used to start up the IMS regions. Chapter 4: Defining Logonids 59

Design Concepts and Features Nonproduction Batch Job Logonids STC Logonid Records A non-production batch job logonid record is usually used by a region running in a test environment. This logonid record can contain a password and does not require the RESTRICT attribute. For those non-production regions requiring access to only a few data sets used for testing purposes, special access authority attributes are not necessary; that is, you can require normal rule validation for non-production batch job logonids. If you specify JOBCK in the CA ACF2 GSO OPTS record, you must specify the JOB attribute on the batch job logonid record to start up the region as a batch job. You might also consider using the SUBAUTH, PROGRAM, and MAINT attributes, depending on your site's non-production environment. The following subcommand statement is an example of how a non-production batch job logonid record might be defined for a region (with the exception of the control region): INSERT logonid NAME(region) JOB In the previous example, the logonid for the region is the logonid record key. The NAME is your way of further identifying the region. This name can consist of a maximum of 20 characters. The following subcommand statement is an example of how a non-production batch job logonid record for the control region might be defined: INSERT logonid NAME(region) MUSASS MUSUPDT MUSID(id) JOB NO-SMC MAINT In the previous example, the logonid for the control region is the logonid record key. The NAME is your way of further identifying the region. This name can consist of a maximum of 20 characters. The MUSID must match the value specified for the DIVISION field of the control region's IMS records. This value can consist of a maximum of eight characters. With the exception of the BMP region, IMS regions can be initiated as batch jobs or as started tasks; however, the IMS facilities (DBRC, DLISAS, and IMSRDR) are usually initiated as started tasks. When you create STC logonid records, remember that the STC JCL PROC name used to start up the region is also used as the STC logonid. To obtain the STC JCL PROC names used for the regions, you might have to consult with your systems programmer. Also, you must specify the STC field of the CA ACF2 GSO OPTS record to activate CA ACF2 validation of STC logonids. 60 IMS Support Guide

Design Concepts and Features With the exception of the control region, STC logonid records only require the STC attribute and a privilege attribute such as MAINT. The STC attribute provides some of the same functions the batch job logonid record attributes RESTRICT, SUBAUTH, PROGRAM, and SOURCE provide. The STC attribute requires that the started task be submitted only from the z/os master console and that only APF programs be allowed to initiate the region. Because the control region is a MUSASS, it requires the MUSASS attribute and the STC attribute when the control region is initiated as a started task. The MUSUPDT attribute is also required to enable the IMS interface to update CA ACF2 databases. You can define the NO-SMC attribute to facilitate multitasking. Message processing regions are usually submitted as batch jobs using the IMSRDR facility. However, if the message-processing region where the ACF transaction executes is a started task, you must define the MUSASS and MUSUPDT attributes in the message processing region logonid record. (For a description of the security implications of the ACF transaction., see the chapter Transaction Security. ) The IMSRDR region requires the JOBFROM attribute because it submits jobs with logonids that are different from its own. The following INSERT subcommand statement is an example of a typical STC logonid record definition that might be used to start up an IMS region (with the exception of the control region): INSERT logonid NAME(region) STC In the previous example, the logonid for the region is the STC JCL PROC name used for initiation. The NAME is your way of further identifying the region. This name can consist of a maximum of 20 characters. The following subcommand statement is an example of how a control region's STC logonid might be defined: INSERT logonid NAME(region) STC MUSASS MUSUPDT MUSID(id) NO-SMC MAINT In the previous example, the logonid must be the STC JCL PROC name used for initiation of the control region. The NAME is your way of further identifying the control region. This name can consist of a maximum of 20 characters. The MUSID must match the value specified for the DIVISION field of the control region's IMS records. Chapter 4: Defining Logonids 61

Design Concepts and Features User Logonid Records To determine the logonid record attributes you want to define for a user logonid, you must make many of the same types of decisions you made for defining region logonid records: The IMS control region the user needs to access How powerful you want the user logonid to be, that is, whether to assign minimal or maximal access authority to the logonid. The type of access authority to define in a user logonid record depends on the user's job function. If the user is a security administrator, his or her logonid record needs more access authority than other user logonid records. For most users, you probably want to require normal data set and resource rule validation; that is, you do not have to assign any special access authority such as MAINT, NON-CNCL, or SECURITY. All online user logonid records require access authority to a control region to let users sign on to IMS terminals. The AUTH option on the control region's IMS SIGNON record specifies the logonid record attribute required to access the control region. To provide users the authority to access the control region, the PRIVILEGES field in the user logonid records must include the value specified for the AUTH option. If you want to assign a unique IDLE time to an online user, you must specify the idle attribute. For more information about idle time considerations, see the chapters System Control Options, and Additional Considerations. The following INSERT subcommand statement is an example of how a typical online user logonid record might be defined: INSERT logonid NAME(user) IMS IDLE(15) In the previous example, the NAME is the user's name. The name can consist of a maximum of 20 characters. The privilege value IMS matches the default AUTH option in the IMS SIGNON record. 62 IMS Support Guide

Design Concepts and Features Automatic Terminal Signon Logonid Records IMS provides the ability to automatically sign on a terminal when the terminal connects to the IMS region. This is done by specifying the OPTION=AUTOSIGN parameter on the TYPE or TERMINAL macro statement that defines the terminal in the IMS system definition (IMS stage 1). For more information about the AUTOSIGN parameter, see the IMS System Definition Guide. When OPTION=AUTOSIGN is specified for normal (non-isc) terminals, the LTERM name is used as the userid and is signed on. For ISC static terminals, the SUBPOOL name is used as the userid instead of the LTERM name. Automatic terminal signon should only be used for IMS terminals whose usage and physical location make it unnecessary to require individual user identification and accountability, for example an terminal on a shop floor that is accessible to and shared by several users. The type of access authority to define in an automatic terminal signon logonid record depends on the requirements of the people who share the terminal and a common job function. In many respects, the definition of an automatic terminal signon logonid record is similar to that of a default logonid record. Because the LTERM or SUBPOOL logonid record is automatically signed on without a password, you must specify the RESTRICT attribute. To ensure that only an IMS control region can use the automatic terminal signon logonid, you should specify the SUBAUTH and PROGRAM fields for the logonid. If you specify PROGRAM, the value must be set to ACF2IMS. Because the logonid does not have a password, no IDLE value should be specified for the logonid. The automatic terminal signon logonid does not require the JOB attribute because the logonid is used to validate online resource access, not batch jobs. The automatic terminal signon logonid records require access authority to a control region to let the logonid sign on to the IMS terminal. The AUTH option on the control region's IMS SIGNON record specifies the logonid record attribute required to access the control region. To provide the automatic terminal signon logonid the authority to access the control region, the PRIVILEGES field in the logonid record must include the value specified for the AUTH option. The following INSERT subcommand statement is an example of how an automatic terminal signon logonid record might be defined: INSERT lterm subpool NAME(ATS user) IMS RESTRICT SUBAUTH PROGRAM(ACF2IMS) Chapter 4: Defining Logonids 63

Design Concepts and Features Default Logonid Records In the previous example, lterm subpool is the LTERM or ISC SUBPOOL name that will be used to automatically sign on to the terminal. The data field of the NAME keyword can be used to specify a descriptive title for this logonid. There can be a maximum of 20 characters. The SUBAUTH and PROGRAM fields limit the use of the logonid to an IMS control region. The privilege value IMS matches the default AUTH option in the IMS SIGNON record CA ACF2 and the IMS TM Interface use default logonids to perform access validations only when no other type of logonid is available. You should define minimal access authority to default logonid records because individual accountability among specific users is not possible with default logonids. A default logonid can identify only a group of users or a particular network connection. Because a group of people uses the same default logonid, each person in the group has the same access privileges. To ensure that the default logonids have minimal access authority, check the UIDs defined for the data set and resource access rules to make certain that the UID associated with the default logonid is defined only to those data sets and resources that are not crucial to your site. To assist you in determining which data sets and resources to permit access to, CA ACF2 provides a cross-reference report. For more information about the CA ACF2 reports, see the chapter Reports. Control Region Default Logonid Record The control region default logonid record is not the same as the control region logonid record. The control region default logonid record should have minimal access authority, whereas the control region logonid record can have unlimited access authority. The default logonid record should have minimal access authority because the IMS interface uses it to validate resource access by unknown users, that is, users who have submitted requests without signing on, thereby rendering them as unknown to the IMS interface. Defining minimal access authority to the default record ensures that the unknown users cannot access crucial IMS resources. Specify the control region default logonid in the DFTLID field of the IMS OPTS record. The CA ACF2 default for this value is IMSDFLT. A logonid record must be defined for this logonid. Because the control region default logonid record cannot have a password, you must specify the RESTRICT attribute. To ensure that only an IMS control region can use the control region default logonid, you should specify the SUBAUTH and PROGRAM fields for the logonid. If you specify PROGRAM, the value must be set to ACF2IMS. The control region default logonid does not require the JOB attribute because the control region default logonid is used to validate online resource access, not batch jobs. 64 IMS Support Guide

Design Concepts and Features The following INSERT subcommand statement is an example of how a typical control region default logonid record might be defined: INSERT IMSDFLT NAME(region) RESTRICT SUBAUTH PROGRAM(ACF2IMS) In the previous example, the NAME is your way of further identifying the control region. The name can consist of a maximum of 20 characters. The SUBAUTH and PROGRAM fields limit the use of the logonid to an IMS control region. Network Link Default Logonid Records If a user logonid cannot be inherited when an access attempt is made from a network link, the IMS interface uses a link default logonid to validate the request. IMS NETWORK records define the default logonids for specific links. Because a link default logonid record cannot have a password, you must specify the RESTRICT attribute. To ensure that only an IMS control region can use a link default logonid, you should specify the SUBAUTH and PROGRAM fields for the logonid. If you specify PROGRAM, the values must be set to ACF2IMS. The link default logonids do not require the JOB attribute because the default logonid is used to validate online resource access, not batch jobs. The following subcommand is an example of how you might define a link default logonid record: INSERT logonid NAME(link) RESTRICT SUBAUTH PROGRAM(ACF2IMS) In the previous example, logonid is the default assigned to an IMS network link. The data field of the NAME keyword can be used to specify a descriptive title for this network link. There can be a maximum of 20 characters. The SUBAUTH and PROGRAM fields limit the use of the logonid to an IMS control region. For more information about implementing network link security, see the chapters Network Security, APPC Security chapter, and OTMA Security. Chapter 4: Defining Logonids 65

Design Concepts and Features MTO Default Logonid Record If no one is signed on to the IMS master terminal when a command or transaction is entered at the terminal, the IMS interface uses the MTO default logonid to validate the request. The MTO default logonid is defined in the MTOUSID parameter on the IMS OPTS record. Because the MTO default logonid record cannot have a password, you must specify the RESTRICT attribute. To ensure that only an IMS control region can use the MTO default logonid, you should specify the SUBAUTH and PROGRAM fields for the logonid. If you specify PROGRAM, the value must be set to ACF2IMS. The MTO default logonid does not require the JOB attribute because the default logonid is used to validate online resource access, not batch jobs. The following subcommand is an example of how you might define the MTO default logonid record: INSERT logonid NAME(MTO default) RESTRICT SUBAUTH PROGRAM(ACF2IMS) In the previous example, logonid is the MTO default logonid. The data field of the NAME keyword can be used to specify a descriptive title for this logonid. There can be a maximum of 20 characters. The SUBAUTH and PROGRAM fields limit the use of the logonid to an IMS control region. The MTO default logonid is optional. When no one is signed on to the IMS master terminal and the MTO default logonid is not defined, the IMS interface uses the control region default logonid to validate access requests made from the master terminal. 66 IMS Support Guide

Design Concepts and Features WTOR Default Logonid Record If no one is signed on to the IMS console ready prompt when a command or transaction is entered in response to the ready prompt, the IMS interface uses the WTOR default logonid to validate the request. The WTOR default logonid is defined in the WTORUSID parameter on the IMS OPTS record. Because the WTOR default logonid record cannot have a password, you must specify the RESTRICT attribute. To ensure that only an IMS control region can use the WTOR default logonid, you should specify the SUBAUTH and PROGRAM fields for the logonid. If you specify PROGRAM, the value must be set to ACF2IMS. The WTOR default logonid does not require the JOB attribute because the default logonid is used to validate online resource access, not batch jobs. The following subcommand is an example of how you might define the WTOR default logonid record: INSERT logonid NAME(WTOR default) RESTRICT SUBAUTH PROGRAM(ACF2IMS) In the previous example, logonid is the WTOR default logonid. The data field of the NAME keyword can be used to specify a descriptive title for this logonid. There can be a maximum of 20 characters. The SUBAUTH and PROGRAM fields limit the use of the logonid to an IMS control region. The WTOR default logonid is optional. When no one is signed on to the IMS console ready prompt and the WTOR default logonid is not defined, the IMS interface uses the control region default logonid to validate access requests made from the ready prompt. Note: Signing on to the IMS console ready prompt should not be confused with signing on to the z/os console. Signing on to the console ready prompt is done by issuing a /SIGN command in response to the ready prompt. Chapter 4: Defining Logonids 67

Chapter 5: System Control Options This chapter describes the functions performed by control options on the IMS OPTS, WTO, and SIGNON records. The last section of this chapter provides procedures for defining the control options. You can review Creating and Modifying IMS Records in the IMS Records chapter before reading these sections. This section contains the following topics: Design Concepts and Features (see page 69) Interface Control Options (see page 72) Design Concepts and Features As defined earlier in this guide, control options establish the overall IMS interface environment. The values selected for these options determine the IMS interface system processing for the entire IMS online environment. This section describes the major concepts, features, and functions that constitute the system control options. Control Region Access Authority The IMS interface uses logonid records to determine whether a user should be granted access to the IMS control region. Users are granted access to a particular control region when the PRIVILEGES field value in their logonid records matches the AUTH option value defined in that region's IMS SIGNON record. Control Region Default Logonid The IMS interface uses the IMS control region default logonid for resource access validations when a user logonid is not provided. Validations that use this default logonid are performed with the UID associated with the control region default logonid record. Idle Time Reverification The IMS interface provides a facility that forces revalidation of a user's password whenever a user exceeds the specified amount of idle time. Chapter 5: System Control Options 69

Design Concepts and Features Logonid Suspension The IMS interface provides the option to automatically suspend a user's logonid after he makes a selected number of unauthorized access attempts. You can specify the number of access attempts permitted with the MAXVIO option on the IMS OPTS record. A default logonid can never be suspended. Multiple Sign-on Control The ENQNAME subsystem option represents an IMS interface feature that controls the simultaneous use of a single logonid to sign on to multiple systems. You can use this feature to prevent the multiple sign-ons altogether, or you can use it to limit the sign-ons. New Password Verification The IMS interface lets you automatically force a user to enter his new password twice when he changes his password. Security Mode The IMS interface has its own security mode to determine the degree of resource protection the interface provides. The default mode, ABORT, is the preferred mode because it ensures the greatest degree of security. If the interface is in ABORT mode, any unauthorized access to a resource is denied. The other modes of the IMS interface security are useful for migration purposes. While you are implementing or adjusting your IMS record options, you can run the IMS interface in one of the lesser modes of security (LOG or QUIET) to minimize the impact of the IMS interface implementation on your users who are not defined in resource rules. Sign-on Format The IMS interface provides a facility to specify the name of an MFS format sign-on screen that is delivered to an IMS terminal whenever sign-on is required. Sign-on Message Delivery The IMS interface provides a facility that controls whether the CA ACF2 informational messages are delivered after sign-on. 70 IMS Support Guide

Design Concepts and Features Successful Sign-on Format The IMS interface provides a facility that specifies the name of an MFS format to be delivered to the terminal after a successful sign-on. For example, you can specify the name of a menu screen that is delivered to the terminal after sign-on. Terminal Messages Besides the capacity to send messages to the console operator, the IMS interface can send informational messages to the terminal user. You must define these messages in the IMS user message table during the IMS interface installation. These messages contain information regarding resource access requests. For example, if a user attempts to initiate a transaction that he is not authorized to run, he receives a message informing him that he does not have the access authority to run the transaction. Write To Operator Messages Write To Operator (WTO) messages constitute an optional IMS interface feature. If you choose to implement this feature, the z/os console operator receives the IMS interface messages whenever a security violation occurs. The WTO feature also lets you control how and where these messages are displayed. In general, the IMS interface violation messages contain the following information: The logonid of the user who attempted the unauthorized access The terminal where the access attempt was made The resource for which access was attempted Chapter 5: System Control Options 71

Interface Control Options Interface Control Options This section describes the IMS record options used to implement the control functions of the IMS TM Interface. This section is written with the assumption that you are already familiar with the basic procedures for creating and modifying IMS records as described in the chapter IMS Records. The following table illustrates the IMS TM Interface control functions and their corresponding IMS record options. Control Function IMS Record Option Control Region Access Authority SIGNON AUTH Control Region Default Logonid OPTS DFTLID Idle Time OPTS IDLE ISRT transaction validation OPTS ISRTNVAL Logonid Suspension OPTS SUSPEND, MAXVIO Message driven BMP validation OPTS BMPMSG MTO Default Logonid OPTS MTOUSID Multiple Sign-on Control SIGNON ENQNAME New Password Verification SIGNON NPVERIFY Non-message driven BMP userid OPTS BMPUSID Password Reverification Limits OPTS PWMAXVIO Security Mode OPTS MODE Sign-on Format SIGNON FORMAT Sign-on Message Delivery SIGNON NOTIFY Successful Sign-on Format SIGNON PSFORMAT Terminal Messages OPTS MSGBASE Transaction Classification OPTS FMTPTRAN Unknown logonid processing OPTS NLIDDFLT WTO Messages WTO INFOWTO, WTO, DESC, ROUTE WTOR Default Logonid OPTS WTORUSID 72 IMS Support Guide

Interface Control Options Control Region Access Authority (AUTH) To enable users access to an IMS control region, the PRIVILEGE field in the users' logonid records must include the value specified for the AUTH option in the control region's IMS SIGNON record. The IMS interface provides a default value for the AUTH option; however, you can choose to use any value consisting of a maximum of eight characters. If your site has more than one control region that is secured by the IMS interface, you might want to use a unique AUTH value for each control region's IMS SIGNON record. To define a control region access authority field, enter the following command from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) SIGNON AUTH(IMS privilegename) The PRIVILEGE field specified in the SIGNON record must be defined in the logonid records. Control Region Default Logonid (DFTLID) The IMS interface uses a control region default logonid to ensure that all IMS resource accesses are validated, even when a user logonid is not provided. IMS interface validations that use this default logonid are performed with the UID associated with the control region's default logonid record. If you are installing the IMS interface in more than one control region, you can specify a unique control region default logonid on each control region's IMS OPTS record. You also must create a logonid record for the logonid specified in the IMS OPTS record. For information about creating logonid records, see the chapter Defining Logonids. To define a control region default logonid, enter the following command from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS DFTLID(IMSDFLT defaultlid) For more information regarding the control region default logonid, see the chapter Defining Logonids. Chapter 5: System Control Options 73

Interface Control Options Idle Time Reverification (IDLE) The IMS interface idle time reverification facility forces a user to enter his password whenever he exceeds the maximum amount of idle time you specify. The IMS interface records the time that a terminal user enters input. It then clocks the amount of time that the terminal is inactive until more input is entered. If a user exceeds the maximum amount of idle time during an IMS session, the IMS interface forces him to reenter his password for revalidation. The default value provided, IDLE, is the name of a CA ACF2-supplied field in the logonid record that you use to specify the idle time. If you choose to use the default, the time value that is defined for the IDLE field of the currently signed-on user's logonid record is the value used for idle time validations. You can choose to create a numeric field in the logonid record to define the idle time. Using a different logonid record field besides the IDLE field lets you define unique idle times for each control region that the user has access to. For example, if a user has access to two IMS control regions and one is more critical than the other, you can define a low idle time for the critical control region and a higher idle time for the other control region. To create a new logonid record field, you must define the @CFDE macro in the CA ACF2 generation. For information about the @CFDE macro, see your Installation Guide. If you decide to use a logonid record field other than the IDLE field, the field name must be specified for this option, and whatever time value is defined in the currently signed-on user's logonid record is used for idle time validations. To define the idle time reverification function, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS IDLE(IDLE fieldname) For more information about idle time, see the chapters Defining Logonids, and Additional Considerations. ISRT Transaction Validation (ISRTNVAL) The IMS interface provides the ability to perform security validation for transactions that are entered by application programs using an ISRT call to a non-modifiable TP-PCB. These transactions are not secured in native IMS security. The ISRTNVAL control option can be used to suppress the security validation for these transactions. 74 IMS Support Guide

Interface Control Options To control security validation for transactions that are entered by application programs using an ISRT call to a non-modifiable TP-PCB, issue the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS NOISRTNVAL ISRTNVAL Logonid Suspension (SUSPEND) The IMS interface lets you automatically suspend a user's logonid after he exceeds the maximum number of unauthorized access attempts in a single sign-on session. You can specify the maximum number in the MAXVIO option. When a logonid is suspended, the suspension bit in the associated logonid record is automatically set, and CA ACF2 does not permit the user to sign on with the logonid again. To place the logonid in use again, the security administrator must turn off the suspension bit in the logonid record. You can turn off the IMS interface logonid suspension function by specifying NOSUSPEND for the SUSPEND option. A security administrator can suspend a logonid at any time by entering the logonid record and setting the suspension bit manually. For further information regarding the suspension bit of the logonid record, see the Administrator Guide. To define the logonid suspension function, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS SUSPEND NOSUSPEND Maximum Security Violations (MAXVIO) By default, the IMS interface automatically suspends a user's logonid after ten unauthorized access attempts; however, you can specify any number from 1 to 32767. You can use the MAXVIO option even if you decide not to use the logonid suspension function. If you specify NOSUSPEND and the maximum number of security violations specified by the MAXVIO option has been reached, the IMS interface does not suspend a user's logonid, but it does not let the user access any of the protected resources. To define the maximum number of security violations your site permits, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS MAXVIO(10 number) Chapter 5: System Control Options 75

Interface Control Options Message Driven BMP Validation (BMPMSG) An IMS BMP region runs under the authority of the logonid specified for the BMP region. If the BMP region reads a message from the IMS message queues, the logonid associated with the message read is also temporarily associated with the BMP. If the BMP generates transactions or commands after reading a message from the IMS message queue, the transactions or commands can be validated using the logonid of the BMP region or the logonid from the last message read from the message queue. The IMS interface provides the ability to specify which of the logonids should be used when a message driven BMP generates transactions or commands. If BMPUSER is specified for the BMPMSG control option, the logonid of the BMP region is used for validation of any transactions or commands generated by the BMP. If MSGUSER is specified for the BMPMSG control option, the logonid of the last message read by the BMP is used for validation of any transactions or commands generated by the BMP. To specify which logonid should be used for transaction or command validation from a message driven BMP, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS BMPMSG(BMPUSER MSGUSER) Note: This option does not control the logonid propagated with transactions generated by a message driven BMP. For a transaction generated by a message driven BMP, IMS always passes the logonid of the last message read. If the transaction generates other transactions or commands in turn, those transactions and commands are validated using this logonid. 76 IMS Support Guide

Interface Control Options MTO Default Logonid (MTOUSID) If no one is signed on to the IMS master terminal, the IMS interface uses the MTO default logonid to validate the commands and transactions made from the master terminal. When no one is signed on to the IMS master terminal and the MTO default logonid is not defined, the IMS interface uses the control region default logonid to validate access requests made from the master terminal. You also must create a logonid record for the MTO default logonid specified in the IMS OPTS record. For information about the MTO default logonid and creating logonid records, see Defining Logonids. To specify the master terminal default logonid Type the following subcommand from the CONTROL IMS setting of the ACF command CHANGE DIVISION(musid jobname) OPTS MTOUSID(mtolid) Multiple Sign-on Control (ENQNAME) Preventing Multiple Sign-ons The ENQNAME subsystem option represents the IMS interface feature that controls the simultaneous use of a single logonid by multiple users. You can use this feature to help prevent multiple sign-ons altogether, or you can use it to limit the sign-ons. The term ENQNAME refers to an enqueue function that indicates that a logonid is in use when a user attempts to access a system with a logonid that is already signed on. When a user attempts to sign on to a system with a logonid that is already in use, the IMS interface does not let the user sign on. The IMS interface enqueue function uses a string of characters made up of a major name and a minor name. The major name is the value provided for the ENQNAME option on the IMS SIGNON record, and the minor name is the user's logonid. Enqueue names are assigned to particular systems such as TSO, CICS, and IMS. When systems have the same enqueue names, a user can be signed on to only one system at a time because each system is assigned the same enqueue name and logonid combination, and the IMS interface does not permit the logonid to be signed on again while it is already in use. Therefore, the enqueue function not only helps to prevent a single user from signing on to more than one system at a time, but it also helps to prevent other users from using the same logonid to sign on to the same system while a session is ongoing. Chapter 5: System Control Options 77

Interface Control Options To prevent multiple users from using the same logonid to access the same system concurrently and to prevent a single user from signing on to more than one system at a time, make sure that you assign your site's IMS control region with the same enqueue name that is used by all the other control regions and systems available to your site's users. Limiting Logonid Sharing and Simultaneous Access Creating an IMS Enqueue Name Turning Off the Enqueue Function When systems have different enqueue names, a user can be signed on to more than one system at a time. If you define a unique enqueue name to an IMS control region, that is, an enqueue name that is not used by another control region or by another system, your site's users are able to sign on concurrently to the control region and another system. You can let your users sign on to a couple of systems concurrently, such as TSO and IMS, if this is necessary to the users' job functions. To let users access more than one system at a time, assign different enqueue names to these systems, but make sure that the systems that you do not want to permit simultaneous accesses to have the same enqueue names. For example, to let users use the same logonid to sign on to TSO and IMS simultaneously, but to prevent them from signing on concurrently to CICS and IMS, assign an enqueue name to IMS that is different from the TSO enqueue name, but is the same enqueue name used by CICS. You can define any major enqueue name in the ENQNAME option. To limit simultaneous use of a single logonid to only particular systems and control regions, consult with your systems programmer to determine the enqueue names used by other systems. To let a user logonid sign on to the IMS control region concurrently from more than one terminal, you must turn off the IMS interface enqueue function. To turn off the enqueue function, do not specify an ENQNAME value, instead specify NA (not applicable) for the ENQNAME value. To define the enqueue function to the IMS interface, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) SIGNON ENQNAME(SYSIKJUA queuename NA) 78 IMS Support Guide

Interface Control Options New Password Verification (NPVERIFY) The IMS interface provides the NPVERIFY option that lets you automatically force a user to enter his new password twice when he changes his password. When a user changes their password, they must first enter their existing password. Then, before they press ENTER, they must enter their new password twice. If the two new passwords match, the user's password is changed. This duplication ensures that the user did not mistype their new password. If the user fails to complete this procedure, they are not able to change their password. To control new password verification, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) SIGNON NPVERIFY NONPVERIFY Non-Message Driven BMP Userid (BMPUSID) An IMS BMP region runs under the authority of the logonid specified for the BMP region. If the BMP region is a non-message driven BMP (the BMP does not read messages from the IMS message queues) and generates transactions into IMS, IMS can either associate the new transactions with the logonid of the BMP, or with the PSBNAME specified for the BMP. The IMS interface provides the ability to specify which of the values IMS will propagate as the userid for a transaction generated by a non-message driven BMP. If USERID is specified for the BMPUSID control option, the logonid of the BMP region is propagated as the userid for transactions generated by the BMP. If PSBNAME is specified for the BMPUSID control option, the PSBNAME of the BMP is propagated as the userid for transactions generated by the BMP. To specify which value should be propagated as the userid for transactions generated by a non-message driven BMP, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS BMPUSID(USERID PSBNAME) Note: This option does not control the logonid used to validate commands and transactions generated directly by a non-message driven BMP. These commands and transactions are always validated using the logonid for the BMP job. However, when BMPUSID(PSBNAME) is specified and a transaction is generated by a non-message driven BMP, the PSBNAME is passed as the userid for the transaction. If the transaction generates other commands or transactions in turn, the generated commands and transactions are validated using the IMS default logonid. Chapter 5: System Control Options 79

Interface Control Options Password Reverification Limits (PWMAXVIO) Password reverification occurs when a user exceeds the specified terminal idle time or when he attempts access to a resource and the corresponding resource rule has the VERIFY keyword specified. By default, a terminal user is granted five incorrect responses to password verification requests in one sign-on session. However, you can specify any number from 1 to 255. When they reach the number of maximum incorrect passwords, the IMS interface does not permit the user to access any protected resources. To define the maximum number of incorrect passwords allowed in password reverification, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS PWMAXVIO(5 number) Security Mode (MODE) QUIET Mode LOG Mode ABORT Mode The security mode of the IMS TM Interface represents the most essential control function. This option defines the degree of security that the IMS interface provides. Progressive degrees of security can be desirable while implementing the IMS interface; however, the strictest degree of security should be established for the final production environment. Three degrees of security are available. The modes of security are discussed here in the order of the least strict to the strictest degree of security. QUIET mode provides the least security. QUIET mode indicates that no resource access validations are performed. When the IMS TM Interface is in QUIET mode, security is limited to sign-on processing. LOG mode grants access to all resources, but all security violations are recorded in an SMF record. ABORT mode is the strictest type of IMS interface security. All unauthorized accesses are denied. 80 IMS Support Guide

Interface Control Options Defining the Security Mode To define the security mode for the CA ACF2 IMS interface, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS MODE(QUIET LOG ABORT) Sign-on Format (FORMAT) When a VTAM terminal that is required to sign on connects to IMS or signs off from IMS, IMS sends its default sign-on screen format to the terminal. The IMS default sign-on format is not easily customizable and is not sufficient for the CA ACF2 IMS interface sign-on processing. (Requirements for a sign-on format are documented in the chapter Additional Considerations. ) Most IMS sites have their own sign-on screen format, customized for their requirements and sufficient for the IMS interface requirements. The IMS interface provides the FORMAT option to specify the name of an MFS format to be delivered to IMS terminals instead of the IMS default sign-on format. To specify the sign-on format, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) SIGNON FORMAT(MFS-format-name) Sign-on Message Delivery (NOTIFY) The IMS interface provides the NOTIFY option to control the delivery of CA ACF2 sign-on messages to users after they successfully sign on to the system. If this feature is activated, when a user signs on to the system they will receive messages from the IMS interface. For example, these messages can include the time and date of the user's last sign-on or CA ACF2 warning messages about the number of days until the user's password expires. To control sign-on message delivery, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) SIGNON NOTIFY NONOTIFY Chapter 5: System Control Options 81

Interface Control Options Successful Sign-on Format (PSFORMAT) The IMS interface provides the PSFORMAT option to specify the name of an MFS format to be delivered to the terminal after successful sign-on. If this feature is activated, when a user signs on to the system, he will view the format you have specified. To use this option, specify the post-sign-on MFS format name in the IMS SIGNON record. The format name is passed to the IMS interface sign-on exit, if activated, which can override the format name. To define successful sign-on format, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) SIGNON PSFORMAT(MFS-format-name) Terminal Messages (MSGBASE) To enable the IMS interface to send informational messages to the IMS terminal user, you must define the message text along with its assigned message number in the IMS user messages table. The message number, known as the base number, is used to locate the messages in the table. To implement IMS interface terminal messages, you must specify the base number that identifies the messages location for the MSGBASE option in the IMS OPTS record. You can consult with your systems programmer to determine the desired base number for the IMS interface terminal messages, since they must install the messages in the IMS user messages table. To define the base number for IMS interface terminal messages, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS MSGBASE(900 nnn) Transaction Classification (FMTPTRAN) In the IMS interface default transaction classification scheme, transactions that are entered from a clear terminal screen are classified as primary transactions and transactions that are entered from an MFS formatted screen are classified as secondary transactions. These transaction classifications are described in detail in the chapter Transaction Security. Use the FMTPTRAN option to change the default transaction classification scheme. When you specify FMTPTRAN, transactions entered from an MFS formatted screen are classified as primary transactions and are validated the same as all terminal transactions. The NOFMTPTRAN default value of this option leaves the default transaction classification scheme in place. 82 IMS Support Guide

Interface Control Options If primary and secondary transactions are validated with the same resource type code, this option does not affect IMS interface processing. To define the setting of the FMTPTRAN option, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS {FMTPTRAN NOFMTPTRAN} Unknown Logonid Processing (NLIDDFLT) The NLIDDFLT control option controls what the IMS interface will do when it is passed a logonid for resource validation that does not exist on the CA ACF2 logonid database. If NONLIDDFLT is specified and a validation logonid does not exist on the logonid database, the IMS interface issues an error message for the invalid logonid and denies the resource access. If NLIDDFLT is specified and a validation logonid does not exist on the logonid database, the IMS interface does not issue an error message for the invalid logonid. It performs the access validation using the IMS default logonid. To specify which process should occur when the logonid for an access validation does not exist on the logonid database Type the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS {NONLIDDFLT NLIDDFLT} Write To Operator Messages Informational Messages (INFOWTO) This section describes the INFOWTO, WTO, DESC, and ROUTE options of the Write To Operator (WTO) record. The setting of this option controls whether some of the IMS interface informational messages are issued to z/os consoles. Not all IMS interface messages that are informational in nature are controlled by this option. The messages that are controlled by this option are noted clearly in the Messages Guide. The informational messages are issued using the MCS route and descriptor codes (see the description later in this section) of the IMS control region. To define the setting of the INFOWTO option, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) WTO {INFOWTO NOINFOWTO} Chapter 5: System Control Options 83

Interface Control Options Security Violation Messages (WTO) Activating the WTO Facilities WTO Descriptor Functions (DESC) If you choose to use the IMS interface Write To Operator (WTO) facility, security messages are issued to z/os consoles whenever a security violation occurs. These WTO messages are not issued unless the WTO facility is specifically defined in the IMS WTO record. The various WTO subsystem options available can be defined to activate the WTO facility, to establish their importance and format of the messages, and to route the messages to specific consoles. If you activate the WTO facility, WTO messages are issued to the z/os console whenever a security violation occurs. To define the WTO facility, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) WTO {WTO NOWTO} If you let this WTO option default (NOWTO), you deactivate the WTO facility. To activate the WTO facility, you must enter the WTO value for this option. The IMS interface uses IBM Multiple Console Support (MCS) descriptor codes to determine factors such as whether to permit WTO messages to roll off the console screen or to highlight the console messages to indicate their importance. The IMS interface default value for the DESC option is the MCS code 0. The MCS code 0 actually indicates the MCS code 6 or 7, meaning the subsystem issues WTO messages with the MCS criticality code of 6 or 7. Both codes 6 and 7 have the status of informational messages. This status indicates a low degree of criticality, and the WTO messages are therefore permitted to roll off the console screen. If your site uses only one z/os console for security purposes, you can use an MCS descriptor code that indicates a higher degree of importance. For more information regarding MCS descriptor codes, see the IBM publication, MVS Routing and Descriptor Codes. To define the WTO descriptor codes, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) WTO DESC(0 descriptorcode) REP 84 IMS Support Guide

Interface Control Options WTO Routing Functions (ROUTE) WTOR Default Logonid (WTORUSID) The IMS interface uses IBM Multiple Console Support (MCS) routing codes to determine where to send messages. MCS routing codes are assigned to z/os consoles in the system generation, and the IMS interface issues WTO messages to those consoles whose MCS routing code assignments match the ROUTE values defined in the IMS WTO record. To ensure that IMS interface WTO messages are displayed at the desired z/os consoles, you can ask your systems programmer for a list of MCS code-console assignments. The IMS interface default values for the WTO routing option are the MCS routing codes 1 and 9. These default values instruct the IMS interface to issue WTO messages to z/os consoles that have MCS routing codes 1 and 9 assigned to them. For more information regarding MCS routing codes, see the IBM publication, MVS Routing and Descriptor Codes. To define the WTO routing codes, enter the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) WTO ROUTE(1,9 routingcode) REP IMS commands and transactions can be entered from the z/os console in response to the IMS console ready prompt. Users can sign on to the console ready prompt by entering a /SIGN command is response to the prompt. If commands and transactions are entered through the console ready prompt and no one is signed on to the ready prompt, the IMS interface uses the WTOR default logonid to validate the commands and transactions. When no one is signed on to the IMS console ready prompt and the WTOR default logonid is not defined, the IMS interface uses the control region default logonid to validate commands and transactions made from the console ready prompt. You also must create a logonid record for the WTOR default logonid specified in the IMS OPTS record. For information about the WTOR default logonid and creating logonid records, see Defining Logonids. To specify the console ready prompt default logonid Type the following subcommand from the CONTROL IMS setting of the ACF command: CHANGE DIVISION(musid jobname) OPTS WTORUSID(wtorlid) Chapter 5: System Control Options 85

Chapter 6: Transaction Security The IMS interface validates transactions by matching UIDs and access conditions with transaction resource rules. To ensure that it makes the correct match of a UID to a resource rule, the IMS interface provides security inheritance. This means that it ensures that the one-to-one correspondence between the transaction and the user logonid is maintained until processing for the transaction and all the transactions that it invokes is completed. By default, the IMS interface validates all IMS transactions, except transactions entered through APPC and OTMA connections. Those transactions can be validated by the IMS interface, or by CA ACF2 through the SAF interface. See the chapters APPC Security and OTMA Security. This section contains the following topics: Design Concepts and Features (see page 87) Implementing Transaction Validation (see page 89) Design Concepts and Features This section describes the various components that affect the CA ACF2 IMS transaction validation processing. IMS Transactions Primary Transactions An IMS transaction is a unit of work initiated from an IMS terminal, a BMP, another transaction, or from an IMS network connection. The IMS interface validates both primary and secondary IMS transactions. Primary transactions are generally transactions that are entered directly at a terminal by an IMS user. Primary transactions are usually the first transactions initiated in a transactional sequence. IMS terminal transactions that are not entered from an MFS formatted screen are considered primary transactions. These transactions are also known as clear screen transactions. Transactions initiated from other IMS regions or other systems, and received from network connections are also primary transactions. Chapter 6: Transaction Security 87

Design Concepts and Features The IMS interface considers terminal transactions initiated from an MFS formatted screen to be secondary transactions. However, it validates these transactions as primary transactions if you specify the FMTPTRAN option of the IMS OPTS record. This option is described in detail in the chapter System Control Options. The IMS interface validates the following IMS transactions as primary transactions: Transactions initiated from a clear screen Transactions initiated from a screen formatted by MFS, if the FMTPTRAN option is specified Transactions invoked by the /SET command Transactions initiated from across a network connection, such as an ISC or MSC link or an APPC or OTMA connection. Transactions entered from an IMS OM environment, using the OM QUE TRAN command (IMS Version 10 and above). Secondary Transactions Secondary transactions are transactions that are not entered directly by a terminal user. These transactions are usually the second and subsequent transactions in a transactional sequence. Transactions that are initiated by other transactions or by a BMP are secondary transactions. Terminal transactions initiated from an MFS formatted screen are also considered secondary transactions. The IMS interface validates the following IMS transactions as secondary transactions: Transactions initiated from a screen formatted by MFS, unless the FMTPTRAN option is specified. Transactions initiated by a program-to-program message switch. This includes transactions invoked by CHNG calls and conversational deferred program-to-program message switches. This also includes transactions invoked using the ISRT call, unless the ISRTNVAL option is specified. 88 IMS Support Guide

a Implementing Transaction Validation Implementing Transaction Validation This section describes the major tasks required to implement transaction validation. You might have to consult with your database administrator to help you determine your site's specific transaction security requirements. The following tasks are required to implement transaction validations: Step Description Complete 1 Determine whether to validate transactions. 2 Determine whether to validate transactional sequences. 3 Define primary and secondary transaction validations in the IMS RESOURCE records. 4 Write transaction resource rules for the transactions you have decided to protect. Step 1: Validating Transactions Default Transaction Security Transactions are the principle resources of IMS and protecting them on one level or another is one of the IMS security administrator's major concerns. The IMS interface performs both primary and secondary transaction validations by default. However, if for some reason you do not want to secure transactions, you must deactivate the IMS interface validation processing. To deactivate transaction validation, you must create two transaction IMS RESOURCE records, one for primary transactions and one for secondary transactions that specify NOVALIDATE. If you decide to secure your site's transactions, alternative methods are available. You can protect transactions by the IMS interface default validation processing, or you can implement one or more of the IMS interface security methods available for transaction validations. The IMS interface validates primary and secondary transactions with the same resource rule type code (ITR) when it cannot locate an IMS RESOURCE record for transactions. Therefore, it validates all transactions with the same resource rules by default. Chapter 6: Transaction Security 89

Implementing Transaction Validation Alternative Transaction Security Because the IMS interface default processing validates all transactions with the same resource rules, it does not discriminate between primary and secondary transactions. In this case, although all transactions are validated, the sequence in which they are executed is not protected. Therefore, users can execute what is ordinarily a secondary transaction directly from a terminal screen as if it were a primary transaction, and thereby bypass those transactions that are normally responsible for invoking the requested transaction. One IMS interface security alternative is to protect transactional sequences by validating secondary transactions different from primary transactions, providing secondary transactions their own set of resource rules and their own IMS RESOURCE record. This alternative ensures that selected secondary transactions are executed only when they are invoked in a transactional sequence. It prevents users from executing the defined transactions directly from a terminal screen. To activate secondary transaction validations, you must create a transaction IMS RESOURCE record that specifies a unique resource rule type code for secondary transactions. The following sections provide more detail regarding the various IMS interface security methods available for transactions. Step 2: Protecting Transactional Sequences To protect transactional sequences, secondary transactions must be validated apart from primary transactions. The major reason for validating secondary transactions apart from primary transactions is to enable a type of pathing capacity. This capacity ensures that selected transactions are not initiated directly from a terminal with a transaction code. Instead, they are initiated only as a result of another transaction. The defined path enforces that secondary transactions are never executed as primary transactions. For example, suppose your site uses payroll transactions that can be invoked indirectly by a security transaction or directly by a terminal user who enters a payroll transaction code at a terminal screen. Because the payroll transactions are critical and highly confidential, you want to prevent users from having direct access to them. You want to enforce that users are permitted to run the payroll transactions only after their authorization is verified by the initial security transaction. To do this, you must ensure that the payroll transaction validations require payroll transactions to be executed only as secondary transactions. To implement secondary transaction validations, you must create a secondary transaction IMS RESOURCE record. It must specify a resource rule type code other than the type code used for primary transactions, which can be the ITR default type code. You also must write secondary transaction resource rules using the type code defined in the secondary transaction IMS RESOURCE record. 90 IMS Support Guide

Implementing Transaction Validation Terminal Initiated Transactions If you choose not to protect transactional sequences, you can use the same set of resource rules (the same type code) for both primary and secondary transaction validations. When primary and secondary transactions are validated with the same set of resource rules, the IMS interface validates all transactions, but the validations do not discern between primary and secondary transactions. Therefore, the validations do not prevent users from executing secondary transactions as primary transactions. Transactions that are initiated from an IMS terminal and any secondary transaction initiated by the terminal transactions are validated by the IMS interface using the logonid of the person who is signed on to the terminal. If the terminal user was not signed on, these transactions are validated using the control region default logonid. The source used by the IMS interface for the resource validation is in one of two formats. If the originating terminal is a VTAM terminal, the IMS interface uses the VTAM node name as the source. If the terminal is not a VTAM terminal, it constructs the source name using the relative line and terminal numbers for the terminal. The format of the constructed source name is: Innn/mmm Where: I-Is a constant value. nnn-is the relative line number. /-Is a constant value. mmm-is the relative terminal number. The relative line and terminal numbers are defined by IMS in the system definition (IMS stage 2) and can be obtained from your IMS systems programmer. Transactions from Non-Message Driven BMPs A BMP that does not read from the IMS message queues is called a non-message driven BMP. You can initiate transactions in an IMS control region from non-message driven BMPs. Because the BMP initiates the transactions using the IMS CHNG and ISRT calls, the IMS interface considers these BMP initiated transactions to be secondary transactions. Transactions that are initiated by a non-message driven BMP are validated by the IMS interface using the logonid of the BMP region. The IMS interface uses the job name of the BMP as the source for the validation. For example, if a BMP with a job name of PAYROLL were started using a logonid of PAYADM, the transactions would be validated using the PAYADM logonid with a source name of PAYROLL. Chapter 6: Transaction Security 91

Implementing Transaction Validation If a transaction initiated by a non-message driven BMP generates other transactions, the logonid used to validate these transactions depends on the values specified for the BMPUSID control option. If USERID is specified for the BMPUSID control option, these subsequent transactions are validated by the IMS interface using the logonid of the BMP region. If PSBNAME is specified for the BMPUSID control option, the subsequent transactions are validated using the control region default logonid. The IMS interface uses the value UNKNOWN as the source for the transaction validation. Transactions from Message Driven BMPs A BMP that reads messages from the IMS message queues as part of its processing is called a message driven BMP. You can initiate transactions in an IMS control region from message driven BMPs. Because the BMP initiates the transactions using the IMS CHNG and ISRT calls, the IMS interface considers these BMP initiated transactions to be secondary transactions. The logonid used to validate transactions that are initiated by a message driven BMP depends on the values specified for the BMPMSG control option. If BMPUSER is specified for the BMPMSG control option, the IMS interface validates the transactions using the logonid of the BMP region, with the job name of the BMP as the source for the validation. If MSGUSER is specified for the BMPMSG control option, the IMS interface validates the transactions using the logonid from the most recent message read from the IMS message queues before the new transaction is initiated by the BMP. If the message read was associated with an IMS terminal, the IMS interface creates the source name for the validation using the guidelines discussed previously for terminal initiated transactions. If the message read was not associated with an IMS terminal; the IMS interface uses the value UNKNOWN as the source for the transaction validation. For a transaction initiated by a message driven BMP, IMS propagates the logonid of the most recent message read with the transaction. If the transaction generates other transactions in turn, those transactions are validated using this logonid. If the transaction is associated with an IMS terminal, the IMS interface creates the source name for the validation using the guidelines discussed previously for terminal initiated transactions. If the transaction is not associated with an IMS terminal, the IMS interface uses the value UNKNOWN as the source for the transaction validation. Transactions from MSC and ISC Links You can initiate transactions in an IMS control region from MSC and ISC links. These links are teleprocessing links that connect an IMS system with other software systems over which messages and responses can be sent and received. The IMS interface validates all attempts to access a resource in the IMS control region at the receiving end of a link. For more information about MSC and ISC links, see the chapter Network Security." 92 IMS Support Guide

Implementing Transaction Validation Transactions from APPC Connections You can initiate IMS transactions from APPC connections to the IMS region. Transactions from an APPC connection can be validated by the IMS interface, or by CA ACF2 through a SAF interface. For more information about APPC security, see the chapter APPC Security." Transactions from OTMA Connections You can initiate IMS transactions from OTMA connections to the IMS region. Transaction from an OTMA connection can be validated by the IMS interface, or by CA ACF2 through a SAF interface. For more information about OTMA security, see the chapter OTMA Security." Transactions in an IMS Shared Queues Environment In an IMS shared queues environment, transactions can be entered in one IMS region, and can execute and generate secondary transactions in a different IMS region in the IMSplex. This affects the security process. Transactions are always validated using the transaction security options and the transaction resource rules of the IMS region in which the transaction validation is performed. Primary transactions and MFS formatted secondary transactions are entered directly by a terminal or network user into an IMS region, and are validated using the transaction security options and transaction resource rules of that region. If the transaction executes in the same IMS region and generates secondary transactions, the secondary transactions are again validated using the transaction security options and transaction resource rules of that region. If the transaction executes in a different (back-end) IMS region in the IMSplex and generates secondary transactions, the secondary transactions are validated using the transaction security options and transaction resource rules of the back-end IMS region. Transactions from the IMS OM QUE TRAN Command In IMS Version 10 and above, transactions can be entered from the IMS OM component using the OM QUE TRAN command. These transactions are validated by the IMS interface using the logonid of the person issuing the OM QUE TRAN command. The source used by the IMS interface for the resource validation is the literal DFSOMAPI, which is the IMS identifier for the OM interface. Chapter 6: Transaction Security 93

. Implementing Transaction Validation Step 3: Defining IMS RESOURCE Records You can implement validation processing for primary and secondary transactions by defining security options in the IMS RESOURCE records. As mentioned earlier, the IMS interface automatically provides transaction validation processing. If the IMS interface does not find an IMS RESOURCE record for transactions, it validates all IMS transactions with the default resource rule type code, ITR. The IMS interface does not discriminate between primary and secondary transactions. Primary Transactions The following discussions illustrate how to create IMS RESOURCE records for primary and secondary transactions. To define primary transaction validation in an IMS RESOURCE record, specify $PRITRAN for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for primary transactions, specify the NOVALIDATE keyword. To create an IMS RESOURCE record for primary transactions, enter the following INSERT subcommand statement: Secondary Transactions INSERT DIVISION(musid jobname) RESOURCE[.qualifier] - NAME($PRITRAN) TYPE(ITR type) {VALIDATE NOVALIDATE} If you do not use the default type code (ITR), ensure that the type code you define for this option is the type code used in the corresponding transaction resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. To define secondary transaction validation in an IMS RESOURCE record, specify $SECTRAN for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To turn off validation processing for secondary transactions, specify the NOVALIDATE keyword. To create an IMS RESOURCE record for secondary transactions, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] - NAME($SECTRAN) TYPE(ITR type) {VALIDATE NOVALIDATE} 94 IMS Support Guide

Implementing Transaction Validation If you use the same type code to validate secondary transactions and primary transactions, the secondary and primary transactions are validated with the same resource rules. To have secondary transactions validated separately with their own resource rules, you must specify a unique type code. Ensure that the type code you define for this option is the type code used in the corresponding transaction resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Step 4: Writing Transaction Resource Rules The IMS interface uses resource rules to validate IMS transactions. The only aspect of transaction resource rule writing that is important to note is the use of the type code. As stated earlier, the IMS interface lets you validate secondary transactions apart from primary transactions. To do so, secondary transaction resource rules must have a type code that is different from the type code used in primary transaction resource rules. With the exception of format-initiated transactions, the VERIFY keyword available for CA ACF2 resource rules is not supported for IMS secondary transactions. For more information about VERIFY and how to write resource rules, see your Administrator Guide. Sample Resource Rule for Primary Transactions The following sample resource rule is for primary transactions: $KEY(IAR****) TYPE(ITR) UID(APM) ALLOW SHIFT(NORMAL) UID(ARC) ALLOW SHIFT(NORMAL) UID(ARM) ALLOW VERIFY UID(IMSDFLT) ALLOW SOURCE(VT001) IAR**** Represents the transaction name. The asterisks indicate masking. Thus, IAR**** defines all seven-character transaction names that begin with the letters IAR, such as Inquiry Accounts Receivable transactions. ITR (IMS transactions) The CA ACF2 default type code for IMS primary transactions. Chapter 6: Transaction Security 95

Implementing Transaction Validation UID(APM) ALLOW SHIFT(NORMAL) All managers from the AP department can execute these transactions only during the company's normal working hours. UID(ARC) ALLOW SHIFT(NORMAL) All clerks from the AR department can execute these transactions only during the company's normal working hours. UID(ARM) ALLOW VERIFY All managers from the AR department can execute these transactions at any time, but they must reverify their passwords. UID(IMSDFLT) ALLOW SOURCE(VT001) The default logonid is granted access to these transactions when the transactions are entering the IMS system from the terminal VT001. Sample Resource Rule for Secondary Transactions The following sample resource rule is for secondary transactions: $KEY(UAR****) TYPE(STR) UID(ARM) ALLOW SHIFT(NORMAL) UID(ARC) ALLOW SHIFT(NORMAL) UID(APM) LOG UID(IMSDFLT) ALLOW SOURCE(VT002) UAR**** STR Represents the transaction names. The asterisks indicate masking. Thus, UAR**** defines all seven-character transaction names that begin with the letters UAR, such as Update Accounts Receivable transactions. A user-defined type code for secondary transactions. UID(ARM) ALLOW SHIFT(NORMAL) All managers from the AR department can execute these transactions only during the company's normal working hours. UID(ARC) ALLOW SHIFT(NORMAL) All clerks from the AR department can execute these transactions only during the company's normal working hours. UID(APM) LOG All managers from the AP department can execute these transactions at any time, and their accesses are logged. 96 IMS Support Guide

Implementing Transaction Validation UID(IMSDFLT) ALLOW SOURCE(VT002) The default logonid is permitted access to these transactions when the transactions are associated with the terminal VT002. Chapter 6: Transaction Security 97

Chapter 7: AGN and RAS Resource Security An application group name (AGN) identifies a group of terminals, program specification blocks, and transactions that an IMS dependent region, such as a BMP or a message-processing region, is permitted to access. The IMS interface provides AGN security that lets you control which terminals, PSBs, and transactions a dependent region can access. AGNs and AGN security are available in IMS releases up to and including IMS Release 9.1. In IMS Release 9.1, IMS introduced Resource Access Security (RAS) as a replacement for application group names and AGN security, which will be removed from the product. With RAS, the IMS interface provides direct validation of the terminals, PSBs, and transactions that a dependent region can access. The principal source for technical information about application group names and resource access security should be the IBM IMS documentation. This chapter is intended to supplement the IBM documentation and describe how the IMS interface performs AGN and RAS security. Note: In IMS Release 9.1, AGN security and RAS security are mutually exclusive. If AGN security is enabled, RAS security must be disabled with appropriate RESOURCE records with NOVALIDATE. Conversely, if any RAS security is enabled, AGN security must be disabled with a RESOURCE record with NOVALIDATE. This section contains the following topics: Design Concepts and Features (see page 99) RAS Security (see page 103) Design Concepts and Features AGNs and AGN security are available in IMS releases up to and including IMS Release 9.1. An AGN identifies a group of transactions, terminals, and PSBs that an IMS dependent region, such as a BMP, is permitted to access. AGNs are defined for an IMS system using the Security Maintenance Utility (SMU). Chapter 7: AGN and RAS Resource Security 99

Design Concepts and Features An IMS dependent region requests the use of an AGN by specifying the AGN name in the startup JCL for the dependent region. The IMS control region then limits the dependent region's use of IMS resources to those defined in the AGN that was requested. For message processing regions, IMS schedules work in the region only if the work falls in the limitations of the AGN. For example, if the AGN name is PAYROLL, transactions that are not defined in the AGN PAYROLL are not scheduled in the region. IMS screens requests from the transactions against the limitations in the AGN. As a security mechanism, AGNs are more useful for BMPs. BMPs can represent work that originates outside the IMS terminal network and are not subject to some of the security procedures that are in place for terminal originated work. For BMPs, IMS screens requests from the BMP, such as the PSB requested, against the limitations in the AGN. In IMS Release 9.1, IMS introduced Resource Access Security (RAS) as a replacement for AGNs and AGN security, which will be removed from the product. With RAS, the IMS interface provides direct validation of the terminals, PSBs, and transactions that a dependent region can access. For example, before a transaction is scheduled to execute in a message processing regions, the IMS interface performs a security validation to see if the logonid of the message processing region is allowed to execute the transaction. If not, the transaction will not be scheduled in that message processing region. IMS and IMS Interface AGN Processing IMS processing of AGNs occurs if dependent region AGN security has been requested. The IMS interface provides AGN security by default. If you do not want to use AGNs and dependent region security, you must deactivate the IMS interface AGN processing. To deactivate AGN validation, you must create a $AGN RESOURCE record that specifies NOVALIDATE. Failure to do this will cause errors in the initialization process. During IMS control region initialization, AGN information is read from the SMU security matrix to determine the AGN names and the resources that are associated with the AGNs. Users must specify an AGN name in the startup JCL for the IMS dependent regions (for example, message processing regions and BMPs). During dependent region initialization, the dependent region communicates to the control region the intent to use the AGN. The control region checks to see if the dependent region is permitted access to the requested AGN. The IMS interface accomplishes this security check by validating that the logonid of the dependent region is permitted access to the AGN. A resource rule validation is performed using the resource type code requested in the AGN RESOURCE record. If an AGN is not specified in the dependent region JCL, if an applicable resource rule does not exist, or if the logonid is not permitted access to the AGN, IMS abends the dependent region. If a resource rule grants access to the AGN, processing continues. 100 IMS Support Guide

Design Concepts and Features Defining Application Group Names to SMU To use dependent region authorization checking, you must define the associated resources in the Security Maintenance Utility (SMU). SMU is a security function internal to IMS that protects IMS commands and transactions through tables that associate logical terminals with commands and transactions. The following shows how each AGN must be defined in the SMU input. )( AGN name AGLTERM terminal name AGPSB PSB name AGTRAN transaction AGN name The name selected for the AGN. AGN is a constant and name identifies the terminals, PSBs, and transactions that follow it as a group that restricts access by dependent regions. The name must be eight characters or less and each AGN name must be unique. AGLTERM terminal name AGLTERM is a constant and terminal name is the logical terminal (LTERM) name for the terminal included in the AGN. AGPSB PSB name AGPSB is a constant and PSB name is the name of the PSB included in the AGN. AGTRAN transaction AGTRAN is a constant and transaction is the name of the transaction included in the AGN. When defining AGNs to SMU, you do not need to include all three groups of resources (terminal, PSB, and transaction) in an AGN, that is, an AGN can include only one or two of the groups. For example, an AGN can consist of terminals and PSBs only, or it can include only transactions. Also, a resource (terminal, PSB, or transaction) can appear in more than one AGN. Defining an IMS RESOURCE Record for AGN Validation You can implement validation processing for AGN security by defining security options in the IMS RESOURCE records. The IMS interface provides AGN validation processing by default. If it does not find an IMS RESOURCE record for AGNs, all IMS AGNs are validated with the default resource rule type code, IAG. To define AGN validation in an IMS RESOURCE record, specify $AGN for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for application group names, specify the NOVALIDATE keyword. Chapter 7: AGN and RAS Resource Security 101

Design Concepts and Features To create an IMS RESOURCE record for application group names, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($AGN) TYPE(IAG type) VALIDATE NOVALIDATE If you decide not to use the default type code (IAG), ensure that the type code you define for this option is the type code used in the corresponding AGN resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Writing Application Group Name Resource Rules The IMS interface uses resource rules to validate access to IMS application group names. To learn how to write resource rules, see your Administrator Guide. The following shows an example of AGN resource rules: $KEY(PAY****) TYPE(IAG) UID(APM) ALLOW SHIFT(NORMAL) UID(APC) ALLOW SHIFT(NORMAL) UID(APM) ALLOW PAY**** IAG Represents the application group name. The asterisks indicate masking. Thus, PAY**** defines all seven-character AGNs that begin with the letters PAY, such as Payroll AGNs. The CA ACF2 default type code for IMS application group names. UID(APM) ALLOW SHIFT(NORMAL) All managers from the AP department can select these AGNs only during the company's normal working hours. UID(APC) ALLOW SHIFT(NORMAL) All clerks from the AP department can select these AGNs only during the company's normal working hours. UID(APM) ALLOW All managers from the AP department can select these AGNs at any time. 102 IMS Support Guide

RAS Security RAS Security In IMS Release 9.1, IMS introduced Resource Access Security (RAS) as a replacement for application group names and AGN security. With RAS, the IMS interface provides direct validation of the terminals, PSBs, and transactions that a dependent region accesses. For example, before a transaction is scheduled to execute in a message processing regions, the IMS interface performs a security validation to see if the logonid of the message processing region is allowed to execute the transaction. If not, the transaction will not be scheduled in that message processing region. Defining an IMS RESOURCE Record for RAS Transaction Validation You can implement RAS transaction validation by defining security options in an IMS RESOURCE record. The IMS interface provides RAS transaction validation processing by default. If it does not find an IMS RESOURCE record for RAS transaction validation, RAS transaction validation is performed with the default resource rule type code, ITR. To define RAS transaction validation in an IMS RESOURCE record, specify $RASTRAN for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate RAS transaction validation, specify the NOVALIDATE keyword. Note: As with all ACF2/IMS resource security options, security is provided by default. If you do not want to perform RAS transaction validation, you must install a RESOURCE record with the NOVALIDATE option specified. To create an IMS RESOURCE record for RAS transaction security, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($RASTRAN) TYPE(ITR type) VALIDATE NOVALIDATE If you decide not to use the default type code (ITR), ensure that the type code you define for this option is the type code used in the corresponding transaction resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Chapter 7: AGN and RAS Resource Security 103

RAS Security Writing Resource Rules for RAS Transaction Security The IMS interface uses resource rules to perform RAS transaction validation. To learn how to write resource rules, see your Administrator Guide. The following shows an example of a RAS transaction resource rule: $KEY(PAY****) TYPE(ITR) UID(APM) ALLOW PAY**** ITR Represents the transaction. The asterisks indicate masking. Thus, PAY**** defines all seven-character transactions that begin with the letters PAY, such as Payroll transactions. The CA ACF2 default type code for IMS transactions. UID(APM) ALLOW A dependent region with a logonid for the AP department can execute these transactions. Defining an IMS RESOURCE Record for RAS PSB Validation You can implement RAS PSB validation by defining security options in an IMS RESOURCE record. The IMS interface provides RAS PSB validation processing by default. If it does not find an IMS RESOURCE record for RAS PSB validation, RAS PSB validation is performed with the default resource rule type code, IPS. To define RAS PSB validation in an IMS RESOURCE record, specify $RASPSB for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate RAS PSB validation, specify the NOVALIDATE keyword. Note the following: As with all CA ACF2/IMS resource security options, security is provided by default. If you do not want to perform RAS PSB validation, you must install a RESOURCE record with the NOVALIDATE option specified. CA ACF2/IMS already performs security for PSB's for IMS BMP regions using the $PSB RESOURCE record. If this is sufficient PSB security, RAS PSB security should be set to NOVALIDATE. For more information see the PSB Security." 104 IMS Support Guide

RAS Security To create an IMS RESOURCE record for RAS PSB security, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($RASPSB) TYPE(IPS type) VALIDATE NOVALIDATE If you decide not to use the default type code (IPS), ensure that the type code you define for this option is the type code used in the corresponding PSB resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Writing Resource Rules for RAS PSB Security The IMS interface uses resource rules to perform RAS PSB validation. To learn how to write resource rules, see your Administrator Guide. The following shows an example of a RAS PSB resource rule: $KEY(PAY****) TYPE(IPS) UID(APM) ALLOW PAY**** IPS Represents the PSB. The asterisks indicate masking. Thus, PAY**** defines all seven-character PSBs that begin with the letters PAY, such as Payroll PSBs. The CA ACF2 default type code for IMS PSBs. UID(APM) ALLOW A dependent region with a logonid for the AP department can reference these PSBs. Defining an IMS RESOURCE Record for RAS LTERM Validation You can implement RAS validation processing for LTERMs by defining security options in an IMS RESOURCE record. The IMS interface provides RAS LTERM validation processing by default. If it does not find an IMS RESOURCE record for RAS LTERM validation, RAS LTERM validation is performed with the default resource rule type code, IRT. To define RAS LTERM validation in an IMS RESOURCE record, specify $RASTERM for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate RAS LTERM validation, specify the NOVALIDATE keyword. Chapter 7: AGN and RAS Resource Security 105

RAS Security Note: As with all ACF2/IMS resource security options, security is provided by default. If you do not want to perform RAS LTERM validation, you must install a RESOURCE record with the NOVALIDATE option specified. To create an IMS RESOURCE record for RAS LTERM security, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($RASTERM) TYPE(IRT type) VALIDATE NOVALIDATE If you decide not to use the default type code (IRT), ensure that the type code you define for this option is the type code used in the corresponding LTERM resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Writing Resource Rules for RAS LTERM Security The IMS interface uses resource rules to perform RAS LTERM validation. To learn how to write resource rules, see your Administrator Guide. The following shows an example of a RAS LTERM resource rule: $KEY(PAY****) TYPE(IRT) UID(APM) ALLOW PAY**** IRT Represents the LTERM. The asterisks indicate masking. Thus, PAY**** defines all seven-character LTERMs that begin with the letters PAY, such as Payroll LTERMs. The CA ACF2 default type code for IMS LTERMs. UID(APM) ALLOW A dependent region with a logonid for the AP department can reference these LTERMs. 106 IMS Support Guide

Chapter 8: IMS Command Security The IMS interface provides command security to let you control who can issue IMS commands. It matches the UID of the user issuing the command against the UID and access conditions in the command resource rule to determine whether the user can issue the command. Commands entered through OTMA or APPC connections can be validated by the IMS interface or by CA ACF2 through the SAF interface. For more information about security for these commands, see the chapters APPC Security and OTMA Security. This section contains the following topics: Design Concepts and Features (see page 107) Implementing Command Validation (see page 113) Exit Processing and IMS Command Keyword Security (see page 117) Design Concepts and Features This section discusses IMS commands, IMS command security, and IMS interface protection for these commands. IMS provides a set of commands that can be entered at IMS terminals or by application programs using the Automated Operator Interface (AOI). These commands provide IMS control and display functions. Some examples of the functions provided by these commands are: Enable and disable transactions and terminals Start and stop network links and dependent regions Display the status of transactions, terminals, and links Shut down the IMS system IMS protects commands through a default IMS security scheme, the internal IMS Security Maintenance Utility (SMU), or external security (IMS interface). Default IMS Security When neither the Security Maintenance Utility nor the IMS interface is invoked, IMS protects commands solely through a default terminal security scheme. This facility lets users issue any command at the IMS master terminal and system consoles, and only a small subset of commands from any other IMS terminal. This mechanism protects the commands based on the terminal entering the command, not the user. Chapter 8: IMS Command Security 107

Design Concepts and Features Security Maintenance Utility (SMU) IMS uses the Security Maintenance Utility (SMU) to provide security in addition to the default terminal security. This utility creates a list of commands and transactions that can be performed from a specified terminal. The list associates commands and transactions with the logical terminal. During system definition, the SMU is executed offline. SMU creates the table that defines the command and transaction restrictions for each terminal. If SMU definitions are not provided, IMS uses its default terminal security scheme. If SMU table definitions are provided, IMS restricts users to the specified commands at a particular terminal. For more information about the SMU and IMS security functions, see the chapter CA-ACF2 IMS Philosophy IMS Interface Validation of Terminal Commands The IMS interface controls who can enter IMS commands at an IMS terminal by validating the UID of the person entering the command against a resource rule for that command. CA ACF2 lets you protect commands at the verb level and, through exit processing, control commands at the level of any keyword. The IMS interface validates commands by referencing a resource rule in which the resource name is the full command verb. For example, if the following command is entered at an IMS terminal, the resource name validated is DISPLAY: /DIS A 108 IMS Support Guide

Design Concepts and Features IMS Interface Validation of Type 1 AOI Commands Application programs can issue IMS commands using the CMD communications call and retrieve the command response using the GCMD communications call. These commands are called type 1 AOI commands. For releases of IMS prior to IMS Release 9.1, the only security available for these commands is the TRANCMD security function of SMU. For IMS Release 9.1 and above, the IMS interface provides security for type 1 AOI commands. The IMS interface validates type 1 AOI commands by referencing a resource rule in which the resource name is the full command verb. For example, if the CMD call is used to issue the following command, the resource name validated is DISPLAY. /DIS A AOI1 and RCF Options The security provided by the CA ACF2 IMS security interface for a type 1 AOI command is determined by two factors: 1. Is the command coming from a transaction application or a BMP? 2. If the command is coming from a transaction application, what is the value for the AOI parameter specified for the transaction in the IMS system definition TRANSACT macro? The possible values for the AOI parameter are NO, YES, TRAN, and CMD. The AOI1 and RCF options are changed by CA ACF2 IMS because the interface validates based on the options specified in the CA ACF2 IMS control records. These changes help IMS makes the appropriate security requests. CA ACF2 IMS changes the IMS parameters that makes only the signon and resource validations that are processed by the interface. If you want to validate type 1 AOI commands, have AOI1 set to R, and defined a CA ACF2 IMS resource record for $TRANCM1 with validate, CA ACF2 IMS enables this security by forcing the active IMS parameter to AOI1=C. The CA ACF2 IMS interface takes control for the validation. CA ACF2 IMS forces RCF=S to limit the scope of RACROUTE calls associated with static and ETO terminals to commands. Any validations omitted by the change from A to S are handled elsewhere in the CA ACF2 IMS processing as indicated by the CA ACF2 IMS resource and signon records. Type 1 AOI Commands from Transactions with AOI=NO If AOI=NO is specified or defaulted, the transaction is not allowed to issue any AOI type 1 commands. This restriction is enforced by IMS, and no calls are made to CA ACF2. Chapter 8: IMS Command Security 109

Design Concepts and Features Type 1 AOI Commands from Transactions with AOI=YES If AOI=YES is specified, CA ACF2 performs security validations for type 1 AOI commands using the logonid of the individual user. This alternative, checking user access to the command, is the most granular security option. The user can be given access to one command entered through a transaction and denied access to another command entered through the same transaction. This alternative also allows for individual accountability in the security process; when an access is denied, the violation is for the individual user. If the application program issuing the CMD call is a transaction application (MPP), the command is validated using the logonid of the terminal user who initiated the transaction and a source field of the terminal where the transaction was entered. If the terminal is not signed on, the IMS interface uses the control region default logonid for validation. IMS allows a transaction application (MPP) to issue the CMD call before it issues a GET UNIQUE (GU) from the transaction queue. In this case, IMS has not yet associated the transaction with a terminal request. The IMS interface validates the CMD command using the control region default logonid with a source of the IMS program (PSB) name for the transaction program. If the transaction issuing the command is associated with an IMS network link (MSC, ISC, APPC, or OTMA), the command is validated according to the options specified in the IMS NETWORK record controlling the link. If no NETWORK record is found controlling the link, the IMS interface uses its default security processing for network links. These alternatives are described in the chapters MSC and ISC Link Security, APPC Security and OTMA Security. Type 1 AOI Commands from Transactions with AOI=TRAN If AOI=TRAN is specified, CA ACF2 performs security validations for type 1 AOI commands using the IMS default logonid with a SOURCE restriction of the transaction issuing the command. Because it is transaction based, this alternative does not provide user-based granularity in security policy. It does not provide individual accountability; if access is denied, the violation is for the IMS default logonid with the transaction as source. This option should only be chosen if CA ACF2 is used for transaction security. CA ACF2 controls user access to the transaction using transaction rules, and controls what commands the transaction can issue using AOI command rules. Type 1 AOI Commands from Transactions with AOI=CMD Type 1 AOI Commands from BMPs AOI=CMD should not be implemented in an CA ACF2 security environment. If the CMD call is issued from a non-message driven BMP, the IMS interface validates the command using the logonid of the BMP, with a source of the BMP job name. 110 IMS Support Guide

Design Concepts and Features If the CMD call is issued from a message driven BMP, the logonid used to validate the command depends on the values specified for the BMPMSG control option. If BMPUSER is specified for the BMPMSG control option, the IMS interface validates the command using the logonid of the BMP region, with the job name of the BMP as the source for the validation. If MSGUSER is specified for the BMPMSG control option, the IMS interface validates the command using the logonid from the most recent message read from the IMS message queues. If the message read was associated with an IMS terminal, the IMS interface creates the source name for the validation using the guidelines discussed previously for terminal initiated transactions. If the message read was not associated with an IMS terminal, the IMS interface uses the value UNKNOWN as the source for the command validation. IMS Interface Validation of Type 2 AOI Commands Application programs can also issue IMS commands using the ICMD communications call and retrieve the command response using the RCMD communications call. These commands are called type 2 AOI commands. For all releases of IMS, the IMS interface provides security for type 2 AOI commands. The IMS interface validates type 2 AOI commands by referencing a resource rule in which the resource name is the full command verb. For example, if the ICMD call is used to issue the following command, the resource name validated is DISPLAY. /DIS A The security provided by the ACF2 IMS security interface for a type 2 AOI command is determined by two factors: 1. Is the command coming from a transaction application or a BMP? 2. If the command is coming from a transaction application, what is the value for the AOI parameter specified for the transaction in the IMS system definition TRANSACT macro? The possible values for the AOI parameter are NO, YES, TRAN, and CMD. Type 2 AOI Commands from Transactions with AOI=NO A value of AOI=NO is not supported by IMS for transactions that issue type 2 AOI commands. If AOI=NO is specified or defaulted for a transaction that issues type 2 AOI commands, the commands are validated as if AOI=YES was specified. This decision is made and enforced by IMS. For more information, see the IMS System Definition Reference. Chapter 8: IMS Command Security 111

Design Concepts and Features Type 2 AOI Commands from Transactions with AOI=YES If AOI=YES is specified, CA ACF2 performs security validations for type 2 AOI commands using the logonid of the individual user. This alternative, checking user access to the command, is the most granular security option. The user can be given access to one command entered through a transaction and denied access to another command entered through the same transaction. This alternative also allows for individual accountability in the security process; when an access is denied, the violation is for the individual user. If the application program issuing the ICMD call is a transaction application (MPP), the command is validated using the logonid of the terminal user who initiated the transaction and a source field of the terminal where the transaction was entered. If the terminal is not signed on, the IMS interface uses the control region default logonid for validation. IMS allows a transaction application (MPP) to issue the ICMD call before it issues a GET UNIQUE (GU) from the transaction queue. In this case, IMS has not yet associated the transaction with a terminal request. The IMS interface validates the ICMD command using the control region default logonid with a source of the IMS program (PSB) name for the transaction program. If the transaction issuing the command is associated with an IMS network link (MSC, ISC, APPC, or OTMA), the command is validated according to the options specified in the IMS NETWORK record controlling the link. If no NETWORK record is found controlling the link, the IMS interface uses its default security processing for network links. These alternatives are described in the chapters MSC and ISC Link Security, APPC Security and OTMA Security. Type 2 AOI Commands from Transactions with AOI=TRAN If AOI=TRAN is specified, CA ACF2 performs security validations for type 2 AOI commands using the IMS default logonid with a SOURCE restriction of the transaction issuing the command. Because it is transaction based, this alternative does not provide user-based granularity in security policy. It does not provide individual accountability; if access is denied, the violation is for the IMS default logonid with the transaction as source. This option should only be chosen if CA ACF2 is used for transaction security. CA ACF2 controls user access to the transaction using transaction rules, and controls what commands the transaction can issue using AOI command rules. Type 2 AOI Commands from Transactions with AOI=CMD Type 2 AOI Commands from BMPs AOI=CMD should not be implemented in an CA ACF2 security environment. If the ICMD call is issued from a non-message driven BMP, the IMS interface validates the command using the logonid of the BMP, with a source of the BMP job name. 112 IMS Support Guide

. Implementing Command Validation If the ICMD call is issued from a message driven BMP, the logonid used to validate the command depends on the values specified for the BMPMSG control option. If BMPUSER is specified for the BMPMSG control option, the IMS interface validates the command using the logonid of the BMP region, with the job name of the BMP as the source for the validation. If MSGUSER is specified for the BMPMSG control option, the IMS interface validates the command using the logonid from the most recent message read from the IMS message queues. If the message read was associated with an IMS terminal, the IMS interface creates the source name for the validation using the guidelines discussed previously for terminal initiated transactions. If the message read was not associated with an IMS terminal, the IMS interface uses the value UNKNOWN as the source for the command validation. AOI Commands in an IMS Shared Queues Environment In an IMS shared queues environment, transactions can be entered in one IMS region, and can execute and generate AOI commands in a different IMS region in the IMSplex. This affects the security process. AOI commands are always validated using the AOI command security options and the AOI command resource rules of the IMS region in which the command validation is performed. If a transaction executes in the front-end IMS region where the user is signed on, and generates AOI commands, the commands are validated using the AOI command security options and AOI command resource rules of the front-end IMS region If the transaction executes in a back-end IMS region in the IMSplex and generates AOI commands, the commands are validated using the AOI command security options and AOI command resource rules of the back-end IMS region. Implementing Command Validation This section describes the major tasks required to implement command validation. The following tasks are required to implement command validation. 1. Determined whether to validate commands. 2. Define command validations in the IMS RESOURCE records. 3. Write command resource rules for the commands you have decided to protect. Chapter 8: IMS Command Security 113

Implementing Command Validation Step 1: Validating Commands Validating Terminal Commands Validating Type 1 AOI Commands Validating Type 2 AOI Commands The IMS interface performs validation processing for IMS terminal commands by default. If you do not want to secure terminal commands, you must deactivate the IMS interface terminal command validation processing. To deactivate terminal command validation, create an IMS RESOURCE record for terminal commands that specifies NOVALIDATE. For IMS Release 9.1 and above, the IMS interface performs validation processing for type 1 AOI (CMD) commands by default. If you do not want to secure type 1 AOI commands, you must deactivate the IMS interface validation processing for these commands. To deactivate this command validation, create an IMS RESOURCE record for type 1 AOI commands that specifies NOVALIDATE. The IMS interface performs validation processing for type 2 AOI (ICMD) commands by default. If you do not want to secure type 2 AOI commands, you must deactivate the IMS interface validation processing for these commands. To deactivate this command validation, create an IMS RESOURCE record for type 2 AOI commands that specifies NOVALIDATE. Step 2: Defining IMS RESOURCE Records for Command Validation Commands from Terminals You can implement validation processing for IMS commands by defining security options in the IMS RESOURCE records. As mentioned earlier, the IMS interface automatically provides command validation processing. If it does not find an IMS RESOURCE record for commands, it validates all IMS commands with the default resource rule type code, ICM. The following illustrates how to create an IMS RESOURCE record for commands from terminals. To define command validation for commands from terminals in an IMS RESOURCE record, specify $COMMAND for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for commands from terminals, specify the NOVALIDATE keyword. 114 IMS Support Guide

Implementing Command Validation To create an IMS RESOURCE record for commands from terminals, enter the following INSERT subcommand: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] - NAME($COMMAND) TYPE(ICM type) {VALIDATE NOVALIDATE} If you do not use the default type code (ICM), ensure that the type code you define for this option is the type code used in the corresponding command resource rules. Type 1 AOI (CMD) Commands If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. The following illustrates how to create an IMS RESOURCE record for type 1 AOI commands. To define command validation for type 1 AOI commands in an IMS RESOURCE record, specify $TRANCM1 for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for type 1 AOI commands, specify the NOVALIDATE keyword. To create an IMS RESOURCE record for type 1 AOI commands, enter the following INSERT subcommand: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] - NAME($TRANCM1) TYPE(ICM type) {VALIDATE NOVALIDATE} If you do not use the default type code (ICM), ensure that the type code you define for this option is the type code used in the corresponding command resource rules. Type 2 AOI (ICMD) Commands If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. The following illustrates how to create an IMS RESOURCE record for type 2 AOI commands. To define command validation for type 2 AOI commands in an IMS RESOURCE record, specify $TRANCMD for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for type 2 AOI commands, specify the NOVALIDATE keyword. Chapter 8: IMS Command Security 115

Implementing Command Validation To create an IMS RESOURCE record for type 2 AOI commands, enter the following INSERT subcommand: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] - NAME($TRANCMD) TYPE(ICM type) {VALIDATE NOVALIDATE} If you do not use the default type code (ICM), ensure that the type code you define for this option is the type code used in the corresponding command resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Step 3: Writing Command Resource Rules CA ACF2 resource rules validate IMS commands. You must ensure that the type code you use to write command resource rules is the same type code used in the TYPE field of the IMS RESOURCE record. The VERIFY keyword available for CA ACF2 resource rules is supported for IMS commands issued from terminals; it is not supported for transactions issuing AOI commands. To implement password reverification, you must enter the password on the IMS command according to IMS conventions, such as the following: /VERB(password) KEYWORD See the IBM publication IMS Command Reference for more information about specifying passwords with commands. For more information about VERIFY and to learn about writing resource rules, see your Administrator Guide. 116 IMS Support Guide

Exit Processing and IMS Command Keyword Security Sample Resource Rule for Commands The following provides an example of a command resource rule. $KEY(DISPLAY) TYPE(ICM) UID(ARM) ALLOW SHIFT(NORMAL) UID(ARC) ALLOW SHIFT(NORMAL) UID(APM) ALLOW VERIFY UID(IMSDFLT) ALLOW SOURCE(VT002) $KEY(DISPLAY) Represents the /DISPLAY command. TYPE(ICM) (IMS commands) The CA ACF2 default type code for IMS commands. UID(APM) ALLOW SHIFT(NORMAL) All managers from the AR department can execute this command only during the company's normal working hours. UID(ARC) ALLOW SHIFT(NORMAL) All clerks from the AR department can execute this command only during the company's normal working hours. UID(APM) ALLOW VERIFY All managers from the AR department can execute this command at any time, but they must reverify their passwords. UID(IMSDFLT) ALLOW SOURCE(VT002) The default logonid is permitted to use this command when the command is associated with the terminal VT002. Exit Processing and IMS Command Keyword Security The IMS TM Interface controls the ability to issue IMS commands. This ability extends to the first level or verb of an IMS command. If you want to protect additional levels or keywords of an IMS command, you can use the IMS interface prevalidation (PREVAL) exit. The prevalidation exit lets you receive control before the IMS interface validation processing. The IMS interface passes the I/O data buffer, which contains the command and the keywords specified with the command, to the prevalidation exit. You can examine the I/O data buffer and change the XPVRKEY field to the resource name of your choice. When the prevalidation exit passes this field back to the IMS interface, the interface uses this new resource name to check the command resource rules. Chapter 8: IMS Command Security 117

Exit Processing and IMS Command Keyword Security Create resource rules for these command and keyword names. The following example shows such a resource rule: $KEY(DISPLAYTRANSACTION) TYPE(ICM) UID(-) ALLOW 118 IMS Support Guide

Chapter 9: PSB Security A PSB (program specification block) is an IMS control block that identifies the terminals, transactions, databases, and database segments that an application program can access. Because a program that executes online must have the same name as the PSB, the IMS interface transaction security can effectively control the program's access to IMS databases. In a batch environment such as a BMP, however, a job can use any PSB with any application program. With the IMS interface, you can write resource rules to secure BMP use of PSBs. Note: In IMS Release 9.1, IMS introduced RAS security, which includes security validation of PSBs for all IMS dependent regions. If the IMS interface RAS security for PSBs has been enabled, the direct security for BMP PSBs described in this chapter is redundant. If you are running IMS release 9.1 or above, read this chapter and the chapter AGN and RAS Resource Security to determine if you want to perform RAS security for PSBs or direct PSB security for BMPs. This section contains the following topics: Design Concepts and Features (see page 119) Defining IMS RESOURCE Records (see page 120) Writing PSB Resource Rules (see page 120) Design Concepts and Features This section describes PSBs and how to secure their use in online and batch environments. A PSB is an assembled control block that any program interacting with IMS must have. The PSB specifies the IMS databases, segments, and fields that the program can access, and the type of access allowed. The PSB also specifies some of the transactions that the program is allowed to place on the IMS message queues. An online transaction must use a PSB with the same name as the transaction program. Therefore, you can use existing IMS interface transaction security to indirectly control the online use of PSBs. A BMP (batch message processing) is a batch-like job that communicates with an IMS system. The BMP can make requests for the IMS databases, and can create and retrieve transactions from the IMS message queues. Because BMPs can execute a program with one name and request a PSB with another name, additional security is required to control a BMP's use of a PSB. Chapter 9: PSB Security 119

Defining IMS RESOURCE Records Defining IMS RESOURCE Records You can implement validation processing for PSB security by defining options in the IMS RESOURCE records. The IMS interface automatically protects the use of PSBs by BMPs by default. If it does not find an IMS RESOURCE record for PSBs, it validates a BMP's use of a PSB with the default resource rule type code IPS. The following illustrates how to create an IMS resource record for PSBs. To define PSB validation in an IMS RESOURCE record, specify $PSB for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for PSBs, specify the NOVALIDATE keyword. To create an IMS RESOURCE record for PSBs that are used by BMPs, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] - NAME($PSB) TYPE(IPS type) VALIDATE NOVALIDATE If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE0001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Writing PSB Resource Rules CA ACF2 resource rules validate BMP access to PSBs. To learn how to write resource rules, see the Administrator Guide. The following shows an example of PSB resource rules: $KEY(PAY****) TYPE(IPS) UID(TESTUID) SOURCE(TESTJOB1) ALLOW UID(TESTUID2) ALLOW PAY**** IPS Represents the PSB name. The asterisks indicate masking. Thus, PAY**** defines all seven-character PSBs that begin with the letters PAY, such as PSBs used for payroll applications. The CA ACF2 default type code for PSBs used by BMPs. UID(TESTUID) SOURCE(TESTJOB1) ALLOW The BMP with a logonid whose UID is TESTUID can use the payroll PSBs, but only when the request originates from a job with the jobname TESTJOB1. 120 IMS Support Guide

Writing PSB Resource Rules UID(TESTUID2) ALLOW The BMP with a logonid whose UID is TESTUID2 can use the payroll PSBs. Chapter 9: PSB Security 121

Chapter 10: MSC and ISC Link Security The IMS TM Interface secures IMS resources that are accessed by systems across an MSC or ISC communications link. The communications links are teleprocessing links that connect an IMS system with other software systems where messages and responses can be sent and received. The IMS interface validates all attempts to access a resource in the IMS control region at the receiving end of a link. It validates these access attempts in one of three ways: Matching the UIDs of user logonids inherited from the sending IMS control region to resource rules Matching the UIDs of link default logonids and their access conditions to resource rules Matching the UIDs of the IMS control region default logonid to resource rules This section contains the following topics: Design Concepts and Features (see page 123) Default IMS Interface Security for MSC and ISC Links (see page 126) Extended IMS Interface Security for MSC and ISC Links (see page 128) Design Concepts and Features This section provides an overview of InterSystems Communication (ISC) links and Multiple Systems Coupling (MSC) links. IMS interface network security information appears later in this chapter. ISC Concepts An InterSystems Communication (ISC) link is a teleprocessing link between the IMS system and another system that uses VTAM LU 6.1 protocol. The second system can be another IMS system, a CICS system, or any piece of software that can communicate with the LU 6.1 protocol. An ISC link appears in the IMS system as a single physical link, but the link can be capable of supporting multiple sessions. One of the limitations of ISC links is that there is no provision for passing security information. For example, if a CICS system sends a transaction over an ISC link, none of the security information from the CICS systems is passed to the receiving IMS system. Chapter 10: MSC and ISC Link Security 123

Design Concepts and Features MSC Concepts A Multiple Systems Coupling (MSC) link is one kind of a teleprocessing link between two IMS systems (control regions). The IMS systems involved can transfer work and responses from one system to another. The system sending the work is known as the sending or originating system. The system where the work is sent is the receiving or target system. A B A more complex example of an MSC network can occur if there are three (or more) IMS systems. A B C In our previous example, system A has a teleprocessing link, called a physical link to system B, and system B has a physical MSC link to system C. An MSC logical link path can be defined between systems A and C when the appropriate statements in the system definitions of each IMS system are set. System A can communicate with system C through system B because of the network configuration in its system definitions. Similarly, system C can communicate with system A through system B. If system A has work for system C, it sends the work to system B, which forwards the work to system C for processing. If there is a response, the response is sent from system C through system B to system A. In the previous configuration, system B is the intermediate system or intermediate node. On the physical link connecting system A with system B, there are two logical link paths, one that connects system A with system B and the other that connects system A with system C. Each MSC system is defined and identified by a unique system number called a system ID or sysid. In the previous example, system A might have a system ID of 1, system B a system ID of 2, and system C a system ID of 3. In the system definition for system A, there are statements that define the physical MSC link between system A and system B. Also, there is the logical link path statements that define the MSC systems that system A knows about and can communicate with. 124 IMS Support Guide

Design Concepts and Features In the system definition for system A, the logical link paths are defined on MSNAME statements. For the physical link AB, there are two MSNAME statements that define the logical paths to system B and system C. Each MSNAME statement has a name for the logical link path, which we call the MSC logical link name, and the system IDs of the target and originating IMS systems. For the logical link path to system C, an MSNAME statement has a logical link name, for example, IMSC, a target system ID of 3 and an originating system ID of 1. Logical link paths can be reassigned from one physical link to another. As an example, look at the following illustration that shows three IMS regions configured in a ring network. AB A AC B C BC On physical link AC, system A has the logical link path to system C. On physical link AB, system A has the logical link path to system B. On physical link BC, system B has the logical link path to system C. Each MSC node communicates directly with the other nodes. However, if the physical teleprocessing link AC becomes unavailable, system A no longer has the physical path to communicate with system C. In system A, the logical link path to system C can be reassigned from physical link AC to physical link AB. Correspondingly, in system C, the logical link path to system A is reassigned from physical link AC to physical link BC. When this is finished, the connection between systems A and C is established through system B, and the configuration looks like the initial example. AB A B C The logical link path defines a connected MSC node. Regardless of which physical link system A uses, the logical link path to system C represents system C. Chapter 10: MSC and ISC Link Security 125

Default IMS Interface Security for MSC and ISC Links Usually, all the transactions that can enter an IMS system are defined in the system definition statements (Stage 1). The definition statements for a transaction contain the system ID of the MSC node where the transaction should execute. Transactions that execute in the IMS system being defined are called local transactions. Transactions that are shipped to and execute in other MSC nodes are called remote transactions. In the previous example, transaction TRANSA is defined with a system ID of 1 (this is a local transaction) in the system definition statements for system A. Transactions TRANSB and TRANSC are defined with system IDs of 2 and 3; these transactions are remote transactions. When transaction TRANSB is entered in system A, IMS recognizes from the system ID in the transaction definition that the transaction should be shipped to system B. System A finds the logical link path for system B and ships the transaction over the corresponding physical link. Using MSC direct routing, a transaction can be shipped from system A to system B without the transaction being defined in system A. Directed routing works for program-to-program message switches, that is, when a transaction initiates another transaction. With directed routing, the initial transaction specifies both the transaction name of the second transaction and the system ID of the target system. The transaction definitions are not checked in the originating system. The second transaction is shipped to the specified target system. Directed routing is important because it has security implications. Additional information about directed routing is provided in the Default IMS Interface Security for MSC and ISC section later in this chapter. Default IMS Interface Security for MSC and ISC Links If a particular ISC or MSC link does not have a NETWORK record that controls it, the IMS interface provides a default level of security for the transactions and commands from the link. Default IMS Interface Security for ISC Links ISC links appear to IMS like special terminals that use the VTAM LU 6.1 protocol, and the links are secured in the same manner as IMS terminals. If the software that is communicating with IMS using the ISC link is designed to allow an IMS sign-on to be performed and a sign-on is done, the subsequent work is validated using the logonid of the signed on user. If the software does not allow IMS sign-on, or if no sign-on occurred, the work that originates from the ISC link is validated using the IMS control region default logonid. The source name used for the validation is the VTAM node name for the ISC link. 126 IMS Support Guide

Default IMS Interface Security for MSC and ISC Links Default IMS Interface Security for MSC Links There are two categories of inbound transactions on an MSC link: normal inbound transactions and directed routing transactions. Normal Inbound Transactions IMS does not invoke transaction security for normal (that is, not directed routing) inbound MSC transactions. This is because the transactions can be secured in the sending system, and transaction security in the receiving system would be unnecessary overhead. IMS does not invoke transaction security so the IMS interface default security for MSC links does not validate these transactions. Directed Routing Transactions Directed routing transactions are not secured in the sending system because the transaction might not be defined there. Security processing is invoked for these transactions in the receiving system. The IMS interface validates these transactions using the IMS control region default logonid. The source name used for the validation is the normal IMS interface source format described on the following page. These directed routing transactions are classified as primary transactions. For detailed information about primary and secondary transactions, see the chapter Transaction Security. If any transaction from an MSC link initiates a secondary transaction, the secondary transaction is validated using the IMS control region default logonid. If any transaction from an MSC link issues an IMS AOI command, the command is validated using the IMS control region default logonid. The source name that the IMS interface uses for the resource validation involving an MSC link is in one of two formats. If the physical link is a VTAM link, the VTAM node name of the link is the source. If the physical link is not a VTAM link, the source name is generated using the relative line and terminal numbers for the link. The format of the source name is: Illl/ttt Where: I-Is a constant lll-is the relative line number /-Is a constant ttt-is the relative terminal number IMS defines the relative line number and the relative terminal number in the system definition (Stage 2). You can obtain these numbers from your IMS systems programmer. Chapter 10: MSC and ISC Link Security 127

Extended IMS Interface Security for MSC and ISC Links Extended IMS Interface Security for MSC and ISC Links You can implement extended IMS interface security for MSC and ISC links with security options in IMS records. The NETWORK records control the security options for one or more network links. Extended IMS Interface Security for ISC Links If the IMS interface finds a NETWORK record that matches the VTAM node name of an ISC link, the options on that record control the extended security processing for the link. If the record specifies INBOUND, the IMS interface validates the transactions received on the link; if the record specifies NOINBOUND, it does not validate transactions received on the link. If the transactions that are received on the link initiate other (secondary) transactions, the IMS interface always validates the secondary transactions. The setting of the INBOUND NOINBOUND field does not affect the processing of secondary transactions. If the transactions that are received on the link issue IMS AOI commands, the IMS interface validates the command. The setting of the INBOUND NOINBOUND field does not affect the processing of commands. If the software that is communicating with IMS using the ISC link is designed to allow an IMS sign-on to be performed and a sign-on occurs, the IMS interface validates the resource access using the logonid of the signed on user. If the software is not designed to allow an IMS sign-on or if no sign-on occurs, it validates the work that originates from the ISC link using the link default logonid (if one is specified in the NETWORK record), or the control region default logonid if no link default is specified. Extended IMS Interface Security for MSC Links If the IMS interface finds a NETWORK record that matches the logical link name for an MSC logical link path, the options in that record control the extended security processing for the link path. If the record specifies INBOUND, the IMS interface validates all transactions received from the sending system; if the record specifies NOINBOUND, it does not validate normal inbound transactions. Directed routing transactions are validated as usual. If the transactions that are received on the link initiate other (secondary) transactions, the IMS interface always validates the secondary transactions. The setting of the INBOUND NOINBOUND field does not affect the processing of the secondary transactions. If the transactions that are received on the link issue IMS AOI commands, the IMS interface validates the command. The setting of the INBOUND/NOINBOUND field does not affect the processing of commands. The other NETWORK options are interrelated and explained in the next section. Note: The source that the IMS interface uses for validation of MSC links that use extended MSC security, is the MSC link path name from the MSNAME statement. This is a change from the default MSC security processing. 128 IMS Support Guide

Extended IMS Interface Security for MSC and ISC Links IMS NETWORK Records Extended network security is implemented by defining security options in IMS NETWORK records. The NETWORK records control the security for one or more network links. LINKNAME(linkname) Specifies which IMS links this record controls. You can specify an individual link name or a mask. A dash (-) is not valid as a masking character for this field. If you wish to specify that this NETWORK record should apply to all links, type LINKNAME(********). TYPE(MSC ISC) Defines which IMS links are controlled by this record in conjunction with the LINKNAME field. The default is MSC. DFTLID(linkdefaultlogonid) Specify a special default logonid for the link. This field is optional. INBOUND NOINBOUND Controls transactions being received from the link are validated. If INBOUND is specified, the transactions being received from the link are validated; if NOINBOUND is specified, they are not validated. The default is INBOUND. On MSC links, the INBOUND NOINBOUND field only controls the normal (not directed routing) transactions. Directed routing transactions are always validated. The selection of INBOUND or NOINBOUND does not affect the validation of secondary transactions initiated by transactions from a network link. These secondary transactions are validated as usual. The selection of INBOUND or NOINBOUND does not affect the processing of commands initiated by transactions from a network link using the ICMD communications call. The IMS interface always validates these commands. You might specify NOINBOUND when: An ISC link is used to enter IMS transactions from a CICS system. The transactions can be secured in the CICS system, and another validation is unnecessary. An MSC link connects two secured IMS systems. The transactions are validated in the sending system, and another validation in the receiving system is unnecessary. Chapter 10: MSC and ISC Link Security 129

Extended IMS Interface Security for MSC and ISC Links INHERIT NOINHERIT Controls whether resource access is validated using the logonid of the user in the originating system. This field is used only if the TYPE field is MSC. If INHERIT is specified, the logonid from the originating system is used for the validation; if NOINHERIT is specified, the originating logonid is ignored and the link default logonid (if there) or the control region default logonid is used. If you specify INHERIT, the logonid from the originating system must be defined in the CA ACF2 Logonid database for the receiving system. If the originating logonid is not defined in the receiving system, you receive an error message and the validation uses the link default logonid (if there) or the control region default logonid. FORCSIGN NOFORCSIGN Specifies whether sign-on is forced in the sending system. This field is used only if the TYPE field is MSC and INHERIT is specified. The default is NOFORCSIGN. Under normal IMS processing, if the user in the originating system is not signed on, the logonid sent with the transaction is set to the LTERM name. The receiving system can compare the logonid and the LTERM for the transaction. If they are the same, the originating user was not signed on. However, if the logonid of the signed-on user and the LTERM name are the same, it is difficult for the receiving system to determine if the user was signed on or not. FORCSIGN indicates that the terminal user was forced to sign on in the originating system. If you specify FORCSIGN, the logonid sent with the transaction is used for the validation. If you specify NOFORCSIGN and the logonid and LTERM for the transaction are the same, the IMS interface assumes that the terminal user was not signed on and validates the transaction using the link default logonid (if there) or the control region default logonid. 130 IMS Support Guide

Extended IMS Interface Security for MSC and ISC Links DEPTH(10 nnnnn) Controls how much storage this process uses. When an IMS system receives the first transaction from an MSC link that inherits the logonid, the IMS interface signs on the logonid to the link. When another transaction is received with a different logonid, that logonid is also signed on to the link. This process occurs for any new logonid received on the link. Specify the maximum number of logonids that can be concurrently signed on to the link. If you specify DEPTH(10), when ten logonids are signed on to the new link and a transaction with a new logonid is received, the oldest logonid on the link queue is signed off and the new logonid is signed on. When you specify the value for the DEPTH field, carefully weigh performance against storage. If you specify a low value, less storage is used, but the IMS interface can perform a higher number of sign-ons, each having the performance impact of a regular terminal sign-on. If you specify a high value, the IMS interface does not need to do extra sign-offs and sign-ons, but storage is used for each logonid. This field is used only when the TYPE field value is MSC and INHERIT is specified. The possible values are 1 to 32767. TIMEOUT Specifies the number of minutes that a set of user control blocks in the link logonid cache is valid. This field is only meaningful for network links that inherit the userid. After the timeout number of minutes has elapsed for a set of user control blocks, the control blocks are considered obsolete and are re-created for new requests. If TIMEOUT is not specified for a NETWORK record, the default is 0 (zero). If the timeout value for a link is zero, user control blocks are not timed out. If the user control blocks exist in the link logonid cache, they are used. SET C(IMS) SYSID(sysid) CHANGE NETWORK.suffix TIMEOUT(0 n) To display the current setting of this option, the /ACF SHOW STATE or /ACF SHOW LINK commands can be entered. Chapter 10: MSC and ISC Link Security 131

Chapter 11: LOCK and UNLOCK Command Resource Security The IMS LOCK command can be used to disable a terminal, stop the scheduling of a specific transaction, stop the scheduling of a specific program, or disable a database, making the IMS resource unavailable for processing. The UNLOCK command can be used to enable the IMS resource again, making it available for processing. To prevent unauthorized users from disabling IMS resources and affecting IMS processing, security must be provided for the resources specified on the LOCK and UNLOCK commands. In releases of IMS prior to IMS Release 9.1, IMS provided a mechanism using the IMS Security Maintenance Utility (SMU) to control who was allowed to lock and unlock specific IMS resources. In IMS Release 9.1 and above, the IMS interface can be used to directly protect the resources specified on the LOCK and UNLOCK commands. Note: This chapter only pertains to IMS regions running IMS Release 9.1 and higher. The IMS interface only provides security for resources specified on the LOCK and UNLOCK command in IMS regions running IMS Release 9.1 or higher. This section contains the following topics: Design Concepts and Features (see page 134) Transactions on the LOCK and UNLOCK commands (see page 134) Programs on the LOCK and UNLOCK commands (see page 136) Databases on the LOCK and UNLOCK commands (see page 137) LTERMs on the LOCK and UNLOCK commands (see page 139) Chapter 11: LOCK and UNLOCK Command Resource Security 133

Design Concepts and Features Design Concepts and Features In releases of IMS prior to IMS Release 9.1, IMS provided a mechanism using the IMS Security Maintenance Utility (SMU) to control who was allowed to lock and unlock specific IMS resources. In the SMU definitions, passwords could be assigned to specific terminals, transactions, programs, and databases. When a LOCK or UNLOCK command was issued for a resource that had an assigned password, the corresponding password was required on the request before the request would be processed. In IMS Release 9.1 and above, the IMS interface can be used to directly protect the resources specified on the LOCK and UNLOCK commands. For each kind of resource (terminals, transactions, programs, and databases) that can be specified on a LOCK or UNLOCK command, a corresponding IMS RESOURCE record controls whether the IMS interface will perform a security validation and what resource type code will be used. The IMS RESOURCE record that controls each resource type is explained in the following sections. Transactions on the LOCK and UNLOCK commands You control the validation processing for transactions specified on the LOCK and UNLOCK commands by defining security options in an IMS RESOURCE record. The IMS interface provides security for these transactions by default. If it does not find an IMS RESOURCE record for these transactions, all transactions specified on the LOCK and UNLOCK commands are validated with the default resource rule type code, ILT. 134 IMS Support Guide

Transactions on the LOCK and UNLOCK commands Defining the IMS RESOURCE Record To define validation for transactions on the LOCK and UNLOCK commands, create an IMS RESOURCE record with $LOCKTRN for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for these transactions, specify the NOVALIDATE keyword. To create an IMS RESOURCE record for transactions on the LOCK and UNLOCK commands, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($LOCKTRN) TYPE(ILT type) VALIDATE NOVALIDATE If you decide not to use the default type code (ILT), ensure that the type code you define for this option is the type code used in the corresponding transaction resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Writing the Resource Rules The IMS interface uses resource rules to validate access to transactions on the LOCK and UNLOCK commands. To learn how to write resource rules, see your Administrator Guide. The following shows an example of a resource rule for these transactions: $KEY(IAR****) TYPE(ILT) UID(APM) ALLOW SHIFT(NORMAL) UID(IMSDFLT) ALLOW SOURCE(VT001) IAR**** Represents the transaction name. The asterisks indicate masking. Thus, IAR**** defines all seven-character transaction names that begin with the letters IAR, such as Inquiry Accounts Receivable transactions. ILT (IMS transactions) The CA ACF2 default type code for IMS transactions on the LOCK and UNLOCK commands. UID(APM) ALLOW SHIFT(NORMAL) All managers from the AP department can LOCK and UNLOCK these transactions during the company's normal working hours. Chapter 11: LOCK and UNLOCK Command Resource Security 135

Programs on the LOCK and UNLOCK commands UID(IMSDFLT) ALLOW SOURCE(VT001) The default logonid can LOCK and UNLOCK these transactions when the command is entered from the terminal VT001. Programs on the LOCK and UNLOCK commands You control the validation processing for programs specified on the LOCK and UNLOCK commands by defining security options in an IMS RESOURCE record. The IMS interface provides security for these programs by default. If it does not find an IMS RESOURCE record for these programs, all programs specified on the LOCK and UNLOCK commands are validated with the default resource rule type code, ILP. Defining the IMS RESOURCE Record To define validation for programs on the LOCK and UNLOCK commands, create an IMS RESOURCE record with $LOCKPGM for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for these programs, specify the NOVALIDATE keyword. To create an IMS RESOURCE record for programs on the LOCK and UNLOCK commands, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($LOCKPGM) TYPE(ILP type) VALIDATE NOVALIDATE If you decide not to use the default type code (ILP), ensure that the type code you define for this option is the type code used in the corresponding program resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. 136 IMS Support Guide

Databases on the LOCK and UNLOCK commands Writing the Resource Rules The IMS interface uses resource rules to validate access to programs on the LOCK and UNLOCK commands. To learn how to write resource rules, see your Administrator Guide. The following shows an example of a resource rule for these programs: $KEY(IAR****) TYPE(ILP) UID(APM) ALLOW SHIFT(NORMAL) UID(IMSDFLT) ALLOW SOURCE(VT001) IAR**** Represents the program name. The asterisks indicate masking. Thus, IAR**** defines all seven-character program names that begin with the letters IAR, such as Inquiry Accounts Receivable programs. ILP (IMS programs) The CA ACF2 default type code for IMS programs on the LOCK and UNLOCK commands. UID(APM) ALLOW SHIFT(NORMAL) All managers from the AP department can LOCK and UNLOCK these programs during the company's normal working hours. UID(IMSDFLT) ALLOW SOURCE(VT001) The default logonid can LOCK and UNLOCK these programs when the command is entered from the terminal VT001. Databases on the LOCK and UNLOCK commands You control the validation processing for databases specified on the LOCK and UNLOCK commands by defining security options in an IMS RESOURCE record. The IMS interface provides security for these databases by default. If it does not find an IMS RESOURCE record for these databases, all databases specified on the LOCK and UNLOCK commands are validated with the default resource rule type code, ILD. Defining the IMS RESOURCE Record To define validation for databases on the LOCK and UNLOCK commands, create an IMS RESOURCE record with $LOCKDB for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for these databases, specify the NOVALIDATE keyword. Chapter 11: LOCK and UNLOCK Command Resource Security 137

Databases on the LOCK and UNLOCK commands To create an IMS RESOURCE record for databases on the LOCK and UNLOCK commands, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($LOCKDB) TYPE(ILD type) VALIDATE NOVALIDATE If you decide not to use the default type code (ILD), ensure that the type code you define for this option is the type code used in the corresponding database resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Writing the Resource Rules The IMS interface uses resource rules to validate access to databases on the LOCK and UNLOCK commands. To learn how to write resource rules, see your Administrator Guide. The following shows an example of a resource rule for these databases: $KEY(IAR****) TYPE(ILD) UID(APM) ALLOW SHIFT(NORMAL) UID(IMSDFLT) ALLOW SOURCE(VT001) IAR**** Represents the database name. The asterisks indicate masking. Thus, IAR**** defines all seven-character database names that begin with the letters IAR, such as Inquiry Accounts Receivable databases. ILD (IMS databases) The CA ACF2 default type code for IMS databases on the LOCK and UNLOCK commands. UID(APM) ALLOW SHIFT(NORMAL) All managers from the AP department can LOCK and UNLOCK these databases during the company's normal working hours. UID(IMSDFLT) ALLOW SOURCE(VT001) The default logonid can LOCK and UNLOCK these databases when the command is entered from the terminal VT001. 138 IMS Support Guide

LTERMs on the LOCK and UNLOCK commands LTERMs on the LOCK and UNLOCK commands You control the validation processing for LTERMs specified on the LOCK and UNLOCK commands by defining security options in an IMS RESOURCE record. The IMS interface provides security for these LTERMs by default. If it does not find an IMS RESOURCE record for these LTERMs, all LTERMs specified on the LOCK and UNLOCK commands are validated with the default resource rule type code, ILL. Defining the IMS RESOURCE Record To define validation for LTERMs on the LOCK and UNLOCK commands, create an IMS RESOURCE record with $LOCKTRM for the NAME field, a resource rule type code for the TYPE field, and the VALIDATE keyword. To deactivate validation processing for these LTERMs, specify the NOVALIDATE keyword. To create an IMS RESOURCE record for LTERMs on the LOCK and UNLOCK commands, enter the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($LOCKTRM) TYPE(ILL type) VALIDATE NOVALIDATE If you decide not to use the default type code (ILL), ensure that the type code you define for this option is the type code used in the corresponding LTERM resource rules. If you need more than one RESOURCE record, you can append a qualifier to the record name in the format RESOURCEqualifier to generate a unique record ID (for example, RESOURCE001 or RESOURCE.ABC). This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. Writing the Resource Rules The IMS interface uses resource rules to validate access to LTERMs on the LOCK and UNLOCK commands. To learn how to write resource rules, see your Administrator Guide. The following shows an example of a resource rule for these LTERMs: $KEY(IAR****) TYPE(ILL) UID(APM) ALLOW SHIFT(NORMAL) UID(IMSDFLT) ALLOW SOURCE(VT001) IAR**** Represents the LTERM name. The asterisks indicate masking. Thus, IAR**** defines all seven-character LTERM names that begin with the letters IAR, such as Inquiry Accounts Receivable LTERMs. Chapter 11: LOCK and UNLOCK Command Resource Security 139

LTERMs on the LOCK and UNLOCK commands ILL (IMS LTERMs) The CA ACF2 default type code for IMS LTERMs on the LOCK and UNLOCK commands. UID(APM) ALLOW SHIFT(NORMAL) All managers from the AP department can LOCK and UNLOCK these LTERMs during the company's normal working hours. UID(IMSDFLT) ALLOW SOURCE(VT001) The default logonid can LOCK and UNLOCK these LTERMs when the command is entered from the terminal VT001. 140 IMS Support Guide

Chapter 12: APPC Security This chapter describes the steps required to implement security for IMS commands and transactions entered through an APPC (Advanced Program-to-Program Communication) session. The intent of this chapter is not to describe APPC processing in general, but to describe APPC security processing in the IMS environment. Options and instructions for implementing APPC in a z/os environment are provided in the Administrator Guide. Before using APPC security in IMS, you should understand the documentation provided by the IBM Planning: APPC Management Guide and the CA ACF2 documentation. There are two facilities that can be used, separately or together, to provide security for IMS commands and transactions entered from an APPC session. The first facility is the CA ACF2 IMS interface security for APPC sessions, implemented using the IMS NETWORK record. The second facility is a SAF interface for APPC/IMS, where IMS will issue SAF security calls to request security services directly from CA ACF2. The IMS interface is not involved in this process. These facilities are explained in more detail in this chapter. We strongly recommend using the CA ACF2 IMS NETWORK record for APPC to implement the IMS interface security for the IMS APPC environment. This recommendation is explained in more detail in the Choosing Your APPC Security Implementation section in this chapter. This section contains the following topics: Design Concepts and Features (see page 141) Security processing during APPC session establishment (see page 142) IMS Interface Network Security for APPC (see page 143) SAF Security for APPC/IMS (see page 145) Choosing Your APPC Security Implementation (see page 148) DFSAPPC (see page 152) Design Concepts and Features This section describes the CA ACF2 and the IMS interface design components that apply to the topics discussed in this chapter. Chapter 12: APPC Security 141

. Security processing during APPC session establishment APPC Processing APPC is a facility that lets a user enter a transaction at a LU 6.2 device or system and have it communicate with another LU 6.2 device or system. This allows systems and networks to share work, data, and services. With APPC, transactions on a z/os system can initiate or allocate conversations with other transactions on different systems throughout an SNA network. System Authorization Facility (SAF) The System Authorization Facility (SAF) is a generalized security interface that directs all calls for security validation to the external security product in use. When a system resource or product requests the services of an external security product, SAF directs the call to CA ACF2, which handles the security event. Program-to-Program (PTP) Message Switching The program-to-program (PTP) message switching facility enables an IMS application program to send a message (transaction or command) to another IMS application program. In the case of APPC transactions that initiate other transactions, the IMS interface validates any secondary transaction initiated by the transaction. Security processing during APPC session establishment When an LU 6.2 device or program establishes an APPC session, it communicates first with the APPC system address space in your z/os system. APPC validates the user's logonid and password, and the user's ability to establish an APPC session with the IMS region. When the LU 6.2 device or program allocates the APPC conversation, it specifies the level of security used during the APPC conversation. If it specifies NONE for the security specification, the CA ACF2 batch default logonid is used throughout the conversation. If it specifies SAME, the logonid of the user making the request is used. APPC accepts the user's identity without performing validation. If PROGRAM is specified, APPC performs validation against a supplied logonid and profile record name. Then, APPC determines whether the transaction is sent to the APPC/IMS component in the control region or the message region, depending on the IMS program definition in the APPC TP profile entries For more information about the options available for APPC/MVS, see the CA ACF2nko documentation. 142 IMS Support Guide

IMS Interface Network Security for APPC IMS Interface Network Security for APPC You can implement security for commands and transactions entered from an APPC session with security options specified in an IMS NETWORK record. If the IMS interface finds a NETWORK record with a fully masked link name and a link type of APPC, the options on that record control the IMS interface security processing for commands and transactions from APPC sessions. The NETWORK record options for the APPC NETWORK record are explained in the next section. IMS NETWORK Records The IMS interface security for APPC is implemented by defining security options in an IMS NETWORK record. This record controls the security for all APPC sessions with the IMS control region. LINKNAME(linkname) In conjunction with the TYPE filed, this field defines the IMS links that are controlled by this record. For the APPC NETWORK record, the value for the LINKNAME field must be fully masked, for example, LINKNAME(********). TYPE(APPC) In conjunction with the LINKNAME field, this field defines which IMS links are controlled by this record. For the APPC NETWORK record, the value for TYPE must be APPC. The default is MSC. DFTLID(linkdefaultlogonid) This field is optional. It can be used to specify a special default logonid to be used for APPC sessions that do not inherit the logonid of the APPC session. INBOUND NOINBOUND This field controls whether commands and transactions received from APPC sessions are validated. If INBOUND is specified, the commands and transactions received from APPC sessions are validated; if NOINBOUND is specified, they are not validated. The default is INBOUND. The selection of INBOUND or NOINBOUND does not affect the validation of secondary transactions initiated by transactions from APPC sessions. These secondary transactions are validated as usual. The selection of INBOUND or NOINBOUND does not affect the processing of AOI commands initiated by transactions from APPC sessions. The IMS interface always validates these commands. You might specify NOINBOUND when you are using the APPC/IMS SAF facility to provide security for transactions and commands from APPC sessions. Chapter 12: APPC Security 143

IMS Interface Network Security for APPC INHERIT NOINHERIT This field controls whether resource access is validated using the logonid of the APPC session. If INHERIT is specified, the logonid of the APPC session is used for the validation; if NOINHERIT is specified, the originating logonid is ignored and the link default logonid (if there) or the control region default logonid is used. FORCSIGN FORCSIGN This field is not used for APPC NETWORK records. DEPTH(10 nnnnn) This field is used only when the TYPE field value is MSC, APPC, or OTMA, and INHERIT is specified. The possible values are 1 to 32767. When an IMS system receives the first command or transaction from an APPC session that inherits the logonid, the IMS interface signs on the logonid to the APPC link. When a request is received from another APPC session with a different logonid, that logonid is also signed on to the link. This process occurs for any new logonid received for an APPC session. Use the DEPTH field to control how much storage this process uses. Specify the maximum number of logonids that can be concurrently signed on to the APPC link. If you specify DEPTH(10), when ten logonids are signed on to the APPC link and a transaction or command is received with a new logonid, the oldest logonid on the APPC queue is signed off and the new logonid is signed on. When you specify the value for the DEPTH field, carefully weigh performance against storage. If you specify a low value, less storage is used, but the IMS interface can perform a higher number of sign-ons, each having the performance impact of a regular terminal sign-on. If you specify a high value, the IMS interface does not need to do extra sign-offs and sign-ons, but storage is used for each logonid. TIMEOUT This field is only meaningful for network links that inherit the userid. The value specified for this field is the number of minutes that a set of user control blocks in the link logonid cache is valid. After the timeout number of minutes has elapsed for a set of user control blocks, the control blocks are considered obsolete and are re-created for new requests. If TIMEOUT is not specified for a NETWORK record, the default is 0 (zero). If the timeout value for a link is zero, user control blocks are not timed out. If the user control blocks exist in the link logonid cache, they are used. SET C(IMS) SYSID(sysid) CHANGE NETWORK.suffix TIMEOUT(0 n) To display the current setting of this option, the /ACF SHOW STATE or /ACF SHOW LINK commands can be entered. 144 IMS Support Guide

SAF Security for APPC/IMS SAF Security for APPC/IMS APPC/IMS provides a SAF security interface that can be used to provide security for IMS commands and transactions entered through an APPC session. Requesting APPC/IMS SAF security The APPC/IMS SAF interface is controlled in one of two ways. The first is an IMS execution parameter, APPCSE, that can have the value F (for FULL), C (for CHECK), P (for PROFILE), or N (for NONE). The second control, which can override the APPCSE specification, is the IMS /SECURE command with the syntax /SECURE APPC xxxx, where xxxx can have the value FULL, CHECK, PROFILE, or NONE. If neither of these control options is used, the APPC/IMS security defaults to FULL. The APPC/IMS security setting determines the level of SAF security (that is, the number of SAF calls) provided in the IMS regions for APPC conversations. If APPC/IMS security is set to NONE, APPC/IMS issues no SAF calls and provides no security for commands and transactions from APPC sessions. If APPC/IMS security is set to CHECK, APPC/IMS will issue a SAF VERIFY request without password checking to create the user's security environment in IMS, and a FASTAUTH request to verify the user's access to the command or transaction. If APPC/IMS security is set to FULL, when the APPC transaction is scheduled in the message region, an additional VERIFY request is performed to re-create the user's security environment in the message region. The APPC/IMS SAF interface does not provide security when an APPC transaction initiates other transactions or enters commands using the ICMD call. The IMS interface validates these secondary transactions and commands. Implementing APPC/IMS SAF Security Perform the following steps to implement APPC/IMS SAF security for transactions or commands entered from a LU 6.2 session. Step 1: Update GSO CLASMAP Record CA ACF2 uses the GSO CLASMAP record during SAF resource validation. The CLASMAP record translates the SAF resource class into the CA ACF2 resource type code used in resource rules. The CLASMAP record is optional if you want to use the default type code of SAF. SAF resource classes depend on the type of resource accessed. APPC transactions use a SAF resource class of TIMS. Commands use a SAF resource class of CIMS. You can translate these resource classes into a three-character type code of your choice. Chapter 12: APPC Security 145

SAF Security for APPC/IMS The following example shows how to update an existing CLASMAP record for the transaction and command resources. This example uses a type code of ITR for transactions and ICM for commands. acf ACF set control(gso) CONTROL change clasmap.qual1 resource(tims) rsrctype(itr) musid(imsprod) CPU1 / CLASMAP.QUAL1 LAST CHANGED BY USER01 ON 06/30/02-13:12 ENTITYLN(0) MUSID(IMSPROD) RESOURCE(TIMS) RSRCT TYPE(ITR) CONTROL change clasmap.qual2 resource(cims) rsrctype(icm) musid(imsprod) CPU1 / CLASMAP.QUAL2 LAST CHANGED BY USER01 ON 06/30/02-13:14 ENTITYLN(0) MUSID(IMSPROD) RESOURCE(CIMS) RSRCT TYPE(ICM) CONTROL You can let different MUSASSes use different resource classes or share the same resource class by using the MUSID field. The MUSID field specifies the MUSASS to which this CLASMAP record applies. 146 IMS Support Guide

SAF Security for APPC/IMS Step 2: Make the Directory and Rules Resident To perform a FASTAUTH call, the directory and rules for the type code associated with the SAF resource classes of CIMS or TIMS must be locally resident in the IMS control region address space or globally resident in common system storage. If they are not resident, CA ACF2 will deny the request. To make the directory and rules locally resident, use the IMS RESOURCE record. At installation time, you define an IMS RESOURCE record for each type of resource being validated. The IMS interface makes any rule sets and directory associated with each resource type locally resident when IMS is started. To create a RESOURCE record for the command resource, here are the ACF subcommands: acf ACF set c(ims) CONTROL insert resource name($command) type(icm) validate This example assumes the GSO CLASMAP record associates the CIMS SAF resource class with the default ICM type code. To make the directory and rules globally resident, use the GSO INFODIR record. The GSO INFODIR record lets you make directories globally resident and their associated rule sets locally or globally resident. Add the resource type codes you referenced in the CLASMAP record for the CIMS and TIMS resource classes to the ACF2 GSO INFODIR record. Here are the ACF subcommands to add the ITR and ICM type codes to the GSO INFODIR record: acf ACF set control(gso) GSO Step 3: Write Resource Rules change infodir types(r-ritr,r-ricm) add This example uses r-ritr,r-ricm for the TYPES field value. This indicates that resource rules of types ITR and ICM are globally resident. If you have not already created them, write resource rules to protect the IMS transaction or command issued. For information about writing transaction and command resource rules, see the Transaction Security and IMS Command Security. Chapter 12: APPC Security 147

Choosing Your APPC Security Implementation Step 4: Refresh the GSO Records For CA ACF2 to process the GSO records you have just created or updated, you must refresh the GSO records. Here are the commands F ACF2,REFRESH(CLASMAP),SYSID(sysid),CLASS(C),TYPE(GSO) Step 5: Enable APPC/IMS SAF Security F ACF2,REFRESH(INFODIR),SYSID(sysid),CLASS(C),TYPE(GSO) Use the APPCSE execution parameter or the IMS /SECURE command to enable APPC/IMS SAF security for commands or transactions entered from APPC sessions. Choosing Your APPC Security Implementation The two security options, the IMS interface NETWORK security and APPC/IMS SAF security, can be used separately or together to provide the security for IMS commands and transactions entered in an APPC session. Choosing the correct implementation for your site requires an understanding of the requirements of your APPC implementation. 148 IMS Support Guide

Choosing Your APPC Security Implementation Using IMS Interface NETWORK Security without APPC/IMS SAF This is the implementation you should use for securing your IMS resources in an APPC environment, unless you have an application-based need for the user's security environment to be built in the IMS dependent region. This implementation provides complete security for the IMS APPC environment and the best performance. To implement this option, you must: 1. Specify APPCSE=N (APPC/IMS SAF security set to NONE) in the IMS execution parameters. 2. Specify the IMS interface NETWORK record for APPC described earlier in this chapter, with the INBOUND NOINBOUND parameter set to INBOUND. With this implementation, APPC/IMS will issue no SAF calls during the APPC/IMS security process. When a command or transaction is first received from an APPC session, the IMS interface issues a request to CA ACF2 to create the user's security environment. For any command or transaction received from this APPC user, the IMS interface locates the user's security environment and issues a resource validation. If a transaction from the APPC session creates secondary transactions or issues AOI commands, the IMS interface locates the user's security environment and issues the resource validation. The IMS interface will keep the security environment for the APPC user until the total number of APPC users exceeds the DEPTH value specified on the APPC NETWORK record. Then, the IMS interface locates the oldest, currently inactive APPC user and deletes the user's security environment, before processing requests from a new APPC user. This implementation has the following advantages: 1. The security environment for the APPC user is created once, and is used for all security processing for the user. 2. Because the IMS interface performs all resource validations, the IMS interface resource cache can be used to optimize performance. 3. Because the IMS interface performs all resource validations, the IMS interface exits can be used if customization of the security process is needed. 4. The IMS operator cannot bypass APPC security processing using the APPCSE parameter or the /SECURE APPC command. Chapter 12: APPC Security 149

Choosing Your APPC Security Implementation Using APPC/IMS SAF and IMS Interface NETWORK Security This implementation should be used if you have an application-based need for the user's security environment to be built in the IMS dependent region (APPCSE=F or /SECURE APPC FULL). To implement this option, you must: 1. Specify APPCSE=F (APPC/IMS SAF security set to FULL) in the IMS execution parameters 2. Specify the IMS interface NETWORK record for APPC described earlier in this chapter, with the INBOUND NOINBOUND parameter set to NOINBOUND. With this implementation, when an APPC session is created for the IMS region, APPC/IMS issues a SAF request to CA ACF2 to create the user's security environment. For any command or transaction received from the APPC session, APPC/IMS issues a FASTAUTH request to CA ACF2 to check the resource access. The IMS interface receives control for these commands and transactions, but because of the NOINBOUND parameter on the APPC NETWORK record, it will not perform a resource validation. When a transaction from the APPC session is scheduled to run in an IMS dependent region, APPC/IMS issues another SAF request to CA ACF2 to create the user's security environment in the dependent region. The user's security environment can then be used for application-based security processing. If a transaction from the APPC session creates secondary transactions or issues AOI commands, the IMS interface performs the resource validations. The IMS interface has no access to the user security environment created by APPC/IMS, and maintains its own cache of user security environments for APPC users. Before performing the resource validation, it searches this cache of APPC users to see if it already has the security environment for the user. If it does, it issues the resource validation using the user security environment. If the user security environment is not currently in the IMS interface APPC user cache, the IMS interface issues a request to CA ACF2 to create the user's security environment, adds it to the cache, and performs the resource validation. The IMS interface will keep the security environment for the APPC user until the total number of APPC users exceeds the DEPTH value specified on the APPC NETWORK record. Then, the IMS interface locates the oldest, currently inactive APPC user and deletes the user's security environment, before processing requests from a new APPC user. This implementation should only be used if you have an application-based need for the user's security environment to be built in the IMS dependent region. It has the following disadvantages: 1. The security environment for the APPC user is frequently created twice, once by APPC/IMS and later by the IMS interface. 150 IMS Support Guide

Choosing Your APPC Security Implementation 2. Because APPC/IMS performs validations for transactions and commands from the APPC session, the IMS interface resource cache is not used to optimize performance. 3. Because APPC/IMS performs validations for transactions and commands from the APPC session, the IMS interface exits cannot be used if customization of the security process is needed. 4. The IMS operator can alter or bypass APPC security processing using the APPCSE parameter or the /SECURE APPC command. Using APPC/IMS SAF without the IMS Interface NETWORK Security If you request APPC/IMS SAF security and do not create an IMS interface NETWORK record for APPC, this is the level of APPC security you will implement. This implementation provides complete security for the IMS APPC environment, but is not recommended for performance reasons. To implement this option, you must: 1. Specify APPCSE=F/C (APPC/IMS SAF security set to FULL or CHECK) in the IMS execution parameters 2. Not create an IMS interface NETWORK record for APPC. With this implementation, when an APPC session is created for the IMS region, APPC/IMS issues a SAF request to CA ACF2 to create the user's security environment. For any command or transaction received from the APPC session, APPC/IMS issues a FASTAUTH request to CA ACF2 to check the resource access. The IMS interface receives control for these commands and transactions, but because there is no APPC NETWORK record, it will not perform a resource validation. If a transaction from the APPC session creates secondary transactions or issues AOI commands using the ICMD call, the IMS interface performs the resource validations. The IMS interface has no access to the user security environment created by APPC/IMS. Because there is no APPC NETWORK record, it does not maintain its own cache of user security environments for APPC users. The IMS interface issues a request to CA ACF2 to create the user's security environment., performs the resource validation, and deletes the user security environment. This implementation has the following disadvantages: 1. The security environment for the APPC user is created by CA ACF2 IMS each time a resource validation is done for secondary transactions. 2. Because APPC/IMS performs validations for transactions and commands from the APPC session, the IMS interface resource cache is not used to optimize performance. Chapter 12: APPC Security 151

DFSAPPC 3. Because APPC/IMS performs validations for transactions and commands from the APPC session, the IMS interface exits cannot be used if customization of the security process is needed. 4. Because the IMS interface created the user security environment each time a resource validation is done for secondary transactions, its resource cache is not available to optimize performance. 5. The IMS operator can alter or bypass APPC security processing using the APPCSE parameter or the /SECURE APPC command. This implementation provides complete security for the IMS APPC environment, but is not recommended for performance reasons. Not Using APPC/IMS SAF or the IMS Interface NETWORK Security The option is implemented when you: 1. Specify APPCSE=N in the IMS execution parameters or issue the /SECURE APPC NONE command to set APPC/IMS SAF security to NONE 2. Do not create an IMS interface NETWORK record for APPC. Warning! You should never implement this option. With this implementation, there is no security for commands or transactions entered from an APPC session. DFSAPPC DFSAPPC is a system service that enables IMS to send messages to other LU 6.2 devices or to IMS-managed LTERMs. DFSAPPC generates SAF VERIFY calls for the user issuing the message. If the user is logged on to the terminal, CA ACF2 uses the user's logonid in the validation. If the user is not logged on to the terminal, the value of the LTERM is substituted for the logonid. If the LTERM value is not a valid logonid, CA ACF2 denies the request and does not send the message. To ensure that messages are sent, create a logonid for the value of the LTERM. 152 IMS Support Guide

Chapter 13: OTMA Security This chapter describes the steps required to implement security for IMS commands and transactions entered from IMS OTMA (Open Transaction Manager Access) clients. The intent of this chapter is not to describe OTMA processing in general, but to describe OTMA security processing in the IMS environment. Options and instructions for implementing OTMA in a z/os environment are provided in the Cookbook. Before using OTMA security in IMS, you should understand the documentation provided by the IBM Open Transaction Manager Access Guide and Reference and the CA ACF2 documentation. There are two facilities that can be used, separately or together, to provide security for IMS commands and transactions entered from OTMA clients. The first facility is the CA ACF2 IMS interface security for OTMA, implemented using the IMS NETWORK record. The second facility is a SAF interface for IMS OTMA, where IMS will issue SAF security calls to request security services directly from CA ACF2. The IMS interface is not involved in this process. These facilities are explained in more detail in this chapter. We strongly recommend using the IMS interface NETWORK record for OTMA to implement the IMS interface security for the IMS OTMA environment. This recommendation is explained in more detail in the Choosing Your OTMA Security Implementation section in this chapter. This section contains the following topics: Design Concepts and Features (see page 153) IMS Interface Network Security for OTMA (see page 154) SAF Security for IMS OTMA (see page 156) Choosing Your OTMA Security Implementation (see page 160) Design Concepts and Features This section describes the CA ACF2 and the IMS interface design components that apply to the topics discussed in this chapter. Chapter 13: OTMA Security 153

IMS Interface Network Security for OTMA OTMA Processing Open Transaction Manager Access (OTMA) is a transaction-based, client/server protocol. As it is implemented in IMS, z/os, OTMA enables z/os application clients to submit commands and transactions to an IMS server and receive the output returned from IMS using the z/os Cross-System Coupling Facility (XCF). The OTMA client application places the IMS command or transaction input into the Coupling Facility. IMS picks up the command or transaction from the Coupling Facility and processes it. Responses are returned to the Coupling Facility, where they are retrieved by the client application and processed. System Authorization Facility (SAF) The System Authorization Facility (SAF) is a generalized security interface that directs all calls for security validation to the external security product in use. When a system resource or product requests the services of an external security product, SAF directs the call to CA ACF2, which handles the security event. Program-to-Program (PTP) Message Switching The program-to-program (PTP) message switching facility enables an IMS application program to send a message (transaction or command) to another IMS application program. In the case of OTMA transactions that initiate other transactions, the IMS interface validates any secondary transaction initiated by the transaction. IMS Interface Network Security for OTMA You can implement security for commands and transactions entered from OTMA clients with security options specified in an IMS interface NETWORK record. If the IMS interface finds a NETWORK record with a fully masked link name and a link type of OTMA, the options on that record control the IMS interface security processing for commands and transactions from OTMA clients. The NETWORK record options for the OTMA NETWORK record are explained in the next section. 154 IMS Support Guide

IMS Interface Network Security for OTMA IMS NETWORK Records The IMS interface security for OTMA is implemented by defining security options in an IMS NETWORK record. This record controls the security for all OTMA client requests processed in the IMS control region. LINKNAME(linkname) In conjunction with the TYPE field, this field defines the IMS links that are controlled by this record. For the OTMA NETWORK record, the value for the LINKNAME field must be fully masked, i.e. LINKNAME(********). TYPE(OTMA) DFTLID In conjunction with the LINKNAME field, this field defines which IMS links are controlled by this record. For the OTMA NETWORK record, the value for TYPE must be OTMA. The default is MSC. This field is optional. It can be used to specify a special default logonid to be used when the logonid of the OTMA client is not inherited. INBOUND NOINBOUND This field controls whether commands and transactions received from OTMA clients are validated. If INBOUND is specified, the commands and transactions received from OTMA are validated; if NOINBOUND is specified, they are not validated. The default is INBOUND. The selection of INBOUND or NOINBOUND does not affect the validation of secondary transactions initiated by transactions from OTMA clients. These secondary transactions are validated as usual. The selection of INBOUND or NOINBOUND does not affect the processing of AOI commands initiated by transactions from OTMA clients. The IMS interface always validates these commands. You might specify NOINBOUND when you are using the IMS OTMA SAF facility to provide security for transactions and commands from OTMA clients. INHERIT NOINHERIT This field controls whether resource access is validated using the logonid specified for the OTMA client. If INHERIT is specified, the logonid of the OTMA client is used for the validation; if NOINHERIT is specified, the OTMA logonid is ignored and the link default logonid (if there) or the control region default logonid is used. FORCSIGN NOFORCSIGN This field is not used for OTMA NETWORK records. Chapter 13: OTMA Security 155

SAF Security for IMS OTMA DEPTH(10 nnnnn) This field is used only when the TYPE field value is MSC, APPC, or OTMA, and INHERIT is specified. The possible values are 1 to 32767. When an IMS system receives the first command or transaction from an OTMA client that inherits the logonid, the IMS interface signs on the logonid to the OTMA link. When a request is received from OTMA with a different logonid, that logonid is also signed on to the link. This process occurs for any new logonid received with an OTMA request. Use the DEPTH field to control how much storage this process uses. Specify the maximum number of logonids that can be concurrently signed on to the OTMA link. If you specify DEPTH(10), when ten logonids are signed on to the OTMA link and a transaction or command is received with a new logonid, the oldest logonid on the OTMA queue is signed off and the new logonid is signed on. When you specify the value for the DEPTH field, carefully weigh performance against storage. If you specify a low value, less storage is used, but the IMS interface can perform a higher number of sign-ons, each having the performance impact of a regular terminal sign-on. If you specify a high value, the IMS interface does not need to do extra sign-offs and sign-ons, but storage is used for each logonid. TIMEOUT This field is only meaningful for network links that inherit the userid. The value specified for this field is the number of minutes that a set of user control blocks in the link logonid cache is valid. After the timeout number of minutes has elapsed for a set of user control blocks, the control blocks are considered obsolete and are re-created for new requests. If TIMEOUT is not specified for a NETWORK record, the default is 0 (zero). If the timeout value for a link is zero, user control blocks are not timed out. If the user control blocks exist in the link logonid cache, they are used. SET C(IMS) SYSID(sysid) CHANGE NETWORK.suffix TIMEOUT(0 n) To display the current setting of this option, the /ACF SHOW STATE or /ACF SHOW LINK commands can be entered. SAF Security for IMS OTMA IMS provides a SAF security interface that can be used to provide security for IMS commands and transactions entered through the OTMA connection. 156 IMS Support Guide

SAF Security for IMS OTMA Requesting SAF security for IMS OTMA The IMS OTMA SAF interface is controlled in one of two ways. The first is an IMS execution parameter OTMASE, that can have the value F (for FULL), C (for CHECK), P (for PROFILE), or N (for NONE). The second control, which can override the OTMASE specification, is the IMS /SECURE command with the syntax /SECURE OTMA xxxx, where xxxx can have the value FULL, CHECK, PROFILE, or NONE. If neither of these control options is used, the IMS OTMA security defaults to FULL. The IMS OTMA security setting determines the level of SAF security (that is, the number of SAF calls) provided in the IMS regions for OTMA requests. If IMS OTMA security is set to NONE, IMS issues no SAF calls and provides no security for commands and transactions from OTMA clients. If IMS OTMA security is set to CHECK, IMS will issue a SAF VERIFY request without password checking to create the user's security environment in IMS, and a FASTAUTH request to verify the user's access to the command or transaction. If IMS OTMA security is set to FULL, when the OTMA transaction is scheduled in the message region, an additional VERIFY request is performed to re-create the user's security environment in the message region. The IMS OTMA SAF interface does not provide security when an OTMA transaction initiates other transactions or enters commands using the ICMD call. The IMS interface validates these secondary transactions and commands. Implementing IMS OTMA SAF Security Perform the following steps to implement IMS OTMA SAF security for transactions or commands entered from the OTMA connection. Chapter 13: OTMA Security 157

SAF Security for IMS OTMA Step 1: Update GSO CLASMAP Record CA ACF2 uses the GSO CLASMAP record during SAF resource validation. The CLASMAP record translates the SAF resource class into the CA ACF2 resource type code used in resource rules. The CLASMAP record is optional if you want to use the default type code of SAF. SAF resource classes depend on the type of resource accessed. OTMA transactions use a SAF resource class of TIMS. Commands use a SAF resource class of CIMS. You can translate these resource classes into a three-character type code of your choice. The following example shows how to update an existing CLASMAP record for the transaction and command resources. This example uses a type code of ITR for transactions and ICM for commands. acf ACF set control(gso) CONTROL change clasmap.qual1 resource(tims) rsrctype(itr) musid(imsprod) CPU1 / CLASMAP.QUAL1 LAST CHANGED BY USER01 ON 06/30/02-13:12 ENTITYLN(0) MUSID(IMSPROD) RESOURCE(TIMS) RSRCT TYPE(ITR) CONTROL change clasmap.qual2 resource(cims) rsrctype(icm) musid(imsprod) CPU1 / CLASMAP.QUAL2 LAST CHANGED BY USER01 ON 06/30/02-13:14 ENTITYLN(0) MUSID(IMSPROD) RESOURCE(CIMS) RSRCT TYPE(ICM) CONTROL You can let different MUSASSes use different resource classes or share the same resource class by using the MUSID field. The MUSID field specifies the MUSASS to which this CLASMAP record applies. Step 2: Make the Directory and Rules Resident To perform a FASTAUTH call, the directory and rules for the type code associated with the SAF resource classes of CIMS or TIMS must be locally resident in the IMS control region address space or globally resident in common system storage. If they are not resident, CA ACF2 will deny the request. To make the directory and rules locally resident, use the IMS RESOURCE record. At installation time, you define an IMS RESOURCE record for each type of resource being validated. The IMS interface makes any rule sets and directory associated with each resource type locally resident when IMS is started. 158 IMS Support Guide

SAF Security for IMS OTMA To create a RESOURCE record for the command resource, here are the ACF subcommands: acf ACF set c(ims) CONTROL insert resource name($command) type(icm) validate This example assumes the GSO CLASMAP record associates the CIMS SAF resource class with the default ICM type code. To make the directory and rules globally resident, use the GSO INFODIR record. The GSO INFODIR record lets you make directories globally resident and their associated rule sets locally or globally resident. Add the resource type codes you referenced in the CLASMAP record for the CIMS and TIMS resource classes to the ACF2 GSO INFODIR record. Here are the ACF subcommands to add the ITR and ICM type codes to the GSO INFODIR record: acf ACF set control(gso) GSO Step 3: Write Resource Rules Step 4: Refresh the GSO Records change infodir types(r-ritr,r-ricm) add This example uses r-ritr,r-ricm for the TYPES field value. This indicates that resource rules of types ITR and ICM are globally resident. If you have not already created them, write resource rules to protect the IMS transaction or command issued. See the chapters Transaction Security and IMS Command Security for information about writing transaction and command resource rules. For CA ACF2 to process the GSO records you have just created or updated, you must refresh the GSO records. Here are the commands F ACF2,REFRESH(CLASMAP),SYSID(sysid),CLASS(C),TYPE(GSO) Step 5: Enable IMS OTMA SAF Security F ACF2,REFRESH(INFODIR),SYSID(sysid),CLASS(C),TYPE(GSO) Use the OTMASE execution parameter or the IMS /SECURE command to enable IMS OTMA SAF security for commands or transactions entered from the OTMA connection. Chapter 13: OTMA Security 159

Choosing Your OTMA Security Implementation Choosing Your OTMA Security Implementation The two security options, the IMS interface NETWORK security and IMS OTMA SAF security, can be used separately or together to provide the security for IMS commands and transactions entered from the OTMA connection. Choosing the correct implementation for your site requires an understanding of the requirements of your OTMA implementation. Using IMS Interface NETWORK Security without IMS OTMA SAF This is the implementation you should use for securing your IMS resources in an OTMA environment, unless you have an application-based need for the user's security environment to be built in the IMS dependent region. This implementation provides complete security for the IMS OTMA environment and the best performance. To implement this option, you must: 1. Specify OTMASE=N (IMS OTMA SAF security set to NONE) in the IMS execution parameters. 2. Specify the IMS interface NETWORK record for OTMA described earlier in this chapter, with the INBOUND NOINBOUND parameter set to INBOUND With this implementation, IMS will issue no SAF calls during the IMS OTMA security process. When a command or transaction is first received from an OTMA client, the IMS interface issues a request to CA ACF2 to create the user's security environment. For any command or transaction received from this OTMA user, the IMS interface locates the user's security environment and issues a resource validation. If a transaction from the OTMA connection creates secondary transactions or issues AOI commands, the IMS interface locates the user's security environment and issues the resource validation. The IMS interface will keep the security environment for the OTMA user until the total number of OTMA users exceeds the DEPTH value specified on the OTMA NETWORK record. Then, the IMS interface locates the oldest, currently inactive OTMA user and deletes the user's security environment, before processing requests from a new OTMA user. This implementation has the following advantages: 1. The security environment for the OTMA user is created once, and is used for all security processing for the user. 2. Because the IMS interface performs all resource validations, its IMS resource cache can be used to optimize performance. 160 IMS Support Guide

Choosing Your OTMA Security Implementation 3. Because the IMS interface performs all resource validations, its exits can be used if customization of the security process is needed. 4. The IMS operator cannot bypass OTMA security processing using the OTMASE parameter or the /SECURE OTMA command. Using IMS OTMA SAF and the IMS Interface NETWORK Security This implementation should be used if you have an application-based need for the user's security environment to be built in the IMS dependent region. To implement this option, you must: 1. Specify OTMASE=F (IMS OTMA SAF security set to FULL) in the IMS execution parameters. 2. Specify the IMS interface NETWORK record for OTMA described earlier in this chapter, with the INBOUND NOINBOUND parameter set to NOINBOUND. With this implementation, when an OTMA request is received by the IMS region, IMS issues a SAF request to CA ACF2 to create the user's security environment. For any command or transaction received from the OTMA client, IMS issues a FASTAUTH request to CA ACF2 to check the resource access. The IMS interface receives control for these commands and transactions, but because of the NOINBOUND parameter on the OTMA NETWORK record, it will not perform a resource validation. When a transaction from the OTMA connection is scheduled to run in an IMS dependent region, IMS issues another SAF request to CA ACF2 to create the user's security environment in the dependent region. The user's security environment can then be used for application-based security processing. If a transaction from the OTMA connection creates secondary transactions or issues AOI commands, the IMS interface performs the resource validations. The IMS interface has no access to the user security environment created by IMS, and maintains its own cache of user security environments for OTMA users. Before performing the resource validation, the IMS interface searches this cache of OTMA users to see if it already has the security environment for the user. If it does, it issues the resource validation using the user security environment. If the user security environment is not currently in the IMS interface OTMA user cache, the IMS interface issues a request to CA ACF2 to create the user's security environment, adds it to the cache, and performs the resource validation. The IMS interface will keep the security environment for the OTMA user until the total number of OTMA users exceeds the DEPTH value specified on the OTMA NETWORK record. Then, the IMS interface locates the oldest, currently inactive OTMA user and deletes the user's security environment, before processing requests from a new OTMA user. Chapter 13: OTMA Security 161

Choosing Your OTMA Security Implementation This implementation should only be used if you have an application-based need for the user's security environment to be built in the IMS dependent region. It has the following disadvantages: 1. The security environment for the OTMA user is frequently created twice, once by IMS and later by the IMS interface. 2. Because IMS performs validations for transactions and commands from the OTMA connection, the IMS interface resource cache is not used to optimize performance. 3. Because IMS performs validations for transactions and commands from the OTMA connection, the IMS interface exits cannot be used if customization of the security process is needed. 4. The IMS operator can alter or bypass OTMA security processing using the OTMASE parameter or the /SECURE OTMA command. Using IMS OTMA SAF without the IMS Interface NETWORK Security If you request IMS OTMA SAF security and do not create an IMS interface NETWORK record for OTMA, this is the level of OTMA security you will implement. This implementation provides complete security for the IMS OTMA environment, but is not recommended for performance reasons. To implement this option, you must: 1. Specify OTMASE=F/C (IMS OTMA SAF security set to FULL or CHECK) in the IMS execution parameters. 2. Not create an IMS interface NETWORK record for OTMA. With this implementation, when an OTMA request is received by the IMS region, IMS issues a SAF request to CA ACF2 to create the user's security environment. For any command or transaction received from the OTMA client, IMS OTMA issues a FASTAUTH request to CA ACF2 to check the resource access. The IMS interface receives control for these commands and transactions, but because there is no OTMA NETWORK record, it will not perform a resource validation. If a transaction from the OTMA connection creates secondary transactions or issues AOI commands, the IMS interface performs the resource validations. The IMS interface has no access to the user security environment created by IMS. Because there is no OTMA NETWORK record, the IMS interface does not maintain its own cache of user security environments for OTMA users. The IMS interface issues a request to CA ACF2 to create the user's security environment, performs the resource validation, and deletes the user security environment. This implementation has the following disadvantages: 1. The security environment for the OTMA user is created by the IMS interface each time a resource validation is done for secondary transactions. 162 IMS Support Guide

Choosing Your OTMA Security Implementation 2. Because IMS performs validations for transactions and commands from the OTMA connection, the IMS interface resource cache is not used to optimize performance. 3. Because IMS performs validations for transactions and commands from the OTMA connection, the IMS interface exits cannot be used if customization of the security process is needed. 4. Because the IMS interface created the user security environment each time a resource validation is done for secondary transactions, the IMS interface resource cache is not available to optimize performance. 5. The IMS operator can alter or bypass OTMA security processing using the OTMASE parameter or the /SECURE OTMA command. This implementation provides complete security for the IMS OTMA environment, but is not recommended for performance reasons. Not Using IMS OTMA SAF or the IMS Interface NETWORK Security The option is implemented when you: 1. Specify OTMASE=N in the IMS execution parameters or issue the /SECURE OTMA NONE command to set IMS OTMA SAF security to NONE 2. Do not create an IMS interface NETWORK record for OTMA. Warning! You should never implement this option. With this implementation, there is no security for commands or transactions entered from an OTMA client. TPIPE Security for the RESUME TPIPE Request If you are using OTMA in an IMS environment with IMS Version 10 and above, you can protect messages on OTMA asynchronous hold queues from unauthorized use of the RESUME TPIPE request. If security is enabled for the TPIPE hold queues, the userid issuing a RESUME TPIPE request must be authorized to access the TPIPE name in the RESUME TPIPE request before any of the TPIPE messages are sent to the OTMA client. Chapter 13: OTMA Security 163

Choosing Your OTMA Security Implementation Defining the IMS RESOURCE Record To define validation for TPIPEs on the OTMA RESUME TPIPE request Create an IMS RESOURCE record with $TPIPE for the NAME field. Create a resource rule type code for the TYPE field and VALIDATE keyword. To deactivate validation processing Specify the NOVALIDATE keyword. To create an IMS RESOURCE record for TPIPEs on the OTMA RESUME TPIPE request Type the following INSERT subcommand statement: INSERT DIVISION(musid jobname) RESOURCE[.qualifier] NAME($TPIPE) TYPE(ITP type) VALIDATE NOVALIDATE Note: If you decide not to use the default type code (ITP), ensure that the type code you define for this option is the type code used in the corresponding TPIPE resource rules. If you need more than one RESOURCE record Append a qualifier to the record name in the format RESOURCEqualifier. Writing the Resource Rules This generates a unique record ID. For example, RESOURCE001 or RESOURCE.ABC. Note: This optional qualifier can be up to eight characters and must immediately follow RESOURCE. If you use a period as part of the qualifier string for the record name, the IMS interface counts it as one of the eight characters. The IMS interface uses resource rules to validate access to TPIPEs on the OTMA RESUME TPIPE requests. For more information on how to write resource rules, see the Administrator Guide. The following is an example of a resource rule for these TPIPEs: $KEY(AP******) TYPE(ITP) UID(APM) ALLOW SHIFT(NORMAL) 164 IMS Support Guide

Choosing Your OTMA Security Implementation AP****** Represents the TPIPE name. The asterisks indicate masking. Thus, AP****** defines all eight-character TPIPE names that begin with the letters AP, such as Accounts Payable TPIPEs. ITP (OTMA TPIPEs) The CA ACF2 default type code for IMS TPIPEs on the OTMA RESUME TPIPE requests. UID(APM) ALLOW SHIFT(NORMAL) All managers from the AP department can issue a RESUME TPIPE on these TPIPEs during the company's normal working hours. Chapter 13: OTMA Security 165

. Chapter 14: IMS Shared Queues and Security This chapter describes different alternatives available with the CA ACF2 IMS interface for optimizing the performance impact of security processing in an IMS shared queues environment. Note: It is not the intent of this chapter to describe the coupling facility or how to implement IMS shared queues. That information is provided in the IBM z/os and IMS documentation sets. This section contains the following topics: Overview (see page 167) Design Concepts (see page 168) Default Processing (see page 170) Design Features (see page 171) Overview In its simplest form, an IMS shared queues environment, or IMSplex, consists of several IMS regions that work together as if they were a single IMS system. The IMS regions share application data and the IMS message queue. A user can sign on to any of the IMS regions in the IMSplex and enter transactions. The transactions are placed in the shared message queue. Any IMS region in the IMSplex can read the transaction from the message queue and execute it. The transaction responses are placed back into the shared message queue. The IMS region where the user is signed on retrieves the messages and returns them to the user Shared queues have an impact on the IMS security process. When the user signs on to a IMS region, the control blocks that define the user's security environment are created in that region. If the user enters a transaction that executes in a different region, and it generates work that requires security processing, the security processing requires access to the user security environment. The original user security environment does not exist in the region where the transaction is executing. The region where the transaction is executing must recreate the user security environment in order to perform the security processing. This process of recreating the user security environment has a performance impact in the region where the security process is occurring. Chapter 14: IMS Shared Queues and Security 167

Design Concepts Design Concepts This section describes the CA ACF2 and IMS interface design components in an IMS shared queues environment. Shared Queues In an IMS shared queues environment, the IMS message queues that hold the IMS transactions and responses are in a structure in the z/os coupling facility. More than one IMS region share the message queue structure. All of these regions can put transactions and responses into the message queue and can take transactions out of the message queue to execute them. Collectively, these regions are called an IMSplex. Front-end Region In an IMS shared queues environment, the IMS region where a user is signed on is called the front-end region. The user's original security environment is created in the front-end region. Back-end Region In an IMS shared queues environment, if a user signs on to an IMS region, enters a transaction, and the transaction executes in a different region in the IMSplex, the region where the transaction executes is called the back-end region for the process. The user's original security environment does not exist in the back-end region and must be replicated for any security process in that region. Note: Because users can sign on to different regions in an IMSplex, the concept of a front-end and back-end region is relative to a user and the work that they initiate. For example, consider an IMSplex that consists of two regions, IMSA and IMSB. If a user signs on to IMSA and enters transactions that execute in IMSB, then IMSA is the front-end region for that user, and IMSB is the back-end region when the user's transactions execute there. If, at the same time, a second user signs on to IMSB and enters transactions that execute in IMSA, then IMSB is the front-end region for that user and IMSA is the back-end region when that user's transactions execute there. 168 IMS Support Guide

Design Concepts Program-to-Program Message Switching The program-to-program (PTP) message switching facility enables an IMS application program to send a message (transaction) to another IMS application program. A PTP message switch generates a new transaction, and causes a transaction validation to occur. When the PTP message switch occurs in an IMS back-end region, the original user's security environment must be recreated in the back-end region to perform the transaction validation. Automated Operator Interface Commands The automated operator interface (AOI) enables an IMS application program to issue an IMS command and to retrieve and process the command responses. This process causes a command validation to occur. When the AOI command is issued by the application in an IMS back-end region, the original user's security environment must be recreated in the back-end region to perform the command validation. AUTH Calls The AUTH call is an IMS security call available to IMS application programs that provides a way for sites to develop application-based security processing. An AUTH call causes a resource validation to occur. When the call is issued by an application in an IMS back-end region, the original user's security environment must be recreated in the back-end region to perform the resource validation. Chapter 14: IMS Shared Queues and Security 169

Default Processing Default Processing In its default processing, when a resource validation is performed in a back-end IMS region, the IMS interface calls CA ACF2 to read the security database and create the user security environment in the back-end region. These user control blocks are used for the resource validation, and then deleted. If a new resource validation is required for the same user, the IMS interface calls CA ACF2 to create the user security environment again, uses the new control blocks to perform the resource validation, and deletes the new control blocks. This process occurs for any resource validation performed in an IMS back-end region. This process has three characteristics that can have a negative effect on your environment: Each resource validation requires an interaction with CA ACF2 to create the user security environment. This adds the performance impact of an CA ACF2 SVC for signon and the associated I/O activity to the logonid and Infostorage databases. If a resource violation occurs in the back-end system, it is not communicated to the front-end region. It is an isolated violation, and does not count toward the maximum violation (MAXVIO) and user suspend processing in the front-end region. The resource violation count in the front-end system only reflects the violations that occur in that IMS region. Because violations can occur in other IMS regions, the maximum violation and user suspend processing becomes unreliable and difficult to predict. If the user is allowed access to the resource, it is not communicated to the front-end region. The resource validation cache in the front-end system only reflects the resources that have been allowed in that IMS region, and some of the performance advantages of using a validation cache are lost. Note the following: When an IMS user signs on to an region, the control blocks that define the user security environment are created in that region. When the user enters a transaction, the user's security environment is available and is used for the transaction validation. When the transaction executes, it can generate other work that requires security processing. For example it can:: Generate other transactions using a PTP message switch such as a CHNG call Issue IMS commands using the AOI command interface Request security services directly using the IMS AUTH call 170 IMS Support Guide

Design Features All of these requests require a security validation. When the transaction is executing in the front-end region, the original user security environment is available and can be used for the resource validation. However, when the transaction is executing in a back-end IMS region, the original user security environment is not available. The user security environment must be recreated in the back-end region before the resource validation can be performed. Design Features There are two design features of the CA ACF2 IMS interface for the IMS shared queues environment: IMS interface SYSPLEX feature Shared Queues (SQ) NETWORK record These features can be used, separately or together, to optimize the performance of security processing in an IMS shared queues environment. CA ACF2 IMS SYSPLEX Feature The CA ACF2 IMS SYSPLEX feature uses a structure in the coupling facility to maintain a copy of the user security environment. When a user signs on to an IMS region in a shared queues environment, the IMS interface creates a copy of the user security environment in the coupling facility structure. When security processing is required for the user, the user security environment is read from the coupling facility structure and used for the security process. The user security environment maintained in the SYSPLEX structure is a copy of the user cache area. The user cache area contains a copy of the ACMCB and MLID for the user, and the resource validation cache. For more information on the user cache area, see the chapter "Storage." For more information about MLID see the "Installation." For more information on the resource validation cache see the chapter "IMS Interface Philosophy." Because the user's resource violation count is in the ACMCB, and the resource validation cache is also in the SYSPLEX cache area, the SYSPLEX cache area is the repository for global information about the user session. It contains the total resource violation count for the user session, regardless of the IMSplex region in which the violation occurred. It also contains the resource validation cache of resources such as transactions and commands to which the user has been allowed access, regardless of the IMSplex region in which the access was allowed. Chapter 14: IMS Shared Queues and Security 171

Design Features This SYSPLEX cache area is used when any resource validation is required, in the front-end IMS or a back-end IMS region. 172 IMS Support Guide

Design Features SYSPLEX Feature Processing The CA ACF2 IMS SYSPLEX feature is controlled by an option in the IMS SYSPLEX record. If the SYSPLEX feature is active, the IMS interface will connect to the SYSPLEX structure during CA ACF2 IMS initialization. The first IMS region in the IMSplex to connect to the structure causes the structure to be created, and creates a control record in the structure describing the IMSplex and the contents of the structure. Subsequent IMS regions in the IMSplex connect to the structure, and verify from the control record that the structure is valid for their use. When a user signs on to an IMS region, a copy of the cache area for the user is written to the SYSPLEX structure. If the SYSPLEX structure becomes full, the SYSPLEX cache area for a user cannot be added to the structure when the user signs on. This does not impact the user session, and the user is not notified. When a resource validation is done for the user, in the IMS front-end region or a back-end region, the SYSPLEX cache area for the user is read from the SYSPLEX structure. This process obtains the current resource violation count and the current validation cache for the user session. This cache area is used for the validation process. If the user is not permitted access to the resource, the SYSPLEX cache area is read again and locked for update, the violation count is incremented, and the SYSPLEX cache area is written back to the SYSPLEX structure. If the user is permitted access to the resource and the resource is not already in the resource validation cache, the SYSPLEX cache area is read and locked for update, the new resource is added to the validation cache, and the SYSPLEX cache area is written back to the SYSPLEX structure. In some situations, the IMS interface might not be able to obtain the user SYSPLEX cache area from the SYSPLEX structure. For example, this can happen if: The user has already signed off in the front-end IMS region The SYSPLEX feature was not active in the front-end IMS region The SYSPLEX structure was full when the user signed on The SYSPLEX structure was cleared If the IMS interface cannot obtain the user SYSPLEX cache area, it simply reverts to the default process of asking CA ACF2 to recreate the user control blocks. When the user signs off the IMS region, the SYSPLEX cache area for the user session is deleted from the SYSPLEX structure. During IMS termination, the IMS interface disconnects from the SYSPLEX structure. When all IMS regions in the IMSplex have disconnected from the SYSPLEX structure, the structure is automatically deleted. Chapter 14: IMS Shared Queues and Security 173

Design Features If the SYSPLEX structure fails, the IMS SYSPLEX feature is disabled. The CA ACF2 IMS interface will revert to performing the default processing described previously. SYSPLEX Record The CA ACF2 IMS SYSPLEX feature is controlled in the IMS SYSPLEX control record. The following describes the fields in the IMS SYSPLEX record. ACTIVE NOACTIVE Controls whether the CA ACF2 IMS SYSPLEX feature is active. If ACTIVE is specified, the SYSPLEX feature will be activated during IMS initialization. If NOACTIVE is specified, the SYSPLEX feature will not be activated. The default is ACTIVE. PRIMNAME(structurename) Contains the structure name of the CA ACF2 IMS structure in the coupling facility when the CA ACF2 IMS SYSPLEX feature is set to ACTIVE. The structure name must match the structure name specified when the SYSPLEX structure is defined in the coupling facility. See the Implementing the SYSPLEX Feature section for more information on defining the SYSPLEX structure to the coupling facility. If the CA ACF2 IMS SYSPLEX feature is set to NOACTIVE, this field is ignored. There is no default value. ACF Commands There are four subcommands in the /ACF command specifically for the SYSPLEX feature: /ACF SHOW SYSPLEX Displays the current status of the SYSPLEX feature, information about the SYSPLEX structure, and statistics about the usage of the SYSPLEX structure from this IMS region. /ACF SYSPLEX START Starts the CA ACF2 IMS SYSPLEX feature after it has been stopped. /ACF SYSPLEX STOP Stops the CA ACF2 IMS SYSPLEX feature and disconnects from the SYSPLEX structure. /ACF SYSPLEX CLEAR Deletes all user entries from the SYSPLEX structure, regardless of the IMS region that created them. For more information see the chapter "ACF Command." Important! The IMS interface SYSPLEX structure should be cleared or the SYSPLEX feature manually stopped and started only when absolutely necessary. The impact of these commands is explained in more detail in the "ACF Command" chapter. 174 IMS Support Guide

Design Features Implement the SYSPLEX Feature Perform the following steps to implement the CA ACF2 IMS SYSPLEX feature. 1. Verify the cache structure for the IMSplex. The SYSPLEX cache entry contains the ACMCB, MLID, and validation cache for the user. Because the entry will be used in each of the IMS regions in the IMSplex, all of the IMS regions must have the same cache size and structure. They must all use the same minilid definition, or they must all use full logonids. For information on minilids, see the chapter "Installation Procedures." The IMS regions must also have the same number specified for the count of validation cache entries in the CACHENT# field in the STORAGE record. For more information on the STORAGE record, see the "Storage." 2. Calculate the size for the SYSPLEX structure. The storage requirement for the SYSPLEX structure is determined by the number of entries in the structure and the size of the entries. There should be an entry in the SYSPLEX structure for each user signed on to an IMS region in the IMSplex. Determine the total number of users you expect to be concurrently signed on in the IMSplex. Each entry is a copy of the user cache area. The size of the cache area can be obtained by issuing the following command: /ACF SHOW STORAGE Multiply the number of concurrent users by the size of the cache area. This gives you the approximate storage required to hold the user entries in the SYSPLEX structure. IBM also reserves a certain portion of the structure for structure overhead. For information on how to calculate that portion, see the IBM guide Setting Up A Sysplex. 3. Define the SYSPLEX structure to the coupling facility. Choose a name for the CA ACF2 IMS SYSPLEX structure in the coupling facility. There are different types of structures that can be defined to the coupling facility, including List, Cache, and Lock structures. The CA ACF2 IMS SYSPLEX structure must be defined as a List structure. Using the information collected above, the system programmer responsible for the coupling facility can define the CA ACF2 IMS SYSPLEX structure to the coupling facility. 4. Create the IMS SYSPLEX record. For each IMS region in the IMSplex, insert an IMS SYSPLEX record with the structure name from step 3. INSERT DIVISION(musid jobname) SYSPLEX ACTIVE PRIMNAME(structurename) For each IMS region, the IMS SYSPLEX record must be created in the CA ACF2 database for the z/os image where for the IMS region executes. Chapter 14: IMS Shared Queues and Security 175

Design Features 5. Start the IMS regions Start the IMS regions in the IMSplex. If an IMS region is unable to activate the SYSPLEX feature, diagnostic messages are issued during initialization. 6. Verify that the SYSPLEX feature is active Enter the following command to verify that the SYSPLEX feature is active: /ACF SHOW STATE CA ACF2 IMS Shared Queues NETWORK Record IMS NETWORK Record The CA ACF2 IMS interface supports a NETWORK record for an IMS shared queues environment. While the shared queues environment is not a true network environment, it has many of the characteristics of a network environment. Work is generated somewhere else (in this case, an IMS front-end region), and executes in an IMS region (the back-end region) without a user actually signing on. When it is defined in a back-end IMS region, the shared queues NETWORK (SQ NETWORK) record lets you establish a user cache, or a chain of user security environments that are created and saved in the back-end region. In the SQ NETWORK record, you specify how many users are kept in the user cache, and for how long. The IMS interface user cache processing for a back-end IMS region is defined in an IMS SQ NETWORK record. The fields in an IMS NETWORK record are explained below. LINKNAME(linkname) In conjunction with the TYPE field, this field defines the IMS links that are controlled by this record. For the SQ NETWORK record, the value for the LINKNAME field must be fully masked, for example, LINKNAME(********). TYPE(SQ) In conjunction with the LINKNAME field, this field defines which IMS links are controlled by this record. For the SQ NETWORK record, the value for TYPE must be SQ. The default is MSC. DFTLID(linkdefaultlogonid) This field is not pertinent in an IMS shared queues environment, and is ignored in the IMS SQ NETWORK record. INBOUND NOINBOUND This field is not pertinent in an IMS shared queues environment, and is ignored in the IMS SQ NETWORK record 176 IMS Support Guide

Design Features INHERIT NOINHERIT This field is not pertinent in an IMS shared queues environment, and is ignored in the IMS SQ NETWORK record. FORCSIGN FORCSIGN DEPTH This field is not pertinent in an IMS shared queues environment, and is ignored in the IMS SQ NETWORK record. When the IMS interface processes the first resource validation in a back-end IMS environment, the IMS interface signs on the logonid to the SQ link. When a back-end resource validation is processed for a different user, that logonid is also signed on to the link. This process occurs for any new logonid required in a back-end IMS environment. Use the DEPTH field to control how much storage this process uses. Specify the maximum number of logonids that can be concurrently signed on to the SQ link. If you specify DEPTH(10), when ten logonids are signed on to the SQ link and a resource validation is required for a new logonid, the oldest logonid on the SQ chain is signed off and the new logonid is signed on. When you specify the value for the DEPTH field, carefully weigh performance against storage. If you specify a low value, less storage is used. The IMS interface can perform a higher number of sign-ons, each having the performance impact of a regular terminal sign-on. If you specify a high value, the IMS interface does not need to do extra sign-offs and sign-ons, but storage is used for each logonid. TIMEOUT The value specified for this field is the number of minutes that a set of user control blocks in the link logonid cache is valid. After the timeout number of minutes has elapsed for a set of user control blocks, the control blocks are considered obsolete and are not used for new requests. If TIMEOUT is not specified for a NETWORK record, the default is 0 (zero). If the timeout value for a link is zero, user control blocks are not timed out. If the user control blocks exist in the link logonid cache, they are used. Chapter 14: IMS Shared Queues and Security 177

Design Features Implement the Shared Queues NETWORK Record Perform the following steps to implement the SQ NETWORK record. 1. Create the IMS SQ NETWORK record. For each IMS region in the IMSplex that may perform shared-queues back-end processing, that is, processing a resource validation for a user who is signed on to a different IMS region in the IMSplex, insert an IMS SQ NETWORK record. INSERT DIVISION(musid jobname) NETWORK.SQ LINKNAME(********) TYPE(SQ) DEPTH(nn) TIMEOUT(tt) For each IMS back-end region, the IMS SQ NETWORK record must be created in the CA ACF2 database for the z/os image where for the IMS back-end region executes. 2. Start the IMS region 3. Verification with the /ACF command Enter the following command to verify that the SQ NETWORK record is active and to display usage statistics for the process. /ACF SHOW LINK SQ Choose Your Security Process Choosing the correct implementation for your site requires an understanding of your security requirements, the storage requirements and performance of your IMS regions, and the capacity and performance of your coupling facility. You can choose the run with the default CA ACF2 IMS processing in a shared queues environment. You can also choose to use the SYSPLEX feature and the SQ NETWORK record separately or together, to provide the security process in a shared queues environment. 178 IMS Support Guide

Design Features IMS Interface Default Processing If you do not implement the SYSPLEX feature or the SQ NETWORK record, the IMS interface will perform the default IMS security processing described earlier in this chapter. This might be an acceptable alternative in some cases. For example, if your application transactions do not generate work in the back-end IMS region, that is, they do not issue PTP messages switches, AOI commands, or IMS AUTH calls, there will be no security processing in the back-end IMS regions. Another example could be a shared queues environment, such as a test IMSplex environment, which has low volume and for which violation processing is not required. However, for most shared queues environments, this alternative is not recommended. It has poor performance profile due to constant interaction with CA ACF2 and its databases, and cannot keep accurate violation counts. SQ NETWORK Record Without the SYSPLEX Feature If the storage capacity or performance of the coupling facility eliminates it as an alternative for your IMS security process, the SQ NETWORK record provides the best alternative. The user chain provided as part of the network processing minimizes the performance impact of constant interaction with CA ACF2 and its databases for signon, and the resource validation cache for each user minimizes the interaction with CA ACF2 for resource validation. This alternative does require storage in the IMS back-end region for the saved user control blocks, and you need to evaluate the storage and performance impact in choosing a DEPTH value in the record. This alternative does not keep accurate violation counts in the IMS front-end region for maximum violation (MAXVIO) and user suspend processing. Chapter 14: IMS Shared Queues and Security 179

Design Features SYSPLEX Feature With a SQ NETWORK Record Using an SQ NETWORK record in the IMS back-end regions with the IMS SYSPLEX feature can be useful in the following circumstances: 1. If the coupling facility is unstable and the SYSPLEX feature becomes inactive, the IMS interface can no longer use the coupling facility structure. If no SQ NETWORK record exists for the IMS back-end regions, the IMS interface reverts to its default processing, which calls CA ACF2 to recreate user security environments in the back-end region for every resource validation. If an SQ NETWORK record exists for the back-end regions, the IMS interface will revert to the SQ NETWORK process, which has better performance, without the process off bringing the IMS region down, creating an SQ NETWORK record, and bringing the region back up. 2. If a significant portion of your IMS workload is generated by users who sign on, enter transactions, and sign off before the transactions execute, most of the performance enhancement of the SYSPLEX feature is lost. When the transaction executes in the IMSplex, the SYSPLEX entry for the user session has been deleted. If no SQ NETWORK record exists for the back-end regions, the IMS interface reverts to its default processing, which calls CA ACF2 to recreate the user security environment in the back-end region for every resource validation for the user. If an SQ NETWORK record exists for the back-end regions, the IMS interface will revert to the SQ NETWORK process, which maintains the user security environment on the SQ link chain. The negative impact of using the SYSPLEX feature with an SQ NETWORK record is performance and storage in the back-end IMS region during normal processing. If the user is still signed on, the IMS interface reads the user SYSPLEX entry in the back-end region and uses it for the validation. It also spends execution time and storage maintaining and updating the user environment on the SQ link chain, which will be used only if the user signs off or the coupling facility structure fails. Security Processing in the IMS Back-end Region The CA ACF2 IMS processing in an IMS back-end region is controlled by the security options specified for that region. The security options in the front-end region do not affect the security processing in the back-end region. 1. Transaction security in the back-end region is controlled by the $SECTRAN RESOURCE record for that region. 2. Command security in the back-end region is controlled by the $TRANCMD and $TRANCM1 RESOURCE records for that region. 3. AUTH call security in the back-end region is controlled by the resource pre-validation exit in that region. For consistent security processing in a shared queues environment, the same RESOURCE records should be specified in all regions in the IMSplex. 180 IMS Support Guide

Design Features NETWORK Records and Shared Queues Environments IMS NETWORK records provide additional levels of control over security processing when a transaction or command comes from: a network link, such as an ISC or MSC link an APPC conversation an OTMA connection For more information on security processing for ISC and MSC links see the chapter "MSC and ISC Link Security." For more information on security processing for APPC conversations see the "APPC Security" chapter. For more information on security processing for OTMA connections see the chapter "OTMA Security." In network processing for the shared queues environment, the IMS front-end region is the region communicating directly with the network link. If transactions entered from the network link execute in a different region, that region is the back-end region for the process. In an IMS shared queues environment, the NETWORK record in the region performing the validation controls the security processing in that region. For example, a transaction that enters a front-end region from an MSC link is validated using the options specified in the NETWORK record for the MSC link in that front-end region. If the transaction executes in a different region and generates a secondary transaction, the new transaction will be validated using the options specified in the NETWORK record for the MSC link in the back-end region. This is true for ISC, MSC, APPC, and OTMA network links. For consistent security processing for network links, the same NETWORK records should be specified in all regions in the IMSplex. For ISC and MSC links, the links should also be defined in the IMS system definitions for all regions in the IMSplex. This is required so that the links are mapped to the appropriate NETWORK records in all regions. Chapter 14: IMS Shared Queues and Security 181

Chapter 15: ACF Transaction CA ACF2 IMS (IMS Interface) provides the ACF transaction so that you can maintain logonid records from IMS. The logonid maintenance requests for IMS Interface are very similar to the ACF subcommands used on other CA ACF2 systems. This section contains the following topics: ACF Transaction (see page 183) END Request (see page 183) SET Request (see page 183) INSERT Request (see page 184) CHANGE Request (see page 185) DELETE Request (see page 186) LIST Request (see page 187) ACF Transaction Enter the ACF transaction to begin the IMS logonid maintenance transaction. ACF After you enter the ACF transaction, you can use the SET, INSERT, CHANGE, DELETE, LIST, or END requests. END Request Enter the END request to terminate the ACF transaction END SET Request The SET request determines which type of logonid record information display is returned after CA ACF2 processes an INSERT, CHANGE, or LIST request. A combination of TERSE or VERBOSE and TRIVIA or NOTRIVIA can be specified. When you enter the ACF transaction, the default values are VERBOSE and TRIVIA. If you want a different logonid display mode, use the SET request before you perform an INSERT, CHANGE, or LIST. SET [TERSE VERBOSE] [TRIVIA NOTRIVIA] Chapter 15: ACF Transaction 183

INSERT Request Parameters TERSE VERBOSE Whenever the logonid display is controlled by TERSE, CA ACF2 issues an abbreviated response, regardless of whether TRIVIA or NOTRIVIA is in effect. When the VERBOSE display mode is in effect, the fields that are listed depend on whether TRIVIA or NOTRIVIA is in effect, and whether a single record or multiple records are being processed. When multiple records are processed by CHANGE, DELETE, or LIST (with the LIKE or UID parameter), CA ACF2 automatically issues the command response in TERSE mode. TRIVIA NOTRIVIA All fields that have a value, and each attribute field that is on, are printed when CA ACF2 is in the VERBOSE, TRIVIA mode. All TRIVIA fields are omitted from the logonid record display when you specify NOTRIVIA. To determine which fields are TRIVIA fields, CA ACF2 checks the @CFDE LIST= and FLAGS= settings in the Field Definition Record (ACFFDR) as generated at your site. See the LIST= and FLAGS= operand descriptions in the Installation Guide for additional information. INSERT Request The INSERT request is used to create a new logonid record and to specify values for the fields in the record. This establishes a user profile and positive identification for an authorized system user. INSERT [USING(logonid)\ logonid field1(value1) attribute1 fieldx(valuex) attributex Parameters USING(logonid) The optional USING parameter causes CA ACF2 to model the new logonid record after a preestablished prototype, whose name is specified in parentheses. Values for fields in the specified logonid prototype are copied into the new record. This means that standard fields do not have to be defined each time a new logonid record is created. Whenever the USING parameter is used, it must be specified first. Logonid Logonid is a required parameter for the INSERT request that assigns a unique identity to the record being created. CA ACF2 does not insert a new record if a record with the specified logonid already resides in the database. 184 IMS Support Guide

CHANGE Request Fields and Attributes Rules governing how fields are assigned values in the logonid record being created with the USING parameter are: Fields that you do not explicitly define on the INSERT request are set to the value in the designated logonid prototype. Any logonid field that was specified in the @ZEROFLD macro during ACFFDR generated is zeroed or blanked out when a new logonid record is created. Typically, these include user identification fields, such as NAME and PHONE, and privilege fields, such as ACCOUNT and AUDIT. To supersede a field value in the logonid prototype, or to assign a value to a field blanked out with @ZEROFLD, specify the field name and desired value in the INSERT quests. Fields that signify attributes, such as the AUDIT privilege, are off or on and are considered to be bit fields. To turn on an attribute, the field name is specified on the INSERT request. Conversely, to turn off an attribute, precede the field name by NO. For example, to turn off the AUDIT privilege, specify NOAUDIT on the INSERT request. This also applies when you want to modify attribute fields with the CHANGE subcommand. See the Administrator Guide for additional information concerning bit fields. When CA ACF2 finishes processing the INSERT request, it responds with an acknowledgment that the logonid record has been created. The information that is contained in this acknowledgment depends on the mode, as determined by the SET request or its defaults. When ACF is in TERSE mode, it returns the RECORD INSERTED message. In VERBOSE mode, the fields displayed depend on whether TRIVIA or NOTRIVIA is set. (See SET request.) CHANGE Request The CHANGE request alters particular fields in existing logonid records. CHANGE * logonid LIKE(logonidmask) UID(uidmask) field1(value1) attribute1 Parameters The first parameter on the CHANGE request indicates the logonid records affected by the change operation. The four choices for this parameter are as follows. * The current logonid record. To make the change apply to the logonid record that you are currently working with, specify an asterisk(). For example, suppose you just created logonid ABN597 with the INSERT request. To modify fields in ABN597, enter CHANGE followed by the desired field specifications. This is shorthand for entering CHANGE ABN597. Chapter 15: ACF Transaction 185

DELETE Request Logonid Enter the logonid (LID field value) to change fields in a single logonid record. LIKE(logonidmask) or UID(uidmask) A single CHANGE request can modify fields in multiple logonid records by using LIKE or UID, followed by a mask (that is, a pattern) in parentheses. You can create a mask by coding an asterisk(*) to denote that any character, including a blank, can be present in that positional. For example, both ABC59 and ABN 597 match a mask of AB*59*. Masks (asterisks) that are near the beginning of the logonid cause a greater number of logonid records to be checked than masks (asterisks) near the end of the logonid. For example, a seemingly simple mask such as BC59 causes all logonid records to be compared against the mask. When you use the LIKE keyword, CA ACF2 examines the LID field of each record to determine if it fits the given mask. When you use the UID keyword, CA-ACF first constructs the UID for each logonid record by concatenating all fields that comprise the string, then compares it to the mask to determine if it matches. Fields and Attributes To change a field in a logonid record, specify the field name followed by the desired value in parentheses, with no intervening blanks. To turn on an attribute, specify the field name. Conversely, to turn off an attribute, precede the field name by NO. When CA ACF2 finishes processing the CHANGE request, it responds with an acknowledgment that one or more logonid records have been modified. The content of the command response depends on the mode, as determined by the SET request, and whether multiple records have been changed. DELETE Request The DELETE request eliminates the logonid records and their associated access rule sets from the CA ACF2 databases. DELETE logonid LIKE(logonidmask) YUDyudnasj( [NORULE] 186 IMS Support Guide

LIST Request Parameters The first parameter on the DELETE request determine which logonid records are eliminated. The four choices for this parameter are identical to the CHANGE and LIST requests, and are briefly reiterated as follows: CA ACF2 deletes the current logonid record when you enter an asterisk, that is, DELETE. However, you cannot use the * specification to delete your own logonid. CA ACF2 eliminates a single record when you enter its unique logonid. CA ACF2 deletes multiple logonid records when you use LIKE or UID, followed by a mask. (See CHANGE Request) In addition, CA ACF2 deletes the access rule set with a high-level index that matches the LID field value of the deleted logonid record. Similarly, when you delete multiple logonid records, CA ACF2 deletes each corresponding rule set. NORULE The optional NORULE parameter saves the access rule sets associated with the logonid records being deleted. LIST Request The LIST request displays logonid record fields and their values. LIST * logonid LIKE(logonidmask) UID(uidmask) [IF(fieldlist)] CA ACF2 displays the current logonid record when you enter as asterisk, that is, LIST *. CA ACF2 displays a single logonid record when you specify its unique logonid. When a single logonid record is listed, the choice of displayed fields depends on the ACF mode. (See SET Request.) CA ACF2 displays multiple logonid records when you use LIKE or UID, followed by a mask. When you request CA ACF2 to list multiple records, CA ACF2 immediately goes into TERSE mode. In TERSE mode, CA ACF2 lists only three items from each logonid record: the LID field, the user identification string (UID), and the Name FIELD. Chapter 15: ACF Transaction 187

Chapter 16: ACF Command The IMS interface provides the /ACF command to perform system control and display functions, such as reloading resource rule directories and displaying the IMS interface system options. This section contains the following topics: Design Concepts and Features (see page 189) RELOAD Function (see page 190) RESET CACHE Function (see page 191) RESET LINK Function (see page 192) SHOW LINK Function (see page 193) SHOW SIGNON Function (see page 195) SHOW STATE Function (see page 195) SHOW STORAGE Function (see page 198) SHOW SYSPLEX Function (see page 200) SYSPLEX CLEAR Function (see page 201) SYSPLEX START Function (see page 202) SYSPLEX STOP Function (see page 203) Design Concepts and Features The IMS interface provides the /ACF command to perform system control and display functions. The /ACF command is defined with default IMS command security, meaning it can only be executed from the IMS master terminal. If SMU is used to change this default security, a modification to the IMS software is required to formally define the /ACF command to IMS. This modification, and the job provided to make the modification, is described in the chapter Installation Procedures. The /ACF command is also defined as not valid for AOI, that is, it cannot be entered from an IMS transaction using the automated operator interface feature. This cannot be changed. The syntax of the /ACF command is: /ACF functions parameters The IMS interface supports the following functions: RELOAD RESET Reloads resource rule directories. Resets the resource rule caches. Chapter 16: ACF Command 189

RELOAD Function SHOW Displays the IMS interface system information. SYSPLEX Controls the IMS interface SYSPLEX feature. RELOAD Function The RELOAD function requests the IMS interface to reload one or all of the locally resident resource rule directories. You should use this function when you change resource rules that affect the IMS interface resources while IMS is running. To implement the updated resource rules in the online environment, you must perform a directory reload. Syntax The syntax of the RELOAD function is: /ACF RELOAD ttt ALL Parameters The RELOAD function uses the following parameters: RELOAD A directory reload request. ttt Type code for the resource rule directory that is to be reloaded. ALL Request is to reload the resource rule directories for all IMS interface protected resources in this IMS system. Processing The IMS interface attempts to reload the resource rule directories indicated in the reload request. The IMS interface also resets (clears) the resource validation caches for all current users because the rules affecting the cached resources might have changed. 190 IMS Support Guide

RESET CACHE Function Response The IMS interface responds with the successful completion or error message for each resource rule directory indicated on the reload request. RESET CACHE Function The RESET CACHE function requests the IMS interface to reset (clear) the resource validation caches for all current users. You should use this function when you rebuild a globally resident resource rule directory that affects the IMS interface resources. Because the rules that affect the cached resources might have been changed, you must clear the resource validation caches and reset the caches to their initial state. Syntax The syntax of the RESET CACHE function is: /ACF RESET CACHE Parameters The RESET CACHE function uses the following parameters: RESET A reset request. CACHE Reset request is for the resource validation caches. Processing The IMS interface clears the resource validation caches for all current users and resets the caches to their initial state. Response The IMS interface responds with a command complete message. Chapter 16: ACF Command 191

RESET LINK Function RESET LINK Function The RESET LINK function requests that the IMS interface find a particular logonid signed on to a network link, and set an indicator in the control blocks that prevent the control blocks from being used again. You should use this function when something in the logonid has been changed, and you want the IMS interface to stop using the existing control blocks with the obsolete logonid information and to create a new set of control blocks with the new logonid information. The control blocks in question can exist only on links which are defined with the INHERIT attribute. As a result, issuing this command against a link defined with NOINHERIT will have no effect other than message ACFDC072. The RESET LINK command only affects control blocks for inherited IDs, and has no effect on the default logonid, if any assigned to the link. Syntax The syntax of the RESET LINK function is: /ACF RESET LINK linkname USERID logonid Parameters The RESET LINK function uses the following parameters: RESET LINK A reset request. Reset request is for a network link logonid cache. linkname USERID logonid Name of the network link where the logonid is signed on. Reset request is to reset the control blocks for a logonid in the network link logonid cache. Logonid in the network link logonid cache whose control blocks are to be reset. 192 IMS Support Guide

SHOW LINK Function Processing The IMS interface sets an indicator in the control blocks for the logonid that prevent the control blocks from being used. If another request is received from this network link for this logonid, the logonid is signed on to the network link again and the new set of logonid control blocks are added to the link logonid cache. Note: The control blocks for the logonid are not removed from the link logonid cache when the reset command is processed. If a /ACF SHOW LINK command is issued, the depth count for the link will still include this logonid. If, during later processing, the maximum depth count for the logonid cache is exceeded, these control blocks are available to be signed off. Response The IMS interface responds with a command complete message. SHOW LINK Function The SHOW LINK command displays one or all of your network links, the security options in effect for the links, and some statistical information about the IMS interface security processing for the link. Syntax The syntax of the SHOW LINK functions are: /ACF SHOW LINK /ACF SHOW LINK ALL /ACF SHOW LINK linkname Parameters The SHOW LINK function uses the following parameters: SHOW A display request. LINK Display request is for the IMS interface network link information. blank No linkname is specified, ALL is assumed. Chapter 16: ACF Command 193

SHOW LINK Function ALL Request is to display the link information for all network links in the IMS system. linkname Name of the network link whose information is to be displayed. The linkname can be the name of a MSC or ISC link, or can be the names APPC, OTMA, or SQ. Processing The IMS interface formats and displays the information requested. Response A8DLU6T1 ISC LINK CONTROLLED BY NETWORK RECORD RECORD KEY ======> CIMS********NETWORK.ISC LINKNAME(********) TYPE(ISC) INBOUND LINKMTM1 MSC LINK CONTROLLED BY NETWORK RECORD RECORD KEY ======> CIMSTESTNET4NETWORK.MSC LINKNAME(********) TYPE(MSC) DFTLID(IMSISCL1) DFTLID(IMSMSCL2) INHERIT NOFORCSIGN DEPTH( 2) INBOUND LINK STATISTICS: CURRENT DEPTH = 0 LOGONID FOUND = 0 LOGONID SIGNED ON = 0 LINKVTM1 MSC LINK CONTROLLED BY NETWORK RECORD RECORD KEY ======> CIMSTESTNET4NETWORK.MSC LINKNAME(********) TYPE(MSC) DFTLID(IMSMSCL2) INHERIT NOFORCSIGN DEPTH( 2) INBOUND CURRENT DEPTH LINK STATISTICS: CURRENT DEPTH = 0 LOGONID FOUND = 0 LOGONID SIGNED ON = 0 The number of logonids currently signed on to the link. LOGONID FOUND The number of times the IMS interface found a logonid already signed on the link when doing a validation. LOGONID SIGNED ON The number of times the IMS interface had to sign a logonid on to the link when doing a validation. 194 IMS Support Guide

SHOW SIGNON Function SHOW SIGNON Function The SHOW SIGNON command requests a display of the terminals in the IMS system where a given logonid is signed on. Syntax The syntax of the SHOW SIGNON function is: /ACF SHOW SIGNON logonid Parameters The SHOW SIGNON function uses the following parameters: SHOW-This is a display request. SIGNON-The display request is for the list of terminals in the IMS system where a given logonid is signed on. logonid-the logonid for which the display is requested. Processing The IMS interface formats and displays the information requested. Response LOGONID IMSLID1 IS SIGNED ON TO THE FOLLOWING TERMINALS: VT001 SHOW STATE Function The SHOW STATE command requests a display of the IMS interface system options currently in effect for this IMS system. Syntax The syntax of the SHOW STATE function is: /ACF SHOW STATE Chapter 16: ACF Command 195

SHOW STATE Function Parameters The SHOW STATE function uses the following parameters: SHOW-This is a display request. STATE-The display request is for the IMS interface system options in effect for this IMS system. Processing The IMS interface formats and displays the information requested. 196 IMS Support Guide

SHOW STATE Function Response The IMS interface options are grouped by the IMS control record where the option is obtained. The following is a sample response: ACF2/IMS RELEASE - 15.0 IMS RELEASE - 9.1 OPTS RECORD KEY ======> CIMS********OPTS MODE(ABORT ) DFTLID(IMSDFLT ) IDLE(IDLE ) MAXVIO( 5) PWMAXVIO( 3) MSGBASE(900) SUSPEND NOFMTPTRAN NONLIDDFLT NOISRTNVAL BMPUSID(USERID ) BMPMSG(BMPUSER ) SIGNON RECORD KEY ======> CIMS********SIGNON ENQNAME(SYSIKJUA) AUTH(IMS ) PSFORMAT(SIGN ) NOTIFY NPVERIFY FORMAT( ) $LOCKTRM RECORD KEY ======> DEFAULT VALUES TYPE(ILL) VALIDATE $LOCKDB RECORD KEY ======> DEFAULT VALUES TYPE(ILD) VALIDATE $LOCKPGM RECORD KEY ======> DEFAULT VALUES TYPE(ILP) VALIDATE $LOCKTRN RECORD KEY ======> DEFAULT VALUES TYPE(ILT) VALIDATE $TRANCM1 RECORD KEY ======> DEFAULT VALUES TYPE(ICM) VALIDATE $TRANCMD RECORD KEY ======> DEFAULT VALUES TYPE(ICM) VALIDATE $COMMAND RECORD KEY ======> DEFAULT VALUES TYPE(ICM) VALIDATE $PSB RECORD KEY ======> DEFAULT VALUES TYPE(IPS) VALIDATE $SECTRAN RECORD KEY ======> CIMS********RESOURCE.SECTRAN TYPE(CTR) VALIDATE $RASTRAN RECORD KEY ======> CIMS********RESOURCE.RASTRAN TYPE(ITR) VALIDATE $RASTERM RECORD KEY ======> CIMS********RESOURCE.RASTERM TYPE(ILT) NOVALIDATE $RASPSB RECORD KEY ======> CIMS********RESOURCE.RASPSB TYPE(IPS) NOVALIDATE $PRITRAN RECORD KEY ======> CIMS********RESOURCE.PRITRAN TYPE(ITR) VALIDATE $AGN RECORD KEY ======> CIMS********RESOURCE.AGN TYPE(IAG) NOVALIDATE WTO RECORD KEY ======> CIMS********WTO NOWTO NOINFOWTO EXITS RECORD KEY ======> CIMSJ16XIMS9EXITS IDLE(ACFDCXID) INITIAL( ) PRESIGN( ) PREVAL( ) POSTVAL( ) SIGNOFF( ) SIGNON( ) STORAGE RECORD KEY ======> CIMS********STORAGE Chapter 16: ACF Command 197

SHOW STORAGE Function CACHENT#( 10) CACHPOOL( 20, 5) IPBXPOOL( 20, 5) DFTCIDLE( 0) DFTCPOOL( 11, 6) DFTCSCAN( 0) SAVEPOOL( 20, 5) WKA1POOL( 20, 5) WKA2POOL( 20, 5) WKB1POOL( 20, 5) WKB2POOL( 20, 5) NETWORK RECORD KEY ======> CIMS********NETWORK.APPC LINKNAME(********) TYPE(APPC) DFTLID( ) INBOUND NOINHERIT NOFORCSIGN DEPTH( 10) TIMEOUT( 0) MATCHED IMS LINKNAME ======> APPC NETWORK RECORD KEY ======> CIMS********NETWORK.ISC LINKNAME(********) TYPE(ISC ) DFTLID(IMSISCL1) INBOUND MATCHED IMS LINKNAME ======> AXXLU6T1 SYSPLEX RECORD KEY ======> CIMS********SYSPLEX NOACTIVE STRUCTURE(ACF2IMSSQ1 ) THE SYSPLEX FEATURE IS CURRENTLY NOT ACTIVE SHOW STORAGE Function The SHOW STORAGE command requests a display of the current IMS interface storage use statistics. Syntax The syntax of the SHOW STORAGE function is: /ACF SHOW STORAGE Parameters The SHOW STORAGE function uses the following parameters: SHOW-This is a display request. STORAGE-The display request is for the current IMS interface storage use statistics. Processing The IMS interface formats and displays the information requested. 198 IMS Support Guide

SHOW STORAGE Function Response ACF2/IMS RELEASE - 15.0 IMS RELEASE - 9.1 STORAGE - PROGRAM ====> 100616 STORAGE - ABOVE THE LINE ====> 79598 STORAGE - BELOW THE LINE ====> 28928 POOL ALLOCATIONS LENGTH PRIMARY SECONDARY TOTAL IN USE HIGH WATER CACHE AREAS 1624 20 5 20 2 2 IPB EXTENSIONS 56 20 5 20 3 3 DEFAULT CACHE 448 11 6 11 1 1 SAVE AREAS 72 20 5 20 2 3 ABOVE / WORK 1 256 20 5 20 0 3 ABOVE / WORK 2 1504 20 5 20 2 3 BELOW / WORK 1 256 20 5 20 0 0 BELOW / WORK 2 1024 20 5 20 0 0 STORAGE - PROGRAM Amount of storage (bytes) occupied by currently resident IMS interface programs. STORAGE - ABOVE THE LINE This field contains the amount of storage in extended storage (above the 16MB line) currently in use by the IMS interface for control blocks, storage pools, and so on. STORAGE - BELOW THE LINE This field contains the amount of storage not in extended storage (below the 16MB line) currently in use by the IMS interface for control blocks, storage pools, and so on. Chapter 16: ACF Command 199

SHOW SYSPLEX Function STORAGE - POOL Allocations ACF2/IMS RELEASE - 15.0 IMS RELEASE - 9.1 STORAGE - PROGRAM ====> 100616 STORAGE - ABOVE THE LINE ====> 79598 STORAGE - BELOW THE LINE ====> 28928 POOL ALLOCATIONS LENGTH PRIMARY SECONDARY TOTAL IN USE HIGH WATER CACHE AREAS 1624 20 5 20 2 2 IPB EXTENSIONS 56 20 5 20 3 3 DEFAULT CACHE 448 11 6 11 1 1 SAVE AREAS 72 20 5 20 2 3 ABOVE / WORK 1 256 20 5 20 0 3 ABOVE / WORK 2 1504 20 5 20 2 3 BELOW / WORK 1 256 20 5 20 0 0 BELOW / WORK 2 1024 20 5 20 0 0 STORAGE - PROGRAM Amount of storage (bytes) occupied by currently resident IMS interface programs. STORAGE - ABOVE THE LINE This field contains the amount of storage in extended storage (above the 16MB line) currently in use by the IMS interface for control blocks, storage pools, and so on. STORAGE - BELOW THE LINE This field contains the amount of storage not in extended storage (below the 16MB line) currently in use by the IMS interface for control blocks, storage pools, and so on. SHOW SYSPLEX Function The /ACF SHOW SYSPLEX subcommand displays the current status of the IMS interface SYSPLEX feature, information about the SYSPLEX structure, and statistics about the usage of the SYSPLEX structure from this IMS region. Syntax The syntax of the SHOW SYSPLEX functions is: /ACF SHOW SYSPLEX 200 IMS Support Guide

SYSPLEX CLEAR Function Parameters The SHOW SYSPLEX function uses the following parameters: SHOW-This is a display request. SYSPLEX-This display request is for the IMS interface SYSPLEX feature information. Processing The IMS interface formats and displays the information requested. Response CURRENT DEPTH The number of logonids currently signed on to the link. LOGONID FOUND The number of times the IMS interface found a logonid already signed on the link when doing a validation. LOGONID SIGNED ON The number of times the IMS interface had to sign a logonid on to the link when doing a validation. SYSPLEX CLEAR Function The /ACF SYSPLEX CLEAR subcommand can only be entered if the IMS interface SYSPLEX feature is active. The command deletes all entries from the SYSPLEX structure. Entries are deleted whether they were created by the IMS region processing the command or by another IMS region connected to the structure. For more information about the SYSPLEX feature, see the chapter "IMS Shared Queues and Security." Important: The IMS interface SYSPLEX structure should be cleared only when absolutely necessary. When the structure is cleared, the user control blocks for all users currently signed on are deleted from the structure, and will not be available until the user signs off and signs back on. For authorizations in back-end IMS regions, the IMS interface will create user control blocks by requesting them from ACF2. This will impact performance and the accuracy of resource violation counts. Chapter 16: ACF Command 201

SYSPLEX START Function Syntax The syntax of the SYSPLEX CLEAR function is: /ACF SYSPLEX CLEAR Parameters The SYSPLEX CLEAR function uses the following parameters: SYSPLEX-This is a SYSPLEX request. CLEAR-This request is to delete all user entries from the SYSPLEX structure Processing The IMS interface deletes all user entries from the IMS interface SYSPLEX structure. Response The IMS interface responds with a command complete message. SYSPLEX START Function The /ACF SYSPLEX START subcommand connects to the IMS interface SYSPLEX structure and activates the IMS interface SYSPLEX feature. For more information about the SYSPLEX feature, see the chapter "IMS Shared Queues and Security." Important: The IMS interface SYSPLEX structure should be manually stopped and started only when absolutely necessary. When the SYSPLEX feature is stopped, no user control blocks are written to the SYSPLEX structure when a user signs on. If the SYSPLEX feature is started later, no control blocks are available for the user in the SYSPLEX structure until the user signs off and signs back on. For authorizations in the back-end IMS regions, the IMS interface will create user control blocks by requesting them from ACF2. This will impact performance and the accuracy of resource violation counts. Syntax The syntax of the SYSPLEX START function is: /ACF SYSPLEX START 202 IMS Support Guide

SYSPLEX STOP Function Parameters The SHOW SYSPLEX function uses the following parameters: SYSPLEX A SYSPLEX request. START Request is to activate the IMS interface SYSPLEX feature. Processing The IMS interface activates the IMS interface SYSPLEX feature. Response The IMS interface responds with a command complete message. SYSPLEX STOP Function The /ACF SYSPLEX STOP subcommand deactivates the IMS interface SYSPLEX feature and disconnects from the IMS interface SYSPLEX structure. For more information about the SYSPLEX feature, see the chapter "IMS Shared Queues and Security." Important: The IMS interface SYSPLEX structure should be manually stopped and started only when absolutely necessary. When the SYSPLEX feature is stopped, no user control blocks are written to the SYSPLEX structure when a user signs on. If the SYSPLEX feature is started later, no control blocks are available for the user in the SYSPLEX structure until the user signs off and signs back on. For authorizations in the back-end IMS regions, the IMS interface will create user control blocks by requesting them from ACF2. This will impact performance and the accuracy of resource violation counts. Syntax The syntax of the SYSPLEX STOP function is: /ACF SYSPLEX STOP Chapter 16: ACF Command 203

SYSPLEX STOP Function Parameters The SYSPLEX STOP function uses the following parameters: SYSPLEX A SYSPLEX request. STOP Request is to deactivate the IMS interface SYSPLEX feature. Processing The IMS interface deactivates the IMS interface SYSPLEX feature. Response The IMS interface responds with a command complete message. The ACF Command in an IMSplex In an IMSplex environment, each IMS region registers with the CSL OM address space and communicates to OM the subset of IMS commands that can be entered through DFSSPOC or the OM API and routed to that IMS region. The IMS source module DFSOSY20 contains the commands and keywords that IMS registers with the OM address space. By default, the /ACF command is not one of these IMS commands that can be entered through OM. If you have a requirement to enter the /ACF command through OM and route it to multiple IMS regions in the IMSplex, you must apply a USERMOD to the IMS software to add the /ACF command to the IMS OM registered commands. A sample USERMOD to add the /ACF command to the DFSOSY20 module is included in the IMSUMOD1 member in the CAX1JCL2 sample JCL data set. For more information on the installation of this USERMOD see Installation Procedure (see page 237). 204 IMS Support Guide

Chapter 17: Reports This chapter provides a summary of the CA ACF2 reports that apply to IMS interface and describes how you can use the reports to analyze the IMS interface system. It describes the reports that have IMS interface implications. This section contains the following topics: Design Concepts and Features (see page 205) Report Generators (see page 205) Design Concepts and Features The reports discussed in this chapter are provided with the CA ACF2 system. The ACFRPTEL, ACFRPTPW, ACFRPTRV, ACFRPTRX, ACFRPTXR, and ACFRGP report generators can help you analyze an IMS interface system. The reports include information specific to the IMS interface. The use of these report generators and general considerations for interpreting their output are documented in the Reports and Utilities Guide and the Administrator Guide. We recommend that you read this chapter to obtain overview information and see the two guides previously mentioned to obtain detailed information about files, parameters, field descriptions, and sample output for each of the reports. Report Generators This section provides overview information about the CA ACF2 reports that include IMS interface information. ACFRPTEL-The Infostorage Update Log The Infostorage Update Log provides a list of changes made to the Infostorage database. These changes include updates made to resource rule sets. ACFRPTPW-The Invalid Access/Authority Log The Invalid Access/Authority Log (ACFRPTPW) shows all denied system access attempts and the reason for denial, along with any accesses logged because of the LOGSHIFT privilege. The ACFRPTPW report shows all attempted accesses of IMS systems that were denied. Chapter 17: Reports 205

Report Generators ACFRPTRV-The Generalized Resource Event Log The resource facility produces journal information based upon the results of IMS resource validation requests. The Generalized Resource Event Log describes the nature of resource accesses, the user requesting the access, and the final disposition of the access. The ACFRPTRV report generator has special considerations when used for IMS. These are: The resource name is displayed as: R-type-resource Where: R type A constant, representing storage class = R for resource rules. Three-character resource type specified for the resource in the IMS RESOURCE record. resource Resource name (for example, the transaction, AGN, or command name). The lookup key is the name of the resource rule set that was used to determine access authority. If the lookup key is a mask, it can be different than the resource name. ACFRPTRX-The Logonid Access Report The Logonid Access Report (ACFRPTRX) displays all resource rule entries that apply to a given logonid. A logonid (LID) mask and a user identification string (UID) mask are accepted as input. A Logonid Access Report is generated for each input LID/UID. Additionally, accesses permitted by special CA ACF2 privileges, such as NON-CNCL and SECURITY, are also indicated on the report. For IMS interface user logonids, the ACFRPTRX report shows all IMS interface protected resources that apply to that logonid. 206 IMS Support Guide

Report Generators ACFRPTXR-The Cross-Reference Report The Cross-Reference Report (ACFRPTXR) accepts a resource type and resource name as input and generates a report showing all logonids that have access to that resource. Also, the report displays the reason why each logonid has access to the resource. When used for an IMS interface protected resource, the ACFRPTXR report shows all logonids that have access to that resource. ACFRGP-The Resource Grouping Utility The Resource Grouping Utility produces a list of resource group names where a particular resource belongs. You can categorize resources, such as transactions, with similar access requirements in groups so that only one resource rule is needed. Resources can belong to more than one group, and groups can belong to other groups. This utility shows all the resource group names where a specified resource belongs. See the cross-reference chapter in the Administrator Guide for more information about resource grouping. Chapter 17: Reports 207

Chapter 18: Additional Considerations This chapter discusses a wide range of topics regarding the overall use of IMS interface security. These topics are of concern to security administrators, database administrators, systems programmers, and IMS terminal users. This section contains the following topics: Design Concepts and Features (see page 209) Using Password Reverification (see page 210) Using Rule Directories (see page 212) Maintaining IMS Records (see page 214) Signing On With The IMS Interface (see page 214) Understanding Security Implications of the ACF Transaction (see page 219) Supporting Transactions that Submit Jobs (see page 220) Supporting the AUTH Call with the IMS Interface (see page 221) Design Concepts and Features This section describes the CA ACF2 and IMS interface design components that apply to the topics discussed in this chapter. The /ACF Command The /ACF command is an IMS command that provides IMS interface functions, such as reloading local rule directories. The AUTH Call The AUTH call is an IMS communications call that makes resource security decisions available to IMS application programs. Idle Time Idle time is the amount of time that elapses between a terminal user's entries. The term idle refers to the terminal being inactive. The IMS TM Interface provides the Idle time facility to enforce reverification of a user's password whenever he exceeds the specified amount of idle time. Chapter 18: Additional Considerations 209

Using Password Reverification Resource Rule Directories A resource rule directory contains resource rule sets copied from the Infostorage database and placed into computer memory for easy and timely access. The main function of resource rule directories is to make resource rule sets readily available to CA ACF2 systems (for example, CA ACF2, the CICS interface, the IMS interface, and so forth) residing in z/os address spaces. Resource rule directories also enable the CA ACF2 masking feature for resource rule keys. CA ACF2 provides two types of resource rule directories: Globally Resident Directories-Globally resident directories are accessible to any z/os address space because they are stored in the extended common storage area (ECSA). Copies of the IMS interface resource rule sets that are shared among multiple IMS control regions can be stored in globally resident rule directories. For information about how to make resource rule directories globally resident, see the explanation of INFODIR records in the chapter Maintaining Global System Options Records, in the Administrator Guide. Locally Resident Directories-A locally resident directory is stored in a specific z/os address space (for example, an IMS control region). Therefore, it is accessible only to the address space on which the directory is built. Locally resident directories are stored in the extended local system queue area (ELSQA). Copies of the IMS interface resource rule sets that are used only by a single IMS control region can be stored in locally resident directories. See the Administrator Guide for further information. The VERIFY Keyword You can include the VERIFY keyword on resource rules to request users to reenter their passwords during access attempts. The Greeting Message Exit The Greeting Message Exit lets you change the message presented to a terminal user at sign-on. Using Password Reverification You can request password reverification in the IMS TM Interface in two ways: Specify the Idle time facility in the IMS OPTS record and the users' logonid records Specify VERIFY in a resource rule entry The following section describes what you must consider when you decide to implement password reverification. 210 IMS Support Guide

Using Password Reverification Idle Time Considerations The Idle time facility serves to check lengthy lapses of terminal activity in between operator entries. If a user walks away from his terminal without signing off, the facility keeps track of the amount of time the terminal remains inactive. If the user returns to his terminal after the specified idle time has elapsed and attempts to execute an IMS transaction or command, the following message is displayed on the terminal screen: DFSUnnn ACF2/IMS: IDLE PASSWORD REVERIFICATION IS REQUIRED Where DFSUnnn is the IMS message number assigned to the message. For a transaction or a command, the user must reenter the request with the following response: trancode(password) data You can also enter the password in the MFS formatted screen password field. Upon receipt of the user's response, the IMS interface verifies that the password matches the password of the user's logonid. If the match is successful, the user is permitted to execute the requested transaction or command. If the password does not match the password of the logonid, the IMS interface issues the following message: DFSUnnn ACF2/IMS: PASSWORD NOT MATCHED Where DFSUnnn is the IMS message number assigned to the message. The PWMAXVIO field in the IMS OPTS record limits the number of incorrect passwords that a user is permitted in a session. If the user exceeds the password allowance, the IMS interface prevents the user from accessing any IMS interface protected resources, and the following message is displayed: DFSUnnn ACF2/IMS: MAX PASSWORD VIOLATIONS EXCEEDED - SIGNON IS REQUIRED Where DFSUnnn is the IMS message number assigned to the message. At this point, the user can take no other action but to sign off from the terminal. The IMS interface does not support Idle time password reverification during the following types of IMS processing: Conversational transactions Logical paging Transaction input associated with the /SET command Chapter 18: Additional Considerations 211

Using Rule Directories During processing performed for any of the items listed, the IMS interface performs Idle time monitoring but, if Idle time elapses, it does not require users to reenter their passwords. To learn how to define idle time in the IMS OPTS record, see the chapter System Control Options. To learn how to define Idle time in the users' logonid records, see the chapter Defining Logonids. VERIFY Considerations If you specify the VERIFY keyword in a resource rule, CA ACF2 asks the user to reenter his password when access to that resource is attempted. Password reverification with the resource rule VERIFY keyword occurs when it is possible for an operator to enter a password on the terminal screen. For example, password reverification does not occur if a transaction is entering the system with a CHNG call or if an application is issuing an AOI command because the transaction or command is not coming from a terminal and a password cannot be entered. To implement password reverification for format-initiated transactions, define a password field on the screen format definitions. If you do not create a password field, Idle time and VERIFY processing can cause these transactional sequences to be broken. Check with your database administrator to ensure that use of password reverification does not impact desired transactional sequences. If a SYSMSG field is not defined in the format, IMS clears the screen to present any message back to the user. If you want to retain the screen with its information, ensure that the format contains a SYSMSG field. When a terminal user attempts to access an IMS resource (for example, a IMS transaction or command) and the VERIFY keyword was specified in the resource rule, the following message is displayed on the terminal screen: DFSUnnn ACF2/IMS: PASSWORD REVERIFICATION IS REQUIRED Where DFSUnnn is the IMS message number assigned to the message. The operator responses and any subsequent messages are the same as for the Idle time facility. To review the operator procedures for password reverification, see the previous section, Idle Time Considerations. Using Rule Directories To use masking in a resource rule, you must direct CA ACF2 to load a directory for the rule set. These directories can be globally resident or locally resident. You must determine which type of directory to use for your resource rules. 212 IMS Support Guide

Using Rule Directories Loading and Reloading Globally Resident Directories Global directories can be shared among multiple IMS control regions. Therefore, if multiple IMS control regions are using some of the same resource rule sets, you might want to use a globally resident directory. To ensure that the globally resident directory is loaded at CA ACF2 initialization time, you must specify a GSO INFODIR record. Globally resident directories are loaded in the ECSA. Globally resident directories are pageable and, while these directories reduce storage, they can introduce undesirable paging waits. When you modify rules, the changes you make do not take effect until CA ACF2 reloads their associated directory. An operator can dynamically reload globally resident directories with the following command: F ACF2,REBUILD(type) Where type is the type code of the resource rule set. After the globally resident directory has been reloaded, the IMS interface must be notified to disregard any current cache entries that can be invalidated by the resource rule changes. You must notify the IMS interface of the request with the following IMS terminal command: /ACF RESET CACHE For more information about globally resident directories, see your Administrator Guide. Chapter 18: Additional Considerations 213

Maintaining IMS Records Loading and Reloading Locally Resident Directories Locally resident directories cannot be shared among multiple IMS control regions. Therefore, to define a set of resource rules to only one IMS control region, use a locally resident directory for these rules. Locally resident directories are automatically loaded during IMS interface initialization. Locally resident directories are loaded into the ELSQA area and are not pageable. When you modify rules, the changes you make do not take effect until their associated directory is reloaded. You can dynamically reload the locally resident directories with the following IMS terminal command: /ACF RELOAD [ALL type] Where: ALL Indicates that all locally resident resource rule sets are to be reloaded. type Specifies the type code of a particular resource rule set. Maintaining IMS Records When you modify existing IMS records (for example, OPTS, WTO, SIGNON), the changes do not take effect until the IMS control region is restarted. Signing On With The IMS Interface The first interaction that a terminal user usually has with IMS is signing on. From the viewpoint of the IMS interface, signing on is optional. If the terminal user has not signed on to IMS, all resource accesses (for example, transactions) that he attempts are validated using the control region default logonid. If the terminal user has signed on, all resource accesses are validated using the logonid of the terminal user. To sign on to IMS, use one the following formats of the IMS/SIGN command: /SIGN ON logonid password{/newpassword} [GROUP groupname] /SIGN ON logonid password[newpw newpassword] [GROUP groupname] Where: logonid Is the terminal user's CA ACF2 logonid. 214 IMS Support Guide

Signing On With The IMS Interface password Is the current password for the logonid. newpassword Is the optional new password to be assigned to the logonid. groupname Specifies the name of a group that the user wants to associate with for this session. This is an optional keyword. If the GROUP parameter is specified, CA ACF2 validates the group name against resource rules with a type code of TGR to verify that the user can access the group's resources. The GROUP parameter affects data access only if the GROUP logonid field is defined in the ACFFDR as part of the UID concatenation, or if the group name is processed by a user exit. If the UID does include the GROUP value, the UID changes dynamically when the user signs on with a group name that is different from his default group. Subsequent accesses during this session are validated using the changed UID. This can help you streamline your resource administration if you write resource rules that permit access based on the GROUP value in the UID. For more information about using the GROUP parameter, see the chapter Controlling System Entry in the Administrator Guide. Requiring Terminals to Sign On For IMS releases prior to IMS release 9.1, the IMS Security Maintenance Utility (SMU) can be used to control which IMS terminals are required to sign on before any transactions or commands can be entered. The following examples show SMU statements that specify terminals that are required to sign on. )( SIGN Where: STERM STERM terminalname STERM terminalname Is a constant. terminalname Is the name of a logical terminal (LTERM) that are required by IMS to sign on before any work can be initiated. Chapter 18: Additional Considerations 215

Signing On With The IMS Interface In the following example, all terminals are required by IMS to sign on before any work can be initiated. )( SIGN STERM ALL In IMS Release 9.1, and above, the use of SMU definitions to require IMS sign on has been replaced with a change to the TYPE and TERMINAL statements used in the IMS system definition to define IMS terminals. For the TYPE and TERMINAL statement, the new parameter OPTIONS=SIGNON NOSIGNON is used to designate whether the terminal is required to sign on. NOSIGNON is the default. A new parameter SIGNON=ALL in the DFSDCxxx IMS initialization parameters can be used to force all IMS static terminals to sign on. Regardless of IMS release, dynamic (ETO) terminals are always required to sign on. Signing On With an MFS Format IMS provides a sign-on format that is used by default for VTAM terminals that are required to sign on. This format is not sufficient for the IMS interface sign-on processing. You must create an alternate sign-on format that meets the following sign-on requirements. The IMS interface provides a sample MFS format for 3270 type terminals in the SIGNFMT member of the ACF2IMS.ACFMAC data set. You can customize this sample for your site or create your own format and add it to your IMS format libraries. When you customize the sample MFS format or create your own, there are special considerations that should be taken into account for the output format. Your sign-on format MID/MOD names must not begin with DFS. The IMS interface assumes all such formats are IMS system formats and does not interact with them. In response to a sign-on error, the IMS interface returns one error message. For 3270 type terminals this message is valid for the SYSMSG type field. If a 3270 type terminal format is defined, you should define a SYSMSG field to hold the message. On a 3270 type terminal using an MFS format with a SYSMSG field, the sign-on error message appears in the SYSMSG field without disturbing the information currently on the screen. 216 IMS Support Guide

Signing On With The IMS Interface In response to a successful sign-on, the IMS interface can return two messages, an CA ACF2 informational message and an IMS command completion message. The output format should enable these two messages as a multi-segment response. You can use the sample MFS format as a model to provide this support. You can specify NONOTIFY on the IMS SIGNON record to suppress delivery of the CA ACF2 system entry message. If, instead, you want to suppress the CA ACF2 message only for certain users, use the SIGNON exit to control delivery of this message at the terminal level. See the description of this exit in the chapter User Exits for more information about this option. You must ensure that this alternate format is used instead of the default IMS sign-on format. This can be done by specifying the format modname in the FORMAT option of the IMS SIGNON record. This record is documented in the chapter System Control Options. The IMS interface provides a facility for specifying the name of an MFS format to be delivered to the terminal after a successful sign-on. This feature can be used to specify, for example, the name of a menu screen delivered to the terminal after sign-on. The sample presign-on exit contains code that you can use as a model to ensure that users use a formatted screen when they sign on to a valid terminal. You can find the sample presign-on exit in the ACFDCXPS member in the ACF2IMS.ACFMAC data set. Verifying a New Password When a user changes his password by entering the new password in a nondisplay field (as described in the previous section), occasionally the user types the new password incorrectly. The result is that the new password is changed to a value that the user did not intend and does not know. A security administrator is then needed to reset the password. A common method of avoiding this problem is to require that the new password be entered twice when changing passwords. This can be done by turning on new password verification (NPVERIFY) on the IMS SIGNON record. Each of these is a valid format of the sign-on command with new password verification turned on: /SIGN ON logonid password{/newpassword/newpassword} /SIGN ON logonid password [NEWPW newpassword/newpassword] Where: logonid Is the terminal user's CA ACF2 logonid. Chapter 18: Additional Considerations 217

Signing On With The IMS Interface password Is the current password for the logonid. newpassword Is the optional new password to be assigned to the logonid. If the terminal user enters a new password, it must be entered twice. If it is not entered twice, or if the two new passwords do not match, the IMS interface rejects the sign-on. The sample MFS format provided with the IMS interface includes this new password verification field. This sample format is found in ACF2IMS.ACFMAC member SIGNFMT. Changing Sign-on Messages Exit Processing You can use the IMS Greeting Message exit (DFSGMSG0) to control sign-on messages issued to a terminal user. You can change the IMS message or the IMS interface message or messages issued. IMS calls the DFSGMSG0 exit before issuing a message to a user signing on and supplies to the exit a parameter list that includes the following information: Address of the IMS message Address of an alternate buffer The value of the IMS message format The value of the alternate message format Changing the Sign-on Messages The IMS interface interacts with this exit to supply its own messages, if any, at sign-on in the alternate message buffer passed to the exit. If a post-signon format was specified in the PSFORMAT option of the IMS SIGNON record or by the SIGNON exit, the format name is passed to the exit in the alternate message format field. If you want to change the IMS or the IMS interface sign-on messages presented, you must supply your new messages in the alternate buffer. If the IMS interface messages exist in the alternate buffer, be aware that you are overlaying these messages. You must also issue one of the following nonzero return codes: 4-Exit is supplying one message in alternate buffer. 8-Exit is supplying two or more messages in alternate buffer. 12-Send no message, but use the new alternate message format. 218 IMS Support Guide

Understanding Security Implications of the ACF Transaction Accepting the Sign-on Messages If you want to accept the IMS interface or IMS sign-on messages as they are, specify a zero return code in this exit. Automatic Terminal Signon IMS provides the ability to automatically sign on a terminal when the terminal connects to the IMS region. This is done by specifying the OPTION=AUTOSIGN parameter on the TYPE or TERMINAL macro statement that defines the terminal in the IMS system definition (IMS stage 1). For more information about the AUTOSIGN parameter, see the IMS System Definition Guide. When OPTION=AUTOSIGN is specified for normal (non-isc) terminals, the LTERM name is used as the userid and is signed on. For ISC static terminals, the SUBPOOL name is used as the userid instead of the LTERM name. For the automatic signon to succeed, the LTERM or SUBPOOL name must be defined as a logonid to ACF2. For more information about the logonid definition, see "Defining Logonids". Understanding Security Implications of the ACF Transaction The ACF transaction, like most IMS transactions, executes in the IMS regions called message-processing regions. If you use the ACF transaction to perform logonid maintenance from IMS, the MUSASS and MUSUPDT attributes must be defined in the logonid record for the logonid used to start up the message-processing region where the ACF transaction executes. These attributes permit the ACF transaction to check the authority of the person making the logonid maintenance request and to update the CA ACF2 Logonid database. Because these attributes represent a significant level of privilege for the message processing region logonid, you should consider using the SUBAUTH and PROGRAM attributes to protect the logonid from unauthorized use. For a complete discussion of message processing region logonids, see the chapter Defining Logonids. Chapter 18: Additional Considerations 219

//*JOBF ROM state ment is as follows: Supporting Transactions that Submit Jobs The MUSASS and MUSUPDT privileges specified for the message processing region logonid are implicitly assumed by any transaction running in the message-processing region. This is necessary for the ACF transaction to function properly. However, it is a security exposure if these privileges are assumed by other application transactions that can run in the region. For this reason, we recommend that one or more message processing regions, with the MUSASS and MUSUPDT privileges, be defined as dedicated to running the ACF transaction. This can be accomplished using the following procedure: 1. In the IMS system definition (stage 1 input) for the ACF transaction, your IMS systems programmer should assign a unique transaction class to the ACF transaction. The transaction class is defined using the MSGTYPE parameter of the TRANSACT statement or the PGMTYPE parameter of the APPLCTN statement in the transaction definition. (See the chapter Installation Procedures, Step 12: Update IMS System Definition.) No other transaction should be defined in this transaction class. 2. Your IMS database administrator or systems programmer should create one or more message processing regions that are defined to service only this transaction class. The logonids used to start these message processing regions are the only message processing region logonids that require the MUSASS and MUSUPDT privileges. With this IMS system definition, only the ACF transaction will execute in the privileged message processing regions. You should be aware that the IMS /ASSIGN command can override these system definitions. Anyone with the authority to use the /ASSIGN command can reassign transaction classes and region service classes and thereby permit other transactions to run in the privileged message processing regions. Consult your IMS systems programmer or database administrator to determine who has the authority to use the /ASSIGN command and how to secure it. Supporting Transactions that Submit Jobs To support a transaction that submits jobs to JES (Job Entry Subsystem), the message processing region logonid must have the JOBFROM attribute. This logonid is specified in the message processing region's JCL. The JOBFROM attribute indicates that jobs running under this logonid have the authority to submit jobs on behalf of other users. The transaction that is to submit jobs must insert the //*JOBFROM statement immediately after the JOB statement of the submitted JCL. The format of the 220 IMS Support Guide

Supporting the AUTH Call with the IMS Interface //*JOBFROM logonid {source} The logonid can be obtained from the IMS IOPCB control block by a message-processing program. To learn how to use this control block, see the IBM IMS Application Programming: Transaction Manager. This manual refers to the logonid as the user ID. An example of source in the //*JOBFROM statement is an IMS logical terminal (LTERM). For more information about the //*JOBFROM statement, see your Systems Programmer Guide. Also, you can consult with your database administrator to determine those transactions that submit jobs. Supporting the AUTH Call with the IMS Interface The principal source for technical information for the AUTH call is the documentation provided by IBM. This section is intended to supplement that documentation and to describe how the IMS interface supports the AUTH call. AUTH Call The AUTH call is an IMS security call available to IMS online application programs that provides a way for sites to develop application-based security processing using the IMS interface. The principal problem for applications with security requirements has been that IMS and the IMS interface security is concentrated in the IMS control region. The application program, which is running in a dependent IMS region, has had no access to these security mechanisms. Some sites with application security requirements have developed alternative security systems that are entirely application based and that do not interact with IMS or CA ACF2 security. Other sites, to keep their security processing under CA ACF2 control, have chosen other alternatives, such as CA ACF2 Note 13. Each of these alternatives has its drawbacks. The AUTH call makes the IMS interface security processing accessible to application programs. When the application program needs to make a security decision, such as whether a user should have access to a particular subfunction or field, it can prepare and issue an AUTH call to IMS. The AUTH call is processed by the IMS and the IMS interface security mechanisms that are in place in the IMS control region. The results of the security processing are returned to the application program, which can tailor its processing based on the results of the security decision. Up to 1024 bytes of information can also be returned to the application program with the results of the AUTH call. This information is returned only when the results of the security processing indicate that the access is permitted. Chapter 18: Additional Considerations 221

Supporting the AUTH Call with the IMS Interface Issuing the AUTH Call The AUTH call is issued by the IMS application program using the IO-PCB, the AUTH call function, and a program work area. The information that controls the AUTH call is formatted in the program work area before the call. The format for the program work area that is described in the IBM AUTH call documentation is designed to interact with RACF support code in IMS. In an CA ACF2 IMS interface environment, the format of the program work area is more flexible and the processing that can be performed is more varied. The format of the AUTH call program work area in an IMS interface environment is: 2 bytes 2 bytes 8 bytes Standard LL length field containing the length of the work area. Binary zeros. Resource class field. Possible values are: LL-12 bytes TRAN DATABASE SEGMENT FIELD OTHER The remainder of the work area is available for use by the customer site. The IMS support code for the AUTH call requires that the resource class field be set to one of the five aforementioned values. The IMS interface support for the AUTH call does not affect this requirement. However, it does not use this field to determine the kind of resource being validated. This provides a greater flexibility in the kinds of resources that can be validated and the security processing that can be performed. There is another limitation in the format for the program work area in an IMS interface environment. Bytes 21-28 of the program work area must not contain the value USERDATA. These bytes correspond to the AUTH call qualifier field in the RACF fixed format for the program work area. If the string USERDATA is encountered in this area, IMS support code intended specifically for RACF is executed. In an CA ACF2 IMS interface site, this causes an error. 222 IMS Support Guide

Supporting the AUTH Call with the IMS Interface IMS Interface Processing of the AUTH Call The AUTH call passes through the IMS interface security processing as far as the interface prevalidation exit. (For more information about the prevalidation exit, see the chapter User Exits ) The prevalidation exit is passed all the information about the AUTH call, including the AUTH call program work area. The exit program, using this information, must do one of two things: It can make the validation decision itself, permit or deny the resource access. It can supply to the IMS interface the resource key (resource type code and name) that are used for the validation. If no prevalidation exit exists, or if the exit does not implement one of these two alternatives, the IMS interface indicates to the application program that the resource access should be denied. If the prevalidation exit program does supply the resource key, the resource validation is done. The results of the resource validation are returned to the application program. If the resource access is permitted, the IMS interface prevalidation and postvalidation exit programs can return to the application program up to 1024 bytes of information in the USERDATA field of the program work area. The format of the program work area returned to the application program is described in the next section. To return the USERDATA information, the exit program must do the following: Ensure that the length of the information moved to the USERDATA field, plus the length of the rest of the program work area, does not exceed the length of the allowable program work area as defined in the IMS PSB definition. The maximum length of the work area provided can be found in the PSTXWASZ field of the IMS PST. Move the information to the USERDATA field in the program work area. Set the length of the information moved to the USERDATA field, plus two for the length of the LL field itself, in the USERDATA LL length field. Indicate to the IMS interface that USERDATA has been returned by setting the XPVF2AUD indicator in the exit control parameter list. Information Returned to the Application Program The results of the AUTH call are returned to the application program in the program work area. The format of the program work area that is returned to the application program is: 2 bytes 2 bytes Standard LL length field containing the length of the work area returned. Binary zeros. Chapter 18: Additional Considerations 223

Supporting the AUTH Call with the IMS Interface 2 bytes 2 bytes 2 bytes 16 bytes 2 bytes n bytes Return code from RACF (are zeros). Return code from the IMS interface. Values are: 0-AUTH call passed validation 8-AUTH call failed validation Code indicating status of user data. Values are: 0-USERDATA returned by RACF 4-USERDATA returned by user exit 12-No USERDATA available 16-USERDATA was not requested Unused and reserved for future use. LL length field of USERDATA, including LL field. USERDATA returned (up to 1024 bytes). If the IMS interface security validation determines that the resource access requested by the AUTH call should be denied, a return code of eight is returned to the application program in the program work area and a status code of A4 is returned in the status code field of the IO-PCB. If the IMS interface security validation determines that the resource access requested by the AUTH call should be permitted, a return code of zero is returned to the application program in the program work area and a status code of spaces is returned in the status code field of the IO-PCB. Optionally, the IMS interface prevalidation and postvalidation exit programs can return information to the application program in the USERDATA field of the program work area. 224 IMS Support Guide

Chapter 19: Storage This chapter provides the general storage requirements of the IMS TM Interface. It describes the function of the options in the STORAGE record that affect the IMS interface storage use. The last section of this chapter outlines the process of tuning these storage options. This chapter is intended for the person responsible for the impact the IMS interface storage requirements in the IMS control region and in the z/os operating system. It is written with the assumption that the reader is familiar with data processing terms and concepts.` This section contains the following topics: Design Concepts and Features (see page 226) Storage Utilization (see page 228) The Storage Record (see page 230) Tuning the IMS Interface Storage Allocations (see page 233) Chapter 19: Storage 225

Design Concepts and Features Design Concepts and Features Pool Processing During initial and secondary storage allocation, the IMS interface obtains storage and preformats the storage into a group of control block areas that are used for IMS interface processing. This group of preformatted control block areas is referred to as a storage pool. Control blocks are used for processing and returned to the storage pool after processing is complete. For example, if a program needs a work area, the work area is returned to the work area pool after the program finishes execution. Storage pools reduce the overhead associated with requesting storage from the z/os storage manager because the pools are allocated to the IMS interface until it is terminated. Each storage pool is controlled by allocation parameters specified on the IMS STORAGE record, for example: SAVEPOOL(nn mm) Where: nn mm Primary or initial allocation of save areas in the pool. Secondary allocation of save areas in the pool. During the IMS interface initialization, for each pool, the number of areas specified as the primary allocation value in the IMS STORAGE record are obtained. During subsequent IMS interface processing, if all areas in a pool are currently in use and additional storage is needed, it obtains a secondary allocation of storage areas using the secondary allocation value specified in the IMS STORAGE record. If the secondary allocation is zero or if the IMS interface is unable to obtain the storage for the secondary allocation, the request that it is processing is refused with a message indicating insufficient storage for IMS interface processing. The only exception to this rule is the save area pool. If the IMS interface is unable to obtain a save area from the save area pool, it abnormally terminates the IMS control region. Generally, storage obtained for secondary allocations of pool areas is not returned to z/os. After it is allocated, the secondary allocation of storage is dedicated to the storage pool until the IMS control region is terminated. But, if a secondary allocation of 1 is specified for a work area pool, the storage obtained for the secondary allocation is not added to the storage pool and is returned to z/os when the request being processed has completed. Situations in which this allocation and deallocation might be useful are explained in the Tuning the IMS Interface Storage Allocations section later in this chapter. 226 IMS Support Guide

Design Concepts and Features Types of Storage Area Pools There are five types of storage area pools that are used with the IMS interface. Each type of pool is described in this section to provide you with a thorough understanding of the concept of the IMS interface storage pools. Save Areas A critical piece of storage used when one IMS interface program calls another IMS interface program. When one program calls another program, it is the responsibility of the calling program to pass a 72-byte save area to the receiving program. The receiving program saves the values of the registers in the save area before it changes any of the registers. IPB Extensions A permanently assigned to each terminal that communicates with the IMS control region. These IPB extensions are the IMS interface equivalent of the IMS IPBs. Cache Areas Created for every user who is signed on to the system. The cache area is used with the cache facility to speed up validation processing. The cache area contains a copy of the ACMCB and the MLID for the user and as many cache entries as are allocated by the site. (See the CACHENT# field described later in this chapter.) Each cache entry contains the 44-byte resource key of a resource to which access has been permitted. The size of the cache area differs from one site to another, depending on the length of the ACMCB and MLID and how many cache entries are requested. Default Cache Areas If a resource request is granted for a terminal that is not signed on, the IMS interface creates a cache for the control region default logonid at that terminal. The cache area is used with the cache facility to quicken validation processing. Default cache areas contain as many cache entries as are allocated by the site. (See the CACHENT# field described later in this chapter.) Each cache entry contains the 44-byte resource key of a resource to which access has been permitted. The size of the default cache area differs from one site to another, depending on how many cache entries are requested. System Work Areas There are four system work area pools. Small (256 bytes) above-the-line work areas Large (1,024 bytes) above-the-line work areas* Small (256 bytes) below-the-line work areas Large (1,024 bytes) below-the-line work areas *The default size for these work areas is 1,024 bytes. If the IMS interface determines, during initialization, that 1,024 bytes is too small to handle the required processing, a larger size sufficient for the processing is chosen. Chapter 19: Storage 227

Storage Utilization Storage Utilization CA ACF2 Storage Requirements The following figure illustrates the approximate amount of storage that is obtained by CA ACF2 in support of the IMS interface. Component Size/Number Location* CA ACF2 control blocks 1.3K ELSQA Resource directory 32 + (13 x number of resource rules) ELSQA/ECSA Resource rules 300 x number of resource rules ELSQA/ECSA *The resource directory and resource rules are located in the ELSQA if the resource rules are local, and in the ECSA if the resource rules are global. For detailed information about local and global directories, see the chapter Additional Considerations. IMS Interface Storage Requirements The following figure shows the approximate amount of storage that is required by the IMS interface. The amount of storage used by the IMS interface varies from site to site.to obtain numbers that are more reliable, use the /ACF SHOW STORAGE command in the chapter ACF Command. Component Size/Number Location Programs alone Fixed control blocks Variable control blocks Approximately 60K 3K 3K 1K Extended Private ECSA Private area Extended private 228 IMS Support Guide

Storage Utilization Component Size/Number Location Default LID Length of ACMCB + length of MLID Save area pool 72 x number of save areas allocated* IPB extensions 48 x number of IPB extensions allocated* Cache areas Length of cache area** x number of cache areas allocated* Default cache areas Length of cache area**** x number of cache areas allocated* Extended private Extended private Extended private Extended private Extended private System work areas WKA1POOL 256 x number allocated* Extended private WKA2POOL 1024*** x number allocated* Extended private WKB1POOL 256 x number allocated* Private WKB2POOL 1024 x number allocated* Private *Recommendations for the initial allocations for these control blocks are given in subsequent sections of this chapter. If the IMS interface detects during execution that more control blocks are needed, unless specifically told not to (secondary allocation of 0), it obtains as many of these control blocks as are required to process. **The length of the cache area is an 8-byte header plus the length of the ACMCB and MLID plus the result of multiplying 44 times the number of cache entries requested in the IMS STORAGE record. ***The default size for these work areas is 1,024 bytes. If the IMS interface determines, during initialization, that 1,024 bytes is too small to handle the required processing, a larger size sufficient for the processing is chosen. ****The length of a default cache area is an 8-byte header plus the result of multiplying by 44 times the number of cache entries requested in the IMS STORAGE record. Chapter 19: Storage 229

The Storage Record The Storage Record The IMS STORAGE record is used to specify the IMS interface subsystem options that affect IMS interface storage utilization. The following discussion describes how to create IMS STORAGE records: INSERT DIVISION(musid jobname) STORAGE - [CACHENT#(10 nnn)] [CACHPOOL(20,5 nnnnn mmmmm)] - [IPBXPOOL(20,5 nnnnn mmmmm)] [DFTCIDLE(0 mm)] [DFTCSCAN(0 mm)] - [DFTCPOOL(0,0 nnnnn mmmmm)] - [DFTSCAN(0 nn,mm) [SAVEPOOL(20,5 nnnnn mmmmm)] - [WKA1POOL(20,5 nnnnn mmmmm)] - [WKA2POOL(20,5 nnnnn mmmmm)] - [WKB1POOL(20,5 nnnnn mmmmm)] - [WKB2POOL(20,5 nnnnn mmmmm)] REP CACHENT#(10 nnn) Specifies the number of 44-byte resource cache entries in the user cache area. Possible values are 1 to 255. Each entry holds the key of a resource to which the user has been given access. CACHPOOL(20,5 nnnnn mmmmm) Specifies the primary and secondary allocation of cache areas that are used for terminals that are signed on. The variable nnnnn is the primary or initial allocation of cache areas in the pool. Possible values are 1 to 32767. The primary allocation should be set to the maximum number of concurrent signed-on terminal users plus the maximum number of users queued on MSC, APPC, and OTMA network links that inherit the sending logonid plus the maximum number of dependent regions (message processing regions and BMPs). The variable mmmmm is the secondary allocation of cache areas in the pool. Possible values are 1 to 32767. IPBXPOOL(20,5 nnnnn mmmmm) Specifies the primary and secondary allocation for IPB extensions. The variable nnnnn is the primary allocation of IPB extensions. Possible values are 0 to 32767. A IPB extension is permanently assigned to every terminal that communicates with the IMS control region. The primary allocation should be set to the number of terminals you expect to communicate with the IMS control region, plus the maximum number of users queued on MSC, APPC, and OTMA network links that inherit the sending logonid plus the maximum number of dependent regions (message processing regions and BMPs). The variable mmmmm is the secondary allocation for IPB extensions. Possible values are 0 to 32767. 230 IMS Support Guide

The Storage Record DFTCPOOL(0,0 nnnnn mmmmm) Specifies the primary and secondary allocation of the cache areas. The variable nnnnn is the primary or initial allocation of cache areas in the pool that can be used for access requests from terminals that are not signed on. Possible values are 0 to 32767. If 0 is specified for the primary allocation, no caching is done for terminals that do not sign on. The variable mmmmm is the secondary allocation of cache areas in the pool. Possible values are 0 to 32767. DFTCIDLE(0 mm) Specifies the number of minutes that a non-signed on terminal can be idle before the IMS interface determines that the terminal is inactive. This parameter is used with the DFTCSCAN parameter to free caches that are associated with non-signed on terminals that are no longer active. If the field is set to 0, no idle processing of non-signed on terminals will occur. DFTCSCAN(0 mm) Specifies the number of minutes that must elapse between the times that the IMS interface scans non-signed on terminals to determine whether their idle time has expired. It performs this scan only when no cache areas are available for non-signed on terminals before a secondary allocations is attempted. If it determines that there are no more cache areas available and that the scan time has elapsed, it 1. Locates the non-signed on terminals that have exceeded their idle time (specified in the DFTCIDLE parameter) 2. Frees the caches associated with these terminals. SAVEPOOL(20,5 nnnnn mmmmm) Specifies the primary and secondary allocations for save areas. The variable nnnnn is the primary allocation for the number of save areas that the IMS interface needs to execute. This number varies, depending on the size of your IMS network and the workload of your IMS control region. Possible values are 1 to 32767. A discussion about tuning the allocation parameters is included later in this chapter. The variable mmmmm is the secondary allocation for the number of save areas. Possible values are 1 to 32767. Note: Do not specify a secondary allocation of zero for the save area pool. If the IMS interface cannot obtain a save area, the IMS control region is terminated. Chapter 19: Storage 231

The Storage Record WKA1POOL(20,5 nnnnn mmmmm) Specifies the primary and secondary allocation for the 256-byte above-the-line work area for the IMS interface programs. The variable nnnnn is the primary allocation for this work area. Possible values are 1 to 32767. The variable mmmmm is the secondary allocation for this work area. Possible values are 1 to 32767. If a secondary allocation of 1 is specified for this work area pool, the storage obtained is not added to the storage pool; it is returned to z/os when the request being processed has completed. Situations in which secondary allocation is useful are explained in the Tuning CA-ACF2 IMS Storage Allocations section later in this chapter. The number of work areas the IMS interface needs to execute varies depending on the size of the IMS network and the workload of your IMS control region. A discussion about tuning the allocation parameters is included later in this chapter. WKA2POOL(20,5 nnnnn mmmmm) Specifies the primary and secondary allocation for the 1024-byte above-the-line work area for the IMS interface programs. The variable nnnnn is the primary allocation for this work area. Possible values are 1 to 32767. The variable mmmmm is the secondary allocation for this work area. Possible values are 1 to 32767. If a secondary allocation of 1 is specified for this work area pool, the storage obtained is not added to the storage pool; it is returned to z/os when the request being processed has completed. Situations in which secondary allocation is useful are explained in the Tuning CA-ACF2 IMS Storage Allocations section later in this chapter. The number of work areas the IMS interface needs to execute varies depending on the size of the IMS network and the workload of your IMS control region. A discussion about tuning the allocation parameters is included later in this chapter. WKB1POOL(20,5 nnnnn mmmmm) Specifies the primary and secondary allocations for 256-byte below-the-line work area for the IMS interface programs. The variable nnnnn is the primary allocation for this work area. Possible values are 1 to 32767. The variable mmmmm is the secondary allocation for this work area. Possible values are 1 to 32767. If a secondary allocation of 1 is specified for this work area pool, the storage obtained is not added to the storage pool; it is returned to z/os when the request being processed has completed. Situations in which secondary allocation is useful are explained in the Tuning CA-ACF2 IMS Storage Allocations section later in this chapter. The number of work areas the IMS interface needs to execute varies depending on the size of the IMS network and the workload of your IMS control region. A discussion about tuning the allocation parameters is included later in this chapter. 232 IMS Support Guide

Tuning the IMS Interface Storage Allocations WKB2POOL(20,5 nnnnn mmmmm) Specifies the primary and secondary allocations for 1024-byte below-the-line work area for the IMS interface programs. The variable nnnnn is the primary allocation for this work area. Possible values are 1 to 32767. The variable mmmmm is the secondary allocation for this work area. Possible values are 1 to 32767. If a secondary allocation of 1 is specified for this work area pool, the storage obtained is not added to the storage pool; it is returned to z/os when the request being processed has completed. Situations in which secondary allocation is useful are explained in the Tuning CA-ACF2 IMS Storage Allocations section later in this chapter. The number of work areas the IMS interface needs to execute varies depending on the size of your IMS network and the workload of your IMS control region. A discussion about tuning the allocation parameters is included later in this chapter. Tuning the IMS Interface Storage Allocations CACHENT# Option The CACHENT# option controls the number of resource entries in the user cache area. The purpose of tuning this option is to reach an appropriate balance for your site between storage use (and associated effects, such as system paging) and the IMS interface system performance. If you specify zero for the CACHENT# option, there is no session cache for users of the IMS system. Every resource validation requires an interaction with CA ACF2 and the associated overhead. For each increment of one you specify for the CACHENT# option, the storage requirements for the IMS interface increase by an approximate value (in bytes) of 44 times the number of user cache areas allocated (CACHPOOL + DFTCPOOL). Choosing an appropriate value for the CACHENT# option requires an understanding of your z/os system's storage and performance profile. If your site has adequate paging resources, a large value provides the best performance. If your site is storage or paging constrained, but with adequate processing power, a lower value is appropriate. One method of tuning the CACHENT# option is to choose a low to moderate value until the tuning of the other IMS interface storage options has stabilized. Increase the value until you notice a negative impact on IMS or z/os virtual storage or until you reach an acceptable level of performance. Another method for tuning this option, given sufficient storage, is to choose as a value the number of high-use transactions for your average or critical IMS users. This method provides optimal performance without wasting storage on unnecessary cache entries. Chapter 19: Storage 233

Tuning the IMS Interface Storage Allocations IMS Interface Storage Pools The idea behind using storage pools in the IMS interface subsystem is to improve system performance by reducing the overhead associated with frequent interactions with the z/os storage manager (GETMAIN/FREEMAIN). If the allocation parameters for the storage pools are kept unnecessarily low, the number of these interactions with the z/os storage manager increases and the performance enhancement offered by the storage pools is reduced. If the allocation parameters are kept unnecessarily high, storage is allocated to the pools that are never used. The allocation options for the IMS interface storage pools control the number of entries obtained for the storage pool during primary (initialization) and secondary allocation. The primary allocation is the initial, not the total, number of entries obtained for a storage pool. The secondary allocation controls the number of entries that the IMS interface obtains and adds to the storage pool when it determines, during processing, that all currently allocated entries in the pool are in use and more are needed for processing to continue. Unless specifically told not to (with a secondary allocation of 0), the IMS interface obtains as many storage entries in each storage pool as it requires to run. In most cases, this storage remains dedicated to the IMS interface storage pool until the IMS control region is terminated. The storage is not returned to z/os. But, if a secondary allocation of 1 is specified for a work area pool, the storage obtained for the secondary allocation is not added to the storage pool and is returned to z/os when the request being processed has completed. When the IMS interface determines that all currently allocated entries in a storage pool are in use, if the secondary allocation for the storage pool is zero or if the request (GETMAIN) for the secondary allocation fails, it denies whatever request it is processing with a message indicating insufficient storage. The only exception to this rule is secondary allocation for the save area pool. If the IMS interface is unable to obtain a save area, it terminates the IMS control region. Appropriate primary allocations can be approximated for the CACHPOOL and IBXPOOL options. The CACHPOOL option controls the allocation of user cache areas that are assigned to IMS users as they sign on and returned to the pool when they sign off. The primary allocation should be set to the maximum number of concurrent signed-on terminal users, plus the maximum number of users queued on MSC, APPC, and OTMA network links that inherit the sending logonid plus the maximum number of dependent regions (message processing regions and BMPs). The IPBXPOOL option controls the allocation of IPB extension areas. A IPB extension is permanently assigned to a terminal when the terminal first communicates with the IMS control region. The primary allocation should be set to the number of terminals that you expect to communicate with the IMS control region, plus the maximum number of users queued on MSC, APPC, and OTMA network links that inherit the sending logonid plus the maximum number of dependent regions (message processing regions and BMPs). 234 IMS Support Guide

Tuning the IMS Interface Storage Allocations Appropriate primary and secondary allocations for the remaining storage pools, the save area pool (SAVEPOOL), and work area pools (WKxxPOOL), varies from site to site, depending on the workload of the IMS control region. The only way to select appropriate allocations is to tune the allocation parameters using the following method: The IMS interface storage pool allocations should be monitored for a representative period of time, involving a number of IMS runs. You can monitor the storage pool allocations with the /ACF SHOW STORAGE command that is explained in the chapter ACF Command. For the tuning process, the operative fields in the pool allocation display are the high water mark, that is, the highest number of entries in the storage pool that were in concurrent use and the current in-use count. If, over a representative period of time, the high water mark remains fairly consistent from run to run, that number is an appropriate choice as the primary allocation for the storage pool and you should choose a small secondary allocation. If the high water mark fluctuates from run to run, then the lowest number of pool entries is an appropriate choice for the primary allocation and the secondary allocation should be large enough to obtain, in only a few iterations, the highest number of pool entries that were experienced. This method of tuning the storage pool allocations ensures that the IMS interface performance is optimal, that sufficient storage is obtained for IMS interface processing, and that unnecessary storage is not obtained and dedicated to the IMS interface. An exception to this tuning algorithm is when the current in-use count for a work area pool remains consistent, and is consistently and substantially lower than the high water mark. This is indicative of a system that experiences an isolated high peak of IMS interface activity. Storage is obtained to handle the peak activity and remains dedicated to the storage pool, but is not used during normal activity. In this case, choosing appropriate values for the pool allocation parameters requires an understanding of your z/os and IMS system's storage and performance profile. If your IMS region has adequate storage, and performance during peak activity is a concern, the work area pool allocations should be selected as described previously. If your system has adequate processing power, but the IMS system is constrained in the type of storage (above or below the line) used for the work area pool, an appropriate choice for the primary allocation for the storage pool is the most frequent in-use count, with a secondary allocation of 1. The secondary allocations to handle the peak activity are obtained from and returned to z/os storage, and not dedicated to the storage pool. This results in slightly poorer performance during peak activity, but unnecessary storage is not dedicated to the work pool during normal processing. Chapter 19: Storage 235

Chapter 20: Installation Procedure This chapter describes how to install the IMS interface. All z/os, CA ACF2, IMS interface, and IMS considerations are discussed. A checklist that lists the tasks necessary to complete the IMS interface installation is provided. Detailed information regarding each step of installation follows the checklist. Prerequisite installation planning is necessary before you begin the installation tasks. This release of the IMS interface executes on the CA ACF2 base product r15 and above. This chapter assumes that the reader is a systems programmer and is familiar with systems programming terms and concepts. This section contains the following topics: Pre-Installation Requirements (see page 237) Packaging Considerations (see page 238) Design Concepts and Features (see page 239) How You Acquire the Product (see page 240) Installation Checklist (see page 240) Detailed Installation Instructions (see page 242) Pre-Installation Requirements Before proceeding with the actual IMS interface installation, you must review and complete the tasks listed in the chapter Planning Considerations that contains a detailed checklist of the tasks that you should complete before you begin the installation steps listed and described in this chapter. Your software must meet these minimum requirements to operate this release of the IMS interface: IMS release 9.1 or above CA ACF2 r15 or above Any supported IBM release of z/os Chapter 20: Installation Procedure 237

Packaging Considerations Packaging Considerations As part of the adoption of Mainframe 2.0 initiatives, CA ACF2 installation has been simplified in r15. If you use the IMS interface, you need to be aware of these changes and how they impact you. CA product packaging and installation procedures have been standardized and simplified. Data set naming conventions have been modified to facilitate these procedures. Additionally, a single set of installation procedures and jobs is now used for all of CA ACF2, including required components such as the base CA ACF2 product, JES2/JES3 support components, and the optional CICS, IMS, and batch IMS interfaces. The CA ACF2 IMS Interface has been further simplified so that only a single SMP/E function modifier (FMID) needs to be installed to provide support for all supported IMS releases. This means that your systems programmer can now install all required CA ACF2 components needed for your installation using a single set of installation jobs that are executed one time, using a common install environment. CA recommends that all desired optional interfaces, including the CA ACF2 IMS interface, be installed in this manner. CA offers three CA ACF2 installation paths which accommodate a wide-ranging variety of customer needs and requirements. They are: CA CSM installation PAX-Enhanced ESD installation Physical tape media installation The IMS interface installation process can be divided into two general steps: SMP/E product installation Product configuration and deployment You will find the detailed installation procedures for the SMP/E product installation steps documented within the CA ACF2 Installation Guide. CA recommends that you install the IMS Batch interface at the same time that you install the CA ACF2 product. The steps that follow in this chapter cover the IMS interface configuration and deployment procedures that are necessary once SMP/E installation has been completed. If you are not sure if the IMS interface has been installed at your installation, please consult with the systems programmer responsible for installation of CA ACF2. 238 IMS Support Guide

Design Concepts and Features Design Concepts and Features This section provides an overview of the installation procedure and a description of the ACFFDR values relevant to the IMS interface. Overview of the Installation Procedure There are four major tasks that must be addressed during the installation. A brief description of each task is provided to give you an overview. IMS Interface Software Installation The first task in the installation is to create the IMS interface software libraries from the distribution tape. z/os Requirements There are specific modifications to z/os that must be completed for the IMS interface installation. This second task prepares the z/os operating system for IMS interface installation. CA ACF2 Modification There are some specific CA ACF2 system modifications necessary to complete the IMS interface installation. The third task makes the changes necessary for the IMS interface installation. IMS Requirements The fourth and final task completes the IMS interface installation. It sets up IMS for the IMS interface installation. ACFFDR Values Relevant to the IMS Interface You might have to add or modify some macros in the ACFFDR. A detailed description of these macros and the ramifications of changing them appear later in this chapter, in Detailed Installation Instructions. A brief overview of the macros appears below. See the Implementation Guide if you require more information. @MLID ACFFDR Macro The @MLID macro specifies a set of logonid record field names. CA ACF2 uses these logonid record fields to create a minilogonid record, also called an MLID, for every person who signs on to the IMS control region. The MLID is used in the same fashion as the ACMCB; each MLID contains the minimum number of logonid record fields that CA ACF2 needs to validate access requests and still provide full CA ACF2 security controls. Using an MLID rather than a full logonid record results in greatly reduced storage requirements. CA ACF2 builds and maintains each user's MLID in the same manner it maintains the ACMCB. Chapter 20: Installation Procedure 239

How You Acquire the Product @MUSASS ACFFDR Macro The support provided by the optional @MUSASS macro in an IMS interface environment includes: Allocating a dedicated work area for CA ACF2 TYPE=A SVC. The TYPE=A SVC performs all resource validations in an IMS interface environment. Specifying the name of an @MLID ACFFDR macro used for the IMS region. If there is no reference to the MLID, the full logonid record is used and storage requirements increase substantially. @CFDE ACFFDR Macro The @CFDE defines an external field name and related internal characteristics and attributes for a field contained in a structured CA ACF2 record, such as a logonid record. How You Acquire the Product You can install the CA ACF2 IMS interface using one of the following methods: Using CA Chorus Software Manager (CA CSM), which is an application with a web-based user interface (UI) that helps you download, install, and maintain z/os products, and provides a unified view of the products. Note: If you do not have CA CSM, you can download it using Electronic Software Delivery (ESD). For more information about CA CSM, see the CA CSM User Guide. Using Electronic Software Delivery (ESD), which lets you download the interface from the Technical Support Download Center at CA Support Online (http://ca.com/support). Note: For more information about Electronic Software Delivery, see the Pax Enhanced Electronic Software Delivery Guide located on CA Support Online (http://ca.com/support) for further instruction. From a physical CA ACF2 installation tape. Installation Checklist CA CSM automates the allocation and customization of the SMP/E environment and the SMP/E RECEIVE, APPLY, and ACCEPT installation process. If you used CA CSM to download your product, begin the installation procedure at step 5. The Pax Enhanced ESD download process automates the unload of the SAMPJCL installation JCL data set. If you used the ESD download process to download your product, prepare the pax file and begin the installation procedure at step 2. In addition, see the applicable Product Information Bulletin (PIB) and the Pax Enhanced ESD User Guide located on CA Support Online. 240 IMS Support Guide

Installation Checklist Prepare the z/os System for the CA ACF2 IMS Installation To prepare the z/os system for the CA ACF2 IMS installation, add the IMS interface load library to the z/os APF list in SYS1.PARMLIB(IEAAPFxx) or SYS1.PARMLIB(PROGxx). Complete the CA ACF2 Requirements To complete the CA ACF2 requirements: 1. Update and run CAI.CAX1JCL2(IMSAPLDF) to create the definitions of the IMS interface infostorage records. 2. Activate the definitions. 3. Although not required, we strongly recommend that you make updates to the ACFFDR for the @MUSASS and @MLID macros, and any @CFDE changes that your site might require. Install the IMS Interface in an IMS Control Region To install the IMS interface in an IMS control region, complete the following: 1. Create or update the IMS user messages table. 2. If SMU is used for TERMINAL, PASSWORD, or TRANCMD security, install usermod SMUMOD1 to define the /ACF command to IMS. 3. Update the IMS Stage 1 system definition. 4. Run IMS System Definition. 5. If SMU is used for TERMINAL, PASSWORD, or TRANCMD security, install usermod SMUMOD2 to update the IMS command table. 6. Link the ACFDCACT program and generate a PSB for the ACFDCACT program. 7. Generate the MFS format for formatted IMS sign-on. 8. If you are running an IMSplex environment and have a requirement to enter the /ACF command through OM and route it to multiple IMS regions in the IMSplex, install usermod IMSUM0D1 to update the IMS OM command table. 9. Before proceeding with the next step, be sure that your security administrator has created or modified the IMS interface subsystem options, logonids, and resource rules. 10. Update the IMS control region parameters and JCL. Chapter 20: Installation Procedure 241

Detailed Installation Instructions Detailed Installation Instructions CA CSM automates the allocation and customization of the SMP/E environment and the SMP/E RECEIVE, APPLY, and ACCEPT installation process. If you used CA CSM to download your product, begin the installation procedure at step 5. The Pax Enhanced ESD download process automates the unload of the SAMPJCL installation JCL data set. If you used the ESD download process to download your product, prepare the pax file and begin the installation procedure. In addition, see the applicable Product Information Bulletin (PIB) and the Pax Enhanced ESD User Guide located on CA Support Online. Make IMS Interface APF-Authorized Add the IMS interface target load library CAI.ACF2IMS.CAX1IMS to the z/os APF list in SYS1.PARMLIB(IEAAPFxx) or SYS1.PARMLIB(PROGxx). Create or Update the IMS Interface APPLDEF Records Update and run CAI.ACF2IMS.CAX1JCL2(IMSAPLDF) to create or update the definitions of the IMS interface infostorage records. Activate the definitions. The CAI.ACF2IMS.CAX1JCL2(IMSAPLDF) job defines the structure of the IMS interface infostorage records to CA ACF2. You must activate these definitions prior to the start of the control region. To activate the definitions, enter the following from the operator console: F ACF2,REFRESH(APPLDEF) Only one IMS APPLDEF record can be used by CA ACF2. If you are running a previous release of the IMS interface, you must replace the GSO APPLDEF record created during the previous installation with the GSO APPLDEF record created by this job. This GSO APPLDEF record is compatible with previous releases. For more information about APPLDEF records, see Structured Infostorage Record Definitions (APPLDEF) in the chapter Maintaining Global System Options Records in the Administrator Guide. If you change the SELAUTH(ALL) specification in the IMS APPLDEF record, you must ensure that the IMS control region logonid has at least one of the privileges you specify in the SELAUTH field, or the IMS control region is unable to read its options records. 242 IMS Support Guide

Detailed Installation Instructions Customize ACFFDR Although not required, we strongly recommend that you make updates to the ACFFDR for the @MUSASS and @MLID macros, and any @CFDE changes that your site might require. To accomplish these updates, we recommend that you use CAI.ACF2.ACFPTFS(UM99901). If you do not use the USERMOD, you must assemble and link the ACFFDR. See the following information for more about ACFFDR macro values relevant to the IMS interface. You can find additional information about ACFFDR values in the Installation Guide. @MUSASS Considerations We recommend that you specify an @MUSASS ACFFDR macro for each IMS control region logonid. The @MUSASS macro defines how CA ACF2 interacts with a MUSASS system, including the minilogonid definition and work area conventions. To correctly use the @MUSASS, the ID operand (specified in the @MUSASS macro) must match the CA ACF2 logonid of the IMS control region. Additionally, the logonid of the IMS control region must have the MUSASS attribute. @MUSASS IMS,MLID=IMS,FASTPTH=YES In the @MUSASS previous example, IMS is the region logonid. MLID=IMS specifies the name of the @MLID macro that applies to the IMS control region. FASTPTH=YES specifies that fast path support is used by the MUSASS; a dedicated work area is GETMAINed for use by the MUSASS when the MUSASS is initialized. This work area is not deleted until the region is terminated. The CVTCOM, CVTNAME, WORK, CACHE, and CACHE# operands are not required. CVTNAME should not be specified under any circumstances. If you specify a CVTNAME, CA ACF2 tries to load it when IMS is started and initialization errors result. If you have IMS systems with different logonids or if you want your systems to have different @MLIDS, you must specify more than one @MUSASS macro. Chapter 20: Installation Procedure 243

Detailed Installation Instructions @MLID Considerations The @MLID macro specifies the logonid fields that are included in the minilogonid. The complete minilogonid is defined by two @MLID macros called ACF2 and IMS. The ACF2 @MLID contains the minimum information necessary for CA ACF2 processing. The ACF2 @MLID provided in the ACFFDR is discussed in the Installation Guide. The IMS @MLID is required for some additional fields in the minilogonid. Specifically, the IDLE and AUTH fields are required in the IMS @MLID for IMS interface processing. You can add fields to the IMS @MLID macro specification; however, all fields specified in the supplied ACF2 @MLID macro must remain unchanged. Your @MLID macros need not duplicate any fields already defined in the ACF2 @MLID macro. The MLAIMS DSECT in CAI.CAX1MAC defines the structure of the IMS @MLID. If you add fields to the IMS @MLID, you must update the MLAIMS DSECT to reflect the new fields. The default ACFFDR @MLID macro for IMS support is: @MLID IMS,MLAIMS,MLAIMSL, NAME, START, LENGTH X (LIDIDLE,MLAIIDLE), MAX IDLE TIME IN MINUTES X (LIDM2FLG,MLAISAUT), IMS SIGNON AUTH BYTE X (LIDGROUP,MLAIGRP) Changing the Minilogonid Definition GROUP You must evaluate your SIGNON AUTH and OPTS IDLE requirements. If you choose different (nondefault) fields for the SIGNON AUTH and OPTS IDLE fields or if you are adding new fields to the minilogonid, you must: 1. Modify the logonid record (LIDREC) mapping DSECT to include each new field in the mapping of the logonid record. Define these fields in the basic user portion (USERLID copy member) or the extended user portion (USERXLID) of the LIDREC. 2. Create an @CFDE for each field if the field does not exist in the record. 3. Update the existing @MLID or create a new @MLID. 4. Update MLAIMS or create a new copybook. If you create a new copybook, be sure to add it to CAI.CAX1MAC (@SETUP). @CFDE Considerations Each @CFDE defines an external field name and the internal characteristics and attributes for a field in the logonid record. One @CFDE is necessary for each field of the logonid record. You must evaluate if other fields are needed. If so, change the minilogonid definition. 244 IMS Support Guide

Detailed Installation Instructions Create or Update IMS User Messages Table An IMS user messages table is required to include the IMS interface messages. To create or update the IMS user messages table 1. If no IMS user messages table exists, you must create one. If one does exist, you must add a COPY statement to include the IMS interface messages. The requirements for the DFSCMTU0 are documented in the IBM IMS Customization Guide. The message module should minimally contain: DFSCMTU0 CSECT BALR 15,14 COPY ACFDCMSG COPY CA ACF2 IMS MESSAGES DC '7FFF' DEFINE TABLE END END 2. Choose a message range for the user messages table and update CAI.ACF2IMS.CAX1MAC2(ACFDCMSG). The starting message number specified in ACFDCMSG must match the message base specified on the IMS OPTS record. 3. Assemble and link DFSCMTU0, the User Message Module, into the library defined in the USERLIB= operand of the IMSGEN macro in the IMS system definition. Define ACF Command If SMU is used for TERMINAL, PASSWORD, or TRANCMD security, the IMS interface /ACF command must be pre-defined to IMS before the SMU generation job is run. This involves installing usermods on the IMS release software. Two jobs are provided to install the /ACF command in the IMS software. The first job, SMUMOD1, installs the /ACF command in the command verb list and generates support for the /ACF command in the IMS nucleus. This job should be modified and run before the IMS system definition is run. The second job, SMUMOD2, is described in Step 12. For the IMS system definition, the IMS SDFSMAC data set must be added to the SYSLIB DD statement data set concatenation preceding the IMS GENLIB DD statements. This is necessary so that the IMS system definition uses the versions of the macros updated by the SMUMOD1 usermod. CAUTION! If SMU is used for TERMINAL, PASSWORD, or TRANCMD security, failure to complete this step will cause errors during IMS initialization. When SMU is not used, there is no need to pre-define the /ACF command in the IMS tables. CA ACF2 implements the command automatically at IMS startup. Note: In IMS Version 10 and above, SMU is no longer supported. This usermod is not needed and should not be refit. This step should be skipped. Chapter 20: Installation Procedure 245

Detailed Installation Instructions Update IMS System Definition To update the IMS Stage 1 system definition 1. For the COMM macro, you should specify: COMM OPTIONS=(...,USERMSGS,)... This generates support for the user messages table. 2. Add a TP application for the ACF transaction. Add the following TP application description and transaction descriptions to your IMS gen. APPLCTN PSB=ACFDCACT, * ACF/IMS CMD PGM NAME X PGMTYPE=(TP,,1) * TP TYPE - CLASS 1 TRANSACT CODE=ACF, * ACF CMD TRANS NAME X PRTY=(05,09,005), * PRIORITY-NORML/LIMIT/CNT X MSGTYPE=(MULTSEG,RESPONSE,1), * MESSAGES PROCLIM=(1,1), * MSG COUNT / CPU TIME X SCHD=3, * SCHED ANY TRNS IN CLASS X MODE=SNGL, * WRITE DATA BFRS AFT MSG X SPA=(1100), * SCRTCH PAD SIZE X SEGNO=120 * MAX # OUTPUT SEGMENTS If you want users in message processing regions to be able to issue the UID parameter on the LIST request, you must turn off IMS timing services so that IMS does not time out their requests. To do this, change the DFSMPR procedure in the message processing region to STIMER=0. Then, change the ACF transaction description above to TRANSACT PROCLIM(1,65535) to skip the IMS STIMER issued for the transaction. X Run IMS System Definition For proper installation of the IMS interface usermods, a NUCLEUS (or larger) type IMS system definition (stage1, stage2, and JCLIN) must be run. 246 IMS Support Guide

Detailed Installation Instructions Modify IMS Command Table If SMU is used for TERMINAL, PASSWORD, or TRANCMD security, the second IMS interface usermod must be installed. Run the second IMS interface usermod job, SMUMOD2. This job installs a usermod that adds the /ACF command to the IMS command table. It also causes SMP/E to relink the IMS nucleus with the updated command table. Run this job after the complete IMS system definition, including the JCLIN step. This job will not run successfully unless the IMS system definition JCLIN step has been performed. For any subsequent NUCLEUS type (or larger) system definition, after the JCLIN portion of the system definition process, the usermod must be reapplied. When SMU is not used, there is no need to pre-define the /ACF command in the IMS tables. CA ACF2 implements the command automatically at IMS startup. Note: In IMS Version 10 and above, SMU is no longer supported. This usermod is not needed and should not be refit, This step should be skipped. Provide CA ACF2 Logonid Maintenance Link the ACFDCACT program and generate a PSB for the ACFDCACT program. ACFDCACT is the program that provides CA ACF2 logonid maintenance. Modify and run the LINKACT job in CAI.CAX1JCL2 to link edit the load module ACFDCACT to your IMS program library. You must also generate a PSB for the ACFDCACT program. The PSB description for the PSBGEN utility is: PSBGEN LANG=ASSEM,PSBNAME=ACFDCACT Provide MFS Format Generate the MFS format for formatted IMS sign-on. The IMS default sign-on format is not sufficient for IMS interface sign-on processing. You must create an alternate sign-on format that meets the IMS interface requirements. This topic is covered in more detail in the chapter Additional Considerations. You must run an MFSGEN of your site's sign-on format definition to create the format control blocks in the IMS format library. Chapter 20: Installation Procedure 247

Detailed Installation Instructions Modify the IMS OM Command Table If you are running an IMSplex environment and have a requirement to enter the /ACF command through OM and route it to multiple IMS regions in the IMSplex, apply a USERMOD to the IMS software to add the /ACF command to the IMS OM registered commands. Note: Skip this step if you are not running an IMSPLEX environment or you do not have the requirement for the /ACF command through OM. In an IMSplex environment, each IMS region registers with the CSL OM address space and communicates to OM the subset of IMS commands that can be entered through DFSSPOC or the OM API and routed to that IMS region. The IMS source module DFSOSY20 contains the commands and keywords that IMS will register with the OM address space. By default, the /ACF command is not one of these IMS commands that can be entered through OM. A sample USERMOD to add the /ACF command to the DFSOSY20 module is included in the IMSUMOD1 member in the CAX1JCL2 sample JCL data set. Edit this job and modify it to conform to your installation standards. Execute the job to install the USERMOD. The USERMOD is only intended to add the /ACF command and keywords to the DFSOSY20 table before any existing commands and keywords. It should not replace any existing statements in DFSOSY20. Verify in the output of the USERMOD that the new statements were added to the module in the proper location and did not affect any existing commands and keywords. 248 IMS Support Guide

Detailed Installation Instructions Create/Modify IMS Interface Options, Logonids, Rules Before proceeding with the next step, be sure that your security administrator creates or modifies IMS interface system options, logonids, and resource rules as appropriate after reviewing all of your requirements. Verify that your options, logonids and resource rules reflect the security requirements for your site. CAUTION! If you are not using application group names (AGNs), ensure that you create an IMS RESOURCE record that specifies NOVALIDATE for this resource. Failure to do this will cause errors during the IMS initialization process. For more information about these records, see the chapters IMS Records and AGN Security. The IMS interface does not use the native IMS ISIS= parameter to control AGN security. If you have an AGN security user exit (DFSISISO), set the ISIS= parameter to 2. If you do not have an AGN security user exit, set the ISIS= parameter to 0. Failure to do this will cause errors during IMS processing. Important! In IMS Release 9.1, RAS security was introduced as a replacement for AGN security. AGN security and RAS security are mutually exclusive, and cannot both be specified or defaulted to VALIDATE in their respective IMS RESOURCE records. If you want to use one of these security mechanisms, create the appropriate RESOURCE record for that mechanism with VALIDATE specified, and create the RESOURCE record for the other mechanism with NOVALIDATE. For more information see the chapter AGN and RAS Resource Security. Chapter 20: Installation Procedure 249

Detailed Installation Instructions Initialize IMS Interface Update the IMS control region parameters and JCL. 1. Specify RCF=Y (or another RCF option that includes Y), in the IMS control region parameters, in the IMS control region JCL or in the DFSPBxxx member of the IMS PROCLIB specified in the IMS control region JCL. Without this specification, IMS will not include security information required by the CA ACF2 IMS interface when transactions are stored in IMS. During IMS initialization, the CA ACF2 IMS interface ensures that this parameter was specified and terminates the IMS control region if the parameter was not specified. This is the only parameter specification required by the CA ACF2 IMS interface. During IMS initialization, the CA ACF2 IMS interface dynamically changes the IMS control options to provide the appropriate level of security in the IMS control region. At the end of initialization, the CA ACF2 IMS interface resets the RCF option to RCF=N, to avoid duplicate security processing. 2. Add the IMS interface load library to the IMS procedure STEPLIB DD statement. //STEPLIB DD DSN=CAI.ACF2IMS.CAX1IMS // DD DSN=IMS.SDFSRESL Important! The IMS interface library must be the first in the STEPLIB control region startup sequence. 250 IMS Support Guide

Chapter 21: User Exits If your site has security needs that are not part of the normal IMS interface processing, you can accommodate these needs by using the IMS interface exits. An exit is a predefined location where you can choose to receive control for your customized processing. You determine the functions that should occur at each exit and write a program to perform the processing. Exits have major audit implications because they are permitted to alter the normal IMS interface security processing. This chapter describes the IMS interface exits that you can use to perform unique processing requirements. This section contains the following topics: Design Concepts and Features (see page 252) Exit Procedures and Considerations (see page 253) Defining the IMS Exits Record (see page 254) Initialization Exit (INITIAL) (see page 254) Presign-on Exit (PRESIGN) (see page 255) Sign-on Exit (SIGNON) (see page 257) Sign-off Exit (SIGNOFF) (see page 260) Prevalidation Exit (PREVAL) (see page 262) Postvalidation Exit (POSTVAL) (see page 268) Idle Time Exit (IDLE) (see page 271) Chapter 21: User Exits 251

Design Concepts and Features Design Concepts and Features The IMS interface exits that are available for your use are: INITIAL-Initialization exit PRESIGN-Presign-on exit SIGNON-Sign-on exit SIGNOFF-Sign-off exit PREVAL-Prevalidation exit POSTVAL-Postvalidation exit IDLE-Idle Time exit When an exit point occurs, the IMS interface determines if a user exit program is provided. If no exit program exists, it continues standard processing; however, if a user program is available, the site-written code is given control. Each exit is passed its own control area that contains a set of information specific to the exit. The format and length of the exit control area varies for each exit. See the next section, Exit Procedures and Considerations, for information about obtaining the DSECT mappings of each exit control area. 252 IMS Support Guide

Exit Procedures and Considerations Exit Procedures and Considerations This section describes some of the procedures and additional information that are related to IMS interface exits. Sample exit programs for all of the available exits can be found in the CAI.CAX1MAC2 library created during IMS interface installation. See the individual exit sections in this chapter to find the member names of each sample exit. Note: User exits cannot be in a PDSE library due to the IMODULE macro being used. All of your exit programs must be written in assembler language. Do not name your programs anything that begins with ACF. If you follow this rule, you guarantee that you do not cause an error in CA ACF2 processing. When entry to the exit module occurs, the following linkage is used: Register 1-Points to the exit control area Registers 13, 14, and 15-Standard program linkage All exit modules receive control in 31-bit addressing mode. The exit control areas that are passed to the exit module can reside above or below the 16MB line. You must specify the following information to obtain the DSECT mappings of the respective exit control areas. ACFDCXCA EXIT=INITIAL PRESIGN SIGNON SIGNOFF PREVAL POSTVAL IDLE,DSECT=YES NO A portion of the exit control area passed to each exit has been set aside for use by the exit module. The size of the available work area varies for each exit. The location of the available work area is passed to the exit module in the XxxXPWA field of the exit control area. By using this field to get to the location of the available work area, the exit module minimizes the impact of the IMS interface release changes. If the program is coded to give up control during processing, unless otherwise indicated in the individual exit sections of this chapter, the program must be reentrant. Examples of giving up control during processing are issuing an IMS IWAIT or using an IMS function, such as the logging function. In the initialization exit, you can pass to the IMS interface a field or address that the IMS interface passes to every other exit. The Global System Field, XINGFLD, contains four bytes of system information that is passed to all other exits and does not affect normal IMS interface processing. A possible use for this field is to store the address of some additional system information that was created by the initialization exit and that is used by the other exit programs. Chapter 21: User Exits 253

Defining the IMS Exits Record Some of the exits are passed the user's ACMCB and MLID. The format of the ACMCB is available using the ACMCB macro in CAI.CAX1MAC. The format of the MLID can change if your site has modified the MLID. Consult with your CA ACF2 systems programmer to determine your site's MLID format. You must link edit programs into a library that is specified in the IMS control region STEPLIB concatenation or into a z/os link list accessible library. Exit processing has an impact on performance. The prevalidation and postvalidation exits, in particular, can degrade performance if the assembler code is not written efficiently. If you make changes to your exit programs, the changes do not take effect until the IMS control region is restarted. Defining the IMS Exits Record This section discusses how to define exits to the IMS interface. Before you can invoke exit programs, you must specify the names of your exit programs in an IMS interface EXITS record. INSERT DIVISION(musid jobname) EXITS INITIAL(pgmname) - PRESIGN(pgmname) SIGNON(pgmname) SIGNOFF(pgmname) - PREVAL(pgmname) POSTVAL(pgmname) IDLE(pgmname) The pgmname (program name) above is the name of the site-written exit program. This name can be obtained from your systems programmer. Initialization Exit (INITIAL) The initialization exit module is invoked at the end of the IMS interface initialization. No IMS interface decisions can be made with this exit; however, your program can process additional site-specific security requirements. For example, you can build tables in this exit for processing that occurs in other exits or you might use this exit to set up storage for other exit programs. It is not required that this exit program be reentrant. The sample initialization exit program is in CAI.CAX1MAC2 member ACFDCXIN. 254 IMS Support Guide

Presign-on Exit (PRESIGN) Exit Control Area DSECT ACFDCXCA EXIT=INITIAL ACFDCXIN DSECT *----------------------------------------------------------------* * INITIAL EXIT CONTROL AREA *----------------------------------------------------------------* XINSCD DS A IMS SCD ADDRESS XINGFLD DS A EXIT GLOBAL SYSTEM FIELD XINXPWA DS A ADDRESS OF AVAILABLE WORK AREA DS 5A RESERVED FOR FUTURES DS 0D DOUBLEWORD ALIGN WORK AREA XINWORK DS XL128 AVAILABLE WORK AREA XINALEN EQU *-ACFDCXIN LENGTH OF EXIT CONTROL AREA Exit Control Area Fields that Can Be Supplied or Changed XINGFLD The global system field, XINGFLD, contains a field or address that the IMS interface passes to every other IMS interface exit. This field/address does not affect normal IMS interface processing. Presign-on Exit (PRESIGN) The presign-on exit receives control from the IMS interface for sign-on requests before any IMS interface sign-on processing has been performed. The exit can investigate the IMS sign-on environment and choose to refuse the sign-on request, it can modify the sign-on data, or it can change the terminal source name that is used for the IMS interface sign-on. The sample presign-on exit program is in CAI.CAX1MAC2 member ACFDCXPS. Chapter 21: User Exits 255

Presign-on Exit (PRESIGN) Exit Control Area DSECT ACFDCXCA EXIT=PRESIGN ACFDCXPS DSECT *----------------------------------------------------------------* * PRESIGN EXIT CONTROL AREA *----------------------------------------------------------------* XPSSCD DS A IMS SCD ADDRESS XPSGFLD DS A EXIT GLOBAL SYSTEM FIELD XPSXPWA DS A ADDRESS OF AVAILABLE WORK AREA XPSIPB DS A IMS IPB ADDRESS XPSUVS DS A USER VERIFICATION STRING ADDR XPSFLAG1 DS X EXIT CONTROL FLAG XPSF1REF EQU X'80'..REFUSE SIGNON REQUEST XPSSRCE DS CL8 SOURCE USED FOR SIGNON XPSMSG DS XL128 MESSAGE IF SIGNON REFUSED DS 4A RESERVED FOR FUTURES DS 0D DOUBLEWORD ALIGN WORK AREA XPSWORK DS XL128 AVAILABLE WORK AREA XPSALEN EQU *-ACFDCXPS LENGTH OF EXIT CONTROL AREA Descriptions of Some Exit Control Area Fields XPSUVS This field contains the address of the user verification string created by the IMS /SIGN command processor. The user verification string contains the text of the sign-on data that is passed to the IMS interface and used for the sign-on process. The format of the user verification string is: llzzxxx... Where: ll-is the length of the user verification string. zz-is a halfword of binary zeros. xxx...-is the text string beginning with the first character of the logonid. Exit Control Area Fields that Can Be Supplied or Changed XPSSRCE The source name that is used for the IMS interface sign-on process is passed in this field. The presign-on exit can change the source name before the IMS interface sign-on processing is complete. XPSFLAG1 XPSF1REF indicates that the sign-on should be refused. If the exit sets this flag, a message explaining the reason must be returned in the XPSMSG field. 256 IMS Support Guide

Sign-on Exit (SIGNON) XPSMSG If the exit sets the XPSF1REF flag to refuse the sign-on, a message explaining the reason must be returned in this field. This message is delivered to the requesting terminal. The format of the message in this field must be: llzzxxx... Where: ll-is the length of the message, including the llzz field. zz-is a halfword of binary zeros. xxx...-is the text of the message. Sign-on Exit (SIGNON) The sign-on exit is called after the IMS interface sign-on processing is complete but before IMS sign-on processing is complete. The exit can investigate the IMS and IMS interface sign-on environment and perform additional site-required sign-on processing, or choose to refuse the sign-on request. It can also change the MFS format that is sent to the terminal after sign on is complete. For example, you can display additional sign-on information or display broadcast messages. The sample sign-on exit program is in CAI.CAX1MAC2 member ACFDCXSN. Chapter 21: User Exits 257

Sign-on Exit (SIGNON) Exit Control Area DSECT ACFDCXCA EXIT=SIGNON ACFDCXSN DSECT *----------------------------------------------------------------* * SIGN-ON EXIT CONTROL AREA *----------------------------------------------------------------* XSNSCD DS A IMS SCD ADDRESS XSNGFLD DS A EXIT GLOBAL SYSTEM FIELD XSNXPWA DS A ADDRESS OF AVAILABLE WORK AREA XSNIPB DS A IMS IPB ADDRESS XSNACMCB DS A ACMCB/MLID ADDRESS XSNUFLD DS A EXIT USER FIELD XSNUVS DS A ADDRESS OF SIGNON DATA XSNPSFMT DS CL8 POST-SIGNON FORMAT XSNFLAG1 DS X EXIT CONTROL FLAG XSNF1REF EQU X'80'..REFUSE SIGNON REQUEST XSINF1NOT EQU X'40'..ISSUE SIGNON MESSAGES XSNFLAG2 DS X EXIT INFORMATION FLAG XSNF2PWC EQU X'80'..PASSWORD WAS CHANGED XSNF2PCF EQU X'40'..PASSWORD CHANGE FAILED XSNF2MSG EQU X'20'..ACF2 MESSAGE IN XSNMSG DS CL2 RESERVED FOR FUTURES XSNMSG DS XL128 MESSAGE BUFFER DS 2A RESERVED FOR FUTURES DS OD DOUBLEWORD ALIGN WORK AREA XSNWORK DS XL128 AVAILABLE WORK AREA XSNALEN EQU *-ACFDCXSN LENGTH OF EXIT CONTROL AREA MEXIT Descriptions of Some Exit Control Area Fields XSNACMCB This is the address of the ACMCB. Any changes made to the ACMCB or MLID persist until the IMS user signs off. 258 IMS Support Guide

Sign-on Exit (SIGNON) XSNUVS This field contains the address of the user verification string created by the IMS /SIGN command processor. The user verification string contains the text of the sign-on data that is passed to the IMS interface and used for the sign-on process. The format of the user verification string is: llzzxxx... Where: ll-is the length of the user verification string. zz-is a halfword of binary zeros. xxx...-is the text string beginning with the first character of the logonid. XSNFLAG2 XSNF2PWC indicates that the password was successfully changed during the sign-on. This exit must take this into account if it decides to refuse the sign-on. XSNF2PCF Indicates that an attempt to change the password failed during this sign-on. The exit must take this into account if it decides to refuse the sign-on. XSNF2MSG Indicates that a copy of the CA ACF2 informational system entry message has been passed to the exit in the XSNMSG field. The format of the message is: llzzxxx... Where: ll-is the length of the message, including the llzz field. zz-is a halfword of binary zeroes. xxx...-is the text of the message. Exit Control Area Fields that Can Be Supplied or Changed XSNUFLD The sign-on exit can pass back to the IMS interface an address in the XSNUFLD field. This field is passed by the IMS interface to any of the subsequent exit programs, such as the prevalidation or postvalidation exits. A possible use for this field is to store the address of some additional user information that was created by the sign-on exit and that is used by the other exit programs. XSNPSFMT The name of the MFS format that is used to deliver the successful sign-on messages is passed in this field. The sign-on exit can change the format name before the messages are delivered. Chapter 21: User Exits 259

Sign-off Exit (SIGNOFF) XSNFLAG1 XSNF1REF indicates that the sign-on should be refused. If the exit sets this flag, a message explaining the reason must be returned in the XSNMSG field. XSN1NOT Indicates that the CA ACF2 informational system entry message should be delivered to the terminal at sign-on. This flag is initialized to the value of the NOTIFY option in the IMS SIGNON record. The exit can set or reset the flag to override the system NOTIFY setting for this individual sign-on. XSNMSG If the exit sets the XSNF1REF flag to refuse the sign-on, a message explaining the reason must be returned in this field. This message is delivered to the requesting terminal. The format of the message in this field must be: llzzxxx... Where: ll-is the length of the message, including the llzz field. zz-is a halfword of binary zeros. xxx...-is the text of the message. Sign-off Exit (SIGNOFF) The sign-off exit receives control before both the IMS interface sign-off processing and IMS sign-off processing is complete. You cannot override any IMS interface processing. You can write a program to display additional sign-off information or to cut accounting or statistical records for tracking the terminating session. The sample sign-off exit program is in ACF2IMS.ACFMAC member ACFDCXSF. 260 IMS Support Guide

Sign-off Exit (SIGNOFF) Exit Control Area DSECT ACFDCXCA EXIT=SIGNOFF ACFDCXSF DSECT *----------------------------------------------------------------* * SIGNOFF EXIT CONTROL AREA *----------------------------------------------------------------* XSFSCD DS A IMS SCD ADDRESS XSFGFLD DS A EXIT GLOBAL SYSTEM FIELD XSFXPWA DS A ADDRESS OF AVAILABLE WORK AREA XSFIPB DS A IMS IPB ADDRESS XSFACMCB DS A ACMCB/MLID ADDRESS XSFUFLD DS A EXIT USER FIELD DS 4A RESERVED FOR FUTURES DS 0D DOUBLEWORD ALIGN WORK AREA XSFWORK DS XL128 AVAILABLE WORK AREA XSFALEN EQU *-ACFDCXSF LENGTH OF EXIT CONTROL AREA Descriptions of Some Exit Control Area Fields XSFACMCB This contains the address of the ACMCB that is used for the CA ACF2 sign-off. Any changes made to the ACMCB affect the CA ACF2 sign-off processing. Exit Control Area Fields that Can Be Supplied or Changed None. Chapter 21: User Exits 261

Prevalidation Exit (PREVAL) Prevalidation Exit (PREVAL) The prevalidation exit receives control before every IMS interface resource access (for example, transaction) validation. The sample prevalidation exit program is in CAI.CAX1MAC2 member ACFDCXPR. There are five IMS interface decisions that your program can consider in the prevalidation exit: 1. Allow or deny resource access. You can decide to automatically permit or automatically deny resource access. If you permit resource access, the normal IMS interface resource rule checking is bypassed. If you decide to deny resource access, the transaction is denied regardless of the information that is specified in the resource rule. A deny decision in this exit does not create a resource violation log record. The information in the XPVRESP field determines which decision is in effect. If the exit program puts an 'A' in the XPVRESP field, the IMS interface bypasses resource rule checking and allows resource validation. A 'D' in the XPVRESP field denies resource access. 2. Bypass cache processing. If you request that the IMS interface bypass cache processing, it has two effects. First, it does not check the cache before a resource validation and always issues an IMS interface resource validation call. Second, if the resource access is permitted, the IMS interface does not enter the resource in the cache. An 'N' in the XPVCACHE field bypasses the IMS interface cache processing. For a detailed description of validation caching, see the chapter CA-ACF2 IMS Philosophy. 3. Change the resource key that is used for validation. You have the option of changing the resource key that is used for the CA ACF2 resource validation call. The XPVRKEY contains the resource class, resource type, and resource name. 4. Change the information in the ACMCB. The ACMCB passed to the user exit is the ACMCB used for the validation. If the ACMCB is for a default logonid, it is a copy of the actual ACMCB. Any changes made last only for the life of the validation. If the ACMCB is for an IMS user, this is the user ACMCB and any changes made persist until the IMS user signs off. 5. Return user data for AUTH calls. If the IMS interface resource validation is for an IMS AUTH call, the prevalidation exit can return user data to the calling program. For a description of the IMS interface support for the AUTH call, see the chapter Additional Considerations. 262 IMS Support Guide

Prevalidation Exit (PREVAL) Exit Control Area DSECT ACFDCXCA EXIT=PREVAL ACFDCXPV DSECT *----------------------------------------------------------------* * PRE/POST-VALIDATION EXIT CONTROL AREA *----------------------------------------------------------------* XPVSCD DS A IMS SCD ADDRESS XPVGFLD DS A EXIT GLOBAL SYSTEM FIELD XPVXPWA DS A ADDRESS OF AVAILABLE WORK AREA XPVIPX DS A IMS IPX ADDRESS (OR 0) XPVPST DS A IMS PST ADDRESS (OR 0) XPVACMCB DS A ACMCB/MLID ADDRESS XPVUFLD DS A EXIT USER FIELD (OR 0) XPVIDATA DS A INPUT BUFFER ADDRESS (OR 0) XPVCALLR DS X RESOURCE INFORMATION FLAG XPV$TERM EQU X'00' TRANSACTION - TERMINAL XPV$MSC EQU X'04' TRANSACTION - MSC LINK XPV$DPTP EQU X'08' TRANSACTION - DEFERRED PGM-PGM XPV$CHNG EQU X'0C' TRANSACTION - DLI CHNG CALL XPV$SET EQU X'10' TRANSACTION - /SET COMMAND * EQU X'14' TRANSACTION - OM QUE XPV$SIGN EQU X'18' TRANSACTION - /SIGN COMMAND XPV$REL EQU X'1C' TRANSACTION - /RELEASE COMMAND XPV$AUTH EQU X'20' RESOURCE - AUTH CALL XPV$APPC EQU X'24' TRANSACTION - APPC/IMS XPV$OTMA EQU X'28' TRANSACTION - OTMA/IMS XPV$LTRN EQU X'2C' Transaction - /LOCK XPV$LPGM EQU X'30' Program - /LOCK XPV$LDB EQU X'34' Database - /LOCK XPV$LTRM EQU X'38' LTERM - /LOCK XPV$RPTP EQU X'3C' Transaction - remote PTP XPV$TPIP EQU X'C8' TPIPE - RESUME XPV$RTRM EQU X'CC' LTERM - RAS XPV$RPSB EQU X'D0' PSB - RAS XPV$RTRN EQU X'D4' Transaction - RAS XPV$CMD1 EQU X'D8' Command - CMD XPV$PSB EQU X'DC' PSB XPV$TCMD EQU X'E0' COMMAND TRANSACTION XPV$CMD EQU X'E4' COMMAND TERMINAL XPV$MSCI EQU X'E8' TRANSACTION MSC INBOUND XPV$AGN EQU X'EC' AGN XPV$ISRT EQU X'F0' TRANSACTION ISRT NON MOD PCB XPVFLAG1 DS X INFORMATION FLAGS XPVF1IDA EQU X'80' INPUT BUFFER ADDRESS PASSED XPVF1MFS EQU X'40' INPUT FROM MFS FORMAT XPVF1BMP EQU X'20' USER IS A BMP XPVF1ADP EQU X'10' ACF2 DATA IS PASSED TO POST VAL XPVMSG AND/OR XPVREDTA Chapter 21: User Exits 263

Prevalidation Exit (PREVAL) *----------------------------------------------------------------* * DATA WHICH CAN BE CHANGED IN THE EXIT ROUTINES *----------------------------------------------------------------* XPVRKEY DS 0CL44 RESOURCE KEY XPVRCLAS DS CL1 RESOURCE CLASS XPVRTYPE DS CL3 RESOURCE TYPE XPVRRSRC DS CL40 RESOURCE XPVCACHE DS C CACHE CONTROL SWITCH (Y/N) XPV$YES EQU C'Y' USE THE CACHE XPV$NO EQU C'N' DON'T USE THE CACHE XPVRESP DS C RESPONSE XPV$ALLW EQU C'A' ACCESS ALLOWED XPV$DENY EQU C'D' ACCESS DENIED XPV$PVER EQU C'V' VERIFY REQUESTED XPV$PREQ EQU C'V' PASSWORD REQUIRED/MISSING XPV$BPW EQU C'P' PASSWORD INCORRECT XPV$NACF EQU C'N' ACF2 NOT AVAILABLE XPV$EACF EQU C'E' ERROR IN ACF2 PROCESSING XPV$RTRY EQU C'R' POST EXIT REQUESTS RETRY XPVFLAG2 DS X EXIT CONTROL FLAG XPVF2AUD EQU X'80' AUTH CALL USERDATA RETURNED XPVF2DNL EQU X'40' AUTH CALL DO NOT LOG SPACE DS XL3 RESERVED FOR FUTURES SPACE 2 *----------------------------------------------------------------* * DATA AVAILABLE ONLY IN THE POST-VALIDATION EXIT *----------------------------------------------------------------* XPVMSG DS A ACF2 MESSAGE ADDRESS (OR 0) XPVREDTA DS A RULE USER DATA ADDRESS (OR 0) DS XL68 RESERVED FOR FUTURES DS 0D DOUBLEWORD ALIGN WORK AREA XPVWORK DS XL512 AVAILABLE WORK AREA XPVALEN EQU *-ACFDCXPV LENGTH OF EXIT CONTROL AREA 264 IMS Support Guide

Prevalidation Exit (PREVAL) Descriptions of Some Exit Control Area Fields ACFDCXCA EXIT=PREVAL ACFDCXPV DSECT *----------------------------------------------------------------* * PRE/POST-VALIDATION EXIT CONTROL AREA *----------------------------------------------------------------* XPVSCD DS A IMS SCD ADDRESS XPVGFLD DS A EXIT GLOBAL SYSTEM FIELD XPVXPWA DS A ADDRESS OF AVAILABLE WORK AREA XPVIPB DS A IMS IPB ADDRESS (OR 0) XPVPST DS A IMS PST ADDRESS (OR 0) XPVACMCB DS A ACMCB/MLID ADDRESS XPVUFLD DS A EXIT USER FIELD (OR 0) XPVIDATA DS A INPUT BUFFER ADDRESS (OR 0) XPVCALLR DS X RESOURCE INFORMATION FLAG XPV$TERM EQU X'00' TRANSACTION - TERMINAL XPV$MSC EQU X'04' TRANSACTION - MSC LINK XPV$DPTP EQU X'08' TRANSACTION - DEFERRED PGM-PGM XPV$CHNG EQU X'0C' TRANSACTION - DLI CHNG CALL XPV$SET EQU X'10' TRANSACTION - /SET COMMAND * EQU X'14' TRANSACTION - OM QUE XPV$SIGN EQU X'18' TRANSACTION - /SIGN COMMAND XPV$REL EQU X'1C' TRANSACTION - /RELEASE COMMAND XPV$AUTH EQU X'20' RESOURCE - AUTH CALL XPV$APPC EQU X'24' TRANSACTION - APPC/IMS XPV$OTMA EQU X'28' TRANSACTION - OTMA/IMS XPV$LTRN EQU X'2C' Transaction - /LOCK XPV$LPGM EQU X'30' Program - /LOCK XPV$LDB EQU X'34' Database - /LOCK XPV$LTRM EQU X'38' LTERM - /LOCK XPV$RPTP EQU X'3C' Transaction - remote PTP XPV$TPIP EQU X'C8' TPIPE - RESUME XPV$RTRM EQU X'CC' LTERM - RAS XPV$RPSB EQU X'D0' PSB - RAS XPV$RTRN EQU X'D4' Transaction - RAS XPV$CMD1 EQU X'D8' Command - CMD XPV$PSB EQU X'DC' PSB XPV$TCMD EQU X'E0' COMMAND TRANSACTION XPV$CMD EQU X'E4' COMMAND TERMINAL XPV$MSCI EQU X'E8' TRANSACTION MSC INBOUND XPV$AGN EQU X'EC' AGN XPV$ISRT EQU X'F0' TRANSACTION ISRT NON MOD PCB XPVFLAG1 DS X INFORMATION FLAGS XPVF1IDA EQU X'80' INPUT BUFFER ADDRESS PASSED XPVF1MFS EQU X'40' INPUT FROM MFS FORMAT XPVF1BMP EQU X'20' USER IS A BMP XPVF1ADP EQU X'10' ACF2 DATA IS PASSED TO POST VAL XPVMSG AND/OR XPVREDTA Chapter 21: User Exits 265

Prevalidation Exit (PREVAL) *----------------------------------------------------------------* * DATA WHICH CAN BE CHANGED IN THE EXIT ROUTINES *----------------------------------------------------------------* XPVRKEY DS 0CL44 RESOURCE KEY XPVRCLAS DS CL1 RESOURCE CLASS XPVRTYPE DS CL3 RESOURCE TYPE XPVRRSRC DS CL40 RESOURCE XPVCACHE DS C CACHE CONTROL SWITCH (Y/N) XPV$YES EQU C'Y' USE THE CACHE XPV$NO EQU C'N' DON'T USE THE CACHE XPVRESP DS C RESPONSE XPV$ALLW EQU C'A' ACCESS ALLOWED XPV$DENY EQU C'D' ACCESS DENIED XPV$PVER EQU C'V' VERIFY REQUESTED XPV$PREQ EQU C'V' PASSWORD REQUIRED/MISSING XPV$BPW EQU C'P' PASSWORD INCORRECT XPV$NACF EQU C'N' ACF2 NOT AVAILABLE XPV$EACF EQU C'E' ERROR IN ACF2 PROCESSING XPV$RTRY EQU C'R' POST EXIT REQUESTS RETRY XPVFLAG2 DS X EXIT CONTROL FLAG XPVF2AUD EQU X'80' AUTH CALL USERDATA RETURNED XPVF2DNL EQU X'40' AUTH CALL DO NOT LOG SPACE DS XL3 RESERVED FOR FUTURES SPACE 2 *----------------------------------------------------------------* * DATA AVAILABLE ONLY IN THE POST-VALIDATION EXIT *----------------------------------------------------------------* XPVMSG DS A ACF2 MESSAGE ADDRESS (OR 0) XPVREDTA DS A RULE USER DATA ADDRESS (OR 0) DS XL68 RESERVED FOR FUTURES DS 0D DOUBLEWORD ALIGN WORK AREA XPVWORK DS XL512 AVAILABLE WORK AREA XPVALEN EQU *-ACFDCXPV LENGTH OF EXIT CONTROL AREA Exit Control Area Fields that Can Be Supplied or Changed For a description of the options listed here, see the introduction to this exit, Prevalidation Exit (PREVAL), earlier in this chapter. XPVRKEY The full key of the resource that the IMS interface validates. The XPVRCLAS field must remain as the literal R for RESOURCE storage class. XPVCACHE YES or NO. YES is the default. 266 IMS Support Guide

Prevalidation Exit (PREVAL) XPVRESP ALLOW or DENY. XPVFLAG2 XPVF2AUD indicates that the exit is returning user data for an IMS AUTH call. XPVF2DNL Indicates that the prevalidation exit wants to suppress any CA ACF2 logging for the validation of an IMS AUTH call. Chapter 21: User Exits 267

Postvalidation Exit (POSTVAL) Postvalidation Exit (POSTVAL) The postvalidation exit receives control after every IMS interface resource validation or cache validation. The sample postvalidation exit program is in CAI.CAX1MAC2 member ACFDCXPO. There are five IMS interface decisions that you can consider in the postvalidation exit: 1. Override the CA ACF2 decision. You can override the CA ACF2 decision by automatically permitting or denying the validation. Permitting resource validation enables validation, regardless of what was stated in the resource rule. If you deny resource validation, the transaction is denied regardless of what was specified in the resource rule. A deny decision in this exit does not create a resource violation log record. The information in the XPVRESP field determines which decision is in effect. An 'A' in the XPVRESP field overrides the IMS interface decision and allows resource validation. A 'D' in the XPVRESP field denies resource validation. 2. Change the resource key and retry the validation. You can change the resource key and retry the validation using the new resource key. 3. Reverify do not reverify the password. You can override the CA ACF2 password reverification decision by requesting or bypassing password reverification, regardless of what was stated in the resource rule. If 'V' is in the XPVRESP field, moving an 'A' to the field bypasses the password reverification and allows the access. Moving a 'V' to the XPVRESP field overrides the CA ACF2 decision and allows the access after a password reverification. 4. Do not use the cache. You can choose not to place records in the cache. If you choose not to use the cache for a permitted access, the resource is not to be placed in the user's cache and any subsequent request for the same resource goes through full resource validation. An 'N' in the XPVCACHE field bypasses the IMS interface cache processing. See the chapter CA-ACF2 IMS Philosophy for a detailed description of validation caching. 5. Return user data for AUTH calls. If the IMS interface resource validation is for an IMS AUTH call, the postvalidation exit can return user data to the calling program. For a description of the IMS interface support for the AUTH call, see the chapter Additional Considerations." 268 IMS Support Guide

Postvalidation Exit (POSTVAL) Exit Control Area DSECT ACFDCXCA EXIT=POSTVAL ACFDCXPV DSECT *----------------------------------------------------------------* * PRE/POST-VALIDATION EXIT CONTROL AREA *----------------------------------------------------------------* XPVSCD DS A IMS SCD ADDRESS XPVGFLD DS A EXIT GLOBAL SYSTEM FIELD XPVXPWA DS A ADDRESS OF AVAILABLE WORK AREA XPVIPB DS A IMS IPB ADDRESS (OR 0) XPVPST DS A IMS PST ADDRESS (OR 0) XPVACMCB DS A ACMCB/MLID ADDRESS XPVUFLD DS A EXIT USER FIELD (OR 0) XPVIDATA DS A INPUT BUFFER ADDRESS (OR 0) XPVCALLR DS X RESOURCE INFORMATION FLAG XPV$TERM EQU X'00' TRANSACTION - TERMINAL XPV$MSC EQU X'04' TRANSACTION - MSC LINK XPV$DPTP EQU X'08' TRANSACTION - DEFERRED PGM-PGM XPV$CHNG EQU X'0C' TRANSACTION - DLI CHNG CALL XPV$SET EQU X'10' TRANSACTION - /SET COMMAND * EQU X'14' UNUSED XPV$SIGN EQU X'18' TRANSACTION - /SIGN COMMAND XPV$REL EQU X'1C' TRANSACTION - /RELEASE COMMAND XPV$AUTH EQU X'20' RESOURCE - AUTH CALL XPV$APPC EQU X'24' TRANSACTION - APPC/IMS XPV$OTMA EQU X'28' TRANSACTION - OTMA/IMS XPV$LTRN EQU X'2C' Transaction - /LOCK XPV$OMQ EQU X'14' Transaction - OM QUE XPV$SIGN EQU X'18' TRANSACTION /SIGN COMMAND XPV$REL EQU X'1C' TRANSACTION /RELEASE COMMAND XPV$AUTH EQU X'20' RESOURCE AUTH CALL XPV$APPC EQU X'24' TRANSACTION APPC/IMS XPV$OTMA EQU X'28' TRANSACTION - OTMA/IMS XPV$LTRN EQU X'2C' Transaction - /LOCK XPV$LPGM EQU X'30' Program - /LOCK XPV$LDB EQU X'34' Database - /LOCK XPV$LTRM EQU X'38' LTERM - /LOCK XPV$RPTP EQU X'3C' Transaction - remote PTP XPV$TPIP EQU X'C8' TPIPE - RESUME XPV$RTRM EQU X'CC' LTERM - RAS XPV$RPSB EQU X'D0' PSB - RAS XPV$RTRN EQU X'D4' Transaction - RAS XPV$CMD1 EQU X'D8' Command - CMD XPV$PSB EQU X'DC' PSB XPV$TCMD EQU X'E0' COMMAND TRANSACTION XPV$CMD EQU X'E4' COMMAND TERMINAL XPV$MSCI EQU X'E8 TRANSACTION MSC INBOUND XPV$AGN EQU X'EC' AGN Chapter 21: User Exits 269

Postvalidation Exit (POSTVAL) XPV$ISRT EQU X'F0' TRANSACTION ISRT NON MOD PCB XPVFLAG1 DS X INFORMATION FLAGS XPVF1IDA EQU X'80' INPUT BUFFER ADDRESS PASSED XPVF1MFS EQU X'40' INPUT IN MFS FORMAT XPVF1BMP EQU X'20' USER IS A BMP XPVF1ADP EQU X'10' ACF2 DATA IS PASSED TO POST VAL XPVMSG AND/OR XPVREDTA *----------------------------------------------------------------* * DATA WHICH CAN BE CHANGED IN THE EXIT ROUTINES *----------------------------------------------------------------* XPVRKEY DS 0CL44 RESOURCE KEY XPVRCLAS DS CL1 RESOURCE CLASS XPVRTYPE DS CL3 RESOURCE TYPE XPVRRSRC DS CL40 RESOURCE XPVCACHE DS C CACHE CONTROL SWITCH (Y/N) XPV$YES EQU C'Y' USE THE CACHE XPV$NO EQU C'N' DON'T USE THE CACHE XPVRESP DS C RESPONSE XPV$ALLW EQU C'A' ACCESS ALLOWED XPV$DENY EQU C'D' ACCESS DENIED XPV$PVER EQU C'V' VERIFY REQUESTED XPV$PREQ EQU C'V' PASSWORD REQUIRED/MISSING XPV$BPW EQU C'P' PASSWORD INCORRECT XPV$NACF EQU C'N' ACF2 NOT AVAILABLE XPV$EACF EQU C'E' ERROR IN ACF2 PROCESSING XPV$RTRY EQU C'R' POST EXIT REQUESTS RETRY XPVFLAG2 DS X EXIT CONTROL FLAG XPVF2AUD EQU X'80' AUTH CALL USERDATA RETURNED XPVF2DNL EQU X'40' AUTH CALL DO NOT LOG SPACE DS XL3 RESERVED FOR FUTURES SPACE 2 *----------------------------------------------------------------* * DATA AVAILABLE ONLY IN THE POST-VALIDATION EXIT *----------------------------------------------------------------* XPVMSG DS A ACF2 MESSAGE ADDRESS (OR 0) XPVREDTA DS A RULE USER DATA ADDRESS (OR 0) DS XL68 RESERVED FOR FUTURES DS 0D DOUBLEWORD ALIGN WORK AREA XPVWORK DS XL512 AVAILABLE WORK AREA XPVALEN EQU *-ACFDCXPV LENGTH OF EXIT CONTROL AREA 270 IMS Support Guide

Idle Time Exit (IDLE) Descriptions of Some Exit Control Area Fields XPVMSG If resource rule validation was done and CA ACF2 denied the resource access, the address of the CA ACF2 message is placed in this field. XPVREDTA If resource rule validation was done and access was permitted, and user data was specified in the resource rule, the address of the returned user data is placed in this field. Exit Control Area Fields that Can Be Supplied or Changed For a description of the fields listed here, see the introduction to this exit, Postvalidation Exit (POSTVAL), earlier in this chapter. XPVRKEY The full key of the resource that the IMS interface validates. The XPVRCLAS field must remain as the literal R for RESOURCE storage class. XPVCACHE YES or NO. YES is the default. XPVRESP ALLOW, DENY, VERIFY, or RETRY. You are passed the decision thus far. You can override and force reverification. If the value is verify, you can change it before the IMS interface does password reverification. XPVFLAG2 XPVF2AUD indicates that the exit is returning user data for an IMS AUTH call. Idle Time Exit (IDLE) The Idle Time exit is called before the IMS interface performs password verification after idle time has elapsed. You can override or modify the IMS interface password reverification processing with this exit. You can decide not to enforce idle time password reverification or force the user to sign on again. The sample Idle Time exit program is in CAI.CAX1MAC2 member ACFDCXID. Chapter 21: User Exits 271

Idle Time Exit (IDLE) Exit Control Area DSECT ACFDCXCA EXIT=IDLE ACFDCXID DSECT *----------------------------------------------------------------* * IDLE TIME EXIT CONTROL AREA *----------------------------------------------------------------* XIDSCD DS A IMS SCD ADDRESS XIDGFLD DS A EXIT GLOBAL SYSTEM FIELD XIDXPWA DS A ADDRESS OF AVAILABLE WORK AREA XIDIPB DS A IMS IPB ADDRESS XIDUFLD DS A EXIT USER FIELD XIDIDATA DS A INPUT BUFFER ADDRESS XIDUSID DS CL8 XIDRKEY DS CL44 XIDRCLAS DS CL1 XIDRTYPE DS CL3 XIDRRSRC DS CL40 LOGONID RESOURCE KEY RESOURCE CLASS RESOURCE TYPE RESOURCE XIDFLAG1 DS X XIDF1MFS EQU X'80' INFORMATION FLAGS INPUT IN MFS FORMAT XIDVREQ DS C XID$BYPS EQU C'B' XID$NPV EQU C'N' XID$SIGN EQU C'S' XID$PVER EQU C'V' DS H DS 4A DS 0D XIDWORK DS XL128 XIDALEN EQU *-ACFDCXID EXIT VERIFY REQUEST..BYPASS VERIFY ONE TIME..SKIP IDLE VERIFY..FORCE SIGNON INSTEAD..STANDARD IDLE VERIFY RESERVED FOR FUTURES RESERVED FOR FUTURES DOUBLEWORD ALIGN WORK AREA START OF AVAILABLE WORK AREA LENGTH OF EXIT CONTROL AREA Exit Control Area Fields that Can Be Supplied or Changed XIDVREQ XID$PVER is the initial value for this indicator. This requests the standard idle password verification. XID$SIGN Should be set if the exit wants this user to be forced to sign on again, rather than the standard password verification. XID$BYPS Should be set if the exit wants to bypass idle time processing for this request but enforce it for the next request. 272 IMS Support Guide

Idle Time Exit (IDLE) XID$NPV Should be set if the exit does not want to enforce idle time processing for this user. Chapter 21: User Exits 273

Chapter 22: Migration Migration is the process of moving from one version of the IMS interface to another. It can involve tasks such as deinstalling a previous version, updating the IMS APPLDEF record, refreshing GSO APPLDEF records, verifying signon, storage, or security options, or changing exits. This section contains the following topics: Migrating from Prior Releases of the CA ACF2 IMS Interface to r9 or Above (see page 275) Migrating from Prior Releases of the CA ACF2 for z/os to r9 (see page 277) Migrating from Prior Releases of the CA ACF2 IMS Interface to r9 or Above In r9.0 of the CA ACF2 IMS interface, several popular USERMODs have been incorporated as control options in the IMS OPTS control record. If you have not implemented these USERMODs in the past, you do not need to do anything. The default values for these options correspond to the IMS interface processing in prior releases. If you have implemented a USERMOD in the past, simply select the value of the control option that corresponds to the USERMOD to enable the functionality you want. USERMOD Control Option Processing TI0690x BMPUSID(PSBNAME) If BMPUSID(PSBNAME) is specified, the IMS interface will not override the PSBNAME with the logonid of the BMP job as the userid in a non-message driven BMP. If BMPUSID(USERID) is specified, the IMS interface will override the PSBNAME with the logonid of the BMP job as the userid in a non-message driven BMP. This is the default value, and corresponds with the IMS interface processing in prior releases without the USERMOD. Chapter 22: Migration 275

Migrating from Prior Releases of the CA ACF2 IMS Interface to r9 or Above USERMOD Control Option Processing TI0691x NLIDDFLT If NLIDDFLT is specified, and a validation logonid does not exist on the logonid database, the IMS interface does not issue an error message for the invalid logonid. It performs the access validation using the IMS default logonid. If NONLIDDFLT is specified and a validation logonid does not exist on the logonid database, the IMS interface issues an error message for the invalid logonid and denies the resource access. This is the default value, and corresponds with the IMS interface processing in prior releases without the USERMOD. TI2998x BMPMSG(MSGUSER) If MSGUSER is specified for the BMPMSG control option, the logonid of the last message read by a message driven BMP is used for validation of any transactions or commands generated by the BMP. If BMPUSER is specified for the BMPMSG control option, the logonid of the BMP region is used for validation of any transactions or commands generated by a message driven BMP. This is the default value, and corresponds with the IMS interface processing in prior releases without the USERMOD. TI6692x ISRTNVAL If ISRTNVAL is specified, the IMS interface will not perform transaction validation for transactions generated using the IMS ISRT call to a non-modifiable TP-PCB. If NOISRTNVAL is specified, the IMS interface will perform transaction validation for transactions generated using the IMS ISRT call to a non-modifiable TP-PCB. This is the default value, and corresponds with the IMS interface processing in prior releases without the USERMOD. 276 IMS Support Guide

Migrating from Prior Releases of the CA ACF2 for z/os to r9 Migrating from Prior Releases of the CA ACF2 for z/os to r9 In r9 of the CA ACF2 base product, the logonid GROUP field has been added to the IMS MLID specification in the ACF2 ACFFDR. This was done to enable IMS interface processing that will move the default user GROUP into IMS control blocks when a GROUP is not specified at sign on. This should have no effect on your current IMS systems, and does not impact the ability of the IMS interface to function with prior releases of CA ACF2. If the GROUP field is found in the MLID, the default GROUP processing is performed. If the GROUP field is not found, the default GROUP processing is skipped. If you have implemented your own MLID definitions for your IMS regions, either in the ACFFDR or in dynamic GSO MLID records, you should change those definitions to include the GROUP field. Chapter 22: Migration 277

Appendix A: SMU Conversion IMS internal security is defined by a utility called the Security Maintenance Utility (SMU). IBM IMS release 9.1 is the last release of IMS that supports SMU based security definitions. In IMS release 10.1, SMU will not longer be supported. Prior to IMS release 9.1, IMS provided functionality to replace many of the features of SMU. In IMS release 9.1, IBM provided additional functionality to replace the remaining features of SMU with IMS internal mechanisms and external security calls. While running IMS 9.1, IMS installations need to migrate from any remaining SMU based definitions to these new facilities. This appendix discusses the conversion process from the following SMU functionality to CA ACF2 security: Type 1 AOI command security Application Group Names (AGNs) Terminal-based security for transactions and commands This appendix also discusses the following SMU functionality, which has no parallel in CA ACF2 security processing: Requirements for terminal signon Passwords for IMS resources Important: IMS release 9.1 is the first release of IMS to provide the internal mechanisms and external security calls to completely replace SMU functionality. You must be running IMS release 9.1 before you can perform the conversion process. This section contains the following topics: Converting Type 1 AOI Command Security to CA ACF2 (see page 280) Converting AGN Security to RAS (see page 298) Converting Terminal Based Security to CA ACF2 (see page 307) SMU Functionality Without CA ACF2 Equivalent (see page 318) Appendix A: SMU Conversion 279

Converting Type 1 AOI Command Security to CA ACF2 Converting Type 1 AOI Command Security to CA ACF2 SMU Security for Type 1 AOI Commands A type 1 AOI command is an IMS command that is issued by a transaction program using the IMS CMD communications call. SMU provides security for type 1 AOI commands by controlling the commands that can be issued by specific IMS transactions. SMU has two ways to define this security, both of which use the TCOMMAND and CTRANS keyword statements. In the first implementation, a )( TCOMMAND control statement is defined for a command, followed by CTRANS data statements for each transaction that can issue the command. In the second implementation, a )( CTRANS control statement is defined for a transaction, followed by TCOMMAND data statements for each command that can be issued by the transaction. In either case, the statements establish a relationship between IMS commands and the transactions that can issue them. 280 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 CA ACF2 Security for Type 1 AOI Commands The kind of security provided by the CA ACF2 IMS security interface for a type 1 AOI command is determined by the AOI= parameter specified in the IMS system definition TRANSACT macro for the transaction issuing the command. The possible values for the AOI parameter are NO, YES, TRAN, and CMD. If AOI=NO is specified or defaulted, the transaction is not allowed to issue any AOI type 1 commands. This restriction is enforced by IMS, and no calls are made to CA ACF2. If AOI=YES is specified, CA ACF2 performs security validations for AOI type 1 commands using the logonid of the user who entered the transaction issuing the command. This alternative, checking user access to the command, is the most granular security option. An individual user or a set of users can be given access to a command. The users can be given access to one command entered through a transaction and denied access to another command entered through the same transaction. This alternative also allows for individual accountability in the security process; when an access is denied, the violation is for the individual user. However, the migration from SMU AOI security, which is transaction-based, to this security, which is user-based, is not straightforward. If a user has access to a transaction that issues type 1 AOI commands, they must also be given access to each command the transaction issues. If this alternative is chosen, the ACFDCSM3 conversion program can be used to aid the migration from SMU AOI security to CA ACF2 security. If AOI=TRAN is specified, CA ACF2 performs security validations for AOI type 1 commands using the IMS default logonid with a SOURCE restriction of the transaction issuing the command. Because it is transaction based, this alternative does not provide user-based granularity in security policy. It does not provide individual accountability; if access is denied, the violation is for the IMS default logonid with the transaction as source. This option should only be chosen if CA ACF2 is used for transaction security. CA ACF2 controls user access to the transaction using transaction rules and controls what commands the transaction can issue using AOI command rules. This alternative, checking access to the command from the transaction, is a direct parallel to the SMU security process, and the migration from SMU AOI security to this security is straightforward. If this alternative is chosen, the ACFDCSM1 conversion program can be used to aid the migration from SMU AOI security to CA ACF2 security. AOI=CMD should not be implemented in an CA ACF2 security environment. Note: A mixed AOI security implementation is possible in a single IMS region. AOI=YES can be specified for some transactions, while AOI=TRAN is specified for others. Appendix A: SMU Conversion 281

Converting Type 1 AOI Command Security to CA ACF2 Implementation Steps for AOI=TRAN Security The following steps should be performed to implement AOI=TRAN ACF2 security for AOI commands: 1. Identify the division value for the IMS control records for the IMS region being converted. 2. Verify the resource type code in the IMS $TRANCM1 RESOURCE control record for the IMS region being converted. 3. Run the ACFDCSM1 conversion utility program using the SMU statements for the IMS region. 4. Review the ACFNRULE statements created by the ACFDCSM1 utility for accuracy. 5. Execute the ACFNRULE commands to update the AOI command resource rules. 6. Change the IMS system definition (IMS stage 1) for the IMS region to include the AOI=TRAN parameter in the TRANSACT macro for all transactions that issue AOI type 1 commands. The report generated by the ACFDCSM1 utility can be used to manually change the system definition, or the utility stage 1 update process can be used to automatically update the system definition. 7. Run the IMS system definition. 8. Change the ACF2 IMS $TRANCM1 RESOURCE record to specify VALIDATE. 9. Restart IMS 282 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 The ACFDCSM1 Utility The ACFDCSM1 utility can be used as a conversion aid if the AOI=TRAN alternative is chosen for the CA ACF2 security for AOI type 1 commands. This process is a direct conversion of the SMU security process. The ACFDCSM1 utility processes the SMU AOI control statements. For each command/transaction combination in the SMU statements, the utility generates an ACFNRULE statement to add a rule line to the command resource rule allowing access to the IMS command by the UID string of the IMS default logonid with a SOURCE restriction of the transaction name. The type code for this ACFNRULE statement is the type code extracted from the $TRANCM1 RESOURCE record, and the resource rule key is the full command verb. If the command specified in a TCOMMAND statement is *, indicating that the transaction can enter all commands, ACFNRULE statements are generated for each IMS command eligible for AOI. The ACFNRULE statements generated by this utility require that AOI=TRAN be specified in the IMS system definition (IMS stage 1) in the TRANSACT macro for any transaction that issues AOI type 1 commands. The utility optionally issues a report listing the transactions that will require AOI=TRAN in the IMS system definition (IMS stage 1). The utility can also optionally take as input a data set with the IMS system definition (IMS stage 1) statements containing the transaction definitions, and generate an updated set of statements that includes the AOI=TRAN parameter for the transactions that require it. Appendix A: SMU Conversion 283

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM1 Conversion Examples Example 1 If the UID string for the IMS default logonid is DEFAULTUID, the type code from the $TRANCM1 RESOURCE record is IC1, and the SMU input has one of the following: )( TCOMMAND DIS or CTRANS TRANAOI )( CTRANS TRANAOI TCOMMAND DIS The utility generates the following ACFNRULE command: Example 2 ACFNRULE TYPE(IC1) KEY(DISPLAY) - ADD(UID(DEFAULTUID) SOURCE(TRANAOI) ALLOW) If the UID string for the IMS default logonid is DEFAULTUID, the type code from the $TRANCM1 RESOURCE record is IC1, and the SMU input has one of the following: )( TCOMMAND * or CTRANS TRANAOI )( CTRANS TRANAOI TCOMMAND * The utility generates ACFNRULE commands for every IMS command eligible for AOI. ACFNRULE TYPE(IC1) KEY(ACTIVATE) - ADD(UID(DEFAULTUID) SOURCE(TRANAOI) ALLOW) ACFNRULE TYPE(IC1) KEY(ALLOCATE) - ADD(UID(DEFAULTUID) SOURCE(TRANAOI) ALLOW) ACFNRULE TYPE(IC1) KEY(ASSIGN) - ADD(UID(DEFAULTUID) SOURCE(TRANAOI) ALLOW) ACFDCSM1 Authorization Requirements There are no authorization requirements for the ACFDCSM1 utility. 284 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 Before Running the ACFDCSM1 Utility ACFDCSM1 Utility JCL The ACFDCSM1 utility uses the PARM=division input parameter to locate the IMS control records for the IMS region whose SMU input is being converted. One of these IMS control records is the IMS $TRANCM1 RESOURCE record, which controls security for type 1 AOI commands. The type code from this RESOURCE record is used in the ACFNRULE statements generated by the utility. Before running the ACFDCSM1 utility, you should verify the type code specified in the $TRANCM1 RESOURCE record for the IMS region. If there is no $TRANCM1 RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM1 utility will generate the ACFNRULE statements using the default (ICM) type code. Note: A type code can be specified in a $TRANCM1 RESOURCE record that specifies NOVALIDATE. The following is an example of the JCL required to execute the ACFDCSM1 conversion utility. // JOB //ACFDCSM1 EXEC PGM=ACFDCSM1,PARM=division //SMU DD DSN=smu.input,DISP=SHR //RULES DD DSN=acfnrule.output,DISP=SHR //REPORT DD SYSOUT=* //STG1IN DD DSN=ims.stage1.input,DISP=SHR //STG1OUT DD DSN=updated.ims.stage1,DISP=SHR Appendix A: SMU Conversion 285

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM1 Input Parameter The ACFDCSM1 utility requires the PARM=division input parameter. The value of the input parameter is the division field used to locate the IMS control records for the IMS region whose SMU input is being converted. This value is either the job name of the IMS control region or the MUSID field value in the logonid of the IMS control region. For more information about the division field and IMS control records, see the chapter "IMS Records." This division value is used to locate the IMS OPTS record for the IMS region. The default logonid from the OPTS record is used in the ACFNRULE statements generated by the utility. If there is no OPTS record for the division, the default value (IMSDFLT) is used for the IMS default logonid. The division value is also used to locate the IMS $TRANCM1 RESOURCE record for the IMS region. This RESOURCE record contains the security information for validation of type 1 AOI commands. The type code from this RESOURCE record is used in the ACFNRULE statements generated by the utility. If there is no $TRANCM1 RESOURCE record for the division or the type code is not specified in the RESOURCE record, the default value (ICM) is used as the AOI type 1 command resource rule type code. 286 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM1 DD Statements SMU RULES Refers to the input data set containing the SMU statements for the IMS region being processed. This data set must be a sequential data set, with a record length of 80. This DD statement is required. Refers to the output data set created by the ACFDCSM1 utility, containing the ACFNRULE statements generated by the conversion utility. The data set must be a sequential data set, with a record length of 80. REPORT STG1IN This DD statement is required. Refers to the output data set created by the ACFDCSM1 utility, containing a report listing the transactions in the IMS system definition (IMS stage 1) that require the AOI=TRAN parameter. If the DD statement specifies a data set rather than SYSOUT, the data set must be a sequential data set, with a record length of 137. This DD statement is optional. If the DD statement is not specified, the report is not generated. Refers to the input data set containing the IMS system definition (IMS stage 1) statements that include the TRANSACT macro statements for all transactions. The data set must be a sequential data set, with a record length of 80. This DD statement is optional. If the DD statement is not specified, the IMS system definition update processing is not performed. If this DD statement is specified, the STG1OUT DD statement is required. STG1OUT Refers to the output data set created by the ACFDCSM1 utility, containing the updated IMS system definition (IMS stage 1) statements. The AOI=TRAN parameter will be added to the TRANSACT macro definition for any transactions that issue AOI type 1 commands. The data set must be a sequential data set, with a record length of 80. This DD statement is optional. It is only required if the STG1IN DD statement is specified. Note: The STG1OUT DD statement should not point to the same data set as the STG1IN DD statement. Appendix A: SMU Conversion 287

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM1 Processing The ACFDCSM1 conversion utility parses the division parameter from the PARM= execution parameter in the ACFDCSM1 job stream. The utility uses this value to locate the IMS OPTS and $TRANCMD1 RESOURCE control records for the IMS region being processed. From the OPTS record, the utility identifies the IMS default logonid, and extracts the UID string for the default logonid from the CA ACF2 logonid database. If there is no OPTS record for the division, the default value (IMSDFLT) is used for the IMS default logonid. From the $TRANCM1 RESOURCE record, the utility identifies the type code that should be used for the type 1 AOI command resource rules. If there is no $TRANCM1 RESOURCE record for the division or no resource type code is specified in the $TRANCM1 RESOURCE record, the default value (ICM) is used for the AOI type 1 command resource rule type code. The utility then processes the SMU information from the data set specified in the SMU DD statement in the execution JCL. When the utility identifies a )( TCOMMAND control statement, it extracts the command name from the control statement If the command name in the TCOMMAND statement is an abbreviation of the full command verb, the utility replaces it with the full command verb. It then processes the CTRANS data statements that follow the )( TCOMMAND control statement. For each transaction identified in a CTRANS data statement, the utility generates an ACFNRULE command to add a rule line to the command resource rule allowing access to the IMS command by the UID string of the IMS default logonid with a SOURCE restriction of the transaction name. The type code for this ACFNRULE command is the type code extracted from the $TRANCM1 RESOURCE record, and the resource rule key is the full command verb. When the utility identifies a )(CTRANS control statement, it extracts the transaction name from the control statement. It then processes the TCOMMAND data statements that follow the )( CTRANS control statement. For each TCOMMAND data statement, the utility extracts the command name. If the command name in the TCOMMAND statement is an abbreviation of the full command verb, the utility replaces it with the full command verb. The utility generates an ACFNRULE command to add a rule line to the command resource rule allowing access to the IMS command by the UID string of the IMS default logonid with a SOURCE restriction of the transaction name. The type code for this ACFNRULE command is the type code extracted from the $TRANCM1 RESOURCE record, and the resource rule key is the full command verb. If the command specified in a TCOMMAND statement is *, indicating that the transaction can enter all commands, ACFNRULE statements are generated for each IMS command eligible for AOI. 288 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 If the REPORT DD statement is specified in the utility JCL, a report is generated listing all transactions identified in the SMU conversion process as issuing type 1 AOI commands. These transactions will require the AOI=TRAN parameter in the TRANSACT macro transaction definitions in the IMS system definition (IMS stage 1) statements. This report should be used to ensure that the appropriate transaction definitions are updated. If the STG1IN and STG1OUT DD statements are specified in the utility JCL, the utility will provide an updated IMS system definition, including the AOI=TRAN parameter in the TRANSACT macro transaction definition for any transaction identified in the SMU conversion process as issuing AOI type 1 commands. The utility copies the IMS system definition statements from the STG1IN data set to the STG1OUT data set. When it identifies a TRANSACT macro for a transaction identified in the SMU conversion process as issuing AOI type 1 commands, it adds an AOI=TRAN parameter to the end of the TRANSACT macro definition. Executing the ACFNRULE Statements The ACFNRULE statements generated by the ACFDCSM1 utility should be reviewed for accuracy before they are executed. The ACFNRULE statements can be executed in a batch TSO job. The following is an example of the JCL required to execute the ACFNRULE statements. // JOB //IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* EXEC PGM=IKJEFT01,REGION=0M //SYSTSIN DD DSN=acfnrule.input,DISP=SHR // Note: In order to successfully execute the ACFNRULE statements, the user must have a logonid with the SECURITY attribute, and all of the resource rules must be within the user SECURITY scope. Appendix A: SMU Conversion 289

Converting Type 1 AOI Command Security to CA ACF2 Implementation Steps for AOI-YES Security The following steps should be performed to implement AOI=YES ACF2 security for AOI commands: 1. Identify the division value for the IMS control records for the IMS region being converted. 2. Verify the resource type code in the IMS $PRITRAN and $TRANCM1 RESOURCE control records for the IMS region being converted. 3. Run the ACFDCSM3 conversion utility program using the SMU statements for the IMS region. 4. Review the ACFNRULE statements created by the ACFDCSM3 utility for accuracy. 5. Execute the ACFNRULE commands to update the AOI command resource rules. 6. Change the IMS system definition (IMS stage 1) for the IMS region to include the AOI=YES parameter in the TRANSACT macro for all transactions that issue AOI type 1 commands. The report generated by the ACFDCSM3 utility can be used to manually change the system definition, or the utility stage 1 update process can be used to automatically update the system definition. 7. Run the IMS system definition. 8. Change the ACF2 IMS $TRANCM1 RESOURCE record to specify VALIDATE. 9. Restart IMS. 290 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 The ACFDCSM3 Utility The ACFDCSM3 utility can be used as a conversion aid if the AOI=YES alternative is chosen for the ACF2 security for AOI type 1 commands. This process converts the transaction-based SMU security to a user-based security policy for the commands. The ACFDCSM3 utility processes the SMU AOI control statements. For each transaction in the SMU statements that can issue AOI type 1 commands, the utility obtains the transaction resource rule. For each command the transaction can issue, the utility generates ACFNRULE statements to add the rule lines from the transaction resource rule to the command resource rule. This process gives access to the command to every user that has access to the transaction. The type code for this ACFNRULE statement is the type code extracted from the $TRANCM1 RESOURCE record, and the resource rule key is the full command verb. If the command specified in a TCOMMAND statement is *, indicating that the transaction can enter all commands, ACFNRULE statements are generated for each IMS command eligible for AOI. The ACFNRULE statements generated by this utility require that AOI=YES be specified in the IMS system definition (IMS stage 1) in the TRANSACT macro for any transaction that issues AOI type 1 commands. The utility optionally issues a report listing the transactions that will require AOI=YES in the IMS system definition (IMS stage 1). The utility can also optionally take as input a data set with the IMS system definition (IMS stage 1) statements containing the transaction definitions, and generate an updated set of statements that includes the AOI=YES parameter for the transactions that require it. Appendix A: SMU Conversion 291

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM3 Conversion Examples Example 1 If the type code from the $TRANCM1 RESOURCE record is IC1, and the SMU input has one of the following: )( TCOMMAND DIS or CTRANS TRANAOI )( CTRANS TRANAOI TCOMMAND DIS The resource rule for the TRANAOI transaction is as follows: $KEY(TRANAOI) TYPE(ITR) UID(AOIUSER1) ALLOW UID(AOIUSER2) LOG The utility generates the following ACFNRULE commands: Example 2 ACFNRULE TYPE(IC1) KEY(DISPLAY) - ADD( - UID(AOIUSER1) ALLOW - ) ACFNRULE TYPE(IC1) KEY(DISPLAY) - ADD( - UID(AOIUSER2) LOG - ) If the $TRANCM1 RESOURCE record is IC1, and the SMU input has one of the following: )( TCOMMAND * or CTRANS TRANAOI )( CTRANS TRANAOI TCOMMAND * The resource rule for the TRANAOI transaction is as follows: $KEY(TRANAOI) TYPE(ITR) UID(AOIUSER1) ALLOW UID(AOIUSER2) LOG The utility generates ACFNRULE commands for every IMS command eligible for AOI 292 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 ACFNRULE TYPE(IC1) KEY(ACTIVATE) - ADD( - UID(AOIUSER1) ALLOW - ) ACFNRULE TYPE(IC1) KEY(ACTIVATE) - ADD( - UID(AOIUSER2) LOG - ) ACFNRULE TYPE(IC1) KEY(ASSIGN) - ADD( - UID(AOIUSER1) ALLOW - ) ACFNRULE TYPE(IC1) KEY(ASSIGN) - ADD( - UID(AOIUSER2) LOG - ) ACFDCSM3 Authorization Requirements To execute the ACFDCSM3 utility, a user must have a logonid with an unscoped SECURITY or AUDIT attribute. Before Running the ACFDCSM3 Utility The ACFDCSM3 utility uses the PARM=division input parameter to locate the IMS RESOURCE control records for the IMS region whose SMU input is being converted. The $PRITRAN and $TRANCM1 RESOURCE records are processed. The type code from the $PRITRAN RESOURCE control record is used to locate the resource rule for each transaction. The type code from the $TRANCM1 RESOURCE records is used in the ACFNRULE statements generated by the utility. Before running the ACFDCSM3 utility, you should verify the type codes specified in the $PRITRAN and $TRANCM1 RESOURCE records for the IMS region. If there is no $PRITRAN RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM3 utility will use the default type code (ITR) to locate the transaction resource rules. If there is no $TRANCM1 RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM3 utility will generate the ACFNRULE statements using the default type code (ICM). Note: A type code can be specified in a $TRANCM1 RESOURCE record that specifies NOVALIDATE. Appendix A: SMU Conversion 293

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM3 Utility JCL The following is an example of the JCL required to execute the ACFDCSM3 conversion utility. // JOB //ACFDCSM3 EXEC PGM=ACFDCSM3,PARM=division //SMU DD DSN=smu.input,DISP=SHR //RULES DD DSN=acfnrule.output,DISP=SHR //REPORT DD SYSOUT=* //STG1IN DD DSN=ims.stage1.input,DISP=SHR //STG1OUT DD DSN=updated.ims.stage1,DISP=SHR // ACFDCSM3 Input Parameters The ACFDCSM3 utility requires the PARM=division input parameter. The value of the input parameter is the division field used to locate the IMS RESOURCE control records for the IMS region whose SMU input is being converted. This value is either the job name of the IMS control region or the MUSID field value in the logonid of the IMS control region. For more information about the division field and IMS control records, see the chapter "IMS Records." The division value is used to locate the IMS $PRITRAN RESOURCE record for the IMS region. This RESOURCE record contains the security information for validation of transactions. The type code from this RESOURCE record is used to locate the resource rule for each AOI transaction. If there is no $PRITRAN RESOURCE record for the division or the type code is not specified in the RESOURCE record, the default value (ITR) is used to locate the transaction resource rules. The division value is also used to locate the IMS $TRANCM1 RESOURCE record for the IMS region. This RESOURCE record contains the security information for validation of type 1 AOI commands. The type code from this RESOURCE record is used in the ACFNRULE statements generated by the utility. If there is no $TRANCM1 RESOURCE record for the division or the type code is not specified in the RESOURCE record, the default value (ICM) is used as the AOI type 1 command resource rule type code. 294 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM3 DD Statements SMU RULES Refers to the input data set containing the SMU statements for the IMS region being processed. This data set must be a sequential data set, with a record length of 80. This DD statement is required. Refers to the output data set created by the ACFDCSM3 utility, containing the ACFNRULE statements generated by the conversion utility. The data set must be a sequential data set, with a record length of 80. REPORT STG1IN This DD statement is required. Refers to the output data set created by the ACFDCSM3 utility, containing a report listing the transactions in the IMS system definition (IMS stage 1) that require the AOI=YES parameter. If the DD statement specifies a data set rather than SYSOUT, the data set must be a sequential data set, with a record length of 137. This DD statement is optional. If the DD statement is not specified, the report is not generated. Refers to the input data set containing the IMS system definition (IMS stage 1) statements that include the TRANSACT macro statements for all transactions. The data set must be a sequential data set, with a record length of 80. This DD statement is optional. If the DD statement is not specified, the IMS system definition update processing is not performed. If this DD statement is specified, the STG1OUT DD statement is required. STG1OUT Refers to the output data set created by the ACFDCSM3 utility, containing the updated IMS system definition (IMS stage 1) statements. The AOI=YES parameter will be added to the TRANSACT macro definition for any transactions that issue AOI type 1 commands. The data set must be a sequential data set, with a record length of 80. This DD statement is optional. It is only required if the STG1IN DD statement is specified. Note: The STG1OUT DD statement should not point to the same data set as the STG1IN DD statement. Appendix A: SMU Conversion 295

Converting Type 1 AOI Command Security to CA ACF2 ACFDCSM3 Processing The ACFDCSM3 conversion utility parses the division parameter from the PARM= execution parameter in the ACFDCSM3 job stream. The utility uses this value to locate the IMS $PRITRAN and $TRANCMD1 RESOURCE control records for the IMS region being processed. From the $PRITRAN RESOURCE record, the utility identifies the type code that will be used to locate transaction resource rules. If there is no $PRITRAN RESOURCE record for the division or no resource type code is specified in the $PRITRAN RESOURCE record, the default value (ITR) is used for the transaction resource rule type code From the $TRANCM1 RESOURCE record, the utility identifies the type code that will be used for the type 1 AOI command resource rules. If there is no $TRANCM1 RESOURCE record for the division or no resource type code is specified in the $TRANCM1 RESOURCE record, the default value (ICM) is used for the AOI type 1 command resource rule type code. A directory is built for the transaction resource rules. This directory will be used to locate the resource rules for each AOI transaction. The utility then processes the SMU information from the data set specified in the SMU DD statement in the execution JCL. When the utility identifies a )( TCOMMAND control statement, it extracts the command name from the control statement If the command name in the TCOMMAND statement is an abbreviation of the full command verb, the utility replaces it with the full command verb. It then processes the CTRANS data statements that follow the )( TCOMMAND control statement. For each transaction identified in a CTRANS data statement, the utility locates the resource rule that controls access to the transaction. The rule decompiler is called to return a decompiled version of the transaction resource rule. The utility then generates ACFNRULE commands to add the rule lines from the transaction resource rule to the command resource rule. The type code for this ACFNRULE command is the type code extracted from the $TRANCM1 RESOURCE record, and the resource rule key is the full command verb. When the utility identifies a )(CTRANS control statement, it extracts the transaction name from the control statement. The utility locates the resource rule that controls access to the transaction and calls the rule decompiler to return a decompiled version of the transaction resource rule. It then processes the TCOMMAND data statements that follow the )( CTRANS control statement. For each TCOMMAND data statement, the utility extracts the command name. If the command name in the TCOMMAND statement is an abbreviation of the full command verb, the utility replaces it with the full command verb. The utility then generates ACFNRULE commands to add the rule lines from the transaction resource rule to the command resource rule. The type code for this ACFNRULE command is the type code extracted from the $TRANCM1 RESOURCE record, and the resource rule key is the full command verb. 296 IMS Support Guide

Converting Type 1 AOI Command Security to CA ACF2 If the command specified in a TCOMMAND statement is *, indicating that transaction can enter all commands, ACFNRULE statements are generated for each IMS command eligible for AOI. If the REPORT DD statement is specified in the utility JCL, a report is generated listing all transactions identified in the SMU conversion process as issuing type 1 AOI commands. These transactions will require the AOI=YES parameter in the TRANSACT macro transaction definitions in the IMS system definition (IMS stage 1) statements. This report should be used to ensure that the appropriate transaction definitions are updated. If the STG1IN and STG1OUT DD statements are specified in the utility JCL, the utility will provide an updated IMS system definition, including the AOI=YES parameter in the TRANSACT macro transaction definition for any transaction identified in the SMU conversion process as issuing AOI type 1 commands. The utility copies the IMS system definition statements from the STG1IN data set to the STG1OUT data set. When it identifies a TRANSACT macro for a transaction identified in the SMU conversion process as issuing AOI type 1 commands, it adds an AOI=YES parameter to the end of the TRANSACT macro definition. Executing the ACFNRULE Statements The ACFNRULE statements generated by the ACFDCSM3 utility should be reviewed for accuracy before they are executed. The ACFNRULE statements can be executed in a batch TSO job. The following is an example of the JCL required to execute the ACFNRULE statements. // JOB //IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* EXEC PGM=IKJEFT01,REGION=0M //SYSTSIN DD DSN=acfnrule.input,DISP=SHR // Note: In order to successfully execute the ACFNRULE statements, the user must have a logonid with the SECURITY attribute, and all of the resource rules must be within the user SECURITY scope. Appendix A: SMU Conversion 297

Converting AGN Security to RAS Converting AGN Security to RAS Application Group Names An application group name (AGN) identifies a group of transactions, terminals, and PSBs that an IMS dependent region, such as a BMP, is permitted to access. AGNs are defined for an IMS system using the Security Maintenance Utility (SMU). The following shows how an AGN can be defined in the SMU input. )( AGN name AGLTERM AGPSB AGTRAN AGN name terminal name PSB name transaction AGN is a constant and name is the name selected for the AGN. This statement identifies the terminals, PSBs, and transactions that follow it as a group that restricts access by dependent regions. The name must be eight characters or less and each AGN name must be unique. AGLTERM terminal name AGLTERM is a constant and terminal name is the logical terminal (LTERM) name for a terminal included in the AGN. AGPSB PSB name AGPSB is a constant and PSB name is the name of a PSB included in the AGN. AGTRAN transaction AGTRAN is a constant and transaction is the name of a transaction included in the AGN. An IMS dependent region requests the use of an AGN by specifying the AGN name in the startup JCL for the dependent region. IMS performs a security validation to verify that the dependent region is permitted to use the AGN. The IMS control region then limits the dependent region's use of IMS resources to those defined in the AGN that was requested. 298 IMS Support Guide

Converting AGN Security to RAS Resource Access Security In IMS Release 9.1, IMS introduced Resource Access Security (RAS) as a replacement for AGNs and AGN security. In IMS release 10.1, AGNs and AGN security will be removed from the product. With RAS, IMS performs a direct security validation of the terminals, PSBs, and transactions that a dependent region can access. For example, before a transaction is scheduled to execute in a message processing regions, IMS performs a security validation to see if the logonid of the message processing region is allowed to execute the transaction. If not, the transaction will not be scheduled in that message processing region. CA ACF2 Security for RAS Resources The CA ACF2 IMS interface security for RAS resources is controlled by IMS RESOURCE control records. For more information about the IMS RESOURCE records and RAS security, see the chapter "AGN and RAS Resource Security." Each kind of RAS resource is controlled by its own RESOURCE record, which specifies whether the resource will be validated, and the resource type code for the resource rules that secure the resource. The following is a table of the different RAS resources, the RESOURCE record that controls the security process for that resource, and the default type code used if no RESOURCE record exists for that resource. RAS Resource RESOURCE record Type code PSBs $RASPSB IPS Transactions $RASTRAN ITR LTERMs $RASTERM IRT Because the different RAS resources are controlled by different RESOURCE records, security processing can be enabled for one kind of RAS resource, while it is disabled for another. The IMS $RASTRAN RESOURCE record controls IMS dependent region access to transactions. The IMS $PRITRAN and $SECTRAN RESOURCE records control user access to execute transactions. These RESOURCE records may specify the same type code if the same set of transaction resource rules is used to control all access, or different type codes if different sets of resource rule are desired. The CA ACF2 IMS security interface already performs security for PSB's for IMS BMP regions using the $PSB RESOURCE record. If this is sufficient PSB security, RAS PSB security can be set to NOVALIDATE. See the "PSB Security" chapter for more information about PSB security with the CA ACF2 IMS interface. Appendix A: SMU Conversion 299

Converting AGN Security to RAS Converting AGN Security to RAS with CA ACF2 Before going through the effort of converting your AGN definitions to RAS security, you should evaluate whether you need this level of security. Many IMS installations implemented AGN security many years ago as a means of securing the use of PSBs in IMS BMP regions. Because of its design, when AGN security is implemented, it must be implemented for all IMS dependent regions. This lead to the definition of AGNs for message processing regions that look like this: )( AGN MSG1 AGLTERM AGPSB AGTRAN ALL ALL ALL These AGNs are designed to prevent AGN security, implemented for PSB security in BMPs, from interfering in the processing of message processing regions. If this description matches your implementation, you should evaluate whether existing PSB security in the CA ACF2 IMS interface is sufficient for your security requirements, and if AGN security can be eliminated rather than converted. If you choose to convert your AGN security to RAS, the ACFDCSM2 conversion program can be used to aid the migration. Migration Steps: AGN Security to RAS Security The following steps should be performed to migrate from AGN security to RAS security: 1. Determine whether you want to perform RAS security. If the existing CA ACF2 PSB security is sufficient for your security requirements, a complete AGN to RAS conversion may not be necessary. 2. Identify the division value for the IMS control records for the IMS region being converted. 3. Verify the VALIDATE setting and the resource type code in the IMS $AGN RESOURCE control record for the IMS region being converted. 4. Verify the resource type codes in the IMS $RASPSB, $RASTRAN, and $RASTERM RESOURCE control records for the IMS region being converted. 5. Run the ACFDCSM2 conversion utility program using the SMU statements for the IMS region. 6. Review the ACFNRULE statements created by the ACFDCSM2 utility for accuracy. 7. Execute the ACFNRULE commands to create or update the RAS element resource rules. 8. For the RAS elements that you want to secure, change the corresponding IMS RESOURCE record to specify VALIDATE. 9. Restart IMS. 300 IMS Support Guide

Converting AGN Security to RAS The ACFDCSM2 Utility The ACFDCSM2 utility can be used to simplify the conversion from AGN security to RAS. The utility processes the SMU control statements for the IMS region being converted. For each AGN defined in the SMU input, the utility locates the resource rule controlling access to the AGN. For each element assigned to the AGN in the SMU input, the utility generates ACFNRULE statements to update the resource rule for the element with the rule lines from the AGN resource rule. This allows the same access to the AGN element that was held on the AGN. If the element for the AGN is ALL, the utility generates ACFNRULE commands to add the rule lines from the AGN resource rule to every resource rule for the element type. Appendix A: SMU Conversion 301

Converting AGN Security to RAS ACFDCSM2 Conversion Examples Example 1 If the AGN resource type code is IAG, the RAS PSB type code is IPS, and SMU input has the following: )( AGN BMP1 AGPSB PGMBMP1 The AGN resource rule has the following $KEY(BMP1) TYPE(IAG) UID(BMPUSER1) ALLOW UID(BMPUSER2) ALLOW The utility generates the following ACFNRULE commands. These ACFNRULE commands create or update the PGMBMP1 resource rule, giving access to the PSB to the same set of users that have access to the AGN. Example 2 ACFNRULE TYPE(IPS) KEY(PGMBMP1) - ADD - (UID(BMPUSER1) ALLOW - ) ACFNRULE TYPE(IPS) KEY(PGMBMP1) - ADD - (UID(BMPUSER2) ALLOW - ) If the AGN resource type code is IAG, the RAS PSB type code is IPS, and SMU input has the following: )( AGN MSG1 AGPSB ALL )( AGN BMP1 AGPSB PGMBMP1 The AGN resource rules have the following: $KEY(MSG1) TYPE(IAG) UID(MSGUSER1) ALLOW $KEY(BMP1) TYPE(IAG) UID(BMPUSER1) ALLOW The following are two existing PSB resource rules: $KEY(PSB2) TYPE(IPS) 302 IMS Support Guide

Converting AGN Security to RAS UID(BMPUSER2) ALLOW $KEY(PSB3) TYPE(IPS) UID(BMPUSER3) ALLOW The utility generates the following ACFNRULE commands: ACFNRULE TYPE(IPS) KEY(PGMBMP1) - ADD - (UID(MSGUSER1) ALLOW - ) ACFNRULE TYPE(IPS) KEY(PSB2) - ADD - (UID(MSGUSER) ALLOW - ) ACFNRULE TYPE(IPS) KEY(PSB3) - ADD - (UID(MSGUSER) ALLOW - ) ACFNRULE TYPE(IPS) KEY(PGMBMP1) - ADD - (UID(BMPUSER) ALLOW - ) The first three ACFNRULE commands are in response to the AGPSB ALL data statement for AGN MSG1. These commands change every existing PSB resource rule (commands 2 and 3) and any PSB resource rule that will be created by the utility (command 1), giving access to the PSB to the same set of users that have access to the AGN. The last ACFNRULE command is in response to the AGPSB PGMBMP1 statement for AGN BMP1. This command gives access to the PSB to the same set of users that have access to the AGN. ACFDCSM2 Authorization Requirements To execute the ACFDCSM2 utility, a user must have a logonid with an unscoped SECURITY or AUDIT attribute. Appendix A: SMU Conversion 303

Converting AGN Security to RAS Before Running the ACFDCSM2 Utility ACFDCSM2 Utility JCL The ACFDCSM2 utility uses the PARM=division input parameter to locate the IMS RESOURCE control records for the IMS region whose SMU input is being converted. The $AGN and the RAS element RESOURCE control records are processed. The type code from the $AGN RESOURCE control record is used to locate the resource rule for the AGN. The type codes from the RAS element RESOURCE records are used in the ACFNRULE statements generated by the utility. Before running the ACFDCSM2 utility, you should verify the type codes specified in the $AGN and RAS element RESOURCE records for the IMS region. If there is no $AGN RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM2 utility will use the default type code (IAG) to locate the resource rule for each AGN. For each RAS element type, if there is no RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM2 utility will generate the ACFNRULE statements using the default type code for that element type. Note: A type code can be specified in a $RASPSB, $RASTRAN, or $RASTERM RESOURCE record that specifies NOVALIDATE. The following is an example of the JCL required to execute the ACFDCSM2 conversion utility: // JOB //ACFDCSM2 EXEC PGM=ACFDCSM2,PARM=division //SMU DD DSN=smu.input,DISP=SHR //RULES DD DSN=acfnrule.output,DISP=SHR // 304 IMS Support Guide

Converting AGN Security to RAS ACFDCSM2 Input Parameters ACFDCSM2 DD Statements The ACFDCSM2 utility requires the PARM=division input parameter. The value of the input parameter is the division field used to locate the IMS RESOURCE control records for the IMS region whose SMU input is being converted. This value is either the job name of the IMS control region or the MUSID field value in the logonid of the IMS control region. For more information about the division field and IMS control records see the chapter "IMS Records." The division value is used to locate the IMS $AGN RESOURCE record for the IMS region. This RESOURCE record contains the security information for validation of AGNs. The utility uses this RESOURCE record to verify that AGN validation is performed in the IMS region, and the type code is used to locate the resource rule for each AGN. If there is no $AGN RESOURCE record for the division, the default value (IAG) is used to locate the AGN resource rules. The division value is also used to locate the IMS RESOURCE records for the RAS elements ($RASTRAN, $RASTERM, and $RASPSB) for the IMS region. The type codes from these RESOURCE records are used in the ACFNRULE statements generated by the utility. For each RAS element, if there is no RESOURCE record for the division, the default value is used for the resource rule type code. SMU RULES This DD statement is used to refer to the input data set containing the SMU statements for the IMS region being processed. This data set must be a sequential data set, with a record length of 80. This DD statement is required. This DD statement is used to refer to the output data set created by the ACFDCSM2 utility, containing the ACFNRULE statements generated by the conversion utility. The data set must be a sequential data set, with a record length of 80. This DD statement is required. Appendix A: SMU Conversion 305

Converting AGN Security to RAS ACFDCSM2 Processing The ACFDCSM2 conversion utility parses the division parameter from the PARM= execution parameter in the ACFDCSM2 job stream. The utility uses this value to locate the IMS RESOURCE control records for the IMS region being processed. From the $AGN RESOURCE record, the utility verifies that AGN validation is performed in the IMS region. The utility extracts the type code, which will be used to locate the AGN resource rules. If there is no $AGN RESOURCE record for the division or no resource type code is specified in the $AGN RESOURCE record, the default value (IAG) is used for the AGN resource rule type code. From the RAS element RESOURCE records, the utility identifies the type codes that correspond to the resource rules for those resources. For each RAS element type, if there is no RESOURCE record for the division or no resource type code is specified in the RESOURCE record, the default value is used for the resource rule type code. The utility then processes the SMU information from the data set specified in the SMU DD statement in the execution JCL. When the utility identifies a )( AGN control statement, it extracts the AGN name from the control statement It then processes the AGPSB, AGTRAN, and AGLTERM data statements that follow the )( AGN control statement. For each AGN element, the utility adds an AGN/element entry to an in-storage table. If AGPSB ALL was specified in any AGN data statement, a directory is built of all existing RAS PSB resource rules. This directory and the AGN/element table are processed to create an in-storage table of all RAS PSB resource rule keys, both from existing resource rules (using the directory) and for resource rules that may be created by the utility (using the AGN/element table). If AGTRAN ALL was specified in any AGN data statement, a directory is built of all existing RAS TRAN resource rules. This directory and the AGN/element table are processed to create an in-storage table of all RAS TRAN resource rule keys, both from existing resource rules (using the directory) and for resource rules that may be created by the utility (using the AGN/element table). If AGLTERM ALL was specified in any AGN data statement, a directory is built of all existing RAS TERM resource rules. This directory and the AGN/element table are processed to create an in-storage table of all RAS TERM resource rule keys, both from existing resource rules (using the directory) and for resource rules that may be created by the utility (using the AGN/element table). A directory is built for AGN resource rules. This directory will be used to locate the resource rules for each AGN. 306 IMS Support Guide

Converting Terminal Based Security to CA ACF2 The utility then processes the AGN/element table. For each unique AGN, the utility locates the resource rule that controls access to the AGN. The rule decompiler is called to return a decompiled version of the AGN resource rule. For each element associated with the AGN, the utility generates ACFNRULE commands to add the rule lines from the AGN resource rule to the element resource rule. If the element for the AGN is ALL, the utility uses the in-storage table of resource keys to generate ACFNRULE commands to add the rule lines from the AGN resource rule to every resource rule for the element type. Executing the ACFNRULE Statements The ACFNRULE statements generated by the ACFDCSM2 utility should be reviewed for accuracy before they are executed. The ACFNRULE statements can be executed in a batch TSO job. The following is an example of the JCL required to execute the ACFNRULE statements. // JOB //IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* EXEC PGM=IKJEFT01,REGION=0M //SYSTSIN DD DSN=acfnrule.input,DISP=SHR // Note: In order to successfully execute the ACFNRULE statements, the user must have a logonid with the SECURITY attribute, and all of the resource rules must be within the user SECURITY scope. Converting Terminal Based Security to CA ACF2 SMU Terminal-Based Security for Transactions and Commands SMU provides security for transactions and commands by identifying the terminals at which the transactions and commands can be entered. This architecture is called terminal-based security. SMU has two ways to define this security, both of which use the TERMINAL, TRANSACT, and COMMAND keyword statements. In the first implementation, a )( TERMINAL control statement is defined for an IMS logical terminal (LTERM), followed by TRANSACT and COMMAND data statements for the transactions and commands that can entered at that terminal. In the second implementation, a )( TRANSACT or )( COMMAND control statement is defined for a transaction or command, followed by TERMINAL data statements for each terminal that can enter the transaction or command. In either case, the statements establish a relationship between IMS LTERMS and the IMS commands and transactions that can be entered at the terminals. Appendix A: SMU Conversion 307

Converting Terminal Based Security to CA ACF2 CA ACF2 Security Transactions and Commands The CA ACF2 IMS interface has always provided security for IMS transactions and commands that are entered at a terminal. For more information about CA ACF2 and IMS transaction security, see the chapter "Transaction Security." For more information about CA ACF2 and IMS command security, see the chapter "IMS Command Security." The kind of security provided by the CA ACF2 IMS security interface for transactions and commands from an IMS terminal is determined by the CA ACF2 resource rule written for the transaction or command. Either user-based security or terminal-based security can be implemented in the CA ACF2 resource rules. To provide user-based security in CA ACF2 for an IMS transaction or command, resource rule lines should be written in the resource rule for the transaction or command permitting access to specific users or groups of users with the UID mask. This alternative is not a direct parallel to SMU terminal-based security. However, because it is based on user identification and user-based security policy, it is the best practice implementation for IMS security, and should be used unless it is impractical or impossible. To provide terminal-based security in CA ACF2 for an IMS transaction or command, a resource rule line should be written in the resource rule for the transaction or command with a full mask value in the UID mask and a SOURCE restriction of the IMS physical terminal name. This rule line gives access to the IMS transaction or command to any user so long as the transaction or command is entered at that terminal. This alternative, permitting access to the transaction or command to any user if the access is from the terminal, is a direct parallel to the SMU terminal-based security. Because it is terminal based, this alternative does not provide user-level granularity in security policy. It should only be used if a terminal user cannot sign on, it is not important who the terminal user is, or if the physical security for the IMS terminal is sufficient to determine who the terminal user is. It is also possible to combine user-based security in CA ACF2 with terminal-based security features. If it is important that an IMS transaction or command only be entered by a specific set of users at a specific terminal, the resource rule lines can be written permitting access to the specific set of users with a SOURCE restriction of the IMS physical terminal. 308 IMS Support Guide

Converting Terminal Based Security to CA ACF2 Converting SMU Terminal-Based Security to CA ACF2 Because the CA ACF2 IMS interface has always provided security for IMS transactions and commands, most IMS installations have already converted from SMU terminal-based security to CA ACF2 security. If you have IMS regions that still have SMU terminal security definitions, you should evaluate whether you need to convert the SMU security definitions to CA ACF2 security, and whether the CA ACF2 security should be user-based, terminal-based, or both. If you are converting the SMU terminal security for an IMS region that also uses the CA ACF2 IMS interface for command and transaction security, you already have security policy defined for your IMS transactions and commands. The CA ACF2 security policy should be examined to determine if the SMU terminal-based security definitions are redundant and can be eliminated. If the terminal restrictions provided in SMU are required, SOURCE restrictions may need to be added to the CA ACF2 security policy to provide the same functionality. If you are converting an IMS region that does not already use the CA ACF2 IMS security interface, or if CA ACF2 security for transactions or commands has been disabled in the IMS region, you probably do not have security policy defined for your IMS transactions and commands. The best practice implementation for CA ACF2 security for IMS transactions and commands is a user-based security implementation. You must determine who your IMS users are and what IMS transactions and commands they should have access to, and write your security policy accordingly. This is a manual process, and the SMU terminal security definitions are usually of little help. If you decide on a terminal-based security implementation, the SMU terminal security definitions provide the roadmap for the security policy. In either case, the ACFDCSM4 conversion program can be used to aid the migration from SMU terminal security to CA ACF2 security. Appendix A: SMU Conversion 309

Converting Terminal Based Security to CA ACF2 Migrating SMU Terminal Security to CA ACF2 The following steps should be performed to migrate from AGN security to RAS security: 1. Determine whether you need to perform the conversion of the SMU terminal-based security definitions. If existing CA ACF2 transaction and command security policy is sufficient, conversion of the SMU terminal security may not be necessary. 2. Determine whether you want to convert the SMU terminal security definitions to a user-based CA ACF2 security policy or a terminal-based CA ACF2 security policy. 3. Identify the division value for the IMS control records for the IMS region being converted. 4. Verify the resource type codes in the IMS $PRITRAN and $COMMAND RESOURCE records for the IMS region being converted. 5. Run the ACFDCSM4 conversion utility program using the SMU statements for the IMS region. 6. Modify the ACFNRULE statements created by the ACFDCSM4 utility for reflect your choice of user-based or terminal-based security. 7. Execute the ACFNRULE commands to create or update the transaction and command resource rules. 8. If transaction or command security is currently disabled in the IMS RESOURCE records, change the corresponding IMS RESOURCE record to specify VALIDATE. 9. Restart IMS. 310 IMS Support Guide

Converting Terminal Based Security to CA ACF2 The ACFDCSM4 Utility The ACFDCSM4 utility can be used to provide the skeletons for the security policy in a conversion from SMU terminal security to CA ACF2 security. The utility processes the SMU security definitions for the IMS region being converted. For each terminal/transaction or terminal/command combination in the SMU definitions, the utility generates an ACFNRULE statement for the corresponding CA ACF2 transaction or command resource rule. The resource rule line in the ACFNRULE statement has a dummy UID value, and a SOURCE restriction of the IMS LTERM value from the SMU definition. If you are implementing a user-based security policy, you should determine who the users are who enter the transaction or command at the IMS terminal. You should then change the UID value in the ACFNRULE statement to reflect those users, and remove the SOURCE restriction. If necessary, the ACFNRULE statement can be duplicated to permit access from different sets of users. If you are implementing a terminal-based security policy, you should determine what IMS physical terminal name corresponds to the LTERM name in the SMU definition. This physical terminal name can be obtained from the IMS system definitions (IMS stage 1). You should then change the UID value in the ACFNRULE statement to a full mask value, and change the SOURCE restriction in the ACFNRULE statement to the IMS physical terminal name. If you are implementing user-based security policy with terminal restrictions, you should determine who the users are who enter the transaction or command at the IMS terminal and the IMS physical terminal name for the IMS LTERM. You should then change the UID value in the ACFNRULE statement to reflect the users, and change the SOURCE restriction in the ACFNRULE statement to the IMS physical terminal name. Again, if necessary, the ACFNRULE statement can be duplicated to permit access from different sets of users. Appendix A: SMU Conversion 311

Converting Terminal Based Security to CA ACF2 ACFDCSM4 Conversion Examples Example 1 If the transaction resource type code is ITR, the command type code is ICM, and SMU input has the following: )( TERMINAL TERM1 TRANSACT PAYINQ COMMAND DISPLAY The utility generates the following ACFNRULE commands: Example 2 ACFNRULE TYPE(ITR) KEY(PAYINQ) - ADD - (UID(????????????????????????) SOURCE(TERM1) ALLOW - ) ACFNRULE TYPE(ICM) KEY(DISPLAY) - ADD - (UID(????????????????????????) SOURCE(TERM1) ALLOW - ) If the transaction resource type code is ITR and SMU input has the following: )( TRANSACT PAYINQ TERMINAL TERM1 TERMINAL TERM2 The utility generates the following ACFNRULE commands: ACFNRULE TYPE(ITR) KEY(PAYINQ) - ADD - (UID(????????????????????????) SOURCE(TERM1) ALLOW - ) ACFNRULE TYPE(ITR) KEY(PAYINQ) - ADD - (UID(????????????????????????) SOURCE(TERM2) ALLOW - ) ACFDCSM4 Authorization Requirements There are no authorization requirements for the ACFDCSM4 utility. 312 IMS Support Guide

Converting Terminal Based Security to CA ACF2 Before Running the ACFDCSM4 Utility ACFDCSM4 Utility JCL The ACFDCSM4 utility uses the PARM=division input parameter to locate the IMS RESOURCE control records for the IMS region whose SMU input is being converted. The $PRITRAN and $COMMAND RESOURCE records are processed. The type code from the $PRITRAN record is used in the ACFNRULE statements for transactions generated by the utility. The type code from the $COMMAND record is used in the ACFNRULE statements for commands. Before running the ACFDCSM4 utility, you should verify the type codes specified in the $PRITRAN and $COMMAND records for the IMS region. If there is no $PRITRAN RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM4 utility will generate the ACFNRULE statements for transactions using the default type code (ITR). If there is no $COMMAND RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM4 utility will generate the ACFNRULE statements for commands using the default type code (ICM). Note: A type code can be specified in a $PRITRAN or $COMMAND RESOURCE record that specifies NOVALIDATE. The following is an example of the JCL required to execute the ACFDCSM4 conversion utility. // JOB //ACFDCSM4 EXEC PGM=ACFDCSM4,PARM=division //SMU DD DSN=smu.input,DISP=SHR //RULES DD DSN=acfnrule.output,DISP=SHR // Appendix A: SMU Conversion 313

Converting Terminal Based Security to CA ACF2 ACFDCSM4 Input Parameters ACFDCSM4 DD Statements The ACFDCSM4 utility requires the PARM=division input parameter. The value of the input parameter is the division field used to locate the IMS RESOURCE control records for the IMS region whose SMU input is being converted. This value is either the job name of the IMS control region or the MUSID field value in the logonid of the IMS control region. Refer to the "IMS Records" chapter for more information about the division field and IMS control records. The division value is used to locate the IMS $PRITRAN RESOURCE record for the IMS region. This RESOURCE record contains the security information for validation of transactions. The type code from this RESOURCE record is used in the transaction ACFNRULE statements generated by the utility.. If there is no $PRITRAN RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM4 utility will generate the transaction ACFNRULE statements using the default type code (ITR). The division value is also used to locate the IMS $COMMAND RESOURCE record for the IMS region. This RESOURCE record contains the security information for validation of commands. The type code from this RESOURCE record is used in the command ACFNRULE statements generated by the utility. If there is no $COMMAND RESOURCE record for the division or the type code is not specified in the RESOURCE record, the ACFDCSM4 utility will generate the command ACFNRULE statements using the default type code (ICM). SMU RULES Refers to the input data set containing the SMU statements for the IMS region being processed. This data set must be a sequential data set, with a record length of 80. This DD statement is required. Refers to the output data set created by the ACFDCSM4 utility, containing the ACFNRULE statements generated by the conversion utility. The data set must be a sequential data set, with a record length of 80. This DD statement is required. 314 IMS Support Guide

Converting Terminal Based Security to CA ACF2 ACFDCSM4 Processing The ACFDCSM4 conversion utility parses the division parameter from the PARM= execution parameter in the ACFDCSM4 job stream. The utility uses this value to locate the IMS RESOURCE control records for the IMS region being processed. From the $PRITRAN RESOURCE record, the utility extracts the type code. If there is no $PRITRAN RESOURCE record for the division or no resource type code is specified in the $PRITRAN RESOURCE record, the default value (ITR) is used for the transaction resource rule type code. From the $COMMAND RESOURCE record, the utility extracts the type code. If there is no $COMMAND RESOURCE record for the division or no resource type code is specified in the $COMMAND RESOURCE record, the default value (ICM) is used for the command resource rule type code. The utility then processes the SMU information from the data set specified in the SMU DD statement in the execution JCL. When the utility identifies a )( TERMINAL control statement, it extracts the LTERM name from the control statement It then processes the data statements that follow the )( TERMINAL control statement. If a TRANSACT data statement is found, the utility generates ACFNRULE commands to add a rule line to the resource rule for the transaction. The type code for this ACFNRULE command is the type code extracted from the $PRITRAN RESOURCE record, and the resource rule key is the transaction name. The UID value is a dummy value ('????????????????????????') and the rule line contains a SOURCE restriction for the LTERM name. If a COMMAND data statement is found, the utility extracts the command name from the data statement If the command name in the COMMAND statement is an abbreviation of the full command verb, the utility replaces it with the full command verb. The utility then generates ACFNRULE commands to add a rule line to the resource rule for the command. The type code for this ACFNRULE command is the type code extracted from the $COMMAND RESOURCE record, and the resource rule key is the full command verb. The UID value is a dummy value ('????????????????????????') and the rule line contains a SOURCE restriction for the LTERM name. When the utility identifies a )( TRANSACT control statement, it extracts the transaction name from the control statement It then processes the data statements that follow the )( TRANSACT control statement. If a TERMINAL data statement is found, the utility generates ACFNRULE commands to add a rule line to the resource rule for the transaction. The type code for this ACFNRULE command is the type code extracted from the $PRITRAN RESOURCE record, and the resource rule key is the transaction name. The UID value is a dummy value ('????????????????????????') and the rule line contains a SOURCE restriction for the LTERM name. Appendix A: SMU Conversion 315

Converting Terminal Based Security to CA ACF2 When the utility identifies a )( COMMAND control statement, it extracts the command name from the control statement If the command name in the COMMAND statement is an abbreviation of the full command verb, the utility replaces it with the full command verb. It then processes the data statements that follow the )( CIOMMAND control statement. If a TERMINAL data statement is found, the utility generates ACFNRULE commands to add a rule line to the resource rule for the command. The type code for this ACFNRULE command is the type code extracted from the $COMMAND RESOURCE record, and the resource rule key is the full command verb. The UID value is a dummy value ('????????????????????????') and the rule line contains a SOURCE restriction for the LTERM name. 316 IMS Support Guide

Converting Terminal Based Security to CA ACF2 Executing the ACFNRULE Statements Before you execute the ACFNRULE statements, they must be modified according to your implementation of user-based or terminal-based security. If you are implementing a user-based security policy, you should determine who the users are who enter the transaction or command at the IMS terminal. You should then change the UID value in the ACFNRULE statement to reflect those users, and remove the SOURCE restriction. If necessary, the ACFNRULE statement can be duplicated to permit access for different sets of users. If you are implementing a terminal-based security policy, you should determine what IMS physical terminal name corresponds to the LTERM name in the SMU definition. This physical terminal name can be obtained from the IMS system definitions (IMS stage 1). You should then change the UID value in the ACFNRULE statement to a full mask value, and change the SOURCE restriction in the ACFNRULE statement to the IMS physical terminal name. If you are implementing user-based security policy with terminal restrictions, you should determine who the users are who enter the transaction or command at the IMS terminal and the IMS physical terminal name for the IMS LTERM. You should then change the UID value in the ACFNRULE statement to reflect the users, and change the SOURCE restriction in the ACFNRULE statement to the IMS physical terminal name. Again, if necessary, the ACFNRULE statement can be duplicated to permit access for different sets of users. After they have been modified, the ACFNRULE statements can be executed in a batch TSO job. The following is an example of the JCL required to execute the ACFNRULE statements. // JOB //IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* EXEC PGM=IKJEFT01,REGION=0M //SYSTSIN DD DSN=acfnrule.input,DISP=SHR // Note: In order to successfully execute the ACFNRULE statements, the user must have a logonid with the SECURITY attribute, and all of the resource rules must be within the user SECURITY scope. Appendix A: SMU Conversion 317

SMU Functionality Without CA ACF2 Equivalent SMU Functionality Without CA ACF2 Equivalent The following functionality in SMU has no direct parallel in ACF2 security processing: Requirements for terminal signon Passwords for IMS resources The SMU signon requirements functionality can be addressed in the IMS system definition (IMS stage 1). Passwords for some IMS resources can be implemented with other kinds of changes, depending on the reason that passwords were assigned. The ACFDCSM5 utility can be used to report the statements in a SMU security definition that cannot be converted to an CA ACF2 equivalent. SMU Signon Requirements SMU used the )( SIGN and STERM statements to define the IMS static terminals that must sign on before they can enter transactions and commands. Beginning in IMS release 9.1, IMS provides the same functionality with the SIGNON= initialization parameter in the IMS DFSDCxxx parameter list, and with the OPTIONS=SIGNON NOSIGNON parameter on the TYPE or TERMINAL macro statements in the IMS system definition (IMS stage 1). If you specify STERM ALL in your SMU signon security definition, you should specify SIGNON=ALL in your IMS DFSDCxxx initialization parameter list, and remove the SMU signon definitions. If you list specific static terminals in your SMU signon security definition, you should add the OPTIONS=SIGNON parameter to the TYPE or TERMINAL macros for those terminals in your IMS system definition (IMS stage 1), and run your system definition process. Then you should specify SIGNON=SPECIFIC in your IMS DFSDCxxx initialization parameter list, and remove the SMU signon definitions. IMS provides a conversion program that will process your SMU definitions and your IMS system definitions, and provides a system definition updated with OPTION=SIGNON specifications for those terminals identified in the SMU definitions as required to signon. For more information about this conversion program, consult your IMS documentation. 318 IMS Support Guide

SMU Functionality Without CA ACF2 Equivalent Password for IMS Resources In the SMU security definitions, you can assign a password to several different kinds of IMS resources. Before that resource can be used, the corresponding password must be provided. No equivalent functionality was added to IMS release 9.1 to provide this functionality. In CA ACF2, only users have passwords; there is no mechanism by which a password can be assigned to a resource. So, this specific SMU functionality cannot be converted. Either some other mechanism must be implemented to provide equivalent functionality, or the functionality must be eliminated. For passwords assigned to IMS transactions and commands, there are some alternatives that can be implemented fairly easily. The two most common reasons for assigning passwords to IMS commands and transactions are: 1. In a terminal-based security implementation, this is a way of limiting a transaction or command to a subset of users who know the corresponding password. This provides a sort of privileged user identification. 2. In a z/os image with multiple IMS regions, assigning different passwords to the same command in different IMS regions provides a way of ensuring that a user knows which IMS they are communicating with when they enter an IMS command. In an CA ACF2 user-based security implementation for an IMS region, the first reason becomes redundant and the password can be eliminated. The user is identified when they sign on, and the security policy determines whether the user is allowed to enter the transaction or command. If you want to further ensure that the person entering the transaction or command is the same person who is signed on to the terminal, the VERIFY parameter can be specified on the resource rule line giving the user access to the transaction or command. This forces the user to enter their password again with the transaction or command when it is entered. This password is verified against the password of the user signed on to the terminal, to ensure that the same person is entering the transaction or command. In an CA ACF2 terminal-based security implementation, or in the multiple IMS region scenario described above, a special password can be assigned to a transaction or command if an installation is willing to write and implement an CA ACF2 IMS resource pre-validation exit. The CA ACF2 IMS pre-validation exit is described in the User Exits chapter. A pre-validation exit program can be written to define and enforce the password specification. The program should include a table of commands and transactions and their corresponding passwords. When the transaction or command is entered and the pre-validation exit is called, the program should ensure that a password was entered and that the password is correct for the transaction or command. The program should also set the indicator for CA ACF2 to not cache the successful access, or subsequent transactions or commands may be allowed without calling the pre-validation exit. Note that this implementation will not work in any scenario, such as VERIFY on the resource rule or IDLE timeout password reverification, where CA ACF2 will expect the user password to accompany the transaction or command. Appendix A: SMU Conversion 319

SMU Functionality Without CA ACF2 Equivalent ACFDCSM5 Utility The ACFDCSM5 utility can be used to generate a report of the SMU security definitions that cannot be converted to equivalent CA ACF2 security policy. The utility processes the SMU security definitions for the IMS region being converted. For each SMU definition that does not have a direct equivalent in CA ACF2 security, the utility generates output to a report. This report can be used to ensure that equivalent functionality is provided by either IMS system definitions or some other mechanism. The SMU security definitions that do not have an equivalent in CA ACF2 security policy definitions are: Requirements for terminal signon Passwords for IMS resources ACFDCSM5 Authorization Requirements ACFDCSM5 Utility JCL There are no authorization requirements for the ACFDCSM5 utility. The following is an example of the JCL required to execute the ACFDCSM5 conversion utility. // JOB //ACFDCSM5 EXEC PGM=ACFDCSM5 //SMU DD DSN=smu.input,DISP=SHR //REPORT DD SYSOUT=* // ACFDCSM5 DD Statements SMU Refers to the input data set containing the SMU statements for the IMS region being processed. This data set must be a sequential data set, with a record length of 80. REPORT This DD statement is required. Refers to the output data set created by the ACFDCSM5 utility, containing a report listing the SMU security definitions that cannot be converted to equivalent functionality in CA ACF2. If the DD statement specifies a data set rather than SYSOUT, the data set must be a sequential data set, with a record length of 137. This DD statement is required. 320 IMS Support Guide

SMU Functionality Without CA ACF2 Equivalent ACFDCSM5 Processing The ACFDCSM5 conversion utility processes the SMU information from the data set specified in the SMU DD statement in the execution JCL. When the utility identifies a )( SIGN control statement, it generates report lines for the )( SIGN statement and any STERM data statements that follow it. When the utility identifies a )( PASSWORD control statement, it generates report lines for the )( PASSWORD statement and any data statements that follow it. When the utility identifies a )( COMMAND, )( DATABASE, )( PROGRAM, )( PTERM, )( TERMINAL, or )( TRANSACT control statement, it saves the control statement. If the utility finds a PASSWORD data statement following the control statement, it generates report lines for the control statement and the PASSWORD data statement that follows it. Appendix A: SMU Conversion 321

Appendix B: Security in IMS DBCTL This section contains the following topics: Overview (see page 323) Design Concepts (see page 323) Resource Security in DBCTL (see page 325) CA ACF2 IMS Security for DBCTL Resources (see page 325) Implementing CA ACF2 IMS Security for DBCTL (see page 327) SAF Security for DBCTL Resources (see page 329) Overview This appendix describes how to use the CA ACF2 IMS interface to provide security in an IMS DBCTL environment. It is not intended to describe when and how to implement the IMS DBCTL environment. For information about implementing an IMS DBCTL environment, see the IBM IMS documentation set. The CA ACF2 IMS interface was designed to provide security for the IMS TM environments, which include the DB/DC and the DBCTL environments. IMS TM regions are transaction and terminal management environments. They support a network of terminals where users sign on and enter transactions and commands. They schedule and execute the transactions and return the results of the transactions back to the terminal user. The data maintained by the transactions can be in IMS DB databases, in an external database or file structure such as DB2, or both. Unlike the IMS TM environments, the IMS DBCTL environment has no terminal or transaction definition or support. The IMS DBCTL environment is used when data is in IMS DB databases and access to the databases is needed by batch IMS processes (BMPs) or from other transaction managers such as CICS (CCTL). The DBCTL environment lets these processes share access to the IMS DB data while ensuring data integrity. For a more information on the different IMS environments and when they can be used, consult the IBM IMS documentation. While the CA ACF2 IMS interface was designed for the IMS TM environments, it can also be used to provide security in the IMS DBCTL environment. Design Concepts This section describes the CA ACF2 IMS interface design concepts for the IMS DBCTL environment. Appendix B: Security in IMS DBCTL 323

Design Concepts CSL OM Environment The IMS Common Service Layer (CSL) is a set of IMS manager address spaces for one or more IMS control regions. One of these CSL address spaces is the Operations Manager (OM) address space. The Operations Manager is typically used in an IMSplex, which consists of several IMS control regions that work together as if they were a single IMS system. In this environment, the Operations Manager provides the following abilities: Route a single command to one or more of the IMSplex control regions Consolidate and deliver the responses from the regions. IMS Commands IMS provides a set of commands for the IMS DBCTL environment which can be entered at MCS and EMCS consoles or by application programs using the Automated Operator Interface (AOI). These commands provide IMS control and display functions. IMS DBCTL Region The IMS DBCTL region has no terminal or transaction definitions or support. The DBCTL region manages access to IMS DB databases from batch IMS processes (BMPs) or from other transaction managers such as CICS (CCTL). The DBCTL environment lets these processes share access to the IMS DB data while ensuring data integrity. MCS and EMCS Consoles Multiple Console Support (MCS) consoles devices are locally attached to a z/os system providing the ability for operators to enter z/os commands and interact with the z/os system. Extended Multiple Console Support (EMCS) consoles are typically programs that simulate an MCS console, allowing users to enter z/os commands and receive z/os messages. An example of an EMCS console is the TSO CONSOLE command processor. Program Specification Block In the IMS DBCTL environment, a program specification block (PSB) is an IMS control block that identifies the databases and database segments that an application program can access. Each batch process (BMP) or transaction manager that communicates with the IMS DBCTL region must specify the PSB that defines its database access. 324 IMS Support Guide

Resource Security in DBCTL System Authorization Facility (SAF) The System Authorization Facility (SAF) is a generalized security interface that directs all calls for security validation to the external security product in use. When a system resource or product requests the services of an external security product, SAF directs the call to CA ACF2, which handles the security event. Resource Security in DBCTL The IMS TM environment has a large number of resources that can be protected. Only a small subset of these resources pertains to the IMS DBCTL environment. The IMS resources that can be secured in the IMS DBCTL environment are PSBs and IMS commands. Program Specification Block Each batch process (BMP) or transaction manager that communicates with the IMS DBCTL region must specify the PSB that defines its database access. As part of RAS security, the IMS DBCTL region validates the userid of the dependent region (BMP or CCTL) can use the PSB specified in the dependent region parameters. If the dependent region is not allowed access to the PSB specified, the dependent region is not allowed to connect to the IMS DBCTL region. Commands A subset of the available IMS commands is supported in the IMS DBCTL environment. These commands are usually entered at an MCS or EMCS console using a command recognition character (CRC) that controls which IMS region should process the command. In the IMS DBCTL environment, commands can also be entered from application programs using the AOI communications calls, and from the IMS SCL OM environment. The IMS DBCTL region validates whether the userid associated with the command is allowed to execute the command. CA ACF2 IMS Security for DBCTL Resources The CA ACF2 IMS interface can be used to provide security for some of the resources in an IMS DBCTL environment. Appendix B: Security in IMS DBCTL 325

CA ACF2 IMS Security for DBCTL Resources Program Specification Block In the IMS DBCTL environment, you can control the use of PSBs in one of two ways: PSB security for BMPs RAS PSB security For more information, see the PSB Security and AGN and RAS Resource Security chapters to determine which of these methods meet your security requirements. Implement the security by specifying either the $PSB or the $RASPSB IMS RESOURCE record as described in those chapters. Commands from MCS/EMCS Consoles The CA ACF2 IMS interface does not provide security for commands from MCS and EMCS consoles. To implement security for these commands you must use IMS SAF security based on the setting of the IMS CMDMCS execution parameter. If you specify CMDMCS=R, the IMS DBCTL region issues a SAF call to validate whether the userid associated with the MCS or EMCS console is allowed to issue the IMS command. For more information on DBCTL and the CMDMCS parameter, see the IBM IMS documentation. Commands from Application Programs In the IMS DBCTL environment, you can control the use of AOI commands issued by application programs using the $TRANCMD IMS RESOURCE record. For more information about AOI command security and the $TRANCMD RESOURCE record, see the Command Security chapter. Commands from the SCL OM Environment The CA ACF2 IMS interface does not provide security for commands from the SCL OM environment. To implement security for these commands you must use IMS SAF security based on the setting of the CMDSEC execution parameter of the OM region. If you specify CMDSEC=R, the OM region issues a SAF call to validate whether the userid communicating with the OM environment is allowed to issue the IMS command. For more information on the IMS OM environment and the CMDSEC parameter, see the IBM IMS documentation. 326 IMS Support Guide

Implementing CA ACF2 IMS Security for DBCTL Implementing CA ACF2 IMS Security for DBCTL IMS Control Records for DBCTL The IMS control records that are used in the IMS DBCTL environment are: OPTS EXITS STORAGE WTO RESOURCE for the $PSB resource RESOURCE for the $RASPSB resource RESOURCE for the $TRANCMD resource See the appropriate chapters in this guide for information on choosing the values for and defining these IMS control records for the IMS DBCTL region. The following IMS control records are not used in the IMS DBCTL environment and should not be specified for the IMS DBCTL region: SIGNON NETWORK SYSPLEX RESOURCE for the $PRITRAN resource RESOURCE for the $SECTRAN resource RESOURCE for the $COMMAND resource RESOURCE for the $TRANCM1 resource RESOURCE for the $RASTRAN resource RESOURCE for the $RASTERM resource RESOURCE for the $LOCKTRN resource RESOURCE for the $LOCKPGM resource RESOURCE for the $LOCKDB resource RESOURCE for the $LOCKTRM resource RESOURCE for the $TPIPE resource If these IMS control records are specified for an IMS DBCTL region, they will be ignored. Appendix B: Security in IMS DBCTL 327

Implementing CA ACF2 IMS Security for DBCTL Implementing CA ACF2 IMS Security for DBCTL The process of installing and implementing CA ACF2 IMS security for the IMS TM environment is described in the Installation Procedure chapter. While the process of implementing CA ACF2 IMS security in an IMS DBCTL environment is similar, many of the steps in the IMS TM implementation are unnecessary in an IMS DBCTL implementation. This section lists the steps required for the IMS DBCTL implementation. Where appropriate, it refers to the detailed information in the Installation Procedure chapter. Follow these steps: 1. Make the IMS Interface APF-Authorized Add the IMS interface target load library CAI.ACF2IMS.CAX2IMS to the z/os APF list in SYS1.PARMLIB(IEAAPFxx) or SYS1.PARMLIB(PROGxx). 2. Create or Update the IMS Interface APPLDEF Records Update and run CAI.ACF2IMS.CAX1JCL2(IMSAPLDF) to create or update the definitions of the IMS interface infostorage records. Activate the definitions. For more information, see the corresponding task description in the Installation Procedure chapter. 3. Modify the IMS OM Command Table If you are running an IMSplex environment and have a requirement to enter the /ACF command through OM and route it to multiple IMS regions in the IMSplex, apply a USERMOD to the IMS software to add the /ACF command to the IMS OM registered commands. For more information, see the corresponding task description in the Installation Procedure chapter. Note: Skip this step if you are not running an IMSPLEX environment or you do not have the requirement for the /ACF command through OM. 4. Create/Modify IMS Interface Options, Logonids, Rules Before proceeding with the next step, be sure that your security administrator creates or modifies IMS interface system options, logonids, and resource rules as appropriate after reviewing all of your requirements. 5. Initialize the IMS Interface Add the CA ACF2 IMS interface load library to the IMS DBCTL procedure STEPLIB DD statement. //STEPLIB DD DSN=CAI.ACF2IMS.CAX1IMS // DD DSN=IMS.SDFSRESL Important! The CA ACF2 IMS interface library must be the first in the IMS DBCTL procedure STEPLIB DD concatenation. 328 IMS Support Guide

SAF Security for DBCTL Resources The /ACF Command in DBCTL When the CA ACF2 IMS interface is implemented in the IMS DBCTL region, the /ACF command is available to display the status of the CA ACF2 IMS security and to reload the directories for the IMS resources that are protected. For more information on the /ACF command, see the ACF Command chapter. SAF Security for DBCTL Resources If you choose to not use the CA ACF2 IMS security for the IMS DBCTL environment, IMS provides a SAF security interface that can be used to provide security for the IMS resources that can be protected in this environment. This section is not intended to describe the DBCTL SAF security process in detail. For detailed information on using SAF security in the DBCTL environment, see the IBM IMS documentation. Program Specific Block The IMS DBCTL environment uses RAS security to control the use of PSBs by IMS dependent regions. Implementation of RAS security in the DBCTL environment is controlled by the ISIS execution parameter. If you specify ISIS=R, DBCTL issues a SAF call to validate whether the IMS dependent region is allowed to use the PSB. For more information on DBCTL and the ISIS parameter, see the IBM IMS documentation. Commands from MCS/EMCS Consoles The IMS DBCTL environment controls the use of commands from MCS and EMCS consoles based on the setting of the CMDMCS execution parameter. If you specify CMDMCS=R, DBCTL issues a SAF call to validate whether the userid associated with the MCS or EMCS console is allowed to issue the IMS command. For more information on DBCTL and the CMDMCS parameter, see the IBM IMS documentation. Commands from Application Programs The IMS DBCTL environment controls the use of AOI commands issued by application programs based on the setting of the AOIS execution parameter. If you specify AOIS=R, DBCTL issues a SAF call to validate whether the userid associated with the application program is allowed to issue the IMS command. For more information on DBCTL and the AOIS parameter, see the IBM IMS documentation. Appendix B: Security in IMS DBCTL 329

SAF Security for DBCTL Resources Commands from the SCL OM Environment In the IMS DBCTL environment, security for commands issued from the SCL OM environment to the DBCTL region is controlled based on the setting of the CMDSEC execution parameter of the OM region. If you specify CMDSEC=R, the OM region issues a SAF call to validate whether the userid communicating with the OM environment is allowed to issue the IMS command. For more information on the IMS OM environment and the CMDSEC parameter, see the IBM IMS documentation. 330 IMS Support Guide