Customization - publib.boulder.ibm.compublib.boulder.ibm.com/tividd/td/job/emsc1mst/en... ·...

NetView Access Services (MVS/ESA) IBM

CustomizationVersion 2 Release 1

SH19-4502-00

NetView Access Services (MVS/ESA) IBM

CustomizationVersion 2 Release 1

SH19-4502-00

Note!

Before using this information and the product it supports, be sure to read the general information under “Notices” on page xi.

First Edition, December 1997

This is a major revision of, and obsoletes, SH12-5812-01. Technical changes or additions to the text and illustrations are indicatedby a vertical line to the left of the change.

This edition applies to Release 1 Modification Level 1 of NetView Access Services Version 2 (MVS/ESA) (Program Number5695-036) and to all subsequent releases and modifications until otherwise indicated in new editions or technical newsletters.

Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at theaddress below.

IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication, or you may addressyour comments to the following address:

NVAS Information DevelopmentRome Tivoli LaboratoryIBM Italia S.p.A.Via Sciangai, 53

00144 Rome Italy

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believesappropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1987, 1997. All rights reserved.Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject torestrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiProgramming Interface Information . . . . . . . . . . . . . . . . . . . . . . . . . . xiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

| What Is New in NetView Access Services Version 2.1.1 . . . . . . . . . . . xv| External Application Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . xv| Direct Logon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv| Compact Application Selection Panel . . . . . . . . . . . . . . . . . . . . . . . . xv| Logmode Override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv| REXX API Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Part 1. Concepts and Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. NetView Access Services Concepts . . . . . . . . . . . . . . . . . 3NetView Access Services Modes of Operation . . . . . . . . . . . . . . . . . . . . 3The NetView Access Services Pseudo Terminal Concept . . . . . . . . . . . . . 4

Shared Pseudo Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Unique and Individual Pseudo Terminals . . . . . . . . . . . . . . . . . . . . . 5Pseudo Terminal Prefix and Maximum Sessions . . . . . . . . . . . . . . . . . 6

Defining Different Terminal Models . . . . . . . . . . . . . . . . . . . . . . . . . . 7Matching a Real Terminal Name with a Pseudo Terminal Name . . . . . . . . . 8Pass Mode Application Session Considerations . . . . . . . . . . . . . . . . . . . 9The NetView Access Services Virtual Terminal Concept . . . . . . . . . . . . . 10

What the Virtual Terminal Concept Supports . . . . . . . . . . . . . . . . . . 11Functions that Leave Virtual Terminal Mode . . . . . . . . . . . . . . . . . . . 12Data Stream Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Invocation and Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 2. VTAM Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 15How NetView Access Services is Defined in VTAM . . . . . . . . . . . . . . . . 15NetView Access Services Buffer Usage for VTAM Macros . . . . . . . . . . . . 16Logmode Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Logmode Entry Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Logmode Considerations for Printers . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 3. VSAM Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 21VSAM Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

VSAM Profile Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21VSAM Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Reorganizing VSAM Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Sharing VSAM Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Refreshing VSAM Profiles with the Latest Updates . . . . . . . . . . . . . . . . 26

Chapter 4. Security and Accounting Considerations . . . . . . . . . . . . . 27Network and Application Access Control . . . . . . . . . . . . . . . . . . . . . . 27

Application and Terminal Idle Time . . . . . . . . . . . . . . . . . . . . . . . . 27Installation-Wide Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Copyright IBM Corp. 1987, 1997 iii

User Data Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Logon Panel Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Terminal Based Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Synchronizing Passwords across Several Host Systems . . . . . . . . . . . 30Password Expiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31RACF PassTicket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Accounting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31NetView Access Services Installation-Wide Exits . . . . . . . . . . . . . . . . 31NetView Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Application Access Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Considerations for 7171 Attached Dial-In Terminals . . . . . . . . . . . . . . . . 33Considerations for Using the Dummy Logon Authorization Exit (EMSELGNX) . 34Session Transfer Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 5. Network Considerations . . . . . . . . . . . . . . . . . . . . . . . 35Network Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Session Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Response Time Monitor Considerations . . . . . . . . . . . . . . . . . . . . . . . 37NetView Performance Monitor Considerations . . . . . . . . . . . . . . . . . . . 38Network Capacity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39User Response Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Gaining Access to CICS/VS Using NetView Access Services . . . . . . . . . . 40Gaining Access to IMS/VS through NetView Access Services . . . . . . . . . . 41

Chapter 6. General Considerations . . . . . . . . . . . . . . . . . . . . . . . . 43Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Suppressing NetView Access Services Messages . . . . . . . . . . . . . . . . . 44Total Number of Users and Application Sessions . . . . . . . . . . . . . . . . . 44Using the TERMQ Operator Command for Load Balancing . . . . . . . . . . . 45Access Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Graphic Display Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Data Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Outbound-Only Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Outbound and Inbound Data Compression . . . . . . . . . . . . . . . . . . . 46

Using BIND User Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Automatic Logon Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Part 2. Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Chapter 7. Migration Considerations . . . . . . . . . . . . . . . . . . . . . . . 51Logon Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51VSAM Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Installation-Wide Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51NetView Access Services Supplied Command Lists . . . . . . . . . . . . . . . . 52Primary and Auxiliary Storage Requirements . . . . . . . . . . . . . . . . . . . . 52Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Panel Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 8. Preparing to Customize NetView Access Services . . . . . . . 55Primary Virtual Storage Used by NetView Access Services . . . . . . . . . . . 55

Static Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Dynamic Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

iv NetView Access Services Version 2 Customization

Storage Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55CSA and SQA Storage Requirements . . . . . . . . . . . . . . . . . . . . . . 56Calculating NetView Access Services Storage . . . . . . . . . . . . . . . . . 56Example of Calculating the Primary Storage Required . . . . . . . . . . . . . 56

Auxiliary Storage Required for NetView Access Services . . . . . . . . . . . . . 57

Chapter 9. Customizing NetView Access Services after Base Installation 61Step 1: Generating the Customization Jobs . . . . . . . . . . . . . . . . . . . . 61Step 2: Running the Customization . . . . . . . . . . . . . . . . . . . . . . . . . 65Step 3: Verifying the Installation of the Batch Load Program . . . . . . . . . . . 75Step 4: Modifying EUSZAP Flag-Bit Area for Sharing VSAM Profiles (Optional) 75Step 5: Switching to Confidential Mode (Optional) . . . . . . . . . . . . . . . . . 76

Chapter 10. Customizing NetView Access Services for Your Environment 77Enabling the Generic Alert Interface to NetView . . . . . . . . . . . . . . . . . . 77Enabling the NetView Synergy Interface to the NetView Performance Monitor 78Enabling for Secondary Authentication . . . . . . . . . . . . . . . . . . . . . . . 81Customizing for Model Terminal Support . . . . . . . . . . . . . . . . . . . . . . 82Customizing NetView Access Services for Public Groups . . . . . . . . . . . . 82Preparing for NetView Access Services Startup . . . . . . . . . . . . . . . . . . 84

Chapter 11. Modifying NetView Access Services Panels, Messages, andCommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Locating the Source Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Modifying the Source Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Modifying NetView Access Services Panels . . . . . . . . . . . . . . . . . . . . 91Migrating NetView Access Services Panels . . . . . . . . . . . . . . . . . . . . . 95Defining a NetView Access Services Help Panel . . . . . . . . . . . . . . . . . 99Guidelines for Rewriting Message Text . . . . . . . . . . . . . . . . . . . . . . 103

Message Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Generating a Message Table . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Specifying Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Example of a Message Definition . . . . . . . . . . . . . . . . . . . . . . . . 106Message Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Multilingual Support Considerations . . . . . . . . . . . . . . . . . . . . . . . . 107Modifying NetView Access Services Commands . . . . . . . . . . . . . . . . . 108

| Chapter 12. Customizing NetView Access Services Sample Exits to| Interface with RACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Concept of the NetView Access Services Interface to RACF . . . . . . . . . . 111| External Application Authorization . . . . . . . . . . . . . . . . . . . . . . . . . 115| How Does External Application Authorization Change the Procedure . . . 116

Using RACF to Maintain External Groups . . . . . . . . . . . . . . . . . . . . . 117Comparison between Normal and External Groups . . . . . . . . . . . . . 118Where the Application Access Data Is Stored in RACF . . . . . . . . . . . 119How Application Access Data Is Stored in RACF . . . . . . . . . . . . . . . 119Deleting an Application from RACF . . . . . . . . . . . . . . . . . . . . . . . 122Installation Requirements in RACF . . . . . . . . . . . . . . . . . . . . . . . 123RACF Profiles Processed by NetView Access Services . . . . . . . . . . . 123Synchronization of RACF and NetView Access Services Databases . . . 126

Chapter 13. Customizing NetView Access Services Installation-WideExits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Overview of Installation-Wide Exit Routines . . . . . . . . . . . . . . . . . . . 129

Contents v

Coding Requirements for an Installation-Wide Exit Routine . . . . . . . . . . 130Installing an Installation-Wide Exit Routine . . . . . . . . . . . . . . . . . . . . 132EMSEADEX, Administration Exit . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

EMSEAPAN, Automatic Logon and Logoff Exit . . . . . . . . . . . . . . . . . 141Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Sample Automatic Logon and Logoff Exit . . . . . . . . . . . . . . . . . . . 142

EMSEATTE, Inactivity Timeout Exit . . . . . . . . . . . . . . . . . . . . . . . . 143Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

EMSEBXML, Broadcast Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

EMSEDTEX, Date and Time Exit . . . . . . . . . . . . . . . . . . . . . . . . . 147Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Sample Date and Time Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

EMSEDVEX, Data Viewing Exit . . . . . . . . . . . . . . . . . . . . . . . . . . 149Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Sample Data Viewing Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

EMSELGFX, Logoff Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Sample Logoff Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

EMSELGNX, Logon Authorization Exit . . . . . . . . . . . . . . . . . . . . . . 154| Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157EMSELNEX, Language Name Exit . . . . . . . . . . . . . . . . . . . . . . . . . 161

Sample Language Name Exit . . . . . . . . . . . . . . . . . . . . . . . . . . 161Installing a New Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

EMSELVEX, Language Verification Exit . . . . . . . . . . . . . . . . . . . . . . 164Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Sample Language Verification Exit . . . . . . . . . . . . . . . . . . . . . . . 165

EMSENPME, Accounting Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

EMSEPRPS, Printer Presetting Exit . . . . . . . . . . . . . . . . . . . . . . . . 167Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Sample Exit EMSEPRPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

EMSESEEX, Session Establishment Exit . . . . . . . . . . . . . . . . . . . . . 171Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Sample Session Establishment Exit . . . . . . . . . . . . . . . . . . . . . . 176Using This Exit for Session Load Balancing . . . . . . . . . . . . . . . . . . 176

EMSESHRX, Shared Session Exit . . . . . . . . . . . . . . . . . . . . . . . . . 177Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

EMSESREX, Session Reselection Exit . . . . . . . . . . . . . . . . . . . . . . 178Parameter List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

vi NetView Access Services Version 2 Customization

Part 3. NetView Access Services Application Service Routines . . . . . . . . . . . 181

Chapter 14. Writing New Application Service Routines . . . . . . . . . . 183Major Functions of an Application Service Routine . . . . . . . . . . . . . . . 183

Establishing Addressability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Establishing and Terminating Sessions with Logical Units . . . . . . . . . . 183Communicating with Logical Units . . . . . . . . . . . . . . . . . . . . . . . 184

Coding Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185NetView Access Services Macros . . . . . . . . . . . . . . . . . . . . . . . . . 185

Macro Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Operand Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

EMSSTRT, Initiate the Macro Interface . . . . . . . . . . . . . . . . . . . . . . 187EMSALLOC, Request a Session . . . . . . . . . . . . . . . . . . . . . . . . . . 187EMSDEALL, Deallocate a Session . . . . . . . . . . . . . . . . . . . . . . . . . 192EMSFBUF, Free a Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193EMSGATTR, Return Information about a Session . . . . . . . . . . . . . . . . 194EMSGBUF, Get a Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197EMSNPM, NetView Performance Monitor Interface . . . . . . . . . . . . . . . 198EMSPRETR, Prepare to Receive . . . . . . . . . . . . . . . . . . . . . . . . . 199EMSRECV, Receive Information . . . . . . . . . . . . . . . . . . . . . . . . . . 200EMSREQTS, Request to Send . . . . . . . . . . . . . . . . . . . . . . . . . . . 205EMSSENDD, Send Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206EMSSENDE, Send Error Response . . . . . . . . . . . . . . . . . . . . . . . . 208Using NetView Access Services Buffers . . . . . . . . . . . . . . . . . . . . . 209

Part 4. NetView Access Services REXX Application Programming Interface . . 213

Chapter 15. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Concept of Virtual Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Installing the NVASAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Defining the Maximum Number of REXX Environments Required . . . . . . . 217Invoking the NVASAPI Functions or Subroutines . . . . . . . . . . . . . . . . 217Invoking REXX Execs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Terminating REXX Execs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Debugging of REXX Execs for NetView Access Services . . . . . . . . . . . 221Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221NVASAPI Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223270 Attributes and Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Programming Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Chapter 16. NetView Access Services REXX Application ProgrammingInterface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Prerequisite Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Returned Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

NVASAPI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228CONVERT_POS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Contents vii

COPY_FIELD_TO_STR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231COPY_PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233COPY_PS_TO_STR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235COPY_STR_TO_PS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237DIAGNOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239DISABLE_AUTOLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243DISCONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244DISPLAY_PS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

| DISPMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247FIND_FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250QUERY_CURSOR_POS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252QUERY_FIELD_ATTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

| QUERY_LOGON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254QUERY_ORIGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254QUERY_PS_UPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257QUERY_READ_STATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258QUERY_SESSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

| QUERY_TERMINALS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260QUERY_VARIABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261QUERY_VT_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262SEARCH_FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263SEARCH_PS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265SENDKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266SEND_3270DS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269SET_CURSOR_POS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270SET_SEND_MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Chapter 17. REXX Execs for Automatic Logon to NetView AccessServices and Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Description of the REXX Execs . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Part 5. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Appendix A. Reading the Syntax Diagrams . . . . . . . . . . . . . . . . . 303

Appendix B. NetView Access Services Administration Record Formats 305NetView Access Services Profile Concept . . . . . . . . . . . . . . . . . . . . 305

Profile Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Profile Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Profile Record Field Relationship . . . . . . . . . . . . . . . . . . . . . . . . 307Procedure for Updating Profiles . . . . . . . . . . . . . . . . . . . . . . . . . 307Profile Update Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Content of VSAM Profile Data Areas . . . . . . . . . . . . . . . . . . . . . . . 309User Profile Table (EMSSRTU) . . . . . . . . . . . . . . . . . . . . . . . . . 309Application Routing Table for Groups (EMSSRTG) . . . . . . . . . . . . . . 315Group Profile Table (GPRF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Application Routing Table (EMSSRTS) . . . . . . . . . . . . . . . . . . . . . 321Group Access List Table (EMSGAL) . . . . . . . . . . . . . . . . . . . . . . 324

Appendix C. Customization Worksheets . . . . . . . . . . . . . . . . . . . 325

viii NetView Access Services Version 2 Customization

Part 6. Glossary, Bibliography, and Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337NetView Access Services Version 2 Publications . . . . . . . . . . . . . . . . 337Network Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337VTAM Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337VSAM Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337OS/VS Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337RACF Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337SNA Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337CICS Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337TSO Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Additional Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Contents ix

x NetView Access Services Version 2 Customization

Notices

References in this publication to IBM products, programs, or services do not implythat IBM intends to make these available in all countries in which IBM operates.Any reference to an IBM product, program, or service is not intended to state orimply that only IBM's product, program, or service may be used. Any functionallyequivalent product, program, or service that does not infringe any of IBM's intellec-tual property rights may be used instead of the IBM product, program, or service.Evaluation and verification of operation in conjunction with other products, exceptthose expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter inthis document. The furnishing of this document does not give you any license tothese patents. You can send license inquiries, in writing, to the IBM Director ofLicensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594, USA.

Programming Interface InformationThis book is intended to assist system programmers to customize NetView AccessServices.

This book primarily documents Product-sensitive Programming Interface and Asso-ciated Guidance Information.

Product-sensitive programming interfaces allow the customer installation to performsuch tasks as diagnosing, modifying, monitoring, repairing, or tuning of NetViewAccess Services Version 2. Use of such interfaces creates dependencies on thedetailed design or implementation of the IBM software product. Product-sensitiveprogramming interfaces should be used only for these specialized purposes.Because of their dependencies on detailed design and implementation, it is to beexpected that programs written to such interfaces may need to be changed in orderto run with new product releases or versions, or as a result of service.

However, this book also documents General-use Programming Interface and Asso-ciated Guidance Information provided by NetView Access Services Version 2.

General-use programming interfaces allow the customer to write programs thatobtain the services of NetView Access Services Version 2.

General-use Programming Interface and Associated Guidance Information is identi-fied where it occurs by an introductory statement to a chapter or section.

TrademarksThe following terms, denoted by an asterisk (*) in this publication, are trademarks ofIBM Corporation in the United States or other countries or both:

ACF/VTAM CICS DB2IBM IMS MVS/ESAMVS/XA NetView OfficeVision/MVSQMF RACF System/360System/370 VM/ESA VTAM

Copyright IBM Corp. 1987, 1997 xi

Tivoli is a trademark of Tivoli Systems, Inc.

Other company, product, and service names which may be denoted by a doubleasterisk (**), may be trademarks or service marks of others.

xii NetView Access Services Version 2 Customization

About This Book

The IBM* licensed program NetView Access Services Version 2 running under theMVS/ESA* operating system is a member of the NetView* family of products andprovides a single access control system for users of 3270-type terminal devices ina Systems Network Architecture (SNA) network, and supports the management of anumber of applications from a single terminal.

This book provides information on how to customize NetView Access ServicesVersion 2 for your own location. You should be familiar with the MVS/ESA oper-ating system, the VTAM* communication programs, VSAM, and the applicationsthat will be used through NetView Access Services Version 2.

Unless otherwise stated, NetView Access Services in this book refers to NetViewAccess Services Version 2.

Copyright IBM Corp. 1987, 1997 xiii

xiv NetView Access Services Version 2 Customization

| What Is New in NetView Access Services Version 2.1.1

| Four new features have been included in NetView Access Services Version 2| Release 1 Modification Level 1. These are:

| � External Application Authorization

| � Direct Logon

| � Compact Application Selection panel

| � Logmode override.

| The set of functions available with the REXX API feature has been extended.

| External Application Authorization| This feature enables NetView Access Services to use the application access infor-| mation defined in the RACF database when building the Application Selection| Panel for each user. The NetView Access Services administrator, therefore, need| no longer create security definitions for applications in NetView Access Services as| all this information will be taken from the RACF definition for the application.

| This enhancement improves the synergy between NetView Access Services and| RACF, reduces the NetView Access Services administration time, and hence| improves the usability of the NetView Access Services product.

| Direct Logon| This feature introduces the ability to define terminals that are to be logged on to| NetView Access Services without the logon panel being displayed. This feature| allows the NetView Access Services Application Selection panel to be displayed| directly when terminals are powered on.

| Compact Application Selection Panel| This is an additional format in which to display the NetView Access Services Appli-| cation Selection panel. With this new format you can display up to 42 applications| on a single screen. There is lo longer a maximum limit of 99 applications. The use| of this new format can be configured for each group.

| Logmode Override| This feature allows the NetView Access Services administrator to explicitly specify a| logmode to be used by NetView Access Services when establishing a session with| an application.

Copyright IBM Corp. 1987, 1997 xv

| REXX API Extensions| Three new REXX API calls have been added to allow users to accomplish the fol-| lowing tasks from REXX execs:

| � Get a list of all the terminals attached to NetView Access Services, regardless| of which screen they are currently displaying.

| � Get a list of all the terminals that are currently displaying the NetView Access| Services Logon Panel.

| � Send a message to all the terminals attached to NetView Access Services,| regardless of which screen they are currently displaying.

xvi NetView Access Services Version 2 Customization

Part 1. Concepts and Considerations

This part provides information on the concepts of NetView Access Services andconsiderations required for customizing NetView Access Services for your installa-tion.

Copyright IBM Corp. 1987, 1997 1

2 NetView Access Services Version 2 Customization

Chapter 1. NetView Access Services Concepts

NetView Access Services is a VTAM application program that enables users in anSNA network to gain simultaneous access to several applications. NetView AccessServices uses VTAM to communicate with the applications.

This chapter and the following chapters in this part provide general information thatmay be useful when customizing NetView Access Services.

NetView Access Services Modes of OperationNetView Access Services has two modes in which users can gain access to appli-cations, “relay mode” and “pass mode”. Figure 1 shows the relay or pass modeconfigurations.

Figure 1. Relay or Pass Mode

Relay ModeNetView Access Services simulates a 3270 LU Type-2 device for each relay-modesession with an application. This simulated device is referred to as a “pseudoterminal”, and it acts as the Secondary Logical Unit (SLU) in the session betweenNetView Access Services and the application. To perform this simulation process,NetView Access Services uses a pool of pseudo terminals that are defined toVTAM as network resources in APPL definition statements. When a user starts arelay-mode session, NetView Access Services allocates a pseudo terminal nameand establishes a session with the application on the user’s behalf. The pseudoterminal name allocated for the session is defined by the administrator. All dataflow between the physical terminal and the application then passes throughNetView Access Services.


Pass ModeIn pass mode, the primary session end point (Primary Logic Unit (PLU)) function ispassed from NetView Access Services to the selected application. A direct sessionis established between the terminal and the application. NetView Access Servicesuses a VTAM facility (CLSDST PASS) to terminate the current session and estab-lish a new session between the terminal and the application selected by the user.After completion of the logon process only one session exists between the terminalSLU and the application PLU.

The NetView Access Services Pseudo Terminal ConceptThe following describes the pseudo terminal concept of NetView Access Services.This concept is only valid for relay mode.

One of the major user productivity functions of NetView Access Services is toprovide access to several applications concurrently from a single terminal. NetViewAccess Services interacts with an application as if it were a user’s terminal using apseudo terminal. That is, NetView Access Services establishes a session using apseudo terminal name with each active application the user selects.

The pseudo terminal name is an ACB that is defined to VTAM via an APPL defi-nition statement. NetView Access Services must be informed if a particular applica-tion can support parallel sessions using a single ACB. If the application cannotsupport this capability, NetView Access Services uses a Unique or Individual ACBfor each relay-mode session established to that application. Therefore the specificoption to select depends on the characteristics of the application.

Shared Pseudo TerminalsIf an application supports parallel sessions (for example, TSO, as shown inFigure 2), only one ACB is required for all sessions between NetView Access Ser-vices and the application, and an ACB type Shared can be defined.

Figure 2. Using a Shared ACB to Gain Access to TSO


Unique and Individual Pseudo TerminalsIf an application does not support parallel sessions (for example, CICS*), an ACB isrequired for each session between NetView Access Services and the application.In this case, either of the following can be done:

� An ACB type of Unique can be defined. Unique ACBs are shown in Figure 3.This enables the ACB to be used by a user for one application. The number ofACBs required depends on the maximum number of concurrent sessionsbetween NetView Access Services and the application.

Figure 3. Using Unique ACBs

� An ACB type of Individual can be defined. This enables the ACB to be used bythe same user for several applications. Individual ACBs are shown in Figure 4.

Chapter 1. NetView Access Services Concepts 5

Figure 4. Using Individual ACBs

Each of these ACBs represent an SLU (pseudo terminal) within the SNA network.NetView Access Services must establish a pseudo terminal ACB as the SLU in thesession between the relay mode application and NetView Access Services. TheACB can be defined as either Shared, Unique, or Individual, and its properties mustbe defined to VTAM as described in “APPL Statements for Each of the PseudoTerminal SLUs” on page 73.

Pseudo Terminal Prefix and Maximum SessionsWhen an application is defined to the system, values for the pseudo terminal prefixand the maximum sessions must also be specified.

If a Shared ACB type is defined, then only the pseudo terminal prefix is used as theterminal name for all relay-mode sessions to that application. The number of ses-sions that can be established using this single ACB is controlled by the maximumsessions value.

If a Unique or Individual ACB type is specified, then these two parameters are usedto derive the pseudo terminal names.

The name is constructed by taking the pseudo terminal prefix and suffixing anumber to it, making 8 characters in all. All such 8-character names must bedefined to VTAM. For example, for prefix EMSYAT, VTAM needs definitions forEMSYAT01 to EMSYAT99. The maximum sessions value can be used to set theactual upper limit required. For example, if maximum sessions was set to 20, thenEMSYAT20 is the highest-numbered SLU required.

Note: When an application is assigned to a user, a different pseudo terminalname can be specified for that user. If a pseudo terminal name is specificallyassigned to a user, NetView Access Services always uses that name to establishthe relay-mode session for that application. Otherwise, the pseudo terminal prefixinitially defined is used.


The maximum sessions value can be increased or decreased while NetViewAccess Services is running.

Defining Different Terminal ModelsSome applications require characteristics of the user terminal to be defined. Thismeans that the pseudo terminal must also be defined to the application. IMS, forexample, requires a definition of each terminal and its type.

To provide support for different terminal models using pseudo terminals, you mustdo the following for each application in question:

1. Define a different system-internal name and pseudo terminal prefix for eachmodel on the Assign an Application for the System panel.

2. Assign the system-internal name for the most frequently-used model to thegroup on the Assign an Application to a Group panel.

The session establishment exit EMSESEEX then determines the model type by useof the logmode parameter. For further details see the description of this exit inChapter 13, “Customizing NetView Access Services Installation-Wide Exits” onpage 129.

Figure 5 on page 8 shows an example of how the support for different terminalmodels can be implemented. The names in this sample refer to the names used inthe sample coding (in comments) of the EMSESEEX exit routine. The following isassumed:

� IMSM2 is used as the system-internal name when IMS is defined to theNetView Access Services system. This system-internal name is specified whenthe application IMS is defined to a group. NVPIM2 is used as the pseudo ter-minal prefix for the default Model 2 pseudo terminal pool.

� IMSM3 is used as the system-internal name for the Model 3 terminal typesystem definition. NVPIM3 is used as the pseudo terminal prefix for theModel 3 pseudo terminal pool.

� IMSM4 is used as the system-internal name for the Model 4 terminal typesystem definition. NVPIM4 is used as the pseudo terminal prefix for theModel 4 pseudo terminal pool.

The sample assumes that Model 2 pseudo terminals are the default terminals con-nected to the IMS system. The pseudo terminal names created by NetView AccessServices based on the pseudo terminal prefix for the system-internal name must bedefined to IMS with the appropriate model types information. The names createdby NetView Access Services in this example are:

NVPIM201, NVPIM202 .... NVPIM299 for Model 2 type pseudo terminalsNVPIM301, NVPIM302 .... NVPIM399 for Model 3 type pseudo terminalsNVPIM401, NVPIM402 .... NVPIM499 for Model 4 type pseudo terminals.


Figure 5. Support for Different Terminal Models

Matching a Real Terminal Name with a Pseudo Terminal NameNetView Access Services can provide an SLU name based on the real terminalname. This could be used for the terminal based security, terminal associationCICS TCT, or for the IMSGEN. The system administrator can define the SLU (inthe pseudo terminal prefix field) containing asterisks on the Define an Applicationfor the System panel. This is referred to as a generic pseudo terminal name.

Information on how to enter the generic pseudo terminal name and how theresulting pseudo terminal name can be built can be found in NetView Access Ser-vices Version 2 Administration.

Notes:

1. The resulting pseudo terminal names must be defined as a VTAM APPL state-ment and in the target application, for example, in CICS TCT.

2. The Session Initialization exit EMSESEEX enables you to overwrite the SLUnames defined on the administration panels.


Pass Mode Application Session ConsiderationsConsider the following two items if you plan to use pass mode application sessionswith NetView Access Services.

Forwarding Terminal Sessions in Pass ModeNetView Access Services issues a SIMLOGON to regain control of the terminal LUif SIMLOGON=YES has been specified in the input parameters. VTAM queues theSIMLOGON request in a first in, first out (FIFO) queue.

If, for example, NetView Access Services passes the terminal LU to an applicationthat passes the terminal LU to another application (that is, to a third party) and alsoissues a SIMLOGON, VTAM queues this request as the next SIMLOGON in thequeue. When the terminal LU is logged off from the third party application, VTAMreturns the terminal to the application that issued the first SIMLOGON. If the ter-minal LU is logged off from the first application, VTAM gives the terminal to theapplication that issued the second SIMLOGON request.

If an LU is forwarded in this way through the network, it is not returned to the appli-cations in the same sequence as it was passed forward. Therefore, when you planto use the pass mode facility with SIMLOGON=YES, take note of the sequence inwhich the terminal is forwarded and returned in your environment. For further infor-mation, refer to Figure 6.

If SIMLOGON=YES has been specified in the input parameters, NetView AccessServices issues a SIMLOGON to regain control of the terminal LU that is passed toan application (in pass mode). This SIMLOGON request is queued by VTAM.When the terminal LU is returned to NetView Access Services, the NetView AccessServices Logon panel is displayed if RCONNECT=NO is specified in the inputparameters. If the input parameters specify RCONNECT=YES, NetView AccessServices displays the Application Selection panel upon return from a pass-modeapplication.

If SIMLOGON=NO is specified, NetView Access Services does not issue aSIMLOGON for the terminal LU that is passed to another application. If the ter-minal is returned because NetView Access Services has been defined as thedefault logon application, and SIMLOGON=NO is defined in the NetView AccessServices input parameter file, the Logon panel is always displayed, regardless ofwhat has been specified for the RCONNECT keyword.


Figure 6. Passing the Terminal through Several Systems with SIMLOGON=YES

Pass Mode Return If the Terminal Is Switched OffThis also refers to what happens if there is a power failure.

If the terminal is switched off while it is in session with an application, VTAM dropsthe session with the application. The pending queued SIMLOGON request isdropped from the queue and the NetView Access Services Logon panel or Applica-tion Selection panel is not displayed.

The NetView Access Services Virtual Terminal ConceptVirtual Terminal (VT) is a new concept for handling and storing incoming 3270 datastreams in NetView Access Services. The data stream coming from an applicationis processed by the VT function. VT acts on all 3270 orders, and stores the dataas a screen image . This screen image is always a true copy of the actual terminalscreen buffer, including the extended attribute buffer of the display terminal.

For example, when a Jump or Escape requires to save the current screen, only thenewly modified data is added to the VT buffer. No Full Screen Read operationmust be issued. When the screen has to be restored later, the VT component gen-erates a 3270 data stream out of its saved VT buffer, and sends it to the terminal.

This provides the following enhancements over current non-VT operation:

� Improved line performance for all functions that require a Full Screen Read.This is especially important for installations using relatively slow remote lines.

� VT operation is a prerequisite for the NVASAPI function, which works againstthe VT buffer to find fields or modify data, for example. These functions aredescribed in Chapter 16, “NetView Access Services REXX Application Pro-gramming Interface Functions” on page 225.


� Session running in the background, for example, not displayed on the screen,continue to accept outbound data from an application, until this application iswaiting for input. This is important for Operator consoles with a lot of output.

� In VT mode, NetView Access Services improves the handling of the applicationID display function. This means that the application ID is written to the screenonly if there is a protected field and no input field will be overwritten. The lastattribute overlayed by the application ID on the terminal screen is added at theend of the application ID to make sure that no colors, highlighting, or text onthe screen are changed. The appearance of the application ID on the terminalscreen depends on whether the display mode is currently set to extended orbase display mode.

� Write optimization. NetView Access Services Version 2 uses enhanced com-pression algorithms. If Y is specified in the Data Compression field on theAssign an Application to a Group panel, then the type of compression for out-bound data streams depends on the virtual terminal definition for the applica-tion. If N is specified in the Virtual Terminal field on the Assign an Applicationto a Group panel, the normal compression method is used, which replacesrepeated characters with a Repeat to Address Order. If Y is specified in theVirtual Terminal field, an enhanced compression algorithm is used. The WriteOptimization function checks whether the data is already on the real terminal,and only the delta data (data that has changed) is transmitted in compressedformat. Erase/Writes may change to Update/Writes for this process.

� Outbound and Inbound Data Compression. If F is specified in the Data Com-pression field on the Assign an Application to a Group panel, and Y is specifiedfor Virtual Terminal, NetView Access Services compresses the outbound dataas previously described, that is, only the changed data is sent. In addition,NetView Access Services removes all MDT-bits (Modified Data Tag) from thefield definitions sent to the real device. This reduces the inbound data becauseonly the data entered is sent to NetView Access Services. NetView AccessServices then adds the data from all other fields and sends it to the application.

What the Virtual Terminal Concept Supports

3270 Data Stream SupportThe VT function supports all 3270 base and extended orders. The extended attri-bute support is limited to the following attribute types:

1. Extended highlight (attribute type X'41')2. Foreground color (attribute type X'42') for up to 15 colors3. Background color (attribute type X'45') for up to 15 colors4. Character set (attribute type X'43')5. Transparency (attribute type X'46').

If other attribute types appear in the data stream, NetView Access Services tempo-rarily leaves VT mode, and continues working in non-VT mode of operation, untileither a command or a structured field that clears the screen, or the CLEAR keyrecovers from this situation.


Outbound 3270 Structured Field SupportThe VT function checks the header information in each structured field. Some ofthe structured fields are handled by the VT terminal function before they are passedto the terminal. Other structured fields are just passed to the terminal withoutaction.

Inbound 3270 Structured Field SupportThe VT function checks each Structured fields header information. Some of thestructured fields will be handled by the VT function before they are passed either toNetView Access Services or to the application. Other structured fields are justpassed to the application without action.

Virtual Terminal and 3270 Null/Space HandlingWhen a virtual terminal is configured for an application, NetView Access Servicesno longer uses the Read Buffer command to read the complete screen, forinstance, for a Jump or Escape. Instead, the Read Modified data stream commandis used to update the virtual terminal buffer in NetView Access Services storage.Because the Read Modified command suppresses all nulls from the applicationpanel, input data may appear shifted when the saved application panel is redis-played. This is similar to the effect seen when using host editors, such as SPF,when working with Nulls ON. To avoid this effect, it is recommended to run the3270 terminal with the Enhanced Null/Space processing set to ON. EnhancedNull/Space processing provides all the advantages of Read Modified, but no longershifts data. For further information on Enhance Null/Space processing and how toset it to ON, refer to 3174 Establishment Controller Terminal User’s Reference forExpanded Functions.

Functions that Leave Virtual Terminal ModeThe following functions cause NetView Access Services to temporarily leave VTmode of operation:

� DBCS (Double Byte Character Set) data in a data stream� Use of Multiple Partitions� BIDI (Bidirectional Languages, for example, Arabic, Hebrew) in a data stream� Format Storage Structured fields� Attributes appearing in the data stream other than 3270 base and extended

orders and attribute types previously mentioned under 3270 data streamsupport.

These functions cause NetView Access Services to temporarily leave VT mode ofoperation, until the application sends a command that clears the VT buffer, or theuser presses the CLEAR key on the terminal. In this case, VT operation isresumed.

Data Stream Error HandlingIf virtual terminal function detects a data stream error, a NetView Access Servicesoperator message is issued. This message includes an error code that identifiesthe cause of the error. Then the defective data stream is passed to the terminal.The sense code generated by the terminal then causes the session to be left andthe Application Selection panel is displayed with an error message.

If the data stream error is detected while the VT function is working with a sessionin the background, a NetView Access Services operator message is issued, and


the defective data stream is queued and later sent when the user switches to thisapplication. The logical unit will appear busy during this queuing time.

Invocation and InteractionVT mode of operation is the default for NetView Access Services. The systemadministrator can disable VT mode for an application. For further information, referto NetView Access Services Version 2 Administration.

The VT function for the NetView Access Services panels is always allocated andused. It can not be disabled by administration.



Chapter 2. VTAM Considerations

The following provides VTAM considerations.

How NetView Access Services is Defined in VTAMNetView Access Services can be defined in VTAM in a number of ways that can beused to implement a user logon to NetView Access Services.

NetView Access Services Defined as a LOGAPPL for a TerminalUsing the LOGAPPL operand in the VTAM definition statement for a terminal to beconnected to NetView Access Services causes VTAM to initiate a session automat-ically when the terminal is activated. This means that when the terminal isswitched on, the NetView Access Services Logon panel is displayed. The sessionis created immediately, even if the terminal is not in use. This might influence thetotal system performance, because the session establishment processing and thesending of the Logon panel is performed by NetView Access Services. A high CPUload might occur during system start or restart.

NetView Access Services Defined as a VTAM USSTAB EntryTo request a session with an application program, an LU can send a formattedlogon request to VTAM specifying the name of the application program (in thiscase, NetView Access Services) and some other information. This is hard coded inthe terminal LU and therefore not all terminals can initiate a formatted logonrequest.

However, VTAM can also accept logons in character-coded (unformatted) form froman LU. To do so, the unformatted system services (USS) component of VTAMmust have the appropriate tables to convert the character strings into formattedrequests. The installation must create these tables.

Using the VTAM USS, the terminal is connected to VTAM when it is switched on.When a piece of character-coded information is entered, VTAM establishes asession between the terminal and the application defined in the USS definitions.That is, the USS table (USSTAB) tells VTAM what to do. If USSTAB is used, theterminal is in session with VTAM only when it is switched on, and the session toNetView Access Services is established on user request. This means that aUSSTAB definition causes less load than a LOGAPPL definition. The definition youuse in your environment depends on your performance and usability requirements.

For additional information refer also to VTAM Resource Definition Reference.

NetView Access Services Defined As an Entry in a VTAMInterpret TableIf the SEQNCE operand on the LOGCHAR macro is not specified for a VTAM inter-pret table entry, and the APPLID operand specifies the NetView Access Servicesapplication name, then all user logons are directed to this application. That is, nomatter what the user enters at the terminal, if this is the first entry in the interprettable, the user logon is always forced to the NetView Access Services Logon panel.Therefore, by specifying the INTAB operand on any or all of the VTAM terminal orLU definition statements, any terminal can be forced to USSTAB entry.


To force users to always access applications through NetView Access Services aVTAM interpret table can be built.

Figure 7 shows a sample VTAM interpret table.

INTBL INTAB

LOGCHAR APPLID=(APPLICID,NVAS_APPL),SEQNCE='NVAS' LOGCHAR APPLID=(APPLICID,NVAS_APPL),SEQNCE='nvas' LOGCHAR APPLID=(APPLICID,NVAS_APPL) ENDINTAB

END

Figure 7. Sample VTAM Interpret Table

Where NVAS_APPL is the name of your NetView Access Services application.

This table automatically displays the NetView Access Services logon screen regard-less of the key stroke entered at the VTAM USSMSG10 screen.

NetView Access Services Buffer Usage for VTAM MacrosNetView Access Services uses VTAM macros, SEND and RECEIVE, with both ter-minals and applications, but does not use the authorized path facility of VTAM.VTAM uses Service Request Block (SRB) scheduling for much of theSEND/RECEIVE functions. NetView Access Services uses multiple Task ControlBlocks (TCBs) to perform various functions and therefore can exploit a multi-processor machine, in conjunction with the SRB scheduling of VTAM.

It should also be noted that NetView Access Services uses the VTAM LargeMessage Performance Enhancement Outbound (LMPEO) option for SEND oper-ations, as appropriate. For this purpose it uses the facilities of VTAM to split alarge data buffer into one or more Request Units (RUs) for transmission to thereceiver. None of the RUs generated by VTAM exceed the RU size specified in theBIND for sending in that direction on the session. Because there are two separatesessions in relay mode, the RU sizes can differ between the terminal-to-NetViewAccess Services session and the pseudo terminal-to-application session. You cancompare the RU size used in the logmode table entries (EMSMODE), used byNetView Access Services for pseudo terminal sessions, to the RU size that isacceptable to each application. Then you can determine whether changes couldimprove performance.

Logmode ConsiderationsThe following provides information on logmode entry analysis and provides consid-erations for printers.

Logmode Entry AnalysisA logmode entry or BIND information is used to establish the session between thereal terminal and NetView Access Services. However, NetView Access Services,when establishing a relay mode session with an application, does not use the samelogmode entry or BIND. When a session request (CINIT) is received from the ter-minal in the VTAM logon exit for NetView Access Services, it analyzes the


PSERVIC field of that BIND to select an equivalent logmode entry from its logmodetable, EMSMODE, as follows:

1. The LU type of the terminal is first examined. The only LU types that are sup-ported are LU Type-0 and LU Type-2. Both the Function Management (FM)and Transmission Services (TS) profiles are examined to determine the LUtype. If the FMPROF and TSPROF are 02, then an LU Type-0 is assumed. Ifthe FMPROF and TSPROF are 03, then an LU Type-2 is assumed. Otherwise,a message is issued (EMS0517E).

2. The logmode for the incoming terminal session must not be specified by usingan Exception Response Only protocol. This session request will be rejected, ornot established by NetView Access Services. All data to the terminal is sent tothe terminal with Exception Response, with the exception of Change Directioncaused by the Attention key. This is sent with Definite Response.

You are required to use one of the following protocol types:

� No response� Definite response only

Refer also to the note on page 80 � Definite or exception response

for the terminal session (PRIPROT parameter in the logmode table entry) andthe application session (SECPROT parameter in the logmode table entry).

3. The PSERVIC is examined to determine if extended data stream or queryfacility is supported for the terminal. If the terminal supports this facility, thelogmode entry name that is selected has the prefix EXT. However, if the ter-minal does not support the extended data stream, the prefix SNA is used forthe logmode entry name selection.

4. The next element analyzed in the original BIND is the screen size of the ter-minal. The PSERVIC field is examined to determine whether the terminal canalso support an alternative screen size. The hexadecimal value of X'7F' in thescreen size control byte in the PSERVIC indicates that an alternative screensize is supported and X'7E' indicates that only a primary screen size can beused. A value of X'03' means that a dynamic screen size is used. Theprimary or alternative screen size or both, determine the terminal type or modelthat is selected for the logmode entry name. The suffix that is appended to theEXT or SNA prefix is the same as that used in the VTAM supplied defaultlogmode entry table—ISTINCLM.

5. If a match cannot be made with the value in the PSERVIC field, then amessage is issued (EMS0517E) and an attempt is made to establish thesession using the logmode entry used to establish the original terminal session.However, for NetView Access Services to use that particular logmode entry, itmust be added to the EMSMODE table that NetView Access Services uses.

The logmode entries in the EMSMODE table do not include any Class ofService (COS) name. Therefore, to ensure consistent transmission priority forinteractive sessions in relay mode, the EMSMODE table entries must also beupdated to match the installation’s requirements. Also, this logmode entry canbe defined only for an LU Type-2 device, because NetView Access Servicesonly uses an LU Type-2 device as a pseudo terminal. See Figure 8.

Chapter 2. VTAM Considerations 17

Figure 8. VTAM and NetView Access Services Logmode Entry Tables

For example, for a 3270 terminal that supports Extended Data Stream, NetViewAccess Services uses the prefix EXT for the logmode entry. If this terminal alsosupports a primary screen size of 24 by 80, a 2-byte hexadecimal value of 1850,and an alternate screen size of 32 by 80 or X'2050', then NetView Access Ser-vices maps that to a terminal type/model suffix of 32783. Therefore the logmodeentry that is used by NetView Access Services to establish any relay mode ses-sions for this terminal is EXT32783.

This analysis of the original terminal logmode entry is done only for relay modesessions. For pass mode sessions, the original logmode entry used to establishthe session between NetView Access Services and the terminal is used, unless it ischanged by the EMSESEEX installation-wide exit.

The logmode entry used when NetView Access Services establishes a session withan application can be:

| � Overridden by the user. This is done on the Application Selection panel by| entering the application ID, followed by LM= and the new logmode value. For| example:

| 5 LM=EXT32782

| The new logmode value remains active until the user logs off from the applica-| tion.

| � Specified by the NetView Access Services administrator using option 6 of the| ADM function. This LogMode will be used by NetView Access Services to| open all the server sessions with this application both in pass-mode and in| relay-mode, when the user requesting the session is logged on this group.

| The logic priority for choosing the logmode to be used is as follows:

| 1. Session establishment exit (EMSESEEX)

| 2. LogMode field on option 6 of ADM function

| 3. NetView Access Services chosen logmode.

Logmode Considerations for PrintersNetView Access Services allows a user to send a copy of an application panel to aprinter. The copy can be sent:

� Directly via VTAM to a line printer connected to NetView Access Services. Forinformation on defining VTAM printers to NetView Access Services, refer to“Customizing for Model Terminal Support” on page 82.

� To a JES2 or JES3 system printer.


NetView Access Services supports the printing of:

� Alphanumeric characters� Special displayable characters� Double Byte Character Set (DBCS) characters

� Field outlining � Nondisplayable fields.

The following characters are ignored by NetView Access Services:

� Intensified display � Extended highlighting � Extended color� Character sets other than the default and the DBCS character set

� Transparency.

Notes:

1. Truncation takes place if the presentation space of the printer (rows andcolumns) is less than the presentation space of the terminal.

2. At the beginning of printing, NetView Access Services assumes that the printeris already positioned on a new page.

Print Support for Printers Connected to NetView AccessServicesNetView Access Services establishes a session with a printer via VTAM when theuser requests to print an application panel. The printer session is available as longas:

� No other application program requests the printer� NetView Access Services is sending print data or data is queued� NetView Access Services is running.

NetView Access Services supports the following printer type sessions:

LU1 LU-LU session type 1 (data stream based on the SNA Character String(SCS) or structured fields).

NetView Access Services uses FM profile 3 and TS profile 3. Any othervalues for these profiles are changed to 3. NetView Access Services sup-ports the exchange of FM headers if requested by the SLU. It is suggestedthat the printer is run with FM headers. This allows NetView Access Ser-vices to determine the printer row and column size as well as the ability tosupport DBCS and field outlining.

If the exchange of the FM headers is not supported, NetView Access Ser-vices assumes that the printer does not support DBCS and field outlining. Inthis case, NetView Access Services uses a default column size of 80 and adefault row size of 72.

LU3 LU-LU session type 3 (an SNA 3270 data stream).

If the printer is defined to support extended data stream (that is, query issupported), then NetView Access Services checks whether the printer canhandle DBCS and field outlining. If not, NetView Access Services assumesthat the printer does not support these.

Chapter 2. VTAM Considerations 19

Print Support for System PrintersNo truncation is performed by NetView Access Services, and it is assumed that thesystem printer supports DBCS and field outlining. No special entry is needed in theNetView Access Services supplied logmode table, EMSMODE.


Chapter 3. VSAM Considerations

The following describes some VSAM items that should be considered in conjunctionwith your NetView Access Services.

VSAM PerformanceThe following VSAM items may have an impact on the performance of yourNetView Access Services.

VSAM Profile LocationNetView Access Services maintains a set of VSAM profile data sets. Most of theprofiles are used only at NetView Access Services startup and for administratorupdates. However, the EMSSRTU data set containing the user profiles is used atevery user logon to NetView Access Services. In addition, the EMSALLT profiledata set is used for each automatic logon or logoff. Therefore, it is recommendedto locate these data sets on a DASD volume that allows for fast access. If youwant to share the data sets, they have to be located on a shared device.

The SRTU can be discarded only if no Normal groups exist in the NetView AccessServices system. The EMSGAL profile data set is read whenever the ADMcommand is issued.

VSAM TuningWhen a user assigned to use applications in a normal group logs on, NetViewAccess Services performs VSAM I/O to retrieve user profile record from its VSAMuser data set (EMSSRTU).

The number of records retrieved from the VSAM data set corresponds to thenumber of applications that the user is authorized to access. For instance, if a useris authorized to use three applications, three separate records are retrieved fromthe VSAM data set. Each user profile record contains one authorized applicationfor the user and the access parameters (for example, jump key or applicationsequence) for that application.

VSAM tuning for the user-profile data set can improve VSAM access performanceand therefore reduce logon response time and CPU usage. Some of the VSAMtuning techniques are:

� Allocate additional index buffers.

The recommended method for allocating buffers is to specify explicitly thedesired number of buffers on the DD statement using the AMP parameters withBUFNI subparameters.

� The index and data components may be allocated on different volumes toimprove direct processing performance if IMBED is not used.

For further information, refer to the MVS/ESA VSAM Administration Guide.


Reorganizing VSAM Data SetsVSAM data sets must be reorganized using IDCAMS services periodically toimprove access to the VSAM data sets and consequently to improve the systemperformance. It is the system administrators responsibility to determine the periodbetween reorganizations based on the frequency of data set updates.

Sharing VSAM Data SetsNetView Access Services allows its profiles, which are located in VSAM data sets,to be shared between more than one program. This allows an installation to runmore than one NetView Access Services and the Batch Load Facility concurrently,using the same profiles. For information on the Batch Load Facility, refer toNetView Access Services Version 2 Administration. The profile sharing allows forbalancing the system workload or increasing the system’s availability.

When sharing VSAM data sets, NetView Access Services locks the VSAM datasets for all ADD, UPDATE, READ, and DELETE requests.

VSAM I/O activity of NetView Access Services is mainly performed during theinitialization phase and the refresh phase. The EMSDSRTG, EMSDSRTS,EMSDPLDT, EMSDGPRF, and EMSBROD files are read when a REFRESHcommand is processed. The user profile (EMSSRTU) is read when a user logs onto NetView Access Services, and the automatic logon profile (EMSDALLT) is readwhenever an automatic application logon or logoff is performed. EMSDALLT iswritten to when an automatic logon profile is recorded. Other files are also writtento when the administration facility is used for update. The normal use of the admin-istration facility does not produce any significant I/O activity.

Prerequisites for Sharing Data SetsSharing VSAM data sets NetView Access Services follows the requirements, speci-fied in the MVS/ESA VSAM Administration Guide.

The actual processing in NetView Access Services is triggered by two bits in theEUSZAP flag-bit area (refer to Figure 10 on page 25):

� Cross-region profile-sharing flag� Cross-system profile-sharing flag.

The job EMSVLOCK is provided by NetView Access Services to modify theEUSZAP flag-bit area according to your installation requirements. For further infor-mation refer to “EMSVLOCK” on page 75.

Ensuring Data Integrity for READ and WRITE Access

Cross-Region SharingConcurrent VSAM accesses, invoked by the VSAM subtasks of severalNetView Access Services or the Batch Load Facility in the same operatingsystem, are synchronized using the ENQ and DEQ macros. You must enablecross-region sharing by using value '1' for the cross-region profile-sharing flag.

The ENQ and DEQ macros are invoked with the SYSTEMS parameter and,supported by the global resource serialization facility (GRS), have a scopeacross operating systems.


The macros use the fixed value EMSELOCK for the queue name and theactual values specified for the appropriate VSAM DD name in the EMSSTARTjob for the resource names. An example with resource names is shown inFigure 9.

//EMSSTART

...

EMSSRTS DD DSN=EMS.SAMPLE.EMSSRTS

EMSSRTG DD DSN=EMS.SAMPLE.EMSSRTG

...

Figure 9. Example of EMSSTART Job Showing Resource Names

In the example, the resource names are:

EMS.SAMPLE.EMSRTS for SRTS

EMS.SAMPLE.EMSRTG for SRTG

Using the resource names for each VSAM data set reduces the occurrence ofa locking conflict. For example, a system administrator can add a new applica-tion to the NetView Access Services system (adding a new SRTS record) inparallel to a user who updates an SRTU profile.

VSAM write access is locked with the EXCLUSIVE parameter of the ENQmacro, and read access is locked with the SHARED parameter. For moreinformation on the ENQ and DEQ macros refer to MVS/ESA ApplicationDevelopment Macro Reference.

Cross-System SharingIf the NetView Access Services systems that share the data sets are located ondifferent operating systems, in addition to the ENQ and DEQ processing, reo-pening of the particular data set occurs every time it is accessed. This ensuresthat the different VSAM systems are always working with the true information ofthe data sets concerning CI/CA splits. You must enable cross-system sharingby using value '1' for the cross-system profile-sharing flag. The flag can beswitched with the EMSVLOCK job. For further information refer to“EMSVLOCK” on page 75.

Share Options for NetView Access Services Used VSAM Data Sets

NetView Access Services always requires write access when opening the VSAMdata sets. For cross-region sharing you must ensure that the VSAM data sets youwant to share between more than one NetView Access Services are defined withSHAREOPTIONS(4,3) parameter. Note that the shipped default option for NetViewAccess Services is SHAREOPTIONS(3,3).

If in addition you want to share the data sets across operating systems,SHAREOPTIONS(3,3) is sufficient. This is because the synchronization ismanaged by NetView Access Services in a different way.

Note: Sharing VSAM data sets always affects system performance. Most per-formance degradation can be expected from setting the cross-system profile-sharing flag on. It is therefore recommended not to switch this bit on if you do notintend to share the data sets across operating systems.

Chapter 3. VSAM Considerations 23

Sharing VSAM data sets is disabled by submitting the EMSRESTO job. For furtherinformation, refer to “Modifying EUSZAP Flag-Bit Area for Sharing VSAM Profiles”on page 75.

Activating Modified Share Options

You can change the SHAREOPTIONS parameter of your data sets using theALTER command. For instance, before you start a Batch Load job concurrently toa running NetView Access Services, you can change the share option to 4,3 and,after the job has completed, reset the share option to 3,3.

Note: A changed share option must be activated in NetView Access Services.

NetView Access Services provides the ability to activate a modified VSAM shareoption in a running NetView Access Services system. The share option becomesactive in NetView Access Services by closing and reopening all NetView AccessServices allocated VSAM clusters.

The CLOSE/OPEN process cannot be invoked separately, but it is linked with therefresh function. The CLOSE/OPEN process is independent of the share optionspecified in the EUSZAP area. This means, if no cross-region sharing and nocross-system sharing is specified, the NetView Access Services allocated VSAMclusters are closed and reopened.

You must enable the “CLOSE/OPEN before REFRESH” by using value '1' for the“CLOSE/OPEN before REFRESH flag”. This flag can be switched with theEMSVLOCK job. For further information refer to “EMSVLOCK” on page 75.

Notes:

1. Switching the sharing of VSAM data sets on and off is not possible whileNetView Access Services is running.

2. All NetView Access Services systems that share the data sets must berestarted after the function has been switched on or off.

3. NetView Access Services reads the VSAM data sets during startup and thenmaintains all profiles in main storage that are not user related. This avoidsadditional disk access during runtime. However, a refresh function is requiredevery time the VSAM data sets are modified via an external program thatshares the data sets, for example, a batch load or a second NetView AccessServices.

4. Sharing VSAM data sets does not guarantee data consistency for concurrentupdates between NetView Access Services profile data and the VSAM datasets. Installations are advised to put into place procedures to ensure that onlyone administrator function tries to modify a given record at a particular time.

Suppressing Reopening of Data Sets for Cross-System SharingWhen cross-system sharing is requested, reopening of the particular data setoccurs every time it is accessed. Reopening can be suppressed for one or moredata sets by one or more indicators in the EUSZAP flag-bit area. For example,when two NetView Access Services systems share all VSAM data sets with theexception of EMSBROD (each system has its own EMSBROD cluster), or whentwo NetView Access Services systems share an EMSBROD VSAM cluster and allother VSAM clusters used are different for each NetView Access Services system.


Only the NetView Access Services cluster EMSBROD can be handled differentlythan other NetView Access Services clusters, because EMSBROD has no logicaldependency on any other NetView Access Services cluster.

Note: Using shared profiles together with unshared profiles in a NetView AccessServices system in another way to that described can lead to unpredictable results.

Cross-system sharing of NetView Access Services VSAM profiles is indicated via aflag-bit area in the NetView Access Services zap area EUSZAP. The flag-bit areacan be switched with the job EMSVLOCK and can be reset with the jobEMSRESTO.

EUSZAP Flag-Bit Area

1st Byte

XXXX Xððð ðððð ðððð

│││

││└───────────── Cross region profile sharing flag

││ '1' = share profiles cross region

││ 'ð' = no profile sharing at all

││

│└────────────── Cross system profile sharing flag

│ '1' = share profiles cross system

│ Cross system sharing is started

│ only if the cross region sharing

│ is activated.

│ It is possible to suppress cross

│ system profile sharing on profile

│ level. See 2nd byte.

│ 'ð' = no cross system sharing

│

└─────────────── CLOSE/OPEN before REFRESH flag

'1' = A VSAM CLOSE/OPEN is issued for

each entered REFRESH command

regardless of the profile sharing status.

'ð' = VSAM CLOSE/OPEN is issued depending

on the profile sharing status.

2nd Byte

┌───────┬────── This flag area byte is used for cross

│ │ system sharing only

XXXX Xððð ðððð ðððð (cross system flag = '1'

││││ ││││ cross region flag = '1').

││││ ││││ It indicates all VSAM profiles that

││││ ││││ are excluded from cross system profile

││││ ││││ sharing. That means VSAM CLOSE/OPEN

││││ ││││ is suppressed for the indicated

││││ ││││ profiles.

││││ ││││ Each flag agrees with one profile:

││││ │││└────── EMSBROD ─ Time controlled messages

││││ ││└─────── EMSGAL ─ Admin. access list profiles

││││ │└──────── EMSALLT ─ Automatic logon profiles

││││ └───────── EMSGPRF ─ Group profiles

││││

│││└─────────── EMSPLDT ─ BIND user data profiles

││└──────────── EMSSRTU ─ User profiles

│└───────────── EMSSRTG ─ Group application profiles

└────────────── EMSSRTS ─ System application profiles

Figure 10. EUSZAP Flag-Bit Area

Chapter 3. VSAM Considerations 25

Example of Modifying the EUSZAP Flag-Bit AreaTable 1 shows an example of modifying the EUSZAP flag-bit area.

Table 1. Example of Modifying the EUSZAP Flag-Bit Area

ZAP Value Meaning

0100 VSAM cross-region sharing

0300 VSAM cross-system sharing

0400 CLOSE/OPEN VSAM data sets for each refresh command

0301 VSAM cross-system sharingThe profile EMSBROD is excluded from cross-system sharing

Refreshing VSAM Profiles with the Latest UpdatesThe refresh function allows an installation to read in the following profiles fromVSAM:

EMSSRTS EMSSRTG EMSGPRF EMSPLDT EMSBROD

to then update the NetView Access Services profiles with the latest versions fromVSAM.

Note: Concurrent updates can result in data inconsistency between NetViewAccess Services profile data and the VSAM data sets. The Locking function pre-vents destroying the VSAM data sets during a parallel operation, but it does notprevent data inconsistency between NetView Access Services profile data and theVSAM data sets.

Installations are advised to put into place procedures to ensure that only oneadministrator function tries to modify a given record at a particular time.


Chapter 4. Security and Accounting Considerations

The following provides information on various security aspects and the exits thatcan be used for accounting tasks.

Network and Application Access ControlNetView Access Services can secure access to both the network and applications.It can act as a front-end security system for the SNA network in that only users witha valid user ID and password that are registered with NetView Access Services anda security management system such as RACF* can gain access to the network.The facility protects the SNA network from any unauthorized access. You cantherefore make it a requirement that every user enters into your network exclusivelyvia NetView Access Services.

You can use the following methods to implement a user logon to NetView AccessServices:

� After switching on, log the users’ terminals automatically on to NetView AccessServices by specifying the operand LOGAPPL on the VTAM terminal LU defi-nition statement.

For further information refer to “NetView Access Services Defined as aLOGAPPL for a Terminal” on page 15.

� Define NetView Access Services in the USSTAB table and allow users to issuea command to invoke NetView Access Services.

For further information refer to “NetView Access Services Defined as a VTAMUSSTAB Entry” on page 15.

� To force any or all users to log on to NetView Access Services, a null entry in aVTAM interpret table can be used.

For further information refer to “NetView Access Services Defined As an Entryin a VTAM Interpret Table” on page 15.

NetView Access Services also allows a system administrator to restrict the applica-tions that are accessible by each user or group of users. The user can thereforeonly have access to those applications that the system administrator associatedwith the group, and that the group administrator has authorized the user to gainaccess to.

Application and Terminal Idle TimeThe system can also be used to help protect against unauthorized access from aterminal that is connected but not being used. NetView Access Services discon-nects relay mode application sessions for which there is no user activity after apredefined timeout period has elapsed. The system administrator specifies thetimeout period for each relay mode application session and, if NetView Access Ser-vices receives no data from the application after the specified idle time, that sessionis disconnected.

If there is no input activity from a terminal for a predefined time, the sessionbetween NetView Access Services and the terminal is disconnected.


If the terminal idle timeout occurred with an application screen displayed on theterminal, or with the NetView Access Services Application Selection panel showinghighlighted applications on the terminal, the application sessions are still maintainedby NetView Access Services until the application idle time-out for a particular appli-cation occurs. For additional information refer to “APPL Control Statement” onpage 68 and the IDLETIME operand in the list that follows Figure 18 on page 68.

Installation-Wide ExitsIn addition to the standard administrative security mechanisms, NetView AccessServices provides installation-wide exits that can be used to implement additionalsecurity measures.

Restricting UsersThe logon authorization exit EMSELGNX is invoked each time a user logs on toNetView Access Services. This exit can be used to verify a user’s access using asecurity management system such as RACF, and can deny access at that point.You can also use the logon exit if RACF or another security system is not used.

The PUBUSER User ID: An initial administrative user ID (PUBUSER) is also pro-vided with NetView Access Services. NetView Access Services does not allow thisuser ID to be deleted. The security management system can prevent other usersfrom logging on with this user ID. For example, the security administrator canrevoke the PUBUSER user ID in RACF.

Restricting ApplicationsThe session establishment exit EMSESEEX is invoked each time an applicationsession is established by a user. Information is passed to the exit such as thetarget application name, the user’s group and user ID, the name of the terminal,and even the logmode entry. You can use this exit to deny access to the applica-tion in addition to that already provided through the standard administrative facilitiesof NetView Access Services.

Restricting TerminalsYou can ensure that only terminals with specific names or naming conventions cangain access to the system. Using the SERVRTN definition statement, an installa-tion can specify through the INPLU operand the specific LU names or a generic LUname that can access NetView Access Services. This assigns terminals to a spe-cific Application Service Routine (ASR), which can be either the NetView AccessServices-supplied routine—End User Services (EUS) or a user-written ASR. Forfurther information refer to Figure 19 on page 70 and the INPLU operand in the listthat follows the table.

You may also utilize RACF to verify whether a terminal is authorized to log on toNetView Access Services. Any unauthorized terminal will receive an errormessage.

You can also use this technique to implement a different level of security. It can beespecially useful if your installation uses the network services of other organiza-tions. If an installation is connected to other SNA networks using SNA NetworkInterconnection (SNI), any cross network access to the installation’s applicationscan be forced through NetView Access Services. You can use this as an additionalsecurity check to ensure that only terminals that conform to a specific naming con-vention can perform a cross network logon to the NetView Access Services system.


Otherwise, this facility is normally not used to verify terminal names within the samenetwork, but is only used to associate a terminal name with a particular ASR.

The same process can also be used to check and verify a logmode entry name. Alogmode entry name can be specified on either the INPLU operand or theDEFMODEN operand of the SERVRTN control statement. You can use thesenames to further define the association of an LU to a specific ASR. However, it isnot necessarily practical to use this facility to further control access to NetViewAccess Services as is the case with an LU name.

The Language Verification exit (EMSELVEX) provides a convenient method ofchecking terminals.

User Data SecurityNetView Access Services can be used to control user access to, and therefore thecost of, network services that are provided by other organizations. The accountingexit can be used to record each cross network session that is established and ter-minated. This exit can be used to reject any application access that might exceedthe maximum number of sessions for the services contracted, regardless of theaccess mode. Another method is to use only relay mode sessions and establish apool of pseudo terminal names that supports the maximum number of sessions foraccess to the organization’s application services. Then for those relay mode ses-sions that are used to access those services, application session requests thatexceed the maximum pseudo terminal pool size are rejected. These techniquesmight effectively control access to network services and potentially reduce costs,depending on how the charges are derived.

Logon Panel SecurityOn the NetView Access Services default logon panel delivered with the product,there is a Location field which is intended to be used for accessing remote copiesof NetView Access Services. However, this field may also impose a security expo-sure since a user may gain access to any of your network application by enteringthe application name on this field.

To eliminate this exposure, the recommendations are:

1. If you do not have a remote NetView Access Services system, delete thelocation field from the logon screen. You can do this by modifying the defaultlogon screen using the guidelines in “Modifying NetView Access ServicesPanels” on page 91.

2. If you have several copies of NetView Access Services, the location field canbe useful. You can limit the applications that users can access through theLOCATION field by modifying and specifying the authorized applications in thesession initialization exit (EMSESEEX). This is documented in “EMSESEEX,Session Establishment Exit” on page 171.

For sensitive user data NetView Access Services provides variables that the usercan exploit to make this type of information secure, for example, for passwordsNetView Access Services provides variables &PWD, &OPW, &NPW. The valuesthe user assigns to these variables, using the Maintain User Parameters panel, aremasked by NetView Access Services.

Chapter 4. Security and Accounting Considerations 29

Therefore, to maintain proper security when recording an automatic logon profile,the user should use these variables instead of the actual values assigned to thevariables. The values of variables such as &PWD or &UVAR1 are not recorded inthe automatic logon profile. The variable values are only substituted as requiredduring the playback process.

Additionally, because NetView Access Services uses the “Confidential Text Facility”of VTAM, none of the user data is exposed in either a VTAM trace or a VTAMdump. For additional information, refer to the TRACE command described inNetView Access Services Version 2 Operation.

Terminal Based SecuritySome applications such as IMS provide security based on terminal ID. In order topreserve terminal-based security when accessing the application in relay mode,NetView Access Services can generate a pseudo terminal name based on a realphysical terminal name using a generic pseudo terminal prefix.

For more information on how to match a real terminal name with a pseudo terminalname, refer to “Matching a Real Terminal Name with a Pseudo Terminal Name” onpage 8.

PasswordsThe following paragraphs discuss password-related items.

Synchronizing Passwords across Several Host SystemsWith NetView Access Services, the task of synchronizing passwords across severalhosts can be simplified. Whenever a user enters a new password, NetView AccessServices can dynamically set the values of the new password variable (&PWD) andthe old password (&OPW) variables. If the user has previously defined values tothe PWD and OPW variables using the Maintain User Parameters panel, thenNetView Access Services retains these user-defined values. Otherwise, NetViewAccess Services defines the new password entered on the New Password field asthe value of the &PWD variable, and the value entered on the Password field asthe value of the &OPW variable. The user can then use these variables in an auto-matic logon profile to propagate the new password to applications in other hostsduring that session with NetView Access Services.

The user can record an alternative sequence as part of the active profile. In thiscase, the automatic logon sequence simply sends the old password variable whenthe application prompts for the current password, and the password variable(&PWD) when the new password is requested. This automatic logon sequencemust be executed during the session that the password is changed.

The values that are dynamically set for the &OPW and &PWD variables are lostafter the user logs off from NetView Access Services. These variables are set andmaintained only for the session during which the user changes the password.


Password ExpiryIt should be noted that NetView Access Services does not display a message toinform users that their passwords will expire in xx days, as some packages do, forexample TSO. However, when the password is expired, NetView Access Servicesprompts the user for a new password to be updated on the security system that isin use.

NetView Access Services does not record any message when an invalid passwordis supplied with a user ID. If RACF is used, then it issues a message indicatingthat an invalid password has been entered for a specific user ID.

RACF PassTicketWhen a user logs on to an application requiring a password, the password used issent in clear text across the network to the application. This presents a securityexposure. However, if you are using RACF 1.9.2 or later as your external securitymanager, this security exposure can be overcome using the RACF Secured Signonfunction. This RACF function is an SPE (small programming enhancement) thatprovides a RACF PassTicket as an alternative to a RACF password associated witha user profile. This enables another product or function to authenticate access toan application without needing to send passwords in clear text across the network.A PassTicket is a one-time-only password generated by the product or function.

NetView Access Services can be used to generate the RACF PassTicket to provideSecured Single Signon to an application. This requires the modification of two ofthe NetView Access Services installation-wide exits, the logon authorization exit,EMSELGNX and the session establishment exit, EMSESEEX.

For further information on the RACF PassTicket, refer to Enhanced Exploitation ofRACF 1.9.2 Secured Single Signon Using NV/AS.

AccountingThe following provides details on the ways in which accounting and auditing infor-mation can be gathered.

NetView Access Services Installation-Wide ExitsNetView Access Services provides three basic installation-wide exits that can beused to perform a variety of accounting or auditing tasks, or both. Two installation-wide exits, EMSELGFX and EMSELGNX, can be used to record information whena user logs on to or logs off from NetView Access Services. A third installation-wide exit, EMSENPME, is invoked each time a user establishes an applicationsession, regardless of the mode of access—pass or relay. Each of theseinstallation-wide exits are passed information that can be recorded in a facility suchas System Management Facility (SMF) for processing by other programs, such asthe Service Level Reporter (SLR) to perform accounting or auditing analysis.

The combination of these installation-wide exits can be used to perform accountingor auditing functions such as:

� Connection time accounting on a user ID basis for NetView Access Servicesand all applications accessed in either relay or pass mode

� Application access accounting on an account number basis


� Auditing access to specific applications for a user, group, or both, and ana-lyzing the mode of access.

You can use the logon authorization exit EMSELGNX and logoff exit EMSELGFX toprovide the total connection time to NetView Access Services on a user ID basis.The logon authorization exit EMSELGNX can record a successful logon to NetViewAccess Services, using a mechanism such as SMF. The logon record, in additionto date, time, and user ID, can include information such as the terminal name,which copy of NetView Access Services (ACB name) was used, and the groupname, if entered on the Logon panel. The logoff exit EMSELGFX can then be usedto record the logoff or disconnect of a user from NetView Access Services. Thelogoff record, written to SMF, can include information similar to the logon record.These records when sorted on the date, time, and user ID fields can provide arecord of logon activity to NetView Access Services, the connection time for eachaccess, and the network terminal name used for each logon.

A third installation-wide exit, the accounting exit (EMSENPME), can be used inaddition to the logon and logoff exits to perform application access accounting andanalysis. This accounting exit is entered whenever an application session is estab-lished or terminated, regardless of the mode—relay or pass and can be used torecord in SMF each application session established by a user. The basic type ofinformation that the record can contain is: date, time, user ID, group name, thename of the application accessed, and the network terminal used. Other relevantdata is also passed to the exit including the account number associated with theapplication and the mode of access—pass or relay. Since the exit is invoked eachtime the user terminates a session, the session end date, time, user ID, and appli-cation name can also be recorded. Therefore, by sorting these application startand end records using date, time, user ID, and application name, accounting orauditing can be performed on a user ID basis. In fact, in conjunction with the logonand logoff records that can be written to SMF using the other installation-wide exits,a user’s entire NetView Access Services application access and connection timecan be accounted for and analyzed.

NetView Performance MonitorNetView Performance Monitor (NPM) Release 4 in conjunction with the NetViewSynergy Interface (NSI) can correlate terminal and application sessions and provideyou with session accounting information for terminal-to-application sessions con-nected through NetView Access Services. For further information refer to “Enablingthe NetView Synergy Interface to the NetView Performance Monitor” on page 78.

NetView Performance Monitor (NPM) Release 3, in conjunction with NCP V4R3 orV5, provides a “network session accounting” facility. This facility enablesaccounting information from a session to be recorded with NetView Access Ser-vices information, in SMF. These records can be merged and sorted, by variouscriteria, to provide accounting information to a user ID level, which can be recordedand analyzed.


Application Access AuditingEach time a user logs on or off an application via NetView Access Services eitherin relay or pass mode, a record (Message EMS0250I) is generated and stored inthe SYSPRINT file.

Each record in the SYSPRINT file has the following structure:

� The user ID� The application name

� The time� The group name� The account number� The real terminal name� The pseudo terminal name� The type of connection (logon or logoff and relay or pass mode).

This file can be used to monitor the application access activity and to estimate thelogon and logoff rate for an application.

Considerations for 7171 Attached Dial-In TerminalsTo implement automatic disconnect of 7171-attached dial-in terminals when theuser logs off from NetView Access Services, the following tasks are required:

1. If the user is to gain access to applications in pass mode, specifyRCONNECT=NO and SIMLOGON=NO in the NetView Access Services APPLControl Statement.

For further details refer to “APPL Control Statement” on page 68 and theRCONNECT and SIMLOGON statements in the operand list that followsFigure 18 on page 68.

2. If the user is to gain access to applications in relay mode, modify the samplelogoff exit (EMSELGFX) to define the dial-in terminals in the TERMLIST field.The terminals in the TERMLIST field are automatically returned to the VTAMUSSMSG10 screen instead of the NetView Access Services logon screen afterthe user enters the LOGOFF or DISC commands. You can specify terminalsthat begins with certain characters or the complete terminal names in theTERMLIST field.

For further details of the EMSELGFX, Logoff Exit, refer to page 151.

3. Install the host initiated disconnect sequence X'2B5B4B' in the VTAMUSSMSG10.

To minimize the security exposure, you may also want to prevent dial-in usersfrom using the DISC command to leave relay mode sessions active. You canalso customize the EMSELGFX to change a DISC command to a LOGOFFcommand by modifying the LGFXTYPE parameter.


Considerations for Using the Dummy Logon Authorization Exit(EMSELGNX)

If you are not verifying the user ID and password via RACF or a security system atthe NetView Access Services logon screen, the following should be implemented toprevent access to the applications serviced through NetView Access Services:

1. Disable the DISC command so that users cannot leave any relay mode ses-sions active. This can be done by modifying the logoff exit (EMSELGFX) tochange the disconnect indicator D to L. For further details of the EMSELGFX,Logoff Exit, refer to page 151.

2. Disable the ability to log on at several terminals and transfer sessions from oneto another via the NetView Access Services administration function.

Session Transfer ConsiderationsFor applications that must only be accessed from authorized terminals, the sessiontransfer capability should be disabled. You can control and restrict the sessiontransfer function by two methods:

� When assigning an application to a user with administration option 3, a groupadministrator can specify N for the Terminal Assume field to restrict the userfrom assuming sessions from other terminals.

� The session reselection exit, EMSESREX, can be used to perform securitychecks when transferring an application session from one physical terminal toanother. The session transfer capability can be restricted via this exit based onterminal name, application name, or user ID.

The reselection exit is called under the following circumstances when a user:

– Disconnects from one terminal and logs on again from another, and selectsan active session that was initiated from the first terminal.

– Logs on concurrently on two physical terminals and attempts to transfer anapplication session from one terminal to another.

For further details of the EMSESREX, Session Reselection Exit, refer to page178.


Chapter 5. Network Considerations

The following provides network considerations.

Network OperationsAll of the facilities of NetView are available to perform any necessary network man-agement tasks for sessions that are operating in pass mode. That is, the NetViewsession monitor facility can be used to collect session awareness data (SAW) ortrace data, and even to obtain response time monitor (RTM) data. However, forrelay mode application sessions there are two network sessions involved:

� One session between the real terminal and NetView Access Services

� Other sessions between pseudo terminal names in NetView Access Servicesand the applications.

Therefore SAW and trace data, available through NetView, must be collected andcorrelated across two different sessions. RTM data can only be collected on thesession between the real terminal and NetView Access Services. Additional infor-mation on the RTM data collected for the relay mode session is discussed under“Response Time Monitor Considerations” on page 37.

Session initiation failures that are associated with relay mode sessions can requiremore investigation. To determine the cause of the failure, as recorded by theNetView session monitor facility, the pseudo terminal name used to initiate thesession must first be obtained. Messages EMS0599E and EMS0524E provide theapplication name, pseudo terminal name, VTAM failure sense code, and returncode information. Based on the application name, a network operator can possiblycorrelate a pseudo terminal with a user’s logon failure. If not, the network operatormay need to ask the user to repeat the logon attempt and examine the error mes-sages that are generated during the process. Once a relay mode session is suc-cessfully established, an operator can determine the name of the pseudo terminalthat is used for a relay mode session by issuing a NetView Access ServicesDISPLAY command.

To perform problem isolation for relay mode session errors, trace data can be col-lected using a VTAM buffer trace command or NetView trace command. The tracecommand can be issued for the pseudo terminal name to obtain data that is passedbetween the pseudo terminal name and the application. The same trace commandcan also be issued for the VTAM real network terminal name to obtain the data thatis passed between NetView Access Services and that terminal.

Using the Subsystem Interface (SSI) facility of NetView Version 2, messages gen-erated by NetView Access Services are accessible to NetView. The NetViewmessage automation table can trap and record the important messages in theNetView log. This facility enables an operator to use NetView as the single inter-face and source of information to perform problem isolation for NetView AccessServices. For instance, messages (such as EMS0599E, EMS0524E) that are gen-erated for relay mode logon failure can be recorded in the NetView log. Makingthese messages available from NetView eliminates the need for operators toaccess an MVS system console or browse the system log to obtain the information.


NetView Version 2 can also be used to monitor and control the availability of theNetView Access Services itself. NetView Access Services generates messages toreport any internal error conditions such as application service routine (ASR)abnormal terminations (EMS0507E), and maximum buffer pool encountered(EMS0529E). Therefore, NetView can be used to detect any NetView Access Ser-vices problems based on these messages. Messages that indicate severe prob-lems can also be used to trigger a CLIST to initiate any recovery action or generatean alert using the GENALERT function of NetView.

NetView Version 2 subsystem interface allows NetView Access Services messagesto be passed to NetView, and also enables an operator to issue an MVS/ESAcommand. NetView Access Services operator commands are issued using a replyto an outstanding write-to-operator (WTOR) message (EMS0990A). The SSI inter-face can therefore be used to send NetView Access Services commands as repliesto the WTOR message. CLISTs can also be constructed to allow operators toissue NetView Access Services commands without having to find out the currentMVS/ESA reply number for the EMS0990A message. Sample CLISTs are providedby NetView Access Services that can be used to issue NetView Access Servicescommands from NetView. For further information, refer to NetView Access Ser-vices Version 2 Operation.

Therefore, establishing communication between NetView and NetView Access Ser-vices can preserve the centralized network management strategy and facilitatescontrol of all network resources from a single networking tool.

Session Load BalancingThere are different possibilities for implementing session load balancing usingNetView Access Services:

� Different groups can be assigned to use different copies of the application.

� The session establishment exit EMSESEEX can be used to dynamically assignusers to different copies of an application.

� Different NetView Access Services can run concurrently.

The simplest way to achieve static load balancing is to assign different groups todifferent copies of the same application. This method does not balance the loaddynamically, but it is easy to implement. If one copy of the application is down, thesystem administrator can reassociate the group to another copy of the application.This means that manual intervention is required to provide a backup application.Also, all users must be defined to all copies of the application, because the copy ofthe application to which any user may log on can vary for each logon. If relaymode sessions are supported, all pseudo terminal names must also be defined toall copies of applications if terminal predefinition is required by the application (forexample CICS).

The session establishment exit EMSESEEX can also be used to perform sessionload balancing. This exit is invoked each time a user initiates a session with anapplication, either in relay or pass mode. The exit is passed the target applicationprimary logical unit (PLU) name, which can be altered in the exit. The users’session request for a particular application can be alternated between differentcopies of the application.


For example, users that use an application such as CICS could have the sessionsdirected to one of two different copies of the subsystem using this exit without anyuser intervention. In this case, the proper VTAM resource name for the appropriateCICS subsystem must be substituted in the target PLU name field in the parame-ters passed to the exit. If one of the copies of CICS terminates, the exit mightcontinue to direct sessions to that application incorrectly. Therefore, the exit mustbe capable of accommodating this particular condition.

Response Time Monitor ConsiderationsThere are several ways of gathering response time data. One is the use ofResponse Time Monitor (RTM), which is a hardware feature of the 3x74 controlunit. RTM collects response time on a transaction basis. The criteria used todetermine the end of a transaction is a parameter that can be specified during the3x74 control unit customization. When a terminal is in session with NetViewAccess Services, several types of activities can be registered as transactions byRTM, and can cause different response times to be recorded:

� Any NetView Access Services commands such as COPY, JUMP, ESCAPE,and administration commands issued from the terminal, are counted as indi-vidual transactions. The response time measured is the time between the entryof the command at the terminal and the receipt of the response from NetViewAccess Services. Therefore, the response time constitutes only the data trans-mission time on the session between the terminal and NetView Access Ser-vices plus NetView Access Services processing time. As shown in Figure 11,the response time for this type of activity is:

T1 + T2 + P1

� Any activity that is executed in a relay mode application session is also subjectto RTM response time recording. However, the response time measured is theend-to-end response time between the terminal and the application. Thisincludes the transmission time of the user request and application responsethrough both:

– The session between the terminal and NetView Access Services– The session between the application and the pseudo terminal

plus the application and NetView Access Services processing time. As shownin Figure 11, the response time for this type of activity is the sum of T1 throughT4, plus P1 and P2.

Figure 11. Response Time Measurement Considerations

Chapter 5. Network Considerations 37

If a user has several relay mode sessions with different applications, RTM data iscollected for all transactions executed on all relay mode sessions, as well as for allof the NetView Access Services commands that are issued. However, it is not pos-sible to separate the response time data for individual relay mode sessions. It isalso not possible to segregate the response time for the two types of transactionsmentioned previously. The RTM data recorded for all sessions is estimated usingone set of response time boundaries. If NetView is used, the performance classthat NetView Access Services maps to is used to determine the response timeboundaries and objectives. If NetView is not installed, time boundaries specified onthe 3x74 control unit customization are used.

NetView Performance Monitor ConsiderationsUsing the NetView Performance Monitor (NPM) program Release 4 in conjunctionwith the NetView Synergy Interface (NSI), it is possible to correlate NetView AccessServices terminal and application session data. Response time data can be col-lected by NPM for terminal-to-application sessions connected to NetView AccessServices. For further information refer to “Enabling the NetView Synergy Interfaceto the NetView Performance Monitor” on page 78.

If you are using a previous release of NPM software, then response time data canalso be estimated by NPM on a session-by-session basis. It should be noted thatthis is a more complicated method than that described for NPM Release 4. Whena user logs on to NetView Access Services, NPM can start estimating responsetime for the session between the real terminal and NetView Access Services.

As the user establishes relay mode sessions with different applications, separateresponse time data can be gathered for the sessions between the pseudo terminalsand the applications. When a response time problem occurs, NPM can be used todetermine whether the bottleneck exists at NetView Access Services or at the appli-cation.

Although NPM can provide individual application response time for each relay modesession, based on a pseudo terminal name, the response time collected includesonly the transaction time between NetView Access Services and the application. Inorder to compute the end-to-end response time between the real terminal and theapplication in relay mode, the transaction time between the terminal and NetViewAccess Services must be added to the transaction time between the pseudo ter-minal and the application. This requires a correlation between the real terminal andthe pseudo terminal, which is not possible when several relay mode sessions areestablished.


Network CapacitySince the normal data flow for a relay mode session is routed through NetViewAccess Services, user data is sent twice through the network, once on the sessionbetween NetView Access Services and the terminal, and again on the sessionbetween the NetView Access Services pseudo terminal and the application. Theimpact of having this additional network data can vary depending on the networkconfiguration, the location of NetView Access Services, and the number of relaymode sessions.

For example, in Figure 12 the support of relay mode sessions from terminalsattached to NCP2 to the application host creates additional network traffic on thechannel between the NCPs and the hosts, as well as on the Intermediate RoutingNode (IRN) telecommunication link between the two NCPs. The impact of thisadditional traffic on the channel might be minimal because channels can usuallyhandle large quantities of data. However, depending on the speed of the IRN linkbetween the NCPs and the number of relay mode sessions, this additional trafficmight create a network bottleneck and cause network congestion. A networkplanner should estimate the volume of the additional network traffic and make theappropriate network configuration adjustments.

Figure 12. Data Flow for Relay Mode


User Response TimeThe additional path that the relay session data must traverse before reaching thereal terminal can result in slower user response time. Using Figure 12 on page 39as an example, the response time for any user logging on directly from terminal T1to the application CICS, or using NetView Access Services pass mode is:

R = 3725D + CTT

However, if the user is to log on from NetView Access Services in relay mode toCICS, the response time is:

R = 4 \ 3725D + 3 \ CTT + 2 \ LTT

where:

3725D = Process delay and queuing time

CTT = Transmission time through the channel

LTT = Transmission time through the IRN link between NCPs.

As demonstrated in this example, the user response time between pass mode andrelay mode can be substantial, especially if the IRN link between the NCPs is at alower speed such as 9600bps. Also, as the number of relay mode sessionsincreases and more traffic is added to the IRN link, the queuing time alsoincreases.

Gaining Access to CICS/VS Using NetView Access ServicesThe following description applies to CICS/VS up to and including Release 1.6.CICS/VS 1.7 and subsequent releases have the autoinstall feature that can beused to define pseudo terminals to CICS/VS. Refer to the relevant CICS ResourceDefinition (Online) publication.

To gain access to CICS/VS using NetView Access Services, you must define theNetView Access Services pseudo terminal names for CICS/VS in the CICS/VS Ter-minal Control Table (TCT). The pseudo terminal names are defined by the admin-istrators on the Pseudo Terminal Prefix or Pseudo Terminal Name fields on theadministration panels.

Figure 13 shows an example of an entry in the CICS/VS TCT using the resourcedefinition (macro level).

DFHTCT TYPE=TERMINAL, X

TERMIDNT=ACð1, X

TRMTYPE=LUTYPE2, X

.

.

NETNAME=EMSYACð1, X

.

Figure 13. Defining a Session to CICS/VS in the TCT Using the Resource Definition (MacroLevel)


The NETNAME parameter refers to the NetView Access Services pseudo terminalname. CICS/VS overwrites the logmode entry it receives with its own TCT defi-nitions. For a terminal that does not support an extended data stream, the TCTterminal or TCT system entry in the table must specify ERRATT=NO, and EXTDS(extended data stream definition) must not be specified for FEATURE.

The GMMSG parameter in the CICS/VS TCT must also be taken into account. Ifthe GMMSG=YES parameter, or a default transaction is not specified, then it ispossible that control is not returned to the keyboard after the session is establishedand the keyboard remains locked.

This can be prevented by customizing the session establishment exit EMSESEEX,Control Block field, SEEXF1C2. For further information refer to “Send X'F1C2'after BIND” on page 173.

It is possible for the NetView Access Services Application Selection panel to be stilldisplayed after CICS/VS has become the active session. This is because CICS/VShas not erased the terminal screen. To erase the displayed screen press theCLEAR key.

Note: You must define each possible pseudo terminal name.

In the sample shown in Figure 13, you must define EMSYAC01 to EMSYAC99,assuming that a maximum of 99 sessions has been specified.

Refer to NetView Access Services Version 2 Administration for sample VTAM defi-nitions for NetView Access Services.

Gaining Access to IMS/VS through NetView Access ServicesTo gain access to IMS using NetView Access Services, you must define to IMS/VSthe NetView Access Services pseudo terminal names for IMS/VS. The pseudo ter-minal names are defined by the administrators on the pseudo terminal prefix orpseudo terminal name fields on the administration panels.

Figure 14 shows an example of a definition for IMS.

TYPE UNITYPE=SLUTYPE2

TERMINAL NAME=EMSYAIð1, X

MODEL=2, X

FEAT=(NOCD), X

OPTIONS=TRANSRESP

NAME EMSYAIð1

Figure 14. Defining a Session to IMS/VS

The NAME parameter refers to the NetView Access Services pseudo terminalname.


Notes:

1. You cannot use ACBs of type Shared.

For further information refer to “Shared ACB and Individual ACB Restrictions”on page 73.

2. You must define each possible pseudo terminal name.

In the sample shown in Figure 14, you must define EMSYAI01 to EMSYAI99,assuming a maximum of 99 sessions has been specified.

3. If you specify a SEGSIZE or OUTBUF parameter on the type statement toIMS/VS, it must match the request-unit (RU) size in the logmode table entrydefined to VTAM. These parameters are not shown in Figure 14.

4. If you are using Individual ACBs, you should consider the following securityproblem. If a user does not leave a terminal correctly (for example, simplyswitches off the power) another user may get the first user’s ACB and be ableto continue with that user’s IMS session.


Chapter 6. General Considerations

This chapter provides general considerations to be taken into account for yourNetView Access Services installation.

Resource UsageThe following items might have an impact on the performance and resource usageof your NetView Access Services system:

StorageIt is recommended that NetView Access Services is installed using nonswappablestorage. Only the NetView Access Services main module EMSMAIN needs to beincluded in the primary program operator interface task (PPT) with the attribute ofNOSWAP. Other modules that are called by the main module are given this attri-bute automatically.

NetView Access Services programs do not require any page fixing.

NetView Access Services modules do not have to be placed in the Link Pack Area(LPA).

Dispatching Priority of NetView Access ServicesIt is recommended that the dispatching priority of NetView Access Services is lessthan VTAM’s priority but greater than any application it services.

Buffer Size and Maximum Number of BuffersNetView Access Services uses a single buffer size for SEND/RECEIVE operations.This need not be large enough to contain the largest message that could bereceived and sent. If the buffer size selected is not large enough to receive all ofthe data, successive RECEIVE macros are issued to obtain all of the data, and thebuffer elements are chained. However, these additional RECEIVE operations addto the processing resources required to obtain the data. It is recommended that theselected buffer size is large enough to accommodate 80% or more of the mes-sages in a single buffer. Also, NetView Access Services uses dynamic bufferexpansion. That is, it only allocates 128 buffers at initialization and allocates addi-tional segments of 128 buffers as demand requires.

The buffer size and the maximum number of buffers (BUFFLEN and BUFFMAXN)can be specified in the NetView Access Services APPL control statement. Forfurther information refer to “APPL Control Statement” on page 68, and to theBUFFLEN and BUFFMAXN operands in the list following Figure 18 on page 68.

BUFFLEN: The size of the data part of the buffers must be equal to the requestunit (RU) size or the average message size used for the terminal LUs in your envi-ronment. You can get this information from the VTAM logmode-entry definitions foryour terminal LUs or from VTAM traces.


A buffer that is smaller than the received data RU requires additional VTAM receiveoperations in NetView Access Services. This increases the CPU load. If thebuffers are larger than the average data sent to the terminal or the application, youwaste virtual storage space in your system and the paging rate might increaseunnecessarily.

It should be noted that the buffer header, which is 16 bytes long, is also included inthe size for the buffer. Refer to “Using NetView Access Services Buffers” onpage 209 for additional information.

BUFFMAXN: The amount of storage to be used for the NetView Access Servicesbuffer pool can be limited with the maximum number of buffers parameter. Youcan monitor the buffer usage periodically using the DISPLAY STATISTICS operatorcommand to determine a more appropriate value for BUFFMAXN. If the requirednumber of buffers exceeds the specified maximum value, NetView Access Servicesrejects further logons and terminates the functions that need the buffers. Messageswritten to the MVS/ESA operator console indicate the buffer shortage.

Suppressing NetView Access Services MessagesNetView Access Services provides some information messages (message type I,see Figure 29 on page 105) that help in auditing, for example, when an applicationsession is created or terminated. The messages are written to the SYSPRINT dataset. If these messages are not required at your installation, you can suppress theinformation messages by specifying MSGLEVEL=ERROR in the NetView AccessServices APPL control statement in the input parameter data set.

Alternatively, you can suppress all individual messages by specifying WTO=NO andLOG=NO in the message table. This saves the processing required to write themessages and decreases the I/O activities for NetView Access Services. Forfurther information refer to Figure 18 on page 68.

Total Number of Users and Application SessionsThe system load caused by NetView Access Services depends on the number ofsessions and the number of transactions to be processed. You can control thesystem load by specifying:

� The maximum number of terminal sessions in the MAXLUNO parameter of theSERVRTN control statement. Refer to “SERVRTN Control Statement” onpage 70.

� The Maximum Sessions value for an application. Refer to NetView AccessServices Version 2 Administration.

If the MAXLUNO parameter is changed in the input parameters, the new valuebecomes active at the next startup of NetView Access Services. If the MaximumSessions value for an application is changed on the system administrator panel, thenew value becomes active immediately. This value can be used to do some loadbalancing for NetView Access Services, the application, or both.


Using the TERMQ Operator Command for Load BalancingThe TERMQ operator command can be used to put NetView Access Services intoa quiesce mode. NetView Access Services does not accept further logons anddoes not start new sessions with applications in quiesce mode. The current ses-sions continue until they end normally. The RESET operator command can beused to reset the quiesce mode to normal mode and then NetView Access Servicesaccepts logons and starts new application sessions again. For further information,refer to NetView Access Services Version 2 Operation. These two commandsallow the system operator to control the system load.

Access ModesThe administrator can define the access mode used to connect a terminal LU to anapplication: pass mode, relay mode, or both.

In relay mode, the terminal is connected to NetView Access Services and NetViewAccess Services maintains the session to the application. All data received fromthe terminal in relay mode is routed through NetView Access Services. This allowsNetView Access Services to control the data from the terminal and application andprovide the relay mode functions, for example, jump or automatic logon. The addi-tional processing to be done by NetView Access Services in relay mode mightimpact your system performance.

In pass mode the terminal is connected directly to the application after selection.NetView Access Services is not involved in the data transfer from the terminal tothe application. However, the NetView Access Services relay mode functions arenot available to the user in pass mode. The pass mode sessions do not requireadditional VTAM sends or receives. In addition, they require less storage forNetView Access Services control blocks and work areas. But you must considerthe security and usability aspects as described in “Pass Mode Application SessionConsiderations” on page 9, if you plan to use pass mode sessions in your environ-ment.

The system administrator can change the access mode for an application for loadbalancing or resource optimization during the day. If the system administratorchanges the access mode from relay mode to pass mode, all future sessionrequests for that application are in pass mode. The existing relay sessions remainactive until they are deactivated by the user, or canceled by the operator.

Graphic Display SessionsThe display of graphics on 3270-type terminals might contain large data streamsincluding the programmed symbol sets. The graphic data and programmed symbolset data must be saved by NetView Access Services to enable the data to be sentto the terminal after reselection (jump or escape). Additional buffer space may berequired by NetView Access Services for graphic display sessions. You shouldalso consider using pass mode sessions for applications that use a high volume ofgraphic displays.

Chapter 6. General Considerations 45

Data CompressionThe system administrator can specify whether outbound-only data compression, full(outbound and inbound) data compression, or no data compression is to be usedby NetView Access Services. NetView Access Services panels are always sent tothe terminal in compressed format. If the virtual terminal function is used, the effi-ciency of data compression can be greatly improved because a more efficient datacompression algorithm is used. NetView Access Services compares the datareceived from the application with the content of the virtual terminal buffer. Onlythe data that has changed is sent.

Use of the data compression feature increases the NetView Access Services CPUconsumption. The CPU resource requirement for data compression variesdepending on the type of data stream sent to or from the applications, and thenumber of concurrent sessions existing with the application. The benefit of datacompression is that less data is sent, which results in a decreased buffer trans-mission time for that data. It is, however, the responsibility of the administrator todetermine the optimum balance between increased CPU usage and decreasedtransmission time. For further information refer to NetView Access ServicesVersion 2 Administration.

Outbound-Only CompressionIf outbound-only data compression is specified, NetView Access Services com-presses the data received from an application before the data is sent to a terminal.Data entered on a terminal, and sent via NetView Access Services to an applica-tion, is not compressed. This is shown in Figure 15.

Figure 15. Outbound-Only Data Compression via NetView Access Services. The applica-tion can be configured for Virtual Terminal, but this is not a prerequisite for outbound-onlycompression.

Outbound and Inbound Data CompressionIf full (outbound and inbound) data compression is used, NetView Access Servicescompresses the outbound data as previously described, that is, only the changeddata is sent. In addition, NetView Access Services removes all MDT-bits (ModifiedData Tag) from the field definitions sent to the real device. This reduces theinbound data because only the data entered is sent to NetView Access Services.


NetView Access Services then adds the data from all other fields and sends it tothe application. Virtual Terminal option Y is a prerequisite for inbound com-pression, and is should be used for applications that send their input field defi-nitions with an MDT bit set to ON. Figure 16 shows outbound and inbound datacompression.

ApplicationNetViewAccessServices

1 =

2 =

Data stream without MDT-bits and compressedby outbound compression algorithm.

Inbound data with actually entered data.

Figure 16. Outbound and Inbound (Full) Data Compression via NetView Access Services. The application must be configured for Virtual Terminal. Full data compression is possibleonly when Virtual Terminal option Y is specified.

Using BIND User DataNetView Access Services enables you to send BIND user data with the sessionrequest. The BIND user data can be used by an application as logon data, forexample, a user ID. This can save some logon dialogs with the application andtherefore improve the logon processing. For further information refer to NetViewAccess Services Version 2 Administration.

Automatic Logon ProceduresYou can record your own logon and logoff sequences for applications. Therecorded data is stored in the EMSALLT profile data set. The processing of theautomatic logon is mainly simulating dialogs for an application on behalf of theuser. Long dialog sequences require a large amount of processing. Therefore, it isrecommended to use the automatic logon function only for the logon. To set up theuser environment, the subsystem facilities such as the TSO START CLIST or thePROFILE EXEC in VM/CMS should be used.

Instead of using NetView Access Services automatic logon and logoff profiles, aREXX exec can be used to automate automatic logon to and logoff from an appli-cation. For further information, refer to Part 4, “NetView Access Services REXXApplication Programming Interface” on page 213.

Chapter 6. General Considerations 47


Part 2. Customization

This part documents Product-Sensitive Programming Interface and AssociatedGuidance Information. It provides information for customizing NetView Access Ser-vices, and also describes how to customize NetView Access Services to interfacewith RACF and other NetView products.

Before you start customizing NetView Access Services, you must plan together withthe administrators. This involves deciding on the number of users that will useNetView Access Services, the terminals that they will use, the applications they willhave access to, the type of authorization, the type of group, as well as other cri-teria. For details about the criteria affecting administration see NetView AccessServices Version 2 Administration. In addition, NetView Access Services requiresa number of VTAM APPL definitions for applications and terminals. One APPLdefinition is required for the main Access Method Control Block (ACB) for NetViewAccess Services. In addition, for relay sessions, APPL statements for variousACBs must be defined. The number and the associated names are taken from theplanning information.



Chapter 7. Migration Considerations

The following are the considerations for migrating from NetView Access ServicesVersion 1 to NetView Access Services Version 2.

Logon ProfilesMigration of logon profiles (EMSALLT) between NetView Access Services

| Version 2 and NetView Access Services Version 1 is not necessary. Release 1.1| of NetView Access Services Version 2 can run with logon profiles recorded in the

following NetView Access Services Version 1 releases:

| � NetView Access Services Version 2 Release 1.1| � NetView Access Services Version 2 Release 1.0

� NetView Access Services Version 1 Release 3.2� NetView Access Services Version 1 Release 3.1� NetView Access Services Version 1 Release 3.0.

VSAM Data SetsThe record length of the VSAM EMSSRTG data set was increased from 128 bytesto 168 bytes for NetView Access Services Version 1 Release 3.0.

To use the existing VSAM data sets from a previous release of NetView AccessServices Version 1 in NetView Access Services Version 2, job EMSVSAM1 is pro-vided to allocate the VSAM data sets. NetView Access Services job EMSVSAM2then automatically copies the existing VSAM clusters and automatically migratesthem to the needs of the current release. This is described in “Allocating and Ini-tializing VSAM Profile Data Sets” on page 66.

| Profiles migrated to Release 1.1 of NetView Access Services Version 2 can still be| used with:

| � NetView Access Services Version 2 Release 1.1| � NetView Access Services Version 2 Release 1.0

� NetView Access Services Version 1 Release 3.2� NetView Access Services Version 1 Release 3.1� NetView Access Services Version 1 Release 3.0.

Installation-Wide Exit RoutinesThe parameter lists for the following installation-wide exit routines were extended orchanged for NetView Access Services Version 1 Release 3.1:

� “EMSEBXML, Broadcast Exit”� “EMSELGNX, Logon Authorization Exit”� “EMSELNEX, Language Name Exit”� “EMSEPRPS, Printer Presetting Exit”� “EMSESEEX, Session Establishment Exit.”

No changes were made to the parameter lists for NetView Access ServicesVersion 1 Release 3.2.


The parameter lists for the following installation-wide exit routines have beenextended or changed for Release 1.0 of NetView Access Services Version 2:

� “EMSEADEX, Administration Exit” on page 132� “EMSEAPAN, Automatic Logon and Logoff Exit” on page 141� “EMSELGNX, Logon Authorization Exit” on page 154� “EMSELVEX, Language Verification Exit” on page 164� “EMSENPME, Accounting Exit” on page 165� “EMSESEEX, Session Establishment Exit” on page 171.

The EMSEACEX, Attribute Character Exit is no longer required for NetView AccessServices Version 2.

The following new installation-wide exits are provided by Release 1.0 of NetViewAccess Services Version 2:

� “EMSEATTE, Inactivity Timeout Exit” on page 143� “EMSEDVEX, Data Viewing Exit” on page 149.

| The parameter lists for the following installation-wide exit routine have been| extended or changed for Release 1.1 of NetView Access Services Version 2:

| � “EMSELGNX, Logon Authorization Exit” on page 154.

For further information, refer to Chapter 13, “Customizing NetView Access ServicesInstallation-Wide Exits” on page 129. It is the system administrator’s responsibilityto check the installation-wide exit routines to see if the existing installation-wideexits need updating.

NetView Access Services Supplied Command ListsTwo new NetView command lists (CLISTs) were provided by NetView Access Ser-vices Version 1 Release 3.1:

� “NAREFRSH” � “NAMENU”.

It is the system administrator’s responsibility to check the CLISTs to see if theexisting CLISTs need updating.

For information on NetView CLISTs, refer to NetView Access Services Version 2Operation.

Primary and Auxiliary Storage RequirementsRelease 1.0 of NetView Access Services Version 2 requires increased primarystorage for programs and dynamically created control blocks.

Release 1.0 of NetView Access Services Version 2 does not require any more aux-iliary storage than NetView Access Services Version 1 Release 3.2, NetViewAccess Services Version 1 Release 3.1, or NetView Access Services Version 1Release 3.0.

For further information on primary storage requirements, refer to “Primary VirtualStorage Used by NetView Access Services” on page 55.


Buffer SizeThe minimum buffer size was changed from 768 bytes to 1024 bytes for NetViewAccess Services Version 1 Release 3.1. No change in minimum buffer size wasmade for NetView Access Services Version 1 Release 3.0 or Release 3.2.

| The minimum buffer size for Release 1.1 of NetView Access Services Version 2 is| 1024 bytes.

For further information on buffer size refer to “APPL Control Statement” on page 68and the BUFFLEN operand in the list that follows Figure 18 on page 68.

It is the responsibility of the system administrator to determine if this change hasany impact on the operating environment.

Panel MigrationNetView Access Services Version 2 provides the means of specifying the fore-ground color and highlighting of any attribute position (for example, input field ortext area) on a NetView Access Services panel.

An optional migration job and REXX execs are provided to migrate NetView AccessServices Version 1 panels that have been modified. These REXX execs convertexisting panel highlight attribute characters to the same character, and generateSETTATR, SETACTIV, and DEFINE statements for default foreground color andhighlighting of the panels. These can be changed to suit your own requirements.This is valid for all additional languages you install. For further information, refer to“Migrating NetView Access Services Panels” on page 95.

Note: The EMSEACEX, Attribute Character Exit is no longer required for NetViewAccess Services Version 2.

The panel migration job only migrates NetView Access Services Version 1 panelsto the new color definitions. Panels with new fields for NetView Access ServicesVersion 2 must be manually updated. A message is issued for each panel withadditional fields. Refer to “Using the Migration Tool” on page 96.

For information on changing foreground color and highlighting on NetView AccessServices Version 2 panels, refer to “Specifying the Foreground Color and High-lighting on Panels” on page 94.

Chapter 7. Migration Considerations 53


Chapter 8. Preparing to Customize NetView Access Services

This chapter provides information on the storage requirements for NetView AccessServices.

Primary Virtual Storage Used by NetView Access ServicesThe amount of storage required by NetView Access Services depends on specifica-tions in the input parameter (INPARM) data set, and that entered by the MVS oper-ator at startup time. The region size must be specified using the OS/VS EXECREGION parameter.

Static StorageNetView Access Services requires approximately 1.3MB (where MB equals1 048 576 bytes) of virtual storage for executable code in the MVS private storagearea. For each language approximately 244KB (where KB equals 1 024 bytes) arerequired for panels, and 54KB are required for a message table.

Dynamic StorageApproximately 9.6KB are required for control blocks for each VT terminal sessionwith NetView Access Services.

Approximately 11.6KB (including two buffers of 1 024 bytes each) are required foreach application session with Virtual Terminal configured.

296 bytes are required for control blocks for each application of a user who haslogged on to NetView Access Services.

208 bytes plus the length of the message text are required for each selectivebroadcast message, and 48 bytes are required for each 936 bytes of the messagetext and the length in bytes of the message text itself. An additional 64 bytes arerequired for a time-controlled message.

24 bytes are required for each message assigned to a user.

A minimum of 28.3KB are required for each running REXX exec, plus a minimum ofeach nested REXX exec.

All storage required for the working set and buffers is located above the 16MB line.

Storage RequirementsThere is no exact formula that can be used to estimate the real storage require-ment for NetView Access Services. This is because the working set size is envi-ronment dependent. For example, some of the factors that affect the working setsize are transaction rate, logon and logoff activity, and user behavior patterns, suchas frequency of switching between sessions.


CSA and SQA Storage RequirementsNetView Access Services itself does not require storage in the CSA or ECSAcommon area. VTAM uses ECSA on NetView Access Services behalf.

If RACF is used, a RACF ACEE is built in the logon authorization exit(EMSELGNX) for each user logon with an authorized user ID and password. TheRACF ACEEs are saved in the subpool 255 key 0 of the system queue area (SQA)and may reside above the 16MB line.

The size of the ACEE is 144 bytes + length of the variable data. The format of theACEE is documented in Systems Programming Library: Resource Access ControlFacility (RACF).

Calculating NetView Access Services StorageNetView Access Services allocates working storage for about 128 sessions atstartup time, even if you specify fewer sessions. The working sets are dynamicallyextended as required by additional session requests.

The storage used for buffers depends on the definition of the BUFFLEN andBUFFMAXN keywords in your input parameter data set for NetView Access Ser-vices. Refer to “APPL Control Statement” on page 68.

Example of Calculating the Primary Storage RequiredThe example here shows you how to estimate the storage required by NetViewAccess Services. The following assumptions are made for this example:

� NetView Access Services is installed with one language.

� Five hundred users are active at a given time.

� Each user uses three applications concurrently using UNIQUE ACBs.

� Five applications are defined for each user.

� Buffer length of 1024 bytes.

� Ten time-controlled messages each of 936 bytes are assigned to 500 users.


Table 2. Calculation of Primary Storage

Item Description Calculation Bytes

Program storage Size of all modules| 1 425 ððð

Language storage Size of panels + size of

message table

| 251 4ðð

| + 54 72ð

| 32ð ððð

Storage for terminal

sessions

Number of active users x 9 868 5ðð x 9 868 4 934 ððð

Storage for virtual terminal

configured application

sessions

Number of active applications x

number of users x 11 832

3 x 5ðð x 11 832 17 748 ððð

Storage for applications

available

Number of applications x number

of users x 296

5 x 5ðð x 296 74ð ððð

Storage for broadcast

message assigned to users

Number of users x number of

messages x 24

5ðð x 1ð x 24 12ð ððð

Storage for broadcast

messages

Number of messages x 1 256 1ð x 1 256 12 56ð

Total storage 25 214 752

For this example you should specify REGION=25M in your startup job for NetViewAccess Services.

Note: If the administration functions are used heavily, you may need to increasethe storage. If you are using RACF and keeping an ACEE for each active user,then this requires storage from the SQA. For details, refer to Systems Program-ming Library: Resource Access Control Facility (RACF).

Auxiliary Storage Required for NetView Access ServicesNetView Access Services requires the following auxiliary (disk) storage for VSAMuser profiles and for the panel library:

� Approximately 1.5KB for the profiles created for each registered user. Thisdepends on the number of applications and groups defined for the user.

� Approximately 2KB for each recorded automatic logon sequence.

� Approximately 0.3KB for each data stream that goes with a session request.

� An average of 2KB for the parameter input data set.

� Approximately 522KB for each panel library.

� 208 bytes are required for the message criteria of each time-controlledmessage plus 984 bytes for each message text panel.

Panel Library Storage: For details of the minimum disk space requirements fordistribution libraries when installing NetView Access Services, refer to the ProgramDirectory.

Chapter 8. Preparing to Customize NetView Access Services 57

Example of Calculating the Auxiliary Storage RequiredThe following example shows how to calculate the disk space required for theVSAM profile data sets. These figures give an indication of the requirements forthe VSAM part of the cluster in bytes. You must also add appropriate storagespace for the index. The following assumptions are made for this estimate:

� Twenty applications have been defined to the system.� Two groups, Group A and Group B, are defined.� There are 200 users defined in Normal groups.� Each user has access to twelve applications:

– Seven applications in Group A– Five applications in Group B.

� BIND user data has been defined for ten applications.� Two system administrators have been defined.� Four group administrators have been defined (two for each group).� Twenty automatic logon profiles will be recorded.� Five time-controlled selective broadcast messages consisting of:

– Two messages with one message text panel– Three messages with two message text panels.

You obtain this information (the number of applications, groups, and users) from theadministrators who do the planning, as described in NetView Access ServicesVersion 2 Administration.

Calculation of Disk Storage:

� User Profiles EMSSRTU

A user profile entry requires 256 bytes. There is an entry for each applicationdefined for each user. The applications can be in more than one group. Youshould add a contingency factor for further enhancements, for example, newusers. Only users that are defined to Normal groups require space inEMSSRTU:

2ðð users x 12 applications for each user = 24ðð EMSSRTU entries

24ðð x 256 = 614.4KB

+ 1ð% contingency 61.4KB

Total = 675.8KB

� Group Application Profiles EMSSRTG

A group application profile entry requires 168 bytes. There is an entry for eachapplication defined for each group. You should add a contingency factor forfurther enhancements (for example, additional applications or groups):

7 applications in Group A + 5 applications in Group B

12 x 168 = 2.ð2KB

+ 1ð% contingency ð.22KB

Total = 2.22KB


� Group Profiles EMSGPRF

A group profile entry requires 96 bytes. There is an entry for each definedgroup. You should add a contingency factor for further enhancements (forexample, additional groups). Total number of two groups:

2 x 96 = 192 bytes

+ 1ðð% contingency 192 bytes

Total = 384 bytes

This value should be rounded up to 1KB.

� System Application Profile EMSSRTS

A system application profile entry requires 96 bytes. There is an entry for eachdefined system application. You should add a contingency factor for furtherenhancements, for example, additional applications. Total number of 20system applications:

2ð x 96 = 1.92KB

+ 1ðð% contingency 1.92KB

Total = 3.84KB

� BIND User Data Profile EMSPLDT

A BIND user data profile entry requires 320 bytes. There can be one entry foreach defined system application. You should add a contingency factor forfurther enhancements (for example, additional BIND user data). Total numberof 10 BIND user data definitions:

1ð x 32ð = 3.2ðKB

+ 1ðð% contingency 3.2ðKB

Total = 6.4ðKB

� Administrator Access List Profile EMSGAL

An administrator access list profile entry requires 64 bytes. There is an entryfor each defined system or group administrator. You should add a contingencyfactor for further enhancements (for example, additional administrators). Totalnumber of six administrators:

6 x 64 = 384 bytes

+ 1ðð% contingency 384 bytes

Total = 768 bytes

� Automatic Logon Profile EMSALLT

An automatic logon profile entry requires about 2KB per recorded logonsequence. You should add a contingency factor for further enhancements (forexample, additional logon recordings, alternative sequence recordings, or logoffrecordings). Total number of 20 logon recordings:

2ð x 2KB = 4ðKB

+ 1ðð% contingency 4ðKB

Total = 8ðKB

Chapter 8. Preparing to Customize NetView Access Services 59

� Time-controlled messages EMSBROD

Each time-controlled message requires 208 bytes for the message criteria. 984bytes are additionally required for each message text panel. You should add acontingency factor for further enhancements (for example, additional broadcastmessages:

5 x 2ð8 + 2 x 984 + 3 x 2 x 984 = 8.912KB

+ 1ðð% contingency 8.912KB

Total = 17.824KB

This can be rounded up to 18KB.

Therefore the total auxiliary storage required for this example (rounded up) is:

The following storage is required for the NetView Access Services clusters:

Table 3. Total Auxiliary Storage

Profile Storage Requirements

EMSSRTU 675.800KB

EMSSRTG 2.220KB

EMSGPRF 0.380KB

EMSSRTS 3.840KB

EMSPLDT 6.400KB

EMSGAL 0.770KB

EMSALLT 80.000KB

EMSBROD 17.824KB

Total 787.990KB Rounded up= 800.000KB

Table 4. Storage Requirements for NetView Access Services VSAM Clusters

Data Set NameorLibrary Name

Type DSORG Keys RecordSize

NumberofRecords

EMSSRTS EU VSAM (8,6) (96,96) 100

EMSSRTG EU VSAM (16,6) (168,168) 500

EMSSRTU EU VSAM (24,6) (256,256) 500

EMSPLDT EU VSAM (8,6) (320,320) 500

EMSGPRF EU VSAM (8,6) (96,96) 500

EMSALLT EU VSAM (30,6) (64,2120) 1000

EMSGAL EU VSAM (16,6) (64,64) 500

EMSBROD EU VSAM (8,38) (208,984) 1000


Chapter 9. Customizing NetView Access Services after BaseInstallation

| The complete installation of NetView Access Services is divided into two phases:

| � Phase 1: Base installation

| � Phase 2: Customization

| Phase 1 is described in the Program Directory. Once the base installation is com-| pleted, you can customize NetView Access Services to suit your own environment.

Phase 2 uses the NetView Access Services customization tool, NVAS-CTOOL.The following describes the customization steps.

Step 1: Generating the Customization Jobs| Job EMSCGEN (placed in data set ems.v2r1m1.INSTLIB by job EMSBGEN during

base installation) uses the NVAS-CTOOL EXEC EMSCUST and parameter data| members EMSPARMB and EMSPARMC, also located in the ems.v2r1m1.INSTLIB| data set to generate a number of customization jobs and parameter data members.| These are then stored in the ems.v2r1m1.CUSTJOBS data set.

Worksheets with the IBM default parameters for parameter data membersEMSPARMB and EMSPARMC are provided in Appendix C, “CustomizationWorksheets” on page 325. For future reference, enter your values as required inthe worksheets. The values are used as input values when EXEC EMSCUST isrun.

Syntax Rules for Data Members EMSPARMB and EMSPARMC

Take into consideration the following when updating the parameter datamembers EMSPARMB and EMSPARMC:

� Ensure that balanced quotes are used when specifying values. If a valuecontains single quotes within the value, the whole value must be containedwithin double quotes.

� Ensure that a semicolon follows each value.� You can insert comments after the semicolon.� Comment lines can be inserted, but /* must be specified at the start of each

comment.� If you delete a parameter, the NVAS-CTOOL uses default values where

possible.

1. Before you submit job EMSCGEN:

a. Substitute the parameter values in parameter member EMSPARMB to suityour requirements. For example, change the following parameter values, ifnecessary:


CUSTACCTCUSTPGRNCUSTUIDJOBCLSJOBMCLSJOBOUTC

Parameters in Job EMSPARMB

DRYRUNThis specifies whether the installation jobs are to be generated orwhether parameter checking only is to be carried out.

BASEINSTThis specifies whether the base installation phase 1 is to be carried out.

INSTACCTThis is the job account number for all installation jobs submitted.

INSTPGRNThis is the name of the installer for the job statements.

INSTUIDThis specifies the user ID of the installer performing the installation.

CUSTACCTThis is the job account number for all customization jobs submitted.

CUSTPGRNThis is the name of the customizer for the job statements.

CUSTUIDThis specifies the user ID of the customizer performing thecustomization.

JOBCLSThis is the class for all jobs submitted.

JOBMCLSThis is the message class for all jobs submitted.

JOBOUTCThis is the output class for all jobs executed during installation ofNetView Access Services.

Note: For some jobs, you must verify that all the expected messageshave been issued. It is easier to do this if your output is machine-readable. This means that whatever you specified in the EMSJOBCmacro is used as the default MSGCLASS. If you did not specify anMSGCLASS, then the system default is used.

JOBPREFThis is the user ID prefixed to the names of the generated jobs.

NLSINSTThis specifies whether an additional language is to be installed.

NVASHLQThis is the high-level qualifier for NetView Access Services.


SMSThis indicates if the System Managed Storage (SMS) is active on thesystem.

TUNITThis is the tape unit device type onto which the distribution tape isunloaded during installation.

b. Substitute the parameter values in parameter data member EMSPARMC tosuit your requirements.

Parameters in Job EMSPARMC

DRYRUNThis specifies whether the customization jobs are to be generated orwhether parameter checking only is to be carried out.

VSAMHLQThis is the high-level qualifier of the CLUSTER name of the VSAM files,which is allocated on the volume specified by the VSAMVOL param-eter.

VSAMVOLThis is the volume serial identifier for the disk that contains the NetViewAccess Services Version 2 VSAM files.

SRCEXITThis is the name of the source library containing the NetView AccessServices installation-wide exits.

SRCMESTBThis is the name of the source library containing the NetView AccessServices message tables.

DUMPDSNThis is the name of the data set to which dumps are to be routed.

ACBLENThis is the length of the ACB name.

ACBNUMThis is the number of ACB names to be automatically generated.

ACBPREFXThis is the fixed prefix for the ACB names.

ACBSUFFXThis is the variable suffix for the ACB names. It can be a decimal orhexadecimal value. If DEC is specified, the suffix numbers generatedare in decimal, starting from the number specified by the ACBSTARTparameter. The suffix numbers are generated in hexadecimal, if HEXis specified for the ACMSUFFX parameter.

ACBSTARTThis specifies the suffix start number for the ACB names to be auto-matically generated.

Note: NetView Access Services may need a large number of ACBs toestablish sessions between pseudo terminals and applications. The ACBsmust be defined in the SYS1.VTAMLST data set (contact the VTAM system

Chapter 9. Customizing NetView Access Services after Base Installation 63

programmer). The last five parameters in EMSPARMC (ACBxxxxx) aresupplied to generate as many ACB definitions (ACBNUM) as you require.You can specify the maximum length of the ACB name as well as the fixedprefix and a variable suffix. The supplied default values result in the defi-nition of 99 ACBs with the names EMSACB01 through EMSACB99.

| 2. Submit job EMSCGEN. The job adapts the skeleton jobs located in the| ems.v2r1m1.INSTLIB data set and adds the customization jobs to the| ems.v2r1m1.CUSTJOBS data set.

The job must complete with a return code <= 3. If the job completes with areturn code of > 3, there are errors in your parameter definitions and nocustomization jobs are generated.

Note: If you want to check the parameters you specify without generating thecustomization jobs, specify DRYRUN = 'YES' in job EMSPARMC.

A dummy invocation of the job is made and the results of the parameter check| are written to a protocol file PROTCUST in the ems.v2r1m1.CUSTJOBS data| set.

Because job EMSCGEN processes both parameter data members EMSPARMBand EMSPARMC, you get a message stating that the DRYRUN parameter isduplicated. This message can be ignored; the value used for DRYRUN isshown in the message that follows.

The following is a list of the data members generated by job EMSCGEN and| located in the ems.v2r1m1.CUSTJOBS data set. Most of the members contain

executable jobs, but some just contain data. For example, EMSINPI contains datato supply input parameters for NetView Access Services startup.

Member Name ExplanationEMSACCPT Job to accept a user modificationEMSALPDS Job to allocate the Broadcast Partitioned data setEMSANCHR Job to change the default number of environmentsEMSAPPL Sample VTAM APPL statements, for NetView Access Services

and for pseudo terminalsEMSBACK1 Job to export a backup copy of VSAM profilesEMSBACK2 Job to import a backup copy of VSAM profilesEMSBLINP Command input for sample batch load programEMSBLOAD Sample batch load programEMSEXIT SMP/E job to receive and apply an installation-wide exit routineEMSINPI Sample input parameter fileEMSMODE Logmode TableEMSMSGTB SMP/E job to receive and apply a message tableEMSCONF Job to switch NetView Access Services to confidential modeEMSPMIGx Control data member for panel color migration from NetView

Access Services Version 1, where x is:1 = English2 = German3 = Kanji

| 4 = Katakana5 = French

EMSPMIGJ Job for panel color migrationEMSPMIGX EXEC for panel color migrationEMSPMIGY EXEC for panel color migrationEMSPROC Sample startup procedure for NetView Access Services


EMSRESTO Job to restore a user modification after apply and receiveEMSSTART Sample startup job for NetView Access ServicesEMSVLOCK Job to enable locking for VSAM profile sharingEMSVSAM1 Job to allocate VSAM profilesEMSVSAM2 Job to initialize VSAM profilesEMSZCMDS ZAP to change a NetView Access Services commandPROTCUST Protocol file containing all customization parameters.

Note: You may have to insert a Mount Tape command into specific jobs,according to your installation.

Step 2: Running the CustomizationThe following describes the jobs supplied to customize NetView Access Services.

| You may not need to run all jobs located in the ems.v2r1m1.CUSTJOBS data set.It is recommended that you read the descriptions in each job and then decidewhether you need to run the job or not. For example, if you are installing NetViewAccess Services for the very first time, you need to run jobs EMSVSAM1 andEMSVSAM2. However, if you are installing NetView Access Services Version 2and have an already running NetView Access Services Version 1 system, you donot need to run these jobs because you can use your existing VSAM profiles withNetView Access Services Version 2.

If a customization job completes abnormally, analyze the messages produced in thejob log list. Correct the error, and rerun the job. Do not run the next job until theprevious job has completed successfully.

Making Backup Copies of Existing VSAM ProfilesIf you already have a previous release of NetView Access Services installed andyou want to use already existing profiles, you can use your normal backup proce-dures or you can use the EMSBACK1 job to make a backup copy of these profiles.You can use EMSBACK2 to reinstall your saved VSAM profiles. Note that it is notpossible to run these jobs while NetView Access Services is running and using thesame VSAM profiles.

EMSBACK1Job EMSBACK1 exports the VSAM profiles to a temporary file on tape.

1. Submit the job.

2. When this job completes successfully with a condition code of 0, the VSAMprofiles are exported on tape.

EMSBACK2Job EMSBACK2 imports the VSAM profiles from a temporary file on tape. Run thisjob as follows:

1. Modify the values shown in lowercase in the job as required for your localenvironment:

� The VOL value volser in the PROC statement

� Replace the prefix ems.temp in each DD statement with the prefix for thetemporary VSAM data sets

� Replace the values ems.source in each of the IDCAMS IMPORT com-mands with the names of the VSAM data sets that are to be copied.


2. Submit the job.

When this job completes successfully with a condition code of 0, the VSAM datasets are imported from tape.

Allocating and Initializing VSAM Profile Data Sets

EMSVSAM1Job EMSVSAM1 allocates VSAM profiles. Run this job as follows:

1. If you want to delete existing VSAM profiles, remove the comment characters /*and */ from the DELETE statements.

2. Submit the job.

When the job completes successfully with a condition code of 0, the VSAM profiledata sets are allocated.

EMSVSAM2Job EMSVSAM2 is used to copy NetView Access Services VSAM profile data setsonto the allocated VSAM profiles.

1. Submit the job.

2. When this job completes successfully with a condition code of 0, the input datahas been copied into the VSAM profile data sets.

Allocating the Input Parameter and Broadcast Data Sets

EMSALPDSJob EMSALPDS is used to allocate the NetView Access Services input parameter

| library (ems.v2r1m1.INPARM) and copies the sample member EMSINPI into theallocated library. The job also allocates the Broadcast partitioned data set.

1. Submit the job.

| 2. When this job completes successfully with a condition code of 0, the sample| member from ems.v2r1m1.CUSTJOBS has been copied into the NetView| Access Services input parameter library ems.v2r1m1.INPARM and the NetView

Access Services Broadcast partitioned data set has been allocated.

Preparing the NetView Access Services Control StatementsNetView Access Services has two control statements, APPL and SERVRTN.Prepare these as described in the following. There is a sample member, called

| EMSINPI, contained in the ems.v2r1m1.CUSTJOBS data set.

Control Statement Format

The format of the control statements is:

Format of Control Statements

┌ ┐─,─────────────55──statement_name─ ───

6┴parameter=value ─────────────────────────────────────5%

Figure 17. Format of Control Statement


Each statement consists of a statement name and one or more parameters. Eachparameter has an associated value.

All parameter values are either names or numbers. All names follow the sameconventions as specified for symbols in the 370 assembler. They must begin witha letter (A-Z), or @, #, or $, and successive characters can be alphanumeric.Name values are not enclosed in quotes. All numbers are decimal integers con-sisting of a sequence of digits (0-9).

The following describes the precise rules for writing the control statements:

1. The statements can be specified in any order.

2. Each statement begins with the statement name (for example, APPL) and canbegin in any column.

3. Any number of blanks can follow the statement name preceding the firstparameter.

4. No blanks can be included in a parameter specification. For example,ACBNAME=AAAAA is correct, while ACBNAME = AAAAA results in an error.

5. A parameter value followed by a blank indicates the end of the statement.

6. The parameters of a statement are separated only by commas. Except for thelast parameter, a comma must immediately follow the parameter value. Forexample,

ACBNAME=AAAAA,PASSWORD=BBBBB is correct, while

ACBNAME=AAAAA ,PASSWORD=BBBBB terminates processing of the state-ment because the blank immediately following the parameter value AAAAAsignals the end of the statement.

7. A comma followed by a blank signals the end of the line and that anotherparameter is expected on the next line that is not a comment line (see rule 10).

8. A parameter cannot span more than one line, that is, a parameter and associ-ated value must be written in the same line.

9. The parameters of a statement can be written in any order.

10. Comment lines can be specified by coding an asterisk (*) in column 1. Also acomment (called remark) can be written on a line following a parameter valueand at least one blank. See rules 5 and 7. So processing stops at the blankand the comment is ignored (as far as processing is concerned).

Note: If a remark begins with a comma, a warning is written to the output dataset reminding you that parameters can only be separated by a comma (see theexample in rule 6).

11. Restrictions:

The APPL statement can be specified only once.

The SERVRTN statement can be specified up to nine times.

Each parameter can be specified only once in each statement, with the excep-tion of the parameters INPLU and DEFMODEN, which can be specified asoften as required.


Syntax NotationThe syntax notation used to define the control statement format is described inAppendix A, “Reading the Syntax Diagrams” on page 303.

APPL Control StatementThis must be the same as the ACBNAME in the VTAM APPL statement.

This statement is used to specify NetView Access Services parameters that do notapply to a specific NetView Access Services application service routine (ASR).Figure 18 shows the default values and number of characters that can be entered.

APPL Control Statement

55──APPL─ ──ACBNAME=acb_name ──┬ ┬──────────────────── ─────────────────────────5└ ┘──,PASSWORD=password

5─ ──┬ ┬───────────────────────── ──┬ ┬───────────────────── ────────────────────5 │ │┌ ┐─ððððððð─ │ │┌ ┐─1ð24─ └ ┘──,BUFFMAXN= ──┴ ┴─n─────── └ ┘──,BUFFLEN= ──┴ ┴─n────

5─ ──┬ ┬───────────────────────────────────── ──┬ ┬────────────────────── ───────5| └ ┘──,DIRLOGON=(LU_name, ──┬ ┬──────────── │ │┌ ┐─ðððð─| └ ┘──Def_Group) └ ┘──,IDLETIME= ──┴ ┴─n────

5─ ──┬ ┬───────────────────── ──┬ ┬───────────────────── ────────────────────────5 │ │┌ ┐─YES─ │ │┌ ┐─YES─ └ ┘──,RCONNECT= ──┴ ┴─NO── └ ┘──,SIMLOGON= ──┴ ┴─NO──

5─ ──┬ ┬─────────────────────── ──┬ ┬──────────────────── ──────────────────────5% │ │┌ ┐─ERROR─ │ │┌ ┐─11─ └ ┘──,MSGLEVEL= ──┴ ┴─ALL─── └ ┘──,ROUTCODE= ──┴ ┴─n──

Figure 18. Syntax of the APPL Control Statement

ACBNAMEThe name of the VTAM ACB for NetView Access Services. This must be thesame as the ACBNAME for NetView Access Services as an application PLU inthe APPL statement of your VTAM system (refer to “Defining the VTAM APPLStatements” on page 72) and according to the VTAM naming conventions.

PASSWORDThe VTAM password for the NetView Access Services application. This param-eter is optional, and must be the same as the PRTCT value, if specified, in theVTAM APPL statement for NetView Access Services (described in “Defining theVTAM APPL Statements” on page 72).

BUFFMAXNThe maximum number of data buffers that can be allocated by NetView AccessServices. Normally a lower number of buffers is allocated during initialization.If NetView Access Services needs more buffers than already allocated, it usesthe macro GETMAIN to allocate new buffer space until the maximum number ofbuffers is reached. The default, zero, represents no maximum, that is, no limit.

BUFFLENThe length of each buffer (between 1024 and 4096). Whatever you specify isrounded up to a multiple of 256. The length of the buffers affects the perform-ance of NetView Access Services and the storage requirements. If the buffersare too small, NetView Access Services must do more chaining of buffers. Ifthe buffers are too large, space is wasted. A reasonable compromise is thedefault, 1024 bytes. This does not waste too much space and normally onlyrequires one buffer for an average-size panel of data. For further information,


refer to “Resource Usage” on page 43, and “Using NetView Access ServicesBuffers” on page 209.

| DIRLOGON| The list of LU names or LU name patterns for which the Application Selection| panel must be displayed directly, and the associated default group.

| When a terminal connects to NetView Access Services via a VTAM logon, and| the terminal LU name matches a DIRLOGON specification, the logon process| proceeds without the logon panel being displayed. If the EMSELGNX logon| exit allows the logon to proceed, the first panel the user at the terminal will see| is the NetView Access Services Application Selection Panel.

| The following rules apply:

| 1. The DIRLOGON is an optional parameter in the APPL NetView Access| Services initialization statement.

| 2. The DIRLOGON parameter can be repeated as many times as needed, up| to 99999.

| 3. The LU_name value (required) is a 1- to 8-character string. It can be either| a specific or a generic name. A generic LU name is a string containing an| asterisk. If an asterisk is specified, it must be the last character. If only an| asterisk is specified, then all the LUs connecting to NetView Access Ser-| vices will match the pattern.

| 4. The Def_Group value is optional. If specified, it is passed to the| EMSELGNX logon exit in the LGNXGRID field, otherwise this field is set to| blank.

| 5. All the LU names of every DIRLOGON parameter are stored alphanumer-| ically (alphabetic character first, then numeric digits, asterisk last). The first| match found following this order determines which default group ID will be| used, if any is specified.

| 6. Duplicate LU_name values are not allowed.

IDLETIMEThe maximum time interval between two key strokes arriving in NetViewAccess Services on a terminal session. If this interval is exceeded, NetViewAccess Services terminates the particular terminal session.

The format of this field is: hhmm, where hh is hours and ranges from 00 to 23,and mm is minutes and ranges from 00 to 59. The default value of 0000 indi-cates that no idle-time checking is performed.

RCONNECTSpecifies whether, after the user has ended a pass-mode session, the terminalis reconnected with the NetView Access Services Application Selection paneldisplayed (RCONNECT=YES). If you specify RCONNECT=NO, the NetViewAccess Services Logon panel is displayed and the user must enter a user IDand password to be reconnected to NetView Access Services. This parameteris used only when SIMLOGON=YES.

SIMLOGONSpecifies whether, after the user has ended a pass mode session, the terminalis logged back on to NetView Access Services (SIMLOGON=YES). If youspecify SIMLOGON=NO, the terminal is connected to VTAM, which then dic-


tates what happens. SIMLOGON=YES must be specified for the RCONNECTparameter to take effect.

MSGLEVELSpecifies whether or not all runtime information messages are to be put to theconsole and SYSPRINT file.

If you specify MSGLEVEL=ALL, the information messages are generated aswell as the error messages. If you specify MSGLEVEL=ERROR, only the errormessages are generated. Information messages are identified by I, error mes-sages are identified by any other character.

ROUTCODESpecifies the routing code to be assigned to the WTO message. Further infor-mation is available in the MVS/ESA Application Development Macro Reference.

SERVRTN Control StatementThis statement is used to specify parameters related to a specific applicationservice routine (ASR) of NetView Access Services. The ASR can be the ASR EndUser Services (EMSEUS) supplied by NetView Access Services, or a user-writtenASR. Refer to Chapter 14, “Writing New Application Service Routines” onpage 183 for more information about ASRs. Figure 19 shows the default valuesand the number of characters that can be entered.

SERVRTN Control Statement

┌ ┐─,MAXLUNO=99999───────55──SERVRTN─ ──NAME=name, ──,LMODNAME=name ──┼ ┼────────────────────── ──────────5 └ ┘──,MAXLUNO= ──┬ ┬─99999─ └ ┘─n─────

┌ ┐─,────────────────────────────────────────────5─ ───

6┴──INPLU= ─(─LU_name ──┬ ┬───────────────────── ─)─ ────────────────────────5

└ ┘ ─,logmode_entry_name─

┌ ┐─,────────────────────────────────────── │ │┌ ┐─,DEFMODEN=\────────────────────────5─ ───

6┴──┼ ┼──────────────────────────────────── ─────────────────────────────5%

└ ┘──,DEFMODEN= ──┬ ┬─\────────────────── └ ┘─logmode_entry_name─

Figure 19. Syntax of the SERVRTN Control Statement

NAMEA unique name for the ASR.

LMODNAMEThe load module name of the ASR. This module is loaded in storage when thesubtask for this ASR is attached. The ASR supplied by NetView Access Ser-vices is EMSEUS (End User Services).

MAXLUNOThe maximum number of terminal LUs that can be connected to the ASR. Themaximum number is 99999.

INPLUAssigns a terminal to the ASR. This parameter can be specified up to 99999times. The value of this parameter consists of two parts enclosed in brackets:


LU_nameA specific or a generic name of an LU that can log on to NetView AccessServices. This must be specified.

In a generic name an asterisk (*) represents one or more characters; one* represents all terminals. If, for example, you want to allow all LUsstarting with I4 to be connected to the ASR, you must specify I4*. If youspecify an *, it must be the last character of a name value, according tothe VTAM naming convention.

logmode_entry_nameThe name of an entry in a logmode table. This value is optional. You canuse it to further define the association of an LU to a specific ASR. An *represents all logmode table entry names. If logmode_entry_name is notspecified, the value of the DEFMODEN parameter is used. If you specifyan *, it must be the last character of a name value, according to the VTAMnaming convention.

The LU_name values of every INPLU parameter of every SERVRTN statementare ordered alphanumerically (alphabetic character first, numerical characternext, and asterisk last). If the LU_name of a terminal that logs on matches aspecified LU_name value of an INPLU parameter, only those INPLU parame-ters that have the same LU_name value are checked for matching logmode-entry-name values. That is, the logmode entry name of the terminal that logson and the logmode entry name in the INPLU are compared. The logmodeentry name values of the INPLU parameters are also ordered alphanumerically.

The terminal is connected to the ASR whose INPLU parameter matches firstwith the terminal LU name and the terminal logmode_entry_name.

You may also utilize RACF to verify whether a terminal is authorized to log onto NetView Access Services. Any unauthorized terminal receives an errormessage.

To specify values for INPLU that support terminal name verification only,specify the terminal names or a generic name in the INPLU operand for all LUsthat can validly access an ASR, but you need not specify anylogmode_entry_name. If only logmode verification is required, specifyINPLU=(*,logmode_entry_name) for all logmode entries that can validly accessthe ASR. If neither terminal name nor logmode verification are used, specifyINPLU=(*,*). This means that all terminals can be connected to the ASR.

If there is no match for the incoming LU_name and logmode_entry_name, thenthe terminal logon is rejected.

DEFMODENAssigns the name of the logmode table entry that is used if logmode-entry-name is not specified for the INPLU parameter.

This parameter can be specified as often as necessary. The value ofDEFMODEN can be a generic name.

Defining the Logmode Table and VTAM APPL Statements| Sample VTAM definitions are included in the ems.v2r1m1.CUSTJOBS data set.

1. Installing the Logmode Table

The logmode table defines session protocols for devices and applications.NetView Access Services supplies its own logmode table, EMSMODE.


Install the NetView Access Services logmode table as described in the VTAMResource Definition Reference. Use member EMSMODE as input. For detailsabout how NetView Access Services uses the EMSMODE logmode table, see“Logmode Considerations” on page 16.

EMSMODE need not be defined in the LU statements for the terminals con-nected to NetView Access Services. There is no need to change your existingVTAM definitions for NetView Access Services. Only the VTAM APPL defi-nitions for pseudo terminals in relay mode must contain the name of theNetView Access Services logmode table. Refer to “APPL Statements for Eachof the Pseudo Terminal SLUs” on page 73.

2. Defining the VTAM APPL Statements

You must define VTAM APPL statements for:

� NetView Access Services (main ACB)

� Pseudo terminals in relay mode sessions with subsystems (for example,CICS or IMS) and VTAM applications in accordance with NetView AccessServices option 4, Define an Application for the System on the ApplicationSelection panel. For additional information, refer to NetView Access Ser-vices Version 2 Administration.

| The member EMSAPPL in data set ems.v2r1m1.CUSTJOBS contains a sampleset of VTAM APPL definitions for the NetView Access Services VTAM APPLstatement, and the APPL statements required for each pseudo terminal.

3. VTAM APPL Statement for NetView Access Services

This VTAM minor node definition represents NetView Access Services as anapplication PLU within the SNA network. During the logon process, NetViewAccess Services is the PLU for all terminals (secondary logical units or SLUs)communicating through NetView Access Services with one or more VTAMapplications. A sample VTAM APPL statement for the NetView Access Ser-vices main ACB is shown in Figure 20. The following operands must bedefined for this APPL statement:

ACBNAMEA name of your choice for NetView Access Services as a VTAM application.The (minor node) name of the APPL statement (on the left in Figure 20) isvalid in your whole network, while the ACBNAME value is known only in thedomain. The same name must be used for both.

PRTCTIf you define a password, it must be the same as that specified in the PASS-WORD parameter of the APPL control statement. Refer also to “APPLControl Statement” on page 68 and the PASSWORD operand that followsFigure 18 on page 68.

AUTH(ACQ,PASS,NVPACE) must be specified.

You can also use VPACE instead of NVPACE in the VTAM APPL statementto suit your requirements.

EMSYASð1 APPL ACBNAME=EMSYASð1,PRTCT=SECRET,AUTH=(ACQ,PASS,NVPACE)

Figure 20. Example of a VTAM APPL Statement for NetView Access Services


4. APPL Statements for Each of the Pseudo Terminal SLUs

NetView Access Services uses a pseudo terminal name to access relay-modeapplications on the user’s behalf. “The NetView Access Services Pseudo Ter-minal Concept” on page 4 contains further information on handling pseudo ter-minals. A sample VTAM APPL statement for a pseudo terminal SLU is shownin Figure 21. The following operands must be defined for each of these APPLstatements:

ACBNAMEThe name of the pseudo terminal SLU. For example, for the pseudo ter-minal prefix IMSACB and a maximum sessions value of 99, you must defineall names from IMSACB01 to IMSACB99.

The (minor node) name of the APPL statement (on the left in Figure 20) isvalid in your whole network. The ACBNAME value is known only in thedomain. It is recommended that the same name be used for both.

MODETABSpecify EMSMODE, or the name used in your installation for the NetViewAccess Services logmode table.

EAS=1For ACBs of type Unique.

EAS=10For ACBs of type Individual.

PARSESS=YESFor ACBs of type Shared and Individual.

The PRTCT parameter need not be specified.

EMSYACS1 APPL ACBNAME=EMSYACS1,MODETAB=EMSMODE,PARSESS=YES

Figure 21. Example of a VTAM APPL Statement for a Pseudo Terminal SLU

A sample set of VTAM APPL definitions that could be placed in a separatemajor node is available in member EMSAPPL in the SEMSAMP0 data set.

Note: Physical-unit and LU definitions are not required. The pseudo terminalsdo not exist physically.

Check the total number of APPL definitions so that you do not exceed theMAXAPPL value in your system generation. The MAXAPPL value must begreater than or equal to the sum of the number of APPL statements requiredfor NetView Access Services (that is, the number of system applications plusthe number of pseudo terminals), together with your already existing APPL defi-nitions.

Further information on defining NetView Access Services to VTAM, both in asingle domain and multidomain, can be found in VTAM Resource DefinitionReference.

Shared ACB and Individual ACB Restrictions :

When using Shared ACBs you must specify PARSESS=YES in the VTAM APPLstatement. Otherwise sessions might fail with a sense code of X'08090000'(mode inconsistency) set by VTAM. You might also need to specify


PARSESS=YES for the applications that these Shared ACBs are used for,depending on the needs of the applications.

If you plan to use Shared or Individual ACBs, you must consider the followingrestrictions:

� Neither Shared nor Individual ACBs can be used for sessions to applicationsthat pass the session to a third party after data has been sent in the session.This refers to both BIND user data and normal session data.

For example, an application may perform a logon dialog and then pass thesession to the next application. In this case the first session is unbound byVTAM and a new session with the third party is created. There is no sessioncorrelation information available. If NetView Access Services detects that asession cannot be correlated, it rejects the new session request and terminatesthe first session. An error message is written to indicate the correlationproblem.

The information as to whether an application passes a session or not can befound in the appropriate application documentation.

For NetView Access Services, this might occur if you have a Shared ACB relaymode session from one NetView Access Services to another NetView AccessServices and this session is passed to an application by the second NetViewAccess Services. If, for example, a user selects a second NetView AccessServices in relay mode from the NetView Access Services the user is initiallylogged on to, and within the second NetView Access Services selects asession to an application in pass mode.

� Shared ACBs must not be used for sessions from one NetView Access Ser-vices to another NetView Access Services if the target NetView Access Ser-vices allows the selection of pass mode applications. Unique ACB definitionsshould be used for such sessions.

� CICS must not request a VTAM ACQUIRE for NetView Access Services sharedor individual ACBs from the LUNT queue. For information on LUNT queues,refer to NetView Access Services Version 2 Administration.

Therefore, you must not code the following CICS TCT parameters with the fol-lowing values for these LUs:

AUTOCONNECT = YES

CONNECT = AUTO

� CICS and TSO must be restricted from acquiring a shared or individual ACBfrom the LUNT queue after recovering from error situations, because theseACBs might already be used for new sessions with applications. For informa-tion on LUNT queues, refer to NetView Access Services Version 2 Adminis-tration.


Step 3: Verifying the Installation of the Batch Load Program

EMSBLOADJob EMSBLOAD executes the NetView Access Services Batch Load and Reporting

| Facility. The member EMSBLINP on the library ems.v2r1m1.CUSTJOBS is used| as the command input file. The command input file is specified with the

EMSBCOMM DD statement in the Batch Load job.

1. Submit the job.

2. When the job completes successfully with a condition code of 0, the installationof the Batch Load program is verified.

The list and report output created by this job can be used as an example.

Step 4: Modifying EUSZAP Flag-Bit Area for Sharing VSAM Profiles(Optional)

EMSVLOCKJob EMSVLOCK is used to modify the EUSZAP flag-bit area. The job is optional.Refer to “Sharing VSAM Data Sets” on page 22 for a detailed description of theEUSZAP flag-bit area.

1. Submit the job.

2. When the job completes successfully with a condition code of 0, the EUSZAPflag-bit area has been modified. Any change to the EUSZAP flag-bit arearequires a restart of NetView Access Services.

Note: If a module has had a usermod applied to it and the module is subsequentlymodified by a PTF, then the original usermod must be redone specifying that PTFas a prerequisite or a supplement, for example:

| ++VER(Zð38) FMID(HNVS111)

| would become

| ++VER(Zð38) FMID(HNVS111) PRE(xxxxxx)

where xxxxxx is the number of the PTF.

EMSRESTOTo revoke the usermod, run job EMSRESTO and restart NetView Access Services.


Step 5: Switching to Confidential Mode (Optional)

EMSCONFUnlike NetView Access Services Version 1, NetView Access Services Version 2runs in semiconfidential mode as default. If, for security reasons, your installationrequires NetView Access Services to be run in confidential mode, job EMSCONFmust be run and NetView Access Services must be restarted. Any authorizedperson can submit job EMSCONF to switch NetView Access Services from semi-confidential mode into confidential mode.

EMSRESTOTo enable diagnostic traces to be taken, if required, NetView Access Services mustbe switched from semiconfidential mode into nonconfidential mode using theTRACE=CONF operator command.

If job EMSCONF has been run to switch NetView Access Services into confidentialmode, you must run job EMSRESTO to switch NetView Access Services into semi-confidential mode.

Submit job EMSRESTO, and restart NetView Access Services.

For further information on taking diagnostic traces, refer to NetView Access Ser-vices Version 2 Operation.


Chapter 10. Customizing NetView Access Services for YourEnvironment

This chapter provides information for customizing NetView Access Services to yourown environment.

Enabling the Generic Alert Interface to NetViewIf NetView Access Services terminates abnormally, it can send alerts to NetViewusing the NetView Generic Alert interface. An alert is sent as a Network Manage-ment Vector Transport (NMVT). NMVTs are displayed on NetView’s hardwaremonitor panels and stored in NetView’s hardware monitor log. An NMVT sent byNetView Access Services provides the NetView operator with information about thefailure that caused the abnormal termination. The most important information sentabout NetView Access Services is:

� Version� System abend code� Failing load module� Failing CSECT with offset� PTF level of the failing CSECT� PSW at time of abnormal termination.

To enable this Generic Alert interface provided by NetView Version 1 Release 3,NetView Access Services must load the NetView module CNMNETV. For thismodule to be loaded, NetView Access Services must have access to the NetViewlibrary. This is done by concatenating NetView’s CNMLINK library in the STEPLIBDD statement in the JCL shown in Figure 24 on page 87 as follows:

// DD DSN=SYS1.CNMLINK,DISP=SHR

The library named in the statement must be APF authorized. If you change thedefault library name and the NetView CNMNETV module is not in librarySYS1.CNMLINK, substitute your name for the library that contains CNMNETV.

NetView Access Services issues the message

EMSð236E THE CNMNETV ROUTINE IS NOT AVAILABLE.

if CNMNETV could not be loaded at NetView Access Services initialization time orat the time of an abnormal termination.

Notes:

1. NetView must be set up correctly to receive alerts from NetView Access Ser-vices. For information on setting up NetView to receive alerts, refer to theNetView Installation and Administration Guide.

2. All concatenated libraries in the STEPLIB statements must be APF authorized.


Enabling the NetView Synergy Interface to the NetView PerformanceMonitor

The NetView Synergy Interface (NSI) enables NetView Performance MonitorRelease 4 to manage sessions connected through NetView Access Services. NSIuses cross-memory services for communication between NetView Access Servicesand NPM. The NSI comprises a separate address space with a program andtables, together with an access module as shown in Figure 22.

As MVS cross-memory services are used, NetView Access Services and NPMmust be in the same host.

Figure 22. Network Synergy Interface Overview


The tables that reside in the NSI address space contain all the information aboutthe sessions that has been sent to NSI by NetView Access Services. NetViewAccess Services and NPM access NSI by using the module FNMNSI. When theNSI is enabled, NPM Release 4 can correlate information about sessions between:

� Terminals and NetView Access Services� NetView Access Services and applications

where the application may be located in the same or another domain.

| To enable the NSI provided by NetView Performance Monitor, NetView Access Ser-vices must load the NPM module FNMNSI. To do this, the NPM load modulelibrary SFNMLMD1 containing the FNMNSI module must be concatenated to theSTEPLIB statements in the NetView Access Services startup job EMSSTART. SeeFigure 24 on page 87. The following must be added:

| // DD DSN=npm.inst.SFNMLMD1,DISP=SHR

Note: All concatenated libraries in the STEPLIB statements must be APF author-ized.

NetView Access Services to NSI Communication � Connect

When NetView Access Services is started it tries to load the FNMNSI module.If the FNMNSI module loads, the connection to the NSI is established automat-ically, and the following message is issued:

EMSð4ð8E THE NETVIEW SYNERGY INTERFACE IS ESTABLISHED.

The connect parameter includes the job name of NetView Access Services.

If the module FNMNSI could not be loaded at NetView Access Services startuptime, the following message is issued:

EMSð4ð6E THE FNMNSI ROUTINE IS NOT AVAILABLE.

If the connection to the NSI could not be established, the following message isissued:

EMSð4ð9E THE NSI CONNECTION COULD NOT BE ESTABLISHED RC=xx, REASON=yy.

where xx represents the return code and yy the reason code from the NSImodule FNMNSI.

Note: If a second NetView Access Services is to be started, it is essential thata different job name is used. If the same job name is used, then the NSIregards this as a restart of NetView Access Services and resets all relatedtable entries.

For detailed information about the NSI, the return codes, and the reason codes,refer to NetView Performance Monitor Installation and Customization.

Chapter 10. Customizing NetView Access Services for Your Environment 79

� Send

NetView Access Services sends the information to NPM via the NSI when anyof the following occur:

– A user logs on to NetView Access Services.– A user logs off from NetView Access Services.– A user reconnects to NetView Access Services after returning from a pass-

mode session.– A user jumps from one application to another.– A user selects an active application.– A user escapes from an application to the Application Selection panel.– NetView Access Services establishes a session with an application for a

user in pass or relay mode.– NetView Access Services terminates a relay-mode session for a user.– The selected application has terminated the application session for a user

and has passed the NetView Access Services pseudo terminal to anotherapplication.

The data that is sent from NetView Access Services contains the followinginformation:

– NetView Access Services name– Type of event– User Descriptive Information:

- User ID - Group ID - Account number

– Session Descriptive Information:- Type of Session- Primary LU Name- Secondary LU Name

- Communication ID.

If the sending of information to the NSI failed, the following message is issued:

EMSð412E SENDING EVENT WAS NOT SUCCESSFUL, RC = xx, REASON = yy

where xx represents the return code and yy the reason code from the FNMNSImodule. Messages (EMS0887E) are printed on the SYSPRINT data set, if theTRACE NSI=ON command is set, giving trace information about the completeSend Request that failed.

� Disconnect

When NetView Access Services is shut down, it disconnects from the NSI, andrelated table entries are freed.

If the NSI is not available, or if NetView Access Services disconnects from theNSI because of an NSI return code, NetView Access Services periodicallyretries to connect to the NSI.


Note: The logmode used for the Terminal and Application sessions must be speci-fied with the exclusive use of a ‘Definite Response only’ protocol (no exceptionresponse). To ensure this it may be necessary to update the following logmodetables:

� VTAM supplied table ISTINCLM� NetView Access Services supplied table EMSMODE.

Refer also to “Logmode Entry Analysis” point 2 on page 17 and to NetView Per-formance Monitor Installation and Customization.

Enabling for Secondary AuthenticationNetView Access Services provides an input field on the Logon panel, the Sec-ondary Data field.

NetView Access Services supports magnetic reader operations that work in themode of nonsecure magnetic stripe cards.

Refer to the 3270 Information Display System Data Stream Programmer’s Refer-ence for a detailed description of nonsecure magnetic stripe cards.

The NetView Access Services logon panel is delivered with the Secondary Datafield switched off. This is done by the specification of the field attribute invisibleprotected numeric . To enable NetView Access Services for the Secondary Datafield you must customize the NetView Access Services Logon panel by modifica-tions to the field attribute, for example invisible unprotected alpha . For furtherinformation refer to “Guidelines for Modifying Panels” on page 91.

Figure 23 shows the Logon panel with the Secondary Data field enabled.

Enter Logon Information:

User . . . . . . . (User ID/Logoff)

Password . . . . . New Password . .

Secondary Data . .

Application. . . .

Group. . . . . . .

Location . . . . .

PF 1=Help 2=Lang 12=Logoff

á ñ

Figure 23. Logon Panel Showing the Secondary Data Field

The length of this field can be customized. The default length of this field as it isdelivered is 8 bytes. It can be specified in the NetView Access Services Logonpanel with a length of 1 to 128 bytes. If this field is customized with a lengthgreater than 128 bytes, NetView Access Services truncates all bytes following the128th byte. As the length of the Secondary Data field can conflict with the positionof the following fields, for example the Application field, the appropriate fields mustbe moved to another position.

The contents of the Secondary Data field is passed unchanged to the logon author-ization exit EMSELGNX, that is, there is no uppercase translation. For further infor-mation refer to “EMSELGNX, Logon Authorization Exit” on page 154.


Customizing for Model Terminal SupportModel Terminal Support (MTS) is supported by NetView Access Services. MTSdata received from the terminal is stored in NetView Access Services and, whenestablishing a relay or pass mode session to an application selected from theNetView Access Services Application Selection panel, or from the Location field onthe NetView Access Services Logon panel, this MTS data is passed to the applica-tion. To enable this function for NetView Access Services you must customizeVTAM as follows:

� Define Model Name Tables (MDLTAB) in the SYS1.VTAMLST.� Define Model Name Entries (MDLENT) referenced by your major node state-

ments for your terminals.� If desired, define MDLPLU instructions for these entries.� Define Associated LU Tables (ASLTAB) in the SYS1.VTAMLST.� Define Associated LU Table Entries (ASLENT) referenced by your major node

statements for your terminals to define primary and alternative printers.� If desired, define ASLPLU instructions for these entries.� Define the major node statements for your terminals using the following param-

eters, if desired: – MDLTAB – MDLENT – ASLTAB – ASLENT

Note: If you provide an MDLPLU or ASLPLU statement for an entry, the PLUname is the NetView Access Services Main ACB name.

For further information refer to the VTAM Resource Definition Reference.

To check your printer definitions in NetView Access Services use the followingsequence:

1. Log on to NetView Access Services and select an application.2. Escape to the Application Selection Panel.3. Enter the PRINT command for the previously selected application.4. The print panel is shown to you with primary and alternative printer names as

defined in the ASLENT statement for your terminal.

Customizing NetView Access Services for Public GroupsWhere most users in an installation require access to the same list of applications,and each application is responsible for its own security, then Public groups mightbe of most use. Public groups can also be used to supply a list of remote NetViewAccess Services systems to unrecognized users, so that users can select theirhome NetView Access Services from the list.

Users in Public groups cannot update their access parameters, and group adminis-trators cannot define or update the user-access parameters.


The logon authorization exit EMSELGNX can be used to force a logon in a Publicgroup under certain circumstances. For example, with the sample exit suppliedwith NetView Access Services: when an unrecognized user attempts to log on andno password is specified by the user, a value of PUBGROUP is put into the groupID field. If you have defined PUBGROUP to NetView Access Services as a Publicgroup, then the user is logged on in this group.

For security reasons, ensure that the administrators, including PUBUSER, whichare defined in NetView Access Services, are never unrecognized users. Thismeans that they must be defined in your external security system. If you do notwant unrecognized users to work with Public group applications, change theEMSELGNX exit or select a name other than PUBGROUP for your Public group.

The default application access parameters used for Public groups are shown inTable 5.

Table 5. Default Application Parameters for Public Groups

&PWD Blank

&NPW Blank

&OPW Blank

&UID Logon user ID

&ACCNO Group account number

&GVAR1 Blank

&GVAR2 Blank

&GVAR3 Blank

&GVAR4 Blank

&GVAR5 Blank

&UVAR1 Blank

&UVAR2 Blank

&UVAR3 Blank

&UVAR4 Blank

Default group indicator N

Default server indicator N

Access mode Group access mode

Logon record authorization N

Terminal assume Y

Logon profile Group default logon profile (S/G)

Active logon profile Not applicable

Selection ID Group default selection ID

Jump key Group Default jump key

Shareable Y


Only system-level and group-level automatic logons are allowed in Public groups.Users cannot record their own logons. This also means that administrators cannotrecord system or group logons while working in a Public group. System administra-tors can record system-level recordings while working in an External or Normalgroup. For a group administrator to be able to record a group level logon it is firstnecessary for the system administrator to temporarily change the group type toNormal. The group administrator can then log on and, assuming that recordauthorization is allowed, use the recording commands to record a logon profile.When this is done, the AG command can be used to add the group recording. Thegroup type must then be changed back to Public (by the system administrator).The logon profile to be used (group or system) is set by the group administrator forthe whole group. This is done on the Maintain Group Parameters panel.

Preparing for NetView Access Services StartupTo run NetView Access Services, use the job control (JCL) statements that aredescribed in the following text. The numbers used in the description relate to thenumbers used to identify the JCL statements in the sample job stream shown inFigure 24 on page 87.

Data set ems.v2r1m1.CUSTJOBS contains a sample startup job EMSSTART. Inaddition, the data set contains a startup procedure EMSPROC that you can copyinto your MVS procedure library if you want to start NetView Access Services as astarted task.

.1/ This statement has no special meaning as far as NetView Access Services isconcerned. Any job name that is adequate for the installation is permitted.You can also chose to run NetView Access Services as a started task.

.2/ The provided program name of NetView Access Services must be specified.If the program might exceed the allowable wait time at the installation, andtherefore time out, you must specify TIME=1440 in the EXEC statement. Thisrepresents unlimited wait time.

The REGION size must be large enough to accommodate the NetViewAccess Services buffers, control blocks, and load modules. The REGIONsize is influenced by the REGION parameter in the startup job and by theMVS exits IEFUSI and IEALIMIT.

.3/ This statement specifies the load library containing the NetView Access Ser-vices load modules. Data sets concatenated to the STEPLIB DD statementmust be APF authorized if any of the following are used:

� RACF as a security management system� The NetView Synergy Interface to NetView Performance Monitor

� SDUMP services� The Generic Alert Interface to NetView.

.4/ This statement specifies the concatenated load libraries for the National Lan-guage Features. There is a DD statement for each national language featurelibrary to define this panel library according to the language IDs 1 to 8. Ifusing the supplied installation-wide exits for NetView Access Services, thislibrary must be APF authorized.

If the language is to be active at run time, remove the comment * from theJCL statement.


.5/ This statement concatenates the NetView CNMLINK library enabling NetViewmodule CNMNETV to be loaded for the NetView Generic Alert Interface.Refer to “Enabling the Generic Alert Interface to NetView” on page 77.

.6/ This statement concatenates the NPM load module library SFNMLMD1 toenable the NPM module FNMNSI to be loaded for the NetView Synergy Inter-face. Refer to “Enabling the NetView Synergy Interface to the NetView Per-formance Monitor” on page 78.

.7/ The data set that contains the NetView Access Services panel libraries.EMSPAN1 is the only mandatory DD statement in this list.

.8/ The data set that contains the NetView Access Services panel libraries for theNational Language Features. There is an EMSPANx DD statement for eachadditional language to define this panel library according to the language ID.Where x is the language ID. For example, 5, which is French.

If the language is to be active at run time, remove the comment * from theJCL statement.

Note: Ensure that the sequence of these statements for the different lan-guages matches with the sequence of the languages in the following NetViewAccess Services installation-wide exits:

� “EMSEBXML, Broadcast Exit” on page 145� “EMSEDTEX, Date and Time Exit” on page 147� “EMSELNEX, Language Name Exit” on page 161� “EMSELVEX, Language Verification Exit” on page 164� “EMSEPRPS, Printer Presetting Exit” on page 167.

.9/ The data set that contains the NetView Access Services System profile.

.1ð/ The data set that contains the NetView Access Services Group Applicationprofile.

.11/ The data set that contains the NetView Access Services User profile.

This statement can be omitted if you intend to use NetView Access Servicesgroups of type External or Public.

.12/ The data set that contains the NetView Access Services BIND user data.

.13/ The data set that contains the NetView Access Services Group profile.

.14/ The data set that contains the NetView Access Services Automatic logondata.

.15/ The data set that contains the NetView Access Services Group access list.

.16/ The data set that contains the NetView Access Services Broadcast messagecluster.

.17/ The data set that contains the NetView Access Services Broadcast partitioneddata set. For further information on the NVASAPI, refer to Part 4, “NetViewAccess Services REXX Application Programming Interface” on page 213.

.18/ The data sets that contain the NetView Access Services Bulletin Board infor-mation.

.19/ The data set containing the REXX programs (written using the NVASAPI) tobe loaded.

.2ð/ The default data set to which the output of REXX programs is to be routed.


.21/ The report data set for the listing of messages is the SYSPRINT data set.The attributes of the SYSPRINT data set defined in the system are:

LRECL=133

RECFM=FBA

A block size (BLKSIZE) of 133 is used if no other block size, or a block sizethat is not a multiple of 133, is given.

.22/ The job stream must have a SYSMDUMP DD statement to allow for a dumpto be taken in case of error. This dump is unformatted machine readable andcan be processed by the Interactive Problem Control System (IPCS). Forfurther information, refer to NetView Access Services Version 2 Operation.

.23/ Control statements for NetView Access Services are provided in the inputparameter data set. They are described in “Preparing the NetView AccessServices Control Statements” on page 66.


.1/ //EMSSTART JOB (accounting information),'start up jcl', // CLASS=a,MSGCLASS=a,MSGLEVEL=(1,1) // USER=user_id,NOTIFY=user_id //\ \

//\

.2/ //NVAS EXEC PGM=EMSMAIN,TIME=144ð,REGION=8ðððK

//\-------------------------------------------------------------+

//\ NVAS load module library(es)...: ]

//\-------------------------------------------------------------+

.3/ //STEPLIB DD DSN=ems.v2r1m1.SEMSLMDð,DISP=SHR .4/ //\ DD DSN=ems.v2r1m1.SEMSLMD2,DISP=SHR GERMAN

.4/ //\ DD DSN=ems.v2r1m1.SEMSLMD3,DISP=SHR KANJI

.4/ //\ DD DSN=ems.v2r1m1.SEMSLMD4,DISP=SHR KATAKANA

.4/ //\ DD DSN=ems.v2r1m1.SEMSLMD5,DISP=SHR FRENCH

.5/ //\ DD DSN=SYS1.CNMLINK,DISP=SHR

.6/ //\ DD DSN=npm.v1r4mð.SFNMLMD1,DISP=SHR //\-------------------------------------------------------------+

//\ NVAS panel data set(s)...: ]

//\-------------------------------------------------------------+

.7/ //EMSPAN1 DD DSN=ems.v2r1m1.SEMSPNL1,DISP=SHR .8/ //\ EMSPAN2 DD DSN=ems.v2r1m1.SEMSPNL2,DISP=SHR GERMAN

.8/ //\ EMSPAN3 DD DSN=ems.v2r1m1.SEMSPNL3,DISP=SHR KANJI

.8/ //\ EMSPAN4 DD DSN=ems.v2r1m1.SEMSPNL4,DISP=SHR KATAKANA

.8/ //\ EMSPAN5 DD DSN=ems.v2r1m1.SEMSPNL5,DISP=SHR FRENCH

//\-------------------------------------------------------------+

//\ NVAS VSAM clusters...: ]

//\-------------------------------------------------------------+

.9/ //EMSSRTS DD DSN=ems.v2r1m1.EMSSRTS,DISP=SHR.1ð/ //EMSSRTG DD DSN=ems.v2r1m1.EMSSRTG,DISP=SHR.11/ //EMSSRTU DD DSN=ems.v2r1m1.EMSSRTU,DISP=SHR.12/ //EMSPLDT DD DSN=ems.v2r1m1.EMSPLDT,DISP=SHR.13/ //EMSGPRF DD DSN=ems.v2r1m1.EMSGPRF,DISP=SHR.14/ //EMSALLT DD DSN=ems.v2r1m1.EMSALLT,DISP=SHR.15/ //EMSGAL DD DSN=ems.v2r1m1.EMSGAL,DISP=SHR.16/ //EMSBROD DD DSN=ems.v2r1m1.EMSBROD,DISP=SHR //\-------------------------------------------------------------+

//\ Following are the NVAS partitioned data sets for ]

//\ Broadcast, Bulletin board and REXX execs.....: ]

//\-------------------------------------------------------------+

.17/ //EMSBPDS DD DSN=ems.v2r1m1.SEMSBPDS,DISP=SHR

.18/ //EMSBULL DD DSN=ems.v2r1m1.SEMSBULL,DISP=SHR

.19/ //EMSREXEC DD DSN=ems.v2r1m1.SEMSREXX,DISP=SHR //\-------------------------------------------------------------+

//\ SYSPRINT, dump and parameter input data sets...: ]

//\-------------------------------------------------------------+

.2ð/ //EMSRPRT DD SYSOUT=\

.21/ //SYSPRINT DD SYSOUT=\

.22/ //SYSMDUMP DD DSN=SYS1.DUMPð1,DISP=SHR

.23/ //SYSIN DD DSN=ems.v2r1m1.INPARM(EMSINPI),DISP=SHR//\ (End of NVAS Startup Job)

Figure 24. Sample Job Control Statements



Chapter 11. Modifying NetView Access Services Panels,Messages, and Commands

This chapter describes Product-Sensitive Programming Interfaces and AssociatedGuidance Information.

Modifying panels is part of customizing NetView Access Services. The followingdescribes how to update the wording of panels, so that they reflect your operatingenvironment and procedures. It also describes how to control the highlighting ofpanel text.

The general procedure for modifying a displayed panel is to locate its source panel,type your changes in the source panel, store it, and test it. Once a panel ischanged, you must restart NetView Access Services to refresh the panel.

Locating the Source PanelThe first step in modifying a panel is to determine which source panel controls thepanel you want to change.

A source panel is a member of a data set that defines the contents of the displayedpanel that appears on the user’s screen. A source panel contains the text of thedisplayed panel and definition statements that do not appear on the displayedpanel. Source panels are stored in panel libraries. In the panel library they areidentified by the panel ID.

Because each language uses its own panel library you must ensure that changesmade in one language are reflected in all the languages that you use. You canalso perform your own translations by copying one of the delivered panel data setsin its entirety and translating each member within it.

The NetView Access Services panel IDs are listed on page 93, and the NetViewAccess Services help panels are listed on page 100.

Modifying the Source PanelUse a full screen editor to make your changes to the source panel. The panel canbe of fixed or variable length and of any block size. Records that result in a linelength of greater than 80 bytes can cause unpredictable results.

The key components of a source panel are numbered in Figure 25 and aredescribed in the list following the figure.


/******************************************************************************//* (C) COPYRIGHT IBM CORP. 1987, 1997 *//* LAST CHANGE: 92/11/25 *//* DESCRIPTION: APPLICATION SELECTION PANEL *//* WHERE CALLED: *//* CHANGED ACTIVITY: *//* CHANGE CODE DATE DESCRIPTION *//* ----------- -------- --------------------------------------------------*//* V1R1M1SCROLL Nov 87 Add scrolling PF keys *//* @F8_HZU1200 03/16/89 Application Selection by Cursor Position *//* *//* CODE REASON RLSE DATE ORIGIN COMMENTS *//* -------------------------------------------- *//* $P1= KNA0067 010 920917 SAE: Change attribute for User and Group ID *//* $L5= FPR 010 921027 DET: Field N9 Printer and *//* Field N0 Print Key for *//* Fast Print *//* $P2= KNA0095 010 921125 DET: Change Redefine Keys into Keys *//* *//*******************************************************************************SETATTR + TD GDSETACTIV WD+EMSP01+ +Application Selection+ +Help:+17-6666+ Term: +N3......++Z3 +Date:+N1......+Time: +N2......++Z4 +User:+N7......+Group: +N8......++ +Broadcast:+K1+ Printer:+N9......++Select application or enter command. LOGOFF command terminates all sessions.+Escape key+N4..+ Command key+N5..+and Prefix+N6......+ Print key+N0..+

+ ID Name Status M B Jump Key Application Description+A+Y1++O1......+O6...+O4+O5+ +O2..+ +O3............................++B+Y2++P1......+P6...+P4+P5+ +P2..+ +P3............................++C+Y3++Q1......+Q6...+Q4+Q5+ +Q2..+ +Q3............................++D+Y4++R1......+R6...+R4+R5+ +R2..+ +R3............................++E+Y5++S1......+S6...+S4+S5+ +S2..+ +S3............................++F+Y6++T1......+T6...+T4+T5+ +T2..+ +T3............................++G+Y7++U1......+U6...+U4+U5+ +U2..+ +U3............................++H+Y8++V1......+V6...+V4+V5+ +V2..+ +V3............................++I+Y9++W1......+W6...+W4+W5+ +W2..+ +W3............................++J+YA++X1......+X6...+X8+X9+ +X2..+ +X3............................++K+YF++A2......+XC...+XA+XB+ +X4..+ +X5............................+

+Z1+Z2+COMMAND+==>+A1_______________+ +B1______+ +B2______+ +B3______+PF 1=Help 2=Lang 3=Disc 4=Keys 7=Backw 8=ForwPFKEYS 01=H 02=L 03=D 04=R 05= 06= 07=B 08=F 09= 10= 11= 12=PFKEYS 13=H 14=L 15=D 16=R 17= 18= 19=B 20=F 21= 22= 23= 24=DEFINITION OF LINE HELP, FULL SCREEN HELP AND ERROR MESSAGE NUMBEREXAMPLE : AN=NNNN/XXXX/MMMM

AN = A1,A2,...,B ,C ,...NNNN = MSG LINE NUMBERXXXX = NAME OF FULL SCREEN PANELMMMM = FIELD ERROR NUMBER

HELPNR A1=1410/P011/1207 A2=1411/P012/1399 GH=1410/PL14/1230HELPNR B1=1412/P013/1204 B2=1412/P013/1204 B3=1412/P013/1204HELPNR A =1545/P014/1360 B =1545/P014/1360 C =1545/P014/1360HELPNR D =1545/P014/1360 E =1545/P014/1360 F =1545/P014/1360HELPNR G =1545/P014/1360 H =1545/P014/1360 I =1545/P014/1360HELPNR J =1545/P014/1360 K =1545/P014/1360DEFINE 01/01 BDMDEFINE 01/23 BDNHDEFINE 01/53 TDNDEFINE 01/71 TDNDEFINE 02/01 YDNHDEFINE 02/53 TDNDEFINE 02/71 TDNDEFINE 03/01 YDNHDEFINE 03/53 TDNDEFINE 03/71 TDNDEFINE 04/58 TDNDEFINE 04/71 TDNDEFINE 06/12 TDNHDEFINE 06/31 TDNHDEFINE 06/47 TDNHDEFINE 06/68 TDNHDEFINE 08/01 BDNHDEFINE 09/01 GDMIDEFINE 09/03 BDNHDEFINE 09/07 BDNDEFINE 09/16 BD

1

4

7

8

11

5

6

2

39

10

| Figure 25. Sample Source Panel

.1/ PrologAn optional section for programmer comments. Each line of the prolog beginswith /* in columns 1 and 2.


.2/ Default Foreground Color and Highlighting StatementThe SETATTR and SEACTIV statements that specify the default foregroundcolor and highlighting on the panel when no other foreground color or high-lighting is defined in the DEFINE statement.

.3/ TitleTitle of the panel.

.4/ NamePanel ID of the panel.

.5/ Broadcast Message AreaThe 2 lines of the panel on which NetView Access Services broadcast mes-sages appear. (Application Selection panel only.)

.6/ Message AreaThe 2 lines of the panel on which NetView Access Services messages appearare identified by the field names Z1 and Z2.

.7/ Command LineThe field on the panel in which users type commands has the field name A1.The word COMMAND is at the left of this input field.

.8/ Panel Text24 lines containing text that constitutes the displayed panel.

.9/ General Information AreaThe area of the panel where information such as the date and time are dis-played.

.1ð/ PF Keys and Help Panel DefinitionsThe area of the panel where the PF key and help panel definitions are speci-fied.

.11/ Define StatementsDEFINE statements for foreground color and highlighting of areas of thepanel.

Modifying NetView Access Services PanelsYou can modify all NetView Access Services panels to suit your own requirements.For example, you can change the position of fields on a panel, change the text, andspecify the foreground color and highlighting of any attribute position on the panels.

The NetView Access Services panels are stored in panel libraries.

Guidelines for Modifying PanelsThe following are the guidelines for modifying the panels:

1. The number of fields and the input field identifiers must not be changed.

2. The panel ID must be the same as the member name for this panel in thepanel library data set. The panel ID must be located before the first input fieldand the first protected field on the panel with the MDT bit on.

This can be changed to a protected field, modified if required, which makes thepanel ID invisible.

3. The foreground color and highlighting of any attribute position on a panel, forexample, the message area or input fields can be defined by specifying an attri-

Chapter 11. Modifying NetView Access Services Panels, Messages, and Commands 91

bute character in front of and at the end of the input, output, or text fields. Forfurther information, see “Specifying the Foreground Color and Highlighting onPanels” on page 94.

On a 3178 terminal you can enter only numeric values in a highlighted inputfield.

You can define an input field as a protected invisible field (which effectivelyremoves it from the panel). If you do this with the Command line, only theDISPLAY command can be used. Refer to position 6 in the DEFINE statementshown in Figure 26 on page 95. In addition, the input field identifiers must notbe changed.

4. If the attribute character identifier is required in the text, then it may be speci-fied twice. The first occurrence is put into the panel text. The second isignored by shifting the rest of the line one place to the left. For example, if youhave used the character + as the attribute character and you want to use + intext, then:

this ++thatwould become: this +that

5. The length of a field is fixed as the number of bytes between two attributes.Each field must, therefore, be terminated by one of the attributes for a pro-tected field. Avoid using superfluous attributes on a panel.

6. When you are defining input fields, the attribute character must be immediatelyfollowed by the field name. The field name is the name by which NetViewAccess Services identifies the field. For example, in Figure 25 on page 90,the command field is given the name A1.

7. The number of panel definition lines must always be 24. Comment lines withina panel are not counted as panel lines. Comment lines must start with /* (slashasterisk). No end delimiter is needed.

8. Any free-format text can be inserted after the 24 panel definition lines. There isno need to start these lines with the comment delimiter.

9. Note, at the bottom of Figure 25 on page 90, the example of how Help mes-sages, panels, and error messages are called from each field.

10. Each panel must have lines to define the PF keys for Help or Disc, or to showthe Help messages, the Help panels, or the error messages for the appropriatefield. These lines are specified by certain line headers.

The header for the key definitions line is PFKEYS.

The header for the error, Help, and panel definitions is HELPNR. SeeFigure 25 on page 90 for an example of the format of these lines. It shows anexample of the definition of the Application Selection panel.

The codes to assign functions to PF keys are:

H HelpE EndD DiscF ForwB Backw

L LangU UpdateR KeysQ Logoff


There are no other functions possible. If a function is not permitted for a partic-ular panel, then an information message is issued during EUS startup. Theinvalid function is ignored. You can assign the same function to several PFkeys, or assign a different PF key than the default as distributed in the panellibrary. For example, PF1 and PF13 can both be defined as the Help key. Youcan also change the default PF key assignments that are provided withNetView Access Services. You must ensure that the prompting text displayedon the screen matches the actual PF key functions.

11. The header for attribute definitions is DEFINE.

12. You can define the Command line on the Maintain User Parameters panelEMSPU1 as a protected field. This allows the user to use the Display function(default display when the Enter key is pressed), but not to enter update com-mands.

13. The jump key can be set to blank by the administrator using Option 2 on theAdministration Selection panel. Then there is no jump key available to theuser. To prevent the user defining a jump key, the Jump Key field on the Main-tain User Parameters panel EMSPU1 can be defined as a protected field.

The NetView Access Services panel IDs are as follows:

Panel ID TitleEMSP00 LogonEMSP01 Application SelectionEMSP02 Language Selection

| EMSP03 Compact Application SelectionEMSPA3 Administration Selection (Group Administrator)EMSPA9 Administration Selection (System Administrator)EMSPG1 Maintain Group ParametersEMSPG2 Assign a User to a GroupEMSPL1 List FunctionEMSPL2 List MessagesEMSPL3 Interruptive Broadcast MessageEMSPL4 Broadcast MessageEMSPL7 Broadcast Selectively Message ListEMSPS1 Define an Application for the SystemEMSPS2 Define an AdministratorEMSPS3 Define a GroupEMSPS4 Assign an Application to a GroupEMSPS5 Define BIND Data for ApplicationsEMSPS6 Broadcast a MessageEMSPS7 Broadcast SelectivelyEMSPS8 Generate or Modify a Broadcast MessageEMSPU1 Maintain User ParametersEMSPU2 Redefine KeysEMSPU3 Shared Session RequestEMSPU4 Shared Session ResponseEMSPU5 Printer DestinationEMSPU6 Bulletin Board.


Specifying the Foreground Color and Highlighting on PanelsYou can change or specify the foreground color and highlighting of any area of thepanel, for example, the message area, input fields, text area, and so on. Back-ground colors are not supported on NetView Access Services panels. The fol-lowing foreground colors and highlighting are supported on all NetView AccessServices panels:

Color and highlighting is defined for attribute positions on a NetView Access Ser-vices panel using SETTATR, SETACTIV, and DEFINE statements (see Figure 25on page 90). The SETATTR statement specifies the default foreground color andhighlighting for attribute positions when no DEFINE statement for those attributepositions exist. The SETACTIV statement specifies the foreground color and high-lighting for active output fields.

SETATTR and SETACTIV Statements

The format of the SETATTR and SETACTIV statement is:

ForegroundColor

ExtendedHighlighting

White DefaultYellow ReversevideoGreen UnderlinedRed BlinkingTurquoisePinkBlue

SETATTR + YD TD SETACTIV RD

Where SETATTR + YD TD specifies that:

� A plus sign is used to define the start attribute position of either a protected orunprotected field

� All input fields preceded and followed by a plus sign are yellow with defaulthighlighting

� All output fields (for example, the text area) are turquoise with default high-lighting

and SETACTIV RD specifies that all active output fields are red with default high-lighting. A blank '' must be specified as a delimiter between each subfield.

DEFINE Statement

The DEFINE statement specifies the foreground color and highlighting of any areaof the panel you wish to change the foreground color and highlighting of.

The format of the DEFINE statement is shown in Figure 26 on page 95. A blank'' must be specified as a delimiter between each subfield. If NONE is specified inthe foreground color and highlighting subfield, the values in the SETATTR state-ment are used.

.1/ Defines the extended foreground color.


.2/ Defines the extended highlighting.

.3/ Defines whether the MDT bit is to be enabled.

.4/ Defines whether the field is to be highlighted (base highlighting) ornondisplayable. The definition H has no effect on terminals with ExtendedAttribute Buffer. It is only required if noncolor 3270 terminals are supported inthe installation.

.5/ Defines whether the skip bit of the base attribute is to be enabled.

.6/ Defines that an input field is to be protected invisible.

DEFINE Row/Column XXXXXX

││││││ .6/│││││└────────5 P rotected invisible (input field)

│││││ .5/││││└─────────5 S kip (default)

││││ N oskip

││││ .4/│││└──────────5 N ormal (default)

│││ I nvisible

│││ H ighlighted

│││ .3/││└───────────5 N ot modified (default)

││ M odified (required for panel ID)

││ .2/│└────────────5 D efault

│ R eversevideo

│ U nderscore

│ B link

│ .1/└─────────────5 W hite

B lue

G reen

R ed

T urquoise

Y ellow

P ink

Figure 26. Format of the DEFINE Statement for Color and Highlighting

For example, the statement DEFINE 09/01 WR specifies that the attribute characterat row 9, column 1, is white reverse video. If NONE is specified in the color andhighlighting subfield, then the attribute character at row 9, column 1, has the fore-ground color and highlighting specified in the SETATTR statement.

Migrating NetView Access Services PanelsThe structure of the panels has been changed in NetView Access ServicesVersion 2. The panels delivered with NetView Access Services Version 2 are allbuilt in accordance with the new structure. If you use the delivered panels, nopanel migration is required. If you have modified panels, or created new panels forNetView Access Services Version 1, you must migrate these panels for use withNetView Access Services Version 2. You can do this manually, or use the optionalmigration tool described in the following and change the values to suit your ownrequirements.


If you intend to continue running your NetView Access Services Version 1 system,it is recommended that you make a backup of the NetView Access ServicesVersion 1 panels before migrating to NetView Access Services Version 2.

Using the Migration Tool| To make the panel migration easier, an optional job EMSPMIGJ, located in data set| ems.v2r1m1.CUSTJOBS, is provided. The job executes a REXX exec EMSPMIGX| that uses REXX exec EMSPMIGY and a control data member, located in the| ems.v2r1m1.INSTLIB data set, to migrate modified panels of NetView Access Ser-

vices Version 1 to NetView Access Services Version 2. The migration job onlyconverts the NetView Access Services Version 1 panels to the NetView AccessServices Version 2 layout. It does not imbed any new fields introduced on panelsof NetView Access Services Version 2 into the panels. The new fields must beadded manually. A message is displayed for each panel containing new fields.

| When migrating from Version 2.1.0 to Version 2.1.1, you can copy the old panels to| new libraries. The new fields introduced with Version 2.1.1 must then be added| manually to the panels (EMSPS3 and EMSPS4).

One control data member is provided for each language supported by NetViewAccess Services Version 2. The job EMSPMIGJ must be run for each language tobe migrated, using the control data member for the specific language. The fol-lowing default control data members are provided:

EMSPMIG1 EnglishEMSPMIG2 GermanEMSPMIG3 KanjiEMSPMIG4 KatakanaEMSPMIG5 French

The REXX execs locate any attribute characters used in the NetView Access Ser-vices Version 1 panels, for example, for protected fields and highlighting of text. Alllocated attribute characters are converted to a plus sign (default) and SETATTR,SETACTIV, and DEFINE statements are automatically generated, according to thedefinition in the respective control data member, to specify the default foregroundcolor and highlighting for the panels. After the panels have been converted, youcan modify the DEFINE statements to change the foreground color and highlightingas you wish. For further information, refer to “Specifying the Foreground Color andHighlighting on Panels” on page 94.

To migrate the NetView Access Services Version 1 panels to NetView Access Ser-vices Version 2:

1. Make a backup of the NetView Access Services Version 1 panels if you intendto continue to run your NetView Access Services Version 1 system.

2. Before you submit job EMSPMIGJ:

a. In the ISPSTART CMD line, substitute:

� 'oldpanels dsname' with the data set name containing the panels to bemigrated.

� 'newpanels dsname' with the name of the data set into which thepanels are to be migrated.

� The control data member name EMSPMIG1 with the name of thecontrol data member for the appropriate language.


b. Change the color and highlighting in the appropriate control data memberas required. Alternatively, you can use the control file as is and change thecolor and highlighting later. Figure 27 on page 98 shows a sample controldata member.

3. Submit the job EMSPMIGJ.

a. When the job completes with return code of zero the panels have beenmigrated. If a NetView Access Services Version 2 panel contains newfields, the following message is displayed:

| Member pppppppp contains new fields. NVAS might not start.| Manual update is required. RC = 8.

No message is displayed for updated NetView Access Services Version 2Help panels. These must be checked for changes and additional informa-tion.

b. Add the new fields to the appropriate panel, and manually create theDEFINE statements as required. Alternatively, you can use the deliveredNetView Access Services Version 2 panel and modify it and the DEFINEstatements as you wish.

Sample Control Data MemberThe control data member is used to convert the NetView Access Services Version1 Release 3.x panels to the NetView Access Services Version 2 panel structure. Asample of a NetView Access Services Version 2 panel is shown in Figure 25 onpage 90. One control data member is provided for each language supported byNetView Access Services. The individual parameters such as color, highlighting,and field attribute indicator can be changed as required. The individual subfieldsare delimited by a blank. A sample control data member is shown in Figure 27 onpage 98.

The control data member is divided into two major parts:

.1/ General Settings.

This specifies the keyword, defines the default foreground colors and high-lighting for input and output fields, and the character used as the attribute indi-cator. The keyword must not be changed.

Keyword DescriptionFIELDAT One byte, defining the character used as the attribute indicator.DEFCOLI Two bytes, defining the default extended foreground color and

highlighting of input fields. Refer to the DEFINE statement inFigure 26 on page 95.

DEFCOLO Two bytes, defining the default extended foreground color andhighlighting of output fields.

.2/ Individual Settings.

These are divided into three areas:

� Convert from Version 1 Release 3.x panels� Convert to Version 2 panels

� Comment.

The NetView Access Services Version 1 Release 3.x panels are searched for thehexadecimal values in the convert from block .a/. If a match is found, a DEFINEstatement is generated for the NetView Access Services Version 2 panels with the


character string in the convert to block .b/. The statement NONE indicates that thedefault setting is to be used for either the input field or output field. The commentblock .c/ describes the NetView Access Services Version 1 panel attribute charac-ters.

.1/┌───────┬────────────────5 Keyword. Do not change

│ │

│ │┌──┬────────────5 Default attribute indicator and default

│ ││ │ foreground color and highlighting

│ ││ │

FIELDAT + /\ Indicator for a field attribute position \/

DEFCOLI GU /\ Default color for input fields is green, underscore \/

DEFCOLO TD /\ Default color for output fields is turquoise \/

DEFACTV PD /\ Default color for active fields is pink \/

.2/ 5ð TD /\ & : Unprotected, normal = No extended colors \/

4F TD /\ | : Unprotected, numeric = No extended colors \/

7B WUNH /\ # : Unprotected, highlight = White + Underscore \/

A1 WUNH /\ ˜ : Unpr. numeric highlight = White + Underscore \/

4E NONE /\ + : Protected, numeric = No extended color \/

6C YDNH /\ % : Prot num highlight skip = Yellow \/

7C BDNI /\ @ : Unprot. nondisplay = Blue + Underscore invisib \/

5B BDNI /\ $ : Prot, num nondisp = Blue default highlight \/

79 BDM /\ ` : Prot, num nondisp MDT = Blue, default highlight \/

5F GDMI /\ ¬ : Unp, nondisp, MDT = Green, default \/

Eð RDNH /\ \ : Prot, highlight = Red, default \/

6A TDNNN /\ : Protected, no skip = Turquoise default \/

│ ││ ││ │

│ ││ ││ │

│ ││ ││ │

└─┬─┘└──┬───┘└──┬──────────────────────────────────────────────────────┘

│ │ │ .c/│ │ └────────5 Comment (Version 1 values)

│ │

│ │

│ │

│ │

│ │

│ │ .b/│ └────────────────5 Version 2 (Convert to)

│ Translates character string representing

│ color and highlighting in the DEFINE

│ statement of the converted panel.

│ Refer to page 94.

│

│

│ .a/ └──────────────────────5 Version 1.3 (Convert from)

Hexadecimal representation of Version 1.3.xcontrol characters. The control character is

replaced by the translated string when

migrating the panels to Version 2.

Figure 27. Sample Control Data Member


Defining a NetView Access Services Help PanelYou can define a Help panel using the following guidelines:

1. The panel ID must be specified on row 1, column 2, of every panel, and mustbe the same as the member name for this panel in the panel library data set.

2. An attribute character in row 1, column 1, for a protected, modified field mustbe specified immediately preceding the panel ID. That makes the panel IDinvisible.

3. You should only use the protected-field attribute characters for the definition ofa Help panel. On these panels there are no input fields.

4. There are two kinds of Help panels:

� General Help panel.

This panel should be a general help description that is displayed if the userpresses the Help key for the second time with the cursor on an input fieldfor which no special panel has been described. This panel is also shown ifthe user enters the HELP command on the command line or if the userpresses the Help key when the cursor is outside any input field.

� Special Help panel.

This panel type contains a special input field description for the field onwhich the cursor was positioned when the user pressed the Help key forthe second time.

5. There is no PFKEY-define line and no HELPNR line used on the Help panels.

6. The panels must have 24 lines.

7. The Help panel name is formed by taking the four characters specified in theHELPNR line of the NetView Access Services panel, and prefixing them withthe letters EMSH.

8. You cannot specify more than 1024 Help panels for each language.

9. You can change or specify the foreground color or highlighting of any area ofthe help panel. For further information, refer to “Specifying the ForegroundColor and Highlighting on Panels” on page 94.

Figure 28 shows an example of the definition of the general Help panel for theMaintain User Parameters panel.


à ð/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/

| /\ (C) COPYRIGHT IBM CORP. 1987, 1997 \/

/\ LAST CHANGE: ð9/14/93 \/

/\ DESCRIPTION: Maintain user parameters help \/

/\ WHERE CALLED: EMSPU1 from the command line \/

/\ CHANGED ACTIVITY: \/

/\ CHANGE CODE DATE DESCRIPTION \/

/\ ----------- -------- --------------------------------------------------\/

/\ \/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

SETATTR + GD BD

+EMSHPU11+ +Maintain User Parameters HELP+

Use the “Maintain User Parameters” panel to enter values for parameters that

control your work with NetView Access Services. For example, you can set

the+Jump Key+or define the logon profile to be used. To get help on a field,

move the cursor to the field and press the help key.

You can issue the following commands from the command line:

+Display+ Displays the current user parameters of an application.

(or+D+) To do this, fill in the Application field and enter+D+.

+Update+ Changes the current user parameters of an application.

(or+U+) To do this, fill in the Application field and enter+U+.

Use the+Display+command to display data that you want

to change.

+List+ Lists the applications you can use in this group.

(or+L+) Enter+L+. A panel is displayed showing the applications you

can use.

Press ENTER to return

DEFINE ð1/ð1 BDMI

DEFINE ð1/24 YD

DEFINE ð6/ð5 WD

DEFINE 11/ð1 WD

DEFINE 12/ð5 WD

DEFINE 12/66 WD

DEFINE 14/ð1 WD

DEFINE 15/ð5 WD

DEFINE 15/66 WD

DEFINE 16/22 WD

DEFINE 19/ð1 WD

DEFINE 2ð/ð5 WD

DEFINE 2ð/2ð WD

á ñ

Figure 28. Example of a Help Panel Definition

The following is a list of the NetView Access Services help panels.

Help Panel DescriptionEMSHP001 NetView Access Services Logon (Help for New, Application,

Location, and Group fields).EMSHP002 NetView Access Services Logon (Help for User and Password

fields).EMSHP003 NetView Access Services Logon (Help for Secondary

Authentication Data field). You can create your own text for thispanel depending on whether you use the field or not.

EMSHP011 Application Selection (General help).EMSHP012 Application Selection (Help for F field).EMSHP013 Application Selection (Help for command field variables).EMSHP014 Application Selection (Help for application selection by cursor

position).EMSHP021 Language Selection (General help).

| EMSHP031 Application Selection (General help).


EMSHPA31 Administration Selection (General help, Group Administrator).EMSHPA91 Administration Selection (General help, System Administrator).EMSHPA94 Define a Group (Help for Admin Exit Data fields).EMSHPG1A Maintain Group Parameters (Help for Color field).EMSHPG1B Maintain Group Parameters (Help for Highlight field).EMSHPG1C Maintain Group Parameters (Help for Text field).EMSHPG2A Assign a User to a Group (Help for Shareable field).EMSHPG11 Maintain Group Parameters (General help).EMSHPG12 Maintain Group Parameters (Help for Jump Key field).EMSHPG13 Maintain Group Parameters (Help for Group, Application, and

Application Description fields).EMSHPG14 Maintain Group Parameters (Help for Logon Profile Type and

Automatic Logon fields).EMSHPG15 Maintain Group Parameters (Help for Message Received Indicator

field).EMSHPG16 Maintain Group Parameters (Help for Default Selection ID field).EMSHPG17 Maintain Group Parameters (Help for Application ID Display field).EMSHPG18 Maintain Group Parameters (Help for Row field).EMSHPG19 Maintain Group Parameters (Help for Column field).EMSHPG21 Assign a User to a Group (General help).EMSHPG22 Assign a User to a Group (Help for User and Group fields).EMSHPG23 Assign a User to a Group (Help for Application field).EMSHPG24 Assign a User to a Group (Help for Default Group field).EMSHPG25 Assign a User to a Group (Help for Access Mode field).EMSHPG26 Assign a User to a Group (Help for Record Authorization and Ter-

minal Assume fields).EMSHPG27 Assign a User to a Group (Help for Logon Variables fields).EMSHPG28 Assign a User to a Group (Help for Pseudo Terminal Name field).EMSHPG29 Assign a User to a Group, and Define an Administrator (Help for

Admin Exit Data fields).EMSHPL14 General Help (General help when cursor is not on any input field).EMSHPS1A Define an Application for the System (Help for Shareable fields).EMSHPS1B Define an Application for the System (Help for Status Update

fields).EMSHPS3A Define a Group (Help for Printer field). You must customize this

help panel to provide the user with a list of the available printersand their location.

EMSHPS3B Define a Group (Help for Logon REXX Exec field).EMSHPS3C Define a Group (Help for Print Key field).EMSHPS3D Define a Group (Help for Logoff REXX Exec field).

| EMSHPS3E Define a Group (Help for ASP Format).| EMSHPS4A Assign an Application to a Group (Help for VTAM Logmode).

EMSHPS11 Define an Application for the System (General help).EMSHPS12 Define an Application for the System (Help for ACB Type field).EMSHPS13 Define an Application for the System (Help for Access Mode

field).EMSHPS14 Define an Application for the System (Help for System-Internal

Name field).EMSHPS15 Define an Application for the System (Help for Primary LU Name

field).EMSHPS16 Define an Application for the System (Help for Automatic Logon

and Alternative Sequences fields).EMSHPS17 Define an Application for the System (Help for Pseudo Terminal

Prefix field).


EMSHPS18 Define an Application for the System (Help for Idle Time Valuefield).

EMSHPS19 Define an Application for the System (Help for TPN of ASR field).EMSHPS21 Define an Administrator (General help).EMSHPS22 Define an Administrator (Help for User and Group fields).EMSHPS23 Define an Administrator (Help for Type field).EMSHPS31 Define a Group (General help).EMSHPS32 Define a Group (Help for Escape key field).EMSHPS33 Define a Group (Help for Command key and Prefix fields).EMSHPS34 Define a Group (Help for Account Number, Number of Sessions,

and Multiterminal Access fields).EMSHPS35 Define a Group (Help for Screen Copy Keys fields).EMSHPS36 Define a Group (Help for Group field).EMSHPS37 Define an Application for the System (Help for Maximum Ses-

sions field).EMSHPS38 Define a Group (Help for Group Type field).EMSHPS39 Define a Group (Help for Shared Session Response field).EMSHPS41 Assign an Application to a Group (General help).EMSHPS42 Assign an Application to a Group (Help for Group and Application

fields).EMSHPS43 Assign an Application to a Group (Help for System-Internal Name

field).EMSHPS44 Assign an Application to a Group (Help for Access Mode field).EMSHPS45 Assign an Application to a Group (Help for Data Compression

field).EMSHPS46 Assign an Application to a Group (Help for Shareable field).EMSHPS47 Assign an Application to a Group (Help for Virtual Terminal field).EMSHPS48 Assign an Application to a Group (Help for Logon REXX Exec

field).EMSHPS49 Assign an Application to a Group (Help for Logoff REXX Exec

field).EMSHPS51 Define BIND User Data for Applications (General help).EMSHPS52 Define BIND User Data for Applications (Help for System-Internal

Name field).EMSHPS53 Define BIND User Data for Applications (Help for BIND User Data

fields).EMSHPS61 Broadcast a Message (General help).EMSHPS71 Broadcast Selectively (General help).EMSHPS72 Broadcast Selectively (Help for Message ID and Language ID

fields).EMSHPS73 Broadcast Selectively (Help for Member Name field).EMSHPS74 Broadcast Selectively (Help for User ID and Group fields).EMSHPS75 Broadcast Selectively (Help for Terminal ID field).EMSHPS76 Broadcast Selectively (Help for System Application Name and

Group Application Name fields).EMSHPS77 Broadcast Selectively (Help for Interruptive Message field).EMSHPS78 Broadcast Selectively (Help for Time Controlled Message,

Start/End Broadcasting, and Purge fields).EMSHPS81 Generate or Modify Message Text (General help).EMSHPS82 Generate or Modify Message Text (General help).EMSHPU11 Maintain User Parameters (General help).EMSHPU12 Maintain User Parameters (Help for Application and Jump Key

fields).


EMSHPU13 Maintain User Parameters (Help for Variables for Logon Profilesfields).

EMSHPU14 Maintain User Parameters (Help for Selection ID and DefaultApplication fields).

EMSHPU15 Maintain User Parameters (Help for Logon Profile fields).EMSHPU16 Maintain User Parameters (Help for Message Received Indication

field).EMSHPU17 Maintain User Parameters (Help for Application ID Display field).EMSHPU21 Redefine Keys (General help).EMSHPU22 Redefine Keys (Help for Escape Key field).EMSHPU23 Redefine Keys (Help for Command Key and Prefix fields).EMSHPU31 Shared Session Request (Help for User, Group, Terminal, and

Application fields).EMSHPU32 Shared Session Request (Help for Share Mode and Password

fields).EMSHPU41 Shared Session Response (Help for User, Group, Terminal, and

Application fields).EMSHPU42 Shared Session Response (Help for Shared Mode and Password

fields).EMSHPU52 Printer Destination (Help for User Defined Printer field).EMSHPU61 Bulletin Board (General Help).

Guidelines for Rewriting Message TextMessages are stored in a series of free-standing load modules. The messages arebuilt from fixed and variable text portions and written to one or more predefineddestinations. All messages numbered below 1000 are for the operator and arewritten to the console or SYSPRINT, or both. These messages are not normallytranslated and are delivered only in English. Messages numbered above 1000 arefor the user and are displayed in the message lines of the EUS panels. These maybe translated and displayed in any language.

Message TablesEach language requires its own message table.

The names of the message tables are as follows:

EMSMSTB0 All messages below 1000EMSMSTB1 Messages above 1000 for language 1EMSMSTB2 Messages above 1000 for language 2EMSMSTB3 Messages above 1000 for language 3EMSMSTB4 Messages above 1000 for language 4EMSMSTB5 Messages above 1000 for language 5EMSMSTB6 Messages above 1000 for language 6EMSMSTB7 Messages above 1000 for language 7EMSMSTB8 Messages above 1000 for language 8.

NetView Access Services is distributed with EMSMSTB0 and EMSMSTB1 inEnglish. Messages and panels for other languages can be ordered separately.The installer can update the messages or translate them into languages other thanthose offered by IBM. If this is done, ensure that the number of the message tablematches the panel library DD statements (EMSPAN1 to EMSPAN8). However:


� You cannot insert new messages or change the number of variables in amessage. You can update the text and rearrange the order of the text andvariables.

� You cannot delete a message or change the message identifier.

The definitions of the messages are generated using the EMSMSDEF assemblermacro. When the source is assembled it must be link-edited to form a load modulewith the correct name as listed here. NetView Access Services attempts to loadEMSMSTB0 to EMSMSTB8 at startup time from STEPLIB, any that are not foundare ignored. Message EMS0500E with a return code of 20 is issued if a missingtable is later referred to.

| A sample job to install an updated message table is available from the NetView| Access Services ems.v2r1m1.CUSTLIB data set. In this way you ensure that

service for a message table is applicable and does not override your updates.

Generating a Message TableTo generate a message table, run the following jobs in the sequence shown.

EMSMSGTB| Job EMSMSGTB, located in data set ems.v2r1m1.CUSTJOBS, is used to receive

and apply a message table.

1. Replace the umodname in the RECEIVE, APPLY, and ++USERMOD state-ments as required for your local environment.

2. Replace mtabname in the ++SRC statement and in the DD statement concat-enated to //SMPPTFIN according to the message table and language ID.

3. Submit the job.

4. When this job completes with a condition code of 4 or less, the message tablehas been applied.

EMSACCPT| Job EMSACCPT, located in data set ems.v2r1m1.CUSTJOBS, is used to accept

the message table:

1. Replace the umodname in the ACCEPT statement as required for your localenvironment.

2. Submit the job.

3. When this job completes with a condition code of 0, the message table hasbeen accepted.

Specifying MessagesA message number (for example, EMS1025I) consists of a 3-character componentname (EMS in this example), a 4-character message serial number (1025 in thisexample), and a 1-character type code (I in this example).

For further information on the message serial numbers and message types refer toFigure 29.

Messages are specified with the following EMSMSDEF macro call:


Note: Do not change the RET type destination or the MSGID identifier.

The syntax notation used in the following is described in Appendix A, “Reading theSyntax Diagrams” on page 303.

EMSMSDEF Macro

55──Symbol──EMSMSDEF─ ──MSGID=identifier ──,MSGSER=serial_number ──────────────5

┌ ┐─,WTO=NO────────5─ ─,MSGTYP=─ ──┬ ┬─A─ ──┼ ┼──────────────── ──┬ ┬─────────────────── ──────────────5

├ ┤─D─ └ ┘──,WTO= ──┬ ┬─NO── └ ┘──,DESC=(d1,d2,...) ├ ┤─E─ └ ┘─YES─ └ ┘─I─

┌ ┐─,LOG=NO──────── ┌ ┐─,RET=NO────────5─ ──┬ ┬─────────────────── ──┼ ┼──────────────── ──┼ ┼──────────────── ───────────5

└ ┘──,ROUT=(r1,r2,...) └ ┘──,LOG= ──┬ ┬─NO── └ ┘──,RET= ──┬ ┬─NO── └ ┘─YES─ └ ┘─YES─

┌ ┐─,──────────────────────────────────5─ ───

6┴──┬ ┬──────────────────────────────── ─────────────────────────────────5%

│ │┌ ┐─,──────────── └ ┘ ─MPART=─ ─(─ ───

6 ┴┬ ┬─'..text..'─ ─)─

└ ┘─vnum───────

Figure 29. Syntax of the EMSMSDEF Macro

MSGIDSpecifies the required message identifier, a string of 1 to 4 digits, according tothe assembler macro rules. MSGID represents an index (or search ID) to theMessage Table. By using the message ID, all changes to message numbersonly affect the Message Table and do not require any changes or reassembliesof the calling programs. Therefore when you change text or serial numbers ofmessages, the calling program stays the same.

MSGSERSpecifies the required message serial number (usually the same as themessage ID) of the message to be defined, which must be a string of 4 digits,according to the assembler macro rules. If the number is less than 4 digits,then zeros are placed preceding it to take up the 4 positions.

MSGTYPSpecifies the required type code of the message to be defined. The followingmessage type codes are supported:

A Immediate action is required.D Immediate decision is required.E Action might be required.I For information purposes only. These are not printed if MSGLEVEL

ERROR is specified in the APPL control statement.

WTO(Write to operator) specifies whether (YES) or not (NO) the required messageis to be written to the operator’s console. The default option is WTO=NO.

The maximum length of a WTO message is 256 characters. The first WTOmessage line can hold up to 70 characters (not including the messagenumber), and the second and any subsequent line only holds 66 characters,due to 4 bytes of indentation.


DESCSpecifies up to 16 descriptor codes that go with a WTO=YES type message.

Note: This operand is ignored with WTO=NO.

ROUTSpecifies up to 16 routing codes that go with the WTO=YES type message.This operand is ignored with WTO=NO, and is also ignored if ROUTCODE isspecified in the NetView Access Services input parameter data set.

LOGSpecifies whether (YES) or not (NO) the required message is to be written tothe SYSPRINT data set. The default option is NO.

The maximum length of the LOG message text must not exceed 115 charac-ters, otherwise it is truncated.

RETSpecifies whether (YES) or not (NO) the required message is to be returned tothe program that called it. RET=NO is the default option.

If the length of the message text that is to be returned to the calling programexceeds the size of the return buffer, the message is truncated.

Note: The first 2 bytes of a return buffer show the significant length of themessage text that is returned.

MPARTSpecifies text portions or variables or both. The actual values of the variablesare supplied later by the program that issued the message.

You can specify the text portions and the order of the variables. All specifica-tions of text portions must be enclosed in quotes.

The variables are represented by numbers. These numbers reflect the proc-essing order of the variable values.

It should be noted that this parameter can be specified many times.

Example of a Message Definition

EMSMSDEF MSGID=44ð, \

MSGSER=44ð, \

MSGTYP=E, \

WTO=YES, \

MPART=('text-1',1,'text-2',2)

Figure 30. Example of a Message Definition

In this example, there are two text portions and two variables specified for MPART.The text portions can be updated, and the variables can be rearranged.

Message Return CodesThe errors that are found by the Message Processor during the processing orcalling of a message are seen in the following message:

EMSð5ððE ERROR ENCOUNTERED PROCESSING MESSAGE ID xxxx — LANGUAGE = yy — RC = zz.


In the example, xxxx is 0440, yy is the language ID as described in “EMSELNEX,Language Name Exit” on page 161, and zz is represented by one of the followingreturn codes: *

RC Meaning4 Message truncation has occurred (RET=Y).

Return area length is insufficient.8 Variable text received, but not expected.

Mismatch between MSDEF and MSPUT.12 Variable text expected, but not received.

Mismatch between MSDEF and MSPUT.16 Invalid message number was specified. Message not defined in table.20 Message Table is missing or not available. Possibly a link-edit failure.24 Error encountered with WTO macro service.

Message not sent to system console.28 Error encountered on External Trace facility.

Message was sent to system console.32 Error with External Trace and WTO facilities.

Message not sent to system console.36 Invalid length specified with conversion.

Allows FIXED(31) or FIXED(15) only.40 Message truncation has occurred (LOG=Y).44 Message truncation has occurred twice.

For both destinations, LOG and RET.48 Return area length or pointer is missing.52 Language is not determinable. Probably a logic error.54 BLDL for message tables failed.56 Invalid language detected, reset to 1.

Multilingual Support ConsiderationsFor languages not provided by IBM you can perform your own translation using thepanels and messages delivered by IBM and translating them. Carry out the fol-lowing steps to implement your own translated panels and messages:

1. Translate:

a. The panels according to the guidelines referred to in “Guidelines for Modi-fying Panels” on page 91

b. The messages according to the guidelines referred to in “Guidelines forRewriting Message Text” on page 103.

2. Choose a ddname of EMSPANx (1 < = x < 8) for your translated panels andstore them in a data set. Use a ddname and number that is not already in use.Make a backup copy of all your panels in case you overwrite your panels byinstalling a new NetView Access Services National Language feature.

3. Store your corresponding translated message table EMSMSTBx in the sourcelibrary.

4. Create the new corresponding message table EMSMSTBx loadlib as describedin “Generating a Message Table” on page 104.

5. Adapt the following language sensitive exit routines:

� “EMSEBXML, Broadcast Exit” on page 145� “EMSEDTEX, Date and Time Exit” on page 147


� “EMSELNEX, Language Name Exit” on page 161� “EMSELVEX, Language Verification Exit” on page 164� “EMSEPRPS, Printer Presetting Exit” on page 167.

Modifying NetView Access Services CommandsYou can remove or change a NetView Access Services command name bychanging the command name constants in the EMSEUS load module. Thecommand constants and appropriate offsets in the CSECT CMDAREA are shown inTable 6.

NetView Access Services provides two jobs, EMSZCMDS to remove or change acommand name, and EMSRESTO to revoke this change. These two jobs are

| located in the ems.v2r1m1.CUSTJOBS data set.

EMSZCMDSIf you want to change or remove a command:

1. Replace umodname in the RECEIVE, APPLY, and ++USERMOD statements.

2. Enter the hexadecimal offset and the contents for the selected command in theEMSEUS CMDAREA of the EMSZCMDS job.

For example, to remove the EXIT command enter the hexadecimal offsetX'120', in the EMSEUS CMDAREA of the EMSZCMDS job, and replace thecontents with X'FFFFFFFFFFFFFFFF'. The EXIT command cannot be used ifthis ZAP is applied.

3. Submit the job.

EMSRESTOIf you want to revoke the change made with the EMSZCMDS job, replace

| umodname in the RESTORE statement of job EMSRESTO located in the| ems.v2r1m1.CUSTJOBS data set and submit the job.

Table 6 (Part 1 of 3). Offsets for the Sample Job

OffsetDecimal

OffsetHex

Contents Hex Type Length Command

ð (ð) C64ð4ð4ð4ð4ð4ð4ð CHAR 8 'F'

8 (8) C3C64ð4ð4ð4ð4ð4ð CHAR 8 'CF'

16 (1ð) C3E34ð4ð4ð4ð4ð4ð CHAR 8 'CT'

24 (18) C3D84ð4ð4ð4ð4ð4ð CHAR 8 'CQ'

32 (2ð) C2D94ð4ð4ð4ð4ð4ð CHAR 8 'BR'

4ð (28) D8D94ð4ð4ð4ð4ð4ð CHAR 8 'QR'

48 (3ð) C6D9C94ð4ð4ð4ð4ð CHAR 8 'FRI'

56 (38) C6D9D44ð4ð4ð4ð4ð CHAR 8 'FRM'

64 (4ð) C6D94ð4ð4ð4ð4ð4ð CHAR 8 'FR'

72 (48) E3D94ð4ð4ð4ð4ð4ð CHAR 8 'TR'

8ð (5ð) D3C64ð4ð4ð4ð4ð4ð CHAR 8 'LF'

88 (58) C4C9E2C34ð4ð4ð4ð CHAR 8 'DISC'

96 (6ð) D3D6C7D6C6C64ð4ð CHAR 8 'LOGOFF'

1ð4 (68) C8C5D3D74ð4ð4ð4ð CHAR 8 'HELP'

114 (7ð) D7C44ð4ð4ð4ð4ð4ð CHAR 8 'PD'

12ð (78) E2D74ð4ð4ð4ð4ð4ð CHAR 8 'SP'

128 (8ð) E2D94ð4ð4ð4ð4ð4ð CHAR 8 'SR'

136 (88) D14ð4ð4ð4ð4ð4ð4ð CHAR 8 'J'



OffsetDecimal

OffsetHex


144 (9ð) C54ð4ð4ð4ð4ð4ð4ð CHAR 8 'E'

152 (98) C1E24ð4ð4ð4ð4ð4ð CHAR 8 'AS'

16ð (Að) C1C74ð4ð4ð4ð4ð4ð CHAR 8 'AG'

168 (A8) C9D5C6D64ð4ð4ð4ð CHAR 8 'INFO'

176 (Bð) C2D9C14ð4ð4ð4ð4ð CHAR 8 'BRA'

184 (B8) C4C9E2D7D3C1E84ð CHAR 8 'DISPLAY'

192 (Cð) D3C9E2E34ð4ð4ð4ð CHAR 8 'LIST'

2ðð (C8) C1C4D44ð4ð4ð4ð4ð CHAR 8 'ADM'

2ð8 (Dð) C5D5C44ð4ð4ð4ð4ð CHAR 8 'END'

216 (D8) C1C4C44ð4ð4ð4ð4ð CHAR 8 'ADD'

224 (Eð) E4D7C4C1E3C54ð4ð CHAR 8 'UPDATE'

232 (E8) C4C5D3C5E3C54ð4ð CHAR 8 'DELETE'

24ð (Fð) C6D6D9E64ð4ð4ð4ð CHAR 8 'FORW'

248 (F8) C2C1C3D24ð4ð4ð4ð CHAR 8 'BACK'

256 (1ðð) C14ð4ð4ð4ð4ð4ð4ð CHAR 8 'A'

264 (1ð8) E44ð4ð4ð4ð4ð4ð4ð CHAR 8 'U'

272 (11ð) C44ð4ð4ð4ð4ð4ð4ð CHAR 8 'D'

28ð (118) D34ð4ð4ð4ð4ð4ð4ð CHAR 8 'L'

288 (12ð) C5E7C9E34ð4ð4ð4ð CHAR 8 'EXIT'

296 (128) D2C5E8E24ð4ð4ð4ð CHAR 8 'KEYS'

3ð4 (13ð) C4C24ð4ð4ð4ð4ð4ð CHAR 8 'DB'

312 (138) D7C6F14ð4ð4ð4ð4ð CHAR 8 'PF1'

32ð (14ð) D7C6F24ð4ð4ð4ð4ð CHAR 8 'PF2'

328 (148) D7C6F34ð4ð4ð4ð4ð CHAR 8 'PF3'

336 (15ð) D7C6F44ð4ð4ð4ð4ð CHAR 8 'PF4'

344 (158) D7C6F54ð4ð4ð4ð4ð CHAR 8 'PF5'


36ð (168) D7C6F74ð4ð4ð4ð4ð CHAR 8 'PF7'


376 (178) D7C6F94ð4ð4ð4ð4ð CHAR 8 'PF9'

384 (18ð) D7C6FðF14ð4ð4ð4ð CHAR 8 'PFð1'

392 (188) D7C6FðF24ð4ð4ð4ð CHAR 8 'PFð2'

4ðð (19ð) D7C6FðF34ð4ð4ð4ð CHAR 8 'PFð3'

4ð8 (198) D7C6FðF44ð4ð4ð4ð CHAR 8 'PFð4'

416 (1Að) D7C6FðF54ð4ð4ð4ð CHAR 8 'PFð5'

424 (1A4) D7C6FðF64ð4ð4ð4ð CHAR 8 'PFð6'

423 (1Bð) D7C6FðF74ð4ð4ð4ð CHAR 8 'PFð7'

44ð (1B8) D7C6FðF84ð4ð4ð4ð CHAR 8 'PFð8'

448 (1Cð) D7C6FðF94ð4ð4ð4ð CHAR 8 'PFð9'

456 (1C8) D7C6F1Fð4ð4ð4ð4ð CHAR 8 'PF1ð'

464 (1Dð) D7C6F1F14ð4ð4ð4ð CHAR 8 'PF11'

472 (1D8) D7C6F1F24ð4ð4ð4ð CHAR 8 'PF12'

48ð (1Eð) D7C6F1F34ð4ð4ð4ð CHAR 8 'PF13'

488 (1E8) D7C6F1F44ð4ð4ð4ð CHAR 8 'PF14'

496 (1Fð) D7C6F1F54ð4ð4ð4ð CHAR 8 'PF15'

5ð4 (1F8) D7C6F1F64ð4ð4ð4ð CHAR 8 'PF16'

512 (2ðð) D7C6F1F74ð4ð4ð4ð CHAR 8 'PF17'

52ð (2ð8) D7C6F1F84ð4ð4ð4ð CHAR 8 'PF18'

528 (21ð) D7C6F1F94ð4ð4ð4ð CHAR 8 'PF19'

536 (218) D7C6F2Fð4ð4ð4ð4ð CHAR 8 'PF2ð'

544 (22ð) D7C6F2F14ð4ð4ð4ð CHAR 8 'PF21'

552 (228) D7C6F2F24ð4ð4ð4ð CHAR 8 'PF22'

56ð (23ð) D7C6F2F34ð4ð4ð4ð CHAR 8 'PF23'

568 (238) D7C6F2F44ð4ð4ð4ð CHAR 8 'PF24'

576 (24ð) D7C1F14ð4ð4ð4ð4ð CHAR 8 'PA1'



OffsetDecimal

OffsetHex


584 (248) D7C1F24ð4ð4ð4ð4ð CHAR 8 'PA2'

592 (25ð) D7C1F34ð4ð4ð4ð4ð CHAR 8 'PA3'

6ðð (258) C1E3E3D54ð4ð4ð4ð CHAR 8 'ATTN'

6ð8 (26ð) E2C84ð4ð4ð4ð4ð4ð CHAR 8 'SH'

616 (268) E2C8C1D9C54ð4ð4ð CHAR 8 'SHARE'

624 (27ð) D7D94ð4ð4ð4ð4ð4ð CHAR 8 'PR'

632 (278) D7D9C9D5E34ð4ð4ð CHAR 8 'PRINT'

64ð (28ð) C2E44ð4ð4ð4ð4ð4ð CHAR 8 'BU'

648 (288) C2E4D3D3C5E3C9D5 CHAR 8 'BULLETIN'

656 (29ð) C2D4E2C74ð4ð4ð4ð CHAR 8 'BMSG'

664 (298) C5E7C5C34ð4ð4ð4ð CHAR 8 'EXEC'

672 (2Að) C3D5C5E7C5C34ð4ð CHAR 8 'CNEXEC'


| Chapter 12. Customizing NetView Access Services Sample| Exits to Interface with RACF

Refer to Systems Programming Library: Resource Access Control Facility (RACF)for more information when reading the following.

Concept of the NetView Access Services Interface to RACFIf you intend to use the NetView Access Services interface to RACF, you mustknow how the interface is intended to be used. MVS NetView/Access ServicesSecurity and RACF provides an overview of how security is to be handled, and howthe security-related tasks should be split between NetView Access Services andRACF administration.

The following explanation of the basic concepts can help you to customize NetViewAccess Services and RACF so that you can gain the maximum benefit from theinterface with the minimum amount of administration:

1. NetView Access Services provides two interfaces to RACF with the followingfunctions:

� User authentication when the user logs on to NetView Access Services pro-| vided by the sample logon authorization exit EMSELGNX. If you customize| this exit to interface with RACF (if &DUMMY is set to N), a user can only| gain access to applications in NetView Access Services groups if the user| is defined to RACF and has entered a valid password. Depending on how| the exit is customized, the entered group ID is also checked against RACF.| The exit can also evaluate and insert a default group ID.

| When NetView Access Services has evaluated that the user ID and group| ID are valid, the applications defined for the user in this group can be eval-| uated and displayed on the Application Selection panel. If the user is| logged on to an external group, RACF is again involved in this process.

� Maintenance of NetView Access Services user data in RACF (instead ofVSAM) for NetView Access Services external groups. This is provided bythe sample administration exit EMSEADEX.

The two sample exits can be customized independently so you can plan asecurity concept for your own environment.

| The session establishment exit EMSESEEX can also use RACF if required, but| it is not used in the supplied implementation. Addressability to ACEE is also| provided.

2. If your installation already has a large RACF database in which all users are| defined, you can use this database instead of the SRTU data set, to define the| groups as External groups in your NetView Access Services environment. You| can then assign applications to the groups and specify the default sequence| number and other parameters using the NetView Access Services adminis-| tration functions. Users can now log on using the default access parameters| defined for the group applications. If you do this, your installation can adapt

the administration exit EMSEADEX using exits for other systems such as aDB2* database or another form of VSAM file.


3. The sample administration exit EMSEADEX is not intended to totally replacethe command interface of RACF. Although you can use the sample exit to

| define and delete NetView Access Services and RACF profiles simultaneously| (if &RACAD is set to Y), it is not recommended to do so. There are several

reasons for this:

� NetView Access Services uses a macrointerface to RACF. The macro,ICHEINTY, bypasses plausibility checks of the RACF manager and it istherefore not recommended to use it to add, or delete RACF profiles.However, the ICHEINTY macro can be used to change RACF profiles.

� Adding and deleting RACF profiles via NetView Access Services mayinteract with the tasks of your security administrator. A system or groupadministrator may not be aware of the effects NetView Access Servicescommands can have on the RACF database.

It is therefore recommended to define the RACF user and group profiles youintend to use with NetView Access Services via the RACF command interface,and then administer the corresponding NetView Access Services profiles.

What the Sample Administration Exit EMSEADEX DoesThe sample exit does the following when the variable &DUMMY has been set to N:

� Checks that NetView Access Services is APF authorized. If not, a return codeof X'FE' is given, and the exit is terminated.

� Adds, updates, and deletes administrators.

If the system administrator to be added is not defined in RACF, the user isadded to the system default group set by the value of the exit field&SYSDEFGR. Make sure that the value you set for the &SYSDEFGR field isdefined as a group in RACF. For system administrators, the RACF systemspecial authority is assigned if the &RACSPEC attribute has been set to Y.

If the group administrator of external groups to be added is not defined inRACF, the user is added to RACF with the group as his or her default group.The user is also connected to the group with RACF group special authorityassigned if the &RACSPEC attribute has been set to Y.

When administrators are deleted, their RACF profiles are not deleted, only theirspecial authority is revoked.

Note: Any administrators defined before the installation of administration exitEMSEADEX are still recognized as NetView Access Services administrators.However, if they are not given special authority in RACF and if &CHKADM isset to Y, they may not be able to perform some of the administration tasks.

� Adds, updates, and deletes a group.

When a group is added via administration option 5, Define a Group, a RACFgroup profile is created if the group type is external. A group record is alsocreated in the NetView Access Services GPRF VSAM data set. Any valuespecified for the Admin Exit Data field is assigned to the installation data fieldof the group profile. The rest of the group information, such as group type andaccount number, is stored in the NetView Access Services GPRF VSAM dataset.

When an external group is deleted, its RACF group profile and the NetViewAccess Services group record are deleted.

� Adds, deletes, and updates an application to a group.


When an application is added to an External group, that application is assignedautomatically to all users of that group. When an application is deleted from anExternal group, that application is deleted for all users of the group. ForExternal groups, when the last application for the group is deleted via adminis-tration option 6, no RACF profiles are deleted. This means that the userprofile, group profile, and the users’ connect profiles are kept. To delete theseprofiles, you need to delete the group using the administration option 5, Definea Group.

� Adds, updates, and deletes applications to a user.

When an application is added to a user of a group via administration option 3,Assign a User to a Group, the exit checks whether the user is defined toRACF. If not, the exit adds the user to RACF by issuing RACF macro calls tocreate a user profile. The RACF user profile created has the followingattributes:

– Default password - group ID– User is forced to change password on the first logon– Default group - group ID as supplied to exit– Set password change interval to 31.

If the user is already defined to RACF but not to the group, a group connectprofile is created for that user. The RACF connect profile created has the fol-lowing attributes:

– UACC - NONE– AUTHDATE - the current date.

When a user is added to an External group, all applications associated with thegroup are automatically assigned to the user. To restrict a user’s access to aparticular application, the administrator must explicitly delete that application forthe user.

When the user’s last application is deleted, the user’s connect profile to thatgroup is deleted (assuming that the profile has the correct profile owner asdefined in the OWNERNAM field). If the group is the user’s default group, theuser profile is deleted unless the user is connected to some other groups.

� Sets the RACF default groups. The first group in which a user is definedbecomes their default RACF group. This must not be confused with the defaultNetView Access Services group.

� Stores the Admin exit data in RACF. For the user-oriented functions, theformat of the user exit data is:

┌───────────────────────────────────────────────────────────────────────┐

│ USER NAME¦INSTALLATION DATA │

└───────────────────────────────────────────────────────────────────────┘

The value of the Admin exit data is assigned to the PGMRNAME andINSTDATA fields of the RACF user profiles. The value of the two fields mustbe separated by a split vertical bar: ¦ (Hex value X'6A'). The name field canhave up to 20 characters. The total Admin exit field can have up to 60 charac-ters. The ¦ symbol is used as a delimiter. These are synonymous with theNAME and DATA parameters of the TSO ADDUSER command. On the Definea Group panel the user data has the format:

INSTALLATION DATA

Chapter 12. Customizing NetView Access Services Sample Exits to Interface with RACF 113

This is synonymous with the DATA parameter of the TSO ADDGROUPcommand. Almost any of the TSO RACF parameters associated withADDUSER and ADDGROUP can be implemented via this data. There are alsopossibilities for entering application dependent data and checking it in sessionestablishment exit EMSESEEX or within the application itself.

Note: The user-exit data can be specified as an asterisk to indicate that nochange in the RACF database is to be performed. Blanking it out resets thedefault values defined in administration exit EMSEADEX, except for groupupdate where it does not change the existing group exit data.

� Sets the owner of the RACF profile. All RACF profiles created by the exit aregiven an owner identity of NVAS. Only such profiles are deleted by the exit.

� See also the comments at the beginning of the sample code.

Before you install the sample administration exit EMSEADEX, there are several var-iables and fields that affect the way RACF profiles are added via the NetView

| Access Services administration exit EMSEADEX, see “EMSEADEX, Administration| Exit” on page 132.

Administering External GroupsThere are functional differences between the administration of NetView Access Ser-vices external, normal, and public groups. The following provides some additionalinformation that you should know, when you administer external groups:

� The LIST command issued on the Assign a User to a Group panel has arestricted scope. Refer to NetView Access Services Version 2 Administrationfor the supported lists.

� The Admin Exit Data is only stored in the RACF user profile, when an externalgroup is processed. The data is only read from the RACF profile for aDISPLAY or UPDATE command. For ADD commands a default value isinserted.

� Deleting external groups or users, that are defined to external groups, must beadministered in a specific way to avoid inconsistent data:

1. For normal and public groups, NetView Access Services performs an auto-matic deletion of underlying profiles, when a superior profile is deleted. Forexample, deleting a normal group causes an implicit delete of all users,applications, and group administrators, defined to that group. This functionis not supported with external groups and may cause problems.

If you want to delete an external group, you must first ensure that all usersin this group, including all group administrators, are deleted and removedfrom this group.

If you try to delete an external group before all users are removed, yourcommand is rejected with error message EMS1683E. You can get a list ofthe user IDs that are connected to the group via RACF LISTGROUPcommand. If there is a user ID connected to the group for which noFACILITY profile exists (for example, a group administrator), you musteither:

a. Define, or redefine, the user to the group and then delete that userfrom the group.

b. Remove that user from the group via RACF REMOVE command.


2. Deleting a user from an external NetView Access Services group does notautomatically mean that the user is removed from that RACF group.

3. Deleting all applications from an external group has no effect on RACF,that is, the user’s CONNECT and FACILITY profiles remain unchanged.Nevertheless, all users are unable to log on to this group.

� ALL commands (using an * in the key field as a global file-name character) arerestricted to the application ID field. Adding a new user to the group is alwaysperformed as ADD ALL command.

Deleting a user from all applications (using an * in the key field as a globalfile-name character) does not remove that user from the group.

� The default server indicator and the selection IDs are automatically updatedwhen something changes.

The default group indicator, however, is not updated automatically across groupboundaries as this is done for normal groups. If a user is defined to severalgroups of different types, changing the default group indicator to Y in one groupautomatically sets the indicator to N in all other normal groups that the user isdefined to. However, the default group indicator in the users external group isnot adapted.

Note: The default group concept for external groups does not rely on this indi-cator.

| External Application Authorization| NetView Access Services Version 2 Release 1.1 introduces a new feature, External| Application Authorization. Currently, when using NetView Access Services external| groups, the information about which applications a NetView Access Services user is| allowed to access is configured by the NetView Access Services administrator.| With the External Application Authorization feature, instead, this information will be| taken directly from the RACF database, and will be used to build the Application| Selection Panel. When a user logs on to NetView Access Services, a call to RACF| results in a list of applications the user, or the group the user is connecting with, is| allowed to access, and only these applications are displayed on the Application| Selection Panel for the user.

| A new parameter, &RACFENH, has been introduced into the EMSEADEX exit| routine. When &RACFENH = 'N' is specified, then NetView Access Services will| function as before, and the NetView Access Services administrator must configure| the information about which applications a user is allowed to access, using the| NetView Access Services ADM panels. If, instead, &RACFENH = 'Y' and| &DUMMY = 'N' are specified in the EMSEADEX exit routine, then NetView Access| Services will use the new external group logic described below:

| � The NetView Access Services administrator must define to NetView Access| Services all the applications to be used with NetView Access Services using| administration option 4.

| � The NetView Access Services administrator must define to NetView Access| Services all the external groups to be used using administrator option 5. The| names of these groups must match names of RACF groups.


| � Optionally, the NetView Access Services administrator can modify application-| group parameters (administration options 6 and 2) and application-user param-| eters (administration options 3 and 1).

| � When a user logs on to NetView Access Services with an external group, the| Application Selection Panel is built according to the following:

| – List all applications defined to the system (SRTS entries) to have the base| set of applications.

| – For each application in the SRTS, call a RACF function to check whether| the user, or the group to which he belongs, is allowed access to that appli-| cation.

| – If the user, or the group to which he belongs, is authorized to use the appli-| cation, then the application is added to the NetView Access Services Appli-| cation Selection panel. In particular:

| - If there is an entry for the application in the SRTG, then this entry is| used to take the values for the SRTU record.

| - NetView Access Services calls RACF (via EMSEADEX) to get the| facility class profile for the user and extracts all personal application| access parameters. If such a profile is found, its values are put into the| SRTU record.

| - The user has access to these applications until he logs off from| NetView Access Services, even when the RACF application access list| is updated while the user is in session with NetView Access Services.

| – If the user is NOT authorized to use the application, or the application is| not protected via RACF, then the application is dropped from the list of| applications available to the user and is not displayed on the NetView| Access Services Application Selection panel.

| How Does External Application Authorization Change the Procedure| With this mechanism, the NetView Access Services administrator need only define| to NetView Access Services the application and the external groups. NetView| Access Services will ascertain which applications the user is allowed to access by| looking at the RACF configuration. If the application is not protected by RACF,| then it assumes that the user does not have access to the application.

| Application access parameters, such as application-group parameters (adminis-| tration options 6 and 2) and application-user parameters (administration options 3| and 1) will be taken from the system definition of the applications, and from default| values. To change these parameters, the NetView Access Services administrator| can add the application to a group or update it for a single user, just as in the old| way for processing external groups.

| Deleting an application for a user from NetView Access Services panels has no| effect in the new External Application Authorization logic. Only the RACF adminis-| trator can grant or deny access to an application for a user.

| The RACF administrator should protect applications as described in RACF Security| Administrator's Guide. The RACF administrator must create a resource in the| 'APPL' class in the RACF database for each application he wants to protect. He| must also create an 'access list' for each of these applications, where he must| specify the authorized access to the application for a specific user or for a group of


| users (RACF group). The name of the resource, (that is, the name of the applica-| tion to be protected), must match the name of the application as defined to NetView| Access Services.

Using RACF to Maintain External GroupsUsing external groups is an easy way to administer users when a large database ofusers already exists. In this case, an administrator is not required to add each userexplicitly to NetView Access Services, but can define the RACF groups of the usersto NetView Access Services as external groups, whereby the name of NetViewAccess Services groups and RACF groups are the same.

When the administrator has added some applications to these groups in NetViewAccess Services, each user connected to a group in RACF can log on to NetViewAccess Services and get all applications of this group displayed on the ApplicationSelection panel. If some applications are to be restricted for a specific user, theymust be deleted explicitly one by one.

Because a user of an external group is not defined to NetView Access Services, noEMSSRTU records for the user exist in a VSAM data set. All user-specific informa-tion (for example, Jump keys and sequence of the application on the ApplicationSelection panel) is stored within RACF in a general resource profile created byNetView Access Services.

When a user of an external group logs on to NetView Access Services the followingoccurs:

The administration exit EMSEADEX reads the user-defined application accessparameters from a general resource profile in RACF. If no profile exists (forexample, the user is logging on to NetView Access Services for the first time),NetView Access Services assumes that all applications defined for the externalgroup are available for this user and the group-wide defined application accessparameters apply. Based on the information in the RACF profile, the defaults forthe group or group applications, or both, NetView Access Services builds the Appli-cation Selection panel for the user.

Whenever users update their access parameters, the values that vary from thedefaults are stored in RACF as shown in Table 7 on page 120. Therefore, whenusing external groups, it is recommended not to share one and the same RACFdatabase between different NetView Access Services systems with different appli-cations.

When the applications in an external group are defined without selection IDs or withselection IDs that are not in the proper order, NetView Access Services mustarrange the applications on the Application Selection panel when it builds the panelfor the first time, that is, when the user logs on for the first time. The order of theapplications is stored as the user’s personal information in a RACF generalresource profile created by NetView Access Services. This is why a new generalresource profile is created in RACF after a user logs on for the first time.


Comparison between Normal and External GroupsThe following provides a comparison between Normal and External groups. Ingeneral, using Normal groups requires more administrative effort, but providesgreater security (each user must be granted explicit access to each application).The use of External groups suit installations that already have a large RACF data-base of users and do not want to readminister those users. The following exam-ples show the difference between the administrative effort required for Normal andExternal groups.

Example 1: Assume that an installation has 20 RACF groups and 1000 usersconnected to them. The same group partition is to be used in NetView AccessServices, and 10 applications are to be assigned to each group.

The main difference between normal and external groups is that with normal groupsa user must be defined explicitly to each application of the group using option 3,Assign a User to a Group on the NetView Access Services Administration Selectionpanel (if an asterisk is specified in the Application field, then the user gets accessto all applications defined to the group), whereas with external groups the user

| automatically gets access to all applications of the group. Furthermore, if| &RACFENH=Y, the applications are associated to each group by the RACF admin-| istrator.

As can be seen from the example, the administrative effort is greatly reduced byusing External groups. However, if one application in an external group is to berestricted for a user, this application must be explicitly deleted for that user on the

| Assign a User to a Group panel, or from RACF if &RACFENH=Y. If different usersof applications in the same group are to have access to different applications in thegroup, then the advantage of using external groups is reduced. In addition, if aninstallation plans to establish new groups and new users, then this reduction ineffort is not so appreciable.

Example 2: Assume that an administrator plans to create 20 workgroups and to| assign 1000 newly hired users to them. Each group will have 10 applications| assigned to it. RACF as security manager is planned and the NetView Access

Services logon exit must call RACF for authentication purposes.

a) If Normal NetView Access Services groups are used.10 applications must be added in NetView Access Services:20 groups must be added to NetView Access Services:10 applications must be added to each group:Each user must be added to a group:

Total:

10 adds+ 20 adds+ 200 adds+ 1000 adds= 1230 adds

b) If External NVAS groups are used (&RACFENH=N).

10 applications must be added in NetView Access Services:20 groups must be added to NetView Access Services:10 applications must be added to each group:

Total:

10 adds+ 20 adds+ 200 adds= 230 adds

| | c) If External NVAS groups are used and also the External| Application Authorization feature is used (&RACFENH=Y).| 10 applications must be added in NetView Access Services:| 20 groups must be added to NetView Access Services:| Total:

| | | | 10 adds| + 20 adds| = 30 adds


Of course the number of theoretical adds does not indicate what real effort isrequired (for instance, NetView Access Services offers a Batch Load and Reportingfacility so that administration can be done in the background), but it does indicatethat an appreciable reduction in administrative effort can be made only if properRACF group partitioning is already made.

a) Normal NetView Access Services groups are used.Each user must be added to RACF:10 applications must be added in NetView Access Services:20 groups must be added to NetView Access Services:10 applications must be added to each group:Each user must be added to a group:

Total:

1000 adds+ 10 adds+ 20 adds+ 200 adds+ 1000 adds= 2230 adds

b) External NVAS groups are used (&RACFENH=N).

Each user must be added to a RACF:10 applications must be added in NetView Access Services:20 groups must be added to NetView Access Services:10 applications must be added to each group:20 groups must be added to RACF:

Total:

1000 adds+ 10 adds+ 20 adds+ 200 adds+ 20 adds

= 1250 adds| | c) If External NVAS groups are used and also the External| Application Authorization feature is used (&RACFENH=Y).| Each user must be added to a RACF:| 10 applications must be added in NetView Access Services:| 20 groups must be added to NetView Access Services:| 20 groups must be added to RACF.:| Total:

| | | | 1000 adds| + 10 adds| + 20 adds| + 20 adds| = 1050 adds

Where the Application Access Data Is Stored in RACFWhenever user-specific parameters are updated, the values that vary from thedefaults are written to RACF. For this purpose, NetView Access Services createsits on general resource profile within the RACF FACILITY class. The key for theprofile is USERID_GROUPID. Refer to Figure 35 on page 125. An array,USERDATA, is defined in the profile (as in other RACF profiles). This array can berepeated as many times as necessary within the actual profile. NetView AccessServices uses this possibility to write one USERDATA array for each application auser can use and can therefore store within one RACF profile the information thatis stored for Normal groups in various EMSSRTU records.

How Application Access Data Is Stored in RACFTo store the application access data for a single application, NetView Access Ser-vices uses one USERDATA array. The USERDATA array has the same format inall RACF profiles. Each entry consists of three fields:

USRNAME This is an 8-byte key used to identify the entry. NetView Access Ser-vices puts the application name in here.

USRDATA This is a variable-length field with a maximum length of 255. NetViewAccess Services stores the access parameters in here.

USRFLAG This is a 1-byte flag that can be put to whatever purpose seems appli-cable. NetView Access Services does not use this field.


Only those access parameters that vary from the default are actually stored in thesubfield USRDATA of the USERDATA array. Each one is identified by a 1-bytebinary key and, where applicable, by a 1-byte binary length field. The followingvalues are used:

Table 7 (Part 1 of 2). RACF Data Format

CodeVari-ableLength

Max.Length

Usage Default

01 N 8 VULUNAME - Terminal LU name Blank

02 Y 15 VULP1D - Profile 1 description Blank

03 Y 15 VULP2D - Profile 2 description Blank

04 Y 8 VUAPWD - Application password Blank

05 Y 8 VUANPW - Application new password Blank

06 Y 8 VUAOPW - Application old password Blank

07 Y 8 VUAUID - Application user ID Blank

08 Y 8 VUAACNO - Application account number Blank

09 Y 8 VUAVAR1 - GVAR1 Blank

0A Y 8 VUAVAR2 - GVAR2 Blank

0B Y 8 VUAVAR3 - GVAR3 Blank

0C Y 8 VUAVAR4 - GVAR4 Blank

0D Y 8 VUAVAR5 - GVAR5 Blank

0E Y 8 VUAVAR6 - UVAR1 Blank

0F Y 8 VUAVAR7 - UVAR2 Blank

10 Y 8 VUAVAR8 - UVAR3 Blank

11 Y 8 VUAVAR9 - UVAR4 Blank

12 N 1 VUDGIND - Default group indicator Y

13 N 1 VUDSIND - Default server indicator N

14 N 1 VUACCTYP - Access type Group access type

15 N 1 VURECAUT - Record authority N

16 N 1 VUTERMAS - Terminal assume authority Y

17 N 1 VUALPRF - Logon profile (U/G/S) Group logon profile

18 N 1 VULOGPRF - Active logon profile (1/2) 1

19 N 1 VUSEQNO - Selection ID Group selection ID

1A N 1 VUJKEY - Jump key Group jump key

1B N 14 VULUPD - Last update (see note) N/A

1C N 1 VUEKEY - Escape key Group escape key

1D N 1 VUCKEY - Command key Group command key

1E Y 8 VUCOPREF - Command prefix Group command prefix

1F N 1 VUAMRI - Message received indicator Group message received indicator

20 N 1 VUDAIID - Display application ID (Y/N) N


Table 7 (Part 2 of 2). RACF Data Format

CodeVari-ableLength

Max.Length

Usage Default

21 Y 8 VUPRTNAM - User-defined printer name N/A

22 N 1 VUSHR - Shareable (Y/N) N

23 N 1 VUPRTKEY - Print key Group print key

FF N 0 Drops application for the user N/A

Note: The last update information is stored differently in USRDATA from theformat in the SRTU. In USRDATA the date and time are stored as a single 6-bytepacked decimal value. In the SRTU they are stored in zoned decimal editedformat.

It is not necessary for EMSEADEX to be aware of the contents of eachUSERDATA array entry, but you might want to check the contents and disallowcertain values. When EMSEADEX is called with the commands ADD, UPDATE, orDELETE, the address of a ready formatted area is given in ADEXUARR. This isnormally a single entry and should be added to the array or used to replace anexisting entry. For DELETE the USRDATA passed is set to X'FF'.

When End User Services needs to read one or more SRTU records, and it deter-mines that the group type is External, it builds the records internally by taking allthe SRTG records for the group and merging them with data obtained from theUSERDATA array. EMSEADEX is called with a command of GETAPPLS. Itshould then retrieve the entire USERDATA array and return its address inADEXUARR. If no array exists for this user and group, then the length containedat the beginning of the returned data should be set to zero.

The data pointed to by ADEXUARR must take the format shown in the followingfigure. If you adapt this interface to your own system then you must still keep tothis format for the data returned on a GETAPPLS request. The data given toEMSEADEX on ADD, DELETE, and UPDATE requests is in this format, but mightonly be the data for one application.


Table 8. Format of Data Pointed to by ADEXUARR

Level Name Length Type Description

1 TOTLEN 2 H Total length of following data

1 ENTRY1 V STR Entry for first application (USERDATA)

2 APPL1 8 C Application name (USRNAME)

2 LEN1 1 B Length of USRDATA (First byte of USRDATA)

2 DATA1 <255 X Data for application 1 (USRDATA)

2 FLAG1 1 X Not used (USRFLAG)

1 ENTRY2 V STR Entry for second application (USERDATA)

2 APPL2 8 C Application name (USRNAME)

2 LEN2 1 B Length of USRDATA (First byte of USRDATA)

2 DATA2 <255 X Data for application 2 (USRDATA)

2 FLAG2 1 X Not used (USRFLAG)

The ENTRYn structure can be repeated as often as needed. The names in paren-thesis (for example, USRNAME) are the names from the RACF template. The fol-lowing shows how this might appear:

ðð26E3E2D64ð4ð4ð4ð4ðð1FFððC3C9C3E24ð4ð4ð4ð1119ð21BC2D9C44ð4ð4ð4ð4ð

T S O C I C S B R D

88271113ð2ðFðð

Figure 31. Names from the RACF Template

X'0026' (38) is the length of the following data; TSO has been deleted for this user(therefore the X'FF'); CICS has a selection ID of 02 and was last updated by userBRD on 88271 at 11:30:20. All other applications assigned to the group are avail-able to the user with default access parameters.

The USRFLAG must be in the data returned from EMSEADEX, but it is not in thedata given to the exit.

Deleting an Application from RACFWhen an application is deleted for a user, NetView Access Services callsEMSEADEX with a command of DELETE. For External groups a USERDATAentry of the following format is passed:

ðððA----------------ð1FFðð

Figure 32. Format of USERDATA Entry

Where X'000A' is the length of the following data, the hyphens represent the appli-cation name, X'01' is the length of USRDATA, X'FF' is the USRDATA indicatingthat the application has been denied to the user, and X'00' is the value for theUSRFLAG.


NetView Access Services must then determine whether this was the last applicationfor the user, either completely or within the group. It can then issue DISGROUPand DELETED requests as appropriate. NetView Access Services reads all SRTU(or pseudo SRTU) records for the user within the group. For External groups, if allapplications have been denied, then no pseudo SRTU records can be found. If nomore applications are available for the user within the group, then EMSEADEX iscalled with a command of DISGROUP (this should not attempt to disconnect theuser from the RACF default group). NetView Access Services then checks whetherthe user is defined in any other groups on the SRTU VSAM data set. If no VSAMrecords are found, then a check must be made for other externally-controlledgroups. EMSEADEX is called with a command of LSTGROUP. The exit must thenset ADEXGLPT with the address of a list of groups to which the user is connected.The format of this list is as follows:

TOTLEN DS H Length of following data

GROUP1 DS CL8 Name of group 1



Figure 33. Format of List Using the LSTGROUP Command

The GROUPn entries can be repeated as often as needed. TOTLEN must be amultiple of eight. If the user is assigned to use applications in only one group andthat group is the one from which the users association with the group has just beendeleted (this should be the RACF default group), then EMSEADEX is called with acommand of DELETED. The user can then be deleted from RACF entirely. Thesample EMSEADEX does not delete RACF profiles that do not have an owner ID ofNVAS.

Installation Requirements in RACFRACF provides a general resource profile for miscellaneous processing known asthe FACILITY class. The sample exit EMSEADEX uses FACILITY class profiles tostore external user profiles (SRTU) data in RACF. If you do not have alreadyexisting NetView Access Services profiles in the RACF FACILITY class, it is recom-

| mended that you use the IBM-supplied NVASAPDT class of RACF 1.9 or later.

RACF Profiles Processed by NetView Access ServicesThe following shows the field entries of the different RACF profiles processed bythe sample administration exit EMSEADEX.

User ProfileFigure 34 shows the structure of the user profile in the sample administration exitfor EMSEADEX:

Profile = USERKey = USERID


┌───────────┐ │ AUTHOR │ │ AUTHDATE │ │ DFLTGRP │ │ CONGRPCT │ │ CONGRPNM │ │ FLAG2 │ │ PASSWORD │ │ PASSDATE │ │ PASSINT │ │ PGMRNAME │ │ INSTDATA │ │ USERDATA │ └───────────┘

Figure 34. Structure of User Profile

AUTHOR The owner of the user profile.AUTHDATE The date that the user was defined to RACF.DFLTGRP The RACF default group associated with the user.CONGRPCT The number of groups that the user is assigned to use applications

in.CONGRPNM A list of the groups that the user is assigned to use applications in.FLAG2 Indicates whether the user has the SPECIAL attribute (bit 0 is on).PASSWORD The user’s password. NetView Access Services uses the group ID

by default.PASSDATE The date that the password was last changed.PASSINT The password change interval. NetView Access Services sets 31

days by default.PGMRNAME The user’s name. NetView Access Services fills in this field with

the first part of the installation-wide exit data.INSTDATA Installation data. NetView Access Services fills in this field with the

second part of the installation-wide exit data.USERDATA Used in NetView Access Services to indicate the user’s NetView

Access Services default group.


General Resource ProfileFigure 35 shows the structure of the general resource profile FACILITY.

Profile = GENERAL RESOURCEClass = FACILITY or ownKey = USERID_GROUPID

┌───────────┐ │ LREFDAT │ │ LCHDAT │ │ USRCNT │ │ USERDATA │ %───┐

│ USRNM │ │Repeatable │ USRDATA │ │ │ USRFLG │ %───┘ │ OWNER │ │ DEFDATE │ │ CLASTYPE │ │ ACSALTR │ │ ACSCNTL │ │ ACSUPT │ │ ACSREAD │ └───────────┘

Figure 35. Structure of General Resource Profile FACILITY

LREFDAT The date when the resource was last referenced.LCHDAT The date when the resource was last updated.USRCNT The number of applications defined for a user in a group.USERDATA Repeatable data to store application access parameters for users.

USRNM The application name.USRDATA Access data that differs from the default values for that user.USRFLG Not used for NetView Access Services.

OWNER The owner of the resource.DEFDATE The date that the resource was defined to RACF.CLASTYPE The class ID to which the resource belongs. FACILITY class has

CLASTYPE 19.ACSALTR The number of times that access was gained to the resource with

ALTER authority.ACSCNTL The number of times that access was gained to the resource with

CONTROL authority.ACSUPT The number of times that access was gained to the resource with

UPDATE authority.ACSREAD The number of times that access was gained to the resource with

READ authority.


Group ProfileFigure 36 shows the structure of the group profile.

Profile = GROUPKey = GROUPID

┌───────────┐ │ AUTHDATE │ │ AUTHOR │ │ ACLCNT │ │ USERID │ │ INSTDATA │ └───────────┘

Figure 36. Structure of Group Profile

AUTHDATE The date when the group was created.AUTHOR The owner of the group.ACLCNT The number of users in the group.USERID The user ID of each user in the group.INSTDATA Installation data. NetView Access Services fills in this field with the

second part of the installation-wide exit data.

Connect ProfileFigure 37 shows the structure of the connect profile.

Profile = CONNECTKey = USERID_GROUPID

┌───────────┐ │ AUTHDATE │ │ AUTHOR │ │ UACC │ │ INITCNT │ │ FLAG2 │ └───────────┘

Figure 37. Structure of Connect Profile

AUTHDATE The date when the profile was last updated.AUTHOR In the sample installation-wide exit, NetView Access Services is

defined as the owner of the profile.UACC The sample installation-wide exit has 'NONE' as the default uni-

versal access.INITCNT Set RACINIT counter to zero.FLAG2 SPECIAL attribute; first bit set; user is group administrator.

Synchronization of RACF and NetView Access Services DatabasesYou can use the Definition exit (EMSEADEX) to register a user to RACF or anotherequivalent security management system when a user is added to NetView AccessServices. However, the user is only added to the RACF system on the processoron which NetView Access Services is operating. The RACF systems on otherprocessors in the installation or throughout the network must be synchronized usingthe procedures or processes that currently exist.


Applications running on different hosts are generally controlled by RACF or someother security management system residing on that particular host. Therefore, auser with access to several applications on different systems must often be regis-tered on separate RACF security systems that are maintained at each host.

Users can dynamically change passwords by entering a new password in the Newfield of the NetView Access Services Logon panel. The new password is updatedonly on the RACF system of the host at which NetView Access Services resides. Ifthe same user registration is used for other applications on the same host, then thepassword change also becomes effective for those applications. However, a useris still required to change passwords for applications residing on other hosts.

The user definition can be controlled from within or outside of NetView Access Ser-vices, or from both. For example, the TSO commands ADDUSER and CONNECTcan be used. Groups must be defined in both media, but this can be achieved inone step by use of installation-wide exit EMSEADEX.

NetView Access Services provides two sample installation-wide exits, which providean interface to RACF. These are for the definition exit EMSEADEX and the logonauthorization exit EMSELGNX. Refer to Chapter 12, “Customizing NetView AccessServices Sample Exits to Interface with RACF” on page 111 for details on thesesample installation-wide exits.



Chapter 13. Customizing NetView Access ServicesInstallation-Wide Exits

This chapter describes Product-Sensitive Programming Interfaces that allow you totake advantage of NetView Access Services’s exits at strategic processing points.These installation-wide exits can be used to extend or modify the existing security,accounting, and other functions.

This chapter shows how to design, code, and install installation-wide exit routines,and also provides detailed information on the installation-wide exit routines providedby NetView Access Services.

Overview of Installation-Wide Exit RoutinesAn installation-wide exit routine is called by NetView Access Services at strategicprocessing points or exit points.

Each installation-wide exit handles a particular event such as, in the example ofuser authorization checking, the receipt of a user logon request. When that eventoccurs, NetView Access Services passes control to the appropriate installation-wideexit routine for processing. After processing, the installation-wide exit routinereturns control and passes a return code to NetView Access Services. When thereis no sample installation-wide exit routine provided, NetView Access Services pro-vides a dummy routine. Where a dummy routine is not permissible, NetViewAccess Services provides a sample that you can use.

Exit EMSELNEX varies from the other exits because it contains no executablecode. It is a table that enables extra customizing of NetView Access Services to becarried out. The use of this installation-wide exit is mandatory.

The following is a list of the installation-wide exits:

“EMSEADEX, Administration Exit” on page 132“EMSEAPAN, Automatic Logon and Logoff Exit” on page 141“EMSEATTE, Inactivity Timeout Exit” on page 143“EMSEBXML, Broadcast Exit” on page 145“EMSEDTEX, Date and Time Exit” on page 147“EMSEDVEX, Data Viewing Exit” on page 149“EMSELGFX, Logoff Exit” on page 151“EMSELGNX, Logon Authorization Exit” on page 154“EMSELNEX, Language Name Exit” on page 161“EMSELVEX, Language Verification Exit” on page 164“EMSENPME, Accounting Exit” on page 165“EMSEPRPS, Printer Presetting Exit” on page 167“EMSESEEX, Session Establishment Exit” on page 171“EMSESHRX, Shared Session Exit” on page 177“EMSESREX, Session Reselection Exit” on page 178.

Figure 38 shows the installation-wide exits.


Terminal–Related Processing

┌───────────────────┬─────────────────────────┐

│ │ │

│Terminal Logon─────┼─5Language Verification │

│ │ Exit ─ EMSELVEX │

┌────────┐ │ │ │

│Terminal├─────┤Panel Display──────┼─5Date and Time │

└────────┘ │ │ Exit ─ EMSEDTEX │

│ │ │

│Language Selection─┼─5Language Name │

│ │ Exit ─ EMSELNEX │

│ │ │

│Data Transfer──────┼─5Data Viewing │

│ │ Exit ─ EMSEDVEX │

│ │ │

│Inactivity─────────┼─5Inactivity Timeout │

│ │ Exit ─ EMSEATTE │

└───────────────────┴─────────────────────────┘

User–Related Processing

┌───────────────────┬─────────────────────────┐

│ │ │

│User Logon ────────┼─5Logon Authorization │

┌────────┐ │ │ Exit ─ EMSELGNX │

│Terminal├─────┤ │ │

└────────┘ │User Logoff/───────┼─5Logoff Exit ─ EMSELGFX │

│ Disconnect │ │

│ │ │

└───────────────────┴─────────────────────────┘

Application–Related Processing

┌───────────────────┬─────────────────────────┐

│ │ │

│Application Logon──┼─5Session │

│ │ Establishment │

│ │ Exit ─ EMSESEEX │

┌────┐ │ │ │

│APPL│ │Application Logon/─┼─5Accounting │

┌┴───┐│ │ Logoff │ Exit ─ EMSENPME │

│APPL├┘───────┤ │ │

┌┴───┐│ │Automatic Logon────┼─5Automatic Logon/Logoff │

│APPL├┘ │ │ Exit ─ EMSEAPAN │

└────┘ │ │ │

│Application────────┼─5Session Reselection │

│ Reselection │ Exit ─ EMSESREX │

│ │ │

│Data Transfer──────┼─5Data Viewing │

│ │ Exit ─ EMSEDVEX │

└───────────────────┴─────────────────────────┘

Administration–Related Processing

┌───────────────────┬─────────────────────────┐

│ │ │

│Administration─────┼─5Administration │

│ │ Exit ─ EMSEADEX │

│ │ │

│Administration─────┼─5Broadcast │

│ │ Exit ─ EMSEBXML │

│ │ │

│Administration─────┼─5Printer Presetting │

│ │ Exit ─ EMSEPRPS │

│ │ │

│Administration─────┼─5Shared Session │

│ │ Exit ─ EMSESHRX │

└───────────────────┴─────────────────────────┘

Figure 38. NetView Access Services Installation-Wide Exit Routines

Coding Requirements for an Installation-Wide Exit RoutineYou must observe the following points when writing your code:

RestrictionsWhen your code receives control, the following restrictions apply:

� Do not code your program to cause a system wait state. A system waitmay produce an interlock. For example, if an exit waits for a resource


being used by the mainline routine, the resource is not released becausethe exit is interrupting the mainline routine.

� To avoid causing a system wait state, do not issue wait macro instructions.

Variable NamesDo not use EMS as a prefix for any variable you name in your code.

Register UsageFollow these guidelines when using registers for installation-wide exit routines:

� Save registers on entry to the user code and restore them before returningcontrol to NetView Access Services. (Use standard linkage conventions tosave and restore registers.)

� Register 13 must contain the address of a standard 72-byte save area.

� Return control to the location in NetView Access Services specified by reg-ister 14.

� Do not rely on the contents of registers 2 through 12 for constant values onentry to user code. Their contents vary.

ReentranceMake sure your code is serially reusable, to enable the code to be used by oneuser or task when it is no longer being used by another.

ConsiderationsNetView Access Services supports any valid combination of AMODE andRMODE for the exit routines. The routines are always called with a BALRinstruction, so the AMODE and RMODE are inherited from the calling program.NetView Access Services is delivered to run under AMODE31 and RMODE24.

In addition installation-wide exit routines must also conform to the special require-ments described in the following paragraphs. NetView Access Services macrosmust not be used in the exit routines.

Upon entry to the installation-wide exit routine, the registers contain the followinginformation:

Installation-wide exit routines pass return codes to NetView Access Services in thereturn code (RC) field of the parameter list.

Table 9. Information Contained in the Registers

Register Contents

1 The address of the installation-wide exit parameter list.The contents of the parameter list is described in the descriptions of theappropriate installation-wide exit.

13 The address of a standard 72-byte save area used to store the caller’sregisters.

14 The return address.

15 The entry address of the installation-wide exit.

0, 2 - 12

Unspecified.

Chapter 13. Customizing NetView Access Services Installation-Wide Exits 131

See the specific installation-wide exit descriptions in this chapter for additionalreturn code considerations. The valid return codes are described in each exitdescription.

Installing an Installation-Wide Exit RoutineThe installation-wide exit routines must be installed as USERMODs using SMP.

| Sample jobs to implement installation-wide exit routines are available from the| NetView Access Services ems.v2r1m1.CUSTJOBS data set. Two jobs are

provided: one to receive and apply installation-wide exit routines and one to acceptthem. In this way you ensure that service for an exit routine is applicable and doesnot override your updates. To install the installation-wide exit routine, run the fol-lowing jobs:

EMSEXITJob EMSEXIT is used to receive and apply an installation-wide exit routine.

1. Replace umodname in the RECEIVE, APPLY, and ++USERMOD statements asrequired for your local environment.

2. Replace exitname in the ++SCR statement and in the DD statement concat-enated to //SMPPTFIN with the name of your installation-wide exit.

3. Copy the lines of your installation-wide exit routine into the job member fol-lowing the DD statement.

4. Submit the job.

5. When this job completes with a condition code of 4 or less, the installation-wideexit is installed.

EMSACCPTJob EMSACCPT is used to accept the installation-wide exit routine:

1. Replace umodname in the ACCEPT statement as required for your own localenvironment.

2. Submit the job.

3. When this job completes with return code zero, the installation-wide exit hasbeen accepted.

EMSEADEX, Administration ExitNetView Access Services can provide an elaborate interface to your external secu-rity management system. The administration and maintenance part of this interfaceis implemented in EMSEADEX. A sample interface for the RACF is supplied.RACF is the default security management system for NetView Access Services, butyou can adapt NetView Access Services to use whichever system is installed.

Note: The term RACF is used here to represent any security managementsystem.

For information on the group types mentioned in the explanation of this installation-wide exit, refer to NetView Access Services Version 2 Administration.


DescriptionEMSEADEX can be used for the following:

� Defining users in an external security management system.

� Defining NetView Access Services groups to an external security managementsystem.

� Defining administrators to an external security management system.

� Storing and retrieving nondefault application access data for users defined inExternal groups.

EMSEADEX is called when:

� The group administrator of an external group adds, updates, or deletes applica-tions for a user. The access parameters that vary from the default values arestored in RACF.

� A system administrator adds, updates, or deletes an external group.

� A system administrator adds, updates, or deletes a user’s authorization as asystem administrator, or as a group administrator for External groups.

� A list of applications is required for a user in an External group.

� It is necessary to know in which External groups a user is defined.

The source is supplied as EMSEADEX on the SEMSSRC0 library, and can be usedas supplied or as a basis for your exit. The load module supplied in SEMSLMD0 isa dummy version. It does, however, prevent you from defining an External group.

Exit Variables � &TRACE

If you wish to have an audit trail of the administration function being performedthrough administration exit EMSEADEX, you can set &TRACE to Y. In thiscase, one or more records are written to the SYSPRINT data set each timeadministration exit EMSEADEX is called. The records have the followingstructure:

– The ID (EMSEADEX)– The name of the EMSEADEX SUBROUTINE that has just been processed– The NetView Access Services administration command that EMSEADEX

has been called for– The application ID if applicable– The group ID if applicable– The LU ID if applicable– The user ID if applicable– The return code related to the SUBROUTINE name– The NetView Access Services default group indicator– The group type.

� &CHKADM

If this variable is set to Y, EMSEADEX checks the user ID of the user issuing acommand, regardless of whether it is issued by a group or system adminis-trator. The user ID of the user issuing the command must have the RACFspecial authority to perform any system administration function and at least theRACF group special authority to perform any group administration function.


When a NetView Access Services group or system administrator is defined andthe RACF interface is active (&DUMMY=N), the exit defines the administratoras a RACF group system administrator with the RACF group special attribute.This depends on whether the &RACSPEC attribute has been set to Y. Refer to&RACSPEC on page 134. RACF user profiles that already exist are modifiedin this way. If a NetView Access Services administrator is deleted, the groupspecial attribute is reset. However, a RACF administrator is not automatically aNetView Access Services administrator and must also be defined to NetViewAccess Services. If the administrator is deleted from NetView Access Services,the RACF special attribute and RACF administrator function is reset.

� &DUMMY

A dummy exit that does not use RACF is created if this variable is set to Y.Therefore, this variable must be set to N if the sample administration exitEMSEADEX is to be used. If you are planning to use External groups, youmust set this variable to N.

� &RACAD

If this variable is set to Y, user and group profiles can be added to or deletedfrom RACF. If set to N, an external group and its users must be defined toRACF before the system administrator can define the group and users. Thesample exit returns an error code if the calling module tries to add or delete auser or group profile.

This also applies when an administrator is to be added to or deleted fromRACF. An administrator can only be added or deleted when that administratoris already defined to RACF. It is recommended that you set &RACAD to N.

� &RACSPEC

This controls the setting of the group special or system special attributes in theconnect or user profiles.

If this variable is set to Y, it specifies one of the following:

– Set the group special bit in the connect profile when a user is defined as aNetView Access Services group administrator.

– Reset the group special bit in the connect profile when a user is no longera NetView Access Services group administrator.

– Set the system special bit in the user profile when a user is defined as aNetView Access Services system administrator.

– Reset the system special bit in the user profile when the user is no longer aNetView Access Services system administrator.

If set to N, setting or resetting of the group special or system special attribute inthe connect or user profiles is disabled.

| � &RACFENH

| If this variable is set to Y, then NetView Access Services handles external| groups as follows:

| – The NetView Access Services administrator must define to NetView Access| Services all the applications he wants to use with NetView Access Ser-| vices.

| – The NetView Access Services administrator must define to NetView Access| Services all the external groups he wants to use. The names of these| external groups must be the same as the RACF group names.


| – The RACF administrator should protect applications as described in RACF| Security Administrator's Guide. The RACF administrator must create a| resource in the 'APPL' class in the RACF database for each application he| wants to protect. He must also create an 'access list' for each of these| applications, where he must specify the authorized access to the applica-| tion for a specific user or for a group of users (RACF group). The name of| the resource, (that is, the name of the application to be protected), must| match the name of the application as defined to NetView Access Services.

| – When a user logs on to NetView Access Services with an external group,| NetView Access Services calls a RACF function for each application| defined in NetView Access Services to check whether or not the user, or| the group to which he belongs, is allowed to access that application. That| is, NetView Access Services scans the list of applications defined to the| system and builds the Application Selection Panel according to the informa-| tion received back from RACF. The user will therefore only be shown on| the Application Selection Panel the applications that they are allowed to| access.

| In this way, the NetView Access Services administrator need only define the| applications and the external groups to NetView Access Services, NetView| Access Services verifying user access by accessing the RACF configuration.

| Note: If an application is not protected by RACF, then NetView Access Ser-| vices assumes that the user is not authorized to use the application.

Exit Default Fields � SYSDEFGR

The value of this field is used as the default RACF group ID for any systemadministrators that are added to RACF via administration exit EMSEADEX, ifthey are not previously defined in RACF. The default value for this variable isEMS. You must ensure that a group with the ID SYSDEFGR is defined in yourRACF environment.

� OWNERNAM

Any RACF profiles including user, connect, group, and general resource pro-files that are added via administration exit EMSEADEX have the value of thisfield as its owner. The sample administration exit EMSEADEX only deletesRACF profiles that are owned by the name given to this variable. The defaultvalue for this field is NVAS. To avoid unintended accesses to the RACF data-base, ensure that no user with the ID OWNERNAM exists in your RACF envi-ronment.

� INTERVAL

When a user is added to RACF via administration exit EMSEADEX, the pass-word effective interval for that user is set to the value of this field. The defaultvalue for this field is 31.

� USERACC

When a user is connected to an RACF group via administration exitEMSEADEX, the default universal access authority assigned to the user for thatgroup is set to the value of this field. The default value for this field is NONE.

� DFLTNAME


When a user is added to RACF, the default user name in the Admin exit dataof the user is set to the value of this field. The default value for this field isNETVIEW/ACCESS USER.

� NVASAPDT

Specifies the name of the RACF general resource class into which NetViewAccess Services data are to be stored. The default value is FACILITY.

Implementing the Administration Exit Routine EMSEADEXThe NetView Access Services administration exit EMSEADEX is called for variousNetView Access administration functions.

The sample exit routine provided by NetView Access Services, for example,enables you to add and delete a user ID in your RACF data set whenever a user isdefined to, or deleted from, NetView Access Services. The object code versiondelivered with NetView Access Services is a dummy version that does not allowExternal groups to be defined. To implement the exit, refer to “Installing anInstallation-Wide Exit Routine” on page 132.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit it supplies you withthe address of a parameter list in register 1. The parameter list contains the fol-lowing fields:

� Command (8 bytes)

ADDSet when an application is added to a user.

UPDATESet when an application is updated for a user.

DELETESet when an application is deleted for a user.

DELETEDSet when the last application has been deleted for a user.

DISGROUPSet when a user’s last application within a group has been deleted. Itsignifies disconnect from the group.

ADDGROUPSet when a new group is added.

UPDGROUPSet when a group is updated.

DELGROUPSet when a group is deleted.

ADDADMINSet when a new group or system administrator is authorized.

UPDADMINSet when a group or system administrator is updated.

DELADMINSet when a group or system administrator is revoked.


VERDATASet when EMSEADEX is called as part of the screen input validationprocess for the administration panels that contain Admin Exit Data fields.The exit data entered in the fields must be validated.

GETDATASet when EMSEADEX is called during display processing. The exit datamust be retrieved and formatted as required.

GETAPPLSSet when the application data for a user in an External group is required.The complete array of user data must be retrieved and its address put inADEXUARR.

LSTGROUPADEXGLPT must be set to point to a list of groups of which the specifieduser is a member. This need only be External groups, but where Normalgroups are defined to RACF they can be included as well. See Figure 33on page 123 for the format of the LSTGROUP command.

LISTUSERADEXGLPT must be set to point to a list of users that belong to the speci-fied group. The format of the LISTUSER command is shown in Figure 39.

TOTLEN DS H Length of following data

USER1 DS CL8 Name of user 1



Figure 39. Format of List Using the LISTUSER Command

� Target application name (8 bytes).

This can be blank or an asterisk (*). When an * is entered on the Assign aUser to a Group panel to delete all the applications for a user within a group,then this installation-wide exit is invoked only once with command DELETE andADEXAPPL set to *. This is followed by a DISGROUP request and possibly aDELETED request.

� Administrator user ID (8 bytes).

This is the NetView Access Services user ID of the administrator.

� User ID (8 bytes).

This is blank for group-related requests.

� Group ID (8 bytes).

This is blank when ADDADMIN, UPDADMIN, and DELADMIN are issued for asystem administrator.

� Terminal LU name (8 bytes).

When a specific LU name is given using option 3, Assign a User to a Group,this is given here. Otherwise this field is blank. It is only provided for ADD,UPDATE, and DELETE requests.

� Return code field (1 byte).

This is the return code from the exit.


� Suppress message EMS0655 indicator (1 byte).

Normally a nonzero return code from EMSEADEX causes a message to be dis-played at the console. This message can be suppressed by setting this indi-cator to Y before returning. This is of most use during VERDATA processing,but can be used for any command or return code. Setting it to N (or any othervalue) means Do not suppress the console message.

� Installation-wide exit generated message length (2 bytes).

Messages to be displayed to the user (administrator) can be returned from theexit when a VERDATA command is processed. The length of the messagemust be set in this field. If no message is required, this must be zero. Thislength is used in conjunction with the following address. The message ID isalways EMS1398.

� Installation-wide exit generated message address (4 bytes).

This is used in conjunction with the previous (length) field. The address of themessage must be set in this field. If no message is required, this must be zero.

� Installation-wide exit data address (4 bytes).

The Assign a User to a Group, Define a Group, and Define an Administratorpanels each have a 60-byte field labeled Admin Exit Data. The data given hereis passed directly to the exit. The format of the data is installation dependent.The address of the data given here must not be changed. For GETDATA proc-essing the data must be returned in the 60-byte area with this address. Whenthe command is DELETE, DELETED, or DISGROUP this address may be zero.

� RACF ACEE address (4 bytes).

If EMSELGNX has saved the RACF ACEE for the administrator, its address isgiven here. Otherwise this is zero. If the ACEE is re-created or deleted for anyreason, this field must be reset accordingly.

� Group list address (4 bytes).

When EMSEADEX is called with the command LSTGROUP or LISTUSER, theaddress of the list created must be returned here. See Figure 33 on page 123for the format of the group list, and Figure 39 on page 137 for the format ofthe LISTUSER command.

� User application array address (4 bytes).

This is the address of an area containing the application data to be stored inthe RACF user data array. There are one or more entries present. The formatof this data exactly matches the RACF USERDATA array found on each profiletype. If you adapt EMSEADEX for use with an external media other thanRACF, you must ensure compatibility with this format. When the array is givento this installation-wide exit (that is, commands other than GETAPPLS) youmust FREEMAIN the area after use. For GETAPPLS you must set thisaddress to point to your area. This area is not freed after use so it is sufficientto get one area when EMSEADEX is first invoked and continue using this.

� Overall length of application user data array area (2 bytes).

This is a halfword containing the total length of the area containing the applica-tion user data array. The actual data may not occupy all of the area. Thislength must be used to FREEMAIN the area. For the GETAPPLS request thisfield is reserved for future use.


� Subpool of the application user data array area (1 byte).

This is the subpool number that must be used to FREEMAIN the applicationuser data array area. For the GETAPPLS request this field is reserved forfuture use.

� NetView Access Services default group indicator (1 byte).

This is the value of the default group indicator from the Assign a User to aGroup panel. This enables the value to be stored in the USERDATA field ofthe user’s RACF profile. For administrator requests (for example, ADDADMIN)it is blank.

� Group type (1 byte).

This is the group type as entered on the Define a Group panel:

N Normal NetView Access Services groupE External groupP Public group.

� Type of administrator

This is the type of administrator entered on the Define an Administrator panel:

S System administratorG Group administratorB Broadcast administrator.

Table 10 shows the layout of the parameter list for this installation-wide exit.

Table 10. Layout of Parameter List for EMSEADEX, Administration ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 79 ADEXPRMS Parameter list for EMSEADEX0 (0) CHARACTER 8 ADEXCMD Command: For example, ADD and DELETE8 (8) CHARACTER 8 ADEXAPPL Target application name

16 (10) CHARACTER 8 ADEXAUID Administrator user ID24 (18) CHARACTER 8 ADEXUID User ID32 (20) CHARACTER 8 ADEXGID Group ID40 (28) CHARACTER 8 ADEXLU Terminal LU name48 (30) UNSIGNED 1 ADEXRC Return code49 (31) CHARACTER 1 ADEXSUPP Y=Suppress console message 65550 (32) SIGNED 2 ADEXMLEN Length of user message52 (34) ADDRESS 4 ADEXMPTR Pointer to user message56 (38) ADDRESS 4 ADEXDATA Pointer to 60 byte user data60 (3C) ADDRESS 4 ADEXACEE RACF ACEE address64 (40) ADDRESS 4 ADEXGLPT Group list pointer68 (44) ADDRESS 4 ADEXUARR Pointer to application data array72 (48) SIGNED 2 ADEXULEN Length of application data array74 (4A) UNSIGNED 1 ADEXSUBP Subpool of application data area75 (4B) CHARACTER 1 ADEXNVDG Default group indicator: Y/N76 (4C) CHARACTER 1 ADEXGTYP Group type: P=Public/E=External/N=Normal77 (4D) CHARACTER 1 ADEXATYP Type of administrator: S=System/G=Group/

B=Broadcast78 (4E) CHARACTER 1 * For future use


Return CodesThe installation-wide exit must return one of the following return codes to the callingmodule:

RC MeaningX'00' Processing without error.Not X'00'

Error occurred during processing. The return code is displayed along withmessage EMS0655, unless ADEXSUPP is set to Y. The return code maybe a RACF return code or a return code issued by the exit (see the fol-lowing). All EMSEADEX commands are issued before updating, so anonzero return code prevents the update occurring. Any nonzero returncode from VERDATA causes the message:

EMS1315E Installation-wide exit checking has rejected the request

to be issued, unless ADEXMLEN and ADEXMPTR are set. GETDATArequests are also issued before updating the NetView Access Servicesprofiles, but a nonzero return code does not prevent the display from com-pleting (but without the installation-wide exit data). All other commandsare issued after the NetView Access Services profile update, so the returncode does not prevent the update from occurring.

The following nonzero return codes can be issued by the exit:

RC MeaningX'E0' User name exceeds 20 bytes on VERDATA request.X'E1' User installation data truncated on GETDATA request.X'E2' Group installation data truncated on GETDATA request.X'E3' Admin exit data not * for user ID *.X'E4' Admin exit data specified as * when application ID is *.X'E5' Your installation has customized EMSEADEX to reject requests for

external groups.X'E6' Your installation has customized EMSEADEX so that only RACF updates

but no add or delete commands are allowed.X'E7' Deletion of a group is not allowed if users are still defined to it.X'E8' EMSEADEX call is only allowed for external groups.X'FA' Default group not deleted.X'FB' Freemain failed.X'FC' Getmain failed.X'FD' Invalid command in parameter list.X'FE' Program is not APF authorized.X'FF' Administrator is not authorized to perform the request.

All other codes are from the RACF ICHEINTY macro.

The exit routine must be link-edited to form a load module called EMSEADEX. Noother name is valid. It must have the NON-REUS linkage editor option. When theRACF ICHEINTY macro is used the whole NetView Access Services load librarymust be APF authorized. For information on the ICHEINTY macro refer to SystemProgramming Library: Resource Access Control Facility (RACF).


EMSEAPAN, Automatic Logon and Logoff ExitThis installation-wide exit is to identify where the user is in the automatic logon orlogoff sequence, using the concept of a panel ID. NetView Access Services callsthis installation-wide exit to return such a unique ID during recording, and duringautomatic logon or logoff. An installer can create an installation-wide exit routinefor any in-house applications that are used through NetView Access Services.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it gives you theaddress of a parameter list in Register 1. The parameter list contains the followingfields. An asterisk (*) indicates that these fields are filled in on return from theroutine:

� Application ID (8 bytes).

This is for optional use by the installation-wide exit. This is the group-widename of the application, not the system-internal name.

� NetView Access Services user ID (8 bytes).

This is for optional use by the installation-wide exit. When developing aninstallation-wide exit routine for use by NetView Access Services, you mightwish to restrict usage of the exit routine to yourself or selected users until theroutine is fully tested.

� Address of a data buffer transmitted by the application (without header informa-tion).

This is a variable length data buffer, and must not be overwritten by the exitroutine. A description of the buffer header is supplied in Chapter 14, “WritingNew Application Service Routines” on page 183.

� Panel ID (8 bytes). * To be filled in by the installation-wide exit routine.

� Keyboard Reset Y/N (1 byte). *

� Erase-Write Y/N (1 byte). *

� Return code field (1 byte). *

� Reserved for future use (1 byte).

NetView Access Services provides a sample EMSEAPAN routine.


Table 11 (Part 1 of 2). Layout of Parameter List for EMSEAPAN, Automatic Logon and Logoff ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 34 APANPRMS Parameter list for EMSEAPAN0 (0) CHARACTER 8 APANAPID Application name8 (8) CHARACTER 8 APANUID User ID

16 (10) ADDRESS 4 APANDPTR Data buffer pointer20 (14) CHARACTER 10 APANPWCC Panel ID + reset keyboard indicator20 (14) CHARACTER 8 APANPNID Panel ID28 (1C) CHARACTER 1 APANWCC Keyboard reset: Y/N29 (1D) CHARACTER 1 APANEW Erase/write: Y/N30 (1E) CHARACTER 1 APANRC Return code31 (1F) CHARACTER 1 APANPSPN Send permitted now32 (20) CHARACTER 1 APANLILO Log in/log out


Table 11 (Part 2 of 2). Layout of Parameter List for EMSEAPAN, Automatic Logon and Logoff ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 33 (21) CHARACTER 1 APANBITS Information bits

1... .... APAN16BM 1=16 Bit mode addressing, 0=12/14 bit modeaddressing.Check SBA bit 0 and 1 00=14 bit mode01=12 bit mode 10=reserved/invalid11=12 bit mode

.1.. .... APAN132U 1=132 columns used, 0=80 columns used ..1. .... * Free ...1 .... * Free .... 1... * Free .... .1.. * Free .... ..1. * Free .... ...1 * Free


RC Meaning

X'00' Panel ID returned in panel ID field (last panel ID).

X'02' Panel ID returned in panel ID field (not the last panel ID).

X'04' No panel ID found by the routine. Automatic logon is terminated and theuser logs on manually.

Sample Automatic Logon and Logoff ExitThis installation-wide exit is called during automatic logon recording and playbackto extract up to 8 bytes of panel identifier from the application response. Only databytes from the response are used to construct the panel identifier. Attribute bytesand control characters are discarded. Multiple panel identifiers can be generatedfrom an application response that contains one or more Set Buffer Address (SBA)orders. The exit performs the following functions:

� Scans each character of the application response stored in the NetView AccessServices buffers.

� Builds a panel identifier using data bytes from one or more of the followingcommands, orders, structure fields, or all in the data stream:

– Write – Erase/Write – Erase/Write Alternate

– Repeat Address Order– 3270 data structure field (type X'40') with a write structure command.

All data bytes except hexadecimal zero and blank are used.

� Skips over all 3270 orders during the scanning process except for the RepeatAddress (RA) order.

� Skips over all structure field types associated with a Write Structure Field(WSF) command during the scanning process except for the 3270 data streamstructure field type (type X'40').


� When an SBA order with a valid address is encountered, the scanning processis stopped. The valid data bytes found in the data stream up to the point ofthis SBA are then compared with the following VM indicators:

– RUNNING – VM READ – CP READ – MORE... – HOLDING.

If a match is found, then this panel identifier is discarded, and the scanningprocess is resumed to build a new panel identifier. If the panel identifier doesnot match a VM indicator, then the data bytes are compared to the reply of aTIME or DATE command. If the data bytes resemble the TIME or DATEformat, XX is substituted for the numeric date/time counters in the panel identi-fier. If less than 8 valid data bytes are found, hexadecimal zeros are padded tocomplete the 8-byte panel identifier. The exit is then terminated. A conditioncode of 02, together with the current buffer and addresses are passed, using asaved area, to the caller of the exit. This signals that an additional panel identi-fier must be created by calling this installation-wide exit again.

� If the end of the current buffer is reached and there are additional data buffers,then the scanning process is continued with the next buffer in the chain.

� When the end of the application response is reached, the panel identifier withthe data bytes found is reformatted if it has the DATE/TIME format. An XX issubstituted for the numeric fields in the DATE/TIME format. The exit is thenterminated.

� During the scanning process, if an ERASE/WRITE command is encountered,an ERASE/WRITE indicator is turned on. If the keyboard restore bit in theWCC is found, then a keyboard restore indicator is turned on.

� If a terminal hang occurs during auto logon or logoff, refer to the documentationwithin the module EMSEAPAN on how to circumvent such situations.

EMSEATTE, Inactivity Timeout ExitThis installation-wide exit, in addition to the existing NetView Access Services idle-time checking function, allows sessions at terminals displaying the NetView AccessServices Logon panel to be deallocated after a given time.

The exit is invoked in one-minute intervals to check whether the inactivity timeoutfunction is to be used for this one minute time interval or not. This check is calledthe enabling check, and is indicated to the exit by passing a blank terminal statusvalue. If the enabling check indicates that the exit is to be used, NetView AccessServices scans the status of all terminals and reinvokes the exit for all terminalsdisplaying the NetView Access Services Logon panel. If the idle-time value in theexit exceeds that for the terminal, the terminal session is deallocated. The exit canbe used to cause NetView Access Services to deallocate a terminal session imme-diately or to keep a terminal session without idle time checking.


Parameter List Fields� Indicator for enabling the exit (1 byte).

This field indicates to NetView Access Services whether the exit is to be usedor not for the inactivity check. The value can be Y or N. Any other value ishandled as if N is specified. If Y is specified, NetView Access Services startsinvoking the exit for terminals displaying the NetView Access Services Logonpanel. The value in this field is checked at one-minute intervals. The value isignored if the exit is used for idle time checks.

This field can be used to increase the checking interval. For example, if onlythe fifth invocation is to enable the exit, then the idle-time checking interval isfive minutes.

If the enabling check is performed, the terminal status field contains a blankvalue.

� Terminal Status (1 byte).

This field contains the status of the terminal. 'L' indicates that the terminal isdisplaying the NetView Access Services Logon panel. A blank specifies thatthe enabling check is to be performed by NetView Access Services. The valuein this field is passed from NetView Access Services to the exit. The value isignored on return to NetView Access Services.

� NETID of the Originator (8 bytes).

This field contains the NETID of the originator. If the NETID is not provided,this field contains '********'.

The value in this field is passed from NetView Access Services to the exit. Thevalue is ignored on return to NetView Access Services.

� Terminal ID of the Originator (8 bytes).

This field contains the VTAM LU name of the terminal at which the user isusing NetView Access Services. The value in this field is passed from NetViewAccess Services to the exit. The value is ignored on return to NetView AccessServices.

� Time Stamp (8 bytes).

This field contains the time of day (TOD) clock output provided by the system.The time stamp is actualized by NetView Access Services each time terminalinput is received from this terminal LU by NetView Access Services.

The value in this field is passed from NetView Access Services to the exit. Thevalue is ignored on return to NetView Access Services.

� Idle Time Value (2 bytes).

The value in this field is passed from the exit to NetView Access Services. Itspecifies the allowed idle time in minutes for the terminal defined in the NETIDand terminal ID fields. If the idle time is greater than the value passed in theidle time value field, the terminal is deallocated by NetView Access Services.

The following list shows the possible idle time values and their meaning:

Value Explanation

0 This causes NetView Access Services to cancel the terminal sessionimmediately.


1 - 32766 (X'7FFE')A value in this range specifies the idle time in minutes.

32767 (X'7FFF')This value causes NetView Access Services to keep the terminal session.No idle time check is performed.

Note: The high order bit is ignored by NetView Access Services.


Table 12. Layout of the Parameter List for EMSEATTE, Inactivity Timeout ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) CHARACTER 1 ATTDUSE Indicator for enabling the exit Y/N1 (1) CHARACTER 1 ATTDSTA Terminal status2 (2) CHARACTER 8 ATTDNETO NETID of the originator

10 (A) CHARACTER 8 ATTDTID Terminal ID of the originator18 (12) CHARACTER 8 ATTDTOD Time stamp26 (1A) BITSTRING 2 ATTDIT Idle time value

...1 11.. ATTDTOTL “*-EMSEATTD” Length of DSECT EMSEATTD

A sample EMSEATTE module suppresses the use of this installation-wide exit byspecifying N in the field for enabling the exit.

EMSEBXML, Broadcast ExitThis installation-wide exit (which is the user-written application) provides informationabout the state of every message in the NetView Access Services system.

The exit is called by NetView Access Services every time a Broadcast message is:

� Added to the NetView Access Services system by the administrator� Deleted from the NetView Access Services system by the administrator� Stopped by a timer event (this means, that the stop time of the Broadcast

message has elapsed)� Stopped and purged by a timer event (this means, that the stop time of a

Broadcast message has elapsed and the Broadcast message is removed out ofthe VSAM cluster EMSDBROD).

All Broadcast message definitions (defined by the administrator) are stored in abuffer. The structure of this buffer is defined in parameter list EMSEXML. Theaddress of the Broadcast message information buffer is passed to the exitEMSEBXML (which is the user-written application) via register 1. The buffer itselfis defined of variable length.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, the address ofparameter list EMSEBXML is passed in register 1. The parameter list contains thefollowing fields:

� Length of the buffer (2 bytes). The field type is binary.

� The Language and Message ID (4 bytes). The format of this field isMMMMMMLL where MMMMMM is the message ID and LL is the language ID.This field represents the key of the message in the system. The field type ishexadecimal.


� The user ID (8 bytes). The field type is character.

� The date (8 bytes). The field type is character.

� The time (8 bytes). The field type is character.

� The status information of a message (1 byte). This information is given byflags as follows:

'1.......' interruptive message'.1......' time controlled message'..1.....' purge message indication'...1....' double-byte character use'....1...' message is active'.....111' IBM reserved

The field type is binary.

� The name of the group the message is sent to (8 bytes). The field type ischaracter.

� The user ID to which the message is sent to (8 bytes). The field type is char-acter.

� The name of the VTAM-LU the message is sent to (8 bytes). The field type ischaracter.

� The name of the system application the message is sent to (8 bytes). The fieldtype is character.

� The name of the group application the message is sent to (8 bytes). The fieldtype is character.

� The date at which the message was started (8 bytes). The content of this fieldis date (YYYYMMDD). The field type is character.

� The time at which the message is started (8 bytes). The content of this field istime (HHMM). The field type is character.

� The date at which the message was stopped (8 bytes). The content of thisfield is date (YYYYMMDD). The field type is character.

� The time at which the message is stopped (8 bytes). The content of this fieldis time (HHMM). The field type is character.

� The length of the message text (2 bytes). The field type is binary.

� The pointer to the message text (4 bytes). The field type is binary.

A dummy routine for this installation-wide exit is provided. The name of the routineis EMSEBXML.


Table 13 (Part 1 of 2). Layout for Parameter List for EMSEBXML, Broadcast ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) SIGNED 2 BXMLBLEN Total buffer length2 (2) SIGNED 2 Alignment4 (4) SIGNED 4 BXMLMLID Message and language ID (MMMMMMLL)4 (4) CHARACTER 3 BXMLMID Message ID (MMMMMM)7 (7) CHARACTER 1 BXMLLID Language ID (LL)8 (8) CHARACTER 24 BXMLLUPD Last update information


Table 13 (Part 2 of 2). Layout for Parameter List for EMSEBXML, Broadcast ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 8 (8) CHARACTER 8 BXMLLUID Last update user ID of administrator

16 (10) CHARACTER 8 BXMLLUDA Last update date of the message24 (18) CHARACTER 8 BXMLLUTI Last update time of the message32 (20) CHARACTER 1 BXMLSTAT Status flags of the message

1... .... BXMLSTII X'80' interruptive message .1.. .... BXMLSTTI X'40' timer-driven message ..1. .... BXMLSTPI X'20' purge message indication ...1 .... BXMLSTDB X'10' double-byte character use .... 1... BXMLSTAC X'08' message is active

33 (21) CHARACTER 8 BXMLGNAM Group the message is addressed to41 (29) CHARACTER 8 BXMLUNAM User the message is addressed to49 (31) CHARACTER 8 BXMLTNAM Terminal the message is addressed to57 (39) CHARACTER 8 BXMLSAPP System application the message is addressed to65 (41) CHARACTER 8 BXMLGAPP Group application the message is addressed to73 (49) CHARACTER 8 BXMLSTRD Date of message start81 (51) CHARACTER 4 BXMLSTRT Time of message start85 (55) CHARACTER 8 BXMLSTOD Date of message stop93 (5D) CHARACTER 4 BXMLSTOT Time of message stop97 (61) CHARACTER 1 Alignment98 (62) SIGNED 2 BXMLLMES Length of message text

100 (64) ADDRESS 4 BXMLDPTR Address of message block .11. 1... BXMLLENC "*-EMSEXML" Length of DSECT

Return CodesThere are no return codes from this installation-wide exit.

EMSEDTEX, Date and Time ExitThis installation-wide exit is called whenever a date and time field is being preparedfor display on a NetView Access Services panel. It contains sample coding for theUS date format (MM/DD/YY) as well as for other formats. The exit allows the dateand time to be displayed in whichever format is required, for example DD/MM/YY orMM/DD/YY.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it supplies you withthe address of a parameter list in register 1. The parameter list contains the fol-lowing fields, and the items marked * must be supplied in the exit:

� Date to be processed (5 bytes).This is zoned decimal in the form YYDDD. For example, the 17th June 1994would be 94168, that is the 168th day of year 94.

� Output date in short format (8 bytes). *This is always used for the date in the last update information.

� Output date in long format (24 bytes). *This is always used for the date when the current date is displayed. Althoughthe field is defined as 24 bytes, the actual amount of data displayed isdependent on the length of the field N1 found on EMSP00 and EMSP01. Thisis normally 8 bytes. If you choose a longer date format (for example, 3January 1994), you must make the date field longer on these two panels. Thelength of a field on the panel is the space between two attributes, the field ispadded with blanks or truncated on the right accordingly.


� Time to be processed (6 bytes - zoned decimal - hhmmss).

� Output time (8 bytes - character). *


This enables the terminal location to be used in deciding the date format. Forexample, terminals located in the US and the UK might both use the sameEnglish messages and panels. Based upon the terminal naming conventionthe UK users could see dates in the European format and the US users in theAmerican format.

� Language code for this terminal (1 byte - hexadecimal).

This is a 1-byte binary number in the range X'01' to X'08'.

Table 14 shows the layout of the parameter list to this installation-wide exit.

Table 14. Layout of Parameter List for EMSEDTEX, Date and Time ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 60 EMSDDTEX0 (0) CHARACTER 5 DTEXDATI Input date in format 'YYDDD'

0 (0) CHARACTER 2 DTEXYY Input year2 (2) CHARACTER 3 DTEXDDD Input day5 (5) CHARACTER 8 DTEXDATS Output date short format

13 (D) CHARACTER 24 DTEXDATL Output date long format37 (25) CHARACTER 6 DTEXTIMI Input time in format 'HHMMSS'43 (2B) CHARACTER 8 DTEXTIMO Output time51 (33) CHARACTER 8 DTEXTERM Terminal LU name59 (3B) UNSIGNED 1 DTEXLANG Language in use at this terminal

Return CodesThere are no return codes from this installation-wide exit. The output fields mustbe set to blank or some meaningful text if an error occurs.

Sample Date and Time ExitThere is a sample routine provided by NetView Access Services. This returns dateformats in accordance with the selected language ID as follows:

For language 1: MM/DD/YY

For language 2: DD.MM.YY

For language 3: DD.MMM.YY

For language 4: MM/DD/YY

For language 5: DD/MM/YY

For language 6: DD/MM/YY

| For language 7: MM/DD/YY

| For language 8: MM/DD/YY

Figure 40. Sample Date and Time Exit

Other formats are available in the sample exit. This exit must be used if you wantthe date and time to appear. It cannot be replaced by a dummy.


EMSEDVEX, Data Viewing ExitThis installation-wide exit is entered whenever a user works with an application inrelay mode, and allows the transfer of data between a terminal and an applicationto be analyzed. The exit can view the data only. Any modification to the data isignored. The exit is not called when the user enters data on any NetView AccessServices panel, including the Logon panel.

NetView Access Services allows the exit to view the 3270 datastream format, thatis, in the same format that NetView Access Services receives from or sends to anapplication. Because sensitive data such as passwords are passed to the exit, theexit must be activated using the following ZAP:

// ...

//SYSIN DD \

NAME EMSEUS EUSZAP

VERIFY ðððð ðððððð

REP ðððð ððððð1

/\

This ZAP assumes that you are not sharing VSAM data sets between differentNetView Access Services systems. If you share a common VSAM profile betweenNetView Access Services systems, you must modify the ZAP so that the appro-priate data sharing bits are set correctly. For further information, refer to “SharingVSAM Data Sets” on page 22. In the following, the first two bytes in the ZAP areacorrespond to data sharing and the third byte corresponds to the data viewing exit.

DCL

1 EUSZAP BASED, /\ switch area \/

3 \ BIT(6), /\ for VSAM sharing \/

3 X_SYS BIT(1), /\ =1, cross system VSAM

sharing required \/

3 VSLOCK BIT(1), /\ =1, enable LOCKING of

VSAM requests \/

3 \ BIT(8), /\ for VSAM data sharing \/

3 \ BIT(7), /\ for future use \/

3 DVEX BIT(1); /\ =1, call data viewing exit

Figure 41. ZAP Area for Data Viewing Exit

If you enable the data viewing exit, all terminal and application data is passed tothe exit. The exit must decide which data is to be processed and which data is tobe ignored.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it supplies theaddress of a parameter list in register 1. The parameter list contains the followingfields:


The NetView Access Services user ID.


The NetView Access Services group ID.

� Group-wide application name (8 bytes).


This is the application name selected from the Application Selection panel.

� System-internal name (8 bytes).

This is the system-internal name specified on the Define an Application for theSystem panel.


� ACB name of this NetView Access Services (8 bytes).

� Secondary LU name (8 bytes).

This secondary LU name is used by NetView Access Services to establish arelay-mode session.

� Primary LU name of the target application (8 bytes).

� Mapped terminal LU logmode entry name (8 bytes).

This is the logmode name contained in the NetView Access Services suppliedlogmode table EMSMODE. This logmode is used by NetView Access Servicesto establish a relay-mode session with an application if the user does notspecify a different logmode using the LM command on the Application Selectionpanel. Any change on return from the exit is ignored.

� Logmode used to establish a relay-mode session (8 bytes).

This is the logmode specified by a user with the LM command.

� Address of data area (8 bytes).

This is the address of the data area containing the data provided to the exit.

� Length of data in data area (4 bytes).

� Return code (4 bytes).

The return code from the data viewing exit is ignored.

� PSERVIC data (5 bytes).

This field contains the size of the primary and alternative screen size as speci-fied in the PSERVIC data.

� Event (1 byte).

This field indicates the event type that has called the exit:

I Exit is called during NetView Access Services initialization.D Exit is called to provide received data.E Exit is called during NetView Access Services termination.

� Direction (1 byte).

This field indicates the direction in which data is transferred:

T Data has been received from the terminal and is routed to the application.A Data has been received from the application and is routed to the terminal.

� Original terminal LU logmode entry name (8 bytes).

This is the logmode entry name supplied by VTAM.



Table 15. Layout of the Parameter List for EMSEDVEX, Data Viewing ExitOffsets

Type Length Name DescriptionDec Hex 0 (0) CHARACTER 8 DVEXUID NetView Access Services logon user ID8 (8) CHARACTER 8 DVEXGID NetView Access Services logon group ID

16 (10) CHARACTER 8 DVEXAPPL NetView Access Services group-wide applicationname

24 (18) CHARACTER 8 DVEXSID NetView Access Services system-wide applicationname

32 (20) CHARACTER 8 DVEXTLU Real terminal LU name40 (28) CHARACTER 8 DVEXNVAS Main ACB name of NetView Access Services48 (30) CHARACTER 8 DVEXSLU Pseudo terminal LU name56 (38) CHARACTER 8 DVEXPLU Target application LU name64 (40) CHARACTER 8 DVEXTMOD Mapped terminal LU logmode entry name72 (48) CHARACTER 8 DVEXSMOD Logmode name of relay-mode session80 (50) ADDRESS 4 DVEXDPTR Address of data area84 (54) BITSTRING 4 DVEXDLEN Length of data in data area88 (58) BITSTRING 4 DVEXRC Return Code92 (5C) CHARACTER 5 DVEXPS Primary and alternative screen size value

taken from PSERVIC field of BIND97 (61) CHARACTER 1 DVEXEVNT I=Initialization of EMSEUS/D=Data (see

DVEXDIR)/E=End of EMSEUS98 (62) CHARACTER 1 DVEXDIR T=Data received from terminal/A=Data received

from application99 (63) CHARACTER 8 DVEXOTMN Original terminal LU logmode entry name

107 (6B) CHARACTER 5 For future use .11. 1... DVEXTOTL "*-EMSDDVEX" Length of DSECT EMSDDVEX

Sample Data Viewing ExitA dummy exit is provided as a sample to return immediate control to the callingmodule.

Notes:

1. 0-RUs (send/receive requests without data) cause a call of EMSEDVEX. Theyare indicated by a data length of zero.

2. Do not code a wait in the exit. The exit is a synchronous exit and coding await would cause a hang of all users logged on to NetView Access Services.

EMSELGFX, Logoff ExitThis installation-wide exit is entered whenever a user logs off or disconnects aNetView Access Services session by using the LOGOFF or DISC commands, or ifthe idle time is reached. It is also entered when the EXIT command is used. DISCcan be assigned to a PF key on the Application Selection panel. Each commandcan be entered via the command prefix on a panel of an application.A DISC command can be automatically scheduled in certain error situations, forexample, lost terminal. EMSELGFX is not called when a relay or pass-modesession between NetView Access Services and an application is terminated, orwhen LOGOFF is entered on the NetView Access Services Logon panel to returnto VTAM.

This installation-wide exit can be used if you want the DISC command, entered onsome terminals, to be treated like the LOGOFF command.


Parameter List FieldsWhen NetView Access Services calls this installation-wide exit it supplies theaddress of a parameter list in register 1. The parameter list contains the followingfields:



� ACB name of this NetView Access Services system (8 bytes).

� NetView Access Services group ID (8 bytes).

� Logoff or Disconnect indicator (1 byte).

This is set to:

L When a user logoff is in progress.D When a disconnect is in progress.M During a multiterminal session a user can log off from one terminal,

causing all the other terminals to be logged off as well. For these sec-ondary logoffs, EMSELGFX is called with an indicator of M.

The exit is finally called with an indicator of L for the terminal at which the logoffwas requested.

� Return code (1 byte - hexadecimal).

� Group type (1 byte).

This is the group type. If it has changed, this is the value as it was when theuser logged on:

N Normal NetView Access Services group.E External group.P Public group.

� Deallocate terminal flag (1 byte-character).

Normally the Logon panel is sent to the terminal after a user has logged off ordisconnected. If you want certain terminals to be deallocated and returned toVTAM, then this flag must be set to Y. This may be particularly useful fordialed lines. The default on entry is N. All other values returned result in N.


This is the address of the RACF ACEE created in the logon exit. The otherexits may have changed the address in the meantime. The ACEE must bedeleted in this installation-wide exit. After it has been deleted, the addressmust be set to zero. If no ACEE is present, the address is zero. If you do notsave the address in EMSELGNX, this address may be used for whateverpurpose you wish, for example a terminal-related work area.

� Fill Logon panel on NetView Access Services time-out (1-byte character)

This specifies whether or not the Logon panel is displayed with the fields auto-matically filled in when NetView Access Services time-out occurs. If Y is speci-fied, the Logon panel is displayed with the fields filled in. If N or any othervalue other than Y is returned, the normal NetView Access Services time-outoccurs (Logon panel displayed with no fields filled in). The default is N.

The fields that are filled in depends on which panel the user is using when thetime-out occurs. If the user is on an EUS panel, the User and Group fields arefilled in. If the user is on a panel of an application, the User, Group, and Appli-


cation fields are filled in. In both cases, the cursor is positioned in the Pass-word field and a message prompts the user to enter the password to reconnect.

� Fill Logon panel on NetView Access Services disconnect (1-byte character)

This specifies whether or not the Logon panel is displayed with the fields auto-matically filled in when the user disconnects from NetView Access Services. IfY is specified, the Logon panel is displayed with the fields filled in. If N or anyother value other than Y is returned, the normal NetView Access Services dis-connect occurs (Logon panel displayed with no fields filled in). The default isN.

The fields that are filled in depends on which panel the user issues the DISCcommand. If the user issues the DISC command on the Application Selectionpanel, the User and Group fields are filled in. If the user issues the DISCcommand on a panel of an application, the User, Group, and Application fieldsare filled in. In both cases, the cursor is positioned in the Password field and amessage prompts the user to enter the password to reconnect.


Table 16. Layout of the Parameter List for EMSELGFX, Logoff ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 44 EMSELFXP Parameter list for EMSELGFX0 (0) CHARACTER 8 LGFXTID Terminal ID8 (8) CHARACTER 8 LGFXUID User ID

16 (10) CHARACTER 8 LGFXNVAS NetView Access Services ACB name24 (18) CHARACTER 8 LGFXGID Group ID32 (20) CHARACTER 1 LGFXTYPE L=Logoff/D=Disconnect/M=Multiterminal

secondary logoff33 (21) CHARACTER 1 LGFXRC Return code34 (22) CHARACTER 1 LGFXGTYP Group type35 (23) CHARACTER 1 LGFXDEAL Deallocate terminal: Y/N36 (24) ADDRESS 4 LGFXACEE RACF ACEE address40 (28) CHARACTER 1 LGFXFLTI Fill Logon panel on NetView Access Services

time-out: Y/N41 (29) CHARACTER 1 LGFXFLDI Fill Logon panel on NetView Access Services discon-

nect: Y/N42 (2A) CHARACTER 2 * For future use

Return CodesThe following return codes are expected:

RC MeaningX'00' Normal.X'01' Load module not APF authorized.X'02' System authorization facility not active.


X'FF' Disconnect request must be treated as a logoff. The exit is called againwith LGFXTYPE set to L, one or more M type calls might also follow.

Notes:

1. If using return code X'FF', it is advisable to set the multiterminaloption for affected groups to N. This is done on the Define a Grouppanel.

2. Treating a Disconnect as a Logoff is ignored for all terminals in amultiterminal session with the exception of the terminal from which theLF command is issued.

Other RACF return codes may occur. Refer to “Return Codes for EMSELGNX” onpage 160.

For all other return codes the message:

EMSð666E INVALID RETURN CODE XX RECEIVED FROM MODULE EMSELGFX IN MODULE EMSEDISC

is issued (normally to the console unless rerouted to SYSPRINT in the messagetable).

Sample Logoff ExitThere is a sample routine provided by NetView Access Services that performs thefollowing functions:

� Tests for APF authorization. If not authorized, a return code of X'01' is givenand the exit is terminated.

� Deletes the RACF ACEE if the address is not zero.

� Requests that certain terminals be deallocated. You can adapt this function bychanging a list of generic terminal names in the exit (TERMLIST).

EMSELGNX, Logon Authorization Exit| This installation-wide exit can be used for:

| � Providing an interface to your security manager to check user logon authori-| zation.

| � Auditing and measuring. For example, you might want to write system meas-| urement facility (SMF) records, if you are not using the NPM interface.

| The sample exit can be replaced with a user-written exit to interface with another| security management system.

| Description| The exit routine is entered when user ID and password information is entered on| the NetView Access Services Logon panel or when BIND user data is sent from the| application that calls NetView Access Services (for example, VTAM). All informa-| tion except the location field information is passed to the exit. In this case the| Session Establishment Exit EMSESEEX is called. (For additional information refer| to page 171.) The exit can be called as often as you like for secondary| authentication.


| The exit can be used to decide whether or not a user ID and password is required.| If no user ID is given, and this is acceptable, then the exit must supply a value in| the LGNXUID field before returning. The terminal ID is a suitable value.

| If a user is to be logged on in a Public or an External group, then the value of| LGNXGRID may not be blank on return from this installation-wide exit. The value| must be entered by the user or generated in the exit.

| If the DIRLOGON parameter has been specified in the APPL statement, NetView| Access Services customers have to code the EMSELGNX logon exit to set up the| logon parameters (user ID, group ID, and so on) for this terminal session. The| logon exit will also have to manage errors that are normally displayed at the ter-| minal on the Logon panel.

The sample exit can perform the following functions:

� Verify that NetView Access Services is APF authorized. If not, a return code of01 is issued and the exit is terminated.

� Check for a new password by comparing the input for the New Password fieldwith eight blanks. If the input contains nonblank characters, it is used as thenew password.

� Issue a RACROUTE macro to pass the terminal name, user ID, password, andnew password to RACF for security verification. Upon completion of the secu-rity functions, RACF passes back a return code to NetView Access Services.

If a nonzero return code is received, access to NetView Access Services isdenied and a message based on the return code is displayed on the user’sscreen.

� Evaluate a default group ID, if the user left the group field blank.

� Issue a message to the NetView Access Services Logon panel, if desired. Thesample exit contains a sample user message. If QUERYACB is typed in theuser ID field, a message showing the ACB name of this NetView Access Ser-vices is displayed.

| � If a direct logon is in process:

| – Set the user ID equal to the terminal ID| – If the group ID is blank, set it to the default value 'DLPUBGRP'| – If an error message is set in the LGNXMTXT field, disconnect the terminal.

The sample exit assumes that RACF is installed. If you do not use RACF, youmust change the sample exit, at least to provide a zero return code in every case.

Note: The sample exit requires that NetView Access Services be loaded from anAPF library.

The sample exit contains the following assembler ampersand variables. By settingthese you can select a number of optional features:

&DUMMYIf set to Y, no RACF processing is performed.

&GRPCHKIf set to Y, the group ID given with the logon is passed to RACF for checking.


&NVASDEFIf set to Y and if no group ID is given, EMSELGNX looks for the NetViewAccess Services default group as stored by EMSEADEX in the USERDATAfield of the RACF user profile.

Once a default group name has been written into the USERDATA field of theRACF user profile, this value remains until the default group has been explic-itly reset or changed by NetView Access Services administration.

&ACEEDEFIf set to Y and when no other group ID has been found, EMSELGNX takes thename of the RACF group in which the user has just been logged on. This isfound in the RACF Accessor Environment Element (ACEE). It is either theRACF default group or the name from the logon if &GRPCHK is also set to Y.If &NVASDEF and &ACEEDEF are both set to Y, then NetView Access Ser-vices first tries to evaluate the group ID from the user data field. If this field isempty, then the RACF default group ID is used.

&PUBGIf set to Y and when a nondefined user is recognized and no group ID hasbeen given, a value of PUBGROUP is put in EMSEGRID and a return code ofzero given. To use this group, PUBGROUP must have been defined as aPublic group and have some applications assigned to it.

&LOGOFFIf set to Y, NetView Access Services returns to VTAM. If set to N, theNetView Access Services Logon panel cannot be left using the LOGOFFcommand.

Note: This facility does not prevent advanced users from using the SYSREQkey to return to the VTAM USSMSG10 menu. For additional information referto “NetView Access Services Defined As an Entry in a VTAM Interpret Table”on page 15.

&UIDTERMThe global variable &UIDTERM can be used to determine whether the user IDor terminal ID is used when a user logs on. If set to Y, and no user ID isentered on the NetView Access Services Logon panel, the terminal ID is sub-stituted for user ID. If set to N, and no user ID is entered on the NetViewAccess Services Logon panel, the terminal ID is not substituted for user ID.The default is N.

Considerations about Default Group ID EvaluationWith the exception of a NetView Access Services group or system administrator, auser can gain access to NetView Access Services only if a unique group ID isspecified before the group-related profiles of the user are read. Specifying aNetView Access Services group ID can happen either:

� Explicitly by entering a value in the GROUP field of the logon panel� Implicitly by forcing NetView Access Services to use a user’s default group ID.

Explicit group specification always takes precedence over implicit group evaluation.

There are two ways to let NetView Access Services evaluate a user’s default groupID:

� The sample logon exit EMSELGNX can be customized to evaluate a defaultgroup ID when the user enters blanks, by setting one or more of &NVASDEF,&ACEEDEF, or &PUBG to Y.


� If no group ID is specified either explicit or evaluated by EMSELGNX, NetViewAccess Services looks for the user’s default group type of Normal in the SRTUVSAM database. If such an entry is found, this group ID is taken. If no suchentry is found, then access is only allowed if the user is defined as a group orsystem administrator.

The following items comprise additional information that will be useful when youwant EMSELGNX to evaluate a user’s default group:

� Ensure that the evaluated group IDs are meaningful for NetView Access Ser-vices, that is, an entry must exist in the GPRF VSAM database for this group.

As the VSAM databases are empty when NetView Access Services is startedfor the first time, it is necessary for EMSELGNX to be initially uncustomized toevaluate a default group ID. For the initial startup, check that &DUMMY is setto Y, or that &NVASDEF and &ACEEDEF are set to N.

� If both Normal and External NetView Access Services groups are to be used,and you want EMSELGNX to evaluate a default group ID in any case, then set&NVASDEF = Y and &ACEEDEF = N. EMSELGNX reads the group ID fromthe USERDATA field of the user’s RACF profile.

If the user has defined an External group as his default NetView Access Ser-vices group, EMSEADEX sets the USERDATA field accordingly. If the user hasdefined a Normal group as his default NetView Access Services group, thegroup ID remains blank and NetView Access Services looks in the VSAM pro-files for the user’s default group.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it supplies you withthe address of a parameter list in register 1. The parameter list contains the fol-lowing fields:

� Terminal ID (8 bytes).

The VTAM LU name of the terminal through which the user is accessingNetView Access Services.


This is the User ID from the Logon panel, if it has been entered.

� Password (8 bytes).

This is the password from the Logon panel, if it has been entered, and speci-fies the user’s current password.

� New Password (8 bytes).

This is entered on the Logon panel, and specifies the password that is toreplace the user’s current password.

� ACB name of this NetView Access Services system (8 bytes).


This is the Group ID from the Logon panel, if it has been entered.


� Recall expected indicator (1 byte).


After entering a new password on the Logon panel, the user is asked to reenterit for verification. In this instance NetView Access Services calls the Logon exittwice. The first time the exit is called the LGNXNPWD field is blank. Thisallows the old password to be checked before the user is prompted to reenterthe new password for verification. The second time the exit is called theLGNXNPWD field contains the new value, allowing it to be updated. Where anew password has been entered by the user, but is not being given to the exiton this occasion, an indicator in the parameter list is set to Y. If you are writingaudit records in this installation-wide exit, you will probably only want to do thiswhen this indicator is set to N. If it is set to Y, do not assume that the verynext call will be the matching N call. If the user types in a different value thesecond time, or changes any of the other fields, then NetView Access Servicesrejects the logon and will not call the logon installation-wide exit for the secondtime.

� Application ID (8 bytes).

This is entered on the Logon panel.


This may be filled in on return from the exit with the address of the RACFAccessor Environment Element (ACEE) created by the RACINIT macro. Thisaddress is communicated to the following exits:

– “EMSESEEX, Session Establishment Exit” on page 171– “EMSESREX, Session Reselection Exit” on page 178– “EMSEADEX, Administration Exit” on page 132– “EMSELGFX, Logoff Exit” on page 151.

If no ACEE is retained by the exit, the address must be set to zero. Theaddress can also be used as a terminal-based communication area betweenthe previously-listed exits. RACF places ACEEs in System Queue Area (SQA)storage.

� Message length and text (118 bytes).

You may generate your own messages to be displayed on the Logon panel,rather than the normal NetView Access Services messages listed in thefollowing:

– The text cannot exceed 118 bytes, and must be placed into the area pro-vided.

– The length of data to be displayed must be set in the message length field.– Values above 118 can cause unpredictable results.

� Deallocate terminal flag (1 byte).

If you want to automatically deallocate the terminal and return it to VTAM, thisflag must be set to Y. Any other value prevents deallocation. This could beused, for example, when an invalid password has been entered several timesin succession from the same terminal. You might want to set a particular returncode for this situation, which causes message EMS0666E to be displayed atthe console.

� Address of the secondary data field (4 bytes).

Contains in the first four bytes the length of the secondary data field followedby 1 to 128 bytes of the secondary data field value entered or displayed on theNetView Access Services Logon panel. The format is as follows:


4 Bytes 1 to 128 Bytes

┌─────────────────────────────┬─────────────────────────────┐

│ Length of Secondary Data │ Secondary Data Field │

│ Field │ │

└─────────────────────────────┴─────────────────────────────┘

� Address of the work area (4 bytes).

Contains in the first 4 bytes the length of the work area followed by the128-byte work area. The format is as follows:

4 Bytes 128 Bytes

┌─────────────────────────────┬─────────────────────────────┐

│ Work Area Length (128) │ Work Area Contents │

└─────────────────────────────┴─────────────────────────────┘

The work area is provided to allow the exit to store temporary data for completelogon process interaction. It is not processed by NetView Access Services inany way. The work area is associated with the terminal LU. The work area isallocated when the logon process starts and is freed when the logon processhas ended.

� REXX exec name (8 bytes).

NetView Access Services provides the name of the REXX exec specified to bestarted before it initializes an application session. If no program is specifiedNetView Access Services provides all bytes as zero. If the exit forces all bytesto zero, the start of a REXX exec can be suppressed. If a REXX exec is speci-fied in the exit and a REXX exec has been defined on the Define a Grouppanel, the REXX exec specified in the exit is used when a user logs on toNetView Access Services in the group for which the exec is defined and not theexec defined on the Define a Group panel.

� NETID of the Originator LU (8 bytes).

If the NETID is not provided this parameter contains '********'.

� NETID of the Destination LU (8 bytes).

If the NETID is not provided this parameter contains '********'.

| � Terminal LU name matching one DIRLOGON entry indicator (1 byte). This| parameter will be set to 'Y' when the terminal LU name being processed| matches one DIRLOGON entry. Otherwise it will be set to 'N'.

| If a Default group ID is supplied with the DIRLOGON parameter, it will be| passed in the LGNXGRID parameter.

| If an error occurs during the logon process, the logon exit will be called again| with the message passed in the LGNXMLEN and LGNXMTXT parameters.

Table 17 on page 160 shows the layout of the parameter list to this installation-wide exit.


Table 17. Layout of Parameter List for EMSELGNX, Logon Authorization ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 220 LGNXPRMS Parameter list0 (0) CHARACTER 8 LGNXTID Terminal ID8 (8) CHARACTER 8 LGNXUID User ID

16 (10) CHARACTER 8 LGNXCPWD Current password24 (18) CHARACTER 8 LGNXNPWD New password32 (20) CHARACTER 8 LGNXAPID ACB name of this NetView Access Services40 (28) CHARACTER 8 LGNXGRID Group ID48 (30) CHARACTER 1 LGNXRC Return code49 (31) CHARACTER 1 LGNXRCAL Recall expected: Y/N50 (32) SIGNED 2 LGNXMLEN Length of user message52 (34) CHARACTER 8 LGNXAPPL Application ID from Logon panel60 (3C) ADDRESS 4 LGNXACEE RACF ACEE address64 (40) CHARACTER 118 LGNXMTXT User message text

182 (B6) CHARACTER 1 LGNXDEAL Y=Deallocate terminal183 (B7) CHARACTER 1 LGNXIUAC IUCV interface active: Y/N184 (B8) ADDRESS 4 LGNXSDAA Address of secondary data188 (BC) ADDRESS 4 LGNXWAA Address of work area192 (C0) CHARACTER 8 LGNXREXX REXX program name200 (C8) CHARACTER 8 LGNXNETO NETID of the originator208 (D0) CHARACTER 8 LGNXNETD NETID of the destination216 (D8) CHARACTER 1| LGNXDRFL Terminal LU name matches one DIRLOGON entry:

Y/N.

If a nonzero return code is returned, NetView Access Services resends the Logonpanel with a message, depending on the return code, as follows:

RC MessageX'01' EMS0481I LOAD MODULE NOT APF AUTHORIZED.X'02' EMS0482I SYSTEM AUTHORIZATION FACILITY NOT ACTIVE.X'04' EMS1038I This user ID is not authorized for logon.X'08' EMS1042I The password is incorrect; the logon is rejected.X'0C' EMS1046I The password has expired; enter a new password.X'10' EMS1050A The new password has been rejected.X'14' EMS1074I You are not defined to this group.X'18' EMS0480E ACCESS CONTROL WAS FAILED BY THE INSTALLATION

EXIT ROUTINE.X'1C' EMS1054I Your access to the system has been revoked.X'20' EMS0484E ACCESS CONTROL IS NOT ACTIVE.

EMS1058E Access control is not active.X'24' EMS1078I Your access to this group has been revoked.X'30' EMS1090I You are not authorized to use this terminal.X'34' EMS1094I You are not authorized to use this application.X'38' EMS1039I Secondary authentication verification failed, the logon is

rejected.X'60' EMS1036E Password update is not supported.X'64' EMS0488E SECURITY MACRO PARAMETERS INVALID.X'F0' EMS1010A Enter your user ID.X'F1' EMS1014A Enter your logon password.X'F2' EMS1398E The text supplied in LGNXMTXT for a length of LGNXMLEN is

displayed.X'F3' EMS1398E The text supplied in LGNXMTXT for a length of LGNXMLEN is

displayed. The cursor is then positioned on the Secondary AuthenticationData field.

For all other return codes, the following message is displayed:


EMSð666E INVALID RETURN CODE XX RECEIVED FROM MODULE YYYYYYYY IN MODULE ZZZZZZZZ

The messages in uppercase letters are sent to the operator’s console, not to theuser’s Logon panel. For these messages, the message:

EMS123ðI Internal error has occurred

is sent to the Logon panel.

The EMSELGNX exit routine must be link-edited to the load module EMSELNQH.The verification of logon requests is handled asynchronously by EMSEUS.EMSELNQH handles the queuing of work between the two tasks.

EMSELNEX, Language Name ExitThis installation-wide exit is used when the Language Selection and Broadcastpanels are displayed, to obtain the names of the installed languages. It does notcontain any executable code, but is a series of tables. There is a sample routineprovided by NetView Access Services.

The languages are identified to the system by the DD statements EMSPAN1 toEMSPAN8. However, if a terminal cannot support a particular language, forexample Japanese on a Single-Byte Character Set (SBCS) terminal, then that lan-guage is not presented to the user. Therefore the language IDs presented to theuser might not match those defined during system installation. The table alsoensures that the language names are displayed in the correct language, forexample, in French the name English could be made to appear as Anglais.

In addition, the exit contains a list of abbreviations for the languages. These abbre-viations, as described in TABSHORT in Figure 42, are used when the ampersandvariable &LCD is used in BIND user data or automatic logon or logoff sequences.

Sample Language Name ExitFigure 42 shows the EMSELNEX sample exit provided with NetView Access Ser-vices. The sample also provides double-byte characters. There must be eight lan-guage tables. Each table must have eight 20-byte entries.

EMSELNEX START ð

DC A(TABLE)

DC C'EMSELNEX &SYSDATE &SYSTIME'

TABLE DS ðC

LANG1 DC CL2ð'English'

DC CL2ð'German'

DC CL2ð'Japanese'

DC CL2ð'Uppercase'

DC CL2ð'French'

| DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

Figure 42 (Part 1 of 2). Sample for EMSELNEX, Language Name Exit


LANG2 DC CL2ð'Englisch'

DC CL2ð'Deutsch'

DC CL2ð'Kanji'

DC CL2ð'Uppercase'

DC CL2ð'Franzoesisch'

| DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

LANG3 DC CL2ð'┌ ┐' \ ENGLISH

DC CL2ð'│ See │' \ GERMAN

DC CL2ð'│ Note │' \ JAPANESE

DC CL2ð'│ │' \ UPPERCASE ENGLISH

DC CL2ð'│ │' \ FRENCH

| DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

LANG4 DC CL2ð'ENGLISH'

DC CL2ð'GERMAN'

DC CL2ð'JAPANESE'

DC CL2ð'UPPERCASE'

DC CL2ð'FRENCH'

| DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

LANG5 DC CL2ð'Anglais'

DC CL2ð'Allemand'

| DC CL2ð'Japonais'

DC CL2ð'Reserve'

DC CL2ð'Francais'

| DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

| LANG6 DC CL2ð' '

| DC CL2ð' '

| DC CL2ð' '

| DC CL2ð' '

| DC CL2ð' '

| DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

LANG7 DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

LANG8 DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

DC CL2ð' '

TABSHORT DS ðC

SHORT DC CL3'ENU' AMERICAN ENGLISH LANGUAGE 1

DC CL3'DEU' GERMAN LANGUAGE 2

DC CL3'JPN' JAPANESE LANGUAGE 3

DC CL3'ENP' UPPERCASE LANGUAGE 4

DC CL3'FRE' FRENCH LANGUAGE 5

| DC CL3' ' LANGUAGE 6

DC CL3' ' LANGUAGE 7

DC CL3' ' LANGUAGE 8

END

Figure 42 (Part 2 of 2). Sample for EMSELNEX, Language Name Exit


| Note: Characters representing the Kanji for English, German, Japanese, Upper-| case English, and French.

The address constant following the EMSELNEX START 0 statement must alwayspoint to the beginning of the actual table.

Note: It is the installer’s responsibility to ensure that the sequence and positionspecified here matches the sequence of the panel data sets (EMSPAN1-8). Formore information refer to “Preparing for NetView Access Services Startup” onpage 84, and Figure 24 on page 87.

It is mandatory to use this installation-wide exit.

Installing a New LanguageTo install a new language carry out the following steps:

1. Add in each table (Lang1,Lang2,...,Lang8) the new language name.

2. Take the next available free description field. The position of the new languagename must be the same in each table.

3. In table TABSHORT add the new language at the same position (as inLang1,Lang2,...,Lang8). The description must be only three (3) uppercaseletters.

Note: It is the installer’s responsibility to ensure that the position of the new lan-guage matches with the EMSPANx DD statement in the startup job EMSSTART.See also “Preparing for NetView Access Services Startup” on page 84, andFigure 24 on page 87.

It is mandatory to use this installation-wide exit.


EMSELVEX, Language Verification ExitThis installation-wide exit is entered whenever a terminal is initially logged on toNetView Access Services and before the Logon panel is displayed (or the Applica-tion Selection panel if BIND user data causes the Logon panel to be bypassed).

DescriptionThis installation-wide exit provides the following functions:

� A different default language can be chosen for the terminal, based on the ter-minal ID or the entry in the logmode table. For example, if the LU namingconvention indicates that this terminal is located in Geneva, then French couldbe the default language, whereas in Zurich it could be German.

� The languages allowed for the terminal could also be restricted. For example,if this terminal cannot support Double Byte Character Set (DBCS) data streams,then any language requiring DBCS capability could be removed. Any lan-guages removed in this way are not listed if the Language Selection panel isdisplayed at this terminal, so that the language IDs shown on this panel mightnot match those defined in the system.

� The exit also provides a convenient way of controlling which terminals can logon to NetView Access Services. The INPLU parameter of the SERVRTNcontrol statement also provides this form of control.

� If the logmode entry name is overwritten in this installation-wide exit, then thisis used to bind sessions with all applications selected from this terminal.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it supplies you withthe address of a parameter list in register 1. The parameter list contains the fol-lowing fields, and the items marked * can be overwritten on return from the exit:


� Mapped terminal LU logmode entry name (8 bytes). *


� Default language ID for this terminal (1 byte). *

This is a 1-byte binary number in the range X'01' to X'08'. The sequencenumber must match with the sequence number of the panel data set(EMSPANx). See also “Preparing for NetView Access Services Startup” onpage 84.

� Languages in the system (1 byte - 8 bits).

For every language installed the corresponding bit in this byte is set to 1.

� Languages possible at this terminal (1 byte - 8 bits). *

Each bit in this byte corresponds to the languages 1 to 8. The correspondingbit is set to 1 for each language supported by the terminal, and to 0 for eachlanguage not supported by the terminal. This is important, because DBCS lan-guages are not supported on every terminal.


� DCBS languages in the system (1 byte - 8 bits).

For every DBCS language installed the corresponding bit in this byte is setto 1.

� Return code (1 byte - hexadecimal). *




Table 18. Layout of Parameter List for EMSELVEX, Language Verification ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) CHARACTER 8 PTERMID Terminal LU name8 (8) CHARACTER 8 PTERMLM Mapped terminal LU logmode entry name

16 (10) CHARACTER 1 PDFLANG Default language for this terminal17 (11) CHARACTER 1 PLANGIS Languages in the system18 (12) CHARACTER 1 PEPLPT Languages possible at this terminal19 (13) CHARACTER 1 PDBIS DBCS languages in system20 (14) CHARACTER 1 RETCODE Return code21 (14) CHARACTER 8 POTMN Original terminal LU logmode entry name

Return CodesThe return code is normally X'00'. For any other code the message:

EMSð557E TERMINAL xxxxxxxx DEALLOCATED DUE TO RETURN CODE nn FROM EMSELVEX

is issued (normally to the console unless rerouted to the SYSPRINT file in themessage table), and the terminal is deallocated.

Sample Language Verification ExitThere is a sample routine provided by NetView Access Services for your guidance.In this, a check is done to find out if the default language is supported by the ter-minal. If it is, EMSELVEX returns the return code RC = 0. If the language is notsupported, a check is done to find which of the available languages is supported bythe terminal. This language number is returned with the return code RC = 0. Ifnone of the languages are supported by the terminal, RC = 2 is returned.

EMSENPME, Accounting ExitThis installation-wide exit is entered:

� When a session for an application has been initialized or terminated

� During a pass-mode reconnect to NetView Access Services (using SIMLOGON)

� For application status changes (ONLINE/OFFLINE).

This installation-wide exit can be used for session auditing and accounting.

NetView Access Services does not provide a sample EMSENPME routine.


Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it supplies you withthe address of a parameter list in register 1.

The parameter list contains the following fields:

� Target application LU name (8 bytes).




� Account Number for the application (8 characters).

� NetView Access Services LU NAME (LU name of the pseudo terminal thatNetView Access Services uses to establish a session with the desired targetapplication). This is blank for a pass mode application.

� Flag indicating the reason why the exit was scheduled (1 byte):

C CONNECT– In relay mode– In pass mode

D DISCONNECT– RETURN from pass mode connection– LOGOFF from relay-mode session

T TERMINATION

The exit is called with this value for all sessions that were active when anormal termination of NetView Access Services was performed. In thecase of pass-mode sessions they continue until the user logs off. Relaymode sessions are terminated along with NetView Access Services.

� Flags indicating pass mode or relay-mode session (1 byte).

� Application status change record (1 byte).

A Application status

� Application up or down (1 byte).

U Up (online)D Down (offline).


� Application LU name for status record (8 bytes).

� Application status change date (8 bytes).

The content of this field is the date the application status has changed and theformat is DD/MM/YY.

� Application status change time (8 bytes).

The content of this field is the time the application status has changed and theformat is HH.MM.SS.

� Number of bytes received from application (8 bytes).

This field contains the number of bytes received from the application. This fieldonly contains values when the Virtual Terminal option for the application is Y.

� Number of bytes sent to terminal after compression (8 bytes).


This field contains the number of bytes sent to the terminal after the bytesreceived from the application have been compressed. This field only containsvalues when the Virtual Terminal option for the application is Y.


Table 19. Layout of Parameter List for EMSENPME, Accounting ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 77 ITEXPRMS Parameter list0 (0) CHARACTER 8 ITEXACB Target application LU name8 (8) CHARACTER 8 ITEXUID User ID

16 (10) CHARACTER 8 ITEXGID Group ID24 (18) CHARACTER 8 ITEXTLU Terminal LU name32 (20) CHARACTER 8 ITEXACNO Account number for application40 (28) CHARACTER 8 ITEXLUN Pseudo terminal LU name48 (30) CHARACTER 2 ITEXFLAG Reason flags48 (30) CHARACTER 1 ITEXF1 C=Connect/D=Disconnect/T=Terminate49 (31) CHARACTER 1 ITEXF2 R=Relay/P=Pass50 (32) CHARACTER 2 ITEXFLA2 Flags for application status50 (32) CHARACTER 1 ITEXF3 A=Application status change record51 (33) CHARACTER 1 ITEXF4 U=Application up/D=Application down52 (34) BITSTRING 1 ITEXRC Return code53 (35) CHARACTER 3 ITEXRES For future use56 (38) CHARACTER 8 ITEXAPPN Application LU name64 (40) CHARACTER 8 ITEXSDTE Date status changed72 (48) CHARACTER 8 ITEXSTIM Time status changed80 (50) CHARACTER 8 ITEXCBR Number of bytes received from application80 (50) UNSIGNED 4 ITEXCBRH High order bytes of count84 (54) UNSIGNED 4 ITEXCBRL Low order bytes of count88 (58) UNSIGNED 8 ITEXCBS Number of bytes sent to terminal after

compression88 (58) UNSIGNED 4 ITEXCBSH High order bytes of count92 (5C) UNSIGNED 4 ITEXCBSL Low order bytes of count96 (60) CHARACTER * Alignment


RC MeaningX'00' Processing completed without error. NetView Access Services continues

processing.X'08' Error during processing. NetView Access Services writes the message:

EMSð634E EMSENPME EXIT FAILED FOR ACB=nn UID=mm FLAG1=xx FLAG2=yy

to the console and continues.

EMSEPRPS, Printer Presetting ExitThis installation-wide exit allows the modification of the printer presetting for thepanel copy to printer function. The exit is called for each print request and consistsof the sample module EMSEPRPS, and the assembler DSECT EMSEPRPD thatcan be generated with the EMSEPRPD macro.


Parameter List Fields� Address of panel copy print data (4 bytes).

NetView Access Services passes the panel copy print data to this installation-wide exit via this field. The data is in 3270 data stream format as read fromthe terminal.

When the exit passes control back, NetView Access Services ignores the dataaddressed by this field and frees the storage area of the panel copy print data.

� Length of panel copy print data (4 bytes).

NetView Access Services passes the length of the panel copy print data to thisexit. When the exit passes control back, NetView Access Services ignores thisfield.

� Continue processing Y/N (1 byte).

This field must be specified in the exit module to indicate to NetView AccessServices if processing is to be terminated or continued. Two possible charactervalues can be coded:

Y Continue processingN Terminate processing.

If an invalid character was coded, the default is N.

� Language ID (1 byte).

This field is passed from NetView Access Services to the exit to indicate thelanguage ID of the terminal. The value passed is a 1-byte binary number in therange of X'01' to X'08'. When the exit passes control back, NetView AccessServices ignores this field.

� Generate title page Y/N (1 byte).

This field must be specified in the exit module to indicate to NetView AccessServices whether a title page is to be generated or not. Two possible charactervalues can be coded:

Y Generates a title pageN No title page is generated.

If an invalid character was coded, the default is N.

� Total title page (1920 bytes).

� Line 1 to 24 of title page (80 bytes each line).

Output line of the title page that should be printed.

� Group ID of the sender (8 bytes).

The group ID of the sender is passed by NetView Access Services to the exit.When the exit passes control back, NetView Access Services ignores this field.

� User ID of the sender (8 bytes).

The user ID of the sender is passed by NetView Access Services to the exit.When the exit passes control back, NetView Access Services ignores this field.

� Output Class (1 byte).

The output class of the system printer must be specified in the exit. This valueis passed from the exit to NetView Access Services. If omitted, NetViewAccess Services does not support the system printer.


� Printer Destination (8 bytes).

The printer destination must be specified in this exit. NetView Access Servicespresets this field with the value 'LOCAL....' before the exit is invoked.

� Output Name (24 bytes).

An output name can be specified in the exit, which is passed to NetViewAccess Services. This field is not checked by NetView Access Services.

� Distribution Code (4 bytes).

A distribution code can be specified in the exit, which is passed to NetViewAccess Services. This field is not checked by NetView Access Services.

� Printer Name (8 bytes).

The Printer Name as selected by the sender is passed by NetView Access Ser-vices to the exit.

The exit may change the name of the printer and pass the new name back toNetView Access Services. Therefore it is possible to use user-friendly printernames that are then mapped by this exit to real printer LU names.

If the printout destination is the JES printer, a value of 'SYSTEMPR' must bereturned. In this case a printer destination and output class must be specified.

� Send Limit (2 bytes).

The Send Limit is used to control the number of print requests accepted byNetView Access Services for a particular printer while printing is not possible.This limit is used only during the printer allocation phase.

During the allocation phase of a printer, several terminal users may start printrequests to this printer, which causes queuing of data within NetView AccessServices. In addition, more print requests may be started in a period of timethan the printer can handle in that time. This also causes queuing of datawithin NetView Access Services. To avoid a lack of storage in such conditions,the print requests are rejected and the terminal users are informed to retry theirprint requests later on.

This value is passed from the exit to NetView Access Services. Returning aHex-Zero value in this field indicates to NetView Access Services that no sendlimit is required. Before NetView Access Services calls the exit, the field isinitialized with decimal 20.

Notes:

1. To calculate the additional amount of storage required for the Send Limit asdefined in the EMSEPRPS exit, the following should be considered:

– The number of buffers required for one print request can be calculatedby dividing the screen size of the terminal by the BUFFLEN value.

– The number of print requests that can be issued for each printerdepends on the Send Limit value.

– The BUFFMAXN value must be increased by the number of buffersrequired per print request, multiplied by the Send Limit multiplied by thenumber of available printers.

2. If an LU 3 printer is used and the print output consists of a title page andapplication panel data, NetView Access Services performs two sends, onefor the title page and one for the application panel data. If the send limit is


reached, it is possible that only the title page is printed. However, the useris notified of this by an appropriate message.


Table 20. Layout of Parameter List for EMSEPRPD, Printer Presetting ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) ADDRESS 4 PRPDDATP Address of panel copy print data4 (4) BITSTRING 4 PRPDLEN Length of panel copy print data8 (8) CHARACTER 1 PRPDCONT Continue processing: Y/N9 (9) BITSTRING 1 PRPDLID Language ID

10 (A) CHARACTER 1 PRPDTI Generate title page: Y/N11 (B) CHARACTER 80 PRPDTIPG

(24)Total title page

11 (B) CHARACTER 80 PRPDLI01 Line 1 of title page91 (5B) CHARACTER 80 PRPDLI02 Line 2 of title page

171 (AB) CHARACTER 80 PRPDLI03 Line 3 of title page251 (FB) CHARACTER 80 PRPDLI04 Line 4 of title page331 (14B) CHARACTER 80 PRPDLI05 Line 5 of title page411 (19B) CHARACTER 80 PRPDLI06 Line 6 of title page491 (1EB) CHARACTER 80 PRPDLI07 Line 7 of title page571 (23B) CHARACTER 80 PRPDLI08 Line 8 of title page651 (28B) CHARACTER 80 PRPDLI09 Line 9 of title page731 (2DB) CHARACTER 80 PRPDLI10 Line 10 of title page811 (32B) CHARACTER 80 PRPDLI11 Line 11 of title page891 (37B) CHARACTER 80 PRPDLI12 Line 12 of title page971 (3CB) CHARACTER 80 PRPDLI13 Line 13 of title page

1051 (41B) CHARACTER 80 PRPDLI14 Line 14 of title page1131 (46B) CHARACTER 80 PRPDLI15 Line 15 of title page1211 (4BB) CHARACTER 80 PRPDLI16 Line 16 of title page1291 (50B) CHARACTER 80 PRPDLI17 Line 17 of title page1371 (55B) CHARACTER 80 PRPDLI18 Line 18 of title page1451 (5AB) CHARACTER 80 PRPDLI19 Line 19 of title page1531 (5FB) CHARACTER 80 PRPDLI20 Line 20 of title page1611 (64B) CHARACTER 80 PRPDLI21 Line 21 of title page1691 (69B) CHARACTER 80 PRPDLI22 Line 22 of title page1771 (6EB) CHARACTER 80 PRPDLI23 Line 23 of title page1851 (73B) CHARACTER 80 PRPDLI24 Line 24 of title page1931 (78B) CHARACTER 8 PRPDGRPI Group ID of the sender1939 (793) CHARACTER 8 PRPDUSRI User ID of the sender1947 (79B) CHARACTER 1 PRPDOCLS Output class1948 (79C) CHARACTER 8 PRPDDEST Printer destination1956 (7A4) CHARACTER 24 PRPDONAM Output name1980 (7BC) CHARACTER 4 PRPDVMDC Distribution code1984 (7C0) CHARACTER 8 PRPDPNAM Printer name1992 (7C8) BITSTRING 2 PRPDSLIM Send limit for this session

EXPRESSION PRPDTOTL "*-EMSEPRPD" Length of DSECT EMSEPRPD

Sample Exit EMSEPRPSNetView Access Services provides a sample exit module. This module contains asample program that generates a title page in the appropriate language. SeeFigure 43.


à ð

N E T V I E W

\\\\\\\ \\\\\\\ \\\\\\\ \\\\\\\\\ \\\\\\\ \\\\\\\

\\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\

\\ \\ \\ \\ \\ \\ \\

\\\\\\\\\ \\ \\ \\\\\\\\\ \\\\\\\ \\\\\\\

\\ \\ \\ \\ \\ \\ \\

\\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\

\\ \\ \\\\\\ \\\\\\ \\\\\\\\\ \\\\\\\ \\\\\\\

S E R V I C E S

Print Output for User : xxxxxxxx

Group: xxxxxxxx

á ñ

Figure 43. Title Page for Print

The sample program specifies no values for the system printer with the exceptionof the output class specified for PRPDOCLS and the printer destination LOCAL.

EMSESEEX, Session Establishment ExitThis installation-wide exit is entered:

� Before session initialization for an application

� If a new system internal name is given by a previous EMSESEEX call

� When a location ID different to the local location ID is entered on the Logonpanel.

DescriptionThis exit provides the following possibilities for checking and modifying the logonparameters:

� It enables data (for example, ampersand variables) that is to be substituted inthe BIND user data to be sent with a request for an application.

� The addition, suppression, or modification of BIND user data.

� The substitution of ampersand variables.

The values of ampersand variables can be modified temporarily. The changedvalues are stored incore only and are not written to VSAM clusters. Permanentmodifications to ampersand variables must be performed by NetView AccessServices administration.

This can be used for loading ampersand variables with nonprintable characters.For example, if an application needs to know that a session request has beeninitiated by a NetView Access Services, then the application can define aspecial string containing a nondisplayable character as an indicator for thisinformation. A nondisplayable character cannot be entered by a user on aphysical terminal, but NetView Access Services can load an ampersand vari-


able with this special string and send this information via BIND user data orduring automatic logon to the application.

� The choice of an SLU name to override the normal NetView Access Servicesselection. This can be useful when a specific SLU name, based upon the ter-minal from which the user is logged on, is required. For example, a CICS/VSsession from an IBM 3278 Model 5 terminal may require a name that is alsodefined as a 3278 Model 5 in the CICS/VS TCT.

� The substitution of PLU names.

For example, an installation may wish to spread the load across two identicalIMS/VS systems without any user intervention. IMS/VS could be defined toNetView Access Services with a generic name, and then this generic namecould be overwritten with the required ACB name in this installation-wide exit.

� The use of meaningful names in the Location ID field of the NetView AccessServices Logon panel.

For example, the name BRISTOL could be translated using this installation-wide exit to the ACB name of the Bristol-based NetView Access Services.

� The rejection of logons to NetView Access Services or to an application basedupon certain criteria.

For example, the Location ID could be checked to make sure that it is the validname of a NetView Access Services system. Another example is checking thatthe user is allowed to use the application from this terminal.

� The overriding of LOGMODE names for specific applications.

� Enabling applications that need a definition of each terminal model to use poolsof pseudo terminals. This is described in “Defining Different Terminal Models”on page 7.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit it supplies theaddress of a parameter list in register 1. The parameter list contains the followingfields:

� Target application primary LU name or the location field from the Logon panel(8 bytes).




� Mapped terminal LU logmode entry name (8 bytes).


� Secondary LU name (8 bytes).

This may be filled in on return with the name of an SLU to be used in prefer-ence to the normal NetView Access Services SLU name for relay-mode ses-


sions. It contains blanks for a relay-mode session and binary zeros for apass-mode session when a location ID is being processed.

� BIND user data area address (4 bytes).

This points to a 255-byte area that contains the BIND user data (if it exists) tobe passed to the application. Ampersand variable substitution takes place afterthis exit has been called. This area can be overwritten by the exit routine if youwant to replace the BIND user data. The address field in the parameter listmust not be altered.

� Data area length (2 bytes).

This is the length of the data inside the 255-byte BIND user data area. It canbe zero. The length must be changed accordingly if it has been overwritten bythis installation-wide exit routine. For example, &UID=4 bytes, but the valueABC=3 bytes might be different.

� Return code (1 byte).

� Action flag (1 byte).

This is set to indicate the type of session being established as follows:

L Location IDU Relay mode session for ACB type UniqueS Relay mode session for ACB type SharedI Relay mode session for ACB type IndividualP Pass mode session.


This is the address of the RACF ACEE created in the logon exit. IfEMSESEEX creates a new ACEE for any reason, this address must beupdated accordingly. If the ACEE is deleted or if no ACEE is present, theaddress is zero. If you do not save the address in EMSELGNX, this addresscan be used for whatever purpose you wish, for example, a terminal-relatedwork area.

� ACB name of this NetView Access Services (8 bytes).

� Application name from the Application Selection panel (8 bytes).

� System-internal name (8 bytes).

This is the system-internal name as specified on the Define an Application forthe System and Assign an Application to a Group panels. This field can beoverwritten by the exit routine. If the exit substitutes a new system-internalname, any BIND data specified at the same time is ignored. Instead NetViewAccess Services sets up the information associated with the new system-internal name and invokes the exit again. Now BIND data must be supplied ifnecessary and other exit modifications should be made.

An attempt to overwrite the system-internal name again on the second invoca-tion of the exit is ignored by NetView Access Services. Execution continueswith the same name substituted on the first invocation.

� Send X'F1C2' after BIND (1 byte).

This can be Y for Yes or N for No. The default is N. If a session is to beestablished to an application, for example, CICS with no good morningmessage and no default transaction, then Y must be specified. NetView


Access Services sends X'F1C2' to the terminal to restore the keyboard afterthe session is established.

� BIDDER Protection (1 byte).

This can be Y for Yes or N for No. The default is Y. If Y is specified, applica-tions that send BIDs are protected from unexpected terminal input.

� Pointer to area of &variables (4 bytes).

This is the pointer to the area of &variables. Refer to Table 22 on page 175for the layout of the parameter list for the &variables. The area of ampersandvariables is not provided, if the exit is called after a location ID has beenentered on the NetView Access Services Logon panel. The pointerSEEXVARS in this case is zero (SEEXACTN = L).

In all other cases NetView Access Services fills the area of ampersand vari-ables with the current values. These values can be changed by the exit. Afterreturning from the exit, NetView Access Services stores the values in internalcontrol blocks. The values returned from the exit can be used for BIND userdata or during automatic logon processing. NetView Access Services frees theinternal control blocks when a user logs off, therefore, changed values remainvalid as long as the user is working in NetView Access Services.

The ampersand variables &PWD, &NPW, and &OPW are decrypted before theyare passed to the exit and are encrypted before they are restored into theinternal control blocks.

� REXX exec name (8 bytes).

NetView Access Services provides the name of the REXX exec specified to bestarted before it initializes an application session. If no program is specified,NetView Access Services provides all bytes as zero. If the exit forces all bytesto zero, the start of a REXX exec can be suppressed. If a REXX exec is speci-fied in the exit and a REXX exec has been defined on the Assign an Applica-tion to a Group panel, the REXX exec specified in the exit is used when a userlogs on to NetView Access Services in the group for which the exec is definedand not the exec defined on the Assign an Application to a Group panel.




Table 21 (Part 1 of 2). Layout of Parameter List for EMSESEEX, Session Establishment ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 112 SEEXPRMS Parameter list for EMSESEEX0 (0) CHARACTER 8 SEEXACB Target application LU name8 (8) CHARACTER 8 SEEXUID NetView Access Services user ID

16 (10) CHARACTER 8 SEEXGID NetView Access Services group ID24 (18) CHARACTER 8 SEEXTLU Terminal LU name32 (20) CHARACTER 8 SEEXMODE Mapped terminal LU logmode entry name40 (28) CHARACTER 8 SEEXSLU Secondary LU name (returned)48 (30) ADDRESS 4 SEEXDPTR Data pointer52 (34) SIGNED 2 SEEXDLEN Data length54 (36) BITSTRING 1 SEEXRC Return code55 (37) CHARACTER 1 SEEXACTN L=Location ID/U=Unique/S=Shared/

I=Individual/P=Pass56 (38) ADDRESS 4 SEEXACEE RACF ACEE address


Table 21 (Part 2 of 2). Layout of Parameter List for EMSESEEX, Session Establishment ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 60 (3C) CHARACTER 8 SEEXNVAS ACB name of this NetView Access Services68 (44) CHARACTER 8 SEEXAPPL Application name76 (4C) CHARACTER 8 SEEXSID NetView Access Services system ID of application84 (54) CHARACTER 1 SEEXF1C2 Y/N (returned variable). Y: NetView Access

Services sends X'F1C2' to the terminal after a BINDfrom an application (for CICS with nogood morning message). The default is N.

85 (55) CHARACTER 1 SEEXBPRT BIDDER protection field: Y/N (returnedvariable). Y: NetView Access Servicesprotects this application from unexpected terminalinput when the application has sent a BID.For monitor applications using BIDs this maylock terminals for a certain time. The default is Y.

86 (56) CHARACTER 2 * For future use88 (58) ADDRESS 4 SEEXVARS Pointer to area of &variables92 (5C) CHARACTER 8 SEEXREXX REXX exec name

100 (64) CHARACTER 8 SEEXOTMN Original terminal LU logmode entry name108 (6C) CHARACTER 12 * For future use

The installation-wide exit must return one of the following return codes to the callingmodule:

RC MeaningX'00' Process request for this session.X'08' Cancel session initialization request. NetView Access Services sends the

message:

EMSð499I REQUEST CANCELED IN EMSESEEX FOR ACB=NN USER=UU.

Table 22 shows the layout of the parameter list for the &variables.

Table 22. Layout of Parameter List for &VariablesOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) CHARACTER 8 AVSXVAR1

(14)Ampersand variables

0 (0) CHARACTER 8 AVPWD Content of &PWD8 (8) CHARACTER 8 AVNPW Content of &NPW

16 (10) CHARACTER 8 AVOPW Content of &OPW24 (18) CHARACTER 8 AVUID Content of &UID32 (20) CHARACTER 8 AVACCNO Content of &ACCNO40 (28) CHARACTER 8 AVGVAR1 Content of &GVAR148 (30) CHARACTER 8 AVGVAR2 Content of &GVAR256 (38) CHARACTER 8 AVGVAR3 Content of &GVAR364 (40) CHARACTER 8 AVGVAR4 Content of &GVAR472 (48) CHARACTER 8 AVGVAR5 Content of &GVAR580 (50) CHARACTER 8 AVUVAR1 Content of &UVAR188 (58) CHARACTER 8 AVUVAR2 Content of &UVAR296 (60) CHARACTER 8 AVUVAR3 Content of &UVAR3

104 (68) CHARACTER 8 AVUVAR4 Content of &UVAR4112 (70) CHARACTER 8 AVSXVAR2

(3)&1,&2,&3 variable

112 (70) CHARACTER 8 AV1 Content of &1120 (78) CHARACTER 8 AV2 Content of &2128 (80) CHARACTER 8 AV3 Content of &3

1... 1... AVSXTOTL '*-EMSDAVSX' Length of DSECT EMSDAVSX


Sample Session Establishment ExitThe sample exit contains an example for changing ampersand variables embeddedin comments. If the comments are removed, then the contents of the &GVAR1 and&UVAR1 variables are copied into the &1 and &2 variables. You can use this codeif you have input fields with length 2 on panels, in which you would like to fill valuesstored in ampersand variables &GVAR1 or &UVAR1. During automatic logonrecording you use &1 or &2, which are substituted by &GVAR1 or &UVAR1 values.This allows you to insert &GVAR1 and &UVAR1 values in input fields with a lengthof less than 6. Normally you need an input field of length 6 for entering &GVAR1or &UVAR1 values, because the string '&GVAR1' or '&UVAR1' is composed of 6characters.

The sample exit also contains an example for the substitution of the system-internalname. The example assumes that the 3278 Model 2 terminal is the default ter-minal model (that is, the one that is used most frequently) at your installation, butthat there are also 3278 Model 3 and Model 4 terminals. The sample code deter-mines the model by means of the logmode in the exit. For the default Model 2 itassumes that the system-internal name presented to the exit is associated with theIMS pseudo terminal pool serving the 3278 Model 2. A new system-internal nameis not substituted for this model. With Models 3 and 4 the exit substitutes newsystem-internal names of the IMS pseudo terminal pools serving these models.

In addition, the sample exit contains code, which ensures that the user ID used tolog on to NetView Access Services is passed to any Application Services Routine(ASR) that is invoked with BIND user data from EUS. For example, to the Applica-tion Connectivity Feature ASR of OfficeVision/MVS*.

Note: Each user can define an alternative user ID for any application or ASR onthe Maintain User Parameters panel. Therefore, if you do not use this exit, analternative user ID can be passed to an ASR without being verified.

The sample source code for EMSESEEX parses the BIND user data for the char-acter string UID = and replaces the parameter value (for example, &UID) by theuser ID used during logon to NetView Access Services. The variables are resolvedafter return from this exit. This replacement takes place only when the selectedapplication is an ASR, for example with the Application Connectivity Feature ofOfficeVision/MVS.

In addition, the sample exit contains code enabling a session to be established withCICS with no good morning message or default transaction.

Using This Exit for Session Load BalancingThe accounting exit EMSENPME can be used in conjunction with this exit to main-tain tables or counters reflecting the status of individual applications. For example,if load balancing is to be done using this exit for two IMS systems using this exit,then a counter for each system could be kept. EMSENPME increases anddecreases the counters for successful logon and logoff attempts. EMSESEEX theninterrogates the counters to find out which IMS system has the lowest load. Youmust use external symbols to communicate with EMSENPME.


EMSESHRX, Shared Session ExitThis installation-wide exit is provided to allow the system programmer to gainaccess to a copy of the panel data sent to the passive shared session partner. Theexit consists of the sample module EMSESHRX and the DSECT EMSESHRD thatis generated by the EMSESHXD macro.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it passes theaddress of the exit parameter list EMSESHXD in Register 1. The parameter listcontains the following fields:

� The NetView Access Services user ID (8 bytes) of the requesting user.

� The NetView Access Services group ID (8 bytes) of the requesting user.

� The terminal LU name (8 bytes) of the requesting user.

� The NetView Access Services user ID (8 bytes) of the requested user.

� The NetView Access Services group ID (8 bytes) of the requested user.

� The terminal LU name (8 bytes) of the requested user.

� The address of the buffer that contains a copy of the data sent to the terminalof the passive user (4 bytes).

� Length of the buffer that contains a copy of the data sent to the terminal of thepassive partner (4 bytes).

� Return code field (4 bytes).


Table 23. Layout of Parameter List for EMSESHRX, Shared Session ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) CHARACTER 8 SHXDUIDA User ID of the shared session requester8 (8) CHARACTER 8 SHXDGIDA Group ID of the shared session requester

16 (10) CHARACTER 8 SHXDLUA Terminal LU of the shared session requester24 (18) CHARACTER 8 SHXDUIDP User ID of the partner32 (20) CHARACTER 8 SHXDGIDP Group ID of the partner40 (28) CHARACTER 8 SHXDLUP Terminal LU of the partner48 (30) ADDRESS 4 SHXDADR Address of the data buffer52 (34) BITSTRING 4 SHXDLEN Length of the data56 (38) BITSTRING 4 SHXDRC Return code

Return CodesThis installation-wide exit returns one of the following codes to the calling module:

RC MeaningX'00' Processing completed without error. NetView Access Services continues

processing.X'08' Error during processing. NetView Access Services writes the message:

EMSð637E INSTALLATION-WIDE EXIT EMSESHRX FAILED with RC=xxxx.

to the console and processing continues.


EMSESREX, Session Reselection ExitThis installation-wide exit enables you to verify terminal access authority when:

� A user reselects an application from a second terminal.

� A shared session is to be established.

Control is given to this exit when an application is reselected at a terminal otherthan the one from which the session with the application was established. Itenables the installation to perform security checks, such as checking whether theuser is allowed to gain access to the application from the new terminal. The namesof the two terminals as well as information about user and application are suppliedto the exit. The installation-wide exit routine can indicate through a return codewhether the session reselection process is to continue or be rejected. In addition,this installation-wide exit is invoked whenever a shared session is established.

Parameter List FieldsWhen NetView Access Services calls this installation-wide exit, it supplies you withthe address of a parameter list in Register 1. The parameter list contains the fol-lowing fields:

� Target application primary LU name (8 bytes).



� Terminal LU name during session initialization (8 bytes).

� Terminal LU name during session reselection (8 bytes).

� Target application name (8 bytes).

� RACF ACEE address from RACINIT ENVIR=CREATE (4 bytes).


� Reason why exit is called (1 byte).

R Application reselection

S Attempt to establish a shared session

F Forward

S Show.

� Shared session type (1 byte).

Table 24 on page 179 shows the layout of the parameter list for this installation-wide exit.


Table 24. Layout of Parameter List for EMSESREX, Session Reselection ExitOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 53 SREXPRMS Parameter list for EMSESREX0 (0) CHARACTER 8 SREXACB Target application LU name8 (8) CHARACTER 8 SREXUID User ID

16 (10) CHARACTER 8 SREXGID Group ID24 (18) CHARACTER 8 SREXITLU Initialization terminal name32 (20) CHARACTER 8 SREXRTLU Reselection terminal name40 (28) CHARACTER 8 SREXANAM Target application name48 (30) ADDRESS 4 SREXACEE ACEE address52 (34) BITSTRING 1 SREXRC Return code53 (35) CHARACTER 1 SREXREAS Reason why exit is called54 (36) CHARACTER 1 SREXSSTY Shared session type


RC MeaningX'00' Process request for this session reselection.X'08' Cancel session reselection request.

NetView Access Services sends the following messages:

� To the console:

EMSð499E REQUEST CANCELED IN EMSESREX FOR ACB=NN USER=UU

� To the user terminal:

EMS1111E Reconnection to application aaaaaaaa not authorized from this terminal.



Part 3. NetView Access Services Application ServiceRoutines

This part documents Product-Sensitive Programming Interface and AssociatedGuidance Information. It provides information on writing your own ApplicationService routines.



Chapter 14. Writing New Application Service Routines

The macros identified in this chapter are provided as programming interfaces forcustomers by NetView Access Services.

Warning: Do not use as programming interfaces any NetView Access Servicesmacros other than those identified in this chapter.

NetView Access Services provides a simple macrointerface between Communi-cation Services (CS) of NetView Access Services and an Application ServiceRoutine (ASR) that enables you to write an ASR to perform new functions, addi-tional to NetView Access Services. ASRs call the macros provided by NetViewAccess Services.

Important

If you use the described macros to write your own Application Service Routinesto run in the NetView Access Services address space, you must ensure thatthey are correctly coded. Otherwise, it is possible to influence the NetViewAccess Services program.

Recompilation of your Application Service Routines for subsequent releases ofNetView Access Services may not be sufficient. Recoding may be necessary.

Major Functions of an Application Service RoutineThe major functions of an ASR are:

� Establishing addressability between the ASR and the CS of NetView AccessServices

� Establishing and terminating sessions with LUs� Communicating with LUs that are in session with NetView Access Services.

Figure 44 shows the basic flow of a NetView Access Services ASR.

Establishing AddressabilityThe EMSSTRT macro establishes the addressability between the ASR and CS.This must be the first macro in the ASR.

To communicate with CS, you must issue the EMSRECV macro. This macrochecks the input queue for the ASR. If the queue is empty, the EMSRECV macrowaits until an element can be received. An element is either control information ordata. EMSRECV does not return control to the ASR if the input queue is empty. Itis a receive and wait function.

Establishing and Terminating Sessions with Logical UnitsIf NetView Access Services receives a session request from an SLU, theEMSRECV macro returns an allocation request indication in the “what received”field and a resource ID for the SLU. The resource ID identifies the LU to the ASR.This resource ID must be used for any further communication with this LU.


If the allocation request is accepted, the ASR responds with the EMSSENDDmacro containing the data to be sent to the SLU. If the allocation request is notaccepted, the ASR must respond with the EMSDEALL macro to terminate thesession.

You can use the EMSALLOC macro if you want to initiate a session with a PLU.The EMSRECV macro returns the resource ID for this session if the session hasbeen established, and returns an allocation response in the what received field. Anallocation failure is received if the allocate request fails and the session cannot beestablished.

Communicating with Logical UnitsTo communicate with an LU, you use the EMSRECV macro for data that has beensent by that LU. The EMSRECV macro provides you with an indication that datahas been received and provides you with the resource ID of the sending LU. Inaddition, the macro provides a pointer to the received data buffer and the datalength.

To send data to an LU you use the EMSSENDD macro. You must supply theresource ID, a data buffer pointer, and the data length to the EMSSENDD macro.

┌─────────────────────────────────────┐

│ Start of routine │

│ EMSSTRT establish addressability │

│ Perform initialization processing │

├─────────────────────────────────────┤

│ │

│ Do until end of job │

│ EMSRECV │

│ Check what received │

│ │

│ ┌──────────────────────┐

│ │ Handle allocate │

│ │ request from SLU │

│ If Allocate request ─────5│ send data using │

│ │ EMSSENDD │

│ └──────────────────────┘

│ │

│ ┌──────────────────────┐

│ │ Handle data from LU │

│ │ send data to the LU │

│ │ with EMSSENDD macro │

│ If Data received ─────5│ or │

│ │ request a session │

│ │ with a PLU using │

│ │ EMSALLOC │

│ └──────────────────────┘

│ │

│ ┌──────────────────────┐

│ │ Send data to the PLU │

│ │ with EMSSENDD macro │

│ If Allocate response ────5│ or │

│ │ deallocate a session │

│ │ with a PLU using │

│ │ EMSDEALL macro │

│ └──────────────────────┘

│ │

│ ┌──────────────────────┐

│ │ Perform deallocation │

│ │ processing using │

│ If Deallocate ─────5│ EMSDEALL │

│ │ Inform related LUs │

│ │ with EMSSENDD │

│ └──────────────────────┘

│ │

│ If End of Job received then │

│ perform termination processing. │

└─────────────────────────────────────┘

Figure 44. Flow of a NetView Access Services ASR


Coding RequirementsYou must observe the following points when writing your code:

RestrictionsDo not code your program to cause a system wait state. A system wait mayproduce an interlock. For example, if an exit waits for a resource being usedby the mainline routine, the resource is not released because the exit is inter-rupting the mainline routine.

To avoid causing a system wait state, do not issue wait macro instructions.

Variable NamesDo not use EMS as a prefix for any variable you name in your code.

Register UsageFollow these guidelines when using registers for ASRs:

� Save registers on entry to the user code and restore them before returningcontrol to NetView Access Services. (Use standard linkage conventions tosave and restore registers.)

� Take into account that registers 0, 1, 14, and 15 are reserved for NetViewAccess Services macro instruction expansion.

� Register 13 should contain the address of a standard 72-byte save area.

� Return control to the location in NetView Access Services specified by reg-ister 14.

� Do not rely on the contents of registers 2 through 12 for constant values onentry to user code. Their contents vary.

ReentranceMake sure your code is serially reusable, to enable the code to be used by oneuser or task when it is no longer being used by another.

ConsiderationsNetView Access Services supports any valid combination of AMODE andRMODE for the exit routines. The routines are always called with a BALRinstruction, so the AMODE and RMODE are inherited from the calling program.NetView Access Services is delivered to run under AMODE31 and RMODE24.

NetView Access Services MacrosThe macros use two types of interface:

� A queued interface for input operations from the ASRs, that is, data or controlinformation transferred from CS to ASRs. This is used by all “Receive” typemacros.

� A call interface for output operations to the ASRs, that is, data or control infor-mation transferred from ASR to CS. This is used by all “Send” type macros.

Chapter 14. Writing New Application Service Routines 185

Macro SummaryThe following macros are provided by NetView Access Services:

EMSSTRT Initiates the macro interface.EMSALLOC Requests a session with an LU and provides a connection with a

subsystem.EMSDEALL Deallocates a session with an LU and terminates it.EMSFBUF Frees a data buffer and requeues it to the buffer pool.EMSGATTR Returns information referring to a specified session.EMSGBUF Requests a free data buffer from the buffer pool.EMSNPM Sends event information to NetView Performance Monitor for

session correlation.EMSPRETR Changes the conversation from send to receive in preparation

for receiving data.EMSRECV Receives a buffer from the queue.EMSREQTS Sends a SIGNAL to a remote LU.EMSSENDD Sends data, commands or responses (or both), to an LU.EMSSENDE Sends an error response to an LU.

Operand DescriptionsAll macros require a 128-byte work area. The work area must be specified in theWORKA operand. In the following, each macro is described. Each operand isnamed and described in accordance with the assembler format table. Thedescription begins with an explanation of the operand’s function. If the operandhas more than one possible fixed value, the description also explains the effect thateach value has on the action performed by the macro instruction.

Operand Format : The operand description can include a description of the formatin which the operand should be coded. This description is provided when theformat is an exception to the following general rules:

� When a variable is indicated (for example, WORKA=workarea) you can use anRX-type address, or registers 2 to 12.

� When a pointer is indicated (for example, DATAPTR=Data buffer pointer) youcan use an RX-type address, or registers 2 to 12. If a register is specified, itcontains the address of the target area, not the address of the field that con-tains the address of the area.

� When a literal is indicated you must specify one of these operands:

RESORCE This operand is a 4-byte field.LENGTH This operand is a 4-byte field.RC This operand is a 1-byte field.

The return code is also supplied in register 15.

Syntax Notation : The syntax notation used for macro operands is described inAppendix A, “Reading the Syntax Diagrams” on page 303.


EMSSTRT, Initiate the Macro InterfaceEMSSTRT initiates the macro interface between the ASR and CS. This macromust be the first macro run when the ASR gets control after a subtask is attached.When a nonzero return code (RC) is returned, this Application Service Routinemust terminate.

EMSSTRT

55─ ─name──EMSSTRT─ ──┬ ┬──────────────── ──┬ ┬──────────────────── ─────────────5%└ ┘──RC=return_code └ ┘──,VERSID=version_id

Figure 45. Syntax of the EMSSTRT, Initiate the Macro Interface

RCThis is returned by NetView Access Services and specifies the variable inwhich a return code is returned to the program. The following return codes canbe expected:

X'00' Normal Return.X'0C' Addressability with CS not established.

VERSIDThis is returned by NetView Access Services and specifies the variable in

| which the version ID (eight characters: leading 00, version, release, modifica-| tion level; for example 00020101 for Version 2 Release 1 Modification Level 1)| is returned to the program.

EMSALLOC, Request a SessionEMSALLOC requests a session with an APPL LU or a printer LU. When thesession has been established, the initiating LU is logically connected to a target LUor subsystem.

The response for the completion of this macro is received by the EMSRECV macro,with WHTRCVD=Allocation Response (X'10'), and RESORCE=Resource ID forthe established session. This returns the resource ID for the established session.

The macro has two parameters, TPN=Transaction_Program_name_of_target_ASRand PIP=ASR, to distinguish an Application Service Routine (ASR) from an applica-tion running in a different address space.

In the case of ASR-to-ASR communication, the macro establishes two internal halfsessions: a quasi server session for the requesting ASR, and a quasi terminalsession for the target ASR.

After allocation this macro issues an Allocation Received with WHTRCVD=X'08'and RESORCE=resource ID of the quasi terminal session that is received from thetarget ASR designated by the Transaction Program Name (TPN). An AllocationResponse is sent to the requesting ASR with the resource ID of the quasi serversession.


EMSALLOC

55──name──EMSALLOC─ ──WORKA=workarea ──,PLUNAME=primary_LU_name ───────────────5

5─ ──,SLUNAME=secondary_LU_name ──,MODNAME=logmode_entry_name ─────────────────5

5─ ──┬ ┬──────────────────────── ──────────────────────────────────────────────5└ ┘──,SECURTY=VTAM_password

┌ ┐─,PIP=SNGL───────5─ ──┬ ┬───────────────────────────────────────────── ──┼ ┼───────────────── ────5

└ ┘──,TPN=Transaction_Program_Name_of_target_ASR └ ┘──,PIP= ──┬ ┬─SNGL─ ├ ┤─CLS── ├ ┤─SHR── └ ┘─ASR──

5─ ──┬ ┬────────────────────────────── ──┬ ┬──────────────────────────── ────────5└ ┘──,DATAPTR=data_buffer_pointer └ ┘──,LENGTH=data_buffer_length

5─ ──┬ ┬─────────────────────────────── ──┬ ┬──────────────────────────── ───────5└ ┘──,TRMRSID=terminal_resource_ID └ ┘──,SINFO=session_information

5─ ──┬ ┬────────────────────────────────────────────────────────── ────────────5└ ┘──,USERFLD=user data to be associated with session request

┌ ┐─,PRINTER=NO────────5─ ──┬ ┬─────────────────────────────── ──┼ ┼──────────────────── ───────────────5

└ ┘──,MTSDATA=mts_data_information └ ┘──,PRINTER= ──┬ ┬─NO── └ ┘─YES─

┌ ┐─,SLIMIT=ð─────── ┌ ┐─,BIDPROT=NO────────5─ ──┼ ┼───────────────── ──┼ ┼──────────────────── ──┬ ┬───────────────── ───────5%

└ ┘──,SLIMIT= ──┬ ┬─ð─ └ ┘──,BIDPROT= ──┬ ┬─NO── └ ┘──,RC=return_code └ ┘─n─ └ ┘─YES─

Figure 46. Syntax of the EMSALLOC, Request a Session Macro

WORKAThis is supplied to NetView Access Services and is the work area for interfaceparameters. This is mandatory for VTAM printer allocation if PRINTER=YES isspecified.

PLUNAMEThis is supplied to NetView Access Services and is an 8-byte field. It indicatesthe primary LU name for which a session must be initialized or logically con-nected. The field must be left blank for ASR-to-ASR communication.

It is not applicable for VTAM printer allocation.

SLUNAMEThis is supplied to NetView Access Services and is an 8-byte field. It is man-datory for relay mode and is ignored for pass mode. It indicates the secondaryLU name that is used for the session to be initialized with the primary LUdefined in the PLUNAME operand, described previously. It is also mandatoryfor VTAM printer allocation if PRINTER=YES is specified. In this case it indi-cates the LU name of the printer. This field must be left blank for ASR-to-ASRcommunication.

MODNAMEThis is supplied to NetView Access Services and is an 8-byte field. It specifiesthe name of the entry in the logmode table that contains the session parame-ters for the new session.


SECURTYThis is supplied to NetView Access Services and is an 8-byte field. It isoptional and indicates the LU password as specified in the VTAM APPL defi-


nitions to be used for the secondary LU name specified in the SLUNAMEoperand.


TPNThis is supplied to NetView Access Services and is mandatory if ASR-to-ASRcommunication is requested.

This is the 8-character name of the target server that is also specified in theNAME operand of the SERVRTN installation macro for this ASR.


PIPThis is supplied to NetView Access Services and is mandatory if ASR-to-ASRcommunication is requested.

It specifies the optional parameters CLS, SNGL, SHR, or ASR:

CLS Indicates that the terminal must be passed via VTAM CLSDST/PASS tothe Primary LU defined in the PLUNAME operand. That is, the sessionis a pass mode session.

SNGLThis is the default and indicates that a single ACB must be used by CSto establish a session for the secondary LU defined in the SLUNAMEoperand (one ACB for each SLU). That is, each session uses a singleACB, and does not share an ACB with any other sessions. This is alsoreferred to as Unique.

SHR Indicates that a Shared ACB should be used by CS to establish asession for the secondary LU defined in the SLUNAME operand. Thatis, more than one session can share one ACB (SLU name). SHR is notsupported by all applications.

ASR Means that an ASR-to-ASR communication is to be started. This alwaysimplies relay mode.

SNGL and SHR are both used for relay mode sessions. This field is not appli-cable for VTAM printer allocation.

DATAPTRThis is supplied to NetView Access Services and is mandatory if LENGTH isspecified, otherwise it is optional.

This specifies the address of the data buffer and is optional for pass mode.It is not applicable for VTAM printer allocation.

LENGTHThis is supplied to NetView Access Services and is mandatory if DATAPTR isspecified, otherwise it is optional.

It specifies the variable in which the data buffer length is to be supplied.It is not applicable for VTAM printer allocation.

TRMRSIDThis is supplied to NetView Access Services and is mandatory if CLS is speci-fied, that is, in pass mode.

It specifies the variable in which the terminal resource ID is to be supplied.This is for the terminal LU to be passed to the primary LU defined in the


PLUNAME operand. This is a 4-byte field. This operand is ignored for relaymode. It is not applicable for VTAM printer allocation.

SINFOThis is supplied to NetView Access Services and is mandatory if ASR-to-ASRcommunication is requested. It is ignored for all other cases.

SINFO is a 4-byte pointer that points to an 11-byte field that must contain infor-mation about the terminal, such as screen size values and whether the terminalsupports Extended Data Stream capability. This information applies to theVTAM terminal session and macro EMSALLOC passes it to the internal quasiterminal session of the target ASR.

It is part of the BIND session request coming from the PLU, which for LU-type2 and 0 sessions had originally been specified with operand PSERVIC in theMODEENT macro instruction in the VTAM installation.


USERFLDThis is supplied to NetView Access Services and is optional. It specifies thevariable that contains the user data to be associated with this session request.

The USERFLD variable allows the ASR to associate a 4-byte data field with asession initiation request. The data provided in this field is returned to the ASRwhen an Allocation Response is received in the EMSCRECV macro operandUSERFLD.

It is optional for VTAM printer allocation if PRINTER=YES is specified, andspecifies user data associated with the allocation request.

MTSDATAThis is supplied to NetView Access Services and is mandatory to allocate asession with Model Terminal support data.

MTSDATA is a 25-byte field that must be provided with the data shown in thefollowing table, that is, a one-byte count field for the next three names, whichare model name, and the primary and alternative printer LU names.

Note: NetView Access Services supports Model Terminal data as defined byACF/VTAM Version 3 Release 3. ACF/VTAM* supplies systems with the exactmodel terminal definition name, plus the associated printer information neededto dynamically define the second logical unit. For further information on modelterminal support, refer to VTAM Resource Definition Reference.


PRINTERThis is supplied to NetView Access Services. The coding of this parameter isoptional.

Possible values are:

Y (Yes) Indicates that CS is to allocate a printer LU (LU 1 or LU 3).

Note: For VTAM LU type-1 sessions, the SNA protocol allows theusage of either FM-Profile 3 or 4, as well as TS-Profile 3 or 4.NetView Access Services supports only FM-Profile 3 andTS-Profile 3.

N (No) Indicates that CS is not to allocate a printer LU, but to an applica-tion.

SLIMITThis is supplied to NetView Access Services and is an optional 2-byte field. Itis valid only for printer sessions. It contains the send limit in hexadecimal formand specifies the number of queued EMSSENDD macro calls that can beissued to CS for a particular session. The default is zero (no limit).

The SLIMIT keyword must be used to prevent a shortage of storage when theLU that is to receive the data sent by the EMSSENDD macro is not fastenough, and data is to be queued by CS. If the limit is reached, it means thatCS has already queued the number of sends specified for the SLIMIT keywordand cannot send more data to the LU because the LU is still processing thefirst send. A return code is passed back via the EMSSENDD macro indicating

Table 25 (Part 1 of 2). Field Description of the Layout for EMSALLOC Macro MTSData

MTSDATA=Field of 25 Byte MTS-Data Information.

OffsetDecimal

OffsetHex

DataType

Length Description

0 0 Binary 1 X'00' Must be set if no names are to begiven.

X'01' Must be set if the first of the 3 fieldsis given.

X'02' Must be set if the first and second ofthe 3 fields are given.

X'03' Must be set if all three fields aregiven.

Note: The unused fields must be set to ablank fill character (X'40').

1 1 Character 8 This field contains the model name and cancontain a maximum of 8 bytes left adjusted.If the model name has less than 8 bytes, thefill characters are blanks (X'40').

9 9 Character 8 This field contains the primary printer LUname and can contain a maximum of 8 bytesleft adjusted. If the primary printer has lessthan 8 bytes, the fill characters are blanks(X'40').

17 11 Character 8 This field contains the alternative printer LUname and can contain a maximum of 8 bytesleft adjusted. If the alternative printer hasless than 8 bytes, the fill characters areblanks (X'40').


this situation. When this occurs, the ASR must delay the send request andresend it later.

BIDPROTThis is supplied to NetView Access Services and is an optional parameter. IfYES is specified, then applications that are sending BIDs are protected againstunexpected terminal input. NO is the default.


X'00' Successful acceptanceThe macro was successfully accepted by NetView Access Services.

X'08' Invalid resource IDThe macro was issued with an invalid resource ID. Either the sessionhas already been deallocated, or a request has already been queued.

X'0C' Parameter errorThe macro was issued with a parameter containing an invalid value or amandatory parameter has not been specified.

X'10' Processing errorAn internal error has occurred, for example, shortage of storage or arecovery has been performed.

This is mandatory for VTAM printer allocation if PRINTER=YES is specified.

EMSDEALL, Deallocate a SessionEMSDEALL ends a session between a terminal or an application LU and NetViewAccess Services.

EMSDEAL

55──name──EMSDEALL─ ──WORKA=workarea ──,RESORCE=resource_ID ───────────────────5

┌ ┐─,TYPE=FLUSH───────5─ ──┼ ┼─────────────────── ──┬ ┬───────────────── ─────────────────────────────5%

└ ┘──,TYPE= ──┬ ┬─FLUSH─ └ ┘──,RC=return_code ├ ┤─LOCAL─ └ ┘─RESET─

Figure 47. Syntax of the EMSDEALL, Deallocate a Session Macro

WORKAThis is supplied to NetView Access Services and is the work area for interfaceparameters.

RESORCEThis is supplied to NetView Access Services and specifies the variable in whichthe resource ID is to be specified.

TYPEThis is supplied to NetView Access Services and is optional. It specifies thetype of deallocation:


FLUSHIndicates that the session must be terminated. This is the default value.

LOCALSpecifies that the session must not be terminated. For LU2 sessions thereceiving of data is stopped (that is, an SNA SIGNAL request from the LUfor NetView Access Services to receive data from it is refused).

RESETSpecifies that messages will be received again. This type resetsTYPE=LOCAL.






EMSFBUF, Free a BufferEMSFBUF frees a data buffer and requeues it to the buffer pool. The NetViewAccess Services buffer layout is shown in “Using NetView Access Services Buffers”on page 209.

EMSFBUF

55──name──EMSFBUF─ ──WORKA=workarea ──,BUFFPTR=data_buffer_pointer ────────────5

5─ ──┬ ┬───────────────── ────────────────────────────────────────────────────5%└ ┘──,RC=return_code

Figure 48. Syntax of the EMSFBUF, Free a Buffer Macro


BUFFPTRThis is supplied to NetView Access Services and is a 4-byte field. It specifiesthe variable that contains the buffer address for the buffer to be returned to thebuffer pool. This field is cleared if the buffer has been freed.







EMSGATTR, Return Information about a SessionEMSGATTR returns information referring to the specified session.

EMSGATTR

55──name──EMSGATTR─ ──WORKA=workarea ──,RESORCE=resource_ ─────────────────────5

5─ ──,LUNAME=logical_name_of_the_SLU ──,MODNAME=logmode_entry_name ────────────5

5─ ──,STATUS=LU_and_session_status ──,SINFO=session_information ───────────────5

5─ ──,PLUNAM=logical_unit_name_of_the_PLU ──LUTYPE=LU_session_type ────────────5

5─ ──┬ ┬───────────────────────── ──┬ ┬─────────────────────────────── ──────────5└ ┘──,EXFMH=exchange_of_FMHs └ ┘──,MTSDATR=MTS_data_information

5─ ──┬ ┬──────────────────────────── ──┬ ┬───────────────────────────── ─────────5└ ┘──,NETIDOR=originator_net_ID └ ┘──,NETIDDS=destination_net_ID

5─ ──┬ ┬────────────────────────────────────── ──┬ ┬───────────────── ──────────5%└ ┘──,TMODNAM=original_logmode_entry_name └ ┘──,RC=return_code

Figure 49. Syntax of the EMSGATTR, Return Information about a Session


RESORCEThis is supplied to NetView Access Services and specifies the variable in whichthe resource ID is to be specified.

LUNAMEThis is returned by NetView Access Services and is an 8-byte field. It indicatesthe LU name of the SLU, related to the specified resource ID.

MODNAMEThis is returned by NetView Access Services and is an 8-byte field. It indicatesthe name of the entry in the logmode table that contains session parameters forthe session.


STATUSThis is returned by NetView Access Services and is a 1-byte field. LU andsession status information are returned in the area addressed by thisparameter:

X'10' Session activeIndicates that the session is active.

X'02' Session initiation request queuedIndicates that a session request has been queued to CS.

X'04' Session initiation in progressIndicates that a session is being established.

X'20' Session InactiveIndicates that the session is inactive.

X'22' Session termination request queuedIndicates that a session termination request has been queued to CS.

X'24' Session termination in progressIndicates that a session is being terminated.

SINFOThis is returned by NetView Access Services and is an 11-byte field. LU andsession information are returned in the area addressed by this parameter, thatis, terminal characteristics. For LU2 and LU0 sessions the 11-byte PSERVICoperand specified in the VTAM installation MODEENT macro instruction isreturned in this field.

It contains the screen size values and an indication whether the terminal sup-ports the Extended Data Stream facility.

PLUNAMThis is returned by NetView Access Services and is an 8-byte field. This indi-cates the LU name of the PLU, related to the specified resource ID.

LUTYPEThis is returned by NetView Access Services and is a 1-byte field. The LUsession type information is returned by this parameter in hexadecimal form:

X'00' = LU type 0X'01' = LU type 1X'02' = LU type 2X'03' = LU type 3

EXFMHThis is returned by NetView Access Services and is an optional 1-byte field.

A value of X'01' is returned in the area addressed by this parameter if theexchange of the Function Management Header is supported by the LU, other-wise a value of X'00' is returned.

MTSDATRThis is returned by NetView Access Services and is optional. MTS data isreturned, that is, model name, and primary and alternative printer namesextracted from VTAM installation tables, or by the 'logon applid(....) ....'command.


NETIDORThis is returned by NetView Access Services and is the Network Identificationof the Originator (secondary) LU. It is an 8-byte field that must be left justifiedand in uppercase characters. If the NETID is not provided this parameter con-tains '********'.

NETIDDSThis is returned by NetView Access Services and is the Network Identificationof the Destination (primary) LU. It is an 8-byte field that must be left justifiedand in uppercase characters. If the NETID is not provided this parameter con-tains '********'.

TMODNAMThis is the logmode entry name supplied by VTAM.




Table 26. Field Description of the Layout for EMSGATTR Macro MTS Data

MTSDATR=Field of 25 Byte MTS-Data Information.

OffsetDecimal

OffsetHex

DataType

Length Description

0 0 Binary 1 X'00' Is returned if no names are definedin VTAM, and the next 3 fields areset to blank (X'40').

X'01' Is returned if one of the 3 fields isdefined in VTAM, and the otherfields are set to blank (X'40').

X'02' Is returned if two of the 3 fields aredefined in VTAM, and the otherfields are set to blank (X'40').

X'03' Is returned if all 3 fields are definedin VTAM.

1 1 Character 8 This field contains the model name and cancontain a maximum of 8 bytes left adjusted.If the model name has less than 8 bytes, thefill characters are blanks (X'40').

9 9 Character 8 This field contains the primary printer LUname and can contain a maximum of 8 bytesleft adjusted. If the primary printer has lessthan 8 bytes, the fill characters are blanks(X'40').

17 11 Character 8 This field contains the alternative printer LUname and can contain a maximum of 8 bytesleft adjusted. If the alternative printer hasless than 8 bytes, the fill characters areblanks (X'40').



X'10' Processing errorAn internal error has occurred, for example, shortage of storage, or arecovery has been performed.

EMSGBUF, Get a BufferEMSGBUF requests a free data buffer from the buffer pool. The address of theobtained buffer is returned in the BUFFPTR variable. The NetView Access Ser-vices buffer layout is shown in “Using NetView Access Services Buffers” onpage 209.

EMSGBUF

55──name──EMSGBUF─ ──WORKA=workarea ──,BUFFPTR=data_buffer_pointer ────────────5

5─ ──┬ ┬─────────────────────── ──┬ ┬───────────────── ─────────────────────────5%└ ┘──,LENGTH=buffer_length └ ┘──,RC=return_code

Figure 50. Syntax of the EMSGBUF, Get a Buffer Macro


BUFFPTRThis is supplied to NetView Access Services and is a 4-byte field. It specifiesthe variable in which the address of the obtained buffer is to be returned.

LENGTHThis is returned by NetView Access Services and is optional. It specifies thelength of the requested buffer.





EMSNPM, NetView Performance Monitor InterfaceThis macro is used to send event information that is used for session correlation byNetView Performance Monitor.

EMSNPM

55──name──EMSNPM─ ──WORKA=workarea ──,UID=user_ID ──,GRPID=group_ID ────────────5

5─ ──,ACCOUNT=account_number ──,TYPE=type ─────────────────────────────────────5

5─ ──┬ ┬─────────────────────────────────── ───────────────────────────────────5└ ┘──,APPLRSID=application_resource_ID

5─ ──┬ ┬──────────────────────────────── ──,RC=return_code ────────────────────5%└ ┘──,TERMRSID=terminal_resource_ID

Figure 51. Syntax of the EMSNPM, NetView Performance Monitor Macro

WORKAThis is supplied to NetView Access Services and is the work area for interfaceparameters, used by this macro.

UIDThis is supplied to NetView Access Services and is the user ID of the user forNetView Access Services. It contains a maximum of 8 bytes left adjusted.

GRPIDThis is supplied to NetView Access Services and is the group ID of the user forNetView Access Services. It contains a maximum of 8 bytes left adjusted.

ACCOUNTThis is supplied to NetView Access Services and is an 8-byte field. This is theaccount number of the user of NetView Access Services.

TYPEThis is supplied to NetView Access Services and is a 1-byte field that indicatesthe Event Type. The following event types are defined:

X'01' Logon to NetView Access ServicesX'02' Reconnect to NetView Access ServicesX'03' Change selected application sessionX'04' Escape to NetView Access ServicesX'05' Logoff from NetView Access ServicesX'06' Disconnect from NetView Access ServicesX'07' Logoff from NetView Access Services and pass the terminal to

another applicationX'08' Disconnect from NetView Access Services and pass the terminal to

another applicationX'09' Application session establishedX'0A' Application session terminationX'0B' Application session establishment and pass the pseudo terminal

(ACB) to another applicationX'0C' Application session termination and pass the pseudo terminal (ACB)

to another application.


APPLRSIDThis is supplied to NetView Access Services and is the application sessionresource ID. It is a 4-byte field and is required for event types X'03', X'09',X'0A', X'0B', and X'0C'. It is ignored for all other event types.

TERMRSIDThis is supplied to NetView Access Services and is the terminal sessionresource ID. It is a 4-byte field and is required for all events types exceptX'04', X'0A', and X'0C'.

RCThis is returned by NetView Access Services and is a 4-byte field. It specifiesthe variable in which a return code is returned to the program. The followingreturn codes can be expected:



EMSPRETR, Prepare to ReceiveThe purpose of the macro EMSPRETR is to change the conversation from send toreceive state in preparation to receive data. When the macro has been completed,a 'null RU' with change direction has been sent to the 'target LU' by VTAM (onlyif NetView Access Services is not yet in receive state, in this case no action isrequired).

EMSPRETR

55──name──EMSPRETR─ ──WORKA=workarea ──,RESORCE=resource_ID ───────────────────5

5─ ──┬ ┬───────────────── ────────────────────────────────────────────────────5%└ ┘──,RC=return_code

Figure 52. Syntax of the EMSPRETR, Prepare to Receive Macro

WORKAWork area for interface parameters.

RESORCEThis is supplied to NetView Access Services and is mandatory. It specifies thevariable in which the resource ID is to be defined.

RCThis is returned by NetView Access Services and is optional. It specifies thevariable in which a return code is returned to the program. Expected returncodes have the following values:






EMSRECV, Receive InformationEMSRECV waits for information to arrive on the input queue and then receives thedata. If information is already available, the program receives it without waiting.The information can be data, conversation status, or a request for confirmation.

EMSRECV

55──name──EMSRECV─ ──WORKA=workarea ──,RESORCE=resource_ID ────────────────────5

5─ ──,DATAPTR=data_buffer_pointer ──,LENGTH=data_length ───────────────────────5

5─ ──,USERFLD=user_data_associated_with_session_request ──────────────────────5

5─ ──,WHTRCVD=what_received ──┬ ┬───────────────────── ──,RC=return_code ───────5%└ ┘──,TIMSTMP=time_stamp

Figure 53. Syntax of the EMSRECV, Receive Information Macro


RESORCEThis is returned by NetView Access Services and specifies the variable inwhich the resource ID is to be returned.

DATAPTRThis is returned as zero by NetView Access Services if anything other thandata is received. It specifies the variable in which the data buffer address is tobe returned. For information on NetView Access Services buffer usage, referto “Using NetView Access Services Buffers” on page 209.

LENGTHThis is returned by NetView Access Services and contains zero if no data isreceived.

It specifies the variable in which the data buffer length is to be returned.

USERFLDThis is returned by NetView Access Services and is a 4-byte field. (This is onlyvalid for WHTRCVD = X'10' allocation response.) The field contains the valuespecified in the USERFLD parameter of the EMSALLOC macro.

WHTRCVDThis is returned by NetView Access Services and is a 1-byte field.

TIMSTMPThis is returned by NetView Access Services and is an optional parameter.

It is an 8-byte field which specifies the variable in which the timestamp of thereceived data is returned to the program.


RCThis is returned by NetView Access Services and is a 1-byte field. It specifiesthe variable in which the WHTRCVD indicator is returned to the program.

Table 27 indicates what is received and shows valid WHTRCVD and RC combina-tions.

Table 27 (Part 1 of 4). Return Codes for WHTRCVD

WHTRCVD Return Code

Value Description Value Description

X'00' Macro.Indicates the results of the macro call.

X'00' Successful completion.The macro call was successfully completed.

X'08' Parameter error.Either the macro was issued with a parametercontaining an invalid value, or a mandatoryparameter has not been specified.

X'0C' Unsuccessful completion.The macro has terminated with an error. Thereturned parameters are not valid.

X'01' Data.Indicates that data has been received from theLU whose resource ID is returned in theRESORCE operand.

X'00' Successful completion.The data has been received without error. Thedata buffer contains the data that has beenreceived.

X'20' LUSTAT received.Indicates that a LUSTAT has been received.The data buffer contains the 4-byte LUSTATdata.

X'30' Send error local.Indicates that a send error has been recog-nized while in send mode.

X'34' Send error remote.Indicates that a send error has been recog-nized while in receive mode.

X'40' Function Management Header.Indicates to the ASR that the received datacontains a Function Management Header.

X'50' Inform ASR if EMSRECV macro could not becompleted because an insufficient amount ofNetView Access Services buffers were avail-able.The ASR must issue an EMSDEALL macro forthe particular terminal and related applicationsessions.

X'05' Prepare to receive request.A second ASR has issued an EMSPRETRmacro to change the conversation state fromsend to receive mode.

X'00' Successful completion.The “prepare to receive” request has success-fully been received.

X'06' ATTN key pressed.Indicates that the user pressed the ATTN key.

X'00' Successful completion.The keystroke ATTN has been received withouterror.

X'08' Allocation.Indicates that an allocation has been receivedfrom the LU whose resource ID is returned inthe RESORCE operand (that is, a logonrequest from an LU).

X'00' Successful completion.The allocation request has been successfullycompleted. The data pointer points to a bufferarea containing BIND user data (if present).

X'01' An LU 0 terminal has been switched off and onagain.



WHTRCVD Return Code


X'10' Allocation response.Indicates that a response to an allocationrequest (EMSALLOC macro) has been receivedfrom the LU whose resource ID is returned inthe RESORCE operand.

X'00' Successful completion.The allocation request has been successfullycompleted.

X'10' Allocation failure.Indicates the session could not be allocatedbecause of an error.

X'11' Allocation session-parm error.Indicates the session could not be allocatedbecause an invalid MODNAME is specified orthe session partner did not accept the sessionparameters.

X'12' Allocation PIP data not accepted.Indicates the target LU has not accepted thePIP data.

X'13' Allocation PIP error.Indicates the target LU detected an error in thePIP data. That is, not all required data hasbeen specified, or incorrect values have beensupplied.

X'14' Allocation security invalid.Indicates the session was rejected becauseinvalid security information has been provided.

X'15' IBM reserved.

X'16' ACB already open.Indicates the session could not be allocatedbecause the SLU name specified in theEMSALLOC macro is already opened.(Corresponds to ACB error field value X'58'.)

X'17' ACB not found in VTAM configuration table.Indicates the session could not be allocatedbecause the SLU name specified in theEMSALLOC macro could not be found in theVTAM configuration table.(Corresponds to ACB error field value X'5A'.)

X'18' Allocation failure.Indicates the session could not be allocated.Retry the allocation request with a backupapplication.



WHTRCVD Return Code


X'20' Deallocate.Indicates that a deallocation indication has beenreceived for the LU whose resource ID isreturned in the RESORCE operand. This couldbe caused by a session failure, session termi-nation, a timer interrupt, or in the case of anASR-to-ASR session notification of a busy con-dition or that this condition has been revoked.

X'00' Deallocate normal.Indicates that deallocate for an active sessionhas been received.An EMSDEALL macro must be issued.

X'20' Deallocate timer.Indicates that NetView Access Services recog-nized an elapsed wait time for a session to anapplication.An EMSDEALL macro must be issued.

X'24' Deallocate error.Indicates that deallocate for an active sessionhas been received because of an error condi-tion.An EMSDEALL macro must be issued.

X'28' Deallocate timer.Indicates that NetView Access Services recog-nized an elapsed wait time for a session to aterminal.An EMSDEALL macro must be issued.

X'30' Deallocate local.Indicates that the remote partner of theASR-to-ASR session has issued a DeallocateType=Local macro due to a busy condition.The return code is valid only for anASR-to-ASR session.

X'34' Deallocate reset.Indicates that the remote partner of theASR-to-ASR session has issued a DeallocateType=Reset macro because the busy conditionis revoked by the partner ASR. The returncode is valid only for an ASR-to-ASR session.

X'21' Release requested.Indicates that another application wants toestablish a session to a printer that is already inuse by the ASR receiving this indication.

X'00' Release requested.The ASR receiving this indication must deallo-cate the printer as soon as possible.

X'22' Allocation failed.Indicates that a previous allocation request for aprinter cannot be performed successfully.

X'00' Allocation failure but queued.Indicates that the requested printer is currentlynot available, for example, in use by anotherapplication, but the allocation request is queuedto VTAM. As soon as the printer is free, therequesting ASR receives WHTRCVD CodeX'08' = Allocation.

X'04' Allocation failure not queued.Indicates that the requested printer cannot beobtained and a session is not established.

X'30' Application session changed.Indicates that the session is terminated by aCLSDST OPTCD=PASS and a session withanother application is established.

X'00' Application session changed.Indicates that the session with the application isterminated and a new session with an applica-tion is established. Information about the newsession, for example, PLU name, PSERVICdata, can be obtained with the EMSGATTRmacro. No data is received by the EMSRECVmacro with this WHTRCVD return code.



WHTRCVD Return Code


X'40' CLSDST/PASS response.Indicates that a CLSDST/PASS operation hasbeen performed for the LU whose resource IDis returned in the RESORCE operand.

X'00' Successful completion.The terminal was successfully returned toNetView Access Services (SIMLOGON redrive).

X'40' Timeout.Indicates that timeout value FF was specified inthe input parameter for CLSDST return value.

X'44' SIMLOGON not issued or not successful.Indicates SIMLOGON was not issued or wasnot successful.

X'48' CLSDST/PASS failed.Indicates that CLSDST/PASS failed.

X'49' CLSDST/PASS failed.Indicates that CLSDST/PASS failed. Retry theallocation request with a backup application.

X'4C' CLSDST/PASS successful.Indicates that CLSDST/PASS was successful.

X'50' Terminate quiesce indication.Indicates that a Terminate Quiesce commandhas been entered at the operator console.

X'50' Terminates quiesce ON.Indicates that terminate quiesce has been setby the operator. The ASR should not initiatenew sessions.

X'58' Terminates quiesce OFF.Indicates that terminate quiesce has been resetby the operator.

X'80' End of job.Indicates that a Terminate Immediate commandhas been entered at the operator console or thelast session has been terminated in TerminateQuiesce mode. The ASR must perform its endprocessing for all data sets and return to theoperating system.

X'00' End of job received.Indicates that a Terminate Immediate commandhas been entered at the operator console.

X'90' Application status information.The name of the application is passed in thefirst 8 bytes of a buffer pointed to by the datapointer.

X'00' Application is OFFLINE.

X'01' Application is ONLINE.

X'02' The VTAM macro APPSTAT INQUIRE failed forthe requested LU.

X'03' A CLSDST OPTCD=PASS to the requestedapplication failed. This application is treated asOFFLINE.

X'A0' NPM Interface established or reconnected. X'00' Informs ASR that the connection to NPM isestablished and that the EMSNPM macro canbe invoked to start sending events aboutalready established sessions and new sessionsthat are to be established or terminated.


EMSREQTS, Request to SendEMSREQTS sends an SNA SIGNAL command to the session partner specified bythe resource ID. When the macro is completed, the SIGNAL is sent to the sessionpartner.

EMSREQTS

55──name──EMSREQTS─ ──WORKA=workarea ──,RESORCE=resource_ID ──,RC=return_code ─5%

Figure 54. Syntax of the EMSREQTS, Request to Send Macro


RESORCEThis is supplied to NetView Access Services and specifies the variable in whichthe resource ID is to be defined.







EMSSENDD, Send DataEMSSENDD sends data to the session partner specified by the resource ID. Thedata format consists of logical records. The amount of data is specified independ-ently of the data format. When the macro has been completed, the data buffer isaccepted by CS for sending to VTAM.

EMSSENDD

55──name──EMSSENDD─ ──WORKA=workarea ──,RESORCE=resource_ID ───────────────────5

┌ ┐─,FMH=NO────────5─ ──,DATAPTR=data_buffer_pointer ──,LENGTH=data_length ──┼ ┼──────────────── ───5 └ ┘──,FMH= ──┬ ┬─NO── └ ┘─YES─

5─ ──┬ ┬───────────────── ────────────────────────────────────────────────────5%└ ┘──,RC=return_code

Figure 55. Syntax of the EMSSENDD, Send Data Macro



DATAPTRThis is supplied to NetView Access Services and specifies the address of thedata buffer. For information on NetView Access Services buffer usage, refer to“Using NetView Access Services Buffers” on page 209.

LENGTHThis is supplied to NetView Access Services and specifies the length of thedata. If zero is specified, no data is sent.

FMHThis is supplied to NetView Access Services. The coding of this keyword isoptional. The following are valid values:

YES Indicates to CS that the data to be sent to the printer contains a FunctionManagement Header.

NO This is the default and indicates to CS that normal data is to be sent tothe printer.

Note: This parameter is only for LU1 printer sessions and is rejected orignored for all other LU type sessions.



X'00' Successful completionThe macro was completed successfully.

X'08' Parameter errorThe macro was issued with a parameter containing an invalid value or amandatory parameter has not been specified.

X'0C' Unsuccessful CompletionThe macro has terminated with an error. The returned parameter orparameters are not valid.


X'1C' Send request failedIndicates that the session with the LU has already ended. It is only validfor LU1 or LU3 printer sessions. This means that Communication Ser-vices has already sent a 'Deallocate WHATRCVD' code to the ASR, butit did not reach the ASR before the ASR issued the EMSSEND macrocall. If this return code is received, the ASR must wait for the'Deallocate WHATRCVD' indication and can then establish a newsession with the printer by issuing a new EMSALLOC macro call.

X'2C' Send request failedIndicates that the send request has failed because CS has reached thelimit specified by the EMSALLOC macro keyword SLIMIT and cannotsend more data to the LU at the moment. It is only valid for LU1 or LU3sessions. The ASR that issued the EMSSENDD macro call must delaythe request and resend it later.


EMSSENDE, Send Error ResponseEMSSENDE informs the session partner specified by the resource ID that theNetView Access Services has detected an error (that is, a negative response issent to the partner LU).

EMSSENDE

55──name──EMSSENDE─ ──WORKA=workarea ──,RESORCE=resource_ID ───────────────────5

┌ ┐─,TYPE=LUSTAT───────5─ ──┼ ┼──────────────────── ──,SDATA=sense_data ──┬ ┬───────────────── ─────────5%

└ ┘──,TYPE= ──┬ ┬─LUSTAT─ └ ┘──,RC=return_code └ ┘─SENSE──

Figure 56. Syntax of the EMSSENDE, Send Error Response



TYPEThis is supplied to NetView Access Services and is optional. It specifies thetype of SDATA that must be sent.

SENSE Specifies that SENSE data must be sent.LUSTAT Indicates that the LU status must be sent. This is the default value.

If LUSTAT is specified, the data of the SDATA field is sent as the LU status tothe session partner identified in the RESORCE parameter.

If SENSE is specified, the data of the SDATA field is sent as sense data to thesession identified in the RESORCE parameter. This is not supported for LU0and LU2.

SDATAThis is supplied to NetView Access Services and is a 4-byte field. It specifiesthe information that must be sent to the session partner. The sense data or LUstatus data describes the type of error detected.







Using NetView Access Services BuffersNetView Access Services maintains a pool of buffers used to send and receivedata, and in some cases to transfer data between the CS and an ASR. Program-mers that customize NetView Access Services by writing their own ASR must usethe buffer facilities to establish sessions and to send and receive data for sessions.NetView Access Services buffer facilities are invoked by a user ASR using theNetView Access Services “get buffer” (EMSGBUF) and “free buffer” (EMSFBUF)macros.

NetView Access Services data buffers are variable in length. The length of a databuffer element is specified as a NetView Access Services installation input param-eter. When a buffer is allocated, the pointer returned specifies the address of thebuffer element—this buffer element is mapped by the DSECT EMSCBUFE. Thelength of an allocated buffer element can be determined by investigating the lengthfield of the allocated data buffer—the LENGTH parameter of the EMSGBUF macrois optional and can therefore be omitted. A user-written ASR must allocate bufferswhen:

� It requests the sending of data on a session using the NetView Access Ser-vices EMSSENDD macro.

� It requests a session with an application and supplies BIND user data.

When supplying BIND user data, only a single data buffer is required. However,when buffers are required for the purpose of sending Function Management Data(FMD) to a session, the length of the data to be sent may be more than the lengthof the NetView Access Services buffer. In this case, the user-written ASR mustallocate as many buffers as necessary to contain the data. The buffers must bechained together using the secondary chain pointers with the last buffer element inthe chain having a secondary chain pointer set to zero.

In all cases, whether single data buffers or a chain of buffers, when moving datainto a buffer, the length field, within the NetView Access Services buffer element,must be set to the number of bytes of data that the buffer element contains. Auser-written ASR may receive buffer elements using the EMSRECV macro when itreceives:

� An “Allocation Received” element and BIND user data is supplied� FMD or LUSTAT data� Application Status Information.

When data is received by the user-written ASR in these cases, it may consist of asingle buffer or a buffer chain. The length of the data contained in any bufferelement is equal to the value contained in the length field of the buffer element. Inthe case of BIND user data, LUSTAT data, or Application Status Information, only asingle data buffer is received by the ASR. When FMD data is received, however,the data may be contained in several NetView Access Services data buffers linkedby their secondary chain pointers.


When data buffers are received by the user ASR in these cases, it must eitherreturn the buffer elements to CS using the EMSSENDD macro, or free the bufferelements using the EMSFBUF macro, even if the data length of the buffer is zero.

When freeing either a single element or a buffer chain that had been chained bythe Secondary Buffer pointer (FESPTR), only a single EMSFBUF macro need beissued with the buffer pointer parameter specifying the first buffer in the chain. Inthis case the NetView Access Services buffer facility frees all elements in the chain.

However, buffers chained by the Primary Buffer pointer (FEPPTR) must bereleased by EMSFBUF macro invocations for each chained buffer.

The NetView Access Services buffers have the following layout.

Table 28 (Part 1 of 2). Layout of a NetView Access Services BufferOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE * EMSCBUFE0 (0) CHARACTER 16 FEBHDR0 (0) CHARACTER 4 * This word is updated by compare and swap

instructions.0 (0) CHARACTER 2 FEBUID Eye catcher. This field allows module EMSFBUFF to

make sure that nothing else than an EMS buffer,which is not currently free, is chained back into thebuffer pool. This field allows module EMSCSNDF tomake sure that nothing else than an EMS buffer ispassed to VTAM for sending. This field allows main-tenance personnel to check the maximum number ofused buffers and easily locate buffers in a dump.

2 (2) UNSIGNED 2 FEBUFL Buffer/Data length. This field is set to the length ofthe data part of the buffer (FEDATA) when a modulegets the buffer, and is set to the length of the datawithin the buffer when data is moved in.

4 (4) BITSTRING 4 FEBFLAGS 1... .... FEBFLUSH Buffer flush indicator .1.. .... FEBEBRVD End bracket indicator, is directly copied from the SCB

upon receipt of a VTAM RPL in order to check it inEUS.

..1. .... FEBBIDRC BID received indicator ...1 .... FEBFMH FMH indicator .... 1... FEBNOFLU NOFLUSH indicator. If this bit is set, CS will send

this buffer without a CD (change direction) indicator.Used for sends to a terminal.

.... .1.. FEBPANSD Panel sent indicator .... ..1. FEBBBRVD Begin bracket indicator, is directly copied from the

SCB upon receipt of a VTAM RPL in order to check itin EUS.

.... ...1 * Reserved 1... .... FEBCD CD-bit indicator, is directly copied from the SCB upon

receipt of a VTAM RPL in order to check it in EUS. .111 1111 * Reserved 1... .... FEBBUFQ Buffer queued for send .1.. .... FEBDNRD Do not receive data. This flag will be set when an

application sends a BID. This bit is relayed to the ter-minal SCB and no terminal input is accepted as longas no reset occurs.

..1. .... FEBRD Receive data (again). This flag enables terminal inputagain

...1 .... FEBRDNRD Reset ‘Do not receive data’. This flag resetsSCBDNRD and the appropriate counter.

.... 1... FEBDFTER Data from terminal flag .... .1.. FEBKBRS1 Value of keyboard restore bit in WSF buffers (X'F3') .... ..1. FEBKBRS2 Shows if FEBKBRS1 in use


Table 28 (Part 2 of 2). Layout of a NetView Access Services BufferOffsets

Type Length Name (Dim) DescriptionDec Hex .... ...1 FEBRBANS This buffer contains a read buffer answer7 (7) BITSTRING 1 * Reserved8 (8) ADDRESS 4 FEPPTR Primary buffer pointer. Used to create a linked list of

free elements anchored off the EMSBPOOL. Alsoused to create a linked list of buffers anchored off anSCB.

12 (C) ADDRESS 4 FESPTR Secondary buffer pointer. Used to create a secondarylinked list of used buffers. This will be done whendata does not fit into a single buffer. Secondary chainof buffers are treated as a single logical buffer.

16 (10) CHARACTER * FEDATA

The following information refers to some of the items in the buffer layout.

FEBUID This field is for exclusive use of the NetView Access Services BufferManagement routines. It must not be changed by an ASR, and anASR must not rely on this field having a specific content.

FEBFLAGS Any changes in this field must be done using the CS (COMPAREAND SWAP) instruction.

FEBFLUSH If this flag is set to on in a buffer to be sent, the Communication Ser-vices of NetView Access Services sends this buffer immediately withChange of Direction (CD). This flag is initialized with 0 for receivedbuffers.

FEBEBRVD If this flag is set to on , the ASR is informed about an End Bracket(EB) sent by an application, which is to be sent to the terminal.

FEBCD If this flag is set to on , the ASR is informed of a CD sent by an appli-cation, which is to be sent to the terminal. This flag is not checked inCommunication Services of NetView Access Services to determinewhether a buffer is to be sent with CD or not.

FEBNOFLU If this flag is set to on in a buffer to be sent, Communication Servicesof NetView Access Services sends this buffer without CD. This flaghas priority over the FEBFLUSH flag, which means that no CD is sentif both flags are set.

If neither of the flags FEBFLUSH or FEBNOFLU are set, Communication Servicesof NetView Access Services sends a single buffer with CD. If more than one bufferis queued to be sent to the terminal, only the last buffer is sent with CD.



Part 4. NetView Access Services REXX ApplicationProgramming Interface

This part documents general-use programming interface and associated guidanceinformation. It describes the general-use programming interface that allows you towrite REXX execs that can be executed to carry out NetView Access Services func-tions, for example, automatic logon and logoff.

Terminology: Throughout this part, REXX exec is used to mean a REXXprogram. This is to differentiate it from any other program you might write such asa CLIST, or an Application Service Routine.

How to read the syntax diagrams used for the REXX Application ProgrammingInterface functions is described in Appendix A, “Reading the Syntax Diagrams” onpage 303.

Sample REXX execs for automatic logon using the REXX Application ProgrammingInterface are supplied. Refer to Chapter 17, “REXX Execs for Automatic Logon toNetView Access Services and Applications” on page 273. These execs are onlyintended to be examples of how to use the REXX Application Programming Inter-face.



Chapter 15. Introduction

The NetView Access Services REXX Application Programming Interface (abbrevi-ated to NVASAPI) is a programming interface for the Restructured Extended Exec-utor (REXX) language. The NVASAPI provides a means of controlling NetViewAccess Services functions or relay-mode applications, and to simulate user activ-ities.

For further information on REXX language rules and environments, refer to TSOExtension Version 2 Procedures Language MVS/REXX References and TSOExtension Version 2 Procedures Language MVS/REXX User's Guide.

Concept of Virtual TerminalsThis paragraph gives a short overview of the virtual terminal concept used inNetView Access Services, which is essential to understand in order to use theNVASAPI.

NetView Access Services uses the concept of virtual terminals to handle the infor-mation flow between a relay-mode application and the real terminal. A virtual ter-minal is a buffer in memory containing an image of the screen seen on the realterminal. All updates from the application and input entered by the user is reflectedin the virtual terminal. A REXX exec can gain access to such a virtual terminal byusing the NVASAPI. Figure 57 shows the relationship between a REXX exec andthe two types of virtual terminal of NetView Access Services. These are:

� The application virtual terminal where an image of the relay-mode applicationpanel is kept

� The NetView Access Services panel virtual terminal where the actual NetViewAccess Services panel is kept.

All NVASAPI functions described in the following can be used to handle both anapplication virtual terminal and a NetView Access Services panel virtual terminal.

Note: The use of the NVASAPI functions against virtual terminals not currentlydisplayed on the real terminal (running in background) is restricted to virtual termi-nals serving relay-mode applications only.


Figure 57. REXX Exec Interfacing with NetView Access Services Virtual Terminals

Installing the NVASAPIThe NVASAPI is an external function package, which is available as an externalfunction or subroutine to each REXX exec running in the NetView Access Servicesaddress space. For a REXX exec using the NVASAPI with a relay-mode applica-tion, NetView Access Services must be administered to provide a virtual terminalfor the application using option 6, Assign and Application to a Group on theNetView Access Services Application Selection panel. For further information, referto NetView Access Services Version 2 Administration. A REXX exec not intendedto work with relay-mode applications can be started by NetView Access Serviceswithout having the virtual terminal function active.

REXX execs can be run compiled or uncompiled.


The execution of REXX execs in the NetView Access Services environment, usingthe NVASAPI or not, requires the definition of program source and output data setsas described in the following:

1. NetView Access Services loads all REXX execs to be started from the data setnamed in the EMSREXEC statement. The member name must be the same asthe REXX exec name, and must be defined in the NetView Access Servicesstart job as follows:

| //EMSREXEC DD DSN=ems.v2r1m1.SEMSREXX,DISP=SHR

Figure 58. Defining Load Source for REXX Execs

2. The output of SAY or TRACE instructions in REXX execs is routed to thedefault data set named EMSRPRT. One of the following statements must beadded in the NetView Access Services startup job to define EMSRPRT as thedata set.

//EMSRPRT DD SYSOUT=\

| //EMSRPRT DD DSN=ems.v2r1m1.REXXOUT,DISP=SHR

Figure 59. Defining the Data Set for Normal REXX Output

This output data set must be sequential and preallocated with the FB record formatand a record length of 80.

Defining the Maximum Number of REXX Environments RequiredThe maximum number of REXX environments that can be established simultane-ously in the same address space is defined in module IRXANCHR. The numberdepends on the requirements of the installation and must be specified accordingly.For example, if you want to be able to run 500 REXX execs simultaneously, thenyou must specify a value of 500 in the module. For further information on changingthe maximum number of environments in an address space, refer to TSO Exten-sions Version 2 Procedures Language MVS/REXX Reference.

Invoking the NVASAPI Functions or SubroutinesNVASAPI provides a single function name that is used with a set of arguments.

The NVASAPI is called by either a REXX function or a REXX subroutine. TheREXX function returns a value, which is assigned to a variable:

REXX Function

┌ ┐────────────────────55─ ─NVASAPI(─ ─function_string─ ───

6┴──┬ ┬────────────── ─)─────────────────────5%

└ ┘─, expression─

Figure 60. REXX Function Syntax

Chapter 15. Introduction 217

REXX Subroutine

┌ ┐────────────────────55─ ─call──NVASAPI─ ─function_string─ ───

6 ┴──┬ ┬────────────── ──────────────────5%

└ ┘─, expression─

Figure 61. Direct REXX Subroutine Syntax

The REXX subroutine places the return value in the special REXX variable calledRESULT.

The REXX syntax rules for functions and subroutines apply to the NVASAPI.Expressions are evaluated in order from left to right and from the argument stringsduring execution of the NVASAPI.

For a detailed description of functions provided by the NVASAPI, see Chapter 16,“NetView Access Services REXX Application Programming Interface Functions” onpage 225.

Invoking REXX ExecsREXX execs using the NVASAPI are executed within the NetView Access Servicesaddress space. Therefore, a REXX exec must be started by NetView Access Ser-vices. The REXX exec can be started implicitly by certain events or explicitly byentering a NetView Access Services command.

1. NetView Access Services can be administrated to implicitly start a REXX execwhen a user:

� Logs on to a NetView Access Services.

� Logs on to a relay-mode application from the NetView Access ServicesApplication Selection panel by entering the ID number or name of the appli-cation, or by entering the JUMP command together with the commandprefix on a panel of an application to jump to an application when nosession with that application exists.

� Logs off from a relay-mode application from the NetView Access ServicesApplication Selection panel using the LF command or by issuing the LFcommand preceded by the command prefix on a panel of a relay-modeapplication.

� Logs off from NetView Access Services from the NetView Access ServicesApplication Selection panel using the LOGOFF, DISC, or EXIT command,or by issuing the LOGOFF, DISC, or EXIT command on a panel of a relay-mode application together with the command prefix.

The names of the REXX exec to start for logon and logoff from NetViewAccess Services must be defined on the Define a Group panel. The names ofthe REXX execs to start for logon to or logoff from an application must bedefined on the Assign an Application to a Group panel. For further information,refer to NetView Access Services Version 2 Administration.

If a REXX exec exists for automatic logon to a relay-mode application, and aNetView Access Services automatic logon profile exists for the same applica-tion, the REXX exec is used and not the NetView Access Services automaticlogon profile.

Logon or logoff REXX execs are ignored for the Free Selection application.


NetView Access Services provides a means for changing the name of theREXX exec to be started in the following NetView Access Services installation-wide exits:

� “EMSELGNX, Logon Authorization Exit” on page 154� “EMSESEEX, Session Establishment Exit” on page 171.

NetView Access Services provides the name of the REXX exec specified byadministration in the field, or all bytes as blank if no REXX exec is adminis-tered. The exit program can change the provided name to cause anotherREXX exec to be started, or set it to blanks to suppress the start of the REXXexec. Refer to the exit description for details of the exit interface.

2. A user can explicitly start a REXX exec by entering the following NetViewAccess Services command on a relay-mode application panel and pressing theNetView Access Services command key. nnnnnnnn is the member name ofthe REXX exec.

55─ ──command prefixEXEC ─nnnnnnnn──────────────────────────────────────5%

Figure 62. Starting REXX Execs from a Panel of an Application

A user can also start a REXX exec by entering the following command on theNetView Access Services Application Selection panel, where nnnnnnnn is themember name of the REXX exec.

55──EXEC──nnnnnnnn────────────────────────────────────────────────────5%

Figure 63. Starting REXX Execs from the Application Selection Panel

In addition to the name of the exec, values can be entered in the three optionalfields on the NetView Access Services Application Selection panel. These8-byte values are left shifted, translated to uppercase, and can be used in theREXX exec. The values can be retrieved as 3 arguments (not 1 argument and3 tokens) for the exec with the REXX ARG instruction. An example is shown inFigure 64.

COMMAND ==> exec freddy abcde wxyz ghijk PF 1=Help 2=Lang 3=Disc 4=Keys 7=Backw 8=Forw

á ñ

Figure 64. Example of EXEC command with Optional Parameters


A sample of the optional parameters used in the REXX ARG instruction isshown in Figure 65.

ARG arg1,arg2,arg3

Figure 65. Example of REXX ARG Instruction

where:arg1 has the value ABCDEarg2 has the value WXYZarg3 has the value GHIJK.

Terminating REXX ExecsA REXX exec normally terminates when the end of the program is reached, or anEXIT command is received. Before a REXX exec terminates, it automatically dis-connects from all connected virtual terminals.

If REXX execs need to be terminated, for example, if an indefinite loop situationoccurs, the CNEXEC command can be issued by a user on the ApplicationSelection panel.

CNEXEC

55─ ─CNEXEC─ ──┬ ┬─rexx_exec_name─ ────────────────────────────────────────────5% └ ┘─'\'────────────

Figure 66. Syntax of the CNEXEC Command

rexx_exec_name is the name of the exec to be terminated. An asterisk can bespecified to terminate all REXX execs running for that user in the group in whichthe user is logged on.

All REXX execs and associated tasks started by NetView Access Services areasynchronously terminated if the TERMI operator command is issued to terminateNetView Access Services. For information on the TERMI operator command, referto NetView Access Services Version 2 Operation.


Debugging of REXX Execs for NetView Access ServicesBecause REXX execs executed under control of NetView Access Services arerunning in a non-TSO/E environment, the standard terminal output and interactivetrace facility cannot be used as easily as for a TSO/E user at a terminal.

However, the SAY and TRACE instructions of REXX can be used for debugging, ifthe programmer observes the following:

� In the NetView Access Services environment the REXX Language Processorroutes all output to the data set defined with EMSRPRT. The output of allREXX execs is stored there. Each REXX exec does an Open/Close of theEMSRPRT data set with an Enqueue/Dequeue. This means that each REXXexec must wait until the output from the previous REXX exec has been writtento the data set. This prevents the output from any REXX exec being over-written.

� SAY and TRACE instructions can be inserted at any position in the REXX execwhere it is appropriate for debugging.

� Run the REXX exec and analyze (browse) the output stored at EMSRPRT.Make your corrections and rerun the REXX exec.

� The REXX trace function '?' that stops execution after each trace event mustnot be used within REXX execs executed under NetView Access Services.

� SAY and TRACE instructions must be commented out or removed from theREXX exec when debugging is finished to avoid normal output being over-loaded with messages.

SecurityThe NVASAPI function covers two aspects to avoid security exposures:

� Authorization

The NVASAPI functions work only within the authorization of the user who hasstarted the REXX exec. There are three different authorizations defined:

– System administrator – Group administrator – User.

This means that a REXX exec started by:

– System administrators can connect to all virtual terminals belonging to:- The applications assigned to all users logged on within all groups- The physical terminals of all users who are logged on within all groups.

– Group administrators can connect to all virtual terminals belonging to:- The applications assigned to all users logged on within the assigned

group- The physical terminals of all users who are logged on within this group.

– End users can connect only to those virtual terminals belonging to:- The applications assigned to the user logged on within the group- The physical terminals of the user who is logged on within the group.


� Password protection

– User passwords are not passed to the REXX exec.

To enter a NetView Access Services user password or a NetView AccessServices administered application password into a virtual terminal, theREXX exec must use the NVASAPI function COPY_PASSWORD. Thisfunction inserts the password only into an unprotected invisible field.

– The contents of unprotected invisible fields is not passed back to the REXXexec by any NVASAPI function. Instead, a string in the given length of thefield containing step characters (X'30') is passed back to the REXX exec.

NVASAPI Return CodesThe NVASAPI provides return codes for all functions.

Check the return codes for all NVASAPI function calls as a prerequisite for contin-uing your program. Return codes provide the following types of information:

� A function was not successfully executed.

� A function has been successfully executed and the REXX exec is to continue.

� A system error has occurred. The NVASAPI makes an error log entry in theNetView Access Services SYSLOG. This information helps you or your systemprogrammer to determine the cause of the system error.

3270 Attributes and ControlsThe following tables list the 3270 Data Stream attribute and control code represen-tation as returned by the NVASAPI functions. The attribute bit positions are in IBMformat with bit 0 as the leftmost bit in the byte.

Table 29. 3270 Field Attributes Returned to the REXX Exec in NVASAPI Format

Bit Position Meaning

0-2 All = 0, field attribute byte.

3 Unprotected/Protected

0 = Unprotected data field1 = Protected data field.

4 Alphanumeric/Numeric

0 = Alphanumeric data1 = Numeric data only.

5-6 Intensity/Selector Pen Detectable

00 = Normal intensity, not selector pen detectable01 = Normal intensity, selector pen detectable10 = High intensity, selector pen detectable11 = Non-display, not selector pen detectable.

7 Modified/Unmodified

0 = Field has not been modified1 = Field has been modified.

Note: This table applies only when 'BASE' or 'EAB' option is used.


The following 3270 control codes returned are translated to an internal NetViewAccess Services code before being sent to the REXX exec.

Table 30. 3270 Extended Field and Character Attributes Returned to the REXX Exec


0-1 Extended Highlighting

00 = Normal01 = Blink10 = Reverse video11 = Underline.

2-4 Foreground color (Color remap may override this color definition.)

000 = Default001 = Blue010 = Red011 = Pink100 = Green101 = Turquoise110 = Yellow111 = White.

5-7 Character set selection

000 = Default character set001 = APL/TEXT character set010...111 = Loadable character sets.

Note: This table applies only when 'EAB' option is set.

Table 31. 3270 Control Codes Returned to the REXX Exec

ReturnedValue

3270DSValue

Abbreviation Description

X'20' X'19' EOM End of Medium (Printer order)

X'21' X'0C' FF Form Feed (Printer order)

X'22' X'0D' CR Carriage Return (Printer order)

X'23' X'15' NL New Line (Printer order)

X'24' X'1C' DUP Duplicate Control

X'25' X'1E' FM Field Mark

X'26' X'3F' SUB Substitute

X'27' X'FF' EO Eight Ones

X'30' – STEP Step character used for password protection

X'FF' X'00' Null Eight Zeros

Note: This table applies only when 'BASE' or 'EAB' option is used.


Programming NotesAll NVASAPI functions can also be used with the NetView Access Services panelvirtual terminal, with the restriction that the NetView Access Services panel virtualterminal must be displayed on the real terminal before a function is called. Use theDISPLAY_PS function to display the NetView Access Services panel virtual ter-minal on the real terminal.

If the NVASAPI is used to control automatic logon to applications, the autologonfeature of NetView Access Services must be disabled for these applications usingeither option 4, Define an Application for the System on the NetView Access Ser-vices Administration Selection panel, or the NVASAPI DISABLE_AUTOLOG func-tion. For further information, refer to NetView Access Services Version 2Administration and “DISABLE_AUTOLOG” on page 243, respectively. Otherwisethe REXX exec receives the result, PS temporary invalid, on function requests tovirtual terminals where the NetView Access Services autologon function is active. Ifthe DISABLE_AUTOLOG ON function is used, an NVASAPI DISABLE_AUTOLOGOFF call must be issued after the logon to reenable the NetView Access Servicesautomatic logon/logoff profile for future use. For example, if a NetView Access Ser-vices automatic logoff is required to log off from the application. An example ofusing the DISABLE_AUTOLOG call is described in “REXX Exec INISES” onpage 293.

It is recommended not to use REXX instructions like SAY or TRACE in a NetViewAccess Services controlled REXX exec except for debug purposes. This isbecause all REXX execs running under NetView Access Services write their ter-minal output to the output data set defined with EMSRPRT. The use of the SAYinstruction unnecessarily fills up the output data set.

Input data sent from the terminal competes with the COPY_STR_TO_PS andSENDKEY functions. If the input to the presentation space is locked either by userinput or an NVASAPI function, the subsequent data from the other source is lost.An NVASAPI function receives an appropriate return code. To reserve a virtualterminal exclusively for a REXX exec, display a different virtual terminal on the userterminal with the DISPLAY_PS function, and run the virtual terminal in the back-ground.

If the QUERY_READ_STATE function indicates that the presentation space is tem-porarily invalid, you get the presentation space valid if you issue DISPLAY_PS toanother virtual terminal (for example, NetView Access Services panel virtual ter-minal). The DISPLAY_PS function causes the presentation space to become valid,provided that the application does not use 3270 data stream functions such asDBCS or format storage that are not supported by the virtual terminal. You canimmediately redisplay the presentation space if you want to show the activity of theREXX exec.


Chapter 16. NetView Access Services REXX ApplicationProgramming Interface Functions

This chapter describes the NVASAPI functions. They are listed in alphabeticalorder.

ConventionsEach NVASAPI function description contains the following:

� Function � Prerequisite calls � Syntax � Supplied parameters � Returned values � Remarks.

FunctionFunction gives the name of the function and provides a brief explanation of thefunction. The following table lists the function groups and their functions.

Table 32. Summary of Function Groups and Functions

Group Function

Data Transfer COPY_FIELD_TO_STRCOPY_PASSWORDCOPY_PS_TO_STRCOPY_STR_TO_PSSENDKEYSEND_3270DS

Session Control CONNECTDISCONNECT

Virtual Terminal Control CONVERT_POSFIND_FIELDQUERY_CURSOR_POSQUERY_FIELD_ATTRQUERY_PS_UPDATEQUERY_READ_STATEQUERY_VT_STATUSSEARCH_FIELDSEARCH_PS

Miscellaneous DIAGNOSEDISABLE_AUTOLOGDISPLAY_PS

| DISPMSGPAUSE

| QUERY_LOGONQUERY_ORIGINQUERY_SESSIONS

| QUERY_TERMINALSQUERY_VARIABLESSET_CURSOR_POSSET_SEND_MODE


Prerequisite CallsPrerequisite Calls lists any functions that your REXX exec must call before you canuse the present function. None indicates that no prerequisite calls are required.Prerequisite calls for all NVASAPI functions are listed in Table 33.

Table 33. Summary of Prerequisite Calls for Functions

Function Prerequisite Calls

CONNECT None

CONVERT_POS CONNECT

COPY_FIELD_TO_STR CONNECT

COPY_PASSWORD CONNECT

COPY_PS_TO_STR CONNECT

COPY_STR_TO_PS CONNECT

DIAGNOSE None

DISABLE_AUTOLOG None

DISCONNECT CONNECT

DISPLAY_PS CONNECT

| DISPMSG| None

FIND_FIELD CONNECT

PAUSE Depends on function syntax

QUERY_CURSOR_POS CONNECT

QUERY_FIELD_ATTR CONNECT

| QUERY_LOGON| None

QUERY_ORIGIN None

QUERY_PS_UPDATE CONNECT

QUERY_READ_STATE CONNECT

QUERY_SESSIONS None

| QUERY_TERMINALS| None

QUERY_VARIABLES None

QUERY_VT_STATUS CONNECT

SEARCH_FIELD CONNECT

SEARCH_PS CONNECT

SENDKEY CONNECT

SEND_3270DS CONNECT

SET_CURSOR_POS CONNECT

SET_SEND_MODE CONNECT


SyntaxSyntax illustrates the format of the function call. Refer to “Invoking the NVASAPIFunctions or Subroutines” on page 217 for more information.

Supplied ParametersSupplied Parameters lists the parameters that your program must define in order tocall the NVASAPI function.

Every function call uses the name of the function as the first parameter, but thenumber of parameters that your REXX exec must define depends on the functionbeing called. Refer to each function description for the format of the suppliedparameters.

The parameters follow the conventions of the REXX programming language andinclude:

� Literal strings (delimited by quotation marks), which are constants.

� Symbols (no quotation marks), which are translated to uppercase. A symbolthat does not begin with a digit or a period can be a name of a variable and thevalue of that variable replaces the symbol during evaluation. Otherwise, asymbol is treated as a constant string, for example, a number.

� Parameters that must be specified as numerical values must be positivedecimal integer numbers, for example, 345. No negative numbers, decimalnumbers, or hexadecimal notation are allowed.

For further details about REXX data types and symbols, refer to the documentsnamed under Chapter 15, “Introduction” on page 215.

For more information about supplied parameters and returned values, refer to thedetailed description of the function.

Returned ValuesReturned Values places values, as either return code or actual data, in a singlevariable. If you are using NVASAPI as a function, these values are put in thereceiving variable. If you are using NVASAPI as a subroutine, the values areplaced in a special variable called RESULT. Refer to the description of each func-tion for the format of the returned values.

For more information about supplied parameters and returned values, refer to thedetailed description of the function.

RemarksRemarks provides any necessary technical information about the function.

Chapter 16. NetView Access Services REXX Application Programming Interface Functions 227

NVASAPI FunctionsThe following describes the various NVASAPI functions.

CONNECTThe CONNECT function connects the REXX exec to a virtual terminal. This is thesecurity entry point, because other REXX exec functions cannot be used until theCONNECT is successful. The CONNECT function returns a virtual terminal ID(vt_id) if the connect is successful. This must be used in subsequent function callsto identify the virtual terminal.

It is not possible to use the CONNECT function for the free-selection application.An attempt to connect fails.

Prerequisite CallsNone.

Syntax

CONNECT

55─ ─NVASAPI(──'CONNECT',─ ─user_id,──group_id,─ ──┬ ┬─appl_id─ ─)──────────────5% └ ┘─term_id─

Figure 67. Syntax of the CONNECT Function

Supplied Parametersuser_id

The user ID of the NetView Access Services user. The maximum length is eightcharacters.

group_idThe name of the NetView Access Services group in which the user is assigned touse applications. The maximum length is eight characters.

appl_idSpecifies the NetView Access Services name of the application in the group inwhich the user is assigned to use the application specified. The maximum lengthis eight characters.

term_idSpecifies the NetView Access Services terminal LU name. This must be speci-fied instead of the application ID if the REXX exec is to connect to the terminalvirtual terminal. The maximum length is eight characters.

Notes:

1. If due to the use of a shared ACB for sessions to a second NetView AccessServices a reference to a terminal LU is ambiguous, the first match foundresolves the CONNECT request.

2. Ensure that no duplicates exist for appl_id or term_id, because the search endsafter the first match is found.

3. A CONNECT to the Free Selection application is not possible.


Returned ValuesThe following returned values are valid:

Table 34. Returned Values for the CONNECT Function

Return Value Explanation

-1 Function request not successful. Call DIAGNOSE function.

DIAGNOSE error codes returned:

2 A parameter error occurred (for example, invalid function request specified).9 A system error occurred.

10 The resource requested does not exist.11 The resource requested is already in use. Another REXX exec is connected

to the virtual terminal.12 Insufficient authorization to complete the request. For example, a CONNECT

request to a virtual terminal not defined for the user has been issued.30 The length of specified user_id, group_id, appl_id, or term_id is incorrect.

The length must be 1 to 8 characters.40 CONNECT failed because a virtual terminal is not configured for this session.41 CONNECT failed because the application is not active.42 CONNECT failed because a pass mode session exists with the application.48 CONNECT failed because it is not possible to connect to the Free Selection

application.57 CONNECT failed because one of the specified items was not found.

vt_id The 4-byte virtual terminal ID, if the virtual terminal is successfully connected.

RemarksThe possible parameter values for the CONNECT function are according to therequirements of NetView Access Services names.

An NVASAPI REXX exec can connect to several virtual terminals concurrently. Anindividual CONNECT request must be issued for each connection to a virtual ter-minal.

If a REXX exec is connected to a virtual terminal, another REXX exec cannotsimultaneously connect to the same virtual terminal. A REXX exec must issue aDISCONNECT request before another REXX exec can connect to the virtual ter-minal.

The virtual terminals a REXX exec can connect to depend on the authorization ofthe NetView Access Services user who has started the REXX exec. The maximumnumber of connects possible in a REXX exec is approximately 20,000.

CONVERT_POSThe CONVERT_POS function converts the presentation space positional value intothe display row-column coordinates, or converts the display row-column coordinatesinto the presentation space positional value for the given vt_id.

Note: If row-column conversion is specified, column is the second parameter. Thevalid row-column values are the values you specified when you configured thissession. For example, a session with 24 rows and 80 columns contains positions 1to 1920.


Prerequisite CallsCONNECT

Syntax

CONVERT_POS

55──NVASAPI(──'CONVERT_POS',──vt_id,─ ──┬ ┬─row,column─ ─)────────────────────5% └ ┘─pos────────

Figure 68. Syntax of the CONVERT_POS Function

Supplied Parametersvt_id

The virtual terminal identifier returned by the CONNECT function.

rowThe row. A value of 1 up greater must be specified. The maximum depends onthe number of rows supported by the terminal.

columnThe column. A value of 1 or greater must be specified. The maximum dependson the number of columns supported by the terminal.

posThe position. A value of 1 or greater must be specified.

Returned ValuesThe following returned values are valid if row-column conversion is requested:

Table 35. Returned Values for the CONVERT_POS Function (Row-Column Conversion)




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).5 Presentation space temporarily invalid.7 The specified presentation space position is invalid (for example, row,

column, position, or offset are outside of presentation space).9 A system error occurred.

23 Position points to an attribute or into a protected field.31 Invalid character found in a specified parameter. The parameter can only

contain numerical characters.44 CONVERT_POS failed because the session no longer exists.49 through 52

CONVERT_POS failed because the virtual terminal ID is invalid.55 Specified row or column exceeds active screen size limits.

n The position of the specified row and column. For example:

NVASAPI('CONVERT_POS', vt_id, 2, 9) = '89'

converts row 2, column 9 to 89 in a 24x80 presentation space. Results arereturned in 4-byte character format:

│ð│ð│8│9│

└─┴─┴─┴─┘

The values are converted automatically by the NVASAPI.


The following returned values are valid if position conversion is requested:

Table 36. Return Values for the CONVERT_POS Function (Position Conversion)







contain numerical characters.44 CONVERT_POS failed because the session no longer exists.49 through 52

CONVERT_POS failed because the vt_id is invalid.55 Specified pos exceeds active screen size limits.

r c Where r is the row number and c is the column number. For example:

NVASAPI('CONVERT_POS', vt_id, 89) = '2 9'

converts position 89 to row 2, column 9 in a 24x80 presentation space. Resultsare returned as a 9-byte character string in the following format:

│ð│ð│ð│2│ │ð│ð│ð│9│

└─┴─┴─┴─┴─┴─┴─┴─┴─┘

The values are converted automatically by the NVASAPI.

RemarksTo determine how many rows and columns are in your presentation space, refer tobytes 9-10 and 11-12 in the returned string for the QUERY_VT_STATUS function.Refer to “QUERY_VT_STATUS” on page 262.

COPY_FIELD_TO_STRThe COPY_FIELD_TO_STR function transfers characters from a field located at aspecified position into a data string.


Syntax

COPY_FIELD_TO_STR

55──NVASAPI(──'COPY_FIELD_TO_STR',──vt_id─ ─── ──,pos─ ─,length────────────────5

┌ ┐─,'NO'───5─ ──┼ ┼───────── ─)──────────────────────────────────────────────────────────5% ├ ┤─,'BASE'─ └ ┘─,'EAB'──

Figure 69. Syntax of the COPY_FIELD_TO_STR Function




posIdentifies the position of the target field in the presentation space. This must bea value of 1 or greater. If '' is specified for the position, then the field at thecurrent cursor position is used.

lengthLength in bytes to be copied from the presentation space.

Note: Do not double this value if the Extended Attribute Bytes (EAB) option isused. NVASAPI does this automatically.

'NO'Only characters in the EBCDIC code range X'40' to X'FE' are copied from thepresentation space to the user string. Attribute bytes and other characters notrepresented in the code range X'40' to X'FE' are translated into blanks.

'BASE'In addition to characters in the code range X'40' to X'FE', passes back allpresentation space data that has a value not represented by a displayable char-acter, for example, field attributes and 3270 control characters. These arereturned as shown in Table 31 on page 223.

'EAB'Passes back all presentation space data in the code range X'40' to X'FE', datathat has a value not represented by a displayable character, and nondisplayablevalues. Passes the Extended Attribute Bytes of the presentation space. Youreceive two characters for every one that is displayed, first the character followedby the attribute. For further information on extended attributes, see Table 30 onpage 223.


Table 37 (Part 1 of 2). Returned Values for the COPY_FIELD_TO_STR Function


'' Null string. Function request not successful. Call DIAGNOSE function.




24 Parameter length contains an invalid value. For example, 0.31 Invalid character found in a specified parameter. The parameter can only

contain numerical characters.33 Invalid option specified.44 COPY_FIELD_TO_STR failed because the session no longer exists.49 through 52

COPY_FIELD_TO_STR failed because the vt_id is invalid.53 COPY_FIELD_TO_STR failed because input parameters are in error.55 Specified pos, row, or column exceeds active screen size limits.62 COPY_FIELD_TO_STR failed because EAB option is on and the Reply

Mode is not 3.


Table 37 (Part 2 of 2). Returned Values for the COPY_FIELD_TO_STR Function


Data The contents of the returned data string is determined by the attribute option inthe function request. An unprotected invisible field is returned as X'30'.

RemarksField position and length information can be found by using the FIND_FIELD func-tion. The COPY_FIELD_TO_STR function can be used with either protected orunprotected fields, but only in a field-formatted presentation space.

The copy starts at position pos which can be any position in the field. The positionis the offset into the presentation space. This offset is based on a layout in whichthe upper left corner (row 1, column 1) is position 1. The copied string ends whenone of the following conditions occurs:

� The end of the field is reached.� The length of the target string, specified with the length parameter, is

exceeded.

Note: If the end of the field is reached before the specified length is exceeded, theactual length of the returned string can be determined with the LENGTH function ofREXX. If the field at the end of the presentation space wraps, theCOPY_FIELD_TO_STR function continues at the start of the presentation space.

COPY_PASSWORDThe COPY_PASSWORD function copies the user password defined in &PWD tothe presentation space position pos, provided that there is an unprotected invisiblefield. The parameter posold can be used to copy the old password &OPW to anunprotected invisible field if a password change activity is to be performed.

Note: The password copied is the one for the appropriate application. If one isnot defined for the application, the NetView Access Services logon password iscopied.

To obtain information on a password change, refer to “QUERY_ORIGIN” onpage 254.


Syntax

COPY_PASSWORD

55──NVASAPI(──'COPY_PASSWORD',──vt_id─ ─── ──,pos─ ──┬ ┬───────── ─)────────────5% └ ┘─,posold─

Figure 70. Syntax of the COPY_PASSWORD Function




posIs the position where the current password is to be copied to. This must be avalue of 1 or greater. If '' is specified for the position, then the current positionof the cursor is used as the target. If only the old password is to be copied, a 0can be specified for the current password position pos.

posoldIs the position where the old password is to be copied to. This must be a valueof 1 or greater. If '' is specified for the old position, then the current position ofthe cursor is used as the target.


Table 38. Returned Values for the COPY_PASSWORD Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).3 A real terminal is not available for this virtual terminal.4 The execution of the function is inhibited because the target presentation

space is busy. For example, the virtual terminal is in a state as whenX SYSTEM is displayed in the OIA on the 3270 terminal.

5 Presentation space temporarily invalid.6 A data error occurred due to specification of an invalid parameter (for

example, a length error causing truncation).7 The specified presentation space position is invalid (for example, row,

column, position, or offset are outside of presentation space).8 Search not successful (for example, string or field not found).9 A system error occurred.

22 COPY_PASSWORD failed because a password cannot be copied into a pro-tected field.

23 Position points to an attribute or into a protected field.26 COPY_PASSWORD failed because a password cannot be copied into a

visible field.31 Invalid character found in a specified parameter. The parameter can only

contain numerical characters.35 COPY_PASSWORD failed because you tried to copy data which is longer

than the area into which it is to be copied. The data is truncated.44 COPY_PASSWORD failed because the session no longer exists.49 through 52

COPY_PASSWORD failed because the vt_id is invalid.53 COPY_PASSWORD failed because input parameters are in error.54 COPY_PASSWORD failed because a REXX exec tried to copy an old pass-

word, but the position for the old password was not specified.55 Specified pos, row, or column exceeds active screen size limits.

0 The password has been successfully copied.


RemarksNone.

COPY_PS_TO_STRThe COPY_PS_TO_STR function copies data from the currently connected presen-tation space into a data string.


Syntax

COPY_PS_TO_STR

┌ ┐─,'NO'───55──NVASAPI(──'COPY_PS_TO_STR',──vt_id─ ─── ──,pos─ ─,length─ ──┼ ┼───────── ─)──5% ├ ┤─,'BASE'─ └ ┘─,'EAB'──

Figure 71. Syntax of the COPY_PS_TO_STR Function



posIdentifies the position where the copy begins. This must be a value of 1 orgreater. If '' is specified for the position, then the current position of the cursoris used to specify where the copy begins.

lengthLength in bytes to be copied.

Note: Do not double this value if EAB option is used. NVASAPI does this auto-matically.

'NO'Only characters in the EBCDIC code range X'40' to X'FE' are copied from thepresentation space to the user string. Attribute bytes and other characters notrepresented in the code range X'40' to X'FE' are translated into blanks.

'BASE'In addition to characters in the code range X'40' to X'FE', passes back allpresentation space data that has a value not represented by a displayable char-acter, for example, field attributes and 3270 control characters. These arereturned as shown in Table 31 on page 223.

'EAB'Passes back all presentation space data in the code range X'40' to X'FE', datathat has a value not represented by a displayable character, and nondisplayablevalues. Passes the Extended Attribute Bytes of the presentation space. Youreceive two characters for every one that is displayed, first the character followedby the attribute. See Table 30 on page 223 for extended attributes.



Table 39. Returned Values for the COPY_PS_TO_STR Function


'' Null string. Function request not successful. Call DIAGNOSE function.




24 Parameter length or n contain an invalid value. For example, 0.31 Invalid character found in a specified parameter. The parameter can only

contain numerical characters.33 Invalid option specified.44 COPY_PS_TO_STR failed because the session no longer exists.49 through 52

COPY_PS_TO_STR failed because the vt_id is invalid.53 COPY_PS_TO_STR failed because input parameters are in error.55 Specified pos, row, or column exceeds active screen size limits.62 COPY_PS_TO_STR failed because EAB option is on and the Reply Mode is

not 3.

Data The contents of the returned data string is determined by the attribute optionvalue in the function request.

RemarksThe input position pos is the offset into the presentation space. This offset isbased on a layout in which the upper left corner (row 1, column 1) is position 1.The bottom right corner of the presentation space has the highest position number.

The copy function is ended when one of the following conditions occurs:

� The end of the presentation space is reached.� The length of the target string is reached (specified with the length parameter).

Note: If the end of the presentation space is reached before the specified length isexceeded, the actual length of the returned string can be determined with theLENGTH function of REXX.

To copy the entire presentation space specify position 1 as start position and alength equal or greater the total presentation space the copied string ends at theend of the presentation space.


COPY_STR_TO_PSThe COPY_STR_TO_PS function copies a string of characters (string) to the pres-entation space at the pos position of the connected virtual terminal and places thecursor after the last byte copied.


Syntax

COPY_STR_TO_PS

┌ ┐─,'NO'──55──NVASAPI(──'COPY_STR_TO_PS',──vt_id─ ─── ──,pos─ ─,data─ ──┼ ┼──────── ─)─────5% └ ┘─,'EAB'─

Figure 72. Syntax of the COPY_STR_TO_PS Function



posPosition in the presentation space where the copy begins. If '' is specified forthe position, then the current position of the cursor is used.

dataString containing the data to be copied into the presentation space. If '' is spec-ified for data, then a null string is copied to the presentation space.

Note: The combination '' '' is not supported.

'NO'Only characters in the code range X'40' to X'FE' are copied to the presentationspace.

'EAB'Allows the character attribute for each of the copied characters to be modified.This doubles the data string to be copied. Each character to be displayed mustbe followed by an attribute byte value.



Table 40. Returned Values for the COPY_STR_TO_PS Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).4 The execution of the function is inhibited because the target presentation





23 Position points to an attribute or into a protected field.25 COPY_STR_TO_PS contains an invalid parameter combination.31 Invalid character found in a specified parameter. The parameter can only

contain numerical characters.33 Invalid option specified.35 COPY_STR_TO_PS failed because you tried to copy data which is longer

than the area into which it is to be copied. The data is truncated.44 COPY_STR_TO_PS failed because the session no longer exists.49 through 52

COPY_STR_TO_PS failed because the vt_id is invalid.53 COPY_STR_TO_PS failed because input parameters are in error.55 Specified pos, row, or column exceeds active screen size limits.62 COPY_STR_TO_PS failed because EAB option is on and the Reply Mode is

not 3.

0 The COPY_STR_TO_PS function has been successful.

4 Not all requested data has been copied. Data is truncated.

8 Data truncated due to invalid data in data string.

RemarksThe COPY_STR_TO_PS function is performed only if the target position points toan unprotected field or the terminal screen is unformatted.

The input position pos is the offset into the presentation space. This offset is basedon a layout in which the upper left corner (row 1, column 1) is position 1.

NetView Access Services commands normally entered with command prefix andcommand key on the application panel cannot be entered with theCOPY_STR_TO_PS function. Such a sequence is ignored and treated as normalinput for the application.

The cursor is moved as the copy function proceeds and is positioned after the lastbyte copied to the presentation space. Positioning of the cursor is achieved by anull string '' as parameter value for string in the function call.

If data is copied into a field in the presentation space, the Modified Data Tag (MDT)bit is set in the field attribute. For all presentation space positions where a char-acter is copied, the corresponding character attribute in the EAB is reset to default(X'00').

If the EAB option is used to change the character attributes, the new attribute valuebecomes only active if the virtual terminal is in reply mode 3. Otherwise the newattribute values are ignored.


The keyboard mnemonics (see “SENDKEY” on page 266) cannot be sent with theCOPY_STR_TO_PS function.

The string to be transferred is specified with the calling data parameter. The copyends when one of the following conditions occurs:

� If a data value less than X'40' or greater than X'FE' is encountered in thestring.

� The end of the string is encountered.

� If the end of the target field is encountered in a field-formatted presentationspace.

Note: If the copy gets to the end of the presentation space, theCOPY_STR_TO_PS function continues at the start of the PS, if the input fieldwraps. The function does not continue at the end of the presentation space if thepresentation space is unformatted.

The source data (the string to be copied) can be no larger than the maximum pres-entation space.

The character attributes to be provided are defined in the following tables. The attri-bute bit positions are in IBM format with bit 0 as the leftmost bit in the byte. Thistable applies only when EAB option is set.

Table 41. 3270 Character Attributes Provided by the REXX Exec


0-1 Highlighting

00 = Normal01 = Blink10 = Reverse video11 = Underline.

2-4 Foreground Color (Color remap may override this color definition.)

000 = Default001 = Blue010 = Red011 = Pink100 = Green101 = Turquoise110 = Yellow111 = White.

5-7 Reserved (must be zero).

DIAGNOSEThe DIAGNOSE function is used to determine the cause of the unsuccessful exe-cution of a function request indicated by a return value -1 or null string ''. TheDIAGNOSE function retrieves the specific error code for the last executedNVASAPI function.



Syntax

DIAGNOSE

55─ ─NVASAPI(──'DIAGNOSE'─ ─)────────────────────────────────────────────────5%

Figure 73. Syntax of the DIAGNOSE Function

Supplied ParametersNone.

Returned ValuesThe following return values are valid:

Table 42 (Part 1 of 3). Returned Values for the DIAGNOSE Function


0 No specific error code available function has been successful.

1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.

Note: This error code is returned for every function requiring the vt_id param-eter.

2 A parameter error occurred (for example, invalid function request specified).

Note: This error code is returned for every function.

3 A real terminal is not available for this virtual terminal.

4 The execution of the function is inhibited because the target presentation spaceis busy. For example, the virtual terminal is in a state as when X SYSTEM isdisplayed in the OIA on the 3270 terminal.

5 Presentation space temporarily invalid.

6 A data error occurred due to specification of an invalid parameter (for example, alength error causing truncation).

7 The specified presentation space position is invalid (for example, row, column,position, or offset are outside of presentation space).

Note: This error code is returned for every function requiring a presentationspace position parameter.

8 Search not successful (for example, string or field not found).

9 A system error occurred.

Note: This error code is returned for every function.

10 The resource requested does not exist.

11 The resource requested is already in use (for example, another REXX exec isconnected to the virtual terminal).

12 Insufficient authorization to complete the request. For example, a CONNECTrequest to a virtual terminal not defined for the user has been issued.

13 An error occurred when sending a 3270DS during a SEND_3270DS call.

14 DISPLAY_PS failed because a shared session is active.

15 Specified terminal ID was not found by DISPLAY_PS request.

16 Function failed because the specified virtual terminal has the status INVALID.

17 Function failed because there are broadcast or interruptive messages pending forthe terminal.




18 DISPLAY_PS of an application panel failed.

19 Terminal ID must be specified because the user has more than one terminalactive.

20 DISPLAY_PS failed because the specified terminal is displaying a NetViewAccess Services panel, not an application panel.

21 The requested DISPLAY_PS is not supported.

22 COPY_PASSWORD failed because a password cannot be copied into a pro-tected field.

23 Position points to an attribute or into a protected field.

24 Parameter length or n contain an invalid value. For example, 0.

25 COPY_STR_TO_PS contains an invalid parameter combination.

26 COPY_PASSWORD failed because a password cannot be copied into a visiblefield.

27 The virtual terminal ID specified in the SEND_3270DS call is not a terminalvirtual terminal ID.

28 The terminal specified is not in the correct status. It must display an applicationpanel, not a NetView Access Services panel.

29 The SET_SEND_MODE must be set before using the SEND_3270DS function.

30 The length of specified user_id, group_id, appl_id, or term_id is incorrect. Thelength must be 1 to 8 characters.

31 Invalid character found in a specified parameter. The parameter can only containnumerical characters.

32 Length of specified string is incorrect. The maximum length is 80 characters.

33 Invalid option specified.

34 Invalid key specified in SENDKEY function.

35 COPY failed because you tried to copy data which is longer than the area intowhich it is to be copied. The data is truncated.

36 SENDKEY function cannot be performed because no session input is possible.

37 QUERY_SESSIONS failed. Invalid request.

38 DISPLAY_PS failed because the target terminal is not available at the moment.

39 DISPLAY_PS failed because a read command is pending.

40 CONNECT failed because a virtual terminal is not configured for this session.

41 CONNECT failed because the application is not active.

42 CONNECT failed because a pass mode session exists with the application.

43 DISPLAY_PS failed because the application and terminal virtual IDs are identical.

44 Function failed because the session no longer exists.

45 Specified virtual terminal ID is either not an application virtual terminal ID, thevirtual terminal has status invalid, or an interruptive action is active.

46 SENDKEY failed due to incorrect terminal status.

47 DISPLAY_PS failed because the application being displayed is not configured forvirtual terminal.

48 CONNECT failed because it is not possible to connect to the Free Selectionapplication.

| 49| VTID Connect counter is greater than current total table (out of range of running| CONNECT request).

| 50| Table entry is empty or connect counter in VTID does not match the connect| counter in the appropriate table entry.

| 51| Table number and/or table entry is invalid.




| 52| All function calls which have to specify the VTID parameter and when address of| VTCB is hex '00' and/or eyecatcher of VTCB is invalid.

53 Function failed because input parameters are in error.

54 A REXX exec tried to copy an old password, but the position for the old pass-word was not specified.

55 Specified pos, row, or column exceeds active screen size limits.

56 Unformatted screen detected while performing a FIND_FIELD orQUERY_FIELD_ATTR request.

57 CONNECT, DISABLE_AUTOLOG, QUERY_SESSIONS, or QUERY_VARIABLESfailed because one of the specified items was not found.

58 DISPLAY_PS failed because of incorrect terminal status during making an activebackground session to an active foreground session.

59 DISPLAY_PS failed because macro call EMSESDDT has returned with returncode > 0.

60 SENDKEY failed because Read Buffer data is too short.

61 SENDKEY failed because a Read Modified was processed but a Read Bufferwas expected.

62 COPY function failed because EAB option is on and the Reply Mode is not 3.

63 SENDKEY function cannot be performed because no session input is possible;read state is not 1.

| 64| Invalid color parameter. The color parameter must be one of: R, G, Y, B, W, T,| or P.

| 65| Invalid terminal name.

| 66| Invalid terminal name. The terminal name cannot contain two successive '*'.

| 67| Invalid termlist parameter. The length of this parameter must be a multiple of 8.

| 68| Invalid termlist end. The list must always be terminated with an 8-character| string.

| 69| Invalid parameter combination between first and last parameter. You can only| specify 'LIST' if you are providing a termlist in the first parameter, or you can| specify 'LOGON' only if you provide a terid as the first parameter.

RemarksThe previous function request determines which error codes are valid. Error codesgenerally returned for all function requests or function request using specific param-eters are noted in the table above. Error codes returned only for a specific functionrequest are described with the function. The error can be retrieved only once.Calling DIAGNOSE a second time results in 0 being returned.

If a reason code indicates that the presentation space is temporarily invalid,recovery may be possible with the DISPLAY_PS function to another virtual terminal(for example, NetView Access Services panel virtual terminal). The DISPLAY_PSfunction causes the presentation space to become valid. You can immediatelyredisplay the presentation space if you want to show the activity of the REXX exec.


DISABLE_AUTOLOGThe DISABLE_AUTOLOG function allows the NetView Access Services automaticlogon and logoff profiles for applications to be disabled if a REXX exec is written toautomatically log on to or log off from several applications in turn. ADISABLE_AUTOLOG statement is required in the REXX exec for each of theappropriate applications for which the NetView Access Services automatic logon orlogoff profile is to be disabled.

The DISABLE_AUTOLOG statement is not required:

� If the REXX exec has been specified for automatic logon to the applicationusing option 6, Assign an Application to a Group on the NetView Access Ser-vices Administration Selection panel.

� When automatic logon has been disabled for the application using option 4,Define an Application for the System on the Administration Selection panel.

In these cases the DISABLE_AUTOLOG function is performed implicitly.

If the DISABLE_AUTOLOG ON function is used, an NVASAPIDISABLE_AUTOLOG OFF call must be issued after the logon to reenable theNetView Access Services automatic logon/logoff profile for future use. Forexample, if a NetView Access Services automatic logoff is required to log off fromthe application.


Syntax

DISABLE_AUTOLOG

55──NVASAPI(──'DISABLE_AUTOLOG',──user_id,──group_id,──appl_id,─────────────5

5─ ──┬ ┬─ON── ─)──────────────────────────────────────────────────────────────5% └ ┘─OFF─

Figure 74. Syntax of the DISABLE_AUTOLOG Function


The NetView Access Services user ID of the user whose automatic logon orlogoff profile is to be disabled for the specified application within the specifiedgroup.

group_idThe NetView Access Services group ID of the user whose automatic logon orlogoff profile is to be disabled for the specified application in the specified group.

applid_idThe NetView Access Services application ID of the application in the specifiedgroup for which the specified user’s automatic logon or logoff profile is to be disa-bled.

ONDisables NetView Access Services autologon.


OFFEnables NetView Access Services autologon for future use. For example, if aNetView Access Services automatic logoff is required for the application.


Table 43. Returned Values for the DISABLE_AUTOLOG Function


0 The DISABLE_AUTOLOG function has been successful.



2 A parameter error occurred (for example, invalid function request specified).8 Search not successful (for example, string or field not found).

30 The length of specified user_id, group_id, or appl_id is incorrect. The lengthmust be 1 to 8 characters.

33 Invalid option specified.57 DISABLE_AUTOLOG failed because one of the specified items was not

found.

RemarksThis function is not required in the REXX exec when an application is alreadyactive and the REXX exec can be started from a panel of an application with theEXEC command preceded by the command prefix.

DISCONNECTThe DISCONNECT function disconnects your REXX exec from the currently con-nected session.


Syntax

DISCONNECT

55──NVASAPI(──'DISCONNECT',──vt_id──)──────────────────────────────────────5%

Figure 75. Syntax of the DISCONNECT Function





Table 44. Returned Values for the DISCONNECT Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).9 A system error occurred.

44 DISCONNECT failed because the session no longer exists.49 through 52

DISCONNECT failed because the vt_id is invalid.

0 The DISCONNECT function has been successful.

RemarksNone.

DISPLAY_PSThe DISPLAY_PS function displays the content of the presentation space of thespecified virtual terminal on the real terminal.


Syntax

DISPLAY_PS

55─ ─NVASAPI(──'DISPLAY_PS',─ ──┬ ┬─appl_vt_id──────────── ─)──────────────────5% ├ ┤─term_vt_id──────────── └ ┘─appl_vt_id,term_vt_id─

Figure 76. Syntax of the DISPLAY_PS Function

Supplied Parametersterm_vt_id

The virtual terminal identifier of the terminal virtual terminal.

appl_vt_idThe virtual terminal identifier of the application virtual terminal.

If a user is logged on at one terminal only, DISPLAY_PS is accepted with eitheroption appl_vt_id or term_vt_id. If a user is logged on at more than one terminal,DISPLAY_PS is accepted only if both the appl_vt_id and term_vt_id are specified.



Table 45. Returned Values for the DISPLAY_PS Function





14 DISPLAY_PS failed because a shared session is active.15 Specified terminal ID was not found by DISPLAY_PS request.16 DISPLAY_PS failed because the specified virtual terminal has the status

INVALID.17 DISPLAY_PS failed because there are broadcast or interruptive messages

pending for the terminal.18 DISPLAY_PS of an application panel failed.19 Terminal ID must be specified because the user has more than one terminal

active.20 DISPLAY_PS failed because the specified terminal is displaying a NetView

Access Services panel, not an application panel.21 The DISPLAY_PS requested is not supported.38 DISPLAY_PS failed because the target terminal is not available at the

moment.39 DISPLAY_PS failed because a read command is pending.43 DISPLAY_PS failed because the application and terminal virtual IDs are

identical.44 DISPLAY_PS failed because the session no longer exists.47 DISPLAY_PS failed because the application being displayed is not config-

ured for virtual terminal.49 through 52

DISPLAY_PS failed because the vt_id is invalid.58 DISPLAY_PS failed because of incorrect terminal status during making an

active background session to an active foreground session.59 DISPLAY_PS failed because macro call EMSESDDT has returned with

return code > 0.

0 The DISPLAY_PS function has been successful.

RemarksThe DISPLAY_PS function can be used after changing the presentation space (forexample, of a virtual terminal with the COPY_STR_TO_PS function) to display theupdated presentation space on the specified real terminal. Each time theDISPLAY_PS function is called, the presentation space of the specified virtual ter-minal is sent to the real terminal.

The DISPLAY_PS function simulates the NetView Access Services JUMPcommand if an application presentation space is to be displayed or a NetViewAccess Services ESCAPE command if the NetView Access Services panel virtualterminal becomes the active one. The current virtual terminal goes into the back-ground and the specified virtual terminal is displayed on the specified real terminal.

Note: The DISPLAY_PS function will fail if the terminal whose presentation spaceis requested is in any NetView Access Services interruptive state, for example,during selective broadcast, or shared session.

The following lists DISPLAY_PS requests that are supported. Requests other thanthose listed will be rejected. The virtual terminal presentation space is displayed if:

� An application is being displayed on the terminal.

� An application is displayed on another terminal.


� An application is active but is not displayed on the terminal (background). Thismeans make an active background session to an active foreground session.

� An application is active but is not displayed on the terminal (background). Thismeans make an active background session to an active foreground session onanother terminal.

� An application panel is active on a terminal and a request to display theNetView Access Services Application Selection panel (escape key processing)is required, then the Application Selection panel is displayed.

� An End User Services panel is being displayed.

It is not possible to display an application panel if the user has an End User Ser-vices panel on the terminal screen. To do this, the SENDKEY function must beused by sending NetView Access Services commands using theCOPY_STR_TO_PS function.

| DISPMSG| The DISPMSG function allows a message to be sent to any NetView Access Ser-| vices terminal, regardless of which screen is currently being displayed.

| Prerequisite Calls| None

| Syntax

| DISPMSG |

| 55─| ─NVASAPI(──'DISPMSG',─ ──┬ ┬─'LIST'── ──┬ ┬─termid,─── ─msgtxt, ul, ll, color, frtext,─| ─)───────────5%| └ ┘─'LOGON'─ └ ┘─termlist,─

| Figure 77. Syntax of the DISPMSG Function

| Supplied Parameters| 'LIST'('LOGON')| A non-mandatory parameter that must be 'LIST' if the last parameter is a termlist,| but otherwise can be left blank. If you want the message to be sent to all termi-| nals displaying the logon panel, then you should specify 'LOGON'. If 'LOGON' is| specified, then the generic identifier '*' must be specified as the second param-| eter.

| Termid (termlist)| The terminal ID of where to send the message or the termlist value returned by| the 'QUERY_LOGON' or 'QUERY_TERMINALS' APIs. In the case of a terminal| ID, an * is allowed as a wildcard character in the terminal name. These parame-| ters are only valid if you are a system or group administrator. The generic identi-| fier '*' must be specified if 'LOGON' is specified as the first parameter.

| msgtxt| The text of the message to be displayed.

| ul| A non-mandatory parameter representing the position of the message box on the| terminal screen. It is expressed in terms of row and column number of the upper


| lefthand corner of the box. The row and column numbers must be separated by| a blank.

| ll A non-mandatory parameter representing the width of the message box. If not| specified, a value of 40 is assumed. It must be at least 15; if a value of less than| 15 is specified, then a value of 15 will be used. If together the value of ul and ll| exceed the line length of the terminal, then ll is truncated to fit.

| color| A non-mandatory parameter representing the color of the message text. It can| take one of the values: R, G, Y, B, W, T, and P.

| frtext| A non-mandatory parameter representing the text to be written on the top edge of| the message box.

| Returned Values| The following returned values are valid:

| Table 46. Returned Values for the DISPMSG Function

| Return Value| Explanation

| -1| Function request not successful. Call the DIAGNOSE REXX API function.

| DIAGNOSE error codes returned:

| 6 Invalid presentation space.| 7 Invalid ul parameter. The row and column numbers are not separated by a| blank.| 12 There is insufficient authorization to complete the request. The user must be| a system or group administrator.| 24 Parameter ll contains an invalid value. For example, 0.| 31 Invalid character found in a specified parameter. The parameter can only| contain numerical characters.| 32 Length of specified string is incorrect. The maximum length is 80 characters.| 33 The first parameter is invalid. It must be LIST or LOGON.| 64 The color parameter is invalid. It must be set to R, G, Y, B, W, T, or P.| 65 The terminal Name is not valid.| 66 The terminal Name is not valid; it cannot contain two successive asterisks.| 67 The length of the termlist parameter must be a multiple of eight.| 68 The termlist must end with an eight-character substring.| 69 Invalid combination between the first and last parameters. You can only| specify LIST if you are providing a termlist as the second parameter, or| LOGON if you provide a terminal ID as the second parameter.

| Remarks| None.

FIND_FIELDThe FIND_FIELD function returns the position of the first character and the lengthof the target field, starting at position pos with the attribute specified by thesearch_option parameter. Unformatted screens are not searched.



Syntax

FIND_FIELD

55──NVASAPI(──'FIND_FIELD',──vt_id─ ─── ──,pos─ ─,'search_option'──)──────────5%

Figure 78. Syntax of the FIND_FIELD Function



posIdentifies the starting position where the determination of the field parametersbegins. If '' is specified for the position, then the current position of the cursor isused. This can be used instead of a TAB key.

'search_option'Valid search options are shown in Table 47.

Table 47. Valid Search_Option Values

Value Explanation

'T ' Current field (the field where the cursor is located).

'N ' Next field, either protected or unprotected.

'P ' Previous field, either protected or unprotected.

'NP' Next protected field.

'NU' Next unprotected field.

'PP' Previous protected field.

'PU' Previous unprotected field.

Note: A blank must be specified following the character for search options 'T ', 'N ', and 'P '.



Note: Results are returned as string value, position and length are separated byone blank. Use the REXX function 'c2d' to convert to a numerical value.

Table 48. Returned Values for the FIND_FIELD Function







contain numerical characters.33 Invalid option specified.44 FIND_FIELD failed because the session no longer exists.49 through 52

FIND_FIELD failed because the vt_id is invalid.55 Specified pos, row, or column exceeds active screen size limits.56 Unformatted screen detected.

p l 9-byte character format, where p is the first character position and l is the lengthof the specified field.

RemarksIf pos points to an attribute in the presentation space and the search option is setfor the current field, a value of -1 is returned and the DIAGNOSE function returnserror code 8.

PAUSEThe PAUSE function causes a timed pause of n 1/10-second intervals to occur.

If the parameter vt_id is provided, the pause is also interrupted by any update tothe specified virtual terminal. Otherwise, the pause lasts until the time is expired.

Prerequisite CallsCONNECT, if used with parameter vt_id, otherwise none.

Syntax

PAUSE

55──NVASAPI(──'PAUSE',──n─ ──┬ ┬─────────────────────── ─)────────────────────5% │ │┌ ┐─,'UPDATE'─ └ ┘ ─,vt_id─ ──┼ ┼─────────── └ ┘─,'SEND'───

Figure 79. Syntax of the PAUSE Function


Supplied Parametersn

A timed pause. A value of 1 or greater must be specified.

vt_idThe virtual terminal identifier returned by the CONNECT function.

'UPDATE'If the vt_id parameter is specified, an additional 'UPDATE' parameter can bespecified which results in ending the pause if an update to the presentationspace or permission to send data is received.

'SEND'If the vt_id parameter is specified, the additional 'SEND' parameter causes thepause to be interrupted only if the virtual terminal receives the permission to senddata to the application.


Table 49. Returned Values for the PAUSE Function





24 Parameter n contains an invalid value. For example, 0.31 Invalid character found in a specified parameter. The parameter can only

contain numerical characters.33 Invalid option specified.44 PAUSE failed because the session no longer exists.49 through 52

PAUSE failed because the vt_id is invalid.

0 The wait duration has expired.

21 Permission to send has been received.

22 The presentation space has been updated.

23 Permission to send has been received and the presentation space has beenupdated.

24 Inbound data stream has ended the pause.

25 PAUSE canceled because the session is no longer active.

RemarksTo check the latest updates, issue a QUERY_PS_UPDATE call, before issuing aPAUSE call.

Applications that require a high-resolution timer must not use the PAUSE function.The time interval created by this function is approximate.

If vt_id with option 'UPDATE' is specified, it can be used to make the applicationwait until the virtual terminal has received an update. The PAUSE terminates whenthis occurs. The application can then issue a SEARCH_PS to see if the expectedupdate occurred. If the virtual terminal is closed while a PAUSE is waiting for anupdate, it is also interrupted. In this case the return value is -1.


QUERY_CURSOR_POSThe QUERY_CURSOR_POS function returns the cursor position for the specifiedvirtual terminal.


Syntax

QUERY_CURSOR_POS

55──NVASAPI(──'QUERY_CURSOR_POS',──vt_id──)────────────────────────────────5%

Figure 80. Syntax of the QUERY_CURSOR_POS Function




Table 50. Returned Values for the QUERY_CURSOR_POS Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).5 Presentation space temporarily invalid.9 A system error occurred.

44 QUERY_CURSOR_POS failed because the session no longer exists.49 through 52

QUERY_CURSOR_POS failed because the vt_id is invalid.

n Current cursor position into presentation space.

RemarksNone.

QUERY_FIELD_ATTRThe QUERY_FIELD_ATTR function returns the hexadecimal representation of thecurrent field attribute valid for the presentation space position pos for the connectedvirtual terminal.



Syntax

QUERY_FIELD_ATTR

55──NVASAPI(──'QUERY_FIELD_ATTR',──vt_id,──pos──)──────────────────────────5%

Figure 81. Syntax of the QUERY_FIELD_ATTR Function



posCan point to any position of the field whose attribute is to be queried.


Table 51. Returned Values for the QUERY_FIELD_ATTR Function






31 Invalid character found in a specified parameter. The parameter can onlycontain numerical characters.

44 QUERY_FIELD_ATTR failed because the session no longer exists.49 through 52

QUERY_FIELD_ATTR failed because the vt_id is invalid.55 Specified pos, row, or column exceeds active screen size limits.56 Unformatted screen detected.

Data Attribute bytes: Byte one is the field attribute value and the second byte is theextended field attribute. Data is in binary format.

RemarksRefer to Table 29 and Table 30 on page 223 for descriptions of the returned attri-bute values. If the function request is issued against an unformatted screen, avalue of -1 is returned and the DIAGNOSE function returns error code 8.


| QUERY_LOGON| The QUERY_LOGON function returns a list of all terminal IDs that are currently| displaying the NetView Access Services Logon Panel. The list is a string of ter-| minal LU names concatenated one after the other. The list ends with a string of| eight periods. If there are no terminals displaying the Logon Panel, then just a| string of eight periods is returned.

| Prerequisite Calls

| Syntax

| QUERY_LOGON |

| 55─| ─NVASAPI(──'QUERY_LOGON')───────────────────────────────────────────────5%

| Figure 82. Syntax of the QUERY_LOGON Function

| Supplied Parameters| None.


| Table 52. Returned Values for the QUERY_LOGON Function




| 9 A system error occurred.| 44 No terminals displaying the NetView Access Services Logon Panel were| found.

| Remarks| None.

QUERY_ORIGINThe QUERY_ORIGIN function returns a 46-byte character string to the REXX exec,which contains information about the originator of the REXX exec. Depending onthe event which caused the start of the REXX exec, only part of the character stringis valid.


Syntax

QUERY_ORIGIN

55─ ─NVASAPI(──'QUERY_ORIGIN'─ ─)────────────────────────────────────────────5%

Figure 83. Syntax of the QUERY_ORIGIN Function


Supplied ParametersNone.


Table 53. Returned Values for the QUERY_ORIGIN Function

data Position Definition

1 X'22' = Length of virtual terminal name reply.

2 X'10' = virtual terminal name reply ID.

3-10 User ID of the originator.

11-18 NetView Access Services group ID of the originator.

19-26 Application ID. All bytes are blanks if no application is accessed at thestart event.

27-34 Terminal ID. All bytes are blanks if no real terminal is accessed at thestart event.

35 X'03' = Length of REXX exec start reason reply.

36 X'20' = REXX exec start reason reply ID.

37 REXX exec start reason code:

X'01' User command (for example, exec, or $$exec)

X'02' Logon to NetView Access Services

X'04' Logon to application

X'08' Logoff from application

X'09' Application time-out

X'16' Logoff from NetView Access Services with LOGOFF command

X'17' Exit from NetView Access Services with EXIT command

X'18' Disconnect from NetView Access Services with DISC command

X'19' Terminal time-out.

38 X'03' = Length of password changed indicator reply.

39 X'21' = Password changed indicator reply ID.


Note: The length of the replies includes ID and length byte of the field.

Table 54. Returned Values for the QUERY_ORIGIN Function Continued


40 NetView Access Services logon password changed.

N For password not changed.

Y For password changed during logon.

41 X'03' = Length of authorization indicator reply.

42 X'22' = Authorization indicator reply ID.

43 Virtual terminal access authorization of REXX exec.

U Access to virtual terminals active for this end user in this group.

G Access by a group administrator to all virtual terminals active in thisgroup.

S Access by a system administrator to all virtual terminals currentlyactive in NetView Access Services.

44 X'03' = Length of selected language indicator reply.

45 X'23' = Selected language indicator reply ID.

46 Selected language indicator:

X'1' Base language (US English)

X'2' German

X'3' KATAKANA

X'4' Kanji

X'5' French

| X'6' Not used

X'7' Not used

X'8' Not used.

Note: The language indicator number returned may not be the same asthat shown on the list of languages on the Language Selection panel. Thenumber returned here represents the number of the language whenNetView Access Services is installed.

47 X'06' = Length of RACF ACEE address reply.

48 X'24' = RACF ACEE address reply ID.

49-52 RACF ACEE address.

53 X'10' = Length of ACB name reply.

54 X'25' = ACB name reply ID

55-62 ACB name.

RemarksThe QUERY_ORIGIN function can be used to obtain the name of the originator of aREXX exec. The name or parts of it can be used as selection qualifier with theQUERY_SESSIONS function to obtain all virtual terminal names related to a useror group.

The indicator for the logon password change is set to Y if a user has changed thepassword during logon to NetView Access Services. This information can be usedto automatically change the password for the applications logged on to. For furtherinformation on how to change a password, refer to “COPY_PASSWORD” onpage 233.


QUERY_PS_UPDATEThe QUERY_PS_UPDATE function determines whether the permission to sendstate has changed or the presentation space has been updated (for the virtual ter-minal specified with vt_id) since the last QUERY_PS_UPDATE has been issued tothe same virtual terminal.


Syntax

QUERY_PS_UPDATE

55──NVASAPI(──'QUERY_PS_UPDATE',──vt_id──)─────────────────────────────────5%

Figure 84. Syntax of the QUERY_PS_UPDATE Function




Table 55. Returned Values for the QUERY_PS_UPDATE Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).

44 QUERY_PS_UPDATE failed because the session no longer exists.49 through 52

QUERY_PS_UPDATE failed because the vt_id is invalid.

0 No updates have been made since the last call.

21 Permission to send has been received.

22 The presentation space has been updated.

23 Permission to send has been received and the presentation space has beenupdated.

RemarksNone.


QUERY_READ_STATEThis function returns the 3270 read status of the connected virtual terminal. It canbe used to determine if the input to the presentation space is temporarily inhibiteddue to active host updates or input from the real terminal.


Syntax

QUERY_READ_STATE

55──NVASAPI(──'QUERY_READ_STATE',──vt_id──)────────────────────────────────5%

Figure 85. Syntax of the QUERY_READ_STATE Function




Table 56. Returned Values for the QUERY_READ_STATE Function





44 QUERY_READ_STATE failed because the session no longer exists.49 through 52

QUERY_READ_STATE failed because the vt_id is invalid.

0 Presentation space is valid and available for input.

4 Presentation space is locked for input (for example, not in send state).

RemarksThe presentation space of the virtual terminal can be temporarily invalid if a hostapplication issues 3270 functions which cannot be reflected in the virtual terminal,for example, after data stream errors or DBCS functions. In this case, the contentsof the presentation space is not identical with the real terminal screen. While thepresentation space is invalid, input is inhibited.


QUERY_SESSIONSThe QUERY_SESSIONS function returns either a 34-byte character string for eachactive session matching the selection criteria or a null string if no virtual terminalhas been found.

If an application is displayed on the terminal, the result contains both the appl_idand term_id. There can be duplicate information because the third parameter canbe appl_id or term_id. The algorithm searches firstly for all applications and thenfor all terminals.


Syntax

QUERY_SESSIONS

55─ ─NVASAPI(──'QUERY_SESSIONS'─ ──┬ ┬─,user_id─ ──┬ ┬─,group_id─ ────────────────5 └ ┘─,'\'───── └ ┘─,'\'──────

5─ ──┬ ┬─,appl_id─ ─)─────────────────────────────────────────────────────────5% ├ ┤─,term_id─ └ ┘─,'\'─────

Figure 86. Syntax of the QUERY_SESSIONS Function


The user ID of the user whose sessions are being queried.

group_idThe group ID of the group whose sessions are being queried.

appl_idThe application ID of the application session being queried.

term_idThe terminal ID of the terminal session being queried.

'*'An asterisk, which must be specified within single quotes, can be used for eachof the parameters to get a list of the currently active virtual terminals. However,the combination '*', '*', '*' is not supported.



Table 57. Returned Values for the QUERY_SESSIONS Function

'' Function request not successful. Call DIAGNOSE function.


2 A parameter error occurred (for example, invalid function request specified).8 Search not successful (for example, string or field not found).9 A system error occurred.

12 Insufficient authorization to complete the request. For example, a CONNECTrequest to a virtual terminal not defined for the user has been issued.

30 The length of specified user_id, group_id, appl_id, or term_id is incorrect. The lengthmust be 1 to 8 characters.

37 QUERY_SESSIONS failed. Invalid request.44 QUERY_SESSIONS failed because the session no longer exists.57 QUERY_SESSIONS failed because one of the specified items was not found.


1-2 Number of virtual terminal names following.

3-* Position Format definition of virtual terminal name

1 X'22' = Length of virtual terminal name reply.

2 X'10' = Virtual terminal name reply ID.

3-10 User ID.

11-18 NetView Access Services Group ID.

19-26 Application ID. This parameter may be blank if the virtualterminal is currently not connected to a real terminal or theuser is disconnected from NetView Access Services.

27-34 Terminal ID. This parameter may be blank if the virtual ter-minal is currently not connected to a real terminal or theuser is disconnected from NetView Access Services.

RemarksThe returned IDs are left justified in each eight-byte subfield and padded to theright with blanks.

The scope within which a user can query active virtual terminals depends on theuser’s authorization within NetView Access Services.

| QUERY_TERMINALS| The QUERY_TERMINALS function returns a list of all terminals connected to| NetView Access Services, regardless of which screen they are currently displaying.| The list is a string of terminal LU names concatenated one after the other. The list| ends with a string of eight periods. If there are no terminals connected to NetView| Access Services, then just a string of eight periods is returned.

| Prerequisite Calls

| Syntax

| QUERY_TERMINALS |

| 55─| ─NVASAPI(──'QUERY_TERMINALS')───────────────────────────────────────────5%

| Figure 87. Syntax of the QUERY_TERMINALS Function


| Supplied Parameters| None.


| Table 58. Returned Values for the QUERY_TERMINALS Function




| 9 A system error occurred.| 44 No active NetView Access Services sessions have been found.

| Remarks

QUERY_VARIABLESThe QUERY_VARIABLES function returns the setting of the &variables defined onthe NetView Access Services Maintain User Parameters panel. The password vari-ables are not returned.


Syntax

QUERY_VARIABLES

55─ ─NVASAPI(──'QUERY_VARIABLES',──user_id,──group_id,──appl_id──)──────────5%

Figure 88. Syntax of the QUERY_VARIABLES Function


The NetView Access Services user ID of the user whose variables are beingqueried.

group_idThe NetView Access Services group ID of the group whose variables are beingqueried.

appl_idThe NetView Access Services application ID of the application variables beingqueried.



Table 59. Returned Values for the QUERY_VARIABLES Function

'' Null. Function request not successful. Call DIAGNOSE function.


2 A parameter error occurred (for example, invalid function request specified).10 The resource requested does not exist.12 Insufficient authorization to complete the request. For example, a CONNECT

request to a virtual terminal not defined for the user has been issued.30 The length of specified user_id, group_id, appl_id, or term_id is incorrect. The length

must be 1 to 8 characters.57 QUERY_VARIABLES failed because one of the specified items was not found.

Data Byte Definition

1 X'32' = Length of user variables reply.

2 X'02' = User variables reply ID.

3-10 &UID value.

11-18 &ACCNO value.

19-26 &UVAR1 value.

27-34 &UVAR2 value.

35-42 &UVAR3 value.

43-50 &UVAR4 value.

51 X'32' = Length of group variables reply.

52 X'03' = Group variables reply ID.

53-60 &GVAR1 value.

61-68 &GVAR2 value.

69-76 &GVAR3 value.

77-84 &GVAR4 value.

85-92 &GVAR5 value.

RemarksThe scope within which a user can query active virtual terminals depends on theuser’s authorization within NetView Access Services. The same rules as describedfor the connection to a virtual terminal are applicable. Refer to “CONNECT” onpage 228.

QUERY_VT_STATUSThe QUERY_VT_STATUS function returns various status information from thevirtual terminal vt_id.


Syntax

QUERY_VT_STATUS

55──NVASAPI(──'QUERY_VT_STATUS',──vt_id──)─────────────────────────────────5%

Figure 89. Syntax of the QUERY_VT_STATUS Function





Table 60. Returned Values for the QUERY_VT_STATUS Function

'' Null. Function request not successful. Call DIAGNOSE function.



44 QUERY_VT_STATUS failed because the session no longer exists.49 through 52

QUERY_VT_STATUS failed because the vt_id is invalid.

Data Byte Definition

1 X'10' = Length of virtual terminal status reply.

2 X'01' = Virtual terminal status reply ID.

3 Current reply mode of virtual terminal.

4-8 Reserved.

9-10 Number of rows in the presentation space. This is a binary number and isnot in display format.

11-12 Number of columns in the presentation space. This is a binary numberand is not in display format.

13-16 Terminal character set and code page number, expressed as CGCSGID.

RemarksRow and column are returned according to the actual active screen size and there-fore may change for terminals supporting alternate screen size or create partitioncommands.

The CGCSGID is made up of the 2-byte character set number and the 2-byte codepage number. If the character set of the terminal has no associated CGCSGID, the4 bytes are set to zeros. For more information about CGCSGID values, refer to3174 Establishment Controller Character Set Reference.

SEARCH_FIELDThe SEARCH_FIELD function searches a field, starting at position pos for the spec-ified string. For unformatted screens, the search starts at the specified position andends at the end of the presentation space.



Syntax

SEARCH_FIELD

┌ ┐─,'NOCASE'─55──NVASAPI(──'SEARCH_FIELD',──vt_id─ ─── ──,pos─ ─,string─ ──┼ ┼─────────── ─)──5% └ ┘─,'CASE'───

Figure 90. Syntax of the SEARCH_FIELD Function



posIdentifies the position of the target field in the presentation space.If '' is specified for the position, then the field at the current cursor position isused.

stringString containing the data to be searched in the target field. The string data mustbe in the code range X'40' to X'FE'. The maximum length of the search stringis 80 characters.

'NOCASE'The search is not case sensitive, for example, 'ABC' will match 'Abc'.

'CASE'The search is performed case sensitive, thus the search string must exactlymatch the string in presentation space.


Table 61. Returned Values for the SEARCH_FIELD Function







32 Length of specified string is incorrect. The maximum length is 80 characters.33 Invalid option specified.44 SEARCH_FIELD failed because the session no longer exists.49 through 52

SEARCH_FIELD failed because the vt_id is invalid.

0 The string was not found.

Data The position of the string in the connected presentation space. 4-byte characterformat.


RemarksThe search for the designated string begins at the specified PS position and pro-ceeds toward the end of the field. If the target string is not found, the search stopsat the end of the field. To search the entire field the position pos must be set to thefirst character in the field.

If the search reaches the end of the presentation space and the field wraps, thesearch continues at the beginning of the presentation space up to the end of thefield.

SEARCH_PSThe SEARCH_PS function searches the virtual terminal buffer for the occurrence ofa specified string. The search starts at the specified position pos.


Syntax

SEARCH_PS

┌ ┐─,'NOCASE'─55──NVASAPI(──'SEARCH_PS',──vt_id─ ─── ──,pos─ ─,string─ ──┼ ┼─────────── ─)─────5% └ ┘─,'CASE'───

Figure 91. Syntax of the SEARCH_PS Function



posIdentifies the starting position in the presentation space. This must be a value of1 or greater. If '' is specified for the position, then the current position of thecursor is used as the starting position.

stringString containing the data to be searched in the presentation space. The stringdata must be in the code range X'40' to X'FE'. The maximum length of thesearch string is 80 characters. The string must not be empty.

'NOCASE'The search is not case sensitive, for example, 'ABC' will match 'Abc'.

'CASE'The search is performed case sensitive, thus the search string must exactlymatch to the string in presentation space.



Table 62. Returned Values for the SEARCH_PS Function







32 Length of specified string is incorrect. The maximum length is 80 characters.33 Invalid option specified.44 SEARCH_PS failed because the session no longer exists.49 through 52

SEARCH_PS failed because the vt_id is invalid.

0 The string was not found.

Data Position of the string in the connected presentation space.

RemarksThe SEARCH_PS function normally scans the presentation space for the firstoccurrence after position pos of the specified string.

The search for the designated string begins at the specified PS position and pro-ceeds toward the end of the presentation space.

SENDKEYThe SENDKEY function is used to send all modified data from the virtual terminalto the application, when an application panel is on the terminal screen, or toNetView Access Services when a NetView Access Services panel is on the ter-minal screen.


Syntax

SENDKEY

55──NVASAPI(──'SENDKEY',──vt_id,──'key'──)─────────────────────────────────5%

Figure 92. Syntax of the SENDKEY Function



'key'AID to be sent to the virtual terminal specified as key mnemonic as defined in thetables, for example, '%E'. This must be specified within single quotes.



Table 63. Returned Values for the SENDKEY Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).5 Presentation space temporarily invalid.6 A data error occurred due to specification of an invalid parameter (for

example, a length error causing truncation).9 A system error occurred.

34 Invalid key specified in SENDKEY function.36 The SENDKEY function cannot be performed because no session input is

possible.44 SENDKEY failed because the session no longer exists.46 SENDKEY failed due to incorrect terminal status.49 through 52

SENDKEY failed because the vt_id is invalid.60 SENDKEY failed because Read Buffer data is too short.61 SENDKEY failed because a Read Modified was processed but a Read Buffer

was expected.63 SENDKEY function cannot be performed because no session input is pos-

sible; read state is not 1.

0 The AID has been sent; status was normal.

RemarksKeystrokes cannot be sent to the virtual terminal when the input is blocked or whilea host update is active.

Data from all fields in presentation space with the MDT set are sent in a read modi-fied data stream to the application. The MDT bit in a field is set due to user input,the COPY_STR_TO_PS function, or by the application.

NetView Access Services commands normally entered with command prefix andcommand key on the panel of an application cannot be entered with the SENDKEYfunction. Such a sequence is ignored and treated as normal input for the applica-tion. In addition, NetView Access Services specific function keys, for exampleJump or Escape, are not recognized by NetView Access Services if the related keyis specified in the SENDKEY function call.

To send special function keys, a compound character coding scheme is used. Thiscoding scheme uses EBCDIC characters to indicate one keystroke and is com-prised of the % sign (default escape character) followed by the key code. A com-plete list of these key codes is shown in “Keyboard Mnemonics” on page 268.

This compound coding technique allows an EBCDIC string representation of allnecessary keystroke codes without requiring the use of complex hexadecimal keycodes.

Only the SENDKEY function can send the special function keys.


Keyboard MnemonicsKeyboard mnemonics provide EBCDIC characters that represent the special func-tion keys of the computer keyboard. A mnemonic abbreviation code makes thesespecial keys easy to remember. An alphabetic key code is used for the mostcommon keys. For example, the Clear key is C. Note that the uppercase andlowercase alphabetic characters are mnemonic abbreviations for different keys.

Here is a list of mnemonics that use uppercase alphabetic characters:

Following is a list of supported mnemonics that use lowercase numbers or letters:

Table 64. Mnemonics with Uppercase Alphabetic Characters

EBCDIC Mnemonic Meaning

%C Clear

%E Enter

Table 65. Mnemonics with Lowercase Numbers or Letters


%1 PF1/F1

%2 PF2/F2

%3 PF3/F3

%4 PF4/F4

%5 PF5/F5

%6 PF6/F6

%7 PF7/F7

%8 PF8/F8

%9 PF9/F9

%a PF10/F10

%b PF11/F11

%c PF12/F12

%d PF13

%e PF14

%f PF15

%g PF16

%h PF17

%i PF18

%j PF19

%k PF20

%l PF21

%m PF22

%n PF23

%o PF24

%p PA1

%q PA2

%r PA3


Following is a list of mnemonics that use combinations of %A and % uppercasealphabetic (A-Z) keys:

Table 66. Mnemonics with %A and % Uppercase Alphabetic Characters


%A%A Attention

SEND_3270DSThe SEND_3270DS function is used to send a 3270 data stream to a terminal.The vt_id must point to a terminal virtual terminal. This virtual terminal must cur-rently display the data of an application virtual terminal that is in a send mode OFFstate, otherwise the request is rejected.

Prerequisite CallsCONNECT and SET_SEND_MODE

Syntax

SEND_327ðDS

55──NVASAPI(──'SEND_327ðDS',──term_vt_id,──data──)─────────────────────────5%

Figure 93. Syntax of the SEND_3270DS Function

Supplied Parametersterm_vt_id

The name of the terminal virtual terminal.

dataThe 3270 data stream to be sent to the terminal.



Table 67. Returned Values for the SEND_3270DS Function





13 An error occurred when sending a 3270DS during a SEND_3270DS call.16 SEND_3270DS failed because the specified virtual terminal has the status

INVALID.17 SEND_3270DS failed because there are broadcast or interruptive messages

pending for the terminal.27 The virtual terminal ID specified in the SEND_3270DS call is not a terminal

virtual terminal ID.28 The terminal specified is not in the correct status. It must display an applica-

tion panel, not a NetView Access Services panel.29 The SET_SEND_MODE must be set before using the SEND_3270DS func-

tion.32 Length of specified string is incorrect. The maximum length is 80 characters.44 SEND_3270DS failed because the session no longer exists.49 through 52

SEND_3270DS failed because the vt_id is invalid.

0 The SEND_3270DS function has been successful.

RemarksNone.

SET_CURSOR_POSThe SET_CURSOR_POS function is used to set the position of the cursor.


Syntax

SET_CURSOR_POS

55──NVASAPI(──'SET_CURSOR_POS',──vt_id,──pos──)────────────────────────────5%

Figure 94. Syntax of the SET_CURSOR_POS Function



posThe position to which the cursor is to be set. This must be a value of 1 orgreater.



Table 68. Returned Values for the SET_CURSOR_POS Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).4 The execution of the function is inhibited because the target presentation




column, position, or offset is outside of presentation space).8 Search not successful (for example, string or field not found).9 A system error occurred.

23 Position points to an attribute or into a protected field.44 SET_CURSOR_POS failed because the session no longer exists.49 through 52

SET_CURSOR_POS failed because the vt_id is invalid.53 SET_CURSOR_POS failed because input parameters are in error.

0 The SET_CURSOR_POS function has been successful.

RemarksNone.

SET_SEND_MODEThe SET_SEND_MODE function is used to set the sending of the 3270 datastream ON or OFF. Refer to “SEND_3270DS” on page 269 for further information.Only the direction of flow from the application or REXX exec to the terminal isaffected.


Syntax

SET_SEND_MODE

┌ ┐─,ON──55──NVASAPI(──'SET_SEND_MODE',──appl_vt_id,─ ──┼ ┼────── ─)───────────────────5% └ ┘─,OFF─

Figure 95. Syntax of the SET_SEND_MODE Function

Supplied Parametersappl_vt_id

The name of the application virtual terminal.

ONSets the send mode function to ON. Data from the application is sent to theterminal.


OFFSets the send mode function to OFF. The REXX exec sends data to the ter-minal.


Table 69. Returned Values for the SET_SEND_MODE Function




1 Either the virtual terminal ID is invalid or the virtual terminal is not connected.2 A parameter error occurred (for example, invalid function request specified).

33 Invalid option specified.45 Specified virtual terminal ID is either not an application virtual terminal ID, the

virtual terminal has status invalid, or an interruptive action is active.49 through 52

SET_SEND_MODE failed because the vt_id is invalid.

0 The SET_SEND_MODE function has been successful.

RemarksNone.


Chapter 17. REXX Execs for Automatic Logon to NetViewAccess Services and Applications

The following provides a description of the sample REXX execs delivered with| NetView Access Services. The REXX execs are located in the| ems.v2r1m1.SEMSREXX data set.

Description of the REXX ExecsThe alphanumeric characters in the following descriptions correspond to thoseshown in the figures.

Master REXX Exec RXLOGRPThe name of the master exec RXLOGRP must be specified in the Logon REXXExec field on the Define a Group panel. For further information, refer to NetViewAccess Services Version 2 Administration.

The master exec RXLOGRP shown in Figure 96 is started automatically when auser logs on to NetView Access Services in the group for which the exec has beendefined. The exec must be modified to suit your own requirements. It specifiesfour applications to be simultaneously started, applida (VM OFFICE session see.A1/), applidb (VM session see .A2/), applidc (TSO session see .A3/), and applidd(CICS session see .A4/). The name of each application must be the same as thename displayed on the Application Selection panel. If no session with an applica-tion is to be started, specify '' for the applid of the appropriate application.

/\ REXX logon exec to log on to 4 host sessions. \/

/\ This exec is started at NVAS logon. The name must be \/

/\ specified on the Define a Group panel. \/

/\ Session 1 is a VM session and is assumed to be the office \/

/\ system, so it will start OfficeVision. \/

/\ Session 2 is a VM session specified in applidb \/

/\ Session 3 is a TSO session, name specified in applidc \/

/\ Session 4 is a CICS session, name specified in applidd \/

/\ Specify names of application to be started. \/

/\ If '' is specified, this application is skipped. \/

applida = 'SDFVM1'; /\ Must be the VM office system \/

applidb = 'SDFVM2'; /\ Must be a VM system \/

applidc = 'TSO'; /\ Must be a TSO system \/

applidd = ''; /\ Change to own CICS name \/

/\ trace i \/

zeit = time();

Figure 96 (Part 1 of 2). REXX Exec (RXLOGRP) to Logon to Four Host Sessions


.A1/IF applida ¬= '' THEN

DO;

call LVM applida 'i';

IF result > = -1 THEN

DO;

apl1 = result; /\ Save vt_id of application 1. \/

call ROFFICE apl1; /\ Start office system. \/

END;

END;

.A2/IF applidb ¬= '' THEN

DO;

call LVM applidb 'i';


DO;

apl2 = result; /\ Save VT ID of second application. \/

END;

END;

.A3/IF applidc ¬= '' THEN

DO;

call LTSO applidc 'i';


DO;

tsovt = result; /\ Save VT ID of TSO session. \/

END;

END;

.A4/IF applidd ¬= '' THEN

DO;

call LCICS applidd 'i';


DO;

cicsvt = result; /\ Save VT ID of CICS session. \/

END;

END;

Figure 96 (Part 2 of 2). REXX Exec (RXLOGRP) to Logon to Four Host Sessions

Figure 97 provides an overview of an automatic logon using REXX execs when auser logs on to NetView Access Services and the master REXX exec RXLOGRP isused for the logon.


Figure 97. Overview of REXX Execs Used for Automatic Logon

Chapter 17. REXX Execs for Automatic Logon to NetView Access Services and Applications 275

REXX Exec LVMThe LVM exec shown in Figure 98 is used to log on to a VM application. The execis either called from master exec RXLOGRP, or can be called by the user from theApplication Selection panel by issuing the command EXEC LVM 1 or EXEC LVM 2.

The VM application to be started must either be specified as 1 or 2 when the execis called from the command line of the Application Selection panel, or the full appli-cation name is passed by the calling exec RXLOGRP (see .B1/). An NVASAPIQUERY_ORIGIN call (see .B2/) is issued to query the originator of the exec. Thisis followed by a CONNECT call (see .B3/) to connect to the virtual terminal. Theexec now performs a call to the RXESCT exec (see .B4/) to perform escape proc-essing to the Application Selection panel (refer to “REXX Exec RXESCT” onpage 292), and then calls the INISES exec (see .B5/) to initiate a session with thespecified application (refer to “REXX Exec INISES” on page 293). If this is suc-cessful, the exec disconnects from the terminal VT and calls the RVMINI exec (see.B6/) to start the VM session from the VM Logon panel (refer to “REXX ExecRVMINI” on page 278).

/\ REXX logon exec to log on to VM host sessions. \/

/\ Parameter aplid passes the application identifier. \/

/\ If started from command line of Application Selection panel (ASP) \/

/\ then aplid must be specified as 1 or 2. 1 starts SDFVM1, 2 starts \/

/\ application SDFVM2. If started by another exec, aplid must specify\/

/\ the exact name of the VM application to be started. \/

/\ Parameter caller is a null string if this exec has been \/

/\ initiated by typing exec lvm on the command line of the NVAS \/

/\ Application Selection panel. If called from another exec, \/

/\ parameter caller is set to 'i'. \/

/\ trace i \/

ARG aplid caller

IF aplid = '' THEN /\ At least 1 parameter must be specified.\/

exit -1;

IF caller = '' THEN

caller = 'e'; /\ Called as exec from ASP command line. \/

ELSE

caller = 'i'; /\ Internally called from another exec. \/

SELECT;

.B1/ WHEN aplid = '1' THEN

applid = 'SDFVM1';

WHEN aplid = '2' THEN

applid = 'SDFVM2';

OTHERWISE /\ Called from another exec. In \/

applid = aplid; /\ this case aplid must be correct.\/

END;

.B2/call NVASAPI 'QUERY_ORIGIN'

parse var result . 3 userid 11 groupid 19 applid1 27 termid ,

35 . 37 helpreason 38 . 4ð pwdchange 41 .

Figure 98 (Part 1 of 3). REXX Exec (LVM) to Start a Logon to a VM Session


/\ First connect to the terminal VT to get access to the NVAS \/

/\ Application Selection panel (ASP). \/

userid = strip(userid);

groupid = strip(groupid);

.B3/termvt = NVASAPI('CONNECT',userid,groupid,termid);

IF termvt = -1 THEN /\ Connect to terminal VT should always \/

DO; /\ be possible, except another EXEC is \/

IF caller = 'e' THEN /\ connected to same terminal VT. \/

exit;

ELSE

RETURN -1;

END;

/\ Now call REXX exec RXESC to do an NVAS Escape key processing \/

/\ which will display the Application Selection panel on the \/

/\ real terminal device. \/

.B4/call RXESCT userid groupid termid termvt;

IF result = -1 THEN

signal finito;

/\ First send a Clear key to ASP to clear input area. \/

call NVASAPI 'SENDKEY',termvt,'%C';

IF result = -1 THEN

signal finito;

call NVASAPI 'PAUSE',1ð;

call NVASAPI 'DISPLAY_PS',termvt;

IF result = -1 THEN

signal finito;

/\ Call INISES REXX exec to initiate a session from the NVAS \/

/\ Application Selection panel. The called exec expects that the \/

/\ ASP is already displayed on the real terminal device. \/

/\ If return code is -1, then leave. In all other cases, the \/

/\ called exec will return the VT_ID of the initiated session. \/

/\ If return code is 1, this signals that this application is \/

/\ already started, and no additional action is necessary. \/

.B5/call INISES userid groupid applid termvt;

IF result = -1 THEN

signal finito;

IF result = 1 THEN /\ Session already up, return. \/

DO;

call NVASAPI 'DISCONNECT',termvt;

return;

END;

aplvt = result; /\ Save VT ID of this application. \/



/\ This is a VM session. Next exec RVMINI will start up this VM \/

/\ session. \/

.B6/call RVMINI userid groupid applid aplvt;

/\ Now disconnect from terminal VT, to allow other execs to connect.\/


IF caller = 'i' THEN

return aplvt;

ELSE

exit;

finito: /\ Terminated due to some error.\/

call NVASAPI 'DISCONNECT',termvt; /\ Disconnect from terminal VT. \/


return -1; /\ Return to main exec \/

ELSE

exit;


REXX Exec RVMINIThe RVMINI exec shown in Figure 99 is called from the LVM exec (refer to “REXXExec LVM” on page 276) and starts a logon from the VM Logon panel. The userID for VM logon is taken from the output of the NVASAPI call QUERY_VARIABLES(see .C1/). The user ID is either the user ID used to log on to NetView AccessServices, or the value of &UID entered on the Maintain User Parameters panel. Ifa value has been specified for &UID, this value is used as the user ID for the appli-cation. The user ID is copied to the VM Logon panel with the NVASAPI callCOPY_STR_TO_PS (see .C2/).

An NVASAPI call FIND_FIELD with NU (see .C3/) is now performed to tab to thenext unprotected field, which is the Password field. The NVASAPI callCOPY_PASSWORD (see .C4/) copies the password to the field. This password iseither the password used to log on to NetView Access Services, or the value of&PWD entered on the Maintain User Parameters panel. If a value has been speci-fied for &PWD, this value is used as the password for the application. The Pass-word field must be a nondisplayable field, otherwise the COPY_PASSWORDfunction call is rejected.

The exec now waits for the first panel sent by the VM application. A loop is started(see .C5/), waiting for Ready to appear on the screen. The exec checks forHOLDING or MORE... and clears the screen if this occurs.


/\ This REXX exec is used to do a logon to a VM host session. \/

/\ It assumes that the VM session is already initiated, and that \/

/\ the first panel sent by VM (Logon panel) is already \/

/\ stored in VT. The panel may or may not be displayed on the \/

/\ real terminal. \/

/\ trace result \/

ARG userid groupid applid aplvtid

/\ First get the userid for this application. If the userid is \/

/\ not the same as the userid used to log on to NVAS, the userid \/

/\ for this VM application must be defined on the Maintain User \/

/\ parameters panel in the &UID. field. \/

.C1/nvars = NVASAPI('QUERY_VARIABLES',userid,groupid,applid);

IF nvars = '' THEN

return -1; /\ Error in API request, leave. \/

parse var nvars . 3 appluid 11 . ; /\ Get application user ID. \/

IF appluid = ' ' THEN

appluid = applid; /\ Use userid from NVAS Logon panel. \/

ELSE

appluid = strip(appluid,T);

DO I = 1 to 1ð;

call NVASAPI 'SEARCH_PS',aplvtid,1,'VM/ESA ONLINE',case

IF result > 1 THEN

LEAVE;

ELSE

CALL NVASAPI 'PAUSE',2ð; /\ Wait 2 seconds. \/

END;

IF result < 1 THEN

return -1;

/\ Now copy userid value to VM Logon panel. It is assumed that \/

/\ the cursor is in the correct field. \/

.C2/Call NVASAPI 'COPY_STR_TO_PS',aplvtid,'',appluid,'NO';

IF result = -1 THEN

return -1;

/\ Now TAB to next input field, which is the Password field. \/

cpos = NVASAPI('QUERY_CURSOR_POS',aplvtid);

.C3/pwpl = NVASAPI('FIND_FIELD',aplvtid,cpos,'NU');

parse var pwpl pwcurs 5 .

/\ Now copy the user password to this cursor position. \/

.C4/call NVASAPI 'COPY_PASSWORD',aplvtid,pwcurs;

IF result = -1 THEN

return -1;

CALL NVASAPI 'SENDKEY',aplvtid,'%E'; /\ Press the Enter key. \//

Figure 99 (Part 1 of 3). REXX Exec (RVMINI) to Logon to a VM Session


/\ Now wait for VM to send the next panel and allow for input. \/

/\ Wait time is 1ð seconds, then a check is made on result to \/

/\ find out if the panel from VM has already been received. \/

/\ If not, give up here, and continue on main exec. \/

CALL NVASAPI 'PAUSE',1ðð,aplvtid,'UPDATE';

.C5/IF result = 21 | result = 22 | result = 23 THEN

DO; /\ New panel from VM has been received. \/

res = ð;

DO I = 1 to 3ð until res ¬= ð;

call NVASAPI 'PAUSE',1ð /\ Wait 1 second. \/

res = NVASAPI('SEARCH_PS',aplvtid,1,'Ready;',case);

IF res > ð THEN

return ð; /\ VM logon finished \/

res = NVASAPI('SEARCH_PS',aplvtid,1,'RECONNECTED',case);

IF res > ð THEN

DO;

res = NVASAPI('SEARCH_PS',aplvtid,18ðð,'CP READ',case);

IF res > ð THEN

DO;

call NVASAPI 'COPY_STR_TO_PS',aplvtid,'','b';

call NVASAPI 'SENDKEY',aplvtid,'%E';

call NVASAPI 'PAUSE',1ðð,aplvtid,'SEND';

IF result = 21 THEN

DO;

DO I = 1 to 1ð;

call NVASAPI 'SEARCH_PS',aplvtid,18ðð,'RUNNING',case;

IF result > 1 THEN

LEAVE;

ELSE


END;

call NVASAPI 'SENDKEY',aplvtid,'%C';


DO I = 1 to 1ð;

call NVASAPI 'SEARCH_PS',aplvtid,18ðð,'RUNNING',case;

IF result > 1 THEN

LEAVE;

ELSE


END;

END;

ELSE

return -1;

END;

ELSE

DO;



END;

return ð; /\ VM logon finished. \/

END;



res = NVASAPI('SEARCH_PS',aplvtid,18ðð,'HOLDING',case);

IF res ¬= ð THEN

DO;



res = ð;

END;

res = NVASAPI('SEARCH_PS',aplvtid,18ðð,'MORE...',case);

IF res ¬= ð THEN

DO;



res = ð;

END;

END; /\ End Do loop. \/

END;

ELSE

return -1;


REXX Exec LTSOThe LTSO exec shown in Figure 100 on page 282 is used to log on to a TSOsession. The exec is either called by master exec RXLOGRP (refer to “MasterREXX Exec RXLOGRP” on page 273), or can be called by the user by enteringEXEC LTSO on the Application Selection panel or EXEC LTSO together with thecommand prefix and the Command key on a panel of an application. In a similarway to REXX exec LVM (refer to “REXX Exec LVM” on page 276), an NVASAPIQUERY_ORIGIN call (see .D1/) is issued to query the originator of the exec. Thisis followed by a CONNECT call (see .D2/) to connect to the virtual terminal. ExecRXESCT is now called (see .D3/) to perform an escape to the Application Selectionpanel (refer to “REXX Exec RXESCT” on page 292). Exec INISES is then called(see .D4/) to initiate the session up to the point where the first TSO panel is sent(refer to “REXX Exec INISES” on page 293). Exec RTSOINI is now called (see.D5/) to perform the TSO logon (refer to “REXX Exec RTSOINI” on page 284).


/\ REXX logon exec to log on to a TSO host session. \/


/\ If not specified, the application TSO is assumed. \/


/\ initiated by typing exec lvm on the command line of the NVAS \/



/\ trace i \/

ARG aplid caller

IF aplid = '' THEN

applid = 'TSO';

ELSE

applid = aplid;

IF caller = '' THEN

caller = 'e'; /\ Externally called from ASP command line.\/

.D1/call NVASAPI 'QUERY_ORIGIN'



/\ First connect to the terminal VT to get access to the NVAS. \/




.D2/termvt = NVASAPI('CONNECT',userid,groupid,termid);




exit;

ELSE

RETURN -1;

END;

/\ Now call REXX exec RXESCT to do an NVAS Escape key processing, \/



.D3/call RXESCT userid groupid termid termvt;

IF result = -1 THEN

signal finito;



IF result = -1 THEN

signal finito;


call NVASAPI 'DISPLAY_PS',termvt;

IF result = -1 THEN

signal finito;

Figure 100 (Part 1 of 2). REXX Exec (LTSO) to Start a Logon to a TSO Session









.D4/call INISES userid groupid applid termvt;

IF result = -1 THEN

signal finito;


DO;


return;

END;


/\ It is assumed that applidc is a TSO session. Now call \/

/\ exec RTSOINI to start up this TSO session. \/

.D5/call RTSOINI userid groupid applid aplvt;

/\ Now disconnect from terminal VT, to allow other execs to connect \/


IF caller = 'i' THEN /\ If called from another exec, then \/

return aplvt; /\ return the vt_id of this application.\/

ELSE

exit;


call NVASAPI 'DISCONNECT',termvt; /\ disconnect from terminal VT \/


return -1; /\ Return to main exec. \/

ELSE

exit;

Figure 100 (Part 2 of 2). REXX Exec (LTSO) to Start a Logon to a TSO Session


REXX Exec RTSOINIThe RTSOINI exec shown in Figure 101 is called by exec LTSO to log on to aTSO session. It starts from the first panel sent, which asks for the user ID. Theuser ID is taken from the result of an NVASAPI QUERY_VARIABLES call (see.E1/). The user ID is either the user ID used to log on to NetView Access Ser-vices, or the value of &UID entered on the Maintain User Parameters panel. Theuser ID is copied with an NVASAPI COPY_STR_TO_PS call (see .E2/), and theEnter key is pressed with an NVASAPI SENDKEY call (see .E3/). The exec nowwaits until the TSO Logon panel is received. An NVASAPIQUERY_CURSOR_POSTION call (see .E4/) gets the position of the cursor andthe password is copied with an NVASAPI COPY_PASSWORD call (see .E5/). Thepassword is either the password used to log on to NetView Access Services, or thevalue of &PWD entered on the Maintain User Parameters panel. If a value hasbeen specified for &PWD, this value is used as the password for the application.An Enter key press is now simulated with an NVASAPI SENDKEY call (see .E6/)and sent to the host. A loop now starts (see .E7/) waiting for the ISPF panel to besent from the host. If * * * is found, an Enter key press is sent to the host and theloop continues.

/\ This REXX exec is used to do a logon to a TSO session. \/

/\ It assumes that the TSO session is already initiated, and that \/

/\ the first panel sent by TSO (asking for userid) is already \/

/\ stored in VT. The panel may or may not be displayed on the \/


/tso still busypid applid aplvtid



/\ for this TSO application must be defined on the Maintain User \/

/\ Parameters panel in the &UID. field. \/

.E1/nvars = NVASAPI('QUERY_VARIABLES',userid,groupid,applid);

IF nvars = '' THEN



IF appluid = ' ' THEN

appluid = applid; /\ Use userid from NVAS logon. \/

ELSE

appluid = strip(appluid,T);

/\ Now copy userid value to first TSO panel \/

.E2/Call NVASAPI 'COPY_STR_TO_PS',aplvtid,'',appluid,'NO';

IF result = -1 THEN

return -1;

Figure 101 (Part 1 of 3). REXX Exec (RTSOINI) to Logon to TSO


.E3/CALL NVASAPI 'SENDKEY',aplvtid,'%E'; /\ Press Enter key. \/

IF result = -1 THEN

DO;

call NVASAPI 'DIAGNOSE'

return -1;

END;

/\ Now wait for TSO to send the Logon panel. Maximum wait time is \/

/\ 1ð seconds. Check for VT buffer update on end of pause. \/

DO I = 1 to 5;


IF result = 22 | result = 23 THEN

LEAVE;

END;


DO;

/\ Loop until the logon panel of TSO is available. \/

found = ð;

DO i = 1 to 1ð while found = ð;

call NVASAPI 'SEARCH_PS',aplvtid,1,'TSO/E LOGON','CASE';

IF result = -1 THEN

return -1;

IF result > ð THEN /\ Logon panel has been found. \/

DO;

found = 1;

leave;

END;

call NVASAPI 'PAUSE',1ð; /\ Wait a second. \/

END;

IF found = ð THEN

return -1;

.E4/pwcurs = NVASAPI('QUERY_CURSOR_POS',aplvtid); /\ Get cursor pos \/


.E5/call NVASAPI 'COPY_PASSWORD',aplvtid,pwcurs;

.E6/CALL NVASAPI 'SENDKEY',aplvtid,'%E'; /\ Press the Enter key. \/

/\ Now wait for TSO to send the next panel. \/


/\ find out if the panel from TSO has already been received. \/




.E7/CALL NVASAPI 'PAUSE',1ðð,aplvtid,'SEND';

IF result = 21 | result = 22 | result = 23 THEN

DO; /\ New panel from TSO received. \/


res = NVASAPI('SEARCH_PS',aplvtid,1,'\\\ ');

IF res > ð THEN

DO;

reslt = res//8ð; /\ Assume an 8ð column panel. \/

IF result < 8 THEN /\ String at begin of line. \/

DO;

Call NVASAPI 'COPY_STR_TO_PS',aplvtid,res,'XX';

call NVASAPI 'SENDKEY',aplvtid,'%E';


END;

ELSE

DO; /\ Found string not at line start \/

call NVASAPI 'COPY_STR_TO_PS',aplvtid,res,'XXX';

IF result = -1 then

DO;

call NVASAPI 'DIAGNOSE';

IF result = 4 then

call NVASAPI 'PAUSE',2ð /\ TSO still busy to

update panel. \/

END;

res = ð;

END;

END;

call NVASAPI 'PAUSE',1ð

res = NVASAPI('SEARCH_PS',aplvtid,1,'ISPF/PDF',case);

END;

IF res > ð THEN

return ð; /\ ISPF panel reached, return to caller. \/

ELSE

return -1;

END;

ELSE

return -1;

END;

ELSE

return -1;



REXX Exec LCICSThe LCICS exec shown in Figure 102 is used to log on to a CICS session. Theexec is either called by master exec RXLOGRP (refer to “Master REXX ExecRXLOGRP” on page 273), or can be called by the user by entering EXEC LCICSon the Application Selection panel or EXEC LCICS together with the commandprefix and the Command key on a panel of an application. In a similar way toREXX exec LVM (refer to “REXX Exec LVM” on page 276), an NVASAPIQUERY_ORIGIN call (see .F1/) is issued to query the originator of the exec. Thisis followed by a CONNECT call (see .F2/) to connect to the virtual terminal. ExecRXESCT is now called (see .F3/) to perform an escape to the Application Selectionpanel (refer to “REXX Exec RXESCT” on page 292). Exec INISES is then called(see .F4/) to initiate the session up to the point where the first CICS panel is sent(refer to “REXX Exec INISES” on page 293). Exec RCICSINI is now called (see.F5/) to perform the CICS logon (refer to “REXX Exec RCICSINI” on page 289).

/\ REXX logon exec to log on to a CICS host session. \/


/\ If not specified, the application CICSV is assumed. \/


/\ initiated by typing exec lcics from the cmd line of the NVAS \/



/\ trace i \/

ARG aplid caller

IF aplid = '' THEN

applid = 'CICSV';

ELSE

applid = aplid;

IF caller = '' THEN

caller = 'e'; /\ Externally called from ASP command line.\/

.F1/call NVASAPI 'QUERY_ORIGIN'



Figure 102 (Part 1 of 3). REXX Exec (LCICS) to Start Logon to a CICS Session


/\ First connect to the terminal VT to get access to the NVAS \/




.F2/termvt = NVASAPI('CONNECT',userid,groupid,termid);




exit;

ELSE

RETURN -1;

END;

.F3//\ Now call REXX exec RXESCT to do an NVAS Escape key processing, \/



call RXESCT userid groupid termid termvt;

IF result = -1 THEN /\ If ESCAPE exec failed, then leave. \/

signal finito;



IF result = -1 THEN

signal finito;


call NVASAPI 'DISPLAY_PS',termvt; /\ Display the ASP. \/

IF result = -1 THEN

signal finito;








.F4/call INISES userid groupid applid termvt;

IF result = -1 THEN

signal finito;


return;


/\ It is assumed that this is a CICS session. Now call \/

/\ exec RCICSINI to start up this CICS session. \/

.F5/call RCICSINI userid groupid applid aplvt;



/\ Now disconnect from terminal VT to allow other execs to connect.\/


IF caller = 'i' THEN /\ Return vt_id of application if called \/

return aplvt; /\ from another exec. \/

ELSE

exit;


call NVASAPI 'DISCONNECT',termvt; /\ Disconnect from terminal VT. \/


return -1; /\ Return to main exec. \/

ELSE

exit;


REXX Exec RCICSINIThe RCICSINI exec shown in Figure 103 on page 290 is called by LCICS to log onto a CICS session. It starts from the first panel sent, which asks for the user ID.The user ID is taken from the result of an NVASAPI QUERY_VARIABLES call (see.G1/). The user ID is either the user ID used to log on to NetView Access Ser-vices, or the value of &UID entered on the Maintain User Parameters panel. AClear key press is simulated with an NVASAPI SENDKEY call (see .G2/). Theexec now waits until the CICS Logon panel is received. The user ID is copied withan NVASAPI COPY_STR_TO_PS call (see .G3/).

An NVASAPI call FIND_FIELD with NU (see .G4/) is now performed to tab to thenext unprotected field. The NVASAPI call COPY_PASSWORD (see .G5/) copiesthe password to the field. This password is either the password used to log on toNetView Access Services, or the value of &PWD entered on the Maintain UserParameters panel. If a value has been specified for &PWD, this value is used asthe password for the application.

Important: The password specified for &PWD must not contain blanks. ThePassword field must be a nondisplayable field, otherwise the COPY_PASSWORDfunction call is rejected.

The exec now waits for the next panel sent by CICS.


/\ This REXX exec is used to do a Log on to a CICS host session. \/

/\ It assumes that the CICS session is already initiated, and \/

/\ that the first CICS panel is available in Virtual Terminal \/

/\ buffer. The panel may or may not be displayed on the \/


/\ trace i \/

ARG userid groupid applid aplvtid



/\ for this application must be defined on the Maintain User \/

/\ Parameters panel in the &UID. field. \/

.G1/nvars = NVASAPI('QUERY_VARIABLES',userid,groupid,applid);

IF nvars = '' THEN



appluid = strip(appluid,T); /\ Remove unneeded blanks. \/

/\ Now do a Clear key operation to the first CICS panel. \/

.G2/call NVASAPI 'SENDKEY',aplvtid,'%C'; /\ Send Clear key. \/

/\ Do a QUERY_PS_UPDATE to find out if CICS already updated \/

/\ its panel in reaction to the Clear key pressed. \/

CALL NVASAPI 'QUERY_PS_UPDATE',aplvtid;


nop; /\ Panle already updated, no wait necessary. \/

/\ Wait maximum of 2ð seconds for panel update. \/

else

CALL NVASAPI 'PAUSE',2ðð,aplvtid,'UPDATE'; /\ Wait for CICS panel \/


DO; /\ Cleared panel from CICS received. \/

/\ Now issue the CESN command to get CICS Logon panel. \/

Call NVASAPI 'COPY_STR_TO_PS',aplvtid,'','CESN','NO';

/\ Press the Enter key to send above command to CICS \/

call NVASAPI 'SENDKEY',aplvtid,'%E'; /\ Press the Enter key. \/

Call NVASAPI 'PAUSE',1ðð,aplvtid,'SEND';

Figure 103 (Part 1 of 2). REXX Exec (RCICSINI) to Logon to CICS


/\ Now wait for the CICS Logon panel. \/

DO I = 1 to 1ð;

call NVASAPI 'SEARCH_PS',aplvtid,1,'CICS/VS SIGNON',case

IF result > ð THEN /\ Search was successful, Logon panel \/

LEAVE; /\ has been received \/

ELSE

CALL NVASAPI 'PAUSE',2ð; /\ Wait 2 seconds. \/

END;

IF result < 1 THEN

return -1; /\ Return to main exec and give up. \/

/\ Now copy userid to userid field. It is assumed that the CICS \/

/\ panel has set the cursor into this field. \/

.G3/call NVASAPI 'COPY_STR_TO_PS',aplvtid,'',appluid

/\ Now TAB to next input field, which is the Password field. \/

/\ A TAB is performed by starting at current cursor position, \/

/\ specified as '', and searching for 'NU' which is the next \/

/\ unprotected field. \/

.G4/ pwpl = NVASAPI('FIND_FIELD',aplvtid,'','NU');

parse var pwpl pwcurs 5 . /\ First 4 characters are cursor addr. \/


.G5/call NVASAPI 'COPY_PASSWORD',aplvtid,pwcurs;

CALL NVASAPI 'SENDKEY',aplvtid,'%E'; /\ Press the Enter key. \/

/\ Now wait for CICS to send the next panel, which should be \/

/\ the answer of the successful logon. \/



DO; /\ New panel from CICS has been received \/

res = ð;


call NVASAPI 'PAUSE',1ð /\ Wait 1 second. \/

res = NVASAPI('SEARCH_PS',aplvtid,1,'SIGN-ON IS COMPLETE',case);

IF res > ð THEN

return ð; /\ CICS logon finished successful. \/

END; /\ End Do Loop \/

END; /\ End result = 22 or 23. \/

ELSE

return -1; /\ Probably a CICS hang, return -1. \/

END;

ELSE

return -1;

Figure 103 (Part 2 of 2). REXX Exec (RCICSINI) to Logon to CICS


REXX Exec RXESCTThe RXESCT exec shown in Figure 104 is called by other execs to performNetView Access Services escape key processing. The escape function is simu-lated from the appropriate exec with an NVASAPI DISPLAY_PS call with a vt_idpointing to the terminal VT.

The RXESCT exec checks whether the NetView Access Services ApplicationSelection panel or an application panel is displayed on the real terminal. This isachieved with an NVASAPI QUERY_SESSIONS call (see .H1/) addressing the ter-minal ID. If the application ID returned as a result of the call is blank, no applica-tion is currently displayed. If no application panel is displayed, then the NetViewAccess Services Application Selection panel is already on the screen and the execreturns with return code zero. If an application panel is on the screen, anNVASAPI DISPLAY_PS call (see .H2/) with vt_id equal to terminal VT performs theescape processing to the NetView Access Services Application Selection panel. Aloop is started to wait for the panel ID of the Application Selection panel (see .H3/).If received, the exec returns return code zero.

/\ This REXX exec is used to do an NVAS Escape key processing. \/

/\ The terminal VT must be connected by caller. \/

/\ If Application Selection panel already displayed. Do nothing. \/

/\ On return, the NVAS Application Selection panel is \/

/\ displayed on the real terminal. \/

ARG userid groupid termid termvt

/\ First check if Application Selection panel is already displayed \/

/\ on the real terminal device. This can be checked with the \/

/\ QUERY_SESSIONS API function. If this function returns a \/

/\ blank application ID, then the ASP is displayed on screen and \/

/\ all applications are in background. \/

.H1/trmses = NVASAPI('QUERY_SESSIONS',userid,groupid,termid);

parse var trmses . 21 taplid 29 .

IF taplid = ' ' THEN

return ð; /\ ASP already displayed on terminal. \/

/\ Now do a DISPLAY_PS function call addressed to the terminal VT. \/

/\ This is the same as pressing the Escape key on the real terminal.\/

.H2/Call NVASAPI 'DISPLAY_PS',termvt; /\ Get ASP onto real terminal. \/

IF result = -1 THEN

DO;

call NVASAPI 'DIAGNOSE'; /\ Negative Return Code. \/

return -1; /\ Leave if display is not possible. \/

end;

Figure 104 (Part 1 of 2). REXX Exec (RXESCT) to Carry Out the NetView Access Ser-vices Escape Function


/\ Now wait for Application Selection panel to be displayed on the \/

/\ real terminal device. This is indicated by doing a \/

/\ QUERY_SESSIONS API call to the terminal VT. If a blank \/

/\ Application ID is returned as response, the ASP is currently \/

/\ displayed on the real terminal. \/

.H3/DO I = 1 to 1ð until taplid = ' ';

trmses = NVASAPI('QUERY_SESSIONS',userid,groupid,termid);

parse var trmses . 21 taplid 29 .


END;

IF taplid ¬= ' ' THEN

return -1; /\ Possible terminal hang problem. \/

ELSE

return ð;

Figure 104 (Part 2 of 2). REXX Exec (RXESCT) to Carry Out the NetView Access Ser-vices Escape Function

REXX Exec INISESThe INISES exec shown in Figure 105 on page 294 is called from other execs toinitiate a session with an application from the Application Selection panel. Thecalling exec must already be connected to the terminal ID with an NVASAPICONNECT call, and the Application Selection panel must be displayed on the realterminal. An NVASAPI SEARCH_PS call (see .I1/) is used to search the Applica-tion Selection panel to find out if the returned application name exists.

An NVASAPI QUERY_FIELD_ATR call (see .I2/) is issued to get the attributevalue of the field where the application name has been found. The field attributehas the following layout:

Using this bit layout, the exec sets not needed bit 7 to null. The exec then checksfor value X'1C' (see .I3/), which means that bits 3, 4, and 5 are set to ON indi-cating a protected, highlighted field. If found, the exec returns return code 1 indi-cating that the session is already initiated. If the field is not highlighted, anNVASAPI FIND_FIELD call (see .I4/) is used to tab to the next field, which is theStatus field. The field attribute of this field is checked to see if it is highlighted. If itis not highlighted, the application cannot be initiated and the exec terminates. If thefield is highlighted, a loop starts. An NVASAPI SEARCH_PS call is used (see.I5/) to search for the Command line on the Application Selection panel. Thename of the application is entered in the Command line with an NVASAPICOPY_STR_TO_PS call (see .I6/). An NVASAPI DISABLE_AUTOLOG ON call(see .I7/) must be used to disable a NetView Access Services automatic logonprofile if one exists for the application.

Bits 0, 1, and 2 Must be zeroBit 3 1 = Protected 0 = UnprotectedBit 4 0 = Alphanumeric 1 = NumericBits 5, and 6 00 = Normal

10 = Highlighted01 = Selector pen detected11 = Nondisplayable field

Bit 7 1 = Modified field 0 = Field not modified


An Enter key press is now simulated with NVASAPI SENDKEY call (see .I8/), andthe exec tries an NVASAPI CONNECT call to the application (see .I9/) waiting fora valid virtual terminal identifier as the result. When the first panel of the applica-tion is received, the exec returns return code zero. An NVASAPIDISABLE_AUTOLOG OFF call (see .I1ð/) is now issued to reenable the NetViewAccess Services automatic logon profile for future use. For example, if an NetViewAccess Services automatic logoff is required to log off from the application.

/\ REXX Exec called by Logon execs to init a session from the \/

/\ Application Selection Panel (ASP). It is assumed that the \/


/\ The calling exec has already done a connect to the terminal VT \/

/\ and passes the Terminal VT_ID as input parameter termid. \/

/\ On return, the VT_ID of the application is passed to the \/

/\ caller, or a -1 if an error occurred. \/

/\ The real terminal has displayed the first panel of the \/

/\ initiated session when returning to caller. \/

/\ trace i \/

ARG userid groupid applid termvt

/\ First verify input parameters. All parameters must be specified.\/

IF termvt = '' THEN

exit -1;

/\ First search on panel if the passed application exists on panel \/

/\ It is assumed that all application sessions fit on one ASP. \/

/\ If more applications are available, extend this exec and press \/

/\ the PF8 key to display the next ASP on terminal VT. \/

.I1/apos = NVASAPI('SEARCH_PS',termvt,1,applid,nocase);

IF apos = ð | apos = -1 THEN

return -1; /\ Exit if applid not found on panel. \/

/\ Now get the attribute byte of the field containing the \/

/\ application name. If this attribute has the highlight bits on, \/

/\ this indicates that this session is already started. \/

ELSE

DO;

/\ Do a QUERY_FIELD_ATTR to the value of the current field \/

/\ attribute, and the value of the Extended Field attribute. \/

.I2/CATT = NVASAPI('QUERY_FIELD_ATTR',termvt,apos);

catt = substr(catt,1,1); /\ Process Base attribute only. \/

catt = bitand(catt,'1E'x); /\ Remove not needed bits. \/

.I3/IF catt = '1C'x THEN /\ Check if highlight bits are set. \/

return 1; /\ Session already active, return. \/

Figure 105 (Part 1 of 4). REXX Exec (INISES) to Start a Session from the ApplicationSelection Panel


/\ The session is not yet started. Find the next field (which \/

/\ contains the time) to check if this field is highlighted. If \/

/\ yes, the session can be established. \/

ELSE

DO; /\ Session inactive, try to start up. \/

/\ Get field position and field length. \/

.I4/pos1 = NVASAPI('FIND_FIELD',termvt,apos,'N ');

pos1 = substr(pos1,1,4); /\ Process field position only. \/

/\ Now get the value of the field attribute. \/

natt = NVASAPI('QUERY_FIELD_ATTR',termvt,pos1);

natt = substr(natt,1,1); /\ Base attribute only. \/

natt = bitand(natt,'1E'x); /\ Remove unwanted bits. \/

IF natt ¬= '1C'x THEN /\ If not highlighted, return to caller \/

return -1;

/\ Now begin session startup. First search for the command \/

/\ input area on the Application Selection panel. This is \/

/\ normally preceded by ==> characters. \/

.I5/ ELSE

DO;

inpo = NVASAPI('SEARCH_PS',termvt,17ðð,'==>',case);

IF inpo > ð THEN

inpo = inpo + 4; /\ Field start is 4 positions behind. \/

ELSE

return -1; /\ Search for ==> failed. Probable cause \/

/\ is a modified ASP panel. \/

count = ð;

DO while count < 8;

/\ Copy name of application to be started to command area \/

/\ and then press Enter key. \/

.I6/rcd = NVASAPI('COPY_STR_TO_PS',termvt,inpo,applid);

IF RCD ¬= ð THEN

return -1;

/\ Now issue a DISABLE_AUTOLOG NVAS request. This disables \/

/\ the Netview Access autologon function. This is required \/

/\ before a session establishment is started from a REXX \/

.I7/call NVASAPI 'DISABLE_AUTOLOG',userid,groupid,applid,'ON';

IF result = -1 THEN

return -1;

.I8/call NVASAPI 'SENDKEY',termvt,'%E'; /\ Press the Enter key. \/

IF result = -1 THEN

do;

call NVASAPI 'DIAGNOSE';

return -1;

end;



/\ Now try to connect to the just started application. \/

/\ The connect will return DIAG code 41 as long as the \/

/\ application is not allocated. The following loop waits \/

/\ until this alloc is completed, and the connect works. \/

.I9/conn = ð;

DO I = 1 to 1ð while conn = ð;

applvt = NVASAPI('CONNECT',userid,groupid,applid);

IF applvt = -1 THEN

DO;

call NVASAPI 'DIAGNOSE'

IF result = 41 THEN /\ not yet allocated \/

call NVASAPI 'PAUSE',1ð; /\ Wait 1 second \/

ELSE

exit -1; /\ All other return codes terminate. \/

END;

ELSE

conn = 1; /\ Connection successful, leave loop.\/

END;

/\ Now wait for the first panel of this application to be \/

/\ displayed on real terminal. This is required for \/

/\ synchronization purposes. \/

IF conn = 1 THEN

DO;

scrnupd = ð; /\ Set panel updated flag off. \/

/\ First find out if panel already updated. \/

call NVASAPI 'QUERY_PS_UPDATE',applvt;


DO; /\ Panel update already finished. \/

scrnupd = 1; /\ Set flag. \/

END;

ELSE

DO;

/\ Wait max 2ð seconds for first application panel. \/

call NVASAPI 'PAUSE',2ðð,applvt,'UPDATE';


scrnupd = 1; /\ Set screen update flag on \/

ELSE

nop; /\ Time expired, no response from

application session. \/

END;



/\ Now issue a DISABLE_AUTOLOG NVAS request with OFF \/

/\ parameter. This enables NVAS autologon function in case \/

/\ it is needed for a recorded logoff sequence later on. \/

.I1ð/call NVASAPI 'DISABLE_AUTOLOG',userid,groupid,applid,'OFF';

IF result = -1 THEN

return -1;

IF scrnupd = ð THEN

return -1;

ELSE

return applvt; /\ Return VT_ID to caller \/

END;

ELSE

DO; /\ Session could not be connected \/

/\ Find out if message EMS1166E has been written to the \/

/\ Application Selection panel. If yes, try again to \/

/\ connect to the application. Up to 8 times. \/

call NVASAPI 'SEARCH_PS',termvt,1,'EMS1166E',case;

if result > 1 THEN

DO;

call NVASAPI 'SENDKEY',termvt,'%C'; /\ Clear the message.\/

IF result = -1 THEN

return -1;

call NVASAPI 'PAUSE',1ð; /\ Wait one second. \/

count = count + 1;

ITERATE; /\ try again \/

END;

ELSE

RETURN -1;

END;

END;

END;

END;

END;


REXX Exec ROFFICEThe ROFFICE exec shown in Figure 106 on page 298 is used to start the OFFICEapplication and automatically perform the Open the Mail function if mail is waiting.The exec can be called from another exec, or by issuing EXEC OFFICE on a panelof an application together with the command prefix and Command key.

An NVASAPI QUERY_ORIGIN call (see .J1/) is issued to query the originator ofthe exec. This is followed by a CONNECT call (see .J2/). An NVASAPISEARCH_PS call (see .J1/) is issued to check whether the VM panel on thescreen or in the background displays RUNNING. If so, an NVASAPICOPY_STR_TO_PS call (see .J3/) copies the command OFFICE to the commandinput area, and an Enter key press is simulated by an NVASAPI SENDKEY call(see .J4/). When the OFFICE application is on the screen, an NVASAPISEARCH_PS call (see .J5/) checks whether the Mail Waiting prompt is displayed.If mail is waiting, a PF2 key press is simulated by an NVASAPI SENDKEY call (see.J6/), otherwise a PF12 key press is simulated by a SENDKEY call (see .J7/) toleave OFFICE.


/\ This REXX exec is used to start VM Office (OFFICE) from the \/

/\ VM panel. If Mail is waiting, the Open the Mail function is \/

/\ automatically started as well. \/

/\ This exec is either called from another exec, in which case \/

/\ the aplvtid is passed as parameter. It can also be called \/

/\ from the VM panel by typing &&EXEC ROFFICE and pressing the \/

/\ NVAS command key. \/

ARG aplvtid

caller = int; /\ Internally called \/

IF aplvtid = '' THEN /\ Called by typing exec name. \/

.J1/DO;

CALL NVASAPI 'QUERY_ORIGIN';

parse var result . 3 userid 11 groupid 19 applid 27 termid 35 .



IF applid ¬= ' ' THEN

.J2/ DO;

aplvt = NVASAPI('CONNECT',userid,groupid,applid);

IF aplvt = -1 THEN

exit;

ELSE

DO;

caller = ext; /\ Externally called by command. \/

aplvtid = aplvt;

END;

END;

ELSE

exit;

END;

/\ First find out if input is possible on the VM panel. The \/

/\ panel can be in the background or in the foreground. \/

.J3/res = NVASAPI('SEARCH_PS',aplvtid,18ðð,'RUNNING',case);

IF res = ð | res = -1 THEN

DO; /\ Try if VM READ is on panel. \/

res = NVASAPI('SEARCH_PS',aplvtid,18ðð,'VM READ',case);

IF res = ð | res = -1 THEN

signal fini;

END;

.J4//\ Copy command office to VM command input area. \/

call NVASAPI 'COPY_STR_TO_PS',aplvtid,'','office',NO;

IF result = -1 THEN

signal fini;

.J5/CALL NVASAPI 'SENDKEY',aplvtid,'%E'; /\ Press the Enter key. \/

Figure 106 (Part 1 of 3). REXX Exec (ROFFICE) to Start a VM OFFICE Session from aVM Panel


/\ Now wait for VM to send the next panel and allow for input. \/


/\ find out if the panel from VM has already been received. \/


/\ Then check if command office is known by this VM system. If \/

/\ not, exec returns to main exec without error. \/



DO; /\ New panel from VM has been received. \/

found = ð;

DO i = 1 to 2ð while found = ð;

res = NVASAPI('SEARCH_PS',aplvtid,1,'OFFICE:','CASE');

IF res > 1 THEN

DO;

found = 1;

leave;

END;

res = NVASAPI('SEARCH_PS',aplvtid,1,'Unknown CP/CMS command','CASE');

IF res > 1 THEN

DO;

Call NVASAPI 'SENDKEY',aplvtid,'%C'; /\ Send Clear key to VM. \/

Call NVASAPI 'PAUSE',1ðð,aplvtid,'UPDATE';

found = 2;

leave;

END;

call NVASAPI 'PAUSE',3ð; /\ Wait 3 seconds. \/

res = NVASAPI('SEARCH_PS',aplvtid,1,'HOTNEWS','CASE');

IF res > 1 THEN

DO;

Call NVASAPI 'PAUSE',2ðð /\ Give 2ð seconds to read hotnews.\/

Call NVASAPI 'SENDKEY',aplvtid,'%E'; /\ Press Enter to continue.\/


IF result < 22 THEN

signal fini;

ELSE iterate;

END;

res = NVASAPI('SEARCH_PS',aplvtid,18ðð,'MORE...','CASE');

IF res > 1 THEN

DO;

Call NVASAPI 'SENDKEY',aplvtid,'%C'; /\ Press Enter to continue.\/


IF result < 22 THEN

signal fini;

ELSE iterate;

END;

END; /\ End Do loop \/

END;

IF found = ð then

signal fini;

IF found = 2 then

return ð; /\ Return if office is not installed. \/



/\ Now search for Mail Waiting message on office panel. \/

.J6/Call NVASAPI 'SEARCH_PS',aplvtid,18ðð,'Mail Waiting',case;

.J6/IF result > ð THEN

DO; /\ Mail is waiting. Press PF2 to open mail.\/

call NVASAPI 'SENDKEY',aplvtid,'%2';


call NVASAPI 'PAUSE',1ðð; /\ Look at your mail \/

END;

ELSE

.J7/DO; /\ No mail waiting. Press PF12 to leave office.\/

call NVASAPI 'SENDKEY',aplvtid,'%c';


call NVASAPI 'PAUSE',1ð; /\ Wait a second before continuing.\/

END;

Return ð;

fini: /\ Error, exit from this REXX exec.\/

IF caller = int THEN

return -1; /\ Signal error to caller. \/

ELSE

exit; /\ Return. \/



Part 5. Appendixes

The following appendixes describe how to read the syntax diagrams in the manual,provides information on the format of the NetView Access Services administrationrecords, and provides worksheets that can be used during the NetView Access Ser-vices customization procedure.



Appendix A. Reading the Syntax Diagrams

Throughout this manual, syntax is described using the following structure. Readthe diagram from left to right, top to bottom, adding elements as you go.

Each diagram begins with a double right arrow and ends with a right and left arrowpair. Lines ending with a single right arrow indicate that the syntax diagram con-tinues. Lines beginning with single right arrows are continuation lines. In thesediagrams, all spaces and other characters are significant.

Required items appear on the main path.

55──KEYWORD──required_item───────────────────────────────────────────────5%

Optional items appear below the main path.

55──KEYWORD─ ──┬ ┬─────────────── ──────────────────────────────────────────5% └ ┘ ─optional_item─

Variable values that you provide are shown in lowercase.

55──variable_value───────────────────────────────────────────────────────5%

If you can choose from two or more items, they appear vertically in a stack.

55──KEYWORD─ ──┬ ┬─required_choice1─ ───────────────────────────────────────5% ├ ┤─required_choice2─ └ ┘─required_choice3─

If choosing one of the items is optional, the entire stack appears below the mainpath.

55──KEYWORD─ ──┬ ┬────────────────── ───────────────────────────────────────5% ├ ┤─optional_choice1─ └ ┘─optional_choice2─

If one of the optional items is the default (that is, if you do not code anything, thedefault is used), it is shown above the main path.

┌ ┐─default_choice───55──KEYWORD─ ──┼ ┼────────────────── ───────────────────────────────────────5% ├ ┤─optional_choice1─ └ ┘─optional_choice2─


A repeatable operand is shown like so:

┌ ┐─,──────────────55──KEYWORD=──(─ ───

6┴─variable_value─ ─)───────────────────────────────────5%

Syntax diagrams may be broken into fragments. A fragment is indicated by verticalbars with the name of the fragment between the bars. The fragment is shown fol-lowing the main diagram, like so:

55──┤ A Fragment ├───────────────────────────────────────────────────────5%

A Fragment:├─ ── KEYWORD=value ────────────────────────────────────────────────────────┤


Appendix B. NetView Access Services Administration RecordFormats

This appendix provides information on Product-Sensitive Programming Interfaces.The appendix contains information about the NetView Access Services VSAMprofile record format.

NetView Access Services Profile ConceptThe functions that NetView Access Services offers from the user’s viewpoint aremade possible by the support of application, group, and user profiles. Applicationprofiles contain system information (for example, VTAM ACB name) that enableNetView Access Services to establish communication with the application for theuser. Group profiles contain information about applications that may be used in thegroup, about NetView Access Services PF key, command key, and command prefixsettings that are tailored for the specific needs of the group. User profiles containinformation that enables the NetView Access Services environment to be tailoredspecifically for an individual user, for example, which applications the user mayselect and the user ID and passwords required to log on to an application.

Profile TypesA User Profile (EMSSRTU) record contains information about the application char-acteristics for a user in a group. There is one record for each application that auser can use within a group. For example, if the user has access to 5 applicationsin a group, the user has 5 SRTU records for that group. For a description of thefields see “User Profile Table (EMSSRTU)” on page 309.

An Application Routing Table Group (EMSSRTG) record contains information aboutthe application characteristics within a group. There is one record for each applica-tion assigned to a group. For instance, if the group has 7 applications defined,there are 7 SRTG records for that group. For a description of the fields see “Appli-cation Routing Table for Groups (EMSSRTG)” on page 315.

A Group Profile (EMSGPRF) record contains specific attributes for each group.There is one Group Profile record for each defined group. For a description of thefields see “Group Profile Table (GPRF)” on page 318.

The Application Routing Table System (EMSSRTS) contains definitions for applica-tions that can be accessed by NetView Access Services. For a description of thefields see “Application Routing Table (EMSSRTS)” on page 321.

The Group Access List (EMSGAL) contains definitions that authorize users assystem or group administrators in NetView Access Services. For a description ofthe fields see “Group Access List Table (EMSGAL)” on page 324.


Profile Structure

┌─────────┐

┌┴────────┐│

┌┴────────┐││

┌┴────────┐│││ ┌─────────┐

│ ││├┘ │ │

│ EMSSRTS │├┘ │ EMSGAL │

│ ├┘ │ │

└────┬────┘ └─────────┘

│

├───────────────┬───── ─ ─ ─ ─ ─ ─ ─────┐

│ │ │

┌────┴────┐ ┌────┴────┐ ┌────┴────┐

│ │ │ │ │ │

│ EMSGRPF │ │ EMSGRPF │ │ EMSGRPF │

│ │ │ │ │ │

└────┬────┘ └────┬────┘ └────┬────┘

│ │ │

│ │ │

┌──6──────┐ ┌──6──────┐ ┌──6──────┐

┌┴────────┐│ ┌┴────────┐│ ┌┴────────┐│

┌┴────────┐││ ┌┴────────┐││ ┌┴────────┐││

│ │││ │ │││ │ │││

│ EMSSRTG │├┘ │ EMSSRTG │├┘ │ EMSSRTG │├┘

│ ├┘ │ ├┘ │ ├┘

└────┬────┘ └────┬────┘ └────┬────┘

│ │ │

│ . .

│ . .

│

│

├───────────────┬───── ─ ─ ─ ─ ─ ─ ─────┐

│ │ │

│ │ │

│ ┌──6──────┐ ┌──6──────┐

┌───6─────┐ ┌┴────────┐│ ┌┴────────┐│

┌┴────────┐│ ┌┴────────┐││ ┌┴────────┐││

│ ││ │ │││ │ │││

│ EMSSRTU ││ │ EMSSRTU │├┘ │ EMSSRTU │├┘

│ ├┘ │ ├┘ │ ├┘

└─────────┘ └─────────┘ └─────────┘

Figure 107. Profile Structure

Abbreviations:

EMSGAL Group Access List

EMSSRTS Server Routing Table System

EMSGPRF Group Profile

EMSSRTG Server Routing Table Group

EMSSRTU User Profile (Server Routing Table Unit).


Profile Record Field Relationship

┌─────────┬─────────┐

EMSSRTS │ VSSYSID │ ........│

└────&────┴─────────┘

│

└───────────────────┐

│

┌─────────┬─────────┐ │

EMSGRPF │ VGPGRPID│ ....... │ │

└────&────┴─────────┘ │

│ │

│ │

│ │

┌────6────┬─────────┬────6────┬─────────┐

EMSSRTG │ VGGRPID │ VGSERVER│ VGSYSID │ ....... │

└────&────┴────&────┴─────────┴─────────┘

│ │

│ │

│ │

┌────6────┬────6────┬─────────┐

EMSSRTU │ VUGRPID │ VUSERVER│ ....... │

└─────────┴─────────┴─────────┘

Figure 108. Profile Record Field Relationship

All connected fields must contain the same character value, for example, VGSYSIDin the EMSSRTG must have the same name as the related VSSYSID in theEMSSRTS.

Procedure for Updating ProfilesNormally NetView Access Services administrator functions should be used to main-tain the NetView Access Services profiles. However, during installation or for latermajor updates an installation EXEC might want to automate the profile definitionprocess. This can be done by using a CLIST or a program that creates the NetViewAccess Services profile records from already available resources that contain therequired information such as a customer employee profile.

To perform this task it is recommended that VSAM AMS REPRO function be usedto create a sequential file from the appropriate VSAM profile data set. The sequen-tial file can then easily be updated by a program, an EXEC, or an editor. With theVSAM AMS REPRO function this file can be loaded into the NetView Access Ser-vices VSAM profile data set.

The sequential files created with the VSAM AMS REPRO function are also suitablefor loading into SQL/DA or DB2 tables. The Query Management Facility (QMF*)can then be used to produce a wide variety of reports and to answer variousqueries about the content of the database.

Appendix B. NetView Access Services Administration Record Formats 307

The following steps are recommended when an installer plans to perform theNetView Access Services profile record creation by an EXEC or a program:

1. Unload the NetView Access Services VSAM data set you want to update usingEMSVUNLO.

2. Update the sequential file either by an EXEC, a user-written program, or withan editor such as XEDIT. See “Profile Update Considerations” for additionalinformation.

3. Reload the updated sequential file using EMSVLOAD.

4. To ensure that the updated records become active, restart NetView AccessServices. The restart is not required if only EMSSRTU (user profile) recordswere updated.

Profile Update ConsiderationsThe following must be considered when updating the profiles:

� Fields that contain PF or PA or Enter key values must contain the data as the3270 AID values. The following values are valid:

The ATTN key is stored in NetView Access Services with a fake AID. Thevalue is X'EE'.

For more information refer to the 3270 Information Display System 3274Control Unit Reference Summary.

� Ensure that for names that reference other profile entries the appropriate profilerecords are defined. For example:

– For each application name and group name defined in the user profileSRTU there must be a GPRF record for the group and an SRTG record forthe application name in that group.

– For each system-internal name defined in an SRTG record there must bean SRTS record (see “Profile Record Field Relationship” on page 307 foradditional information).

Key Hex Value Key Hex ValuePF1 X'F1' PF13 X'C1'PF2 X'F2' PF14 X'C2'PF3 X'F3' PF15 X'C3'PF4 X'F4' PF16 X'C4'PF5 X'F5' PF17 X'C4'PF6 X'F6' PF18 X'C6'PF7 X'F7' PF19 X'C7'PF8 X'F8' PF20 X'C8'PF9 X'F9' PF21 X'C9'PF10 X'7A' PF22 X'4A'PF11 X'7B' PF23 X'4B'PF12 X'7C' PF24 X'4C'

PA1 X'6C' PA2 X'6E'PA3 X'6B' ENTER X'7D'


� All records contain a 4-byte address field in the first 4 bytes. This is forNetView Access Services internal use only and must be zero for profile recordsloaded via the VSAM AMS REPRO function.

� The fifth and sixth bytes contain the length of the record in binary notation.These bytes must be set to the correct values in all records:

EMSSRTS = 96 bytes (X'0060')EMSSRTG = 168 bytes (X'00A8')EMSSRTU = 256 bytes (X'0100')EMSGPRF = 96 bytes (X'0060')EMSGAL = 64 bytes (X'0040').

� The password-related logon variable fields PWD, NPW, and OPW in the userprofile (EMSSRTU) must contain blank characters. Any other data cannot beprocessed by NetView Access Services because these fields contain com-plexity masked data. For a detailed field description see “User Profile Table(EMSSRTU).”

� The last record in each of the profile data sets must contain all hexadecimalX'FF'.

� The character values must be entered in uppercase letters only, except theAPPLICATION DESCRIPTION in the SRTG VGCSELP field.

� The records must be in ascending key sequence. The keys start at byte 6 inthe records. The following list gives the length of each key and the name ofthe key fields:

EMSSRTS = 8 bytes (VSSYSID)EMSSRTG = 16 bytes (VGGRPID, VGSERVER)EMSSRTU = 24 bytes (VUSUID, VUGRPID, VUSERVER)EMSGPRF = 8 bytes (VGPGRPID)EMSGAL = 16 bytes (VGALGID, VGALUID).

Content of VSAM Profile Data AreasThe following describes the contents of the VSAM profiles.

User Profile Table (EMSSRTU)The User Profile Table (EMSSRTU Table) contains the following fields.

Note: The values in parentheses refer to the field names in the EMSSRTU dataarea description in Table 70 on page 314.

User ID (VUSUID)This field contains up to 8 characters. It is the user ID with which the userlogs on to NetView Access Services.

Group ID (VUGRPID)This field contains up to 8 characters. It is the group name. Ensure that aGPRF record for this name exists.


Application (VUSERVER)This field contains up to 8 characters. It is the group-wide name for the appli-cation. An SRTG record for this name must exist with the group name asdefined in the GROUP field.

Eight periods must be entered in this field, if a free-selection application isdefined for the user.

Pseudo Terminal Name (VULUNAME)This field contains up to 8 characters. The default is blank. The administratoruses this field when an application requires a specific logical terminal name.The logical name of the terminal authorized for this application can be entered.

This name should not be the same as any name from a pool of names. Thepools are set up by the system administrator.

Logon Profile 1 Comment (VULP1D)This can be 15 characters of text for easier identification of the private logonprofile.

Logon Profile 2 Comment (VULP2D)This can be 15 characters of text for easier identification of the private logonprofile.

Application fields may contain the logon data to be passed during automatic logonor in the BIND User data.

Variables ListValues can be given to the following variables:

Note: The values in the PWD, NPW, OPW must be blank if the profilerecords are loaded into the data set without using the NetView Access Ser-vices administrator functions.

PWD (VUAPWD)An 8-character Password for this application.

Note: This field must be initialized with 8 blanks if the profile records areloaded into the data set without using the NetView Access Servicesadministrator functions.

NPW (VUANPW)An 8-character New Password for this application.


OPW (VUAOPW)An 8-character Old Password for this application.


UID (VUAUID)An 8-character user ID field for this application. It can be used in the&UID variable during automatic logon if the application user ID is differentfrom the NetView Access Services logon user ID. If the logon user IDmust be used, this field must be initialized with 8 blanks.


ACCNO (VUAACNO)An 8-character Account Number for this application. It can be used inthe &ACCNO variable during automatic logon and its content is passed tothe exit routines that provide account number information.

Group Variables GVAR1...GVAR5 (VUAVAR1...VUAVAR5)Each of these fields contains up to 8 characters. Blanks should bedefined if the fields are not used. These fields can contain data to beinserted in logon profiles for relay mode applications, or BIND user data.It can be any data that can be interpreted by the application.

User Variables UVAR1...UVAR4 (VUAVAR6...VUAVAR9)Variables to be used at logon time. Each of these fields contains up to 8characters. Blanks should be defined if the fields are not used. Thesefields can contain data to be inserted in logon profiles for relay modeapplications, or BIND user data.

Default Group (VUDGIND)This field contains Y for yes or N for no. This indicates whether this group isthe default group of the user. If this field contains Y for any application, it isautomatically Y for all applications. There can be only one default group foreach user.

Default Application (VUDSIND)Indicates if the user is logged on to this application directly after the NetViewAccess Services logon (without the Application Selection panel). Can beeither Y for yes or N for no.

Access Mode (VUACCTYP)This field contains R for relay, P for pass, or B for both. The value in this fielddepends on how the application has been defined in the EMSSRTS orEMSSRTG records related to this application.

Record Authorization (VURECAUT)This field contains Y for yes or N for no. This indicates whether or not a usercan record a logon profile for this application. This can be used only if theapplication is selected in relay mode, and if the related SRTS and SRTGrecords authorize the application for automatic logon.

Terminal Assume (VUTERMAS)This field contains Y for yes or N for no. This indicates whether a user canassume a session from one terminal to another. This is only possible if thesystem administrator has allowed the members of the group multiple terminalauthority.

Logon Profile (VULOGPRF)For NetView Access Services to use the system-wide, the group-wide, or theuser’s own logon and logoff recordings. Valid values are: S for system-wide,G for group-wide, or U for the user’s own recordings.

Active Profile (VUALPRF)This field defines which profile is the active one (1 or 2). The user can selectone of their two private logon profiles as the active one. The value can beeither 1 or 2.


Selection ID (VUSEQNO)Defines the sequence number at which position this application appears onthe Application Selection panel. This can be any number between 1 and 99(X'01' to X'63') or X'FE'. It must be zero for the free-selection application.

Jump Key (VUJKEY)This is a PF or PA key, or the ATTN key written in the format of the 3270attention identifier (AID). It can also be blank if no jump key must be defined.If a jump key is defined, it can be used by the user to jump to this applicationfrom others. This key is used only for relay mode applications.

Escape Key (VUEKEY)A PF or PA key, or the ATTN key assigned as the escape key. It can also beblank, if no escape key is to be defined. The default is PA2. Any member ofthe group can use this key to escape from a relay mode application to theApplication Selection panel. The user can redefine the escape key on theRedefine Keys panel.

Notes:

1. If the ATTN key is defined as the escape key, there are some importantpoints that you must be aware of:

a. The ATTN key can take precedence over another function key that theuser presses. This means that the function of the ATTN key is proc-essed first. For example, if the user is active with an application andpresses a PF key to save some data and then presses the ATTN keyto escape to the Application Selection panel, it can be that the data isnot saved. Therefore the user must be careful not to press the ATTNkey immediately after pressing a PF key in an application.

b. The ATTN key can be used if the user is using an application and thekeyboard is locked. This means that the user can still escape to theApplication Selection panel. However, when returning to the applica-tion the user was originally using, the keyboard is still locked if thefunction the application was executing has not yet been completed.Therefore the user should ensure that this function is completedbefore using any other application function.

2. Whether the ATTN key can be defined as the escape key depends on theavailability of the attention signal to NetView Access Services.

3. The use of the ATTN key as the escape key is not supported on theLogon panel, or any other NetView Access Services panel. If the ATTNkey is pressed, the user is not notified by an error message that this key isnot supported on the panel.

Command Key (VUCKEY)A PF key or the Enter key assigned as the command key. The default isPF10. If you use the Enter key you must type entr , as this is a 4-characterfield. Using Enter is convenient, but can slow down the response time. Thecommand key is used to issue a NetView Access Services command on apanel of an application. The command must also follow the NetView AccessServices command prefix. This field is used only for relay mode applications.The user can redefine the command key on the Redefine Keys panel.


Command Prefix (VUCOPREF)The prefix that the users of this group must enter preceding a NetView AccessServices command on an application panel. It is up to 8 alphanumeric charac-ters. The default is the local currency symbol, for example, $$. This field isused only for relay mode applications. The user can redefine the Prefix on theRedefine Keys panel.

Msg. Received Indicator (VUAMRI)This controls the way in which users receive messages from any suspendedapplication. There are three modes:

� Normal. The user is notified of a message received from a suspendedapplication by an audible alarm, and a highlighted asterisk is displayed inthe M column on the Application Selection panel next to the applicationthat sent the message.

� Interruptive with jump. When the user is active with a session, NetViewAccess Services notifies the user of a message sent from a suspendedapplication by an audible alarm. When the user presses any function keyother than the CLEAR key, the present session is interrupted and NetViewAccess Services automatically jumps to the application that sent themessage.

� Interruptive with information. If the user is active on an application panel,NetView Access Services notifies the user of a message sent from a sus-pended application by an audible alarm. When the user presses any func-tion key other than the CLEAR key, the session is interrupted and NetViewAccess Services displays the Application Selection panel with a high-lighted asterisk in the M column next to the application that sent themessage. If the user is using the Application Selection panel, NetViewAccess Services displays an updated panel with a highlighted asterisk inthe M column next to the application that sent the message.

If the user is using a user administration panel, NetView Access Servicesdisplays a Message Display panel notifying the user that suspended appli-cations have sent messages. When the user presses any function keyother than the CLEAR key, the former panel is displayed and the user candecide on the action to take to view the message. The users in Normaland External groups can redefine the mode in which messages arereceived on the Maintain User Parameters panel.

Application ID Display (VUDAIID)This field contains Y for yes or N for no. It specifies whether an application IDdisplay can be displayed on each panel of a specified application.

User Defined Printer (VUPRTNAM)This field contains up to 8 alphanumeric characters. It specifies the printerchosen by the user when printing a copy of an application panel.

Shareable (VUSHR)This field contains Y for yes or N for no. It specifies whether a user can sharea session with a specified application with another user.


Print Key (VUPRTKEY)This is a PF or PA key, assigned as the print key. It can also be blank. Allusers assigned to use applications in the group can use this key to print apanel of any relay-mode application.

Last Update (VULUPD)Contains user ID, date, and time of last update.

Table 70. VSAM Profile Data Area EMSSRTUOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 256 VSRTU Parameter List0 (0) ADDRESS 4 VUPTR Chain pointer4 (4) UNSIGNED 2 VULEN Length of record (256 bytes)6 (6) CHARACTER 8 VUSUID User ID

14 (E) CHARACTER 8 VUGRPID Group ID22 (16) CHARACTER 8 VUSERVER Application name30 (1E) CHARACTER 8 VULUNAME Specific LU name for application38 (26) CHARACTER 15 VULP1D Logon profile 1 comment53 (35) CHARACTER 15 VULP2D Logon profile 2 comment68 (44) CHARACTER 112 VUVARS Individual names list68 (44) CHARACTER 8 VUAPWD Application password (current)76 (4C) CHARACTER 8 VUANPW Application password (new)84 (54) CHARACTER 8 VUAOPW Application password (old)92 (5C) CHARACTER 8 VUAUID Application user ID

100 (64) CHARACTER 8 VUAACNO Application account number108 (6C) CHARACTER 8 VUAVAR1 Appl. &Variable1 GVAR1116 (74) CHARACTER 8 VUAVAR2 Appl. &Variable2 GVAR2124 (7C) CHARACTER 8 VUAVAR3 Appl. &Variable3 GVAR3132 (84) CHARACTER 8 VUAVAR4 Appl. &Variable4 GVAR4140 (8C) CHARACTER 8 VUAVAR5 Appl. &Variable5 GVAR5148 (94) CHARACTER 8 VUAVAR6 Appl. &Variable6 UVAR1156 (9C) CHARACTER 8 VUAVAR7 Appl. &Variable7 UVAR2164 (A4) CHARACTER 8 VUAVAR8 Appl. &Variable8 UVAR3172 (AC) CHARACTER 8 VUAVAR9 Appl. &Variable9 UVAR4180 (B4) CHARACTER 1 VUDGIND Default group: Y=Yes/N=No181 (B5) CHARACTER 1 VUDSIND Default application: Y=Yes/N=No182 (B6) CHARACTER 1 VUACCTYP Access mode: R=Relay/P=Pass/B=Both183 (B7) CHARACTER 1 VURECAUT Logon record authorization: Y=Yes/N=No184 (B8) CHARACTER 1 VUTERMAS Terminal assume: Y=Yes/N=No/C=Conditional185 (B9) CHARACTER 1 VULOGPRF Logon profile186 (BA) CHARACTER 1 VUALPRF Active logon profile187 (BB) CHARACTER 2 VUSEQ# Sequence number for Sel. Panel187 (BB) UNSIGNED 1 * Reserved (Used by EMSEPU1H)188 (BC) UNSIGNED 1 VUSEQNO Sequence number for Sel. Panel189 (BD) BITSTRING 1 VUJKEY Jump key190 (BE) BITSTRING 1 VUEKEY Escape key191 (BF) BITSTRING 1 VUCKEY Command key192 (C0) CHARACTER 8 VUCOPREF Command prefix200 (C8) CHARACTER 1 VUAMRI Msg. received indicator: I/J/N201 (C9) CHARACTER 1 VUDAIID Display application ID: Y=Yes/N=No202 (CA) CHARACTER 8 VUPRTNAM User defined printer name210 (D2) CHARACTER 1 VUSHR Shareable: Y=Yes/N=No211 (D3) BITSTRING 1 VUPRTKEY Print key212 (D4) CHARACTER 20 * Reserved232 (E8) CHARACTER 24 VULUPD Last update information:232 (E8) CHARACTER 8 VULUUID User ID240 (F0) CHARACTER 8 VULUDAT Date248 (F8) CHARACTER 8 VULUTIM Time256 (100) CHARACTER *


Application Routing Table for Groups (EMSSRTG)The Application Routing Table for Groups (EMSSRTG) contains the following fieldsfor each application within a group.

Note: The values in parentheses refer to the field names in the EMSSRTG dataarea description in Table 71 on page 318.

Group ID (VGGRPID)This field contains up to 8 characters. It is the group name for which theapplication is defined. Ensure that a GPRF record for this name exists.

Application (VGSERVER)This field contains up to 8 characters. It is the group-wide name of the appli-cation. This appears on the Application Selection panel. If this record definesa free-selectable field for the users of a group, eight periods must be enteredin this field. The eight periods appear on the user’s Application Selectionpanel as the F field.

System-Internal Name (VGSYSID)This field contains up to 8 characters. It is the system-wide name for theapplication. It must be the name that is defined for this application in theSRTS record. Leave this field blank for the free-selection entry.

Application Description (VGCSELP)This field contains up to 30 characters of text describing the application. Thisdescription appears on the Application Selection panel, next to the applicationname.

Logon Profile Type (VGLOGPRF)This field contains either G for group or S for system. This identifies whetherthe default logon profile for this application, which applies to all members ofthis group, is the group-wide logon profile or the system-wide logon profile foran application. If this field contains G, each user has the group-wide logonprofile as a default and can choose to use that or the system-wide logonprofile. If this field contains S, then when the user selects G, the system-wideprofile is used. This field is used only for relay mode applications.

Logon Authorization (VGALOG)This field contains Y for yes or N for no. This indicates whether the membersof this group can use automatic logon for this application. This depends onhow the application is defined in the SRTS record for this System-Internalname. This definition is used only for relay mode applications.

Access Mode (VGACCTYP)This field contains R for relay, P for pass, or B for both. It is the access modefor an application. The access mode determines whether the members of thegroup can use the application in relay mode, pass mode, or both. The accessmode in this field depends on how you have set up the application for thewhole NetView Access Services system.

Jump Key (VGJKEY)This is a PF or PA key, or the ATTN key written in the format of the 3270attention identifier (AID). It can also be blank if no jump key must be defined.If a jump key is defined, it can be used by members of the group to jump tothis application from others. The users can define their own jump keys tooverride this definition. This key is only used for relay mode applications.


Default Sequence Number (VGSEQNO)This field defines the sequence number at which position this applicationappears on the Application Selection panel, if the user does not change thisvalue on the administration panel Maintain User Parameters. This value canbe any number between 1 and 99 (X'01' to X'63') or X'FE'.

Data Compression (VGDACOM)This specifies whether NetView Access Services is to compress data. If Y isspecified (outbound only compression), NetView Access Services compressesthe application’s data before it is sent to the users’ terminals. If F is specified(inbound and outbound compression), NetView Access Services compressesthe data from the user’s terminal before it is sent to the application, and theapplication’s data before it is sent to the users’ terminals. Inbound and out-bound compression is only possible when Virtual Terminal Y is specified. Anadvantage of data compression is to reduce transmission charges over a com-munications network.

Msg. Received Indicator (VGAMRI)This controls the way in which users receive messages from any suspendedapplication. There are three modes:

� Normal. The user is notified of a message received from a suspendedapplication by an audible alarm, and a highlighted asterisk is displayed inthe M column on the Application Selection panel next to the applicationthat sent the message.

� Interruptive with jump. When the user is active with a session, NetViewAccess Services notifies the user of a message sent from a suspendedapplication by an audible alarm. When the user presses any function keyother than the CLEAR key, the present session is interrupted and NetViewAccess Services automatically jumps to the application that sent themessage.

� Interruptive with information. If the user is active on an application panel,NetView Access Services notifies the user of a message sent from a sus-pended application by an audible alarm.

When the user presses any function key other than the CLEAR key, thesession is interrupted and NetView Access Services displays the Applica-tion Selection panel with a highlighted asterisk in the M column next to theapplication that sent the message.

If the user is using the Application Selection panel, NetView Access Ser-vices displays an updated panel with a highlighted asterisk in the Mcolumn next to the application that sent the message.

If the user is using a user administration panel, NetView Access Servicesdisplays a Message Display panel notifying the user that suspended appli-cations have sent messages. When the user presses any function keyother than the CLEAR key, the former panel is displayed and the user candecide on the action to take to view the message.

The users in Normal and External groups can redefine the mode in whichmessages are received on the Maintain User Parameters panel.

Shareable (VGSHR)This field contains Y for yes or N for no. It specifies whether a user can sharea session with a specified application with another user.


Virtual Terminal (VGVIT)This field contains Y for yes or N for no. It specifies whether a virtual terminalis to be used for the specified application. Virtual Terminal Y is a prerequisitefor inbound and outbound compression.

Logon REXX Exec Name (VGREXXLN)This field contains up to 8 alphanumeric characters. It specifies the name ofthe REXX exec to be started for automatic logon to the specified applicationwhen selected in relay mode. The REXX exec is not started when the appli-cation is selected in pass mode and the value in this field is ignored.

Logoff REXX Exec Name (VGREXXLF)This field contains up to 8 alphanumeric characters. It specifies the name ofthe REXX exec to be started for logoff from the specified application, andwhen the time-out value for the application session is reached. The REXXexec is only started if the application was selected in relay mode. If the appli-cation was selected in pass mode, the value in this field is ignored.

| Application Logmode| This field contains up to 8 alphanumeric characters. Specify the name of the| logmode to be used when establishing a session.

Last Update (VGLUPD)Contains user ID, date, and time of last update.

Display ID (VGDAIID)This field contains Y for yes or N for no. It specifies that an application identi-fier is to be displayed on each panel of a specified application.

Row (VGDAIRO)This field contains a value from minus 43 to 43 with the exception of zero. Itspecifies the row in which the application identifier is to be displayed on eachpanel of an application.

Column (VGDAICO)This field contains a value from minus 132 to 132 with the exception of zero.It specifies the column in which the application identifier is to be displayed oneach panel of an application.

Text (VGDAITX)This field contains up to 30 alphanumeric characters. It specifies the text ofthe application identifier that is to be displayed on each panel of an applica-tion. If the field is left blank, the description on the Application Selection panelis used.

Highlighting (VGDAIHI)This field contains H (highlight), R (reverse video), B (blinking), or U (under-line). It specifies the type of highlighting in which the application identifier is tobe displayed on each panel of an application.

Color (VGDAICL)This field contains R (red), G (green), B (blue), W (white), T (turquoise), or P(pink). It specifies in which color the application identifier is to be displayed oneach panel of an application.


Table 71. VSAM Profile Data Area EMSSRTGOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 168 VSRTG0 (0) ADDRESS 4 VGPTR Chain pointer4 (4) UNSIGNED 2 VGLEN Length of record (128 bytes)6 (6) CHARACTER 8 VGGRPID Group ID

14 (E) CHARACTER 8 VGSERVER Group application name22 (16) CHARACTER 8 VGSYSID Group system ID30 (1E) CHARACTER 30 VGCSELP Application description on Selection panel60 (3C) CHARACTER 1 VGLOGPRF Group application logon profile61 (3D) CHARACTER 1 VGALOG Group application autologon: Y=Yes/N=No62 (3E) CHARACTER 1 VGACCTYP Access Mode: R=Relay/P=Pass/B=Both63 (3F) BITSTRING 1 VGJKEY Group application jump key64 (40) UNSIGNED 1 VGSEQNO Default sequence number65 (41) CHARACTER 1 VGDACOM Data compression: Y=Yes/N=No/F=Full66 (42) CHARACTER 1 VGAMRI Msg. received indicator: I=Information/J=Jump/

N=Normal67 (43) CHARACTER 1 VGSHR Shareable: Y=Yes/N=No68 (44) CHARACTER 1 VGVIT Virtual terminal69 (45) CHARACTER 8 VGREXXLN Logon REXX exec name77 (4D) CHARACTER 8 VGREXXLF Logoff REXX exec name

| 85| (5D)| CHARACTER| 8| VGLOGMOD| Application logmode| 93| (55)| CHARACTER| 11| *| For future use

104 (68) CHARACTER 24 VGLUPD Last update information:104 (68) CHARACTER 8 VGLUUID User ID112 (70) CHARACTER 8 VGLUDATE Date120 (78) CHARACTER 8 VGLUTIME Time128 (80) CHARACTER 40 VGDAI Application ID128 (80) CHARACTER 1 VGDAIID Display ID: Y=Yes/N=No129 (81) CHARACTER 3 VGDAIRO Row of application ID text132 (84) CHARACTER 4 VGDAICO Column of application ID text136 (88) CHARACTER 30 VGDAITX Application ID text166 (A6) CHARACTER 1 VGDAIHI Highlighting of text167 (A7) CHARACTER 1 VGDAICL Color of text168 (A8) CHARACTER *

Group Profile Table (GPRF)The Group Profile Table (GPRF Table) contains the following fields.

Note: The values in parenthesis refer to the field names in the EMSGPRF dataarea description in Table 72 on page 320.

Group ID (VGPGRPID)This is the group name. It can be up to 8 characters.

Account Number (VGPACC)This field contains up to 8 characters. It is an optional field. The accountnumber is a number that can be used by your installation to charge for allactivities of a group. This field is used to enter a default value to be used bythe ampersand variable, &ACCNO.


Command Prefix (VGPCMDP)This field contains up to 8 alphanumeric characters. Users of this group musttype a prefix before a NetView Access Services command. This tells NetViewAccess Services that it is a NetView Access Services command. Thecommand prefix is to be used only on the panels of an application and not onNetView Access Services panels. It must be used together with a commandand the command key. This prefix is used only for relay mode applications.

Multiterminal Access (VGPMLU)This field contains Y for yes or N for no. This says whether each member of agroup can log on to more than one terminal at a time.

Number of Sessions (VGPMSES)This field contains any number between 1 and 99. This is the number of relayapplication sessions that each user can use simultaneously. It is the samenumber for all the members of the group.

Escape Key (VGPRTKEY)This is a PF or PA key, or the ATTN key assigned as the escape key. It canalso be blank. All users assigned to use applications in the group can use thiskey to escape from any relay-mode application to their Application Selectionpanel.

Command Key (VGPCMDK)This key can be a PF key or the Enter key. The command key is used afterthe user has typed a NetView Access Services command in a panel of anapplication. The command must also follow the NetView Access Servicescommand prefix. This field is used only for relay mode applications. UsingEnter is convenient, but might slow down response time.

CopyFrom Begin (VGPCPYFB)This is a PF key assigned to start the copy-from area. This is used only forrelay mode applications.

CopyFrom End (VGPCPYFE)This is a PF key assigned to end the copy-from area. This is used only forrelay mode applications.

CopyTo (VGPCPYTB)This is a PF key assigned to start the copy-to area. This is used only for relaymode applications.

Group Type (VGPGTYPE)Indicator whether this is a normal (N), external (E), or public (P) group.

Shared Session Response (VGPRESP)This field contains S (system-wide), G (group-wide), or N (none). It specifieswhether or not users of a specified group can share a session with othermembers of the group or with all users of NetView Access Services.

Printer (VGPPRT)This field contains up to 8 alphanumeric characters. It specifies the printer LUname or SYSTEMPR for the specified group. This is the group printer towhich users of the group can send a copy of a panel of an application.


Print Key (VGPPRKEY)This is a PF or PA key, assigned as the print key. It can also be blank. Allusers assigned to use applications in the group can use this key to print apanel of any relay-mode application.

Logon REXX Exec Name (VGPREXX)This field contains up to 8 alphanumeric characters. It specifies the name ofthe REXX exec to start during automatic logon to the specified group.

Logoff REXX Exec Name (VGPRXLF)This field contains up to 8 alphanumeric characters. It specifies the name ofthe REXX exec to start during automatic logoff from the specified group, andwhen the time-out value for the terminal session is reached.

| ASP Format| This field contains 1 alphabetic character. It specifies the form of the Applica-| tion Selection panel to be used. Specify C for compact or N for normal.

Last Update (VGPLUPD)Contains user ID, date, and time of last update.

Table 72. VSAM Profile Data Area EMSGPRFOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 96 VGPRF0 (0) ADDRESS 4 VGPPTR Chain pointer4 (4) UNSIGNED 2 VGPLEN Length of record (96 bytes)6 (6) CHARACTER 8 VGPGRPID Group ID

14 (E) CHARACTER 8 VGPACC Group account number22 (16) CHARACTER 8 VGPCMDP Group command prefix30 (1E) CHARACTER 1 VGPMLU Group multiterminal access31 (1F) CHARACTER 2 VGPMSES Group max. parallel sessions33 (21) BITSTRING 1 VGPRTKEY Group escape key34 (22) BITSTRING 1 VGPCMDK Group command key35 (23) BITSTRING 1 VGPCPYFB Group CopyFrom Begin key36 (24) BITSTRING 1 VGPCPYFE Group CopyFrom End key37 (25) BITSTRING 1 VGPCPYTB Group CopyTo Begin key38 (26) CHARACTER 1 VGPGTYPE Group Type: P=Public/ E=External/ N=Normal39 (27) CHARACTER 1 VGPRESP Shared session request40 (28) CHARACTER 8 VGPPRT Printer LU name or SYSTEMPR48 (30) BITSTRING 1 VGPPRKEY Print key49 (31) CHARACTER 8 VGPRXLN REXX exec for logon49 (31) CHARACTER 8 VGPREXX REXX exec for logon57 (39) CHARACTER 8 VGPRXLF REXX exec for logoff

| 65| (41)| CHARACTER| 1| VGPASPF| ASP Format (Normal or Compact)| 66| (42)| CHARACTER| 6| *| For future use

72 (48) CHARACTER 24 VGPLUPD Last update information72 (48) CHARACTER 8 VGPLUUID User ID80 (50) CHARACTER 8 VGPLUDAT Date88 (58) CHARACTER 8 VGPLUTIM Time


Application Routing Table (EMSSRTS)The Application Routing Table (EMSSRTS Table) contains the following fields.

Note: The values in parentheses refer to the field names in the EMSSRTS dataarea description in Table 73 on page 323.

System-Internal Name (VSSYSID)This field contains up to 8 characters. It is the system-wide name of an appli-cation. It can be given different names in each group, but this is the name bywhich the whole NetView Access Services system knows it.

Primary LU Name (VSSYSLOC)This field contains up to 8 characters. It is the network name of the applica-tion. This is how SNA identifies the location of the application. The applica-tion can run under any operating system, if the operating system has VTAM.NetView Access Services can run in a different operating system from theapplication.

Transaction Program Name (VSTRANS)This field contains up to 8 characters and need only be filled in if an ASR isdefined. In this case no ACB is required. It is the transaction program nameof the ASR for ASR-to-ASR communication. An ASR communicates withapplications through the CS of NetView Access Services and then throughVTAM. VTAM is involved in the communication regardless of whether anapplication runs in another address space (or even another system), or as anASR in the same NetView Access Services address space. ASR-to-ASRcommunication implements a link between ASRs in the same NetView AccessServices through CS without traversing VTAM.

Pseudo Terminal Prefix (VSTPRE)This field contains between 0 and 8 alphanumeric characters. NetViewAccess Services uses this prefix to identify pseudo terminals as NetViewAccess Services terminals. For applications with an ACB type of Unique thepseudo terminal prefix defines a pool of pseudo terminal names. The namesare created by taking this prefix and suffixing digits to get 8-character names.The number of digits suffixed depends on the number of characters in theprefix.

For example, if the prefix is 5 characters long, the numbers span from 001 to999. The actual upper limit is determined by the maximum sessions value.The user can use the same pseudo terminal prefix for more than one applica-tion that has ACB type Unique. In this case the applications share the pool ofpseudo terminal names. The number of names in the pool is determined bythe number of maximum sessions of the application with the highest numberof maximum sessions.

For relay mode applications that have ACB type Shared, this prefix is used asthe pseudo terminal name, with no digits suffixed.

This field is used only with relay mode applications. For pass mode applica-tions it is ignored.


Maximum sessions (VSMSESNO)This field contains any integer between 0 and 65534. The default is 99. Thisis the maximum number of sessions that can be active concurrently for thisapplication in relay mode.

The system administrator can set any number between 0 and 65534, if ACBtype Shared is used. If ACB type Unique is used, the number of maximumsessions is limited by the possible size of the pool. For example, using thepseudo terminal prefix IMSAB, the value for the maximum number of sessionscan be any number between 001 and 999.

If more than one application shares the same pool, then the application withthe highest number of maximum sessions determines the size of the pool. Forexample, if application A has a maximum of 20 sessions and application B hasa maximum of 10 sessions, then the pool contains 20 names. In thisexample, if B uses 9 of the names, A can have only 11 names before the useris notified of maximum sessions. However, B can never get more than 10names.

If the value 0 is specified, no access to the application is possible. This fieldis used only with relay mode applications. For pass mode applications it isignored.

Idle Time Value (VSITIME)This field contains any integer between 0 and 999 minutes. This time defineshow long NetView Access Services waits between checks for idle time. If itfinds a session has been idle for two consecutive checks, then NetViewAccess Services disconnects an application session due to inactivity. 0means that no idle time checking is performed by NetView Access Services.

Alternative Sequences (VSAREC)This field contains any integer between 0 and 10. It is used to define themaximum number of alternative sequences allowed for each logon profile foran application. This is used only by relay mode applications.

Automatic Logon (VSALOG)This field contains Y for yes or N for no. This is where overriding authori-zation for automatic logon is given for an application. A group administratorcould restrict the members of the group further, but only within the confines ofthis definition. If yes, then automatic logon is allowed, and a logon profile canbe used to provide logon and logoff information. If no, then the user mustperform all the logon and logoff manually.

Access Mode (VSACCTYP)This field contains R for relay, P for pass, or B for both. This field is whereoverriding authorization is given for modes of access. It is possible to restrictthe application for the whole system to either relay mode or pass mode, or theuser can allow both modes. The system administrator can restrict further forthe members of a particular group, when assigning an application to thatgroup. The group administrator can decide for each user whether they canuse one mode, the other, or both (within the limits set by the system adminis-trator).


ACB Type (VSACBTYP)This field contains U for Unique or S for Shared.

An ACB type of Shared indicates that the ACB is defined to support parallelsessions. Access control block sharing saves resources, but is not alwayspossible.

An ACB type of Unique indicates that each session requires a separate ACB.Only applications with ACB type Unique can share a pool of pseudo terminalnames.

The ACB type is used only for relay mode applications. For pass mode appli-cations it is ignored.

Shareable (VSSHR)This field contains Y for yes or N for no. It specifies whether a specified appli-cation can be shared between two users or not.

Status Update (VSASITIM)This field contains any integer between 0 and 1440 minutes. It specifies thetime between inquiries as to whether an application is online or not.

Backup Application Name (VSFBNAME)This field contains the system-internal name of the application to be used as abackup for another application.

Last Update (VSLUPD)Contains user ID, date, and time of last update.

Table 73. VSAM Profile Data Area EMSSRTSOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 96 VSRTS0 (0) ADDRESS 4 VSPTR Chain pointer4 (4) UNSIGNED 2 VSLEN Length of record (96 bytes)6 (6) CHARACTER 8 VSSYSID System ID, nickname for subsystem

14 (E) CHARACTER 8 VSSYSLOC System location = VTAM ACB22 (16) CHARACTER 8 VSTRANS Transaction program name30 (1E) CHARACTER 8 VSTPRE Subsystem terminal prefix38 (26) CHARACTER 5 VSMSESNO Maximum session number for subsystem43 (2B) CHARACTER 3 VSITIME Idle time for subsystem46 (2E) CHARACTER 2 VSAREC Maximum alternative sequences48 (30) CHARACTER 1 VSALOG Autologon: Y=Yes/N=No49 (31) CHARACTER 1 VSACCTYP Access Mode: R=Relay/P=Pass/B=Both50 (32) CHARACTER 1 VSACBTYP ACB type: S=Shared/U=Unique51 (33) CHARACTER 1 VSSHR Shareable: Y=Yes/N=No52 (34) CHARACTER 4 VSASITIM ASI inquire time interval56 (38) CHARACTER 8 VSFBNAME Backup application name64 (40) CHARACTER 8 * For future use72 (48) CHARACTER 24 VSLUPD Last update information72 (48) CHARACTER 8 VSLUUID User ID80 (50) CHARACTER 8 VSLUDATE Date88 (58) CHARACTER 8 VSLUTIME Time


Group Access List Table (EMSGAL)The Group Access List Table (EMSGAL Table) contains the following fields.

Note: The values in parentheses refer to the field names in the EMSGAL dataarea description in Table 74.

Group ID (VGALGID)If the user is to be a group administrator. The user will be a system adminis-trator, if no group ID is specified.

User ID (VGALUID)User ID of a NetView Access Services administrator.

Type of Administrator (VGALATTR)Type of NetView Access Services administrator. This field contains S(system), G (group), or B (broadcast only).

Last Update (VGALLUPD)Contains user ID, date, and time of last update.

Table 74. VSAM Profile Data Area EMSGALOffsets

Type Length Name (Dim) DescriptionDec Hex 0 (0) STRUCTURE 64 VGAL0 (0) ADDRESS 4 VGALPTR Chain pointer4 (4) UNSIGNED 2 VGALLEN Length of record (64 bytes)6 (6) CHARACTER 8 VGALGID Group ID

14 (E) CHARACTER 8 VGALUID User ID22 (16) CHARACTER 1 VGALATTR Type of administrator: S=System/G=Group/

B=Broadcast23 (17) CHARACTER 17 * For future use40 (28) CHARACTER 24 VGALLUPD Last update information40 (28) CHARACTER 8 VGALLUUI User ID48 (30) CHARACTER 8 VGALLUDA Date56 (38) CHARACTER 8 VGALLUTI Time


Appendix C. Customization Worksheets

The following provides worksheets that can be filled out to help you duringcustomization of NetView Access Services.

Table 75. Job EMSPARMC Customization Parameters

Parameter IBM Default Value Your Value

DRYRUN 'NO'

| VSAMHLQ| 'EMS.V2R1M1'

| VSAMVOL| 'NVAS01'

| SRCEXIT| 'EMS.V2R1M1.SEMSSRC0'

| SRCMESTB| 'EMS.V2R1M1.SEMSSRC0'

DUMPDSN 'SYS1.DUMP01'

ACBLEN 8

ACBNUM 99

ACBPREFX 'EMSACB'

ACBSUFFX 'DEC'

ACBSTART 1

Table 76. General Parameters for Installation Phase 1


DRYRUN 'NO'

BASEINST 'YES'

INSTACCT '(DE02072)'

INSTPGRN 'NVAS INSTALLER'

INSTUID 'XYZ'

CUSTACCT '(ACCTNBR)'

CUSTPGRN 'NVAS CUSTOMIZER'

CUSTUID 'XYZ'

JOBCLS 'A’

JOBMCLS 'X'

JOBOUTC '*'

JOBPREF 'USERID'

NLSINST 'NO'

| NVASHLQ| 'EMS.V2R1M1'

SMS 'NO'

TUNIT '3480'

WDSK 'SYSDA'


Table 77. Information for NetView Access Services Libraries for Installation Phase 1


| NVASHLQ| 'EMS.V2R1M1'

| BLKFB| '8800'

BLKU '6144'

DISTUNIT 'SYSDA'

DISTVOL 'NVAS01'

TARGUNIT 'SYSDA'

TARGVOL 'NVAS01'

Table 78. ISPF/PDF Data Set Names


ISPPLIB 'SYS1.ISPPLIB'

ISPMLIB 'SYS1.ISPMLIB'

ISPTLIB 'SYS1.ISPTLIB'

Table 79. SMP/E Parameters for Installation Phase 1


| ASSNAME| 'ASMA90'

| CSIDISP| 'NEW'

| DCSIHLQ| 'EMS.V2R1M1.'

| DCSIVOL| 'NVAS01'

| DSPREFIX| 'EMS.V2R1M1'

| DZONE| 'EMSD211'

| GCSIHLQ| 'EMS.V2R1M1'

| GCSIVOL| 'NVAS211'

NEWZONES 'YES'

RELUNIT 'SYSDA'

RELVOL 'NVAS01'

SMPUNIT 'SYSDA'

SMPVOL 'NVAS01'

| TCSIHLQ| 'EMS.V2R1M1'

TCSIVOL 'NVAS01'

| TZONE| 'EMS211'

WDSK 'SYSDA'


Part 6. Glossary, Bibliography, and Index



Glossary

This glossary defines terms as they are used in thisbook. If you do not find the terms you are looking for,refer to Dictionary of Computing, SC20-1699.

abend . Abnormal end of task.

abnormal end of task . Termination of a task beforeits completion because of an error condition that cannotbe resolved by recovery facilities while the task is beingexecuted.

ACB . Application Control Block.

ACB name . (1) The name of an ACB macroinstruction.(2) A name specified in the ACBNAME parameter of aVTAM APPL statement. Contrast with network name.

access . In RACF, the ability to obtain use of a pro-tected resource.

access mode . In NetView Access Services, the typeof access a user can have to an application. There isrelay mode only, pass mode only, or both.

administration . The process of designing, controlling,and managing the use of NetView Access Services or aNetView Access Services group.

administration panel . A panel designed to aid in thetask of administration.

administrator . A person who organizes applicationsinto groups, assigns users to use applications in thegroup, and defines certain parameters for the system,groups, users, and applications.

alert . (1) In SNA, a record sent to a system problemmanagement focal point to communicate the existenceof an alert condition. (2) In the NetView program, ahigh priority event that warrants immediate attention.This database record is generated for certain eventtypes that are defined by user-constructed filters.

alternative sequence . In NetView Access Services, asequence of data, recorded as a branch from a mainsequence. It is used when an application responds withdifferent panels from those in the usual sequence in thelogon profile. It is data recorded as an alternative to amain sequence and is used when an application cannotrespond to the main sequence in the logon profile.

ampersand variable . Variables that are prefixed withan ampersand character.

APAR . Authorized Program Analysis Report.

application . The use to which a data processingsystem is put. In NetView Access Services, the term isused to mean a system, a subsystem, or a transactionwithin a subsystem.

application control block (ACB) . A control block thatlinks an application program to VSAM or VTAM. Astorage area used by a program to hold access-controlinformation.

application program . A program that is written for orby a user that applies to the user’s work.

application session . In NetView Access Services, asession between NetView Access Services and anapplication.

APPL statement . In VTAM, a statement identifying anapplication to VTAM.

ASR. Application Service Routine. In NetView AccessServices, a service routine that communicates withapplications through the communication services ofNetView Access Services and then VTAM.

ASR-to-ASR communication . In NetView AccessServices, a function that implements a link between theASRs of the same NetView Access Services throughthe communication services of NetView Access Ser-vices without traversing VTAM.

authentication . Checking a user’s identity beforeauthorization to log on is given.

authorized program analysis report (APAR) . Areport of a problem caused by a suspected defect in acurrent unchanged release of a program.

automatic logon . A process by which VTAM creates asession-initiation request (a logon) for a sessionbetween a secondary logical unit other than a sec-ondary application program and a designated primarylogical unit. In NetView Access Services, the processof creating a logon from NetView Access Services to anapplication.

begin bracket . In SNA, the value (binary 1) of thebegin-bracket indicator in the request header (RH) ofthe first request in the chain of a bracket; the valuedenotes the start of the bracket. Contrast with endbracket. See also bracket.

BID. A data flow control command that is used torequest permission to start a bracket.

BIND. In SNA products, a request to activate asession between two logical units.


BIND user data . In SNA, data, that relates to a userand is sent with a BIND request.

bracket . In SNA, one or more chains of request units(RU) and their responses that are exchanged betweenthe two LU-LU half-sessions and that represent a trans-action between them. A bracket must be completedbefore another bracket can be started. Examples ofbrackets are database inquiries/replies, update trans-actions, and remote job entry output sequences to workstations. See also begin bracket and end bracket.

CD. Change Direction.

CDR. Cross-Domain Resource.

CDRM. Cross-Domain Resource Manager.

Change Direction (CD) protocol . An SNA data flowcontrol protocol in which the sending LU stops sendingnormal-flow requests, signals this fact to the receivingLU, and prepares to receive requests. It does thisusing the change-direction indicator in the requestheader of the last request of the last chain.

CICS/VS. Customer Information Control System/VirtualStorage.

class of service (COS) . In SNA, a designation of thepath control network characteristics, such as path secu-rity, transmission priority, and bandwidth, which apply toa particular session. The end user designates class ofservice at session initiation by using a symbolic namethat is mapped into a list of virtual routes, any one ofwhich can be selected for the session to provide therequested level of service.

CLIST. Command list.

command key . In NetView Access Services, the keythat is used to send a command to NetView AccessServices when using an application.

command list (CLIST) . (1) In NetView Access Ser-vices, a list of commands, control statements, or both,that is assigned a name. When the name is invoked,the commands in the list are executed. (2) In TSO, adata set or a member of a partitioned data set con-taining TSO commands to be performed sequentially inresponse to the EXEC command.

command prefix . In NetView Access Services, astring of characters that is used, when in an application,to denote the beginning of a command that is sent toNetView Access Services.

control block . A storage area used by a program tohold control information.

COS. Class of Service.

Cross Domain Resource (CDR) . A resource ownedby a cross-domain resource manager (CDRM) inanother domain but known by the CDRM in this domainby network name and associated CDRM.

Cross-Domain Resource Manager (CDRM) . Thefunctions of the system services control point (SSCP)that control initiation and termination of cross-domainresources.

Customer Information System/Virtual Storage(CICS/VS). An IBM licensed program used in a com-munications network. It is a transaction manager thatprovides database and data communications support oftransaction programs.

DASD. Direct Access Storage Device. A device inwhich access time is effectively independent of thelocation of the data.

data stream . A continuous stream of information witha specific structure (architecture).

DBCS. Double-Byte Character Set.

default application . In NetView Access Services,when specified, the application that is assumed if noneis entered on the Logon panel.

default group . In NetView Access Services, the groupwith which a user is associated when no group name isentered on the Logon panel.

default value . An alternative value, attribute, or optionthat is assumed when none has been specified by theuser.

double-byte character set . A set of graphic charac-ters where two bytes are used to represent the char-acter set of such languages as Chinese and Japanese.The shift-in (SI) and shift-out (SO) control codes areused when DBCS is mixed with standard one-byte char-acter sets.

end bracket (EB) . In SNA, the value (binary 1) of theend-bracket indicator in the request header (RH) of thefirst request of the last chain of a bracket; the valuedenotes the end of the bracket. Contrast with beginbracket. See also bracket.

error message . A message that NetView Access Ser-vices shows the user when it has encountered an error.

escape key . In NetView Access Services, the keyused when using an application to return to the Applica-tion Selection panel, without logging off or disconnectingfrom that application.

event . (1) In the NetView program, a record indicatingirregularities of operation in physical elements of anetwork. (2) An occurrence of significance to a task;


typically, the completion of an asynchronous operation,such as an input/output operation.

extended highlighting . On some displays, the abilityto show reverse video, underscoring, and blinking.

field . A specified area used for a particular type ofdata.

FMD. Function Management Data.

FMH. Function Management Header.

function management data (FMD) . In SNA, a requestunit (RU) category used for end-user data exchangedbetween logical units (LU) and for requests andresponses exchanged between network services com-ponents of LUs, physical units (PUs), and system ser-vices control points (SSCPs).

function management header (FMH) . In SNA, one ormore headers, optionally present in the leading requestunits (RUs) of an RU chain, which allow one half-session in an LU-LU session to: (1) select a destinationat the session partner and control the way in which theend-user data it sends is handled at the destination, (2)change the destination or the characteristics of the dataduring the session, and (3) transmit between sessionpartners status or user information about the destination(for example, a program or device). Function manage-ment headers (FMHs) can be based on LU-LU types 1,4, and 6.2.

GAL . Group Access List. This profile contains infor-mation about who has access to group information foreach group (that is, administrators).

generalized trace facility (GTF) . An optional OS/VSservice program that records significant system events,such as supervisor calls and start I/O operations, for thepurpose of problem determination.

GPRF. Group Profile. A profile containing only groupdefinitions. It has nothing to do with applications.

group . A set of applications bound by common cri-teria. The system administrator decides the criteriaused to define groups and how to associate users withdifferent groups. There are three types of NetViewAccess Services groups: Normal, Public, and External.

group administrator . The person that administers agroup.

GRS. Global Resource Serialization facility.

GTF. Generalized Trace Facility.

idle time . The part of operable time during which aprogram is not used.

IMS/VS. Information Management System/VirtualStorage.

Information Management System/Virtual Storage(IMS/VS). A general-purpose database system thatenhances the capabilities of MVS for batch processingand telecommunication. It allows users to gain accessto a computer-maintained database through remote ter-minals.

input field . A field on a panel where a user can enterdata.

installation-wide exit routine . A routine written by auser to take control of an installation-wide exit of aprogram supplied by IBM.

installer . The person who installs a program.

installing . The process of preparing and placing afunctional unit in position for use.

JCL . Job Control Language.

job control language (JCL) . A problem-oriented lan-guage that communicates with operating systems.

jump key . The key used to jump from the currentapplication to another application.

Kanji . A character set of symbols used for Japaneseideograms. See also double-byte character set.

Katakana . A character set of symbols used in one ofthe two common Japanese phonetic alphabets.

large message performance enhancement outbound(LMPEO). In VTAM, a facility in which VTAM reformatsfunction management data (FMD) that exceeds themaximum request unit (RU) size (as specified in theBIND) into a chain or partial chain of RUs.

LMPEO. Large message performance enhancementoutbound.

local address . In SNA, an address used in a periph-eral node in place of an SNA network address andtransformed to or from an SNA network address by theboundary function in a subarea node.

location . In NetView Access Services, a place whereNetView Access Services is installed.

logging on . The process of opening a session with anapplication or with NetView Access Services.

logical unit (LU) . In SNA, a port through which an enduser accesses the SNA network and the functions pro-vided by system service control points (SSCPs). An LUcan support at least two sessions—one with an SSCPand one with another LU—and may be capable of sup-

Glossary 331

porting many sessions with other LUs. See alsonetwork addressable unit (NAU), system servicescontrol point (SSCP), primary logical unit (PLU), andsecondary logical unit (SLU).

logmode . Synonym for logon mode.

logmode table . Synonym for logon mode table.

logoff sequence . A sequence of data recorded duringa logoff.

logon mode . In VTAM, a subset of session parame-ters specified in a logon mode table for communicationwith a logical unit. See also session parameters.

logon mode table . In VTAM, a subset of entries forone or more logon modes. Each logon mode is identi-fied by a logon mode name.

logon profile . A file containing a logon sequence, plusany alternative sequences, and a logoff sequence, ifone has been recorded. This file is used by NetViewAccess Services for automatic logon and logoff, if alogoff sequence has been recorded.

logon sequence . A sequence of data recorded duringa logon procedure. For example, variables for the userID and password, and any other information necessaryto complete the logon to a particular application that canbe used by NetView Access Services to perform theautomatic logon for a user.

LU. Logical Unit.

LU name . In programming, a name used to representan input/output unit.

LUSTAT . Logical Unit Status.

member . A part of a partitioned data set that can beused independently of other members of the data set.

mode . A method of operation. See pass mode andrelay mode.

multidomain network . In SNA, a network with morethan one SSCP.

Multiple Virtual Storage (MVS) . An IBM licensedprogram whose full name is Operating System/VirtualStorage (OS/VS) with Multiple Virtual Storage/SystemProduct for System/370. It is a software operatingsystem controlling the execution of programs.

Multiple Virtual Storage/Extended Architecture . AnIBM licensed program whose full name is OperatingSystem/Virtual Storage (OS/VS) with Multiple VirtualStorage/System Product for Extended Architecture.Extended Architecture allows 31-bit storage addressing.

MVS/XA is a software operating system controlling theexecution of programs.

MVS. (1) Multiple virtual storage. Implies MVS/370,the MVS/XA product, and the MVS/ESA product. (2)Multiple Virtual Storage, consisting of MVS/SystemProduct Version 1 and the MVS/370 Data FacilityProduct on a System/370 processor. See also MVS/XAproduct.

MVS/ESA. Multiple Virtual Storage/Enterprise SystemsArchitecture.

MVS/XA. Multiple Virtual Storage/Extended Architec-ture.

NAU. Network Addressable Unit.

NetView . An IBM licensed program consisting of abase for command processors that can monitor, control,and improve the operation of a network.

NetView Performance Monitor (NPM) . An IBMlicensed program that collects, monitors, analyzes, anddisplays data relevant to the performance of a VTAMtelecommunication network. It runs as an online appli-cation program.

network . A configuration of data processing and soft-ware connected for information interchange. See alsoSNA network.

network address . In SNA, an address, consisting ofsubarea and element fields, which identifies a link, alink station, or a network addressable unit (NAU).Subarea nodes use network addresses; peripheralnodes use local addresses. The boundary function inthe subarea node to which a peripheral node isattached transforms local addresses that networkaddresses and vice versa. See local address. Seealso network name.

network addressable unit (NAU) . In SNA, a logicalunit (LU), a physical unit (PU), or a system servicescontrol point (SSCP). It is the origin or the destinationof information transmitted by the path control network.See also network address and network name.

Network Management Vector Transport (NMVT) . Amanagement services request/receive unit (RU) thatflows over an active session between physical unit man-agement services and control point management ser-vices (SSCP-PU session).

network name . (1) In SNA, the symbolic identifier bywhich end users refer to a network addressable unit(NAU), a link, or a link station. See also networkaddress. (2) In a multidomain network, the name of theAPPL statement defining a VTAM application programis its network name and it must be unique across


domains. Contrast with ACB name. See uninterpretedname.

NMVT. Network Management Vector Transport.

NPM. NetView Performance Monitor.

object code . Output from a compiler or assemblerwhich is itself executable machine code or is suitablefor processing to produce executable machine code.

Operating System/Virtual Storage . A family of oper-ating systems that control IBM System/360 andSystem/370 computing systems.

operator . A person who operates a device or asystem. In NetView Access Services, the person thatsupervises the running of NetView Access Services.

operator console . A display console used for commu-nication between the operator and the system, used pri-marily to specify information concerning applicationprograms, and to monitor the system.

OS/VS. Operating System/Virtual Storage.

panel . The complete set of information shown in asingle display on a screen. Each panel is like a manualpage.

partitioned data set . A data set made up of severalparts (members). Each part can contain text, data, aprogram, or part of a program.

pass mode . In NetView Access Services, the modeused to select an application when NetView AccessServices passes control to the application.

primary half-session . In SNA, the half-session thatsends the session-activation request. See also primarylogical unit (PLU). Contrast with secondaryhalf-session.

PLU. Primary Logical Unit.

POI. Program Operator Interface.

PPT. Primary Program operator interface Task.

primary logical unit (PLU) . In SNA, the LU that con-tains the primary half-session for a particular LU-to-LUsession. Contrast with secondary logical unit (SLU).See also logical unit (LU).

primary program operator interface task (PPT) . Asubtask that processes all unsolicited messagesreceived from the ACF/VTAM program operator inter-face (POI) and delivers them to either the controllingoperator or command processor. The primary POI taskalso processes the initial command specified to be exe-cuted when the Network Communications Control

Facility is initialized, and timer request commandsscheduled to execute under the PPT.

print key . The key used to print a panel of an applica-tion.

problem determination . The process of determiningthe source of a problem; for example, a program com-ponent, machine failure, user-installed programs orequipment, environmental failure such as a power loss,or a user error.

profile . Data that describes the significant character-istics of a user, a group of users, or one or more com-puter resources.

pseudo terminal name . In NetView Access Services,a name used to represent a terminal in a relay modesession. If the session has ACB type Unique or Indi-vidual, this name can be one from a pool of names,each using a common prefix with different numbersaffixed. If the session has ACB type Shared, this nameis not from a pool, but it could be the same as theprefix, with no numbers suffixed.

pseudo terminal prefix . In NetView Access Services,a string used to define a pool of pseudo terminalnames. The names are defined by suffixing numbers tothis prefix.

PTF. Program Temporary Fix.

RACF. Resource Access Control Facility.

recording . The process of storing a sequence of datafor future use in a logon or logoff profile.

relay mode . The mode used when all processing ofan application goes through NetView Access Services.

request header (RH) . In SNA, control information pre-ceding a request unit (RU). See also request/responseheader.

request/response header . In SNA, control informa-tion, preceding a request/response unit (RU), whichspecifies the type of RU (request unit or response unit)and contains control information associated with thatRU.

request/response unit (RU) . In SNA, a generic termfor a request unit or a response unit. See also requestunit and response unit.

request unit . In SNA, a message unit that containscontrol information, end-user data, or both.

Resource Access Control Facility (RACF) . An IBMlicensed program that provides for access control byidentifying and verifying users to the system, authorizingaccess to protected resources, logging the detected

Glossary 333

unauthorized attempts to enter the system, and loggingthe detected accesses to protected resources.

response time data . Data collected by NetView forresponse time monitoring. The response time is thetime measured between activation of a transaction anda received response.

response unit . In SNA, a message unit that acknowl-edges a request unit; it may contain prefix informationreceived in a request unit. If positive, the response unitmay contain additional information (such as sessionparameters in response to BIND Session), or if nega-tive, contains sense data defining the exception condi-tion.

returning . In NetView Access Services, the process ofusing a special key or command, when in an applica-tion, to display the Application Selection panel on thescreen, without logging off or disconnecting from thatapplication.

RH. Request Header.

RPL. Request Parameter List.

RPL exit routine . In ACF/VTAM, an applicationprogram exit routine whose address has been placed inthe exit field of a request parameter list. ACF/VTAMinvokes the routine to indicate that an asynchronousrequest has been completed.

RU. Request/Response Unit.

SAW. Session Awareness Data.

screen copy . In NetView Access Services, the facilitythat enables users to copy data from a panel on a ter-minal screen to a copy buffer, and then to copy it toanother panel on the screen.

SCS. SNA (Systems Network Architecture) CharacterStream.

SDUMP. SVC dump.

secondary half-session . In SNA, the half-session thatreceives the session-activation request. See also sec-ondary logical unit (SLU). Contrast with primary half-session.

secondary logical unit (SLU) . In SNA, the LU thatcontains the secondary half-session for a particularLU-to-LU session. Contrast with primary logical unit(PLU). See also logical unit (LU).

security management program . See RACF.

selective broadcast message . In NetView AccessServices, a broadcast message that is sent only to

selected users or groups of users by the system admin-istrator.

services level reporter (SLR) . A licensed programthat generates reports from data sets such as SystemManagement Facility (SMF) files. See System Manage-ment Facility (SMF).

session . In SNA, a logical connection between twonetwork addressable units that can be activated, tai-lored to provide various protocols, and deactivated asrequired. In NetView Access Services a sessionbetween NetView Access Services and an application.

session-awareness data . Data collected by NetViewabout a session that includes the session type, thenames of session partners, and information about thesession activation status.

session parameters . In SNA, the parameters thatspecify or constrain the protocols (such as bracket pro-tocol and pacing) for a session between two networkaddressable units. See also logon mode. See shift-incharacter.

shift-in character . A code extension character used toterminate a sequence that has been introduced by theshift-out character to make effective the graphic charac-ters of the standard character set.

shift-out character . A code extension character thatsubstitutes for graphic characters of the standard char-acter set an alternative set of graphic characters uponwhich an agreement has been arrived at or that hasbeen designated using code extension procedures.

SI. Shift In. See shift-in character.

SIGNAL . An SNA command used to request a breakin the data flow.

single access control . A facility that provides for pro-grammed control, from a single screen, of a user’sauthorization to access-protected data.

SLR. Services Level Reporter.

SLU. Secondary Logical Unit.

single-domain network . In SNA, a network with oneSSCP.

SMF. System Management Facility.

SMP. System Modification Program. An IBM programthat facilitates the process of installing and servicing anMVS system.

SMS. System Managed Storage.

SNA. Systems Network Architecture.


SNA character stream . A line printer data stream thatconsists of text and formatting information that controlsthe printing of text.

SNA network . In SNA, the part of a user-applicationnetwork that conforms to the formats and protocols ofSystems Network Architecture. It enables reliabletransfer of data among users, and provides protocols forcontrolling the resources of various network configura-tions.

SNA network interconnection . The connection, bygateways, of two or more independent SNA networks toallow communication between logical units in those net-works. The individual SNA networks retain their inde-pendence.

SNI. SNA Network Interconnection.

SO. Shift Out. See shift-out character.

SQA. System Queue Area.

SRTG. Server Routing Table Group. A profile thatcontains information relating to an application in a par-ticular group.

SRTS. Server Routing Table System. A profile con-taining information related to an application for thewhole system, irrespective of group.

SRTU. Server Routing Table User. A profile that con-tains information relating to an application for a partic-ular user.

SSCP. System Services Control Point.

Supervisor Call (SVC) . A request that serves as theinterface into operating systems functions, such as allo-cating storage. The SVC protects the operating systemfrom inappropriate user entry. All operating systemrequests must be handled by SVCs.

SVC. Supervisor Call.

system . In data processing, a collection of users,machines, and methods organized to accomplish a setof specific functions.

SYSOUT. System Output (print class). A concept thatspecifies where to print the data stream in MVS.

system administrator . An administrator of theNetView Access Services system, carrying out suchtasks as defining applications, groups, and administra-tors to NetView Access Services.

system-internal name . The name by which an appli-cation is identified to the NetView Access Servicessystem. The same application may have a differentname within each group.

System Management Facility (SMF) . A standardfeature of MVS that collects and records a variety ofsystem and job-related information.

system printer . A printer that is not a control-unit-attached printer.

system queue area (SQA) . An area of virtual storagereserved for system-related control blocks. It containsfixed pages and is assigned protection key zero.

system services control point (SSCP) . In SNA, afocal point within an SNA network for managing theconfiguration, coordinating network operator andproblem determination requests, and providing directorysupport and other session services for end users of thenetwork. Several SSCPs, cooperating as peers, candivide the network into domains of control, with eachSSCP having a hierarchical control relationship to thephysical units within its domain.

Systems Network Architecture (SNA) . Thedescription of the logical structure, formats, protocols,and operational sequences for transmitting informationunits through, and controlling the configuration andoperation of, networks.

time-out . A feature that logs off a user if no key ispressed within a predefined time.

Time Sharing Option (TSO) . The option on an MVSoperating system, providing interactive time sharingfrom remote terminals.

TPN. Transaction Program Name.

tracing . In NetView Access Services, the process ofdisplaying the sequence in which instructions are per-formed during an automatic logon or logoff.

Transaction Program Name (TPN) . In NetViewAccess Services, the name of the transaction programfor ASR-to-ASR communication.

TSO. Time Sharing Option.

uninterpreted name . In SNA, a character string that asystem services control point (SSCP) is able to convertinto the network name of a logical unit (LU). Typically,an uninterpreted name is used in a logon or initiaterequest from a secondary logical unit (SLU) to identifythe primary logical unit (PLU) with which the session isrequested.

user authorization . Authorization given to a user tohave complete or restricted access to a function.

variable . (1) A name used to represent a data itemwhose value can be changed while the program isrunning. (2) A character string beginning with & that is

Glossary 335

coded in a command and assigned a value during exe-cution of the command.

Virtual Telecommunications Access Method(VTAM). An IBM licensed program whose full name isAdvanced Communications Function for the VirtualTelecommunications Access Method. A set of pro-grams that maintain the control of the communicationbetween terminals and application programs runningunder some operating systems. It provides single-domain, multiple-domain, and interconnected networkcapability.

VTAM. Virtual Telecommunications Access Method.

VTAM application program . An application programthat has opened an ACB to identify itself to VTAM, andcan issue VTAM macroinstructions.


Bibliography

NetView Access ServicesVersion 2 Publications

NetView Access Services Version 2 General Informa-tion, GH19-4497

NetView Access Services Version 2 User’s Guide,SH19-4499

NetView Access Services Version 2 Administration,SH19-4500

NetView Access Services Version 2 Operation,SH19-4501

NetView Access Services Version 2 Messages,SH19-4503.

Network Publications

Network Program Products Storage Estimates,SC30-3403

NetView Installation and Administration Guide,SC31-6018

NetView Performance Monitor Installation andCustomization, SH20-6361.

VTAM Publications

VTAM Resource Definition Reference, SH31-6412.

VSAM Publications

MVS/ESA VSAM Administration Guide, SC26-4518

MVS/ESA VSAM Administration: Macro Instruction Ref-erence, SC26-4517.

OS/VS Publications

OS/VS2 System Programming Library: MVS DiagnosticTechniques, GC28-0725

MVS/ESA Application Development Macro Reference,GC28-1822.

RACF Publications

Systems Programming Library: Resource AccessControl Facility (RACF), SC28-1343

Resource Access Control Facility (RACF) Macros andInterfaces, SC28-1345

Resource Access Control Facility (RACF) CommandLanguage Reference, SC28-0733.

SNA Publications

Systems Network Architecture Management ServicesAlert Implementation Guide, GG31-6809.

CICS Publications

Resource Definition (Online), SC33-0186 (CICS/OS/VS)

Resource Definition (Online), SC33-0508 (CICS/MVS)

Resource Definition (Macro), SC33-0237 (CICS/OS/VS)

Resource Definition (Macro), SC33-0509 (CICS/MVS).

TSO Publications

TSO Extensions Version 2 Procedures LanguageMVS/REXX User’s Guide, SC28-1882

TSO Extensions Version 2 Procedures LanguageMVS/REXX Reference, SC28-1883.

Additional Publications

The following books published by the IBM InternationalTechnical Support Centers, or the TelecommunicationsSystems Support may also be helpful:

NetView Access Services Technical Overview and Per-formance Study, GG66-3167

MVS NetView/Access Services Security and RACF,GG24-3478

Single-Logon and Secondary Authentication withNetView Access Services 1.3 and RACF, GG24-3712

Enhanced Exploitation of RACF 1.9.2 Secured SingleSignon Using NV/AS, GG24-4184


Network Security Involving the NetView Family of Pro-ducts, GG24-3524

Advanced Communications Function Products Installa-tion Guide, GG24-1557

Response Time Data Gathering, GG24-3212

Network Management Reporting Principles and Imple-mentation, GG24-3271

Network Management Reporting Sample Reports,GG24-3272

Network Monitoring Using NPM V1R3, GG24-3337

Network Accounting Using NPM V1R3, GG24-3270

NPM V1R4 New Functions, GG24-3532

MVS Virtual Storage Tuning Cookbook, G320-0597

3270 Information Display System 3274 Control Unit Ref-erence Summary, GX20-1878

3270 Information Display System Data StreamProgrammer’s Reference, GA20-0059

3174 Establishment Controller Terminal User’s Refer-ence for Expanded Functions, GA23-0332

3174 Establishment Controller Character Set Reference,GA27-3831

System/370, 30xx, 4300, 9370 of Industry Systems andApplication Programs, GC20-0379

Dictionary of Computing, SC20-1699.


Index

Numerics3270 null/space handling with virtual terminal 12

AACBNAME

APPL control statement for 68of the pseudo terminal 73VTAM APPL statement for 72

ACBshandling for pseudo terminals 4individual 5restrictions

for individual 73for shared 73

shared 4unique 5

accesscontrol, network and application 27mode 45

accessingCICS/VS using NetView Access Services 40IMS/VS using NetView Access Services 41

accounting 27, 31accounting exit, EMSENPME 165accounting, NetView Access Services Exits 31accounting, NetView Performance Monitor (NPM) 32activating EMSEDVEX, data viewing exitwith ZAP 149administration exit EMSEADEX 132administration record formats, NetView Access

Services 305administrator profiles EMSGAL, calculating disk storage

for 59alerts, sending to NetView 77allocating

a broadcast partitioned data set 66data sets 66

APF authorized 77, 84, 112, 140, 154, 155, 160APPL control statement 68APPL definitions, VTAM

control statement 68defining 71planning 49

APPL statement for NetView Access Services,VTAM 72

applicationaccess control 27connectivity feature, OfficeVision/MVS 176deleting from RACF 122routing table for groups (EMSSRTG) content 315routing table for system (EMSSRTS) content 321

application (continued)session considerations, pass mode 9sessions, total number of users 44

application programming interface, REXX(NVASAPI) 215

CONNECT function 228CONVERT_POS function 229COPY_FIELD_TO_STR function 231COPY_PASSWORD function 233COPY_PS_TO_STR function 235COPY_STR_TO_PS function 237DIAGNOSE function 239DISABLE_AUTOLOG function 243DISCONNECT function 244DISPLAY_PS function 245DISPMSG function 247FIND_FIELD function 248PAUSE function 250QUERY_CURSOR_POS function 252QUERY_FIELD_ATTR function 252QUERY_LOGON function 254QUERY_ORIGIN function 254QUERY_PS_UPDATE function 257QUERY_READ_STATE function 258QUERY_SESSIONS function 259QUERY_TERMINALS function 260QUERY_VARIABLES function 261QUERY_VT_STATUS function 262SEARCH_FIELD function 263SEARCH_PS function 265SEND_3270DS function 269SENDKEY function 266SET_CURSOR_POS function 270SET_SEND_MODE function 271syntax notation used 303

application service routine (ASR) 209array, format of USERDATA 121ASLPLU 82ASR (application service routine) 209Associated LU Table Entries (ASLENT) 82Associated LU Tables (ASLTAB) 82attribute positions on panels, changing foreground color

and highlighting of 94authorized path facility, VTAM 16automatic

logon and logoff exit, EMSEAPAN 141logon and logoff exit, EMSEAPAN, sample 142logon for public groups 83logon procedures 47

automatic logon profiles EMSALLT, calculating diskstorage for 59


auxiliary storage, estimating 58

BBIND user data profiles EMSPLDT, calculating disk

storage for 59BIND user data, using 47broadcast exit, EMSEBXML 145broadcast partitioned data set, allocating 66buffer

freeing a 193getting a 197layout of 210maximum number of 43size of 43used to transfer data 209

BUFFLEN, APPL control statement 68BUFFMAXN, APPL control statement 68

Ccalculating

disk storagefor administrator list profiles EMSGAL 59for automatic logon profiles EMSALLT 59for BIND user data profiles EMSPLDT 59for group application profiles EMSSRTG 58for group profiles EMSGPRF 58for system application profiles EMSSRTS 59for time-controlled messages EMSBROD 59for user profiles EMSSRTU 58

primary storage required, example of 56storage requirements 56

capacity, network 39checking user logon authorization 154CICS/VS, accessing 40CINIT, session request 16class of service name 17codes, message return 106coding installation-wide exit routines 130color and highlighting, changing for attribute positions

on panels 94command

confidential text facility of VTAM 30job EMSZCMDS to ZAP 108modifying NetView Access Services 108SNA SIGNAL 205using the TERMQ operator for load balancing 45

compression, data 11, 46, 316inbound 11, 46, 316outbound 11, 46, 316

concept of the NetView Access Services interface toRACF 111

concept, NetView Access Services profile 305confidential mode 76

CONNECT NVASAPI function 228connecting a terminal to NetView Access Services 15content

of application routing table for groups(EMSSRTG) 315

of application routing table for system(EMSSRTS) 321

of group access list (EMSGAL) 324of group profile table (EMSGPRF) 318of user profile table (EMSSRTU) 309profile 309

control statementsAPPL 68description of 66format of 66preparing 66SERVRTN 70syntax notation used for 303

control, network and application access 27CONVERT_POS NVASAPI function 229COPY_FIELD_TO_STR NVASAPI function 231COPY_PASSWORD NVASAPI function 233COPY_PS_TO_STR NVASAPI function 235COPY_STR_TO_PS NVASAPI function 237cross-region sharing 22cross-system sharing 23customizing

for generic alert interface to NetView 77for Model Terminal Support 82for NetView synergy interface 79NetView Access Services 77NetView Access Services installation-wide exits 129

Ddata

compression 11, 46, 316inbound 11, 46, 316outbound 11, 46, 316

security, user 29stored in RACF, format of 119using BIND user 47

data setsallocating 66VSAM SRTG 51

data viewing exit EMSEDVEX, ZAP to activate 149data viewing exit, EMSEDVEX 149database

synchronization of RACF and NetView Access Ser-vices 126

using an existing RACF 111date and time exit, EMSEDTEX 147date and time exit, sample 148deallocating a session 192defining

a help panel 99


defining (continued)a terminal to NetView Access Services 15logmode table 71NetView Access Services as a VTAM USSTAB

entry 15NetView Access Services as the LOGAPPL for the

terminal 15pseudo LU names 40routine EMSEADEX, implementing the 136VTAM APPL statements 71

DEFMODEN, SERVRTN control statement 71deleting an application from RACF 122description of EMSELGNX 154designing an installation-wide exit routine 130designing and coding an installation-wide exit

routine 130DIAGNOSE NVASAPI function 239different terminal models, support for 7DIRLOGON, APPL control statement 69DISABLE_AUTOLOG NVASAPI function 243DISCONNECT NVASAPI function 244disk storage, calculating

for administrator profiles EMSGAL 59for automatic logon profiles EMSALLT 59for BIND user data profiles EMSPLDT 59for group application profiles EMSSRTG 58for group profiles EMSGPRF 58for system application profiles EMSSRTS 59for time-controlled messages EMSBROD 59for user profiles EMSSTRU 58

dispatching priority 43display sessions, graphic 45DISPLAY_PS NVASAPI function 245DISPMSG NVASAPI function 247

EEMSACCPT job 104, 132EMSALLOC macro 187EMSALPDS job 66EMSBACK1 job 65EMSBACK2 job 65EMSBLOAD job 75EMSCGEN job 61EMSCONF job 76EMSDEALL macro 192EMSEADEX

administration exit 132default fields 135implementing the administration exit routine 136

EMSEAPAN, automatic logon and logoff exit 141EMSEAPAN, sample automatic logon and logoff

exit 142EMSEATTE, inactivity timeout exit 143EMSEBXML, broadcast exit 145

EMSEDTEX, date and time exit 147EMSEDVEX, data viewing exit 149EMSEDVEX, data viewing exit, ZAP to activate 149EMSELGFX, logoff exit 151EMSELGNX, logon authorization exit 154EMSELGNX, sample logon authorization exit 154EMSELNEX, language name exit 161EMSELVEX, language verification exit 164EMSENPME, accounting exit 165EMSEPRPS, printer presetting exit 167EMSESEEX, session establishment exit 171EMSESHRX, shared session exit 177EMSESREX, session reselection exit 178EMSEXIT job 132EMSFBUF macro 193EMSGATTR macro 194EMSGBUF macro 197EMSMODE logmode table 17EMSMSDEF macro 104EMSMSGTB job 104EMSNPM macro 198EMSPMIGJ job 95EMSPRETR, prepare to receive exit 199EMSPROC sample jobEMSRECV macro 200EMSREQTS macro 205EMSRESTO job 75, 76, 108EMSSENDD macro 206EMSSENDE macro 208EMSSRTS, application routing table system 321EMSSRTU, user profile table 309EMSSTART sample job 84EMSSTRT macro 187EMSVLOCK job 75EMSVSAM1 job 66EMSVSAM2 job 66EMSZCMDS zap job for commands 108enabling

the generic alert interface 77the NetView synergy interface 78

errors in changing message text 106establishing a session 187estimating

auxiliary storage 58storage requirements 56

EUSZAP flag-bit area, modifying with ZAP jobEMSVLOCK 75

exampleof a message definition 106of calculating the primary storage required 56

exit sample 133exit, installation-wide

See also installation-wide exit routinedesigning and coding 130EMSEADEX, implementing the administration 136installing an 132

Index 341

exit, installation-wide (continued)NetView Access Services user 129overview of 129

external groups

FFACILITY class profiles, RACF 123field, EMSEASEX default 135fields for parameter list

EMSEADEX, administration exit 136EMSEAPAN, automatic logon and logoff exit 141EMSEATTE, inactivity timeout exit 144EMSEBXML, broadcast exit 145EMSEDTEX, date and time exit 147EMSEDVEX, data viewing exit 149EMSELGFX, logoff exit 152EMSELGNX, logon authorization exit 157EMSELVEX, language verification exit 164EMSENPME, acounting exit 166EMSEPRPD, printer presetting exit 168EMSESEEX, session establishment exit 172EMSESHRX, shared session exit 177EMSESREX, session reselection exit 178

FIND_FIELD NVASAPI function 248format

of data stored in RACF 119of USERDATA array 121

forwarding terminal sessions in pass mode 9freeing a buffer 193function management profile 17functions, NVASAPI (REXX application programming

interface)CONNECT 228CONVERT_POS 229COPY_FIELD_TO_STR 231COPY_PASSWORD 233COPY_PS_TO_STR 235COPY_STR_TO_PS 237DIAGNOSE 239DISABLE_AUTOLOG 243DISCONNECT 244DISPLAY_PS 245DISPMSG 247FIND_FIELD 248PAUSE 250QUERY_CURSOR_POS 252QUERY_FIELD_ATTR 252QUERY_LOGON 254QUERY_ORIGIN 254QUERY_PS_UPDATE 257QUERY_READ_STATE 258QUERY_SESSIONS 259QUERY_TERMINALS 260QUERY_VARIABLES 261QUERY_VT_STATUS 262

functions, NVASAPI (REXX application programminginterface) (continued)

SEARCH_FIELD 263SEARCH_PS 265SEND_3270DS 269SENDKEY 266SET_CURSOR_POS 270SET_SEND_MODE 271syntax notation used 303

Ggaining access

to CICS/VS through NetView Access Services 40to IMS/VS through NetView Access Services 41

GAL group access list table content 324general resource profile, RACF 119generating a message table 104generic alert interface to NetView, enabling 77generic pseudo terminal name 8getting a buffer 197global resource serialization facility 22GPRF group profile table content 318graphic display sessions 45group

access list table (GAL) content 324profile table (GPRF) content 318

group application profiles EMSSRTG, calculating diskstorage for 58

group profiles EMSGPRF, calculating disk storage 58groups

autologon for public 83externalpublic 82

GRS (global resource serialization) 22guidelines

for modifying NetView Access Services panels 91for rewriting message text 103

Hhandling information messages 44help panel, defining a 99

IIDLETIME, APPL control statement 69implementing the administration exit routine

EMSEADEX 136IMS/VS, accessing 41inactivity timeout exit, EMSEATTE 143inbound data compression 11, 46, 316individual ACB restrictions 73individual ACBs 5information messages, handling 44


INISES REXX exec 293initializing

an installation-wide exit routine 165data sets 66

initiating the macro interface 187INPLU, SERVRTN control statement 70INPLU, specifying values for 71input parameters data set

allocating 66copying 66

installationplanning for 49requirements in RACF 123

installation-wide exit routineautomatic logon and logoff 141checking user logon authorization 154definition of 129designing and coding 130installing a 132NetView Access Services 129overview of 129register contents upon entry to 131return codes 131session establishment and termination 165

installation-wide exitscustomizing NetView Access Services 129EMSEADEX 132EMSEAPAN 141EMSEATTE 143EMSEBMXL 145EMSEDTEX 147EMSEDVEX 149EMSELGFX 151EMSELGNX 154EMSELNEX 161EMSELVEX 164EMSENPME 165EMSEPRPS 167EMSESEEX 171EMSESHRX 177EMSESREX 178

installinga new language 163a user-written exit routine 132an installation-wide exit routine, using SMP/E 132logmode table 71

ISTINCLM, VTAM logmode entry table 17

JJCL statements explained 84JES2 or JES3 system printer 18job

control statements explained 84EMSACCPT 104, 132EMSALPDS 66

job (continued)EMSBACK1 65EMSBACK2 65EMSBLOAD 75EMSCGEN 61EMSCONF 76EMSEXIT 132EMSMSGTB 104EMSPMIGJ 95EMSRESTO 75, 76, 108EMSSTART sample 84EMSVLOCK 75EMSVSAM1 66EMSVSAM2 66EMSZCMDS ZAP 108

Llanguage

installing a new 163name exit, EMSELNEX 161name exit, sample 161verification exit, EMSELVEX 164verification exit, sample 165

layout of a buffer 210layout of parameter list

for &variables area of EMSESEEX, session estab-lishment exit 175

for EMSEADEX, administration exit 139for EMSEAPAN, automatic logon and logoff

exit 141for EMSEATTE, inactivity timeout exit 145for EMSEBXML, broadcast exit 146for EMSEDTEX, date and time exit 148for EMSEDVEX, data viewing exit 150for EMSELGFX, logoff exit 153for EMSELGNX, logon authorization exit 159for EMSELVEX, language verification exit 165for EMSENPME, accounting exit 167for EMSEPRPS, printer presetting exit 170for EMSESEEX, session establishment exit 174for EMSESHRX, shared session exit 177for EMSESREX, session reselection exit 179

LCICS REXX exec 287link pack area 43LMODNAME, SERVRTN control statement 70LMPEO (Large Message Performance Enhancement

Outbound) option 16load balancing

session 36using EMSESEEX for session 176

load balancing, using the TERMQ operator commandfor 45

locating a NetView Access Services panel 89LOGAPPL for the terminal, defining NetView Access

Services as the 15

Index 343

LOGAPPL operand 15, 27logmode

considerations for printers 18entry analysis 16table, installing the 71

logmode table, defining a 71logoff exit, EMSELGFX 151logoff exit, sample 154logon

authorization exit, EMSELGNX 154authorization exit, EMSELGNX, sample 154procedures, automatic 47

LTSO REXX exec 281LVM REXX exec 276

Mmacro operands, syntax notation used for 303macros

deallocate a session, EMSDEALL 192free a buffer, EMSFBUF 193get a buffer, EMSGBUF 197initiate the macro interface, EMSSTRT 187NetView Performance Monitor, EMSNPM 198operand descriptions 186prepare to receive, EMSPRETR 199receive information, EMSRECV 200request a session, EMSALLOC 187request to send, EMSREQTS 205return information about a session,

EMSGATTR 194send data, EMSSENDD 206send error response, EMSSENDE 208summary 186types of interface 185

matching a real terminal name with a pseudo terminalname 8

maximumnumber of buffers, buffer size 43sessions, pseudo terminal prefix 6value, increasing or decreasing the 6

MAXLUNO, SERVRTN control statement 70MDLPLU 82message

definition, example of a 106handling information 44return codes 106specifying 104table, generating a 104text, rewriting 103

message processor return codes 106mode, access 45model name entries (MDLENT) 82model name tables (MDLTAB) 82model terminal support, customizing for 82

modifyingEUSZAP flag-bit area to activate data viewing exit,

EMSEDVEX 149EUSZAP flag-bit area with ZAP job EMSVLOCK 75NetView Access Services commands 108NetView Access Services panels 89source panel 89, 91

MSGLEVEL, APPL control statement 70multilingual support 107

NNAME, SERVRTN control statement 70NetView Access Services

concept of interface to RACF 111control statements 66customizing 77exits, accounting 31gaining access

to CICS/VS through 40to IMS/VS through 41

JCL statements 84modifying panels 89performance considerations 21preparing for startup 84profile concept 305resource usage 43REXX application programming interface

(NVASAPI) 215storage calculations 56

NetView Performance Monitor (NPM)considerations when used with the NSI 38description 32, 79used for accounting 32

NetView synergy interface (NSI)considerations 38enabling 79used with NetView Performance Monitor (NPM) 32,

78NetView, sending alerts to 77network and application access control 27network capacity 39network operations 35new language, installing a 163NPM (NetView Performance Monitor)

considerations when used with the NSI 38description 32used for accounting 32

NSI (NetView synergy interface)considerations 38enabling 78used with NetView Performance Monitor (NPM) 32

null/space handling (3270) with virtual terminal 12number of users and application sessions, total 44NVASAPI (REXX application programming

interface) 215


NVASAPI functionsCONNECT 228CONVERT_POS 229COPY_FIELD_TO_STR 231COPY_PASSWORD 233COPY_PS_TO_STR 235COPY_STR_TO_PS 237DIAGNOSE 239DISABLE_AUTOLOG 243DISCONNECT 244DISPLAY_PS 245DISPMSG 247FIND_FIELD 248PAUSE 250QUERY_CURSOR_POS 252QUERY_FIELD_ATTR 252QUERY_LOGON 254QUERY_ORIGIN 254QUERY_PS_UPDATE 257QUERY_READ_STATE 258QUERY_SESSIONS 259QUERY_TERMINALS 260QUERY_VARIABLES 261QUERY_VT_STATUS 262SEARCH_FIELD 263SEARCH_PS 265SEND_3270DS 269SENDKEY 266SET_CURSOR_POS 270SET_SEND_MODE 271syntax notation used 303

OOfficeVision, application connectivity feature 176operator command for load balancing, using the

TERMQ 45outbound data compression 11, 46, 316overview of installation-wide exit routines 129

Ppage fixing 43panels

changing fforeground color and highlighting of attri-bute positions on 94

how to define NetView Access Services help 99locating source 89modifying 89, 91

parallel sessions 4parameter list fields for installation-wide exit

EMSEADEX, administration 136EMSEAPAN, automatic logon and logoff 141EMSEATTE, inactivity timeout 144EMSEBXML, broadcast 145EMSEDTEX, date and time 147

parameter list fields for installation-wide exit (continued)EMSEDVEX, data viewing 149EMSELGFX, logoff 152EMSELGNX, logon authorization 157EMSELVEX, language verification 164EMSENPME, accounting 166EMSEPRPS, printer presetting 168EMSESEEX, session establishment 172EMSESHRX, shared session 177EMSESREX, session reselection 178

parameter list, layout ofSee layout of parameter list

pass modeapplication session considerations 9forwarding terminal sessions in 9return if the terminal is switched off 10

passticket, RACF 31PASSWORD, APPL control statement 68PAUSE NVASAPI function 250performance considerations NetView Access

Services 21planning

for installation 49VTAM APPL definitions 49

power failure 10prepare to receive, EMSPRETR 199preparing for NetView Access Services startup 84primary program operator interface task (PPT) 43primary storage required, example of calculating

the 56printer

logmode considerations for 18presetting exit, EMSEPRPD 167priority, dispatching 43system JES2 or JES3 18VTAM connected to NetView Access Services 18

profileconcept of 305content of 309function management 17location, VSAM 21RACF processed by NetView Access Services 123record field relationship 307structure of 306table (GPRF) content, group 318table (SRTU) content, user 309transmission services 17types 305updating 307

PSERVIC field 16pseudo terminal

ACB handling for 4name, matching a real terminal name with a 8prefix and maximum sessions 6pseudo terminal name, generic 8

Index 345

public groups 82public groups, autologon for 83

QQUERY_CURSOR_POS NVASAPI function 252QUERY_FIELD_ATTR NVASAPI function 252QUERY_LOGON NVASAPI function 254QUERY_ORIGIN NVASAPI function 254QUERY_PS_UPDATE NVASAPI function 257QUERY_READ_STATE NVASAPI function 258QUERY_SESSIONS NVASAPI function 259QUERY_TERMINALS NVASAPI function 260QUERY_VARIABLES NVASAPI function 261QUERY_VT_STATUS NVASAPI function 262

RRACF

concept of the NetView Access Services interfaceto 111

database, using an existing 111deleting an application from 122FACILITY class profiles 123format of data stored in 119format of USERDATA array 121general resource profile 119installation requirements in 123passticket 31profiles processed by NetView Access

Services 123RCICSINI REXX exec 289, 292RCONNECT, APPL control statement 69real terminal name with a pseudo terminal name,

matching a 8RECEIVE macro, VTAM 16receiving information 200record field relationship, profile 307record formats, NetView Access Services

administration 305registers upon entry to installation exit routine 131requirements

auxiliary storage 58for user-written programs 130, 185storage 56

resource usage, NetView Access Services 43response time 40response time monitor (RTM) considerations 37response time, user 40restrictions

for individual ACBs 73for shared ACBs 73for user-written programs 130, 185

return codesEMSEADEX 140EMSEAPAN 142

return codes (continued)EMSEDTEX 148EMSELGFX 153EMSELVEX 165EMSENPME 167from installation-wide exit routine 131from message processor 106message 106

return if the terminal is switched off, pass mode 10returning information about a session 194rewriting message text, guidelines for 103REXX (NVASAPI) application programming

interface 215CONNECT function 228CONVERT_POS function 229COPY_FIELD_TO_STR function 231COPY_PASSWORD function 233COPY_PS_TO_STR function 235COPY_STR_TO_PS function 237DIAGNOSE function 239DISABLE_AUTOLOG function 243DISCONNECT function 244DISPLAY_PS function 245DISPMSG function 247FIND_FIELD function 248PAUSE function 250QUERY_CURSOR_POS function 252QUERY_FIELD_ATTR function 252QUERY_LOGON function 254QUERY_ORIGIN function 254QUERY_PS_UPDATE function 257QUERY_READ_STATE function 258QUERY_SESSIONS function 259QUERY_TERMINALS function 260QUERY_VARIABLES function 261QUERY_VT_STATUS function 262SEARCH_FIELD function 263SEARCH_PS function 265SEND_3270DS function 269SENDKEY function 266SET_CURSOR_POS function 270SET_SEND_MODE function 271syntax notation used 303

REXX exec samplesINISES 293LCICS 287LTSO 281LVM 276RCICSINI 289ROFFICE 297RTSOINI 284RVMINI 278RXESCT 292RXLOGRP 273

ROFFICE REXX exec 297


routine, designing and coding an installation-wideexit 130

routing table(EMSSRTS) content, application 321for groups (EMSSRTG) content, application 315

RTSOINI REXX exec 284RVMINI REXX exec 278RXLOGRP REXX exec 273

Ssample installation-wide exit routines

administration exit 133automatic logon and logoff exit 142date and time exit 148language name exit for 161language verification exit 165logoff exit 154logon authorization exit 154session establishment exit 176

sample REXX execsINISES 293LCICS 287LTSO 281LVM 276RCICINI 289ROFFICE 297RTSOINI 284RVMINI 278RXESCT 292RXLOGRP 273

sample startup job, EMSSTART 84SEARCH_FIELD NVASAPI function 263SEARCH_PS NVASAPI function 265security 27security, user data 29SEND macro VTAM 16SEND_3270DS NVASAPI function 269sending

alerts to NetView 77data to remote LU 206error response 208

SENDKEY NVASAPI function 266SERVRTN control statement 70session

considerations, pass mode application 9establishment exit, EMSESEEX 171establishment exit, sample 176graphic display 45in pass mode, forwarding terminal 9load balancing 36load balancing, using EMSESEEX for 176parallel 4pseudo terminal prefix and maximum 6request CINIT 16single 5

session (continued)total number of users and application 44

session reselection exit, EMSESREX 178SET_CURSOR_POS NVASAPI function 270SET_SEND_MODE NVASAPI function 271shared

ACB restrictions 73ACBs 4session exit, EMSESHRX 177

SIMLOGON, APPL control statement 69single sessions 5SMP/E, using to install an installation-wide exit

routine 132SNA SIGNAL command 205source panel

changing foreground color and highlighting of attri-bute positions on 94

locating the 89modifying the 89

specifying messages 104SRTG

application routing table for groups 315data sets, VSAM 51

storagecalculations 56estimating auxiliary 58estimating requirements 56

storage required, example of calculating theprimary 56

storage requirement, virtualstorage used by NetView Access Services, virtual 55structure, profile 306support for different terminal models 7synchronization of RACF and NetView Access Services

databases 126syntax notation used for

control statements 303macro operands 303REXX application programming interface

(NVASAPI) 303system application profiles EMSSRTS, calculating disk

storage for 59system printer, JES2 or JES3 18

Ttable

(EMSGAL) content, the group access list 324(EMSGPRF) content, group profile 318(EMSSRTG) content, application routing for

groups 315(EMSSRTS) content, application routing 321(EMSSRTU) content, user profile 309logmode EMSMODE 17

terminalACB handling for pseudo 4

Index 347

terminal (continued)defining NetView Access Services as the LOGAPPL

for the 15models, support for different 7prefix and maximum sessions, pseudo 6sessions in pass mode, forwarding 9terminal name, generic pseudo 8

termination of an installation exit routine 165TERMQ operator command for load balancing, using

the 45time-controlled messages EMSBROD, calculating disk

storage for 59time, user response 40transmission services profile 17types, profile 305

Uunique ACBs 5updating NetView Access Services profiles 307user

data security 29profile table (SRTU) content 309translated languages 107

user exitsSee installation-wide exits

user profiles EMSSRTU, calculating disk storagefor 58

user-written programsrequirements 130, 185restrictions 130, 185

USERDATA array, format of 121users and application sessions, total number of 44USSTAB entry, defining NetView Access Services as a

VTAM 15USSTAB table 15, 27

Vvariables, ampersand, in installation-wide exit 155variables, EMSEADEX 133verifying user logon authorization 154VGACCTYP 315VGALATTR 324VGALGID 324VGALLUPD 324VGALOG 315VGALUID 324VGAMRI 316VGCSELP 315VGDACOM 316VGDAICL 317VGDAICO 317VGDAIHI 317VGDAIID 317

VGDAIRO 317VGDAITX 317VGGRPID 315VGJKEY 315VGLOGPRF 315VGLUPD 317VGPACC 318VGPCMDK 319VGPCMDP 319VGPCPYFB 319VGPCPYFE 319VGPCPYTB 319VGPGRPID 318VGPGTYPE 319VGPLUPD 320VGPMLU 319VGPMSES 319VGPPRKEY 320VGPPRT 319VGPRESP 319VGPREXX 320VGPRTKEY 319VGPRXLF 320VGREXXLF 317VGREXXLN 317VGSEQNO 316VGSERVER 315VGSHR 316VGSYSID 315VGVIT 317virtual storage requirementvirtual storage used by NetView Access Services 55virtual terminal

3270 null/space handling 12description of 10write optimization 11

VSACBTYP 323VSACCTYP 322VSALOG 322VSAM

profile data sets 66profile data sets, allocating and initializing 66profile location 21

VSAREC 322VSASITIM 323VSFBNAME 323VSITIME 322VSLUPD 323VSMSESNO 322VSSHR 323VSSYSID 321VSSYSLOC 321VSTPRE 321VSTRANS 321VTAM

APPL definitions, planning 49


VTAM (continued)APPL statement for NetView Access Services 72application statements, defining 71application statements, defining the 72authorized path facility 16confidential text facility of 30Large Message Performance Enhancement Out-

bound (LMPEO) option 16LOGAPPL operand 15logmode entry table ISTINCLM 17printer connected to NetView Access Services 18RECEIVE macro 16SEND macro 16SRTG data sets 51USSTAB entry, defining NetView Access Services as

a 15USSTAB table 15

VUAACNO 311VUACCTYP 311VUALPRF 311VUAMRI 313VUANPW 310VUAOPW 310VUAPWD 310VUAUID 310VUAVAR1 311VUAVAR6 311VUCKEY 312VUCOPREF 313VUDAIID 313VUDGIND 311VUDSIND 311VUEKEY 312VUGRPID 309VUJKEY 312VULOGPRF 311VULP1D 310VULP2D 310VULUNAME 310VUPRTKEY 314VUPRTNAM 313VURECAUT 311VUSEQNO 312VUSERVER 310VUSHR 313VUSUID 309VUTERMAS 311

Wworking storage 56write optimization with virtual termanal 11

ZZAP job

EMSVLOCK to modify EUSZAP flag-bit area 75EMSZCMDS for commands 108to activate data viewing exit EMSEDVEX 149

Index 349

Communicating Your Comments to IBM

NetView Access Services (MVS/ESA)CustomizationVersion 2 Release 1

Publication No. SH19-4502-00

If you especially like or dislike anything about this book, please use one of the methodslisted below to send your comments to IBM. Whichever method you choose, make sure yousend your name, address, and telephone number if you would like a reply.

Feel free to comment on specific errors or omissions, accuracy, organization, subject matter,or completeness of this book. However, the comments you send should pertain to only theinformation in this manual and the way in which the information is presented. To requestadditional publications, or to ask questions or make comments about the functions of IBMproducts or systems, you should talk to your IBM representative or to your IBM authorizedremarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distributeyour comments in any way it believes appropriate without incurring any obligation to you.

If you are mailing a readers' comment form (RCF) from a country other than the UnitedStates, you can give the RCF to the local IBM branch office or IBM representative forpostage-paid mailing.

� If you prefer to send comments by mail, use the RCF at the back of this book.

� If you prefer to send comments by FAX, use this number:

39+6+5966+2077

Make sure to include the following in your note:

� Title and publication number of this book� Page number or topic to which your comment applies.

Help Us Help You!

NetView Access Services (MVS/ESA)CustomizationVersion 2 Release 1

Publication No. SH19-4502-00

We hope you find this publication useful, readable and technically accurate, but only you can tell us! Yourcomments and suggestions will help us improve our technical publications. Please take a few minutes tolet us know what you think by completing this form.

Specific Comments or Problems:

Please tell us how we can improve this book:

Thank you for your response. When you send information to IBM, you grant IBM the right to use ordistribute the information without incurring any obligation to you. You of course retain the right to use theinformation in any way you choose.

Name Address

Company or Organization

Phone No.

Overall, how satisfied are you with the information in this book? Satisfied Dissatisfied

Ø Ø

How satisfied are you that the information in this book is: Satisfied Dissatisfied

Accurate Ø ØComplete Ø ØEasy to find Ø ØEasy to understand Ø ØWell organized Ø ØApplicable to your task Ø Ø

Cut or FoldAlong Line

Cut or FoldAlong Line

Help Us Help You !SH19-4502-00 IBM

Fold and Tape Please do not staple Fold and Tape

PLACEPOSTAGESTAMPHERE

NetView Access Services Information DevelopmentRome Tivoli LaboratoryIBM Italia S.p.A.Via Sciangai, 5300144 RomeItaly

Fold and Tape Please do not staple Fold and Tape

SH19-4502-00

IBM

Program Number: 5695-036

Printed in Denmark by IBM Danmark A/S

SH19-45ð2-ðð

Date post:	23-Apr-2018
Category:	Documents
Upload:	dangdan
View:	320 times
Download:	15 times

Customization - publib.boulder.ibm.compublib.boulder.ibm.com/tividd/td/job/emsc1mst/en... ·...

Documents