IBM Connect:Direct for z/OS6.2

Documentation

IBM

This edition applies to Version 6 Release 2 of IBM® Connect:Direct and to all subsequent releases and modifications untilotherwise indicated in new editions.© Copyright International Business Machines Corporation 1993, 2021.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Chapter 1. Release Notes.......................................................................................1IBM Connect:Direct for z/OS Release Notes............................................................................................... 1

Hardware and Software Requirements..................................................................................................1POSIX Environment and System Libraries.............................................................................................1MBCS Transfers...................................................................................................................................... 2License Key File...................................................................................................................................... 2What's New in This Release................................................................................................................... 2

Connect:Direct for z/OS Special Product Considerations........................................................................... 4Other Product Considerations................................................................................................................6Transmission Control Queue Considerations........................................................................................ 7Miscellaneous Considerations............................................................................................................... 7UDT Special Considerations................................................................................................................... 8Connect:Direct Secure Plus Considerations.......................................................................................... 8Connect:Direct File Agent Special Considerations..............................................................................10

Upgrading IBM Connect:Direct..................................................................................................................10Migrating an Existing Network Map..................................................................................................... 11Migrating existing STATS files.............................................................................................................. 12Using the DGA#FXAL REXX Exec.........................................................................................................12Migrating CICS from Prior Releases.....................................................................................................22Upgrading Connect:Direct File Agent.................................................................................................. 23

Chapter 2. Configuration Guide............................................................................ 25Before you Install.......................................................................................................................................25

Installation Requirements................................................................................................................... 25Virtual Storage Requirements..............................................................................................................31Preparing TCP/IP Configuration (Optional)..........................................................................................33Security Planning..................................................................................................................................35Planning for Parallel Sessions and Process Recovery.........................................................................37Planning the Network Map...................................................................................................................37Planning for Disaster Recovery Testing............................................................................................... 38Planning for Connect:Direct File Agent................................................................................................38Traces in Startup JCL............................................................................................................................38

Configuring IBM Connect:Direct for z/OS..................................................................................................39Define the IBM Connect:DirectVSAM Files..........................................................................................39Define VTAM Resources....................................................................................................................... 40Building a Test IBM Connect:Direct Configuration (optional)............................................................. 40Building the Initialization Parameter File............................................................................................ 41Installing the ISPF IUI......................................................................................................................... 42Start IBM Connect:Direct..................................................................................................................... 51Signing On to IBM Connect:Direct....................................................................................................... 53Customizing the Product...................................................................................................................... 53

VTAM Definitions........................................................................................................................................53Defining APPLID of Local DTF.............................................................................................................. 54APPLID for IUI and Batch Sessions..................................................................................................... 55VTAM and NCP Parameters..................................................................................................................58VTAM Definitions for Full Networking IBM Connect:Direct.................................................................61Network or Domain Name in Cross-Domain Network.........................................................................63

Optional Configuration Tasks.....................................................................................................................65Customizing the Product...................................................................................................................... 65Customizing the Spool Transfer Feature..............................................................................................70

iii

Customizing VPS/CDI........................................................................................................................... 70HP OpenView for SNMP Traps Customization..................................................................................... 71NetView for SNMP Customization........................................................................................................72Configuring IBM Connect:Direct without SNA Support.......................................................................73Overriding IBM Connect:Direct for z/OS Default Language Environment Run-Time Options............75

IBM Connect:Direct Enqueue Resource Management............................................................................. 77Initialization Errors.................................................................................................................................... 78

Overriding IBM Connect:Direct Initialization Parameters...................................................................78Initialization Errors...............................................................................................................................79

Chapter 3. CICS Administration and User Guide....................................................89CICS Interface............................................................................................................................................89

CICS Screen Conventions.....................................................................................................................91About the IBM Connect:Direct for z/OS CICS Documentation............................................................92

Configuring the CICS Interface..................................................................................................................92Activate the CICS Component - Optional............................................................................................ 92Build the CICS Configuration File through ISPF.................................................................................. 93Load IBM Connect:Direct CICS Option into the CICS System Definition............................................95Customize the CICS Interface Overview............................................................................................. 95Tune the CICS Interface.......................................................................................................................97

Using the Administration System.............................................................................................................. 98The Administration Primary Menu....................................................................................................... 99

Maintaining Configuration Information...................................................................................................100Configuration Categories................................................................................................................... 101Accessing the Configuration Screen.................................................................................................. 101Updating the Control Record............................................................................................................. 102Updating DTF Node Records..............................................................................................................106Updating Network Node Records...................................................................................................... 107

Working with the Administration Interface.............................................................................................108Operating the CICS Interface............................................................................................................ 109

Viewing Node Status................................................................................................................................111Viewing the Work Queue Screen....................................................................................................... 113

Signon Defaults........................................................................................................................................114Accessing the Signon Defaults Screen.............................................................................................. 114

Viewing User Status.................................................................................................................................115Operational Considerations.....................................................................................................................116

Signing On to Multiple DTFs from a Single IUI.................................................................................. 116Signing On to a Single DTF from Multiple IUI Facilities.................................................................... 116Performing an Immediate or Uncontrolled Shutdown......................................................................117Restarting Task ABENDS....................................................................................................................117Accessing Accounting and Logging Information............................................................................... 117Using the Extended Submit Facility (ESF)......................................................................................... 118Specifying IBM Connect:Direct Signon Parameters..........................................................................118About IBM Connect:Direct CICS Data............................................................................................... 119

Signing On and Off CICS.......................................................................................................................... 120Signing On...........................................................................................................................................120Using the Primary Menu.....................................................................................................................122Using the SN Option for Multiple Terminal Signon............................................................................ 122Updating Your Signon Defaults.......................................................................................................... 123Using the ESF Session Mode Option..................................................................................................124Signing Off.......................................................................................................................................... 124

About Copying Files................................................................................................................................. 125Generating a Copy File from Connect:Direct for CICS...................................................................... 126Copying a File from Your Node to Your Node.................................................................................... 131

Building, Modifying, and Submitting Processes through CICS...............................................................132Submit Process Screen...................................................................................................................... 132Security Override Screen................................................................................................................... 134

iv

Selecting a Process through CICS...........................................................................................................135Determining the Status of a Submitted Process............................................................................... 135Viewing Summary Information.......................................................................................................... 137Viewing Process Detail.......................................................................................................................138

Selecting Statistics through CICS........................................................................................................... 142Viewing Process Statistics................................................................................................................. 142Viewing Statistics Summary Information..........................................................................................144

Displaying CICS Messages...................................................................................................................... 145Displaying Product Messages............................................................................................................ 145Displaying the Last Message..............................................................................................................146

Displaying Your CICS User Profile........................................................................................................... 147CICS Messages and Problem Isolation................................................................................................... 148

Product Messages.............................................................................................................................. 148Problem Isolation...............................................................................................................................155

Chapter 4. Administration Guide........................................................................ 157Basic System Administrative...................................................................................................................157

IBM Connect:Direct Native Command Structure.............................................................................. 159Managing Tasks.................................................................................................................................. 161Connect:Direct Secure Plus Commands............................................................................................166Displaying Initialization Parameter Settings..................................................................................... 168Displaying IBM Connect:Direct/Plex Status...................................................................................... 172Displaying Module Maintenance History........................................................................................... 173Stopping IBM Connect:Direct............................................................................................................ 175Suspending and Resuming Quiesce and Trace Settings................................................................... 177Global Signon Defaults.......................................................................................................................183

Implementing Security............................................................................................................................186Security Exits......................................................................................................................................187SIGNON Command Sequence........................................................................................................... 188Implementing Security Exits..............................................................................................................191IBM Connect:Direct Secure Point-of-Entry....................................................................................... 210Trusted Node Security........................................................................................................................212Implementing a CA-ACF2 Environment............................................................................................ 213Implementing an IBM RACF Environment........................................................................................ 214Implementing a CA-TOP SECRET Environment................................................................................ 215Configuring Firewall Navigation......................................................................................................... 216Troubleshooting Security Errors........................................................................................................ 218

Maintaining User Authorization...............................................................................................................221Authorization File............................................................................................................................... 222

Certificate-based Authentication for Client Connections.......................................................................234Configuring API certificate authentication........................................................................................ 235

Maintaining the Type File.........................................................................................................................235Overriding File Attributes...................................................................................................................236INSERT TYPE and UPDATE TYPE Commands................................................................................... 236DELETE TYPE Command....................................................................................................................245SELECT TYPE Command.................................................................................................................... 246

Maintaining the Network Map................................................................................................................. 248Local Node Entry................................................................................................................................ 248When to Define the Local Node as the Adjacent Node..................................................................... 250Node Usage Information Maintenance..............................................................................................269Netmap Conversion and Fallback...................................................................................................... 270API Signons........................................................................................................................................ 271Examples of Local and Adjacent Node Records................................................................................272How to Update the Network Map...................................................................................................... 277Viewing the Network Map.................................................................................................................. 285

Configuring a IBM Connect:Direct/Plex Environment............................................................................ 285A New IBM Connect:Direct/Plex Environment..................................................................................287

v

Advanced IBM Connect:Direct:/Plex Configuration Considerations................................................ 290Converting an Existing Stand-Alone Server to a Plex Environment..................................................293Converting Two Existing Stand-Alone Server Systems to a Plex Environment................................ 296Additional IBM Connect:Direct/Plex Configuration Examples..........................................................301Connect:Direct Workload Recovery...................................................................................................306

Configuring Extended Recovery.............................................................................................................. 307Setting Up Extended Recovery for a IBM Connect:Direct/Stand-Alone Server............................... 307Setting Up Extended Recovery for a IBM Connect:Direct/Plex Environment...................................308

Configuring Process Library support....................................................................................................... 310Operations on Process Library support............................................................................................. 310

Configuring Integrated File Agent Support............................................................................................. 311Installing File Agent........................................................................................................................... 311Configuring File Agent........................................................................................................................312Reinstalling File Agent....................................................................................................................... 312Starting and stopping File Agent....................................................................................................... 313

Configuring SNMP Support......................................................................................................................314Identifying Trap Variables..................................................................................................................314Setting Up SNMP................................................................................................................................ 320

IBM Connect:Direct Exits........................................................................................................................ 322Statistics Exit......................................................................................................................................323Submit Exit......................................................................................................................................... 330ALLOCATION EXIT..............................................................................................................................340I/O Exit................................................................................................................................................346Data Exit............................................................................................................................................. 350WLM Exit.............................................................................................................................................355Tapemount Exit.................................................................................................................................. 356Process Exit for Testing (DGAXPRCT)................................................................................................357

Custom Messages in the Message Library.............................................................................................. 365Message IDs....................................................................................................................................... 366

Customizing Submit Screens...................................................................................................................366Step 1 - Modify the Existing Menu DGA@SM03................................................................................ 367Step 2 - Define General Purpose Process......................................................................................... 367Step 3 - Provide a New Submit Screen..............................................................................................368

Administering Statistics...........................................................................................................................372Tools to Monitor the Statistics Facility...............................................................................................372Optimizing Statistics Files..................................................................................................................374Change the File Pair Configuration.................................................................................................... 375Archiving Statistics.............................................................................................................................376Displaying the Status of the Statistics Logging Facility.....................................................................384Displaying the Statistics Archive File Directory.................................................................................385Switching the Statistics File Pair........................................................................................................388Recording Statistics for Specific Record Types................................................................................. 388Notifying IBM Connect:Direct of Statistics File Archival...................................................................389

Managing the Transmission Control Queue............................................................................................ 390Configure the TCQ.............................................................................................................................. 390How to Troubleshoot the TCQ............................................................................................................391

Supporting DBCS and MBCS....................................................................................................................394Overview of DBCS...............................................................................................................................394Translation Tables.............................................................................................................................. 395Customize Translation Tables............................................................................................................395Alternate Logic Applied to DBCS and SBCS Translation (LOGIC =B | (B,RC) )..................................404MBCS Conversions............................................................................................................................. 406

Performance Tuning................................................................................................................................ 407Analyzing TCP/IP Performance..........................................................................................................407How to Improve BSAM Data Transfer Rates......................................................................................409Increasing Throughput and Decreasing CPU Utilization...................................................................410

Using zFBA for File Transfer.................................................................................................................... 416How zFBA works with IBM Connect:Direct....................................................................................... 416

vi

Special Considerations when using zFBA with IBM Connect:Direct................................................ 416zFBA Error Handing............................................................................................................................417

Using zEDC with IBM Connect:Direct......................................................................................................418Using PDSE Version 2 with IBM Connect:Direct..................................................................................... 418

Propagation........................................................................................................................................ 419Limitations..........................................................................................................................................419Copy all member generations............................................................................................................419

Using PS-E Version 2 with IBM Connect:Direct...................................................................................... 419Propagation........................................................................................................................................ 420Version of Created PS-E Data Set ..................................................................................................... 420Limitations..........................................................................................................................................420

Simultaneous Session Reporting and Asset Tracking Reporting........................................................... 420SMF Record Layout............................................................................................................................ 421H2 and HW Statistic Record layout....................................................................................................423Reporting............................................................................................................................................ 424

Isolating Problems...................................................................................................................................425Providing Dumps to Customer Support............................................................................................. 426Resolving the Problem....................................................................................................................... 430Reviewing IBM Connect:Direct Messages and Sense Codes............................................................430Examine Output from Select Commands.......................................................................................... 432Verify File Attributes.......................................................................................................................... 433Common Errors.................................................................................................................................. 434Diagnostic Tools................................................................................................................................. 444

Global Initialization Parameters............................................................................................................. 457ABEND.CODES.NODUMP=(ABEND code list).................................................................................... 457ABEND.RUNTASK = (DUMP | ABEND.CODES.NODUMP)................................................................... 458ALLOC.CODES = (allocation errors)................................................................................................... 458ALLOC.MSG.LEVEL = INFO | WARN | SEVERE................................................................................... 459ALLOC.RETRIES = number of retries................................................................................................. 460ALLOC.WAIT = hh:mm:ss................................................................................................................... 460ALLOCATION.EXIT = modname.........................................................................................................460CDPLEX = NO | YES............................................................................................................................ 460CDPLEX.MAXSERVER = maximum number of servers | 4.................................................................460CDPLEX.TIMER = 5 | number of minutes...........................................................................................460CDPLEX.WLM.GOAL = (NO | YES, exitname)......................................................................................460CHECK.CERT.EXPIRE = NO | YES....................................................................................................... 461CHECK.CERT.EXPIRE.TIME = 00:00:00 | HH:MM:SS........................................................................ 461CHECK.CERT.EXPIRE.WARN.DAYS = 30 | nnn...................................................................................461CKPT = nK | nM...................................................................................................................................461CKPT.DAYS = number of days............................................................................................................ 462CKPT.MODE = (RECORD | BLOCK BLOCK | RECORD PDS | NOPDS NOPDS | PDS VSAM |

NOVSAM VSAM | NOVSAM)...........................................................................................................462COMPRESS.EXT = ALLOW | DISALLOW............................................................................................. 463COMPRESS.NEGO.FAIL = STEP | PROCESS.......................................................................................463COMPRESS.NETMAP.OVERRIDE = ALLOW | DISALLOW................................................................... 463COMPRESS.STD = ALLOW | DISALLOW............................................................................................. 464CONFIRM.COLD.START = YES | NO....................................................................................................464CRC = (OFF | ON, YES, No)................................................................................................................. 464CTCA = NO | YES.................................................................................................................................464CTCA.TIMER = number of seconds....................................................................................................465DATEFORM = (MDY | DMY | YMD | YDM)............................................................................................465DEBUG = nnnnnnnn........................................................................................................................... 466DEFAULT.PERMISS = (text_permissions | 644, binary_permissions | 755).....................................466DESC.CRIT = (descriptor code)..........................................................................................................467DESC.NORM = (n,n,...)........................................................................................................................ 467DESC.TAPE = (n,n,...).......................................................................................................................... 467DSNTYPE = YES | NO..........................................................................................................................467ECZ.COMPRESSION.LEVEL = 1 | n.....................................................................................................468

vii

ECZ.MEMORY.LEVEL = 4 | n............................................................................................................... 468ECZ.WINDOWSIZE = 13 | nn..............................................................................................................468ESF.WAIT = hh:mm:ss........................................................................................................................468EXPDT = (TT,DD,TD,DT) (if multiple values EXPDT = TT | DD | TD | DT | ALL | NONE (if only one

value).............................................................................................................................................469EXTENDED.RECOVERY = NO | YES.................................................................................................... 470EXTERNAL.STATS.ALLOWED = NONE|ALL|(rec_type,app_descr)|list.............................................. 470FASP = ( NO | SSP , NO | SSP)............................................................................................................ 471FASP.FILESIZE.THRESHOLD = nnn | nK | nM | nG.............................................................................471FASP.BANDWIDTH = nnn | nK | nM | nG............................................................................................ 471FASP.POLICY = FAIR | FIXED | HIGH | LOW...................................................................................... 471FIPS = NO | YES..................................................................................................................................471FILE.AGENT.PATH = file agent absolute directory path....................................................................472GDGALLOC = GENERATION | DSNAME..............................................................................................472GDGENQ = YES|NO............................................................................................................................ 474IMMEDIATE.SHUTDOWN = I | R | (I, nnn | 60) | (R, nnn | 60)...........................................................474INITPARM.BACKUP = member..........................................................................................................475INVOKE.ALLOC.EXIT = SEND|RECV|BOTH........................................................................................475INVOKE.ALLOC.EXIT.ON.RESTART = YES|NO................................................................................... 475INVOKE.SPOE.ON.SNODEID = NO|YES.............................................................................................475MAX.AGE = (nnn , * | *(nnn) | ALL | ALL(nnn) | status_type | status_type (nnn) , list)......................476MAX.AGE.TOD = time......................................................................................................................... 477MAXPRIMARY = number of PNODE sessions....................................................................................477MAXPROCESS = number of executing PNODE and SNODE Processes............................................ 477MAXRETRIES = number of retries..................................................................................................... 478MAXSECONDARY = number of SNODE sessions...............................................................................478MAXSTGIO = maximum storage used for sequential data set transfers for system-determined

NCP, maximum I/O storage for user-specified NCP)................................................................... 478MAX.TAPE = number of tape Processes | NONE............................................................................... 479MAXUSERS = number of users.......................................................................................................... 479MCS.CLIST = console operator CLIST library file name.................................................................... 479MCS.SIGNON = (SIGNON USERID = (user ID,password))................................................................ 480MULTI.COPY.STAT.RCD=not set | CT | MC | M2..................................................................................480NETMAP.CHECK = NO | (ALL | TCP, ALL | BOTH | NODENAME, FAIL | WARN | PASS)...................... 481NETMAP.CHECK.ON.CALL= YES | NO.................................................................................................482NODE.QUIESCE.OFF = NODENAME...................................................................................................482NODE.QUIESCE.ON = NODENAME.................................................................................................... 482NODE.TRACE.OFF = NODENAME....................................................................................................... 483NODE.TRACE.ON = (NODENAME,nnnnnnnn).................................................................................... 483NON.SWAPABLE = YES | NO.............................................................................................................. 483PDSE.SHARING = YES | NO................................................................................................................483PDSENQ = YES | NO........................................................................................................................... 484PROCESS.RETENTION = YES | NO.....................................................................................................485PRTYDEF = Process priority............................................................................................................... 485QUIESCE = YES | NO.......................................................................................................................... 486QUIESCE.NODE = node name............................................................................................................486REMOTE.DUMMY.PASSWORD = [ YES | INTERNAL ].........................................................................486REQUEUE = YES | NO ........................................................................................................................ 487RESET.ORIGIN.ON.SUBMIT = YES | NO............................................................................................ 487REUSE.SESSIONS = YES | NO............................................................................................................ 488ROUTCDE.CRIT = (route code)...........................................................................................................488ROUTCDE.NORM = (route code)........................................................................................................ 488ROUTCDE.TAPE = (route code).......................................................................................................... 488RUN.JOB.EXIT = modname............................................................................................................... 489RUNJOBID = USER | CD..................................................................................................................... 489RUN.TASK.EXIT = modname..............................................................................................................489RUNTASK.RESTART = YES | NO......................................................................................................... 489S+CMD.ENFORCE.SECURE.CONNECTION = YES | NO......................................................................490

viii

SECURE.DSN = filename.................................................................................................................... 490SECURE.SSL.PATH.PREFIX = prefix...................................................................................................490SECURITY.EXIT | SECURITY.............................................................................................................. 490SECURITY.NOTIFY = YES | NO | HOLD.............................................................................................. 491SERVER.MSU = number|2147483647.............................................................................................. 491SERVER.TYPE = [PROD | TEST].......................................................................................................... 491SESSION.HIGHWATER.SMF = (133 | 128-255, 1-60) | NO..............................................................492SNA = YES | NO...................................................................................................................................492SNMP = YES | NO................................................................................................................................492SNMP.DSN = data set name | data set name (member)................................................................... 493SNMP.MANAGER.ADDR = hostname | IP address.............................................................................493SNMP.MANAGER.PORTNUM = port-number.....................................................................................493SNODE.ARCH.RECALL.WAIT = NO | YES........................................................................................... 493STAT.ARCH.CONFIRM = YES | NO...................................................................................................... 493STAT.BUFFER.ESDSDATA | STAT.BUFFER.KSDSINDX | STAT.BUFFER.KSDSDATA........................... 494STAT.ERROR = ABEND | DISABLE......................................................................................................494STAT.EXCLUDE = (record type list).....................................................................................................495STAT.INIT = WARM | COLD.................................................................................................................495STAT.QUEUE.ELEMENTS = statistics record queue size....................................................................496STAT.SNODEID = (NO | YES,NO | YES)...............................................................................................496STAT.SWITCH.SUBMIT = dsn [member]............................................................................................496STAT.SWITCH.TIME = (hh:mm:ss , ...)................................................................................................497STAT.TPREC = (start_time, end_time, snaps_per_hour)................................................................... 497STAT.USER = (user ID, [password])....................................................................................................497STATISTICS.EXIT = modname | (modname[,MANAGER | SERVER | BOTH])....................................498STRNO.MSG = number | 10................................................................................................................498SUBMIT.EXIT = modname................................................................................................................. 498SYSOUT = class.................................................................................................................................. 499TAPE.PREMOUNT = YES | NO | LIST.................................................................................................. 499TAPEIO = BSAM | EXCP......................................................................................................................499TAPEMOUNT.EXIT = modname......................................................................................................... 499TCP = OES | NO...................................................................................................................................500TCP.API.LISTEN = ((addr , port) , (addrn , portn))............................................................................. 500TCP.API.DISCONNECT.ERROR.MESSAGE = Yes | No........................................................................ 501TCP.API.TIMER = 00:00:00 | hh:mm:ss.............................................................................................501TCP.CONNECT.TIMEOUT= 30 | number of seconds.......................................................................... 501TCP.FMH.TIMER=hh:mm:ss............................................................................................................... 501TCP.FMH.TIMER.RETRIES=n..............................................................................................................502TCP.LISTEN = ((addr , port) , (addrn , portn)).................................................................................... 502TCP.RUNTASK.TIMER = hh:mm:ss.....................................................................................................502TCP.SOURCEIP = (IPv4 address or DNS | IPv6 address or DNS) ..................................................... 503TCP.SRC.PORTS..................................................................................................................................503TCP.SRC.PORTS.LIST.ITERATIONS = number of scans.................................................................... 504TCP.TIMER = wait time....................................................................................................................... 504TCQ = WARM | COLD.......................................................................................................................... 504TCQ.THRESHOLD = NO | YES | nn...................................................................................................... 505THIRD.DISP.DELETE = YES | NO........................................................................................................ 505THIRD.DISP.DELETE.X37...................................................................................................................506TRACE.BUFFER = nnn | 2................................................................................................................... 507TRANS.SUBPAS = YES|NO................................................................................................................. 507UPPER.CASE = YES|NO...................................................................................................................... 507V2.BUFSIZE = (maximum transmission buffer size, TCP/IP send/receive buffer size)................... 507WTMESSAGE = NO | YES | (YES,nnn).................................................................................................508WTRETRIES = hh:mm:ss | 00:03:00................................................................................................. 508XCF.NAME = XCF group name............................................................................................................508ZEDC = ON|OFF|PREFERRED ............................................................................................................508ZFBA = YES|NO.................................................................................................................................. 509ZIIP = NONE | EXTCOMP | SSLTLS | ALL | PROJECT......................................................................... 509

ix

IBM Connect:Direct System File Initialization Parameters.............................................................. 509Local Initialization Parameters................................................................................................................511

CDPLEX.INITPARM.BACKUP = member............................................................................................512CDPLEX.MANAGER = NO | YES.......................................................................................................... 512CDPLEX.MSGID = NONE | xx..............................................................................................................512CDPLEX.PLEXCLASSES = (*,plexclass,…,plexclass)..........................................................................512CDPLEX.REDIRECT.............................................................................................................................513CDPLEX.REDIRECT.EXCEPTION = ((Mgr-IP, Ext_Svr-IP, Ext_Svr-port, Exception-IP, Exception-

port),...)..........................................................................................................................................513CDPLEX.SERVER = IBM Connect:Direct/Server name...................................................................... 514CDPLEX.SERVER.JOBDSN = data set name...................................................................................... 514CDPLEX.SERVER.JOBMEM = ((member name,server name),…)...................................................... 514CDPLEX.SERVER.NODE = node name............................................................................................... 515CDPLEX.TIMER = 5 | number of minutes...........................................................................................515CDPLEX.VTAM = (VTAM-APPL,P/S-Node-APPL)................................................................................515

Chapter 5. User Guide........................................................................................517Introduction to IBM Connect:Direct commands.................................................................................... 517

Supported commands........................................................................................................................517Writing IBM Connect:Direct commands............................................................................................ 518

The batch interface..................................................................................................................................524Batch interface job requirements......................................................................................................524Sample job stream to run the batch interface...................................................................................525Using the MAXDELAY keyword parameter to synchronize submitted Processes............................ 528

The Interactive User Interface (IUI)....................................................................................................... 531Primary Options Menu....................................................................................................................... 531Operator Tables..................................................................................................................................535Messages............................................................................................................................................536

The Application Program Interface.........................................................................................................540DGADCHLA Program.......................................................................................................................... 540DGADCHLA Examples........................................................................................................................ 549Sample Job Stream for Executing the Program................................................................................ 550

Managing Sessions.................................................................................................................................. 551Signing On to Connect:Direct for z/OS...............................................................................................551Swap Node Command........................................................................................................................561Sign Off Command............................................................................................................................. 562Sequencing the SIGNON, SWAP NODE, and SIGNOFF Commands................................................. 563

Building, Modifying, and Submitting Processes......................................................................................564Process Routing..................................................................................................................................565Process Queuing.................................................................................................................................566SUBMIT Command.............................................................................................................................572Submitting Processes through the IUI.............................................................................................. 581Using the SB IUI Option to Submit a Predefined Process.................................................................582Using the DF IUI Option to Create, Edit, and Submit Processes...................................................... 583Using the CF IUI Option to Generate a COPY Process...................................................................... 585

Controlling Processes in the TCQ............................................................................................................ 591Controlling Processes with Commands.............................................................................................591Modifying a Process in the TCQ with CHANGE PROCESS................................................................. 591Suspending, Flushing, and Deleting Processes.................................................................................597Examining Processes in the TCQ....................................................................................................... 601

Process Queuing and Recovery...............................................................................................................608Logical Queues................................................................................................................................... 608Process Recovery............................................................................................................................... 615

Process Results and Statistics................................................................................................................ 620Statistics Log Records........................................................................................................................620SELECT STATISTICS Command......................................................................................................... 622WRITE EXSTATS Command............................................................................................................... 640

x

SELECT MESSAGE Command............................................................................................................ 647The Network Map.....................................................................................................................................648

Retrieving Records from the Network Map File.................................................................................648Translating TCP/IP Host Names to Network Addresses................................................................... 650

Utility Programs....................................................................................................................................... 652User Notification Programs................................................................................................................652VSAM AMS Interface Program (DGADTAMS).....................................................................................657Symbolic Resolution Utilities (DGADTSUB and DGADGSUB)........................................................... 658Batch Compression Utility (DGASACMP)...........................................................................................661Determine “High-Water Mark” for a Period (DGADVITL)..................................................................664ADRDSSU Interface Program (DGADSIOX I/O Exit)..........................................................................664DGASCONV – Secure Parameter File Conversion Utility...................................................................665Using the TCQ/TCX Repair Utility (DGADTQFX).................................................................................666IBM Sterling Connect:Direct FTP+ for z/OS (CDFTP)........................................................................ 667

Chapter 6. Facilities Guide................................................................................. 679IBM Connect:Direct for z/OS Facilities Overview....................................................................................679ARS Report Examples..............................................................................................................................679

IBM Connect:Direct for z/OS Activity Report.................................................................................... 679IBM Connect:Direct for z/OS Summary Report.................................................................................680IBM Connect:Direct Exception Report...............................................................................................683Security Violations Report................................................................................................................. 684Connect:Direct for z/OS Function Reports........................................................................................ 685

Activity Reporting System....................................................................................................................... 692ARS and IBM Connect:Direct............................................................................................................. 692Business Solutions Using ARS........................................................................................................... 693

Requesting ARS Statistical Reports........................................................................................................ 693Requesting Reports Using ARS Screens............................................................................................694Running the Job................................................................................................................................. 698

Requesting Multiple ARS Reports or Scheduled Processing..................................................................699Modifying the Sample Job Stream.....................................................................................................699

ARS Record Layouts.................................................................................................................................702Description of an SAS Variable.......................................................................................................... 702Authorization Event Record............................................................................................................... 703Change Process Termination Record.................................................................................................703Copy Termination Record...................................................................................................................705Delete Process Termination Record.................................................................................................. 708Display Statistics Record................................................................................................................... 709Flush/Suspend Process Termination Record.................................................................................... 710PDS Member Copy Record................................................................................................................. 710Process Submit Statistics Record......................................................................................................711Process Termination Record.............................................................................................................. 712Run Job Termination Record............................................................................................................. 713Run Task Termination Record............................................................................................................ 714Signon/Signoff Statistics Record....................................................................................................... 714Start IBM Connect:Direct Command Record.....................................................................................715Stop IBM Connect:Direct Statistics Record.......................................................................................715Write to Operator (WTO) Statistics Record........................................................................................716

The Operator Interface............................................................................................................................717Concatenation of Operator CLIST......................................................................................................717Sample Connect:Direct for z/OS CLISTs............................................................................................717Rules for Setting Up Connect:Direct for z/OS CLISTs........................................................................718Connect:Direct for z/OS Commands..................................................................................................719CLIST Examples................................................................................................................................. 719Operation Messages...........................................................................................................................721Stopping IBM Connect:Direct............................................................................................................ 722About Tape Mount Messages.............................................................................................................722

xi

Tape Device Allocation.......................................................................................................................724Event Services Support........................................................................................................................... 725

ESS Concepts and Components........................................................................................................ 725Event Services Support Architecture.................................................................................................726ESS Data Flow Using CICS API.......................................................................................................... 728Deciding What Event Data to Collect................................................................................................. 729Using ESS with the CICS API............................................................................................................. 731Using ESS with the ESS User Exit.......................................................................................................731

Spool Transfer Facility............................................................................................................................. 745Spool Transfer Components.............................................................................................................. 746VTAM Printer Support.........................................................................................................................746IBM Connect:Direct API.....................................................................................................................747Symbolic Definitions.......................................................................................................................... 753Customizing VPSSCDI........................................................................................................................ 754

Transferring Data to the JES Reader or Spool........................................................................................ 754Output to the JES Reader.................................................................................................................. 755Examples of JCL Output.....................................................................................................................755Output to JES Spool Files.................................................................................................................. 755IBM Connect:Direct Banners............................................................................................................. 756IBM Connect:Direct COPY Process....................................................................................................756COPY TO Syntax to Support Spool Transfer...................................................................................... 757Symbolic Definitions for the SYSOUT Keyword................................................................................. 758Sample Process for SYSOUT.............................................................................................................. 761

Chapter 7. Secure Plus for z/OS......................................................................... 763Connect:Direct Secure Plus for z/OS Overview...................................................................................... 763

Security Concepts.............................................................................................................................. 763Security Protocols.............................................................................................................................. 764IBM Connect:Direct Access to System Resources for SSL or TLS.................................................... 770Connect:Direct Secure Plus Tools......................................................................................................771Prerequisites...................................................................................................................................... 774Connect:Direct Secure Plus for z/OS Documentation.......................................................................775

Plan Your Implementation of the SSL or TLS Protocol........................................................................... 776Transport Layer Security Protocol and Secure Sockets Layer Protocol............................................776TLS or SSL Protocol Processing......................................................................................................... 777Self-Signed and CA-Signed Certificates............................................................................................ 779Server Certificates and IBM Connect:Direct..................................................................................... 782

Using the SecurePlus Admin Tool and Populating the Parameter File.................................................. 784Starting the Administration Tool........................................................................................................784Connect:Direct Secure Plus Configuration........................................................................................ 787Populating the Parameter File Using Quick Start..............................................................................789Manual Parameter File Creation........................................................................................................ 790

Create the Parameter File Manually for the SSL or TLS Protocol........................................................... 790Configuration Guidelines....................................................................................................................790Adding the Local Node Record to the Parameter File Manually for the SSL or TLS Protocol...........791Adding a Remote Node Record to the Parameter File Manually for the SSL or TLS Protocol.......... 794

Additional Configuration Options............................................................................................................ 798Adding a Remote Node Record for the External Authentication Server...........................................799Establishing Secure TCP API Connections to a Connect:Direct Secure Plus-Enabled Server.........800Implementing Strong Password Encryption......................................................................................801

Configure the Local Node Record Imported from the Network Map..................................................... 804Configuration Guidelines....................................................................................................................804Configuring the Local Node Record for the SSL or TLS Protocol.......................................................804

Configure Remote Node Records Imported from the Network Map......................................................807Configuration Guidelines....................................................................................................................807Configuring a Remote Node Record for the SSL or TLS Protocol...................................................... 807Disabling Connect:Direct Secure Plus in a Remote Node Record.................................................... 811

xii

Configuration for a Secure Connection between z/OS and OpenVMS Nodes.................................. 811Enable and Validate Connect:Direct Secure Plus Operation ................................................................. 813

Saving and Submitting the Connect:Direct Secure Plus Parameter File.......................................... 813Preparing IBM Connect:Direct for Secure Plus Operations.............................................................. 814Parameter File Saving After the Initial Setup....................................................................................815Validating and Testing Connections by Session................................................................................ 815

Override Settings in IBM Connect:Direct Processes.............................................................................. 816PROCESS Statement Overrides for Connect:Direct Secure Plus Defaults....................................... 816COPY Statement Overrides for Connect:Direct Secure Plus Defaults.............................................. 817Security Settings Override Examples................................................................................................ 817

Maintain Connect:Direct Secure Plus......................................................................................................818Parameter File Maintenance..............................................................................................................819Node Record Maintenance.................................................................................................................823

Connect:Direct Secure Plus Statistics.....................................................................................................828SSL or TLS Statistics Record.............................................................................................................. 828

Troubleshooting.......................................................................................................................................829Certificate Parameter Definitions............................................................................................................835

RACF Application Certificate Parameter Definitions.........................................................................835GSSKYMAN Utility Certificate Parameter Definitions........................................................................837CA-ACF2 Application Certificate Parameter Definitions................................................................... 839CA-Top Secret Application Certificate Parameter Definitions.......................................................... 841

Configuration Worksheets....................................................................................................................... 843Local Node Security Feature Definition Worksheet.......................................................................... 843Remote Node Security Feature Definition Worksheet...................................................................... 844.EASERVER Node Security Feature Definition Worksheet................................................................ 845.CLIENT Node Security Feature Definition Worksheet......................................................................846

Chapter 8. Quick Reference Guide...................................................................... 847Notational Conventions........................................................................................................................... 847IBM Connect:Direct Process Statements............................................................................................... 847

Process Statement............................................................................................................................. 848Intrinsic Variables.............................................................................................................................. 849COPY Statement.................................................................................................................................850RUN JOB Statement...........................................................................................................................853RUN TASK Statement......................................................................................................................... 854Run Task Utility Programs and Parameters.......................................................................................854SUBMIT Statement............................................................................................................................ 855SYMBOL Statement............................................................................................................................855Modal Statements.............................................................................................................................. 855

IBM Connect:Direct Commands..............................................................................................................856Modify Command............................................................................................................................... 856Network Map Commands...................................................................................................................857Process Commands............................................................................................................................859Signon, Signoff, Stop, and Swap Commands.....................................................................................861Task Commands................................................................................................................................. 861Type Commands.................................................................................................................................862User Commands.................................................................................................................................863Inquire Commands............................................................................................................................ 864Statistics Commands......................................................................................................................... 865WRITE EXSTATS Commands..............................................................................................................867Submit Command...............................................................................................................................868

Network Map Parameters........................................................................................................................869Initialization Parameter Overview...........................................................................................................870

Global Initialization Parameters........................................................................................................ 870System File Initialization Parameters................................................................................................875Local Initialization Parameters.......................................................................................................... 875

Status Codes............................................................................................................................................876

xiii

Trace Types.............................................................................................................................................. 877

Chapter 9. Connect:Direct for z/OS EAV support ................................................ 879EATTR parameter.....................................................................................................................................879COPY statement support.........................................................................................................................879VIEW PROCESS support.......................................................................................................................... 880TYPE file support..................................................................................................................................... 881DGADTDYN support.................................................................................................................................882z/OS operating system support of EAV................................................................................................... 882

Notices..............................................................................................................885Trademarks.............................................................................................................................................. 886Terms and conditions for product documentation................................................................................. 887

xiv

Chapter 1. Release Notes

IBM Connect:Direct for z/OS Release NotesThe IBM® Connect:Direct® for z/OS® Release Notes document supplements IBM Connect:Direct for z/OSdocumentation. Release notes are updated with each release of the product and contain last-minutechanges and product requirements. Read the document before installation.

Hardware and Software RequirementsHardware and software requirements for IBM Connect:Direct for z/OS are in the Connect:Direct forz/OS Configuration Guide and the Connect:Direct for z/OS Program Directory. Connect:Direct Secure Plusrequires the same hardware and software and the additional software listed in the following table.

Sterling Connect:Direct File Agent must be installed in the UNIX System Services component of z/OS andconfigured to communicate with the IBM Connect:Direct server. Use a PC for terminal emulation to createa configuration file. Additional Sterling Connect:Direct File Agent requirements include:

Component or Functionality Software

Connect:Direct for z/OS • One or more online zIIP processors to use the zIIPExploitation feature

• One or more online zEDC accelerators to exploit the zEDCfeature

• Two or more online FBA LUNs defined on an IBM DS8000Series Storage Server, to exploit the zFBA feature

Connect:Direct Secure Plus for z/OS • TCP/IP connection to use the SSL or TLS protocol• IBM SystemSSL toolkit• IBM Language Environment• For Secure Plus, ICSF FMID HCR77A0 or higher is

required unless cryptographic coprocessors are available. Ifcoprocessors are available, any ICSF level supported by theConnect:Direct for z/OS release is accepted.

• For TLS 1.3, z/OS 2.4 or higher is required

Connect:Direct File Agent • Java 2 Platform, Standard Edition (J2SE). Download theJ2SE from the IBM web site

• 31-bit JVM (Java Virtual Machine)

POSIX Environment and System LibrariesInstall and set up the UNIX System Services (or POSIX) environment before you install IBMConnect:Direct. The POSIX requirement and use of C/C++ and LE require that the following data setsbe available to IBM Connect:Direct through the STEPLIB or LINKLST. In addition to C/C++ and LE, XPLINKis now required to support the File Accelerator and alters the data set list from previous releases.

• CEE.SCEERUN (IBM Language Environment)• CEE.SCEERUN2 (XPLINK Requirement)• CBC.SCLBDLL (C/C++ Run-time)• SYS1.SIEALNKE (System SSL Environment)

© Copyright IBM Corp. 1993, 2021 1

If IBM Connect:Direct Resource Access Control Facility (RACF) program control is implemented, definethese data sets and the IBM Connect:Direct SDGALINK to the program class.

MBCS TransfersTo perform MBCS transfers, verify that the Natural Language Resources component of LanguageEnvironment is installed on your operating system.

License Key FileTo exploit the FASP feature through SSP you must obtain and store a HSAO license file inside theConnect:Direct for z/OS file system. This HSAO license file must be available to the IBM Connect:Directduring product initialization via the CDASPLIC DD statement.

What's New in This ReleaseIn this release of IBM Connect:Direct for z/OS, and its related software, several features have been addedto enhance functionality. The following sections describe these changes in more detail.

New features added to this release• SY record has been enhanced:

– to record PNODE’s and SNODE’s SYSOPT data. It will have two records on each NODE (1 for PNODEand 1 for SNODE).

– to support S2 panel filtration for various fields like PNODE, SNODE, Local node, Remote node,USERID, Any NODE etc.

– Now True SYSOPT length is 1702. SYSOPT longer than 1702 bytes will be truncated.– There will be SY record for RUNJOB and syntax will be the same as we have for RUNTASK.– CT record will display SYSOPT info for DATATYPE, XLATE and STRIP.BLANKS on “TO” and “FROM”

side. CT record will have this information for each filetype except MVS filetype. But, there won’t beSMS MGD info if any DSN does not support SMS MGD.

– Initparm update with invalid value will not be allowed. Unused Initialization Parameters are markedas obsolete.

• Encrypt.data Deprecation:

– Encrypt.Data has been deprecated from release 6.2 onwards. It will always work as Encrypt.Data=Y,so it will always encrypt all data not just FMHs. Prior release settings will continue to work and will behonored.

– Though user can change Encrypt.Data value (Y|N) in secure parmfile, those changes will be ignored.– Override will no longer have any impact on Encrypt.Data.– Process override will be ignored meaning user can provide Secure=(Encrypt.Data=Y|N) in process

but it will be ignored and will not issue any error message and will not have any impact on process.Though it will issue new informational messages in JESMSGLG. CSPA051I for process override.CSPA052I for step override.

– CSPA051I informational message will have process name and number. This informational messagestates “ ENCRYPT.DATA DEPRECATED. CANNOT OVERRIDE PROCESS_Name (Process#)”.

– CSPA052I information message will show step name and process name and number. Thisinformational message shows “ENCRYPT.DATA DEPRECATED. CANNOT OVERRIDE Step_NameProcess_name (Process#).”

– CSPA052I will be issued for all steps having Secure=(Encrypt.Data=Y|N).– “Secure=” will keep working as it used to for other parameters.– User can use the same Parmfile in 6.2 that was used in prior release.

2 IBM Connect:Direct for z/OS: Documentation

– Secure Admin panel will show “(Ignored, Forced to Y)” on “Secure+,Create/Update,Panel” in‘SSL/TLS Parameters’ tab along with “Enable Data Encrypt field”.

– While saving secure Parmfile it will display warnings for local node and every adjacent node having“Enable Data Encrypt = N”. The warning will be as below:

- Warning: Local.NODE Deprecated value for 'Enable Data Encrypt' setting is used:N, Forcedto 'Y'.

- Warning: Adjacent.NODE Deprecated value for 'Enable Data Encrypt' setting is used:N,Forced to 'Y'.

– When the data sender is CDZ 6.2, whether PNODE or SNODE, it will always require data encryptionirrespective of the setting in its Secure Parmfile or override in the process or COPY step. If in addition,the receiver is a CDZ 6.1 PNODE, and there is an override in the process (PROCESS or COPY step),then the CDZ 6.1 PNODE receiver cannot turn off data encryption, but it can terminate the process orstep (CSPA078E or CSPA011E).

– Adjacent nodes running releases prior to 6.2 can refuse the encryption. In this case Select Statisticsand Select Process will show “Other Node Refused the Encryption” along with Encrypt.Data field.

– Select Process will have 3 new fields (Cipher, Cipher suite and Encrypt.Data) and will drop the 1 field(Encryption).

- Cipher: It will display cipher code value of used cipher, such as 1301, 009D etc.- Cipher Suite: It will display 39 bytes long alphanumeric cipher name, such as

“TLS_RSA_WITH_AES_256_GCM_SHA384” .- Encrypt.Data: it will show true value of Encrypt.Data used irrespective of setting in Secure Parmfile.

That means if we have Encrypt.Data = Y on SP panel then process is using encryption if we have Nthen we are not using encryption.

– View process will show “/* (Ignored; Deprecated)*/” info after each occurrence of Encrypt.Data whichwill inform user that setting was ignored since it has been deprecated.

– When process is in execution status, this info will not display.– Since process override will not be allowed from release 6.2 for Encrypt.Data, there will not be

“Process override” info in CT record. Though for other values like protocol, cipher etc. it will keepdisplaying “Process override” as legacy.

– This enhancement will not reset value of Encrypt.Data in Secure Parmfile. It will remain as user hasset. In other words, there will not be any impact on Encrypt.data setting in Secure Parmfile, processor step. It always will work as Encrypt.Data=Y. Also, internal processing will not change Encrypt.Datasetting in Secure Parmfile.

• Process Library:

– This feature allow user to list, add, delete, rename, fetch processes from/to dedicated process librarydataset.

– 1st concatenated dataset of DD DMPUBLIB in DTF Startup JCL will be used as Process Librarydataset.

– List, Add, Delete, Rename and Get operations can be performed on process members on ProcessLibrary Dataset via Connect:Direct Web Services.

– DD DMPUBLIB will now be mandatory DDNAME for Connect:Direct Startup JCL.– 2 new permissions, Process Library Read and Process Library Update, are added to Authorization Bit

Mask (ABM) to control read and update user access to Process Library on Connect:Direct.– After each operation on Process Library, a new statistical record ‘PL’ will be generated reporting

details of operation. For more information, refer “Configuring Process Library support” on page 310.• Support to specify PS-E Version in a Process, IUI, and the Type Record

– If both PNODE and SNODE are running v6.2, in addition to legacy DSNTYPE support, the DSNTYPEVersion can be specified for a new destination PS-E in the COPY TO section, either in the COPYstatement or in SYSOPTS, but not both in the same COPY step.

Chapter 1. Release Notes 3

– If the PNODE is v6.2 in a PULL, the COPY TO section can specify the DSNTYPE Version in the COPYstatement or in SYSOPTS, but not both.

– If the SNODE is v6.2 in a PUSH, the COPY TO section can specify the DSNTYPE Version in the COPYstatement if the PNODE supports it, or in SYSOPTS, but not both.

– Support for specifying PS-E Version in the IUI CF Receiving File panel, and in the Type Record SMS/VSAM Attributes.

– For a newly created data set, Select Stats of the CT record will display EXTEND-1 for a Version 1 andEXTEND-2 for a Version 2 PS-E file.

– If the data set is not being created, or if the DSNTYPE Version is not specified in the TO section, thenSelect Stats of the CT record will display the file as EXTENDED. For more information, refer “UsingPS-E Version 2 with IBM Connect:Direct” on page 419.

• You can now restrict the use of the Process SNODEID via SAF. If the Process submitter is not grantedaccess to the SNODEID and NODE combination, then the SUBMIT command will fail. This featurerequires the customer to implement a new sample APF authorized Stage 1 SUBMIT exit, DGAXSUBA asload module DMCXSUBA, in order to be activated. For more, refer “IBM Connect:Direct Exits” on page322 and “Sample Statistics Exits” on page 324 in SDGASAMP member DGAXSUBA.

• File Agent:

– File Agent Install Anywhere jar file added to SMP/E package in $CD.SDGADATA(DGAFAJAR).– FILE.AGENT.PATH initialization parameter added to specify File Agent absolute USS directory path.– User will now be able to fetch and update File Agent Configuration from Connect:Direct Web Services

user interface.– 2 new permissions, File Agent Read & File Agent Update, are added to Authorization Bit Mask (ABM)

to control read & update user access to File Agent Configuration.– For each operation on File Agent Configuration, a new statistical record ‘JS’ will be generated

reporting details of operation.– New sample JCLs DGAFAINS, DGAFAREI, DGAFASTA and DGAFASTO are added to install, re-install,

start and stop File Agent.• External Statistics Logging

– This feature allows user to log statistics records from external sources.– New command WRITE EXSTATS is added to write external statistics– New initialization parameter EXTERNAL.STATS.ALLOWED is added to control logging of external

statistics record.– 40 new statistics record type identifiers will be reserved for External Statistics record. These are

- YA, YB, YC, YD, YE, YF, YG, YH, YI, YJ, YK, YL, YM, YN, YO, YP, YQ, YR, YS, YT, YU, YV, YW, YX, YY, YZ,Y0, Y1, Y2, Y3, Y4, Y5 ,Y6, Y7, Y8, Y9, Y@, Y#, Y$, Y%

- New permission, External Statistics Logging, is added to Authorization Bit Mask (ABM) to controluser access to write external statistics records on Connect:Direct.

– After each write operation of External Statistics, a new statistical record ‘ES’ will be generatedreporting details of operation.

Connect:Direct for z/OS Special Product ConsiderationsReview the following considerations before installing the product:

Installation Consideration• If the installation data sets have been loaded to a cataloged data set with an HLQ other than IBM.fmid,

the SMP/E RECEIVE command must change the HLQ by specifying the RFPREFIX(hlq) parameter, forexample, RECEIVE SELECT(HDGA620) RFPREFIX(hlq).

4 IBM Connect:Direct for z/OS: Documentation

Exits Considerations• Sample source code for Stage 1 Signon Security exit (DGACXSIG in SDGASAMP) and Stage 2 Security

exit generation macro (DGASECUR in SDGASAMP) have been renumbered. Verify line numbers beforeapplying any SMP/E USERMOD or custom code changes. For changes to Signon Dummy Passwords,refer to Global Signon Defaults.

• The IBM Connect:Direct startup JCL has a user-definable DD statement (USRINFO) for displaying user-defined information from User Exits. If the USRINFO DD is allocated, then IBM Connect:Direct opens itduring product initialization and initializes it with the string SITA523I USRINFO INITIALIZED.

Initialization Parameters Considerations• In a IBM Connect:Direct/Plex environment, if you specify ANYADDR or ANYADDR6 for the TCP.LISTEN

local initialization parameter associated with a IBM Connect:Direct Server but do not specify theCDPLEX.REDIRECT parameter, a default address is created as the IBM Connect:Direct/Plex redirectionaddress. For the IPv6 protocol, the default is generated by adding a::FFFF: prefix to the IPv4default. If you do not want this to be your default address, specify the value you do want using theCDPLEX.REDIRECT parameter.

If you use the dynamic VIPA resources, you may need to specify the SOURCEIP parameter in thenetwork map if the remote node cannot perform network map checking. The SOURCEIP address is usedto bind the socket and by the remote node to perform netmap checking.

• The following initialization parameters are obsolete and must be removed from the initializationparameter file:

Obsolete Parameters

ABNLIGNR ALLOC.OPTIONS ALLOC.STORAGE

APCTHRSH APDSN API.SYSTEMS

APPLID BUFND BUFSIZE

CD.KEY CD.NODE CDPLEX.TCPIP

CDPLEX.TCPNAME CONNECT.WAIT DUMP

ESTAE EXT.COMPRESS.DEFAULT LINES

LOG LOG.PRINTER LU1.ASYNC

LU1.NETMAP.CHECK LU1.SCRIPT.DSN LU2.WAIT

MAXRESTAR MAXWAIT MP

NDM.KEY NDM.NODE NETEX.MAX.OFFERS

NETEX.MAXRU NETEX.NRBTIME NETEX.OFFERTIM

NETEX.OLD.PREFERRED NETEX.SSNM NETEX.VER

NETEX.WINDOW OS390.TASKING PASSWORD

PASSWORD.REPLY PC.ENABLE.CHECK POA.APPL

POSIX PRTYINT RESIDENT.MOD

SECURITY.TYPE STIMEOUT STORAGE.PER.TASK

TAPE.DETACH TAPE.RETPD TCP.ADDR

TCP.API.PORTNUM TCP.BUFSIZE TCP.NAME

TCP.PORTNUM TCP.SNS.SUBSYS TCQDSN

TCXDSN TPAM XETEX

Chapter 1. Release Notes 5

Obsolete Parameters

XETEX.MAX.OFFERS XETEX.MAXRU XETEX.NRBTIME

XETEX.OFFERTIME XETEX.SSNM XETEX.VER

XETEX.WINDOW XLU1.ASYNC XLU1.SCRIPT.DSN

ZEDC.EXCLUDE ZIIP.EXTCOMP.DATASIZE.THRESHOLD UDT

UDP.SRC.PORTS UDP.SRC.PORTS.LIST.ITERATIONS UDT.MAXPROCESS

UDT33.LISTEN

DEBUG.ABEND EVT.ID EVT.MAXRETRY

EVT.QMANAGER EVT.START EVT.TIMER

EVT.TOPIC EVT.TYPE STATISTICS

Process Retention Considerations• To enable Process Retention, increase the TCQ space before activating it. A Process is retained in the

PR queue until manually deleted, space is required, or MAX.AGE value is reached. Increasing TCQ spacereduces the likelihood that a Process in the PR Queue is automatically deleted when space is required.For information on enlarging the TCQ, see Planning the Installation.

Network Map Considerations• If IBM Connect:Direct FTP+ for z/OS communicates with an earlier version of Connect:Direct for z/OS,

the CDFTP.TEMPFILE specification in the netmap must be an zFS file unless appropriate maintenancehas been applied to that version of IBM Connect:Direct for z/OS.

• Session Management of Adjacent Nodes - Use the SESS.SNODE.MAX network map parameter only withthe TCP/IP and LU6.2 protocols.

Storage Considerations• To maximize available storage below the 16-MB line, define sufficient storage above the 16-MB line, and

maximize concurrent processing, define a region size of 0 MB for IBM Connect:Direct.

Note: Depending on your system-specific storage requirements, the MAXTHREADTASK and MAXASSIZEparameters in SYS1.PARMLIB member BPXPRMxx may also have to be altered to ensure maximumstorage and concurrent processing within IBM Connect:Direct.

Other Product ConsiderationsReview the following other product considerations before installing the product:

• UNIX System Service (BPX) calls are executed in the IBM Connect:Direct IUI under the TSO or BatchUser ID. BPX calls require that a user ID has an OMVS segment defined to it within the external securityproduct, such as IBM RACF, CA-ACF2 or CA-TOP SECRET. The BPX calls resolve the TCP/IP nameor address for reporting purpose in Select Statistics. If a user ID does not have an OMVS segmentdefined to it, an SEC6 ABEND or Trace Resolver messages under the TSO or batch user can occur whenrequesting Select Statistics.

Information about adding an OMVS segment to a user ID using an external security product, eitherindividually or as a group assignment, is found in the external security product documentation.

• Due to an issue with the security toolkit on the i5/OS hardware, an SSL/TLS cipher suite can benegotiated during the SSL/TLS handshake that is not defined in the cipher suite list. IBM PMR, 35692,has been opened to address the i5/OS toolkit issue. When the PTF becomes available for i5/OS, apply itto ensure cipher suite negotiation occurs as expected.

6 IBM Connect:Direct for z/OS: Documentation

• An ABEND 0C4 is possible in z/OS V2R4 using Secure+ due to an error in System SSL. APAR OA58781against System SSL addresses the error with PTF UJ01929 or UJ01933 as appropriate for the installedlevel of System SSL.

Transmission Control Queue ConsiderationsReview the following Transmission Control Queue considerations before installing the product:

• Because of the changes in the Transmission Control Queue (TCQ) to support Processes containing up to1 MB, review all SUBMIT exits. Modify any SUBMIT exit that:

– Alters the size of the TCQE (change TQRECLN)– Uses TQCSPRD (pointer to first, that is, current step)– Uses TSHFTCQE (forward pointer to next step)– Uses TSHBTCQE (backward pointer to previous step)– Adds or changes PACCT or SACCT information

The TQCSPRD, TSHFTCQE, and TSHBTCQE fields contain offsets relative to the start of the TCQE forProcesses that do not exceed 64 KB. For larger Processes, these fields must be multiplied by 16before being used as an offset. In the TCQE, a flag indicates whether or not this processing shouldtake place (the flag byte is TQFLAGA and the bit equate is TQGT64K).

SUBMIT exits are no longer allowed to change the size of the TCQE (modify TQRECLN). The sampleSUBMIT exit DGAXACCT previously showed how to add the PACCT and SACCT fields to the end of theTCQE and extended the length. Because this is no longer allowed, fields have been reserved for thePACCT and SACCT information to allow the SUBMIT exit to add or modify accounting information asrequired. The sample SUBMIT exit DGAXACCT has been modified to show you how to manipulate thisaccount information.

• Using IGGCSI00 to access files requires READ access to the master catalog.• Only Version 2 Flows, which are used for the TCP/IP and SNA LU6.2 protocols, support the ability to

checkpoint files larger than 4 GB. Version 1 Flows, which were used for VTAM SNA LU0, do not supportthis ability.

• To honor the permission setting for HFS files using the PERMISS keyword, you must set the z/OSUNIX System Services UMASK to 000 either by default or by using the runtime environment variable,_EDC_UMASK_DFLT. To set the environment variable, define the _EDC_UMASK_DFLT=000 variable in aRECFM=VB type file and allocate the ENVIRON DD in the IBM Connect:Direct startup JCL.

• Example: //ENVIRON DD DISP=SHR,DSN=$CD.ENVIRON(TZ)

Miscellaneous ConsiderationsReview the following miscellaneous considerations before installing the product:

• Because the standby extended recovery job and the active IBM Connect:Direct node use the sameVTAM APPLID, TCP/IP address, and port, the standby extended recovery job must run in the samez/OS image as the active IBM Connect:Direct node unless you use the Dynamic VIPA and Dynamic SNAinformation described in Preparing TCP/IP Configuration and Configuring Extended Recovery.

• If you copy a file that is in IBM-proprietary compressed format to a new file that is not, IBMConnect:Direct may not allocate enough space for the new file. Such COPYs may experience allocationfailures (Sx37 type ABENDs), which will require SPACE to be manually coded in the Process.

• Scheduling or automated operations packages can result in attempts to process incomplete or emptyfiles. Scheduling packages, such as CA-7, ZEKE, or CONTROL-M and certain automated operationspackages, such as CONTROL-O, are often set to start jobs upon a file's closure and an SMF record beingcut or based upon specific messages appearing on the system console. When using Connect:Direct forz/OS, this method of starting jobs can result in attempts to process incomplete or empty files. Thissituation can occur when an active transfer is interrupted and must be restarted. The receiving file willbe closed, but upon Process restart it will be written to by Connect:Direct for z/OS.

Chapter 1. Release Notes 7

To prevent erroneous processing by such packages, set up Processes with conditional logic to verifythat the copy successfully completes, and then use the scheduling or automation package's providedprogram (U7SVC, ZEKENDM, CTM@IF10) in a IBM Connect:Direct RUN TASK.

• Checkpointing is ignored when transferring HFS files.• IBM C Program Containing MAIN() or Enclave - You cannot execute any IBM C program that contains a

MAIN() section or enclave as a Run Task or Exit. FTP is an example of this type of program.• LU6.2 Does not Support Redirection of Processes in IBM Connect:Direct/Plex Environment -The LU6.2

connection protocol does not support the feature, which allows the IBM Connect:Direct Managerto redirect work to one of its servers. The remote node must address the server on which youwant to run an LU6.2 Process. To do this, specify the node name and VTAM address of the IBMConnect:Direct Server on which the Process is to run in the remote server's network map. Use the sameCDPLEX.SERVER.NODE and CDPLEX.VTAM specified for the local initialization parameters for the IBMConnect:Direct Server you are trying to address.

Another stipulation related to the LU6.2 protocol involves a situation where one of the IBMConnect:Direct servers in a IBM Connect:Direct/Plex environment is communicating with a stand-aloneIBM Connect:Direct DTF. In this case, all LU62 processes for this specific node must be directed to thesame server and you can use a PLEXCLASS to accomplish this.

• IBM Connect:Direct cannot transfer LBI files using LU0 connections.

UDT Special ConsiderationsUDT support has been removed. All UDT and UDP INITPARMs are deprecated and should be removed.They will be tolerated in v6.1, but may be removed in a future release.

Connect:Direct Secure Plus ConsiderationsReview the following Connect:Direct Secure Plus considerations before configuring the product:

• Support for the TLS 1.1 and TLS 1.2 protocols require certain version and release levels, as wellas PTF service to use those protocols. See the Program Directory for detailed information on theserequirements.

• Support for TLS 1.3 requires z/OS V2R4 or greater release or version• TLS 1.3 is not supported in FIPS Mode• TLS 1.3 only support cipher suites TLS_AES_128_GCM_SHA256 (1301) and

TLS_AES_256_GCM_SHA384 (1302)• TLS1.3 does not support certificates with SHA1 & SHA224 signature algorithms and RSA Key Length

less than 2048. Also, DSA certificates not supported by TLS1.3• Elliptic curve (key_shares / groups) supported by TLS1.3

– X448 (0030)– X25519 (0029)– SECP521R1 (0025)– SECP384R1 (0024)– SECP256R1 (0023)

• Certificates supported by TLS 1.3

Certificate type Preferred Signature Algorithm

RSA certificate with a signature algorithm of RSAwith SHA-1 (Key sizes 2048 and larger

0804 - SHA-256 with RSASSA-PSS

RSA certificate with a signature algorithm of RSAwith SHA-256 (Key sizes 2048 and larger

0804 - SHA-256 with RSASSA-PSS

8 IBM Connect:Direct for z/OS: Documentation

Certificate type Preferred Signature Algorithm

RSA certificate with a signature algorithm ofRSASSA-PSS with SHA-256 (Key sizes 2048 andlarger)

0804 - SHA-256 with RSASSA-PSS

RSA certificate with a signature algorithm of RSAwith SHA-384 (Key sizes 2048 and larger)

0805 – SHA-384 with RSASSA-PSS

RSA certificate with a signature algorithm ofRSASSA-PSS with SHA-384 (Key sizes 2048 andlarger)

0805 – SHA-384 with RSASSA-PSS

RSA certificate with a signature algorithm of RSAwith SHA-384 (Key sizes 2048 and larger)

0806 – SHA-384 with RSASSA-PSS

RSA certificate with a signature algorithm ofRSASSA-PSS with SHA-384 (Key sizes 2048 andlarger)

0806 – SHA-384 with RSASSA-PSS

Any ECC secp256r1 certificate 0403 – SHA-256 with ECDSA

Any ECC secp384r1 certificate 0503 – SHA-384 with ECDSA

Any ECC secp521r1 certificate 0603 – SHA-512 with ECDSA

• For TLS 1.3 handshake a CA certificate must have:

– Critical flag set to true for Basic Constraints extension– must contain authorityKeyIdentifier extension

• The support for Security Policy SP800-131a and the Suite B profile requires that the Secure Plusand System SSL be in FIPS mode. See the information below and the System SSL Programing Guideregarding FIPS.

• Connect:Direct Secure Plus uses services from ICSF that require the Connect:Direct ID for Secure Plusand the TSO user ID of the Secure Plus Administrator to have read access defined in the RACF CSFSERVfacilities class.

• The enhancements to Connect:Direct Secure Plus such as, new protocols added, support for newsecurity policies, and removal of support for STS require a Secure Parmfile conversion when upgradingfrom any release prior to 5.2. For more information see, “DGASCONV – Secure Parameter FileConversion Utility” on page 665.

• IBM Connect:Direct administrators need access to z/OS UNIX System Services in order to update SSLand TLS parameters.

• IBM Connect:Direct needs UNIX read permission to the key database. Use the UNIX CHMOD commandto change permissions, if necessary.

• A default certificate must exist for the SSL or TLS protocol to successfully communicate with a tradingpartner. Use the IBM GSKKYMAN utility (or IBM RACF if using key rings) to set a trading partnercertificate as the default. For information about creating and managing certificates, refer to the IBMdocumentation. To locate documentation, go the IBM web site and perform a search on GSKSSL10.

• Secure connections cannot be established using LU0 or PNODE=SNODE. Nonsecure connectionsoperate normally using these protocols.

• You can only use the Quick Start option the first time you create and populate the Connect:Direct SecurePlus parameter file from the network map, and if your IBM Connect:Direct TCP/IP netmap entries usestandard IPV4 addresses.

• While in FIPS mode, the following are important considerations for Connect:Direct Secure Plus:

– The certificate store must be in FIPS mode and the certificate must meet size restrictions forencryption keys. The GSKKYMAN utility can be used to create a key database for FIPS mode. In

Chapter 1. Release Notes 9

addition, other requirements of RACF might be necessary. For more information, see z/OS V1R11.0Cryptographic Services System Sockets Layer Programming SC24-5901-08

– While in FIPS mode, IBM Connect:Direct Secure Plus can open a FIPS mode key database; however,initialization fails if the key database is not in FIPS mode. If the FIPS initialization parameter isspecified as NO, IBM Connect:Direct Secure Plus can still open and use a FIPS-mode database.

– When Connect:Direct FTP+ is in FIPS mode, the TLS protocol is the only supported protocol. If SSL isenabled in the secure parameter file, the connection to that remote node is rejected during the TLShandshake.

– While in FIPS mode, only certain ciphers are supported. During the TLS handshake, any non-FIPSmode ciphers are ignored. The Secure Plus Admin tool provides the following textual representationof the ciphers available in FIPS mode:

- SSL_RSA_AES_128_SHA- SSL_RSA_AES_256_SHA- SSL_RSA_WITH_3DES_EDE_CBC_SHA

– The following errors cause Connect:Direct FTP+ to terminate with a U4079 abend. These are criticalfunctions and indicate a severe problem requiring immediate attention:CMSERR_BAD_RNG_OUTPUT

Failure during random number generationGSK_ERR_RNG

Failure during random number generationCMSERR_FIPS_KEY_PAIR_CONSISTENCY

Failure when generating either an RSA or DSA keypairCMSERR_KATPW_FAILED

Failure was encountered by the gsk_perform_kat API when performing known answer testagainst the System SSL cryptographic algorithm

Connect:Direct File Agent Special ConsiderationsConnect:Direct File Agent has the following special considerations:

• Detect when VSAM files are created, but not when they are updated.• When watching for a VSAM file, it triggers a Process three times because it detects the creation of

the cluster, data, and index portions of the VSAM dataset. To prevent the Process from being triggeredunnecessarily, append.DATA to the data set name. To see an example involving a VSAM data file, see theConnect:Direct File Agent help.

• Connect:Direct File Agent ignores PDSE data sets in a watch directory.• Do not use the Search tab on the IBM Connect:Direct configuration GUI Help when running the GUI as a

z/OS batch job. It may terminate the configuration GUI session.• To avoid a parsing error when a substitution for a variable would include an open or closing parenthesis,

enclose the variable in double quotes.

For example, if %FA_FILE_FOUND. is to be passed as the Process Argument &DSN, specify the variableas:

&DSN=”%FA_FILE_FOUND.”

Note: Variable values enclosed in quotes must not be concatenated with other values. Any attempt to dothis will cause a submit failure or subsequent Process failure.

• Some Hummingbird Exceed releases do not allow you to close the Help windows.

Upgrading IBM Connect:DirectReview the following items before upgrading your existing IBM Connect:Direct system.

10 IBM Connect:Direct for z/OS: Documentation

• You must re-assemble and re-link all user exits after you complete the installation procedure.• If previous modifications were made to the DGASECUR and DGA$MFLG, update the DGAXAUTH macro

with those modifications.• After installation, reassemble and link-edit your security module that uses the DMGSECUR macro (new

element name is DGASECUR) to ensure that all enhancements are implemented. For information, seeImplementing Security.

• After IBM Connect:Direct files have been migrated, using these files with a previous release of IBMConnect:Direct results in the inability to view user comment fields in the network map. If you update thenetwork map using an older version, any information stored in the comment fields may be lost.

• For archive JCL and Processes that use STAT archive files or STAT ESDS, update the LRECL to 2048 andupdate all archive jobs and procedures, which must change the logical record length. You can updatethe LRECLs in advance and use the LRECL updates with any release.

• To ensure above-the-line storage, calculate the difference between the maximum storage values usedfor BSAM data transfers (as specified by the MAXSTGIO initialization parameter) and change theJOBSTEP region accordingly. For additional information, see Improving Performance.

• Performing an upgrade is similar to performing an initial installation. You can retain some or all data filescreated by the initial installation or as a result of the last upgrade.

To retain existing IBM Connect:Direct files when you migrate, use the information in the following table.These files are required to fall back to the previous version.

Data Set Migration Considerations

NETMAP file Unload, delete, reallocate, and reload the network map. For moreinformation, see Migrating an Existing Network Map.

AUTH, CKPT, and TYPE files Use IDCAMS REPRO to migrate the data to the new files. For theAUTH file, use this DCB information:

DCB=(DSORG=PS,RECFM=VB,LRECL=2052,BLKSIZE=24624)

For the CKPT (Checkpoint) file, use this DBC information:

DCB=(DSORG=PS,RECFM=VB,LRECL=20004,BLKSIZE=27998)

For the TYPE file, use this DCB information:

DCB=(DSORG=PS,RECFM=VB,LRECL=1934,BLKSIZE=29010)

STATS files See, Migrating of Existing STATS files steps below.

MSG file Because new messages exist in the MSG file, use the updatedmessage file. Any user-defined messages can be loaded using theDGAJMSGL JCL in the $CD.SDGAJCL installation data set.

IBM Connect:Direct initializationparameters file

After migrating data from a previous release, specify theIBM Connect:Direct initialization parameters TCQ=WARM andSTAT.INIT=WARM and attempt the initialization.

Note: Make sure that all obsolete initialization parameters areremoved before you start up. See the list of initializationparameters that are obsolete.

Migrating an Existing Network MapTo use an existing network map when you migrate to this version of IBM Connect:Direct:

1. Run the DGAJUNLD job stream to unload the network map file of your current release by having yourUNLOAD DD statement point to your upgrade release CNTL library.

Chapter 1. Release Notes 11

2. Make changes to the initialization parameters and edit the network map source, if necessary. Then runDGAJJDEF to redefine your network map, and DGAJLOAD to reload it.

3. If you change the name of your network map:

Update your NETDSN initialization parameter, DGAJBATC member in the $CD.SDGAJCL data set, andISPF main menu panel (usually ISR@PRIM).

Migrating existing STATS filesThere are considerable indexing improvements in the Statistics facility for Version 6 to allowing for theextended search capabilities by NODE.

Due to this, it is recommend that when migrating to Version 6 that you preserve your previous stats filesby performing an archive on the previous version of Connect:Direct. Then perform a Stats Cold start usingSTAT.INIT=COLD command with the new version of Connect:Direct.

The same recommendation applies when backing out or migrating back to the previous release, archivethe data and then Cold start.

Migrate Stats data to Version 6

If Cold start is not possible and you must have the Stat data active then the following procedure MUST beperformed when migrating to Version 6 with Stats data from a previous version.

1. Edit, customize and submit the DGAJBKEY member in the HDGA600.SDGAJCL data set to rebuild eachSTAT.KSDS from every STAT.ESDS from the previous release that contains active data.

2. Ensure that the STEPLIB uses the HDGA600.SDGALINK to execute the version 6 DGADBKEY. Forexample, if you have 2 Stat file pairs and both ESDS01 and ESDS02 contain active data then you wouldneed to execute DGADBKEY for both ESDS01 and ESDS02 to rebuild both KSDS01 and KSDS02.

Example

If there are 2 STAT file pairs and both ESDS01 and ESDS02 contain active data then executeDGADBKEY for both ESDS01 and ESDS02 to rebuild both KSDS01 and KSDS02.

Backout or Migrate STATS data back to Previous Version

To rollback to the previous release, data collected by Version 6 may not be compatible with that previousrelease and the following procedure must be performed to rollback to the previous version:

1. Edit, customize and submit the DGAJBKEY member in the old version HDGAnnn.SDGAJCL data set torebuild each STAT.KSDS from the STAT.ESDS from version 6 that contains active data.

2. Ensure that the STEPLIB uses the old version HDGAnnn.SDGALINK to execute the old versionDGADBKEY.

Using the DGA#FXAL REXX ExecAfter updating a target library type, you can use the DGA#FXAL REXX exec to check the target libraryto ensure the members are all present and all aliases are assigned correctly, and to report on any extramembers or aliases that are not in the list for that type. The default setting simply checks the PDSmembers against the list and reports on what is found. In addition, DGA#FXAL can fix or delete brokenaliases. This exec uses the TSO DELETE and RENAME commands, which require exclusive control of thePDS. Any errors that cannot be fixed automatically by DGA#FXAL must be fixed manually by restoring thePDS from a backup or distribution library. These errors include deleted members, non-alias members thatare supposed to be aliases, and aliases that are supposed to be non-alias members.

Syntax and Parameters

The DGA#FXAL REXX exec has the following format:

12 IBM Connect:Direct for z/OS: Documentation

DGA#FXAL pds [type | . ] [detaillevel | . ] [fixlevel | . ]

The DGA#FXAL REXX exec has the following parameters. The pds parameter is required and must be first.All parameters after the pds parameter are optional and positional, and can take the default by specifyinga "." placeholder.

Parameter Description

pds A fully qualified DSN with or without quotation marks. A partitioned IBM Connect:Directdataset of one of the supported types. A value of '?' requests that the syntax bedisplayed. The syntax is also displayed if there are any parameter errors.

type The pds type. Either specify one of the target library types listed or do not specify. If notspecified, the lowest level qualifier of the PDS must be one of the listed target librarytypes. For each type, you can specify either the new or old value – they produce the sameresult.

detaillevel Controls detail reporting. The default is 1.

The following values are valid for this parameter:

• 0 reports everything, error and non-error alike.• 1 reports only error level 1 and higher.• 2 reports only error level 2 and higher

fixlevel Controls what fixes are attempted. Only levels 2–8 errors can be fixed. Default is 0. Validvalues are 0, 2–8, and combinations of 2–8. The default is 0.

The following values are valid for this parameter:

• 0 does not fix anything• 2 fixes level 2 errors.• 3 fixes level 3 errors• ... fixes level 4–7 errors• 8 fixes level 8 errors

For each pair or solo member listed for the type, an error level is set. See “Error Level Explanation” onpage 20. If the error level is specified in fixlevel and the fix action in the table is not None, the pairis added to a fix list. After all pairs have been checked, if the fix list is not empty, you are prompted tocontinue. If you reply "Y," the fixes are attempted. If the fix for any pair fails, the exec continues with thenext pair. A report is generated and written to both the TSO screen and to a PS dataset. The detail listingsof expected and unexpected members are controlled by detaillevel. All fix attempts are reported.

Examples

1. In this example, IBM Connect:Direct uses list for type SDGAPROC (PROCESS), reports everything, andfixes all that can be fixed.

%DGA#FXAL DGA.SDGAPROC . 0 2345678

2. In this example, IBM Connect:Direct uses list for type SDGAOPLS (OPLIST); and as a result of using alldefaults, reports only errors and fixes nothing.

%DGA#FXAL ‘DGA.SDGAOPLS'

3. In this example,Connect:Direct again uses list for type SDGAOPLS (OPLIST) and all defaults. But in thisscenario, the pds dsn still has the legacy low-level qualifier.

Chapter 1. Release Notes 13

%DGA#FXAL SYS5.CD.OPLIST

4. This example is the same as the previous two examples but the pds dsn has an unsupported low levelqualifier. The following example shows three different ways of coding this scenario.

%DGA#FXAL SYS5.CD.OPERLIST OPLISTor%DGA#FXAL SYS5.CD.OPERLIST SDGAOPLSorExec ‘DGA.SDGAISPC(DGA#FXAL)' ‘ SYS5.CD.OPERLIST SDGAOPLS'

Sample ReportsIn this section, the following two scenarios are demonstrated:

• The first report shows an example of how DGA#FXAL REXX is used to show Connect:Direct errorswithout fixing anything.

• The second report shows how DGA#FXAL REXX is used with Connect:Direct to report everything inSYS5.CD.SDGAMAP and to fix all errors that can be fixed automatically.

The reports are broken into chunks to make them easier to read, and explanations of the reports followthe report samples.

14 IBM Connect:Direct for z/OS: Documentation

Example–Show Errors But Do Not Fix Anything

DGA#FXAL : 5.1.1 PM47625 20 Oct 2011 14:21:06 Command entered : %DGA#FXAL SYS5.CD.SDGAMAP Rexx exec source : CDZ5100.STG1.ISPCLIB(DGA#FXAL) via System-level CLIST DDNAME=SYSPROCReport dsn : USERID.CDFXAL.D2011293.T142106.LIST Pds : SYS5.CD.SDGAMAP Type : MAPLIB DetailLevel : 1 FixLevel : 0 Solo members : 7 TrueNames : 6 Aliases : 14 Orphans : 12 Detail Report - Expected Members | Error Fix | Expected Actual | Expected Actual | | Level Req | Member Status | Alias Status | | ----- --- | -------- -------- | -------- -------- | | 8 | DGAAAER NotInPDS | CDAER Solo | | 7 | DGAACPTR NotInPDS | CDCPTR Alias | | 6 | DGAACTIV NotInPDS | ACTIVITY Orphan | | 9 | DGAACTR Alias | CDCTR TrueName | | 10 | DGAADPTR Alias | CDDPTR NotInPDS | | 11 | DGAADTR Alias | CDDTR Solo | | 1 | DGAAEXEC NotInPDS | EXCEPT NotInPDS | | 12 | DGAAFMCR Alias | CDFMCR Alias | | 13 | DGAAFPTR Alias | CDFPTR Alias | | 2 | DGAANPDS TrueName | NPDSCOPY NotInPDS | | 3 | DGAAPDS Solo | PDSCOPY Orphan | | 14 | DGAAPPSR Alias | CDPSSR Orphan | | 15 | DGAAPTR Orphan | CDPTR NotInPDS | | 16 | DGAARJTR Orphan | CDRJTR Solo | | 17 | DGAARTTR Orphan | CDRTTR Alias | | 4 | DGAARUNJ Solo | RUNJOB Alias | | 5 | DGAARUNT TrueName | RUNTASK Solo | | 18 | DGAASDCR Orphan | CDSDCR Orphan | | 19 | DGAASEC Orphan | SECURITY Orphan | | 1 | DGAASFR NotInPDS | CDSFR NotInPDS | | 1 | DGAASTDC NotInPDS | CDSTDCR NotInPDS | | 1 | DGAASUB NotInPDS | SUBMIT NotInPDS | | 1 | DGAASUM NotInPDS | SUMMARY NotInPDS | Requestable fixes: 7 Detail Report - Unexpected Members | Error Fix | Member Actual | | Level Req | Name Status | | ----- --- | -------- -------- | | 22 | DGAAT7 Solo | | 23 | DGAAT1 TrueName | | 23 | DGAAT2 TrueName | | 24 | DGAAT8 Alias | | 24 | DGAAT1A Alias | | 25 | DGAAT4A Orphan | | 25 | DGAAT9 Orphan |

Chapter 1. Release Notes 15

Summary Report | Error Fix | || Level Req Count | Description Fix Action || ----- --- ----- | ---------------------------------------------- ------------------------ || 0 1 | TRU and ALI or SOL are correct None || 1 5 | TRU and ALI or SOL are not in PDS None || 2 1 | TRU is a TrueName or Solo; ALI is not in PDS Assign ALI || 3 1 | TRU is a TrueName or Solo; ALI is an orphan Delete and re-assign ALI || 4 1 | TRU is a TrueName or Solo; ALI is alien alias Delete and re-assign ALI || 5 1 | TRU and ALI are TrueNames or Solos Delete and re-assign ALI || 6 1 | TRU is not in PDS; ALI is an orphan Delete ALI || 7 1 | TRU is not in PDS; ALI is an alias Delete ALI || 8 1 | TRU is not in PDS; ALI is a TrueName or Solo Delete ALI || 9 1 | TRU is an alias of TrueName ALI None || 10 1 | TRU is an alias; ALI is not in PDS None || 11 1 | TRU is an alias; ALI is a TrueName or Solo None || 12 1 | TRU and ALI are aliases of the same TrueName None || 13 1 | TRU and ALI are aliases of different TrueNames None || 14 1 | TRU is an alias; ALI is an orphan None || 15 1 | TRU is an orphan; ALI is not in PDS None || 16 1 | TRU is an orphan; ALI is a TrueName or Solo None || 17 1 | TRU is an orphan; ALI is an alias None || 18 1 | TRU and ALI are orphans of the same TrueName None || 19 1 | TRU and ALI are orphans of different TrueNames None || 20 | TRU is an alias; ALI is not expected None || 21 | TRU is an orphan; ALI is not expected None || 22 1 | Unexpected member found - Solo None || 23 2 | Unexpected member found - TrueName None || 24 2 | Unexpected member found - Alias None || 25 2 | Unexpected member found - Orphan None | DGA#FXAL ending normally

16 IBM Connect:Direct for z/OS: Documentation

Example–Report Everything and Fix All Fixable Errors

DGA#FXAL : 5.1.1 PM47625 20 Oct 2011 14:50:26 Command entered : %DGA#FXAL SYS5.CD.SDGAMAP . 0 2345678 Rexx exec source : CDZ5100.STG1.ISPCLIB(DGA#FXAL) via System-level CLIST DDNAME=SYSPROC Report dsn : EPETE1.CDFXAL.D2011293.T145026.LIST Pds : SYS5.CD.SDGAMAP Type : MAPLIB DetailLevel : 0 FixLevel : 2345678 Solo members : 7 TrueNames : 6 Aliases : 14 Orphans : 12 Detail Report - Expected Members | Error Fix | Expected Actual | Expected Actual | | Level Req | Member Status | Alias Status | | ----- --- | -------- -------- | -------- -------- | | 8 Yes | DGAAAER NotInPDS | CDAER Solo | | 7 Yes | DGAACPTR NotInPDS | CDCPTR Alias | | 6 Yes | DGAACTIV NotInPDS | ACTIVITY Orphan | | 9 | DGAACTR Alias | CDCTR TrueName | | 10 | DGAADPTR Alias | CDDPTR NotInPDS | | 11 | DGAADTR Alias | CDDTR Solo | | 1 | DGAAEXEC NotInPDS | EXCEPT NotInPDS | | 12 | DGAAFMCR Alias | CDFMCR Alias | | 13 | DGAAFPTR Alias | CDFPTR Alias | | 2 Yes | DGAANPDS TrueName | NPDSCOPY NotInPDS | | 3 Yes | DGAAPDS Solo | PDSCOPY Orphan | | 14 | DGAAPPSR Alias | CDPSSR Orphan | | 15 | DGAAPTR Orphan | CDPTR NotInPDS | | 16 | DGAARJTR Orphan | CDRJTR Solo | | 17 | DGAARTTR Orphan | CDRTTR Alias | | 4 Yes | DGAARUNJ Solo | RUNJOB Alias | | 5 Yes | DGAARUNT TrueName | RUNTASK Solo | | 18 | DGAASDCR Orphan | CDSDCR Orphan | | 19 | DGAASEC Orphan | SECURITY Orphan | | 1 | DGAASFR NotInPDS | CDSFR NotInPDS | | 1 | DGAASTDC NotInPDS | CDSTDCR NotInPDS | | 1 | DGAASUB NotInPDS | SUBMIT NotInPDS | | 1 | DGAASUM NotInPDS | SUMMARY NotInPDS | | 0 | DGAAWTOS TrueName | CDFWTOST Alias | Requestable fixes: 7

Chapter 1. Release Notes 17

Detail Report - Unexpected Members | Error Fix | Member Actual | | Level Req | Name Status | | ----- --- | -------- -------- | | 22 | DGAAT7 Solo | | 23 | DGAAT1 TrueName | | 23 | DGAAT2 TrueName | | 24 | DGAAT8 Alias | | 24 | DGAAT1A Alias | | 25 | DGAAT4A Orphan | | 25 | DGAAT9 Orphan | Summary Report | Error Fix | || Level Req Count | Description Fix Action || ----- --- ----- | ---------------------------------------------- ------------------------ || 0 1 | TRU and ALI or SOL are correct None || 1 5 | TRU and ALI or SOL are not in PDS None || 2 Yes 1 | TRU is a TrueName or Solo; ALI is not in PDS Assign ALI || 3 Yes 1 | TRU is a TrueName or Solo; ALI is an orphan Delete and re-assign ALI || 4 Yes 1 | TRU is a TrueName or Solo; ALI is alien alias Delete and re-assign ALI || 5 Yes 1 | TRU and ALI are TrueNames or Solos Delete and re-assign ALI || 6 Yes 1 | TRU is not in PDS; ALI is an orphan Delete ALI || 7 Yes 1 | TRU is not in PDS; ALI is an alias Delete ALI || 8 Yes 1 | TRU is not in PDS; ALI is a TrueName or Solo Delete ALI || 9 1 | TRU is an alias of TrueName ALI None || 10 1 | TRU is an alias; ALI is not in PDS None || 11 1 | TRU is an alias; ALI is a TrueName or Solo None || 12 1 | TRU and ALI are aliases of the same TrueName None || 13 1 | TRU and ALI are aliases of different TrueNames None || 14 1 | TRU is an alias; ALI is an orphan None || 15 1 | TRU is an orphan; ALI is not in PDS None || 16 1 | TRU is an orphan; ALI is a TrueName or Solo None || 17 1 | TRU is an orphan; ALI is an alias None || 18 1 | TRU and ALI are orphans of the same TrueName None || 19 1 | TRU and ALI are orphans of different TrueNames None || 20 | TRU is an alias; ALI is not expected None || 21 | TRU is an orphan; ALI is not expected None || 22 1 | Unexpected member found - Solo None || 23 2 | Unexpected member found - TrueName None || 24 2 | Unexpected member found - Alias None || 25 2 | Unexpected member found - Orphan None |

Do you wish to attempt the above 7 fixes? Enter YES to attempt, NO to skip: Reply is Y Fix Report Requested fixes: 7 Successful fixes: 7 Failed fixes: 0 | Error | Expected Expected | Del Ren | | Level | TrueName Alias | RC RC Message | | ----- | -------- -------- | --- --- --------------------------- | | 8 | DGAAAER CDAER | 0 ALI deleted | | 7 | DGAACPTR CDCPTR | 0 ALI deleted | | 6 | DGAACTIV ACTIVITY | 0 ALI deleted | | 2 | DGAANPDS NPDSCOPY | 0 ALI assigned | | 3 | DGAAPDS PDSCOPY | 0 0 ALI deleted and re-assigned | | 4 | DGAARUNJ RUNJOB | 0 0 ALI deleted and re-assigned | | 5 | DGAARUNT RUNTASK | 0 0 ALI deleted and re-assigned | DGA#FXAL ending normally

Report ExplanationThe DGA#FXAL report contains the following information.

18 IBM Connect:Direct for z/OS: Documentation

LineNumber /Field /ReportSection Description

Line 1 The release level and maintenance level of DGA#FXAL, as well as the current date andtime.

Line 2 The TSO command the user entered to invoke DGA#FXAL.

Line 3 The REXX exec source dataset and the ALTLIB DISPLAY line for the DGA#FXALinvocation.

Line 4 The DSN of the report dataset.

UtilityParameterOptions

Taken either from the DGA#FXAL parameters or the defaults.

Total Countsper PDSType

The total counts for each of the four types of members in the PDS, where:

• Solo is a member without an alias• TrueName is a member with an alias• Alias is an alias that points to a TrueName• Orphan is an alias that points to a pds member that has been deleted

Detail Report- ExpectedMembers

This report is generated if at least one entry passes detaillevel filtering. For each entryin the DGA#FXAL exec list for the pds type, the actual status of the one or two membernames is determined, and an error level is set based on the results. The error level iscompared to detaillevel, and if it is greater than or equal to it, the detail line is written.

For each detail line, the following information is provided:

• Error Level–A numeric error level. For more information, see “Error Level Explanation”on page 20.

• Fix Req–Yes means a fix was requested for this error level. Else empty.• Expected Member–The first or only member name in the list entry.• Actual Status–One of the four PDS member types or “NotInPds”• Expected Alias–The second member name in the list entry, or empty• Actual Status–One of the four PDS member types, or “NotInPds”, or empty.

The total number of Expected Member detail lines with Yes in the Fix Req column.

Detail Report-UnexpectedMembers

This report is generated if at least one member exists in the pds that is not in theDGA#FXAL list for the pds type. An error level is set based on what kind of pds member itis.

For each detail line, the following information is provided:

• Error Level–A numeric error level. For more information, see “Error Level Explanation”on page 20.

• Fix Req–Always empty.• Member Name–The unexpected member name• Actual Status–One of the four PDS member types.

Chapter 1. Release Notes 19

LineNumber /Field /ReportSection Description

SummaryReport

This report is always generated.

For each possible error level, the following information is provided:

• Error Level–A numeric error level. For more information, see “Error Level Explanation”on page 20.

• Fix Req–Yes means a fix was requested for this error level• Count–The number of times this error occurred• Description–A short description of the error. See below• Fix Action–The action that will be taken to fix the error if Fix Req is Yes

Attempt toFix section

If there are any fixable errors, the attempt-to-fix prompt and the user's response aregiven.

Fix Report If the response was ‘Y', the Fix report is generated, starting with lines giving the numberof fixes requested, successful, and failed, followed by one fix detail line for each fixattempted.

Each detail line provides the following information:

• Error Level–A numeric error level. For more information, see “Error Level Explanation”on page 20.

• Expected TrueName–The first member name in the list entry• Expected Alias–The second member name in the list entry• Del RC– The TSO DELETE command reason code, if it was attempted• Ren RC–The TSO RENAME command reason code, if it was attempted• Message–A description of the results of the attempted fix action

Utilityexecutionstatus

Indicates if the DGA#FXAL ended normally or provides an error message indicatingwhere the utility had a problem in execution, for example, DGA#FXAL ending - cannotALLOC &pds with DISP=OLD where the prefix '&' denotes a variable, which will besubstituted in the actual message.

Error Level ExplanationFor all error level descriptions, the following meanings are in effect:

• SOL–The member name in a list entry that has only one member name• TRU–The 1st member name in a list entry that has two member names• ALI–The 2nd member name in a list entry that has two member names• Solo–A member in pds that has no alias• TrueName–A member in pds that has one or more aliases• Alias–A member in pds that is an alias of a TrueName• Orphan–A member in pds that once was an Alias, but its TrueName no longer exists• Not in PDS–The member was not found in PDS

20 IBM Connect:Direct for z/OS: Documentation

Error Level Description

0 TRU and ALI or SOL are correct. For a list entry with TRU and ALI, TRU is a TrueName andALI is its Alias in pds. For a list entry with SOL, SOL is a non-alias member of pds. No fix isneeded.

1 TRU and ALI or SOL are not in PDS. For a list entry with TRU and ALI, neither one wasfound in pds. For a list entry with SOL, SOL was not found in pds. No automatic fix ispossible.

2 TRU is a TrueName or Solo; ALI is not in PDS. For a list entry with TRU and ALI, TRU wasfound in pds, and it may have one or more aliases, but ALI is not in pds. The fix is toassign ALI as an alias of TRU.

3 TRU is a TrueName or Solo; ALI is an orphan. For a list entry with TRU and ALI, TRU andALI were both found in pds, but though TRU may have one or more aliases, ALI is not oneof them. ALI is an alias of a member that no longer exists. The fix is to delete ALI, thenre-assign it as an alias of TRU.

4 TRU is a TrueName or Solo; ALI is alien alias. For a list entry with TRU and ALI, TRU andALI were both found in pds, but though TRU may have one or more aliases, ALI is not oneof them. ALI is an alias of another (i.e. an alien) TrueName. To find out what that alienTrueName is, invoke the TSO command “LISTDS pds MEM” and look for ALI in each aliaslist. The fix is to delete ALI, then re-assign it as an alias of TRU.

5 TRU and ALI are TrueNames or Solos. For a list entry with TRU and ALI, TRU and ALI wereboth found in pds. TRU may have one or more aliases, but ALI is not one of them. ALI is aSolo or TrueName member. The fix is to delete ALI, then re-assign it as an alias of TRU.

Note: if ALI has any aliases, they will be orphaned.

6 TRU is not in PDS; ALI is an orphan. For a list entry with TRU and ALI, TRU was not foundin pds. ALI is an alias of a member that no longer exists. The fix action is to delete ALI,though that only cleans up the orphan alias. Automatic recovery of the member is notpossible.

7 TRU is not in PDS; ALI is an alias. For a list entry with TRU and ALI, TRU was not found inpds. ALI is an alias of another TrueName. The fix action is to delete ALI, though that onlycleans up the alias. Automatic recovery of the member is not possible.

8 TRU is not in PDS; ALI is a TrueName or Solo. For a list entry with TRU and ALI, TRU wasnot found in pds. ALI is a Solo or TrueName member. The fix is to delete ALI, though thatonly cleans up the incorrect Solo or TrueName member.

Note: if ALI has any aliases, they will be orphaned.

Automatic recovery of the member is not possible.

9 TRU is an alias of TrueName ALI. For a list entry with TRU and ALI, TRU and ALI were bothfound in pds. ALI should be the alias and TRU should be the TrueName but, instead, theirrelationship is reversed. No automatic fix is supported.

10 TRU is an alias; ALI is not in PDS. For a list entry with TRU and ALI, TRU is an alias insteadof a TrueName, and ALI was not found. No automatic fix is supported.

11 TRU is an alias; ALI is a TrueName or Solo. For a list entry with TRU and ALI, TRU is analias instead of a TrueName, and ALI is a TrueName or Solo, instead of an alias of TRU.TRU is not an alias of ALI. No automatic fix is supported.

12 TRU and ALI are aliases of the same TrueName. For a list entry with TRU and ALI, TRUis an alias instead of a TrueName, and ALI is an alias of the same TrueName as TRU. Noautomatic fix is supported.

Chapter 1. Release Notes 21

Error Level Description

13 TRU and ALI are aliases of different TrueNames. For a list entry with TRU and ALI, TRU isan alias instead of a TrueName, and ALI is an alias of a different TrueName. No automaticfix is supported.

14 TRU is an alias; ALI is an orphan. For a list entry with TRU and ALI, TRU is an alias insteadof a TrueName, and ALI is an alias of a member that no longer exists. No automatic fix issupported.

15 TRU is an orphan; ALI is not in PDS. For a list entry with TRU and ALI, TRU is an alias ofa member that no longer exists instead of a TrueName, and ALI was not found in pds. Noautomatic fix is supported.

16 TRU is an orphan; ALI is a TrueName or Solo. For a list entry with TRU and ALI, TRU is analias of a member that no longer exists instead of a TrueName, and ALI is a member withzero or more aliases instead of an alias of TRU. No automatic fix is supported.

17 TRU is an orphan; ALI is an alias. For a list entry with TRU and ALI, TRU is an alias ofa member that no longer exists instead of a TrueName, and ALI is an alias of anotherTrueName instead of an alias of TRU. No automatic fix is supported.

18 TRU and ALI are orphans of the same TrueName. For a list entry with TRU and ALI, TRUand ALI are aliases of a single member that no longer exists instead of a TrueName. Noautomatic fix is possible.

19 TRU and ALI are orphans of different TrueNames. For a list entry with TRU and ALI, TRU isan alias of a member that no longer exists and ALI is an alias of a different member thatno longer exists. No automatic fix is supported.

20 TRU is an alias; ALI is not expected. For a list entry with TRU only, TRU is an alias insteadof a TrueName. No automatic fix is supported.

21 TRU is an orphan; ALI is not expected. For a list entry with TRU only, TRU is an alias of amember that no longer exists instead of a TrueName. No automatic fix is supported.

22 Unexpected member found - Solo. A Solo member was found in pds that does not appearin any list entry. No automatic fix is supported. This may or may not be an error.

23 Unexpected member found - TrueName. A TrueName member was found in pds thatdoes not appear in any list entry. No automatic fix is supported. This may or may not bean error.

24 Unexpected member found - Alias. An alias was found in pds that does not appear in anylist entry. No automatic fix is supported. This may or may not be an error.

25 Unexpected member found - Orphan. An alias of a member that no longer exists wasfound in pds that does not appear in any list entry. No automatic fix is supported.

Migrating CICS from Prior ReleasesCICS uses different program names, map names, and transaction IDs. Refer to Activate the CICSComponent in IBM Connect:Direct for z/OS CICS Administration and User Guide before continuing.

To use the current CONFIG file contents:

1. Shut down the IBM Connect:Direct interface in the CICS region.2. To close the CONFIG file so that the buffers are committed and written, issue CICS commands, for

example, CEMT SET FILE(CONFIG) CLOSE.3. Using IDCAMS, perform a REPRO of the CONFIG file to a new CONFIG file.4. To reactive CICS, restart the API interface.

22 IBM Connect:Direct for z/OS: Documentation

5. In a different CICS system, once the RDO updates have been applied and the Connect:Direct forz/OS Version 5.1 CICS modules loaded, run the Administrator transaction (DGAA) and go to theConfiguration screen.

Go to the Control Record screen to set the Transaction codes to reflect the changes made to the RDOsource $CD.SDGACNTL(DGACCSD).

Enter the CDA transaction and start the interface.6. Complete the CICS panels following the instructions in the procedure Build the CICS Configuration File

through ISPF in IBM Connect:Direct for z/OS CICS Administration and User Guide.

Upgrading Connect:Direct File AgentTo take advantage of the command line in this version of Connect:Direct File Agent, modify the Javacommand line parameters after you install it.

If you are upgrading from an existing version:

Note: Files recorded in the checkpoint file are treated as if the new command line parameters had beenactive when the files were first discovered. You do not have to delete the checkpoint file.

1. Install Connect:Direct File Agent into an empty directory.2. Copy the .ser and .ckpt files from the old to the new installation directory.3. Rename the old installation directory to an archive name.4. Rename the new installation directory to the primary name.

Chapter 1. Release Notes 23

24 IBM Connect:Direct for z/OS: Documentation

Chapter 2. Configuration Guide

Before you InstallInstallation is easier and more effective if you complete your planning before you begin.

Before you begin your installation:

1. Read the IBM Connect:Direct for z/OS Release Notes for the latest product information.2. Verify hardware and software requirements. Review Installation Requirements for hardware and

software requirements.3. Determine whether your system uses a Multi-Image Manager (MIM) or Global Resource Serialization

(GRS) system.

Installation RequirementsConnect:Direct for z/OS requires the following hardware and software. However, this is not a complete list.See the Program Directory for the complete list of requirements, and for more information on several ofthe items listed below:

• Authorized Library - Connect:Direct for z/OS must run from an APF-authorized library. If it is notauthorized, you receive message SITA117I during initialization, and it terminates.

• Connect:Direct for z/OS VSAM space requirements - For information, see VSAM Files DASD Requirementand Description

• High-Level Assembler - High-Level Assembler is required to assemble the sample Connect:Direct forz/OS exits in the SDGASAMP dataset.

• TSO with ISPF/PDF - You must have IBM Time Sharing Option (TSO) with ISPF version 6.0 or later.• SNA Network Requirements - Network support for Connect:Direct for z/OS requires both of the

following: VTAM Communications Server and IBM Advanced Communications Functions for NetworkControl Program (NCP)

• IBM Connect:Direct Spool Transfer - If you use the Spool Transfer feature for outbound spool transfers,you must have LRS (Levi, Ray, and Schoup, Inc.) VTAM Printer Support System (VPS) Release 6.2 orlater, Version 1.12 or later and LRS VPS/CDI Option installed. No additional software is required forinbound transfers.

• The CICS Interface - If you use the CICS interface, you must have at least 200 tracks of 3390 disk spaceavailable and be using CICS/TS version 3.01.00 or higher.

• All other requirements as listed in the Program Directory for IBM Connect:Direct for z/OS.

VSAM Files DASD Requirement and DescriptionUse IBM Connect:Direct VSAM files during testing, and migrate previous versions of the files as part of theproduct release implementation.

Note: If you use VSAM cache utilities, remove IBM Connect:Direct VSAM files from their control orunpredictable results may occur.

IBM Connect:Direct uses VSAM files to control and monitor execution. The following table describes thefiles and space requirements built during the configuration process. These values represent the minimumspace requirement for each VSAM file.

© Copyright IBM Corp. 1993, 2021 25

dataset DSORG Approx. InstallSupplied Size

Number ofEntries

Approx.MinimumSize

MinimumPrimaryEntries

BLK SIZE(CI)

AUTH KSDS 132 KB 100 88 KB 5 4096

CKPT KSDS 600 KB 40 44 KB 5 4096

MSG KSDS 3 MB 12000 3 MB 12000 4096

NETMAP KSDS 88 KB 50 88 KB 2 4096

STATS archive directory1 ESDS 88 KB 500 88 KB 500 4096

STATS index1 KSDS 222 KB 5000 88 KB 750 4096

STATS index22 KSDS 222 KB 5000 88 KB 750 4096

STATS log1 ESDS 1.8 MB 6750 197 KB 1000 4096

STATS log22 ESDS 1.8 MB 6750 197 KB 1000 4096

TCQ RRDS 200 KB 100 44 KB 21 1536

TCX RRDS 44 KB 1 44 KB 1 1024

TYPE KSDS 88 KB 20 88 KB 5 4096

CONFIG3 KSDS 44 KB 1 44 KB 1 2048

USRPROF3 KSDS 144 KB 1 144 KB 1 4096

EVENT3 KSDS 44 KB 1 44 KB 1 2048

TOTAL 8.6 MB 4.4 MB

1. Optional dataset.2. The default configuration for the Statistics facility uses two statistics file pairs, which requires four

VSAM files. Refer to “Statistics Files” on page 28 below for details about the VSAM files.3. Optional IBM Connect:Direct-CICS IUI facility file.

Authorization File (AUTH)The Authorization file, a VSAM KSDS, can contain a record for each authorized IBM Connect:Direct user.If you use the IBM Connect:Direct Authorization Facility, calculate the size of your Authorization filerequirements using the following formula:

Number of IBM Connect:Direct Users X 100 Bytes = Size of Authorization File

If you are not using the IBM Connect:Direct Authorization Facility, you still define an Authorization file.

Checkpoint File (CKPT)The Checkpoint file is a VSAM KSDS that contains checkpoint information generated by the DTF duringexecution of a copy operation. The Checkpoint file consists of variable length records, one per Processthat has checkpointing specified. The average record length is 256 bytes. The equivalent of one cylinderof space is allocated during the installation. The size of the Checkpoint file can be influenced by thenumber of days you retain checkpoint information according to the initialization parameter, CKPT.DAYS.

IBM Connect:Direct for z/OS Message File (MSG)The Message file, a VSAM key-sequenced dataset (KSDS), holds all messages, except ISPF panel-relatedmessages, used by IBM Connect:Direct. Each message record contains the issuing module name, shortmessage text, and message explanation.

26 IBM Connect:Direct for z/OS: Documentation

Network Map File (NETMAP)The network map file is a VSAM KSDS that contains network definition information, including the networknames for the local node and other (adjacent) nodes in the network, the communication addresses for useby the API, and various control information used by IBM Connect:Direct

To estimate the size of the network map, you must determine how many nodes are needed and thecommunications used for each node. This includes determining the node IDs for your network (includingthe local node name), all APPLIDs (SNA type), and all TCP/IP addresses (or DNS names) for the nodes.

The following chart defines the basic size of records for planning how large to make the network map:

Record Size (inbytes)

Description/Comments

Control Records 250 Base records for NDM control

ADJACENT.NODE 124 Basic adjacent node information

ALT.COMM 32 + 59(n) Alternate communications addresses. Each set adds 1 to “n”.

LDNS 278 Holder of the DNS name for an ADJACENT.NODE

CONTACT/

COMMENTS

74 + x 1 per node definition and each segment (x) adds up to:

Conact Name - 40, Phone - 40, Description - 255

IPv6 232 This record exists for an ADJACENT.NODE if the node is defined withany of the following items specified:

• IPv6 address for TCP/IP• the API record specifies an IPv6 record• SOURCEIP is specified.

UDT 96 UDT support has been removed. Please update your Netmap todelete all UDT ADJACENT NODEs.

TCP API 60 Used to specify the address for API

APPLIDs 40 + 8x SNA APPLIDs for a node. Add 1 to x for each node ID specified

xNODE.LUS 28 + 8(x) If either PNODE or SNODE.LUS is specified, add 1 to x for each nodename specified.

Node Usage 1024 1 US record for each Adjacent Node

For example, if the network map contains 25 nodes with API APPLIDs in each of the 25 nodes, it requiresapproximately the space illustrated in the following table.

Netmap Definitions Number Size (in bytes)

Control Records + Local node 3 362

ADJACENT.NODE 25 3100

APPLIDs 25 nodes with 20 APPLIDs 5350

Node Usage 25 25600

Total 78 records 34412

For those installations that make frequent updates to the network map, it is recommended that theallocation be done on a cylinder boundary and be at least one cylinder more than currently needed. CA/CIsplits may take place as additions and updates are done.

Chapter 2. Configuration Guide 27

Statistics Directory of Archive FilesAllocate the STATS Archive Directory file if you plan to archive statistics records and maintain a directoryof the archive files. Archiving is the process of copying statistics records from the IBM Connect:Directstatistics files to other datasets for long-term storage.

Use the directory to track the dataset names of the archive files, and the date and time range of thestatistics records the archive files contain. Each record in the directory contains information about a singlearchive file. Therefore, the value of the RECORDS parameter that defines the directory determines howmany archive files can be represented in the directory. Connect:Direct for z/OS provides facilities formaintaining and displaying the directory through the INQUIRE STATDIR command.

Statistics FilesThe Statistics facility logs statistics to VSAM file pairs. Each file pair consists of the following:

• A VSAM entry-sequenced cluster• A VSAM key-sequenced cluster

The default and minimum configuration uses two such file pairs, making four VSAM files. The maximumnumber of file pairs you can use is twenty. Specify the number of file pairs and the VSAM cluster nameswith the STAT.DSN.BASE and STAT.FILE.PAIRS initialization parameters.

The RECORDS parameter of the Access Methods Services DEFINE command for the ESDS clusterspecifies the maximum number of records each file pair can contain. The maximum number of statisticsrecords available is the sum of the values in the RECORDS parameters for all the statistics ESDS clusters.For example, if you determine that your system needs space for 15,000 statistics records, you can definethree file pairs containing 5,000 records each, or two file pairs containing 7,500 records each.

Note: IBM Connect:Direct does not support extended-format, extended-addressing ESDS Statisticsdatasets.

Within each file pair, IBM Connect:Direct writes statistics records to the ESDS cluster. IBM Connect:Directuses the KSDS cluster to maintain index information about the records in the ESDS. Whenever either fileof the pair becomes full, the entire pair is considered full, and the system initiates a switch to the next pairin the sequence. Because the file pair is full when one file fills to capacity, it is important that you size theESDS and KSDS in a file pair appropriately, relative to each other. Specifying appropriate file sizes reducesthe waste of excessive space.

Statistic File Recommendation

The following tables describes minimum, optimum and maximum values for the VSAM attributes thatimpact the statistic file space and its performance.

CI Size Minimum Size Optimum Size Maximum Size

ESDS (D) 2048 32768 32768

KSDS (D) 4096 4096 32768

KSDS (I) 2560 4096 32768

BUFSP (Cluster) Minimum Size Optimum Size Maximum Size

ESDS (D) 2 * CI size (D) 2 * CI size (D) Storage Limit

KSDS (D) 2 * CI size (D) +

1 * CI size (I)

2 * CI size (D) +

1 * CI size (I)

Storage Limit

Note: The actual maximum BUFSP is limited by your system’s storage constraints. DEFINE allows you tospecify BUFSP(16000000), but most programs would ABEND when they OPEN the file.

28 IBM Connect:Direct for z/OS: Documentation

Note: Decreasing the BUFSP below the optimum size can cause significant performance degradation.Increasing the BUFSP far above the optimum provides no noticeable gain in performance. However,increasing it a little above the optimum provides some extra headroom.

The frequency with which IBM Connect:Direct writes records to the KSDS cluster of a file pair dependson usage patterns at each site and the ESDS CI size. The greater the ESDS CI size, the fewer records IBMConnect:Direct writes to the KSDS. However, a larger ESDS CI size also requires more statistic file bufferstorage in the IBM Connect:Direct address space.

The following table summarizes results from running the KSDS rebuild program against ESDS clusters ofvarious CI sizes. Each ESDS cluster was defined with the optimum BUFSP for its CI size, and each clustercontained identical statistic records. These results are suggestive of the performance differences dueto ESDS CI size which the DTF will experience when writing statistics records and reading them for theSELECT STATISTICS command.

ESDSrecords

KSDS CI sizeData/Index

ECDS CISize

KSDSrebuildrecords

(CD 5.2)

KSDSrebuildrecords

(CD 6.0)

KSDSrebuild time

(CD 5.2)

KSDSrebuild time

(CD 6.0)

1,104,668 4K/4K 4K 705,573 1,360,564 08:26.46 15:33.28

1,104,668 4K/4K 8K 444,153 801,803 04:27.59 08:55.59

1,104,668 4K/4K 16K 282,623 477,526 02:57.60 05:28.93

1,104,668 4K/4K 32K 185,465 288,592 01:41.31 03:15.31

The default configuration provides space for 13,500 statistics records evenly divided between two filepairs. The minimum configuration provides space for 2,000 statistics records. The amount of activity inthe IBM Connect:Direct system determines how frequently the statistics file pair list wraps around. It isrecommended that you estimate your activity rate and allocate enough space so that the system recordsseveral days of records before a wraparound occurs. After running IBM Connect:Direct for several days,you may need to adjust the number or sizes of the statistics files to allocate the right amount of space.

Transmission Control Queue (TCQ) and Index (TCX)The Transmission Control Queue (TCQ) is a VSAM RRDS file that stores Processes that are:

• Executing• Queued for execution• Held for retries• Held for future execution• Retained for reporting

The TCQ index (TCX) is also a VSAM RRDS file. It consists of a record that is a map for controlling theallocation of space in the TCQ.

The control interval (CI) size of the TCQ is from 1,536 to 30,720 bytes. Each Process defined in the TCQoccupies one or more CIs, depending on the number of statements within the Process. Because TCQaccess characteristics prohibit secondary allocation, be sure to allocate enough space for the maximumnumber of potential Processes when you define the TCQ.

The TCX controls space use and access to the TCQ. The TCX average and maximum record sizes shouldbe defined as the CISIZE - 7. To maximize the number of usable TCQ CIs, allocate a record size of 30,713and a CI of 30,720 to the TCX since it occupies only one track. IBM Connect:Direct will use the number ofCIs in the TCQ (rounded down to a multiple of 8) or 65536, whichever is smaller.

The largest TCQ that can be allocated and used is 2621 cylinders, on 3390 DASD device, with a CI sizeof 30,720 and a record size of 30,713. This size can accommodate 65,520 Processes in the queue if nosingle Process exceeds 30,713 bytes in its internal format.

Chapter 2. Configuration Guide 29

The following formula shows the number of CIs that can be controlled:

Maximum number of TCQ CIs = ((TCX Max Record Size - 12) / 2) * 8

In the default TCX definition, the definition of the TCX CI Size is 1,024 bytes; maximum record size is1,017. Substituting the default maximum record size of 1,017 bytes in the formula results in 4,016 TCQ CIrecords, as shown in the following calculation:

Maximum number of TCQ CIs = ((1,017 - 12) / 2) * 8 = 4,016

Using the default TCX definition, you can define the TCQ with up to 4,016 records, thereby allowing theTCQ to hold up to 4,016 Processes, depending on the number of statements in each Process. However,the default definition for the TCQ specifies 1,000 TCQ CIs but actually holds only about 500 simpleone-step Processes).

CAUTION: Depending on your hardware configuration and load, it can take a long time to warmstart IBM Connect:Direct with thousands of Processes in the TCQ. In general, it takes about 1minute for every 1000 Processes.

Note: If you plan to use the Process retention feature, the size of the TCQ and TCX datasets should beincreased, in addition to the factors you consider when determining space requirements for datasets.

Enlarging the TCQTo enlarge the TCQ:

1. AVERAGE PROCESS SIZE. Determine the size of the average Process for your site. To do this, you needto know the type and average number of steps in your average Process. Use the following table tocalculate the TCQ space needed for your average Process. Take the number of steps and multiply thatby the number of bytes for the Process component, then add the number of bytes for a Process header(1,616). If you do not know what the average Process looks like, assume that the average Processcontains five COPY steps:

Process Component Number of Bytes

Process Header 1,616

COPY Step 1,024

RUN TASK 128

RUN JOB 176

GOTO Step 96

EXIT Step 96

IF Statement 208

For example, if the average Process contains five COPY steps, the space required would be 1,616 + (5* 1,024) = 6,736 bytes.

Note: The largest Process can contain up to 1 MB and must fit within 43 TCQ records. A TCQ CISIZE of24 KB is sufficient to hold the maximum size Process.

2. TCQ CISIZE. Calculate the appropriate TCQ CI size that should be defined for the average Process. Thelarger the TCQ CI size, the fewer I/O operations have to be done to read/write the TCQ entry. Ideally,the average Process should fit in a single TCQ entry, but if the average Process is greater than 30 KB,then select a TCQ CI size of 30 KB.

3. TCQ CIs PER PROCESS. Calculate the number of TCQ CIs required for a single Process. For example, ifthe average Process is 36 KB and you use a TCQ CI size of 30 KB, then each Process takes 2 TCQ CIs.

4. NUMBER OF PROCESSES. Calculate the number of Processes you expect to be in the TCQ at any onetime, including Processes that are waiting for a connection or their turn to execute, Processes thatare executing, Processes that have been held, and Processes that are going through retry. Double ortriple this number, then multiple this number by the number of TCQ CIs required for each Process. For

30 IBM Connect:Direct for z/OS: Documentation

example, if you think that you'll have no more than 100 Processes in the queue at any one time, use200 or 300 for the number and multiply it by the number of TCQ CIs required by each Process.

5. TCQ RECORDS. The result of this calculation is the number of records and CISIZE that should bedefined in the TCQ VSAM definition. The average and maximum record size should be the CISIZE - 7.

6. TCX CISIZE. Now, make sure that the TCX definition will be able to map this number of TCQ entries.Take the number of records from Step 5, divide by 4, and add 12. Then, to obtain the average andmaximum record size for the TCX VSAM definition, round this number up to the next valid CI Size(minus 7)

Assume that the average Process consists of 10 COPY steps, 10 IF statements and 10 RUN TASKstatements and you want to allocate space to hold 1,000 of these Processes:

AVERAGE PROCESS SIZE: 1,616 + (10 * 1,024) + (10 * 208) + (10 * 128) = 15,216

TCQ CISIZE: 16,384 (good value that would hold a complete average Process)

TCQ CIs PER PROCESS: 1

NUMBER OF PROCESSES: 1,000

TCQ RECORDS: 1,000

TCX CISIZE: 512 (this would map up to (( 512 - 7 - 12) / 2 * 8) = 1,968 TCQ RECORDS)

Note: If you change the TCX or TCQ definitions, you must COLD start the TCQ.

Type File (TYPE)The Type file is a VSAM KSDS that consists of records containing file attribute defaults for the destinationfile allocations specified in the IBM Connect:Direct Copy statement. For information on the Type filecontents, see Maintaining the Type File in the IBM Connect:Direct for z/OS Administration Guide.

CICS FilesThe following three files are optional IBM Connect:Direct-CICS IUI facility Files:

• CICS Configuration File (CONFIG) - The Configuration file is used by the CICS IUI facility of IBMConnect:Direct-CICS only. It is a VSAM KSDS file. One file exists and is allocated for each CICSregion. It is primed during IBM Connect:Direct-CICS installation and updated online through IBMConnect:Direct-CICS administrator functions. This file contains system parameters that control the IBMConnect:Direct-CICS environment. It also contains information about the IBM Connect:Direct nodesavailable to the IBM Connect:Direct-CICS and their network map definitions. Installed with defaultdataset name $CDVAM.CONFIG.

• CICS User Profile File (USRPROF) - The User Profile or Signon Defaults file is allocated to the CICSregion. It is a VSAM KSDS file with the CICS Userid as key. It is updated using the signon defaultsfunction and used to set up auto-signon to IBM Connect:Direct Installed with default dataset name$CDVAM.USRPROF

• CICS Event Restart File (EVENT) - The Event Restart file is used by the Event Services Support featureof IBM Connect:Direct. One file exists for each CICS system and is allocated to the CICS region. It isupdated by the Event Services Support function, and is used for restarting ESS. Installed with defaultdataset name $CDVAM.EVENT

Virtual Storage RequirementsConnect:Direct for z/OS executes with a REGION of 0 MB allocated for most environments. Using thedefault limits for the IEFUSI exit, IBM Connect:Direct may have enough virtual storage both above andbelow the line to run many Processes concurrently. However, your results may vary depending on thedata type, block sizes, compression, communication buffer sizes, and other factors. IBM Connect:Directstorage requirements also depend on the initialization parameters that you specify and the type ofProcess work being performed. In some cases, you may need to increase the size of the REGION orstorage limits.

Chapter 2. Configuration Guide 31

Note: Connect:Direct for z/OS may use above-the-bar storage. The in-storage trace table defaults to 2 MBabove the bar storage, and is controlled by the TRACE.BUFFER initialization parameter. Each zFBA COPYstep uses 32 MB of page-fixed above-the-bar storage for the duration of the step.

Specifying REGION=0M eliminates the need to determine the REGION needed, and does not use anymore virtual storage than specifying just the needed amount.

The following initialization parameters affect storage allocation below and above the 16 MB line:

Parameters Description

MAXUSER (default 6)

MAXPRIMARY (default 6)

MAXSECONDARY (default 6)

MAXPROCESS (default 12)

These parameters determine the number of tasks that IBMConnect:Direct supports. Storage is obtained during initializationand remains for the duration of the JOB or started task. For eachtask, approximately 2 KB is allocated above the line and 1 KBbelow the 16 MB line.

V2.BUFSIZE (default 32K,128K) The first positional parameter specifies the default maximumbuffer size that IBM Connect:Direct uses for LU6.2 and TCP/IPdata transmission. The default is 32K. (K means thousands ofbytes.) The second positional parameter is used to alter theTCP/IP send and receive buffer sizes within TCP/IP.

In general terms, the second positional parameter should be atleast the same and not less than the first parameter and shouldbe big enough to handle the largest V2.BUFSIZE override from thenetmap. A good common practice is to have the second parameterbe a multiple of the first parameter and at least twice or more thanthe first parameter.

TCP (default NO) The TCP parameter affects the program storage required. Thisparameter allocates approximately 3280 KB above and 112 KBbelow the 16 MB line.

ALLOCATION.EXIT

RUN.JOB.EXIT

RUN.TASK.EXIT

SECURITY.EXIT

STATISTICS.EXIT

These exits are loaded at initialization and reside below the 16 MBline. The default value for these parameters is no exit. Samplesare provided and described in the IBM Connect:Direct for z/OSAdministration Guide.

STAT.QUEUE.ELEMENTS (default1500)

Stat queue elements are 2 KB each and allocated above the 16MB line.

MAXSTGIO (default 1M,1M) This parameter limits the amount of I/O buffers for each COPY.The I/O buffers are allocated above the 16 MB line.

The following example shows reasonable settings for these initialization parameters:

MAXUSER=26MAXPRIMARY=50MAXSECONDARY=50MAXPROCESS=100MAXSTGIO=(1M,1M)V2.BUFSIZE=32KTCP=OESALLOCATION.EXIT=exitnameSECURITY.EXIT=exitnameSTATISTICS.EXIT=exitnameSTAT.QUEUE.ELEMENTS=999TRACE.BUFFER = 2 (default)

32 IBM Connect:Direct for z/OS: Documentation

Storage Requirements in a IBM Connect:Direct Plex EnvironmentIn a IBM Connect:Direct Plex environment, additional storage is allocated based on the number ofservers that the IBM Connect:Direct Manager can support. The maximum number of servers that a IBMConnect:Direct manager can support is 32. The IBM Connect:Direct Manager allocates approximately510K above the 16 MB line for each server, regardless of whether the server is active or not.

Note: The IBM Connect:Direct Manager allocated storage to support and manage 32 servers, which is notneeded for most environments resulting in inefficient usage of storage space. The CDPLEX.MAXSERVERglobal initialization parameter will control the maximum number of servers with the default being 4. If youhave more than 4 servers in your environment, you must specify the number needed or you will receive anerror. For more information, see “Condition: Server Initialization Error (SXTA101I) with ABEND U1024” onpage 79 and the information on the CDPLEX.MAXSERVER parameter in the IBM Connect:Direct for z/OSAdministration Guide.

To calculate the amount of virtual storage above the line allocated for the queue holding the statisticsrecords, the IBM Connect:Direct/Plex Manager multiplies the value for the STAT.QUEUE.ELEMENTS globalinitialization parameter by the maximum number of servers. If the resultant calculation is less than 5000,5000 is used. If it is greater than 10000, 10000 is used. Each element takes 2048 bytes of storage.

Check the REGION parameter on the job card and specify REGION=0M.

Preparing TCP/IP Configuration (Optional)Read this section if you are using TCP/IP support. IBM Connect:Direct supports IBM TCP/IP, Open EditionSockets Interface, which you specify by using the OES value for the TCP initialization parameter. SeeGlobal Initialization Parameters. Review the NETMAP.CHECK parameter to determine if your site performsnetwork map checking on TCP/IP nodes.

TCP/IP SupportThe following procedures relate to the implementation of TCP/IP only:

• The HLQ.PROFILE.TCPIP dataset contains system operation and configuration information for theTCP/IP address space. The PORT statement reserves a port for a given user ID and identifiesthe protocol to be used on that port. It is not required that you reserve a port number for IBMConnect:Direct.

• To verify that a connection between nodes can be established, use the TCP/IP PING command. ThePING command sends an echo request to a foreign host to determine if the computer is accessible.

• To verify that a connection exists to the remote IBM Connect:Direct, issue the following command:

TELNET ip-address,port-number

IBM Dynamic Virtual IP Address (Dynamic VIPA) SupportIBM SecureWay Communications Server provides for dynamic virtual IP addresses (dynamic VIPA). Thisfeature enables you to define a TCP/IP stack so that a TCP/IP address is dynamic and exists only when theapplication that defines it is active. Following is an example:

:VIPADynamic VIPARange DEFINE address_mask network_prefixENDVIPADynamic:

Note: Refer to IBM documentation for options and definitions.

To use Dynamic VIPA for IBM Connect:Direct, define a unique VIPA for each IBM Connect:Directinstance. An instance of IBM Connect:Direct is an “application” per the IBM SecureWay Communications

Chapter 2. Configuration Guide 33

documentation. When that instance is active, it defines the VIPA address, and when it terminates, itdeactivates the VIPA address.

For IBM Connect:Direct Extended Recovery, define VIPA requirements the same way, but you must definethe dynamic VIPA range in each TCP/IP stack. Each IBM Connect:Direct node must have a unique VIPA,meaning that in a IBM Connect:Direct/Plex environment, the manager and each server must have aunique VIPA to bind to. For HOT recovery, the standby server may have the same VIPA as the primary. Thestandby will not use the VIPA until it becomes the active server. In this way, it does not violate the VIPArules as defined by IBM SecureWay Communications documentation.

Implementing TCP Stack AffinityConnect:Direct for z/OS supports TCP/IP connectivity through multiple TCP/IP stacks and does not setstack affinity to any particular TCP/IP stack. You might want to run multiple TCP/IP stacks on the samesystem to provide network isolation for one or more of your applications. Establishing TCP/IP stack affinitybinds all TCP/IP socket communications to that stack, which in turn allocates the proper host domainname resolution configuration datasets to IBM Connect:Direct. These datasets enable host name lookupsto have the desired results.

If TCP/IP stack affinity is required, you must specify the stack using one of the following methods:

• Define the IP addresses and ports specified in the TCP.LISTEN initialization parameter to a particularTCP/IP stack using CINET

• Add the following step to the IBM Connect:Direct started task JCL before executing the DMINITinitialization module:

STEP 0 EXECUTE PGM=BPXTCAFF,PARTM=TCP_Stack_Name

Global TCP/IP SOURCEIP

Global TCP/IP SOURCEIP for Stand Alone ServersThe IBM Connect:Direct Server binds a local socket for out-bound processes and the default is to bind tothe HOST IP as returned by BPX1HST (gethostid/gethostname) function. The HOST name is used for SMFreporting in the SESSION.HIGHWATER.SMF record. The HOST IP will become the local IP for the node.

To allow more control over the HOST IP assignment, the TCP.SOURCEIP initialization parameter can beused to specify the IP for default or global source IP. The intent of TCP.SOURCEIP is to define a globaldefault IP address that the Connect:Direct for z/OS server can bind to for out-bound IP processes so thateach individual NETMAP entry does not require the SOURCEIP parameter unless there is a requirement tooverride the default. An outbound process will bind to an IP obtained from the following places:

• NETMAP SOURCEIP parameter• TCP.SOURCEIP INITPARM• Hostname

TCP.SOURCEIP does not support ANYADDR or 0.0.0.0 as source IP, so to provide compatibility withprevious releases, which assigned the local or host IP differently, TCP.SOURCEIP=1STLISTEN is availableto modify the default. 1STLISTEN will cause Connect:Direct for z/OS to use the first IP in the TCP.LISTENparameter list instead of the IP returned by BPX1HST. If the first IP in TCP.LISTEN is ANYADDR or 0.0.0.0,the bind function will select the first IP in the TCP stack, usually the stack home address.

Note: Services do not currently exist to obtain a hostname for IPv6.

Global TCP/IP SOURCEIP for CD/PLEX ServersSince CD/PLEX servers can run on multiple LPARs, each with its own TCP/IP stack, a different approachmust be used for a global source IP. Normal defaults will assign a different HOST IP for the manager

34 IBM Connect:Direct for z/OS: Documentation

and each server based on the local TCP/IP stack. The TCP.SOURCEIP initialization parameter override thisTCP/IP restriction.

However, IBM TCP/IP provides a feature called Distributed DVIPA that allows a single Dynamic VIPAaddress to be shared across TCP stacks and LPARs in a Sysplex. Please refer to “z/OS CommunicationServer: IP Configuration Guide” for information about Distributed DVIPA. With Distributed DVIPAconfigured for all TCP/IP stacks in a Sysplex and the Distributed DVIPA address included in TCP.LISTEN,TCP.API.LISTEN and TCP.SOURCEIP, the CD/PLEX manager and servers can use the same IP for primaryand backups (Extended Recovery) and can be moved to any LPAR in the Sysplex as needed.

Exploit z/OS Encryption Readiness Technology (zERT)

IBM Connect:Direct with Secure Plus option can exploit z/OS Encryption Readiness Technology (zERT)capability provided by the z/OS V2R3 Communications Server. With zERT, the TCP/IP stack acts as a focalpoint in collecting and reporting the cryptographic security attributes of IPv4 and IPv6 application trafficthat is protected using the TLS/SSL, SSH and IPSec cryptographic network security protocols. For moreinformation, see z/OS® Encryption Readiness Technology for details and requirements.

Security PlanningIBM Connect:Direct supports signon security checking through its own Authorization Facility and throughsecurity exits interfacing with CA-ACF2 and CA-TOP SECRET by Computer Associates International, Inc.,and Resource Access Control Facility (RACF) by IBM. Any of these packages can control access to IBMConnect:Direct functions. Read Implementing Security in the IBM Connect:Direct for z/OS AdministrationGuide.

If your system has z/OS UNIX System Services and RACF Program Control turned on, every JOBLIB/STEPLIB/LINKLIB DSN in the IBM Connect:Direct startup must be in the appropriate RACF ProgramControl list for HFS support to work correctly. If not, z/OS UNIX System Services considers the addressspace “dirty,” and setting thread-level security (which HFS support uses) fails with 0000008B xxxx02AF.IBM Connect:Direct initialization fails with the message SITA997I.

Note: The SP Admin tool is unable to open a Secure parameter file created prior to release 5.2.0. See“DGASCONV – Secure Parameter File Conversion Utility” on page 665 for more information.

Extended Submit Facility (ESF)The Extended Submit Facility (ESF) enables Processes to be submitted even if the Connect:Direct DTF orthe communications path between the API and DTF is not active.

The ESF is active because YES is the default parameter value for the ESF keyword on the Connect:DirectSIGNON command. An AuthorizationRequired error occurs if the logon ID where the API is runningis not appropriately authorized when a Process is submitted through ESF. To prevent this error, do thefollowing:

• If you submit Processes through ESF with CA-ACF2, ensure the logon ID is authorized through CA-ACF2to update TCX and TCQ data sets.

• If you submit Processes through ESF with RACF, ensure the logon ID has control access authority forTCX and TCQ.

RACF Password Phrase (Passphrase)IBM Connect:Direct for z/OS supports RACF Password Phrase(Passphrase) up to 64 characters inlength. Any location within Connect:Direct where a password is accepted, a passphrase can be usedin its place. For more information on RACF support of Password Phrase, see the Security ServerRACF General User’s Guide, SA22-7685-05 at http://pic.dhe.ibm.com/infocenter/zos/v1r12/index.jsp?topic=%2Fcom.ibm.zos.r12.icha100%2Fichza14003.htm.

Passphrases can contain characters that the Connect:Direct z/OS parser defines as "delimiter"characters:

Chapter 2. Configuration Guide 35

Character Description

blank

< less than

¬ logical not

, comma

> greater than

= equal sign

/ forward slash

\ backward slash

' single quote

" double quote

( open parenthesis

) close parenthesis

Passphrases can begin with a blank.

Passphrases can end with a blank.

Special Connect:Direct z/OS rules for Passphrase:

• Passphrases that contain a special character that is also a "delimiter" must be enclosed in doublequotes or single quotes:

'This is<a>passphrase.'

or

"This is<a>passphrase."

• Passphrases that end with a blank must be enclosed with a combination of single quotes and doublequotes:

'" Passphrase that contains blanks. "'

• Passphrases that contain one or more single quotes must be enclosed in double quotes:

"That's a passphrase, not his'ns."

Note: Passphrases that contain single quotes cannot be entered in the ISPF panels and should beavoided.

• Passphrases that contain one or more double quotes must be enclosed in single quotes:

'Passphrase for the "world".'

• Rules for entering a passphrase through the ISPF panels are the same as for entering the passphrase ina PROCESS statement. However, they are somewhat relaxed:

– The ISPF code automatically encloses the passphrase in single quotes if it isn't entered enclosed insingle or double quotes.

This is a <passphrase> and is "easy" to enter.

36 IBM Connect:Direct for z/OS: Documentation

or

'This is a <passphrase> and is "easy" to enter.'

– Passphrase that end in a blank should be enclosed in double quotes (or the single/double quote -double/single quote pair).

"This is a passphrase that ends with a blank. "

or

'"This is a passphrase that ends with a blank. "'

Note: Passphrases that contain a single quote cannot be entered into the ISPF panels and should beavoided.

Note: If "delimiter" characters are avoided, entering the longer passphrase is the same as enteringthe password.

Summary

Passphrase Enclosed within

Contains no Connect:Direct "delimiter" none required

Contains Connect:Direct "delimiter" except singlequote and/or double quote (see ending blank rulebelow)

' or "

Contains single quote *Cannot be entered withISPF*

"

Contains double quote '

Contains both single quote and double quote *Not allowed*

Ends with blank, but has no single quote or doublequote

'" "'

Ends with blank, and has a single quote or doublequote

*Not allowed*

Planning for Parallel Sessions and Process RecoveryIBM Connect:Direct uses the parallel sessions capability to allow multiple Processes to executesimultaneously between any two IBM Connect:Direct nodes. Review Building, Modifying, and SubmittingProcesses in the IBM Connect:Direct for z/OS User Guide for more information on how to plan for parallelsessions.

IBM Connect:Direct provides facilities to recover from most errors that occur during Process execution.Recovery from the point of failure usually can be accomplished quickly. During the installation, you areasked to establish values for various parameters that affect Process recovery and checkpoint/restart.Review Process Recovery and Checkpoint/Restart in the IBM Connect:Direct for z/OS User Guide.

Planning the Network MapThe network map identifies the local IBM Connect:Direct node and the nodes where it can communicate.It consists of a local node entry and one or more adjacent node entries.

Each entry identifies the communications name and protocol associated with a IBM Connect:Direct node.A sample network map source can be found in member DGAXNTMP in the $CD.SDGACNTL library. Thismember should be tailored for and used as input to the network map load utility, DGADNTLD. This utility

Chapter 2. Configuration Guide 37

creates the VSAM form of the network map. It is invoked by the job DGAJLOAD in the $CD.SDGAJCLlibrary.

New Installations1. Gather the information you will need to create your local and adjacent node entries.2. To build a minimal netmap file with a local node and an initialization parameters file which uses all the

default settings, follow the instructions in Building a Test IBM Connect:Direct Configuration (optional).3. After completing the configuration process, update the network map to include other adjacent nodes

in the network.

Existing InstallationsTo upgrade to a later version while retaining an existing netmap and Connect:Direct Secure PlusParameters and Access files, see the IBM Connect:Direct for z/OS Release Notes.

Planning for Disaster Recovery TestingWhen you back up a IBM Connect:Direct system for business continuity testing (also known as "disasterrecovery testing or DR testing"), you create a snapshot of the DTF files at one point in time. If the DTF isrunning when the backup is taken, the captured files may not be in a synchronized known state.

To ensure that you perform a backup at a synchronized point in time to provide a "clean" starting pointfor the DTF, it is recommended that you put IBM Connect:Direct in a quiesced, or non-running state whenyou perform DR backups. Therefore, it is strongly recommended that you set the TCQ global initializationparameter to COLD when you start the DTF at the DR site.

If you do not know at what stage the backup was taken, you may have to deal with the following issues ina recovery situation:

• The TCQ and TCX datasets will probably be out of sync with each other, which will cause a failure whenyou start IBM Connect:Direct at a disaster recovery site. The DTF may terminate during initialization.

• If you need the contents of the TCQ to continue, run the DGADTQFX utility before you attemptto start the DTF (see Managing the Transmission Control Queue in the IBM Connect:Direct for z/OSAdministration Guide for details). Because the system may not be in a known synchronized state, it isrecommended that you set the TCQ initialization parameter to WARM and the QUIESCE initializationparameter to YES. Then you can delete Processes that have already executed before putting the DTF inthe "Run" state.

• The NETMAP could also be corrupted if it was dynamically updated when the NETMAP was backed up. Ifyou experience this with your system, unload the NETMAP, delete and redefine it, and then load it fromthe unloaded source.

Planning for Connect:Direct File AgentConnect:Direct File Agent must be installed in a directory of the z/OS UNIX System Services componentand configured to communicate with the IBM Connect:Direct server. Use a PC for terminal emulationwhen you are ready to create a configuration file using Connect:Direct File Agent. Connect:Direct FileAgent uses mount points, which are HFS/zFS files requiring at least 20 cyclinders of available space. SeeIBM Connect:Direct for z/OS Release Notes for software requirements for Connect:Direct File Agent.

Traces in Startup JCLWhen a problem occurs while Connect:Direct is running, you can use a variety of traces to gatherinformation to diagnose the problem and record events as they happen. Based on the trace specified,the Connect:Direct trace output is directed to various ddnames. For more information on traces, seeIsolating Problems.

Connect:Direct provides the following DD statements in the DGAJCONN JCL member as the basic set ofDDs to run your system including three automatic traces:

38 IBM Connect:Direct for z/OS: Documentation

DDNAME Function

STEPLIB Connect:Direct SDGALINK

DMPUBLIB Connect:Direct Process library

USRINFO Standard display from User exits

NDMLOG Automatic trace to list all initialization parameters read from the INITPARM datasetincluding obsolete parameters, which are indicated by SITA995I messages, and allmodules, along with the last date on which they were modified, and related fixnumbers.

ESTAE Automatic trace to capture I/O errors, VTAM connection errors, ABEND control blocks,open and close errors, TCQ/TCX errors on adds and updates, and Statistics File writeerrors.

RPLERRCK Automatic trace to capture VTAM and TCP/IP send and receive errors.

CDESTAE Supplemental ESTAE Output

CEEOUT Diagnostic messages from Language Environment programs (STDERR).

Configuring IBM Connect:Direct for z/OS

Define the IBM Connect:DirectVSAM FilesEdit and customize the following members in the $CD.SDGACNTL dataset for your environment.

1. Edit and customize the following members in the $CD.SDGACNTL dataset for your environment:

• DGACVDEF – IDCAMS Define of the Connect:Direct VSAM files• DGACVDEL – IDCAMS Delete of the Connect:Direct VSAM files• DGACNDEF – IDCAMS Delete/Define of the Connect:Direct Network Map• DGACAUTH – IDCAMS Repro of the AUTH File• DGACMSGV – IDCAMS Repro of the MSG File• DGACTYPE – IDCAMS Repro of the TYPE File

2. Edit, customize, and submit member DGAJVSAM in the $CD.SDGAJCL dataset. This job defines allConnect:Direct VSAM files, and loads the MSG, TYPE and AUTH files.

Note: Connect:Direct does not support the extended format attribute in any of its VSAM ESDS controldatasets. The following are Connect:Direct VSAM ESDS control datasets:

• MSG• AUTH• STATS• TCQ• TCX• TYPE• CKPT• NETMAP• PARMFILE• ARCHDIR• CONFIG• EVENT• USERPROF

Chapter 2. Configuration Guide 39

Define VTAM ResourcesUsing the samples in dataset $CD.SDGACNTL and VTAM definitions, define the VTAM resourcesappropriate for your environment.

Building a Test IBM Connect:Direct Configuration (optional)IBM Connect:Direct for z/OS provides a series of menus that let you customize the installation. Bothpanel-level and field-level help are available by pressing the PF1 key. Panel-level help identifies requiredfields and provides general information requested on a panel. To see help for a specific field in a separatepop-up window, place the cursor on an individual field and press the PF1 key.

The installation panels are:

• The Connect:Direct for z/OS Installation Main Menu, which collects information about how you want tocustomize your installation, builds a basic test configuration, and provides the IBM Connect:Direct forz/OS Configuration Menu.

• The Connect:Direct for z/OS Configuration Menu displays information to build a default testconfiguration you can use as a preliminary version of the network map for testing. After theconfiguration process is complete, update the network map to include other adjacent nodes in thenetwork. For more information on network maps, see Maintaining the Network Map. This step generatesa JCL member (DGAJNETL) that you will run to build a minimal netmap file with a local node and aninitialization parameters file which uses all the default settings.

Important: This procedure is intended for new users to assist them in building a test Connect:Directfor z/OS configuration—it is not for existing customers who already have netmaps populated with nodeinformation.

To display the installation panels:

1. Request the TSO COMMAND Option (Option 6) from the ISPF Primary Option Menu and type thefollowing:

=== > EXEC '$CD.SDGAISPC(DGA#CFG2)' '$CD'

2. When the Connect:Direct for z/OS Installation Main Menu is displayed, enter information in thePermanent DASD Volume Serial No. field. Press Enter.

IBMConnect:Direct for z/OS DATE-2015/02/13-------- Installation Main Menu -------- TIME-14:19CMD ==>C:D System High Level Qualifier ................. CSDQA1.HDGA510____________Permanent DASD Device Type ...................... SYSDA___ Permanent DASD Volume Serial No. ............... ______Temporary DASD Device Type ...................... SYSDA___Do you wish to configure a Test Connect:Direct... Y (Must be Y to continue)Job Card Information ==> //CDINST JOB (CD-INSTALL),'CD INSTALL',CLASS=O,_______________ ==> // MSGCLASS=X,REGION=0M_______________________________ ==> //*____________________________________________________________ ==> //*____________________________________________________________ Press ENTER to continue, PF1 for Help, PF3 to Terminate the Install

3. When the Connect:Direct for z/OS Configuration Menu is displayed, enter information in the LocalNode Name field to identify this node in the netmap (1–16 characters beginning with an alphacharacter).

Depending on your protocol, enter the following information:

• For SNA, specify the VTAM SNA APPLID and VTAM SNA API APPLID fields.• For TCP, complete the TCP IP Address or Hostname field (supports IPV4, IPV6 as well as a

Hostname).

40 IBM Connect:Direct for z/OS: Documentation

IBM Connect:Directfor z/OS DATE-2011/03/04 -------- Configuration Menu -------- TIME-13:55CMD ==>Connect:Direct configuration Information: Local Node Name .............. ________________ SNA (Yes or No) .............. N____ VTAM SNA APPLID .............. ________ ________ VTAM SNA API APPLID .......... ________ TCP (Yes or No) .............. Y____ TCP IP Address or Hostname ... __________________________________TCP Port Number .............. _______ TCP API Port Number .......... ________ Press ENTER to continue, PF1 for Help, PF3 to return

Press Enter to continue.4. When the Connect:Direct for z/OS JCL Generation Menu is displayed, press Enter to generate the JCL.

The following JCL members are generated in the resultant SDGAJCL dataset:

• DGAJNETL–JCL to build Netmap• DGAJTST–Test Connect:Direct for z/OS JCL

5. To build the test netmap, run the DGAJNETL job.

Once the job has run successfully, specify the NETDSN system file initialization parameter in theDGAJPARM member in $CD.SDGACNTL. as the DSN created via the DGAJNETL job. This parameterspecifies the file name of the Connect:Direct for z/OS VSAM network map file.

Building the Initialization Parameter FileNew releases of IBM Connect:Direct for z/OS often implement new initialization parameters. In addition,initialization parameters frequently become obsolete. IBM Connect:Direct detects parameters, whichshould be retired, and issues messages to NDMLOG. If you receive a return code of 4 when you stopIBM Connect:Direct, review the NDMLOG for a list of obsolete parameters. You must remove obsoleteparameters to eliminate SITA995I messages.

IBM Connect:Direct processes initialization parameters during startup to specify alternate values forvarious parameters. The IBM Connect:Direct initialization module processes the file that contains theseparameters.

Note: In addition to modifying initialization parameter files directly, use IBM Control Center to managethese parameters for a IBM Connect:Direct stand-alone server or the global and local initializationparameters for a IBM Connect:Direct/Plex.

You can create backup copies of the global and local initialization parameter files to use in an emergencysituation if IBM Connect:Direct cannot successfully initialize after initparm updates have been applied.

You must define all initialization parameters that specify the IBM Connect:Direct VSAM file names exceptthe optional $CD.STAT.ARCH.DIR parameter. Failure to take this step results in unpredictable behavior.

To specify your initialization parameters:

1. Modify the parameters as required.

Find sample initialization parameters in the DGAINT01 member of the $CD.SDGAPARM. Observe thefollowing required or suggested values:

• For initial installation and testing, specify SECURITY.EXIT=OFF in member DGAINT01. When IBMConnect:Direct security exits are installed, change the SECURITY.EXIT installation keyword. Thischange prevents any problems with user definitions until the basic installation is verified.

• If you are using TCP/IP connectivity, you must specify TCP=OES. Also specify valid values for theTCP.LISTEN parameter.

• The UPPER.CASE initialization parameter controls what case initialization console messages aredisplayed in. The default is UPPER.CASE=NO, which means that all console messages are displayed

Chapter 2. Configuration Guide 41

in upper and lower case. If you want to display all console messages in upper case, you must specifyUPPER.CASE=YES (this parameter can be modified as an override parameter in the DGADINITexecute statement in the IBM Connect:Direct startup job stream as well).

• If you generated the Test Configuration and successfully executed the DGAJNETL, then specify theNETDSN system file initialization parameter as the DSN created via the DGAJNETL job.

Note: You can initialize IBM Connect:Direct if SNA support is not available. See Configuring IBMConnect:Direct without SNA Support.

2. Specify VSAM file names.

Specify all initialization parameters that indicate the IBM Connect:Direct VSAM file names. Locatefollowing file names in the member DGACVDEF of the $CD.CNTL library:

• $CD.AUTH• $CD.CKPT• $CD.MSG• $CD.NETMAP• $CD.STATS• $CD.TYPE

3. Override the parameters during startup.

Override parameters during startup by specifying the parameter and its value in the PARM keyword ofthe EXEC statement in the startup JCL. See Start IBM Connect:Direct for sample JCL that shows anoverride for the UPPER.CASE=NO initialization parameter.

Note: If you are upgrading and have user exits in your IBM Connect:Direct installation, youmust reassemble and link-edit those exits. For more information on user exits, see Using IBMConnect:Direct Exits in the IBM Connect:Direct for z/OS Administration Guide.

Installing the ISPF IUIThe IBM Connect:Direct IUI is an ISPF dialog. ISPF dialogs have three phases: allocation, invocation,and unallocation. Each of these phases can be done after TSO logon is complete, either outside or insideISPF. Allocation can also be done through the TSO logon procedure. The IUI uses ISPLLIB, ISPMLIB,ISPPLIB and ISPSLIB application libraries. It does not use ISPTLIB. You can either pre-allocate the IUIapplication libraries outside of ISPF to your installation’s concatenations for the associated DDNAMEs, oryou can use the ISPF LIBDEF service in a script (CLIST or REXX) that executes inside ISPF to allocatethem immediately before invoking the IUI.

Optionally, a script can use LIBDEF with generic lib-types DMMSGFIL, DMPUBLIB, and DMNETMAP tospecify IUI components VSAM Message File dataset, Process Library concatenation, and the Netmapdataset, respectively. The main advantage to using generic LIBDEF over pre-allocated DDNAMEsDMMSGFIL and DMPUBLIB is that generic LIBDEF on one ISPF logical screen will not interfere withgeneric LIBDEF on another logical screen. Another advantage is the ISPF command ISPLIBD displays allLIBDEFs in effect for the IUI, generic and non-generic alike. The only IUI component that ISPLIBD doesnot display is the script (REXX or CLIST). To activate, deactivate and display scripts (User, Application andSystem levels), use the TSO command ALTLIB.

A script to invoke the IUI can now consist entirely of TSO ALTLIB, ISPF LIBDEF, and ISPF SELECTstatements, all of which are limited in effect to the ISPF logical screen in which executed. If genericLIBDEF is used, the legacy method of specifying the associated IUI application dataset or libraryconcatenation is not needed, and is ignored by the IUI. If you have either DDNAME DMMSGFIL orDMPUBLIB pre-allocated and also activate the associated generic lib-type, ISPLIBD will show the pre-allocated dataset with an ‘X’ under the USR column, and list it before the generic LIBDEF dataset forthat lib-type, similar to how it shows pre-allocated ISP*USR dataset in the ISP*LIB concatenations. If youuse LIBDEF with the LIBRARY keyword instead of the DATASET keyword, ISPLIBD will show the DDNAMEspecified by the ID parameter. To find the dataset allocated to the DDNAME, you can split your screen anduse the ISPF diagnostic utility ISRDDN.

42 IBM Connect:Direct for z/OS: Documentation

IBM recommends using LIBDEF for all non-script IUI application libraries. Further it is recommended thatLIBDEF with DATASET be used instead of LIBRARY, and that the DDNAMEs DMMSGFIL and DMPUBLIB notbe pre-allocated. If you follow these recommendations, the ISPLIBD display for those IUI applicationlibraries will be unambiguous. IBM recommends using ALTLIB for IUI CLIST and REXX applicationlibraries.

There are two new sample library members which show how to invoke the IUI using generic LIBDEFs:DGA#IUI4 uses LIBDEF with the DATASET keyword, and DGA#IUI5 uses LIBDEF with the LIBRARYkeyword. Using the DATASET keyword is more compact, but requires all dataset be cataloged. Onepossible disadvantage is that any mistake in DSN specification is not usually discovered until DGADISTRattempts to dynamically allocate the DD. In contrast, LIBDEF with the LIBRARY keyword requires a TSOALLOCATE or BPXWDYN command be done beforehand, and so is less compact. This method allowsuncatalogued datasets to be included in the DMPUBLIB concatenation (the other two generic lib-typesare for VSAM dataset which must be cataloged), as well as allowing mistakes in allocation to be detectedand remedied by the script, which is under customer control. See SAMPLIB members DGA#IUI4 andDGA#IUI5 for more information on using the IUI’s generic lib-types.

Allocation Methods for IUI data setsThe following tables list the allocation methods and scopes of all IUI data sets. The first table is for IBMConnect:Direct for z/OS 5.2 and before, the second is forv6.0, and the third is for v6.1 and later. Thechanges for IBM Connect:Direct for z/OS 6.1 are marked in bold.

Note:

1. STEPLIB cannot be changed after TSO LOGON.2. TSOLIB can only be invoked at TSO READY. The DDNAME can be anything.3. If you use LIBDEF ISPLLIB in CD 5.2, DGADISTR will abend S806.4. Use DDNAME SYSPROC, not SYSEXEC, because SDGAISPC contains CLISTs.5. Use ALTLIB ACT APPLICATION(CLIST), because SDGAISPC contains CLISTs.6. Generic LIBDEF will not work for IBM Connect:Direct for z/OS versions prior to v6.1

IBMConnect:Directfor z/OS 5.2

Allocated via TSO LogonProcedure

Allocated after TSO LOGON,Outside ISPF

Allocated after TSO LOGON,Inside ISPF

Data Set DDNAME ISPF LogicalScreen Scope

Command ISPF LogicalScreen Scope

Command ISPF LogicalScreen Scope

VSAM MSG DMMSGFIL All ALLOCATE All ALLOCATE All

Process DMPUBLIB All ALLOCATE All ALLOCATE All

Netmap SELECT

OS PARM

One

SDGALINK STEPLIB (1) All

TSOLIB (2) All

ISPLLIB All ALLOCATE All (3)

SDGAMENU ISPMLIB All ALLOCATE All LIBDEF One

SDGAPENU ISPPLIB All ALLOCATE All LIBDEF One

SDGASENU ISPSLIB All ALLOCATE All LIBDEF One

SDGAISPC SYSPROC (4) All ALLOCATE All ALTLIB (5) One

Chapter 2. Configuration Guide 43

IBMConnect:Directfor z/OS 6.0

Allocated via TSO

LOGON Procedure

Allocated after TSO

LOGON, Outside ISPF

Allocated after TSO

LOGON, Inside ISPF

Data Set DDNAME ISPF Logical

Screen Scope

Command ISPF LogicalScreen Scope

Command ISPF Logical

Screen Scope

VSAM MSG DMMSGFIL All ALLOCATE All ALLOCATE All

Process DMPUBLIB All ALLOCATE All ALLOCATE All

Netmap SELECT

OS PARM

One

SDGALINK STEPLIB (1) All

TSOLIB (2) All

ISPLLIB All ALLOCATE All LIBDEF One

SDGAMENU ISPMLIB All ALLOCATE All LIBDEF One

SDGAPENU ISPPLIB All ALLOCATE All LIBDEF One

SDGASENU ISPSLIB All ALLOCATE All LIBDEF One

SDGAISPC SYSPROC (4) All ALLOCATE All ALTLIB (5) One

IBMConnect:Directfor z/OS 6.1

Allocated via TSO

LOGON Procedure

Allocated after TSO

LOGON, Outside ISPF

Allocated after TSO

LOGON, Inside ISPF

Data Set DDNAME ISPF Logical

Screen Scope

Command ISPF LogicalScreen Scope

Command ISPF Logical

Screen Scope

VSAM MSG DMMSGFIL All ALLOCATE All ALLOCATE All

LIBDEF (6) One

Process DMPUBLIB All ALLOCATE All ALLOCATE All

LIBDEF (6) One

Netmap SELECT

OS PARM

One

DMNETMAP LIBDEF (6) One

SDGALINK STEPLIB (1) All

TSOLIB (2) All

ISPLLIB All ALLOCATE All LIBDEF One

SDGAMENU ISPMLIB All ALLOCATE All LIBDEF One

SDGAPENU ISPPLIB All ALLOCATE All LIBDEF One

SDGASENU ISPSLIB All ALLOCATE All LIBDEF One

SDGAISPC SYSPROC (4) All ALLOCATE All ALTLIB (5) One

44 IBM Connect:Direct for z/OS: Documentation

TSO Logon Procedure Allocation ExampleModify the LOGON PROC used to log in to TSO by integrating IBM Connect:Direct libraries. The bold linesin the following example are for IBM Connect:Direct.

//TSO PROC//*//IEFPROC EXEC PGM=IKJEFT01,DYNAMBR=25,// PARM="PROFILE MODE WTPMSG MSGID"//*//DMMSGFIL DD DSN=$CD.MSG,DISP=SHR//DMPUBLIB DD DSN=$CD.SDGAPROC,DISP=SHR//SYSPROC DD DSN=$CD.SDGAISPC,DISP=SHR// DD DSN=USR.ISPCLIB,DISP=SHR// DD DSN=ISP.SISPCLIB,DISP=SHR//ISPLLIB DD DSN=$CD.SDGALINK,DISP=SHR// DD DSN=USR.ISPLLIB,DISP=SHR//ISPMLIB DD DSN=$CD.SDGAMENU,DISP=SHR// DD DSN=USR.ISPMLIB,DISP=SHR// DD DSN=ISP.SISPMENU,DISP=SHR//ISPPLIB DD DSN=$CD.SDGAPENU,DISP=SHR// DD DSN=USR.ISPPLIB,DISP=SHR// DD DSN=ISP.SISPPENU,DISP=SHR//ISPSLIB DD DSN=$CD.SDGASENU,DISP=SHR// DD DSN=USR.ISPSLIB,DISP=SHR// DD DSN=ISP.SISPSLIB,DISP=SHR// DD DSN=ISP.SISPSENU,DISP=SHR//ISPTABL DD DSN=USR.ISPTABL,DISP=SHR//ISPTLIB DD DSN=USR.ISPTABL,DISP=SHR// DD DSN=ISP.SISPTENU,DISP=SHR//ISPPROF DD DSN=USR.ISPPROF,DISP=SHR//SYSHELP DD DSN=SYS1.HELP,DISP=SHR//SYSUADS DD DSN=SYS1.UADS,DISP=SHR//SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR//SYSPRINT DD TERM=TS,SYSOUT=A//SYSTERM DD TERM=TS,SYSOUT=A//SYSTSPRT DD TERM=TS,SYSOUT=A//SYSIN DD TERM=TS,SYSOUT=A//SYSTSIN DD DDNAME=IEFRDER//IEFRDER DD TERM=TS,SYSOUT=A

Example of TSO CLIST Allocation Outside ISPFCreate a CLIST to allocate the ISPF data sets outside of ISPF and integrate the IBM Connect:Directlibraries. The bold lines in the following example are for IBM Connect:Direct.

ALLOC F(DMMSGFIL) DA(’$CD.MSG’) SHR REUALLOC F(DMPUBLIB) DA(’$CD.SDGAPROC’) SHR REUALLOC F(SYSPROC) DA('$CD.SDGAISPC’ - 'USR.ISPCLIB' - 'ISP.SISPCLIB’) SHR REUALLOC F(ISPLLIB) DA(’$CD.SDGALINK’ - 'USR.ISPLLIB') SHR REUALLOC F(ISPMLIB) DA(’$CD.SDGAMENU’ - 'USR.ISPMLIB’ - 'ISP.SISPMENU’) SHR REUALLOC F(ISPPLIB) DA(’$CD.SDGAPENU’ - 'USR.ISPPLIB’ - 'ISP.SISPPENU’) SHR REUALLOC F(ISPSLIB) DA(’$CD.SDGASENU’ - 'USR.ISPSLIB’ - 'ISP.SISPSLIB’ - 'ISP.SISPSENU’) SHR REUALLOC F(ISPTABL) DA(’USR.ISPTABL’) SHR REUALLOC F(ISPTLIB) DA(’USR.ISPTABL’ - 'ISP.SISPTENU’) SHR REUALLOC F(ISPPROF) DA(’USR.ISPPROF’) SHR REU...PDF

TSOLIB can be used in a CLIST outside ISPF instead of ALLOCATE FI(ISPLLIB):

TSOLIB ACTIVATE DATASET(’$CD.SDGALINK’)

Chapter 2. Configuration Guide 45

Example of TSO REXX Allocation Outside ISPFYou can use REXX instead of CLIST for allocation. TSOLIB cannot be used inside a REXX EXEC.

/* REXX */ADDRESS TSO“ALLOC F(DMMSGFIL) DA(’$CD.MSG’) SHR REU”“ALLOC F(DMPUBLIB) DA(’$CD.SDGAPROC’) SHR REU”“ALLOC F(SYSPROC) DA('$CD.SDGAISPC’” , “'USR.ISPCLIB'” , “’ISP.SISPCLIB’) SHR REU”“ALLOC F(ISPLLIB) DA(’$CD.SDGALINK’” , “'USR.ISPLLIB') SHR REU”“ALLOC F(ISPMLIB) DA(’$CD.SDGAMENU’” , “’USR.ISPMLIB’” , “’ISP.SISPMENU’) SHR REU”“ALLOC F(ISPPLIB) DA(’$CD.SDGAPENU’” , “’USR.ISPPLIB’” , “’ISP.SISPPENU’) SHR REU”“ALLOC F(ISPSLIB) DA(’$CD.SDGASENU’” , “’USR.ISPSLIB’” , “’ISP.SISPSLIB’” , “’ISP.SISPSENU’) SHR REU”“ALLOC F(ISPTABL) DA(’USR.ISPTABL’) SHR REU”“ALLOC F(ISPTLIB) DA(’USR.ISPTABL’” , “’ISP.SISPTENU’) SHR REU”“ALLOC F(ISPPROF) DA(’USR.ISPPROF’) SHR REU”...“PDF”

Example of TSO CLIST Allocation Inside ISPFInside ISPF, DMMSGFIL and DMPUBLIB can still be allocated using the TSO ALLOCATE command, andfreed using the TSO FREE command, but the ISPF application component data sets must be allocatedusing LIBDEF, since ISP*LIB DDs cannot be altered once ISPF has been started. Also, although SYSPROCcan be reallocated inside ISPF, it is easier to use the TSO ALTLIB command to direct the IUI application tothe Sterling Connect:Direct CLIST/REXX PDS.

Create a CLIST to allocate the IUI dialog data sets inside of ISPF. Note that TSOLIB cannot be used insideISPF.

In the following example, DMNETMAP, DMMSGFIL, and DMPUBLIB are specified via generic LIBDEF.

PROC 0ALTLIB ACTIVATE DATASET('$CD.SDGAISPC') APPLICATION(CLIST)ISPEXEC LIBDEF DMNETMAP DATASET ID(‘$CD.NETMAP') STACKISPEXEC LIBDEF DMMSGFIL DATASET ID(‘$CD.MSG') STACKISPEXEC LIBDEF DMPUBLIB DATASET ID(‘$CD.SDGAPROC') STACKISPEXEC LIBDEF ISPLLIB DATASET ID(‘$CD.SDGALINK') STACKISPEXEC LIBDEF ISPMLIB DATASET ID(‘$CD.SDGAMENU') STACKISPEXEC LIBDEF ISPPLIB DATASET ID(‘$CD.SDGAPENU') STACKISPEXEC LIBDEF ISPSLIB DATASET ID(‘$CD.SDGASENU') STACKEXIT

Example of TSO REXX Allocation Inside ISPFCreate a REXX to allocate the IUI dialog data sets inside of ISPF. Note that TSOLIB cannot be used insideISPF or in a REXX.

In the following example, DMNETMAP, DMMSGFIL, and DMPUBLIB are specified via generic LIBDEF.

/* REXX */ADDRESS TSO“ALTLIB ACTIVATE DATASET('$CD.SDGAISPC') APPLICATION(CLIST)”ADDRESS ISPEXEC“LIBDEF DMNETMAP DATASET ID(‘$CD.NETMAP') STACK”“LIBDEF DMMSGFIL DATASET ID(‘$CD.MSG') STACK”“LIBDEF DMPUBLIB DATASET ID(‘$CD.SDGAPROC') STACK”“LIBDEF ISPLLIB DATASET ID(‘$CD.SDGALINK') STACK”“LIBDEF ISPMLIB DATASET ID(‘$CD.SDGAMENU') STACK”“LIBDEF ISPPLIB DATASET ID(‘$CD.SDGAPENU') STACK”“LIBDEF ISPSLIB DATASET ID(‘$CD.SDGASENU') STACK”EXIT 0

46 IBM Connect:Direct for z/OS: Documentation

Invoke the IUI Main Dialog (DGADISTR)

Typically, IUI invocation is done inside ISPF, since doing it outside ISPF via ISPSTART makes it difficultto use the other ISPF options. Connect:Direct for z/OS IUI invocation must be done using ISPF SELECTwith PGM, not SELECT with CMD. The SELECT can be in a Panel, a CLIST or REXX, or in an ISPF commandtable entry. The only prerequisite is that all required application libraries are allocated, either via LIBDEF,or TSO ALLOCATE commands.

A new ISPF APPLID for Connect:Direct for z/OS has to be specified by using NEWAPPL(applid). If LIBDEFwas used to allocate the application component data sets, and NEWAPPL was specified in the SELECT,then you must also specify PASSLIB or the LIBDEFs are not used.

Panel &ZSEL = TRANS( TRUNC (&ZCMD,'.') …CD,'PGM(DGADISTR) PARM(cd-netmap-dsn) …)

CLIST ISPEXEC SELECT PGM(DGADISTR) PARM(cd-netmap-dsn)

REXX ADDRESS ISPEXEC “SELECT PGM(DGADISTR)PARM(cd-netmap-dsn)”

CMD Table ZCTACT = SELECT PGM(DGADISTR) PARM(cd-netmap-dsn)

Note that if the generic LIBDEF for DMNETMAP is active, “PARM(cd-netmap-dsn)” is not required and isignored if specified.

Invoke the IUI MSG Dialog (DGADGDSP)The IUI main dialog includes the MSG (message) dialog. If you want to look up a Connect:Direct for z/OSmessage without having to go through the IUI login process, you can use the message dialog. You mustallocate the same ISPF components as for the IUI dialog, except that you do not need to allocate theDMMSGFIL or DMPUBLIB DDs. The message dialog is invoked through SELECT PGM in the same waysas the IUI dialog, but it uses a different program name and parameter. To specify the message file, youmay use either generic LIBDEF with lib-type DMMSGFIL as with the IUI main dialog, or specify it in theSELECT parameter. If you did not specify the message file DSN via generic LIBDEF DMMSGFIL, you mustspecify it in the SELECT parameter. If you specify the DSN via generic LIBDEF DMMSGFIL and via SELECTPARM, the PARM is ignored. The DSN is the same VSAM message file DSN you would allocate or LIBDEF toDMMSGFIL when invoking the IUI Main Dialog.

Panel &ZSEL = TRANS( TRUNC (&ZCMD,'.') …CD,'PGM(DGADGDSP) PARM(cd-msgfile-dsn) …)

CLIST ISPEXEC SELECT PGM(DGADGDSP) PARM(cd-msgfile-dsn)

REX ADDRESS ISPEXEC “SELECT PGM(DGADGDSP)PARM(cd-msgfile-dsn)”

CMD Table ZCTACT = SELECT PGM(DGADGDSP) PARM(cd-msgfile-dsn)

A new ISPF APPLID for Connect:Direct for z/OS can also be specified by using NEWAPPL(applid). IfLIBDEF was used to allocate the ISPF application component data sets, and NEWAPPL was specified inthe SELECT, you must also specify PASSLIB, or the LIBDEFs are not searched or used. In the followingexample, all needed Connect:Direct application component data sets must have been pre-allocated.

Chapter 2. Configuration Guide 47

See the following example of the invocation of ISPF primary option panel with IUI and MSG dialogs:

%------------ ISPF PRIMARY OPTION MENU --------------------%OPTION ===>_ZCMD +%%+USERID - &ZUSER% 0+SPF PARMS - Specify ... +TIME - &ZTIME% 1+BROWSE - Display ... +DATE - &ZDATE% 2+EDIT - Create ... +JULIAN - &ZJDATE% 3+UTILITIES - Perform ... +TERMINAL - &ZTERM% 4+FOREGROUND - Compile,... +PF KEYS - &ZKEYS% 5+BACKGROUND - Compile, Assemble, or Link Edit% 6+COMMAND - Enter TSO command or CLIST% 7+SUPPORT - Test dialog or convert menu/message fmts% M+C:D-MSGS - Display Sterling Connect:Direct messages% N+C:D - Sterling Connect:Direct% X+EXIT - Terminate ISPF using List/Log defaults%%)INIT.HELP=TTUTOR&ZHTOP=TTUTOR&ZHINDEX=TINDEX)PROC&ZSEL=TRANS( TRUNC (&OPT,'.')0,'PANEL(ISPOPT)'1,'PGM(ISPBRO)'2,'PGM(ISPEDIT)'3,'PANEL(ISPUTIL)'4,'PANEL(ISPFORA)'5,'PANEL(ISPJOB)'6,'PGM(ISPTSO)'7,'PANEL(ISPQTAC) NEWPOOL'M,'PGM(DGADGDSP) PARM($CD.MSG)'N,'PGM(DGADISTR) PARM($CD.NETMAP) NEWAPPL(CD)'X,'EXIT')END

Unallocation of IUI Data Sets

Unallocation usually occurs at the same level as allocation. For example, if the allocations are doneoutside ISPF, they are freed outside ISPF. It is not necessary to free data sets allocated via the ALLOCATEcommand, but it is customary to remove any LIBDEF and ALTLIB allocations when the application ends.Failure to do so can have unpredictable results.

Example of TSO CLIST Unallocation Inside ISPF

This example unallocates the allocations made in “Example of TSO CLIST Allocation Inside ISPF” on page46.

PROC 0ALTLIB DEACTIVATE APPLICATION(CLIST)ISPEXEC LIBDEF DMMSGFILISPEXEC LIBDEF DMPUBLIBISPEXEC LIBDEF DMNETMAPISPEXEC LIBDEF ISPLLIBISPEXEC LIBDEF ISPMLIBISPEXEC LIBDEF ISPPLIBISPEXEC LIBDEF ISPSLIBEXIT

Example of TSO REXX Unallocation Inside ISPF

This example unallocates the allocations made in “Example of TSO REXX Allocation Inside ISPF” on page46.

/* REXX */

ADDRESS TSO“ALTLIB DEACTIVATE APPLICATION(CLIST)”ADDRESS ISPEXEC“LIBDEF DMMSGFIL”“LIBDEF DMPUBLIB”“LIBDEF DMNETMAP”“LIBDEF ISPLLIB”

48 IBM Connect:Direct for z/OS: Documentation

“LIBDEF ISPMLIB”“LIBDEF ISPPLIB”“LIBDEF ISPSLIB”EXIT 0

Using a Panel Option and Screen Prompts with Permanent Allocations toImplement the IUIFollow these steps to implement the IUI by using a panel option and screen prompts with permanentallocations.

1. Change the TSO LOGON PROC by following the example in“TSO Logon Procedure Allocation Example” on page 45.

2. Alternatively, create a REXX or CLIST to be invoked outside or inside ISPF that does the allocations.For more information, see the TSO CLIST and TSO REXX allocation examples.

3. Change the ISPF Primary Option menu by following the example in “Invoke the IUI Main Dialog(DGADISTR)” on page 23 or in “Invoke the IUI MSG Dialog (DGADGDSP)” on page 24.“Invoke the IUI Main Dialog (DGADISTR)” on page 47 or“Invoke the IUI MSG Dialog (DGADGDSP)” on page 47.

4. Get into ISPF, navigate to the modified panel, and enter one of the chosen command strings.

Invoking a CLIST Inside ISPFFollow these steps to invoke a CLIST inside ISPF.

1. Start by creating a CLIST to be invoked inside ISPF that does the allocations. See“Example of TSO CLIST Allocation Inside ISPF” on page 46 for an example of this allocation. Removethe EXIT statement. Customize with your CD DSNs (and applid, if NEWAPPL was added).

2. Add the call to DGADISTR after the allocations. For an example of the CLIST syntax, see“Invoke the IUI Main Dialog (DGADISTR)” on page 47. Customize with your NETMAP DSN.

3. Add the unallocation statements. For an example of unallocation, see“Unallocation of IUI Data Sets” on page 48.

4. Invoke the CLIST from ISPF 6.

Using a REXX EXEC Invoked Inside ISPFFollow these steps to invoke a REXX EXEC inside ISPF.

1. Start by creating a REXX EXEC to be invoked inside ISPF that does the allocations. Follow the exampleof allocating TSO REXX inside ISPF, included in“Example of TSO REXX Allocation Inside ISPF” on page 46. Remove the EXIT statement. Customizewith your Connect:Direct DSNs and applid, if NEWAPPL was added.

2. Add the call to DGADISTR after the allocations. For an example of the REXX syntax, see“Invoke the IUI Main Dialog (DGADISTR)” on page 47. Customize with your NETMAP DSN.

3. Add the unallocation statements. For an example of TSO REXX unallocation, see,“Unallocation of IUI Data Sets” on page 48.

4. From ISPF 6, invoke the REXX EXEC.

Multiple Concurrent IUI Sessions

It is possible to have one IUI session per ISPF logical screen. To start the first IUI session, you might usea script similar to the one below.

/* REXX */ARG NETMAP APPLIF NETMAP = ‘’ THEN NETMAP = “CDA.NETMAP”IF APPL = ‘’ THEN APPL = “CDA”

Chapter 2. Configuration Guide 49

ADDRESS TSO“ALTLIB ACTIVATE DATASET('$CD.SDGAISPC') APPLICATION(CLIST)”ADDRESS ISPEXEC“LIBDEF DMMSGFIL DATASET ID(‘$CD.MSG') STACK”“LIBDEF DMPUBLIB DATASET ID(‘$CD.SDGAPROC') STACK”“LIBDEF DMNETMAP DATASET ID(‘”netmap”') STACK”“LIBDEF ISPLLIB DATASET ID(‘$CD.SDGALINK') STACK”“LIBDEF ISPMLIB DATASET ID(‘$CD.SDGAMENU') STACK”“LIBDEF ISPPLIB DATASET ID(‘$CD.SDGAPENU') STACK”“LIBDEF ISPSLIB DATASET ID(‘$CD.SDGASENU') STACK”“SELECT PGM(DGADISTR) NEWAPPL(“appl”) PASSLIB”ADDRESS TSO“ALTLIB DEACTIVATE APPLICATION(CLIST)”ADDRESS ISPEXEC“LIBDEF DMMSGFIL”“LIBDEF DMPUBLIB”“LIBDEF DMNETMAP”“LIBDEF ISPLLIB”“LIBDEF ISPMLIB”“LIBDEF ISPPLIB”“LIBDEF ISPSLIB”EXIT 0

Invoked with no arguments and no other IUI sessions active in the TSO LOGON, the IUI is started with thedefault netmap and applid, and when exited, cleanup is complete and leaves the TSO session in the samestate as before the REXX EXEC was invoked. The LIBDEF and ALTLIB commands are limited in scope tothe ISPF logical screen they are invoked on. There are no TSO ALLOCATE or FREE commands which couldpull the rug out from underneath a split screen IUI session, or vice versa.

Note:

ISPF supports up to 32 logical screens. Your installation can reduce that number. Each IUI sessionrequires a certain amount of storage (below and above the line). You may need to increase the TSO user’sregion to run multiple IUI sessions. Any ISPF logical screen can be used for any IUI session. You areallowed only one IUI session per ISPF logical screen. If you invoke more than one IUI session on one ISPFlogical screen, the results are unpredictable. IUI sessions started with the same ISPF APPLID share thesame ISPF profile pool. Each IUI session can utilize multi-session signon.

Different Release Levels used by Multiple Concurrent IUI SessionsMultiple concurrent IUI sessions cannot use different IBM Connect:Direct release levels.

The first IUI session will load reentrant load modules into storage, and because they are reentrant,subsequent concurrent IUI sessions started in other logical screens will use them instead of loading anew copy from the ISPLLIB DD, the LIBDEF ISPLLIB, or the LINKLIST. Thus only one IBM Connect:Directrelease can be used at a time, regardless of the number of concurrent IUI sessions.

IUI Load Module Search

In Connect:Direct for z/OS for z/OS 6.0 and later, the IUI calls load modules in two ways. The IUI usesthe ISPF SELECT PGM service call when it calls modules that are limited to IUI usage. The IUI uses theMVS macros LINK or LOAD with the DCB parameter when it calls modules common to the entire IBMConnect:Direct .

When you do not employ LIBDEF ISPLLIB with the IUI session, the IUI passes a zero in the DCBparameter, which is the same as not specifying the DCB parameter at all. When you employ LIBDEFISPLLIB, the IUI passes the DCB of the LIBDEF ISPLLIB concatenation to LINK and LOAD. A nonzeroDCB changes the MVS load module search order by skipping the requesting task's task library and all theunique task libraries of its preceding tasks (for example, ISPLLIB and TSOLIB concatenations). It alsoskips the STEPLIB concatenation. If you employ LIBDEF ISPLLIB, all IUI load modules must be in eitherthe LIBDEF ISPLLIB concatenation or the LINKLIST. For more information about the MVS load modulesearch order, see “The search for the load module” z/OS MVS Programming: Assembler Services Guide.For more information about the SELECT service load module search order, see “Application data elementsearch order” in ISPF Services Guide, LIBDEF service.

50 IBM Connect:Direct for z/OS: Documentation

Checking for IUI ISPLLIB LIBDEF SupportIf you create a REXX or CLIST to invoke the IUI using LIBDEF ISPLLIB, you should check that load moduleDGADR14 exists in the LIBDEF ISPLLIB library before doing the SELECT PGM. If it does not exist, LIBDEFISPLLIB is not supported. An example of how to do this using REXX is as follows:

...if sysdsn(’$CD.SDGALINK(DGADR14)') \= "OK" then do say “LIBDEF ISPLLIB is not supported by this CD release.” say “The CD load module library must be allocated to DD ISPLLIB using ALLOCATE outside ISPF." exit 4end..."SELECT PGM(DGADISTR) ..."...

IUI Stage 1 ExitsIn Connect:Direct for z/OS 6.0 and later, the Stage 1 exits with the IUI can be in a separate library and/orconcatenation from the rest of the IUI load modules, subject to the restrictions above. Whether they aretogether or separate from the rest of the IBM Connect:Direct load modules, the Stage 1 exits must be inan APF-authorized library. This library can be concatenated with APF unauthorized libraries. The Stage 1exits are no longer required to be linked with AC(1), or be NONRENT or NONREUS. They should be linkedwith AMODE 31 since the parameter list passed to them is above the line.

Start IBM Connect:DirectThe $CD.SDGAJCL(DGAJCONN) member contains the sample startup job stream to run the IBMConnect:Direct DTF as a batch job. It can run as a batch job or as a started task.

Important: If you generated the Test Configuration JOB, DGAJNETL, use that JOB instead of theDGAJCONN JOB or modify the DGAJCONN JOB to perform the same as DGAJNETL.

If you use Program Access to datasets (PADS) functionality in your security system, include all datasetsin the IBM Connect:Direct JCL STEPLIB DD concatenation in your Program Control List (PCL). SeeImplementing Security in the IBM Connect:Direct for z/OS Administration Guide for more information.

To start IBM Connect:Direct:

1. Execute IBM Connect:Direct from an authorized library. The installation makes the DTF load module(DGADINIT) APF-authorized with AC(1).

2. Submit the startup job stream. While Connect:Direct for z/OS is initializing, a series of messagesdisplay the sequence of events during initialization. If an initialization error occurs, note the lastmessage issued. The problem most likely occurred during the step indicated by the last message or onthe step indicated by the next message that should have been issued. For more information on specificerror messages, see “Initialization Errors” on page 78

Following is an example of messages you may see. The specific startup messages generated when youstart Connect:Direct for z/OS depend on the following factors:

• What communication protocols are used in your system• Whether Connect:Direct Secure Plus is part of your system and the version• Whether any initialization parameters are being overridden in the startup JCL• Whether any certificates have expired or will soon expire

Note: The SITA460I and SITA462I messages related to the Strong Password Encryption (SPE) featureare displayed even if no encryption is possible. To determine if this feature is in effect, go to theSecure+ Create/Update Panel - SPE Parameters panel where SPE is enabled.

Chapter 2. Configuration Guide 51

SITA001I IBM Connect:Direct for z/OS initialization has begun.SITA002I Connect:Direct parameter file allocated and open.SITA618I CD zIIP support is enabled.SITA617I zIIP processor online.SITA658I CD zFBA support is enabled.SITA120I Keyword INITPARM Value Overridden: TCQSITA120I Keyword INITPARM Value Overridden: STAT.INITSITA120I Keyword INITPARM Value Overridden: DEBUGSITA740I Connect:Direct DGAOPLS Found.SITA022I Loading Connect:Direct modules.SITA601I The TCP server modules are loaded.SITA067I MESSAGE file is open.SITA628I SNMP Trap Agent Initialization Complete.SITA023I Initializing Connect:Direct storage.SITA024I Building the TCA chain.SITA026I Creating the system tasks (master and timer).SITA025I Building the ECB address list.SITA027I Building the DDN table.SITA069I NETWORK MAP file is openSITA028I SECURE+ Initialization completeSITA029I Statistics facility being initiated.SITA996I STATS WARM Start being performed.SITA998I Acquiring storage for STAT.QUEUE.ELEMENTS.SSTL026I Statistics File Pair 01 is now active.SSTL019I Statistics facility successfully initialized.SITA068I AUTHORIZATION file is open.SITA460I Strong Password Encryption Initiated; $CDZ.AUTHSITA462I Strong Password Encryption Completed; $CDZ.AUTHSITA134I TYPE DEFAULTS file is open.SITA074I CHECKPOINT file is open.SITA030I PCQ/TCQ being built.SITA400I Enqueuing TCX from NETMAP for ESF processing.SITA996I TCQ WARM Start being performed.SITA460I Strong Password Encryption Initiated; $CDZ.TCQSITA462I Strong Password Encryption Completed; $CDZ.CDXTST.TCQSITA401I Dequeuing TCX from NETMAP for ESF processing.SITA034I VTAM services being initiated APPLID = M1DEVMW0.SVTJ019I SNA Support is Now Available.SITA439I Global INITPARM member successfully backed up to $BACKUPSITA977I Product Registration was SuccessfulSITA899I Connect:Direct Node : MY_LOCAL_CDZSITA370I ZLIB version : 1.2.7SITA374I zEDC Express Accelerator status is AVAILABLESITA036I Connect:Direct 6.00.00 5655-X11 Initialization Complete.SITA195I Secure+ TLS FIPS Mode initialization complete.SITA146I TCQ automatic update has been initiated.SITA147I TCQ automatic update has deleted 0 queue entries.STCO109I TCP/IP Server Subtask AttachedSTCO110I TCP/IP Interface InitializingSTCO140I TCP/IP IPV6 Support InitializingSTCO102I TCP/IP Issuing BIND Call for address 4199;0.0.0.0STCO103I TCP/IP Issuing LISTEN Call: 4199;0.0.0.0STCA102I TCP/IP API Issuing BIND Call for address 4198;0.0.0.0STCA103I TCP/IP API Issuing LISTEN Call: 4198;0.0.0.0STCO111I TCP/IP Interface Initializing CompleteSTCP104I TCP Support is Available.SNOI000I Operator Interface - initialized, MCS.CLIST openCSPA601E ERROR Cert: CDZCERTA expired on: 01/01/2010-05:59:59CSPA601E ERROR Cert: CDCertB expired on: 12/09/2010-20:41:43

The IEC161I, 062-086, or 056-084 messages can also display at OPEN of the VSAM files. Thesemessages indicate that the files were not closed properly the last time IBM Connect:Direct wasbrought down. These are normal VSAM verification messages.

3. Log on to TSO again.

After the TSO IUI is installed, log on to TSO again so that your new logon procedure or signon CLISTis in effect. You can then sign on to IBM Connect:Direct through the IUI, Operator Interface, or BatchInterface.

Remember: You can initialize IBM Connect:Direct if SNA support is not available. See Configuring IBMConnect:Direct without SNA Support.

52 IBM Connect:Direct for z/OS: Documentation

Signing On to IBM Connect:DirectYou can sign on to IBM Connect:Direct through the IUI, the Operator, or the Batch interface. For sign-oninstructions for the Batch interface, refer to the IBM Connect:Direct for z/OS User Guide.

Signing On through the IUI InterfaceSign on to IBM Connect:Direct uses one of the following methods:

• If the IBM Connect:Direct Authorization Facility is in effect, use the user ID SUPERUSR and thepassword supplied for the superuser in the network map local node definition.

• If you are running with a IBM Connect:Direct security exit, use a user ID and password that meet yoursecurity requirements.

• For an SNA environment, you must specify SNA=YES and define enough APPLIDS to handle both theIUI and Operator Interface sessions in the Netmap ADJACENT.NODE for LOCAL.NODE.For additional information on the IUI and procedures to automate the Signon process, refer to the IBMConnect:Direct for z/OS User Guide.

Signing On through the Operator InterfaceWhen you use the Operator Interface, the operator is automatically signed on to IBM Connect:Direct whenthe first command or CLIST is issued. You must specify the MCS.SIGNON and MCS.CLIST initializationparameters in the appropriate initialization parameter file.

Customizing the ProductAfter you verify the installation, you may want to customize files, screens, and Processes. The followinglist guides you to additional instructions for customizing your installation:

1. Fully define all nodes to the network map file. For information on how to update the network map file,see Maintaining the Network Map.

2. Set up the IBM Connect:Direct/Plex environment, if applicable.3. Select the appropriate step to set up security:

• If you use the IBM Connect:Direct Authorization Facility, add users to the User Authorization file.• If you use external security software such as RACF, ACF2, or TOP SECRET, see Implementing

Security for more information.4. Add types to the Type file. See Maintaining the Type File to add records to the Type file.5. Customize the Messages file. See Customizing IBM Connect:Direct in IBM Connect:Direct for z/OS

Administration Guide.6. Customize the SUBMIT screen.7. Customize the sample Processes. Information on IBM Connect:Direct Processes is available in the IBM

Connect:Direct for z/OS Process Language Reference Guide and IBM Connect:Direct for z/OS User Guide.

VTAM DefinitionsBefore starting IBM Connect:Direct, the VTAM application definitions must be active, the mode tableentries must be completed, and the cross-domain resources must be active. This section explains how toset up VTAM definitions for IBM Connect:Direct.

The following VTAM definitions may be required for each node. The member name of each definition islisted in parentheses. The sample definitions are in the file $CD.SDGACNTL.

• VTAM definitions for IBM Connect:Direct DTF (DGACAPPL)• VTAM definitions for IUI or batch interface (DGACIAPP)• Mode table used with IBM Connect:Direct (DGACMODT)• Cross-domain resource manager node (DGACCDRM)

Chapter 2. Configuration Guide 53

• Cross-domain resource definition for other nodes (DGACCDRS)• VTAM definition for PNODE=SNODE, also known as loop-back, processing (DGACAPPL)

If you are setting up VTAM definitions for mainframe-to-PC-only connections, disregard the informationabout multiple z/OS or VM sites within the IBM Connect:Direct network and VTAM cross-domaindefinitions.

Note: If you went through the installation process and generated the network map, refer to the memberDGAJNET0 in $CD.SDGACNTL for network map definitions that use the VTAM definitions.

Defining APPLID of Local DTFDefine the APPLID of the local IBM Connect:Direct DTF. A sample definition for the APPLID of the localDTF follows.

This example is located in the member DGACAPPL of $CD.SDGACNTL.

CDAPP4 APPL ACBNAME=CDAPP4, VTAM APPLICATION ID X APPC=YES, ENABLE TO RUN LU6.2 SESSIONS X AUTH=(ACQ,NOCNM,NOPASS,NOPO,NOTSO,VPACE), X EAS=n, APPROXIMATE # OF CONCURRENT SESS X MODETAB=CDMTAB, MODE TABLE NAME X SONSCIP=NO, NO UNBIND IN SCIP EXIT X SRBEXIT=NO, NO SRB PROCESSING X VPACING=n, RECEIVE PACING X DLOGMOD=CDLOGM, MODE TABLE ENTRY X PARSESS=YES, PARALLEL SESSIONS CAN BE USED X DSESLIM=n, # OF CONCURRENT LU6.2 SESSIONS X DMINWNL=n, # OF LOCAL CONTENTION WINNERS X DMINWNR=n, # OF REMOTE CONTENTION WINNERS X AUTOSES=n, # OF AUTOMATIC LU6.2 SESSIONS X DDRAINL=ALLOW, ALLOW CNOS TO DRAIN SESSIONS X DRESPL=ALLOW, DEF RESPONSIBILITY FOR LOCAL CNOS X LMDENT=n, SIZE OF HASH TABLE X VTAMFRR=NO

Optimal settings are:

• When using IBM Connect:Direct Extended Recovery, change CDAPP4 to CDAPP* to make the APPLdynamic. This change enables the IBM Connect:Direct extended recovery standby to monitor theactive IBM Connect:Direct image from a different z/OS image and to take over for that active IBMConnect:Direct image if it fails. This setting applies to both stand-alone servers and IBM Connect:Direct/Plex environments

• APPC=YES enables LU6.2 support and is required.• EAS represents the approximate number of concurrent sessions that this APPL has with all other APPLs

(Connect:Direct adjacent nodes and interactive users). The default value is 509. Change the value toone that is realistic for your environment.

• MODETAB must point to the mode table that contains entries for LU0, LU6.2, and SNA Service Managermode (SNASVCMG). See Define Logmode Table Entries for the definition of the mode table.

• Set VPACING to the number of RUs that this DTF receives before being obligated to send a pacingresponse. For best results, use a minimum value of 7. Larger values increase throughput when receivingdata from another DTF.

Do not specify a value of 0, or omit this parameter, which causes no pacing and can lead to a VTAMbuffer shortage.

DLOGMOD (the default log mode) must refer to an LU0 logmode entry to ensure compatibility with priorreleases of IBM Connect:Direct. The LU6.2 logmode name is extracted from the network map.

• PARSESS=YES parameter is required.• Set DSESLIM to the sum of the values specified in DMINWNL and DMINWNR so that DSESLIM is equal

to or greater than the largest PARSESS max value in the network map.• Set DMINWNL to a value that is no larger than one-half the value of DSESLIM.

54 IBM Connect:Direct for z/OS: Documentation

• Set DMINWNR to a value that is no larger than one-half the value of DSESLIM.• Set AUTOSES to 1 if this DTF is used in a mixed environment of sending and receiving files. Set

AUTOSES to 0 if this DTF is used primarily to receive files.

Note: Use this DTF to send files if you set AUTOSES to 0.

• DDRAINL=ALLOW enables Change Number of Sessions (CNOS) to drain sessions.• DRESPL=ALLOW enables the application program to accept responsibility for deactivating sessions.• LMDENT specifies the number of entries to be used for this application program's hash table of remote

LUs. The default value is 19.

APPLID for IUI and Batch SessionsDefine APPLID for IUI and batch session definition.

Note: Add ENCR=NONE to VTAM APPLs used for IUI sessions to avoid signon problems.

The following example shows three VTAM application definitions for the IBM Connect:Direct IUI. Theseapplication IDs must match those specified in the IBM Connect:Direct network map. The examples arelocated in member DGACIAPP of $CD.SDGACNTL.

CAUTION: In the example below, ACBNAME and the label names are representations. You need tochange them to represent your own installation.

NAI01 APPL ACBNAME=NAI01, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB ENCR=NONE*NAI02 APPL ACBNAME=NAI02, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB ENCR=NONE*NAI03 APPL ACBNAME=NAI03, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB ENCR=NONE

Defining APPLID for Loop-Back ProcessingIf you perform PNODE=SNODE (loop-back) processing, define the APPLID to use for the processing.

The following figure shows an additional IBM Connect:Direct DTF APPL (CDAPP2) defined to VTAMthat enables you to perform loop-back processing. This multiple definition is required because withPNODE=SNODE processing the communications name (APPLID) for the adjacent node defined in thenetwork map must be different than the communications name (APPLID) for the local node in the networkmap. This example is located in member DGACAPPL of $CD.SDGACNTL.

CDAPP2 APPL ACBNAME=CDAPP2, VTAM APPLICATION ID X AUTH=(ACQ,NOCNM,NOPASS,NOPO,NOTSO,VPACE), X EAS=n, APPROXIMATE # CONCURRENT SESS X MODETAB=CDMTAB, MODE TABLE NAME X SONSCIP=NO, NO UNBIND IN SCIP EXIT X SRBEXIT=NO, NO SRB PROCESSING X VPACING=7, RECEIVE PACING OF 7 X DLOGMOD=CDLOGM, MODE TABLE ENTRY X PARSESS=YES, PARALLEL SESSIONS CAN BE USED X VTAMFRR=NO

Defining Logmode Table EntriesDefine the logmode table entries used with each APPLID. This step is required if you communicate with anode defined to VTAM as a PU TYPE 4 node.

Chapter 2. Configuration Guide 55

The following sections provide examples from the mode table used with IBM Connect:Direct. Theexamples are located in member DGACMODT.

You can use the optional name (CDMTAB) as an assembler CSECT name for the mode table. You canassemble the table separately from other mode tables or you can insert the IBM Connect:Direct entry intoan existing mode table.

Note: Modify COS, PACING, and RUSIZE values only.

z/OS NodesUse the following entry with other Connect:Direct for z/OS nodes.

Note: Connect:Direct Secure Plus is not supported for SNA connections.

CDLOGM MODEENT LOGMODE=CDLOGM, ENTRY NAME X TYPE=1, NON-NEGOTIABLE BIND X FMPROF=X’04’, FUNCTION MGMT. PROFILE 4 X TSPROF=X’04’, TRANS SERVICE PROFILE 4 X PRIPROT=X’B3’, PRIMARY PROTOCOL X SECPROT=X’B3’, SECONDARY PROTOCOL X COMPROT=X’6080’, COMMON PROTOCOL X PSNDPAC=X’06’ PRIMARY SEND PACING X SRVPAC=X’06’ SECONDARY SEND PACING X RUSIZES=X’8989’, 4K MAX RU SIZE FOR PRI AND SEC X PSERVIC=X’000000000000000000000000’

OpenVMS and HP NonStop (Tandem) NodesUse the following entry with OpenVMS and HP NonStop (Tandem) nodes.

CDVMS MODEENT LOGMODE=CDVMS, X TYPE=1, X FMPROF=X’04’, X TSPROF=X’04’, X PRIPROT=X’B1’, X SECPROT=X’B1’, X COMPROT=X’7080’, X SRCVPAC=X’04’, SRCVPAC,SSNDPAC, AND PSNDPAC X SSNDPAC=X’04’, VALUES CAN BE TUNED X PSNDPAC=X’04’, X RUSIZES=X’8989’, 4K SEND AND RECV RUSIZE X PSERVIC=X’000000000000000000000000’

i5/OS SNUF (LU0) NodesUse the following entry with i5/OS SNUF (LU0) nodes.

SNUF4K MODEENT LOGMODE=SNUF2K, X COS=NJE, X FMPROF=X’04’, X TSPROF=X’04’, X PRIPROT=X’B1’, X SECPROT=X’B1’, X COMPROT=X’7080’, X SRCVPAC=X’07’, SRCVPAC,SSNDPAC, AND PSNDPAC X SSNDPAC=X’07’, VALUES CAN BE TUNED X PSNDPAC=X’07’, X RUSIZES=X’8888’, 2K SEND AND RECV RUSIZE X PSERVIC=X’000000000000000000000000’

LU6.2 NodesUse the following entry with LU6.2 independent nodes.

56 IBM Connect:Direct for z/OS: Documentation

CD624K MODEENT LOGMODE=CD624K, X TYPE=1, X COS=NJE, X FMPROF=X’13’, X TSPROF=X’07’, X PRIPROT=X’B0’, X SECPROT=X’B0’, X COMPROT=X’D0B1’, X PSNDPAC=X’04’, X SRVCPAC=X’04’, X SSNDPAC=X’04’, X RUSIZES=X’8989’, 4K SEND AND RECV RUSIZE X PSERVIC=X’060200000000000000000300’

Use the following entry with LU6.2 dependent nodes.

CD624K MODEENT LOGMODE=CD624K, X TYPE=1, X COS=NJE, X FMPROF=X’13’, X TSPROF=X’07’, X PRIPROT=X’B0’, X SECPROT=X’B0’, X COMPROT=X’50B1’, X RUSIZES=X’8989’, 4K SEND AND RECV RUSIZE X PSERVIC=X’060200000000000000002C00’

LU6.2 SNA Services ManagerLU6.2 requires the following SNA Services Manager mode table entry definition. This LOGMODE is forVTAM use. You must make this definition in the Mode Table, but do not specify it as the LOGMODE in thenetwork map.

SNASVCMG MODEENT LOGMODE=SNASVCMG, X TYPE=1, X COS=NJE, X FMPROF=X’13’, X TSPROF=X’07’, X PRIPROT=X’B0’, X SECPROT=X’B0’, X COMPROT=X’D0B1’, X RUSIZES=X’8585’, 256 SEND AND RECV RUSIZE X PSERVIC=X’060200000000000000000300’

Cross-Domain Resource Manager Minor NodesDefine the cross-domain resource manager nodes. Following are the IBM Connect:Direct Cross-DomainResource Manager node definitions. The sample is located in member DGACCDRM.

CDRMA VBUILD TYPE=CDRMAAAA CDRM SUBAREA=20,ELEMENT=1,ISTATUS=ACTIVEBBBB CDRM SUBAREA=30,ELEMENT=1,ISTATUS=ACTIVECCCC CDRM SUBAREA=40,ELEMENT=1,ISTATUS=ACTIVE

Each CDCDRM entry defines another VTAM domain or equivalent with which this domain communicate, inthe domain in which this IBM Connect:Direct is being defined.

Defining Cross-Domain ResourcesDefine the cross-domain resources. The following figure shows a IBM Connect:Direct Cross-DomainResource (CDRSC) definition. The sample is located in member DGACCDRS. Each CDRSC entry defines anapplications (another IBM Connect:Direct) in another domain.

Chapter 2. Configuration Guide 57

CDRSCNA VBUILD TYPE=CDRSCCDAPP2 CDRSC CDRM=BBBBCDAPP3 CDRSC CDRM=CCCC

IBM Connect:Direct does not use the Unformatted Systems Services (USS) table; however, if you define aUSS table for the LUs to be used with AS/400 communication devices, or with OpenVMS or Tandem logicalunits, you cannot include a MSG10 definition in the table.

Defining APPLIDS for Multiple DTFsOne VTAM APPL is required for each IBM Connect:Direct DTF, along with an optional APPL forPNODE=SNODE processing. If the configuration consists of two or more DTFs, or if a IBM Connect:Direct/Plex is configured, multiple VTAM APPLs must be defined.

When defining APPLs for multiple DTFs or a IBM Connect:Direct/Plex, the APPLs can all reside in the sameapplication major node (VBUILD TYPE=APPL) in SYS1.VTAMLST if necessary.

Defining Network or Domain NamesThe VTAM APPL definitions for IBM Connect:Direct nodes are in the supplied examples (in$CD.SDGACNTL) with the name field value (column 1) equal to the ACBNAME value. However, thesenames may be different. See Network or Domain Name in Cross-Domain Network for an example of VTAMand network map Cross Domain definitions and the rules that govern the definitions.

VTAM and NCP ParametersThis step explains how to set up VTAM and NCP parameters for IBM Connect:Direct operation. You mustperform the following evaluations to prepare for IBM Connect:Direct operation:

• Determine correct RU size for SNA sessions.

The VTAM RUSIZES parameter is located in the VTAM MODEENT macro. It specifies the transmissionbuffer size and can affect IBM Connect:Direct operation. See Selecting RU Size for SNA Sessions thatfollows.

• Determine the effect of NCP parameters.

Several parameters located in the NCP macros used during NCP generation (GEN) can also affect IBMConnect:Direct operation. See Effects of NCP Parameters.

Selecting RU Size for SNA SessionsThe request/response unit (RU) size for IBM Connect:Direct is specified in the VTAM RUSIZES parameterin the VTAM log mode table. The following example shows a mode table entry with a secondary andprimary logical unit RU size of 1,024 bytes.

CDLOGM MODEENT LOGMODE=CDLOGM, X RUSIZES=X‘8787’

When selecting an RU size for IBM Connect:Direct, it is important to know how RU size relates to the NCPMAXDATA parameter.

The NCP MAXDATA value is specified in the NCP physical unit (PU) macro definition. It specifies, in bytes,the maximum amount of data that the NCP can receive from the PU at one time. This amount includes thetransmission header and the request/response header, totaling 29 bytes for IBM Connect:Direct.

For example, if the IBM Connect:Direct VTAM log mode table entry specifies 4,096 bytes, the NCPMAXDATA value must be at least 4,125 bytes for IBM Connect:Direct to function correctly. In otherwords, the NCP MAXDATA value must be at least 29 bytes larger than the RU size specified in the IBMConnect:Direct VTAM log mode table.

58 IBM Connect:Direct for z/OS: Documentation

• The minimum RU size value for IBM Connect:Direct API-to-DTF transmissions is 512 bytes. Themaximum RU size value is 64 KB bytes. For best results, use a value of 7 KB.

Note: For locally attached non-SNA 3270 connections, specify RUSIZES =X‘87C7’.

Understanding RU SizingThe following table shows how to find the appropriate value to specify for the RUSIZES parameter. For theformula RUSIZES=X‘abab’, the first ab pair applies to the secondary logical unit (SLU). The second ab pairapplies to the primary logical unit (PLU). The table shows the values for a and b. The number of bytes isfound where the a column and the b column intersect in the table.

For example, the bold a and b numbers in the table indicate how it is used to determine theRUSIZES=87F8 for SNA connections. Because the primary LU is able to receive 3,840 bytes, thesecondary LU can send 3,840 bytes at a time (the intersection of F and 8). The primary LU can send1,024 bytes at a time because the secondary LU is able to receive 1,024 bytes (the intersection of 8 and7).

a

b 8 9 A(10) B(11) C(12) D(13) E(14) F(15)

0 8 9 10 11 12 13 14 15

1 16 18 20 22 24 26 28 30

2 32 36 40 44 48 52 56 60

3 64 72 80 88 96 104 112 120

4 128 144 160 176 192 208 224 240

5 256 288 320 352 384 416 448 480

6 512 576 640 704 768 832 896 960

7 1,024 1,152 1,280 1,408 1,536 1,664 1,792 1,920

8 2,048 2,304 2,560 2,816 3,072 3,328 3,584 3,840

9 4,096 4,608 5,120 5,632 6,144 6,656 7,168 7,680

A(10) 8,192 9,216 10,240 11,264 12,288 13,312 14,336 15,360

B(11) 16,384 18,432 20,480 22,528 24,576 26,624 28,672 30,720

C(12) 32,768 36,864 40,960 45,056 49,152 53,248 57,344 61,440

D(13) 65,536 73,728 81,920 90,112 98,304 106,496 114,688 122,880

E(14) 131,072 147,456 163,840 180,224 196,608 212,992 229,376 245,760

F(15) 262,144 294,912 327,680 360,448 393,216 425,984 458,752 491,520

The table is derived from the following calculations:

The RUSIZE of ab means RUSIZE equals a x (2 **b). The b of each ab pair is used as an exponent of basetwo. The resulting value is multiplied by a to get the RUSIZE for that logical unit.

Using the same example, RUSIZES=87F8, the SLU and PLU values are determined as follows.

Chapter 2. Configuration Guide 59

if RUSIZES=X‘87F8’ then

the SLU RUSIZE is 87which indicates 8 x 2**7 = 8 x 128 = 1024 (8 times 2 to the 7th power)

the PLU RUSIZE is F8which indicates F x 2**8 = 15 x 2**8 = 15 x 256 = 3840 (15 times 2 to the 8th power)

Effects of NCP ParametersReview the following NCP parameters carefully during the installation:

• BFRS in the BUILD GEN macro that defines the size of NCP buffers• BFRPAD in the HOST GEN macro that defines the number of pad characters inserted by NCP• MAXBUFRU in the HOST GEN macro that defines the number of buffers the access method (VTAM)

allocates to receive data from the NCP• UNITSZ in the HOST (VTAM) GEN macro that defines the size of access method buffers used for data

transfer from NCP to IBM Connect:Direct• TRANSFR in the LINE or BUILD GEN macro that defines the number of NCP buffers corresponding to the

maximum amount of data NCP can receive from another NCP

MAXDATA in the PU unit GEN macro that defines the maximum path information (PIU) size

The following figure illustrates the relationship between these VTAM and NCP parameters. When datais passed from MVS1 to NCPA, the MAXDATA parameter determines the amount of data that NCPA canreceive in one segment of a path information unit (PIU).

Between NCPA, NCPB, and NCPC, if you do not specify the TRANSFR parameter on the LINE statement,VTAM searches the BUILD statement. If you do not define TRANSFR on either statement, the default istaken. See the VTAM Customization manual.

When NCPB passes data to MVS2, the MAXBUFRU times the UNITSZ determines the amount of datathat can be passed to MVS2. The data cannot exceed the size in bytes of the VTAM IOBUF buffer poolallocation parameters.

Calculating Minimum Value of NCP TRANSFRTo calculate the minimum value of an NCP TRANSFR, define each NCP-to-NCP connection toaccommodate the maximum RU size defined for a IBM Connect:Direct DTF-to-DTF session. This valueis controlled by the NCP TRANSFR parameter of each NCP LINE macro defining an NCP-to-NCP link. Thefollowing is a summary of the calculations required to determine the NCP TRANSFR value:

1. Determine the maximum amount of data to be received on this line definition. For IBM Connect:Direct,this amount is the RU size plus 29 bytes for the request/response headers.

2. Add 24 bytes to this value for required NCP overhead (BFRPAD).3. Divide the sum by the NCP buffer size (BFRS).

60 IBM Connect:Direct for z/OS: Documentation

4. Round the result to the next highest integer. This integer is the minimum value that you can specify forTRANSFR that corresponds to the specified RU size.

Changing the TRANSFR ParameterIf you change the TRANSFR parameter in one NCP in a network, all other NCPs in that network require thesame change. If you cannot easily change the NCP TRANSFR parameter, use the following reverse processto calculate the maximum RU size for use by IBM Connect:Direct:

1. Multiply the NCP TRANSFR parameter by the NCP BFRS value. The result is the maximum amount ofdata that NCP can receive.

2. Subtract 24 bytes for required NCP overhead (BFRPAD).3. Subtract 29 bytes for the request/response header.4. Find the next lowest RU size value in the table on Understanding RU Sizing. This value is the largest RU

that you can specify for use by IBM Connect:Direct.

The amount of data VTAM can receive from the NCP is determined by the product of MAXBUFRU timesUNITSZ. This value must be less than or equal to the amount specified on the IOBUF buffer poolallocation parameters in the ATCSTRxx start options list of VTAMLST.

VTAM Definitions for Full Networking IBM Connect:DirectFollowing is a sample IBM Connect:Direct network with SNA connections.

The VTAM definitions in this section are based on this LU0 example.

Note: Do not make the node name the same as the VTAM APPLID.

Node A DefinitionsFollowing is the DTF APPL definition for CD.NODE.A:

CDAPPL1 APPL ACBNAME=CDAPPL1, X AUTH=(ACQ,NOCNM,NOPASS,NOPO,NOTSO,VPACE), X EAS=20, APPROXIMATE # CONCURRENT SESS X MODETAB=CDMTAB, MODE TABLE NAME X SONSCIP=NO, NO UNBIND IN SCIP EXIT X SRBEXIT=NO, NO SRB PROCESSING X VPACING=7, RECEIVE PACING OF 7 X DLOGMOD=CDLOGM, MODE TABLE ENTRY X PARSESS=YES, PARALLEL SESSIONS CAN BE USED X VTAMFRR=NO

The following are the APPL definitions for the API for CD.NODE.A.

Chapter 2. Configuration Guide 61

NAI01 APPL ACBNAME=NAI01, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB ENCR=NONE*NAI02 APPL ACBNAME=NAI02, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB ENCR=NONE

The following is the Cross-Domain Manager definition for CD.NODE.A.

CDRMA VBUILD TYPE=CDRMSA30 CDRM SUBAREA=30,ELEMENT=1,ISTATUS=ACTIVESA20 CDRM SUBAREA=20,ELEMENT=1,ISTATUS=ACTIVE

The following is the Cross-Domain definition for CD.NODE.A.

CDRSCA VBUILD TYPE=CDRSCCDAPPL2 CDRSC CDRM=SA30

The following is the network map definition for CD.NODE.A.

LOCAL.NODE=((CD.NODE.A CDAPPL1 ,, $PW) - TCQ=(TCX.FILE TCQ.FILE))* PNODE=SNODE DEFINITION *ADJACENT.NODE=((CD.NODE.A CDAPPL2) - PARSESS=(12 2) - APPLIDS=(NAI01,NAI02))* SNA CONNECTIONS *ADJACENT.NODE=((CD.NODE.B CDAPPL) - PARSESS=(6 3) - APPLIDS=(NAI01,NAI02))

Node B DefinitionsFollowing is the DTF APPL definition for CD.NODE.B:

CDAPP2 APPL ACBNAME=CDAPP2, X AUTH=(ACQ,NOCNM,NOPASS,NOPO,NOTSO,VPACE), X EAS=20, APPROXIMATE # CONCURRENT SESS X MODETAB=CDMTAB, MODE TABLE NAME X SONSCIP=NO, NO UNBIND IN SCIP EXIT X SRBEXIT=NO, NO SRB PROCESSING X VPACING=7, RECEIVE PACING OF 7 X DLOGMOD=CDLOGM, MODE TABLE ENTRY X PARSESS=YES, PARALLEL SESSIONS CAN BE USED X VTAMFRR=NO

The following are the APPL definitions for the API for CD.NODE.B.

NBI01 APPL ACBNAME=NBI01, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB*NBI02 APPL ACBNAME=NBI02, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB

The following is the Cross-Domain Manager definition for CD.NODE.B.

62 IBM Connect:Direct for z/OS: Documentation

CDRMB VBUILD TYPE=CDRMSA30 CDRM SUBAREA=30,ELEMENT=1,ISTATUS=ACTIVESA20 CDRM SUBAREA=20,ELEMENT=1,ISTATUS=ACTIVE

The following is the Cross-Domain definition for CD.NODE.B.

CDRSCA VBUILD TYPE=CDRSCCDAPPL1 CDRSC CDRM=SA20

The following is the network map definition for CD.NODE.B.

LOCAL.NODE=((CD.NODE.B CDAPPL2 ,, $PW) - TCQ=(TCX.FILE TCQ.FILE))* PNODE=SNODE DEFINITION * ADJACENT.NODE=((CD.NODE.B CDAPPL2B) - APPLIDS=(NBI01,NBI02))* SNA CONNECTIONS *ADJACENT.NODE=((CD.NODE.A CDAPPL1) - APPLIDS=(NBI01,NBI02))

Network or Domain Name in Cross-Domain NetworkThe VTAM APPL definitions for IBM Connect:Direct nodes are in the supplied examples (in$CD.SDGACNTL) with the name field value (column 1) equal to the ACBNAME value. However, thesenames may be different. If they are different, the network name value contained in the name field must beunique within the network, and the value in the ACBNAME field must be unique within the domain.

If the names are different, follow these rules when defining the network map:

• The name specified for the local node’s DTF APPLID must be the domain name.• The name specified for adjacent nodes’ DTF APPLIDs must be the network name.• The names specified in the API APPLIDS keyword of the adjacent node must be the domain names.

The following sample illustrates definitions for two nodes with unique network and domain names:

The VTAM definitions in this section are based on this example.

In the following VTAM definition examples, domain names contain a D as part of their name and networknames contain an N.

Chapter 2. Configuration Guide 63

SNA Node AFollowing is the DTF APPL definition for CD.NODE.A:

CDNAPP1 APPL ACBNAME=CDDAPP1, AUTH=(ACQ,NOCNM,NOPASS,NOPO,NOTSO,VPACE), X EAS=20, APPROXIMATE # CONCURRENT SESS X MODETAB=CDMTAB, MODE TABLE NAME X SONSCIP=NO, NO UNBIND IN SCIP EXIT X SRBEXIT=NO, NO SRB PROCESSING X VPACING=7, RECEIVE PACING OF 7 X DLOGMOD=CDLOGM, MODE TABLE ENTRY X PARSESS=YES, PARALLEL SESSIONS CAN BE USED X VTAMFRR=NO

The following are the APPL definitions for the API for CD.NODE.A.

NAN01 APPL ACBNAME=NAID01, X DLOGMOD=NDMLOGM, X MODETAB=NDMTAB ENCR=NONE*NAN02 APPL ACBNAME=NAID02, XDLOGMOD=CDLOGM, X MODETAB=CDMTAB ENCR=NONE

Following is the Cross-Domain Manager definition for CD.NODE.A:

CDRMA VBUILD TYPE=CDRMSA30 CDRM SUBAREA=30,ELEMENT=1,ISTATUS=ACTIVESA20 CDRM SUBAREA=20,ELEMENT=1,ISTATUS=ACTIVE

Following is the Cross-Domain definition for CD.NODE.A:

CDRSCA VBUILD TYPE=CDRSCCDNAPP2 CDRSC CDRM=SA30

Following is the network map definition for CD.NODE.A:

LOCAL.NODE=((CD.NODE.A CDNAPP1 ,, $PW) - TCQ=(CD.NODEA.TCX CD.NODEA.TCQ))* *ADJACENT.NODE=((CD.NODE.A CDNAPP1) - APPLIDS=(NAID01,NAID02))* *ADJACENT.NODE=((CD.NODE.B CDNAPP2) - APPLIDS=(NBID01,NBID02))

SNA Node BFollowing is the DTF APPL definition for CD.NODE.B:

CDNAPP2 APPL ACBNAME=CDDAPP2, AUTH=(ACQ,NOCNM,NOPASS,NOPO,NOTSO,VPACE), EAS=20, APPROXIMATE # CONCURRENT SESS X MODETAB=CDMTAB, MODE TABLE NAME X SONSCIP=NO, NO UNBIND IN SCIP EXIT X SRBEXIT=NO, NO SRB PROCESSING X VPACING=7, RECEIVE PACING OF 7 X DLOGMOD=CDLOGM, MODE TABLE ENTRY X PARSESS=YES, PARALLEL SESSIONS CAN BE USED X VTAMFRR=NO

64 IBM Connect:Direct for z/OS: Documentation

Following are the APPL definitions for the API for CD.NODE.B:

NBN01 APPL ACBNAME=NBID01, X DLOGMOD=CDLOGM, X MODETAB=CDMTABNBN02 APPL ACBNAME=NBID02, X DLOGMOD=CDLOGM, X MODETAB=CDMTAB

Following is the Cross-Domain Manager definition for CD.NODE.B:

CDRMB VBUILD TYPE=CDRMSA30 CDRM SUBAREA=30,ELEMENT=1,ISTATUS=ACTIVESA20 CDRM SUBAREA=20,ELEMENT=1,ISTATUS=ACTIVE

Following is the Cross-Domain definition for CD.NODE.B:

CDRSCA VBUILD TYPE=CDRSCCDNAPP1 CDRSC CDRM=SA20

Following is the network map definition for CD.NODE.B:

LOCAL.NODE=((CD.NODE.B CDNAPP2 ,, $PW) - TCQ=(CD.NODEB.TCX CD.NODEB.TCQ))* *ADJACENT.NODE=((CD.NODE.B CDNAPP2) - APPLIDS=(NBID01,NBID02))* *ADJACENT.NODE=((CD.NODE.A CDNAPP1) - APPLIDS=(NAID01,NAID02))

Optional Configuration Tasks

Customizing the ProductAfter you verify the installation, you may want to customize files, screens, and Processes. The followinglist guides you to additional instructions for customizing your installation:

1. Fully define all nodes to the network map file. For information on how to update the network map file,see Maintaining the Network Map.

2. Set up the IBM Connect:Direct/Plex environment, if applicable.3. Select the appropriate step to set up security:

• If you use the IBM Connect:Direct Authorization Facility, add users to the User Authorization file.• If you use external security software such as RACF, ACF2, or TOP SECRET, see Implementing

Security for more information.4. Add types to the Type file. See Maintaining the Type File in IBM Connect:Direct for z/OS Administration

Guide to add records to the Type file.5. Customize the Messages file. See Customizing IBM Connect:Direct in IBM Connect:Direct for z/OS

Administration Guide.6. Customize the SUBMIT screen.7. Customize the sample Processes. Information on IBM Connect:Direct Processes is available in the IBM

Connect:Direct for z/OS Process Language Reference Guide.

Chapter 2. Configuration Guide 65

Installing Connect:Direct File AgentBefore you install Connect:Direct File Agent, review the requirements in Planning for Connect:DirectFile Agent. After you customize Connect:Direct File Agent, see the Connect:Direct File Agent Help forconfiguration instructions.

Note: You must download and store the Connect:Direct File Agent code in the HFS directory prior toexecuting the DGA#FINS CLIST. This HFS directory path is required as menu input in the DGA#FINSCLIST.

Access to HFS files is controlled by z/OS UNIX System Services, which enables or denies access basedon UNIX permission rules. The installer and users of Connect:Direct File Agent must have the appropriatepermissions.

To install Connect:Direct File Agent:

1. To download the Java version of the Connect:Direct File Agent component, log on to IBM PassportAdvantage Online and navigate to IBM Connect:Direct Product Updates/Downloads. After you havedownloaded and saved the .zip file to your PC, decompress it to get the JAR file.

2. Upload the FAInstall.jar to an HFS directory using FTP in binary mode.3. Execute the installer from a standard OMVS prompt or TELNET session into a UNIX ISHELL

environment and enter java -jar FAInstall.jar.

CAUTION: The installer requires a region of at least 210 MB. If your region is less than theminimum, make arrangements to define a larger region.

4. Follow the prompts to install Connect:Direct File Agent.5. After installing Connect:Direct File Agent, execute the DGA#FINS CLIST to build the appropriate JCL to

configure and execute Connect:Direct File Agent in a z/OS environment.

Customizing Connect:Direct File AgentTo customize Connect:Direct File Agent:

1. From the TSO COMMAND option of ISPF/PDF, execute the DGA#FINS CLIST, where $CD is the high-level qualifier used to install Connect:Direct for z/OS files, as in the following example.

=== > EXEC '$CD.SDGAISPC(DGA#FINS)' ‘$CD’

During the installation process, you will create and name a Connect:Direct File Agent JCL dataset . Allinstallation variables are saved in this JCL. The following table describes these installation variables:

Field Description

Configuration job Name of the job that starts the Connect:Direct File Agent ConfigurationInterface.

Execution job Name of the job that start Connect:Direct File Agent.

Shutdown job Name of the job that shuts down Connect:Direct File Agent.

File Agent home Full path of the directory where Connect:Direct File Agent is installed.

66 IBM Connect:Direct for z/OS: Documentation

Field Description

X11 Displayvariable

X11 display variable used to connect to the X11 GUI server. The Connect:DirectFile Agent Configuration Interface displays on the monitor that matches thisdisplay variable. You can specify the netowrk ID of the terminal that you wantto use for the Connect:Direct File Agent Configuration Interface.

Note: If you want to display the Connect:Direct File Agent ConfigurationInterface on a Windows computer, you can specify the first node of the FullComputer Name. To obtain this information, right-click on My Computer, clickProperties., and then click the Network Identification tab. The Full ComputerName is displayed.

Job cardinformation

JCL used for the job card.

You can edit the Connect:Direct File Agent JCL dataset with ISPF to change an installation variable.

The Connect:Direct File Agent Installation Main Menu is displayed after all elements have beenunloaded.

More: + Connect:Direct File Agent v.rr.mm Installation Main Menu TIME-hh:mm DATE-yyyy/mm/dd

CMD ==>

This panel can be scrolled up and down to view the entire set of fields to be entered

Press ENTER to continue, PF5 to Terminate the JCL Generation

File Agent jcl dataset... Member name for Configuration job.... CDFACONF Execution job........ CDFAEXEC Shutdown job......... CDFASHUT Unix path for File Agent home...... ___________________________________________________ ...... ___________________________________________________ ...... ___________________________________________________ ...... ___________________________________________________ X11 DISPLAY variable...... ___________________________________________________

Job Card Information...... //CDFA JOB (CDFA),'XX FILE AGENT', ...... //* ...... //*

2. To create the DGA#FINS JCL used to install Connect:Direct File Agent in the $CD.SDGAJCL dataset,specify the fields and press Enter.

3. When the Connect:Direct File Agent JCL Generation Main Menu is displayed, press Enter to generatethe File Agent JCL.

Chapter 2. Configuration Guide 67

Connect:Direct File Agent v.rr.mm JCL Generation Main Menu TIME-hh:mm TIME-hh:mm DATE-yyyy/mm/dd

CMD ==>

Connect:Direct File Agent JCL Generation Complete, RC=0

Name Description ------- ----------- CDFA The job to build the File Agent jobs

Review and submit member CDFA to finish the JCL generation. CDFACONF, CDFAEXEC, and CDFASHUT will be created by job CDFA

Press ENTER to continue

After the JCL has been generated, the following panel lists the jobs created.4. To install Connect:Direct File Agent in the appropriate HFS directory, execute the CDFA JCL

member, which generates the CDFACONF, CDFAEXEC, and CDFASHUT JCL members. The CDFACONF,CDFAEXEC, and CDFASHUT job names are based on the JCL member names you entered in theConnect:Direct File Agent Installation Main Menu panel. The CDFA job name is taken from the job cardinformation entered during the installation.

Note: The CDFACONF, CDFAEXEC, and CDFASHUT job names are based on the JCL member namesyou entered in the Connect:Direct File Agent Installation Main Menu panel. The CDFA job name istaken from the job card information entered during the installation.

5. Open an X11 window, and then run the CDFACONF job to execute the Connect:Direct File Agent GUI.This job copies files from the mainframe library into the UNIX (HFS) directory.

Configuring Connect:Direct File AgentConfigure Connect:Direct File Agent using the configuration interface. The Sterling Connect:DirectFile Agent Configuration Guide describes how Connect:Direct File Agent works and contains sampleconfiguration scenarios.

Before you implement Connect:Direct File Agent in a production environment, use the Connect:Direct FileAgent Help to set up and verify the basic operation. The Connect:Direct File Agent Help contains the sameinformation as the Sterling Connect:Direct File Agent Configuration Guide.

Connect:Direct File Agent is designed to run unattended. After you verify Connect:Direct File Agentoperation and configuration, start it by running the CDFAEXEC job. Connect:Direct File Agent beginsscanning the watch directory containing the directories and partitioned datasets you specify in theconfiguration file. When a file arrives in a watch directory, Connect:Direct File Agent either submits thedefault Process to IBM Connect:Direct or performs the actions specified by the rules for the file.

Backing Out the Connect:Direct File Agent InstallationIt is not necessary to back out the Connect:Direct File Agent installation–if required, execute theDGA#FINS CLIST again.

Planning for Apsera FASP for Connect:Direct for z/OS

Aspera FASP is a high-speed transport for file transfer that avoids some of the slow-downs experiencedwith TCP, especially in networks with high latency and/or high packet loss.

IBM Connect:Direct UNIX (Linux and AIX) and IBM Connect:Direct Windows provide native support forutilizing FASP for the COPY step of a PROCESS. In order to support FASP with IBM Connect:Direct , theuser must purchase and install a High Speed Adapter Option (HSAO) license.

68 IBM Connect:Direct for z/OS: Documentation

Figure 1. Install a High Speed Adapter Option (HSAO) license

Support is being added to IBM Sterling Secure Proxy (SSP) that will allow IBM Connect:Direct FASPtransfers to pass through SSP. Since HSAO licenses are required at each end of the transfer, no additionalHSAO license is needed in SSP.

Figure 2. FASP transfers through SSP

SSP is designed in such a way that there is a complete session break between the two IBM Connect:Directnodes. In this way, SSP offers the capability of having one side of the session using Secure+ while theother side of the session is not. This way, an internal IBM Connect:Direct can eliminate the overhead ofencryption/decryption when passing through SSP and have SSP encrypt/decrypt that data this going overthe public internet. Since SSP does a complete session break, there should be some way provided for SSPto use FASP protocol for one side of a session and the IBM Connect:Direct TCP protocol for the other side.

Figure 3. FASP transfers and session break between two IBM Connect Direct nodes

It should also be possible to allow two SSPs to use FASP across the public network without the two IBMConnect:Direct having to use FASP.

Figure 4. SSPs using FASP across public network

The Connect:Direct for z/OS Server requires the following definitions. See, Connect:Direct for z/OSAdministration Guide for detail description of the FASP Initialization parameters.

Note: A HSAO license must be obtained and stored in the zOS files system and available to the IBMConnect:Direct Server during initialization.

fasp=(yes|no|ssp , yes |no |ssp) fasp.bandwidth=nnnn|<bandwidth_from_license>fasp.filesize.threshold=nnn|1Gfasp.policy=fair|high|low|fixed

IBM Connect:Direct Server start must include a DD statement for the Aspera license file. For example,

//CDASPLIC DD DISP=SHR,DSN=$CD.HSAO.LICENSE

Note: To enable FASP via SSP the initialization parameter must be FASP=(SSP,SSP)

Chapter 2. Configuration Guide 69

Customizing the Spool Transfer FeatureIgnore this procedure if your site does not use the Spool Transfer feature or if you are sending output tothe JES reader from IBM Connect:Direct. For outbound transfers where you will be distributing print filesfrom the JES Spool to IBM Connect:Direct, you must customize the Spool Transfer feature.

Note: For information on Spool Transfer, see IBM Connect:Direct for z/OS Facilities Guide.

Customizing the Spool Transfer feature consists of the following tasks:

1. Assemble DGASVPSA.2. Customize VPS/CDI Option.3. Restart VPS.4. Customize the sample Processes.

Note: The Spool Transfer feature requires that you install VTAM Printer Support (VPS) and that youinclude the optional code in VPS that enables it to interface with IBM Connect:Direct.

Assembling DGASVPSAEdit and modify the member DGAXAVPS in dataset $CD.SDGASAMP to assemble and link the DGASVPSAmodule in the $CD.SDGALINK dataset.

Note: The DGASVPSA module must be reassembled and linked when you upgrade VPS.

Customizing VPS/CDIFollowing are the requirements for the VPS to CDI program (VPSSCDI). Add or modify the following librarymembers. Refer to VPS documentation for explanations and requirements.

VPS.CNTLThis VPS library contains the following library members and parameters supported by IBMConnect:Direct:

Member Description

VPSSTART Contains the VPS system initialization parameters. The following keyword must beadded to activate the VPSSCDI program. KEYCDI activates the VPSSCDI program.

MLISTMEM This member contains the VPS printer activation member inclusion list. Add IBMConnect:Direct printers to this member.

VPSxxxx These members contain the VPS printer initialization parameters.

The following table describes the keywords for a IBM Connect:Direct printer definition:

Keyword Description

DDSNPFX Required. Specifies the high-level qualifier VPS uses when creating the IBMConnect:Direct staged dataset. The default is VPS.

DEVTYPE=V.CDI Required. Defines a printer as a IBM Connect:Direct printer.

CDNETMAP Specifies the IBM Connect:Direct network map dataset name. The default is to usethe DMNETMAP DD statement specified in VPS startup.

CDPLIB Defines the IBM Connect:Direct process library dataset name. The default is to usethe DMPUBLIB DD statement specified in VPS startup.

CDPMBR Specifies the process member name to submit. The default is the printer name withthe class appended.

70 IBM Connect:Direct for z/OS: Documentation

Keyword Description

CDSNODE Defines the SNODE to be passed to the Process. The default is to use the SNODEdefined in the Process.

DSPACE Specifies the amount of DASD space to be allocated to the DASD dataset.

DUNIT Specifies the unit type of the device on which the DASD is to be allocated.

DVOLUME Specifies the volume on which the DASD is to be allocated.

VPS/CDI Interface ProgramAssemble and link-edit module VPSSCDI into VPS LINKLIB using the sample JCL provided by LRS, and theIBM Connect:Direct macros provided in the SDGASAMP and SDGAMAC libraries.

VPS/CDI Startup ProcedureAdd the following IBM Connect:Direct DD statements to the VPS startup procedure:

DD Statement Description

DMMSGFIL Required. IBM Connect:Direct message file.

SYSUT1 Required. DD UNIT=VIO, SPACE=(TRK,(2,1)).

DMPUBLIB Required. IBM Connect:Direct Process library.

STEPLIB IBM Connect:Direct LINKLIB.

DMNETMAP IBM Connect:Direct default network map.

Restarting VPSAfter making changes to the VPS startup procedure, restart VPS to bring in the changes.

Customizing Sample ProcessesCustomize the sample Processes according to your environment. Information on IBM Connect:DirectProcesses is available at .

Information on IBM Connect:Direct Processes is available at the Connect:Direct Process Language help.

HP OpenView for SNMP Traps CustomizationNetwork Management applications do not recognize or display the traps without the IBM Connect:Directtrap configuration file and Management Information Block (MIB). Use the information to customize andload these files for HP OpenView Network Management.

Importing the IBM Connect:Direct Trap Configuration FilePerform this step if you are using SNMP Trap agent to communicate with the HP OpenView Network NodeManager.

1. Transfer the Connect:Direct for z/OS configuration file, $CD.SDGAMIB, to the HP UNIX workstationwhere HP OpenView is installed. This is a text file. Transfer it as CDtrap.conf.

2. Use the HP OpenView process, xnmevents, to load CDtrap.conf into the trapd.conf for HP OpenView(usually in the $OV_DB directory).

Note: Refer to the HP OpenView documentation for correct syntax for the xnmevents process.

Chapter 2. Configuration Guide 71

Import the IBM Connect:Direct MIBPerform this step if you are using SNMP Trap agent to communicate with the HP OpenView Network NodeManager.

1. Transfer the Connect:Direct for z/OS MIB, $CD.SDGAMIB(DGAZMIB), to the workstation where HPOpenView is installed. This is a text file. Transfer it as DGAZMIB.mib.

2. Use the HP OpenView process, xnmloadmib, to load the Connect:Direct for z/OS MIB into the MIBdatabase (usually in the $OV_DB directory).

Note: Refer to the HP OpenView documentation for correct syntax for the xnmloadmib process.

NetView for SNMP CustomizationNetwork Management applications do not recognize or display the traps without the IBM Connect:Directtrap configuration file and Management Information Block (MIB). Use the information to customize andload these files for the IBM® Tivoli® Netview application.

Customizing Tivoli NetView with the Tivoli Enterprise ConsolePerform the following tasks to customize Tivoli NetView using the Tivoli Enterprise Console. Refer to theappropriate Tivoli NetView documentation for the proper command syntax.

Importing the IBM Connect:Direct Trap Configuration FileTransfer and execute the CDTrap_NetView.sh script to add the Connect:Direct for z/OS trap in to thetrapd.conf file.

1. Transfer the file, $CD.SDGATRP(DGAZTRAP), to the appropriate computer. This is a text file. Transfer itas CDTrap_NetView.sh.

2. Run the CDTrap_NetView.sh script to add the traps to the trapd.conf file.

Importing the IBM Connect:Direct MIBTo import the product MIB:

1. Transfer the product MIB, $CD.SDGAMIB(DGAZMIB), to the appropriate machine. This is a text file.Transfer it as SDGAMIB.mib.

2. Use the UNIX process, xnmloadmib, to load the Connect:Direct for z/OS MIB into the MIB database.

Setting Up Tivoli NetView RulesSet up a rule using nvrsEdit that forwards the IBM Connect:Direct trap messages to the Tivoli EnterpriseConsole. A sample rules files is provided in $CD.SDGATRP(DGAZIVRS) that can be transferred as a textfile to CDTrap_Tivoli.rs.

Processing the Boroc File1. Transfer the $CD.SDGATRP(DGATOROC) file to the appropriate machine in the appropriate directory

(usually TEC_CLASSES). This is a text file. Transfer it as CDTrap_Tivoli.boroc.2. Compile the rules using the wcomprules process.3. Load the rulebase using the wloadrb process.4. Recycle the TEC event server, wstopesvr and wstartesvr.

72 IBM Connect:Direct for z/OS: Documentation

Customizing Tivoli NetView without the Tivoli Enterprise ConsoleUse the following information to customize Tivoli Netview for SNMP traps without the Tivoli EnterpriseConsole.

Importing the IBM Connect:Direct Trap Configuration FileTransfer and execute the CDTrap_NetView.sh script to add the Connect:Direct for z/OS trap in to thetrapd.conf file.

1. Transfer the file, $CD.SDGATRP(DGAZTRAP), to the appropriate computer. This is a text file. Transfer itas CDTrap_NetView.sh.

2. Run the CDTrap_NetView.sh script to add the traps to the trapd.conf file.

Importing the IBM Connect:Direct MIBTo import the product MIB:

1. Transfer the product MIB, $CD.SDGAMIB(DGAZMIB), to the appropriate machine. This is a text file.Transfer it as SDGAMIB.mib.

2. Use the UNIX process, xnmloadmib, to load the Connect:Direct for z/OS MIB into the MIB database.

Disabling SNMP TrapsConnect:Direct for z/OS provides support for an SNMP agent to send SNMP traps to alert a networkmanager of certain events. An event is any IBM Connect:Direct message that is written to the consoleusing SCWTO or DMWTO. Each event is triggered by the IBM Connect:Direct message ID and the trap text(short message text of that IBM Connect:Direct message). The IBM Connect:Direct events generated aredefined by category and type.

1. Edit the member DGAXSNMP in the $CD.DGASAMP dataset and disable any SNMP trap that you do notwant IBM Connect:Direct to trigger.

2. Specify the SNMP.DSN initialization parameter to have the SNMP traps specified in Step 1 disabled atinitialization.

Note: Refer to the IBM Connect:Direct for z/OS Administration Guide for a description of each SNMPtrap.

Configuring IBM Connect:Direct without SNA SupportTo configure IBM Connect:Direct without SNA support:

1. Define the following initialization parameters, which allow IBM Connect:Direct to function in a TCP-only environment:

• SNA=NO• TCP=OES• TCP.LISTEN=((addr , port) , (addrn , portn))• TCP.API.LISTEN=((addr , port) , (addrn , portn))• MAXUSER=nnn

See Global Initializaton Parameters for detailed information on these parameters.

When SNA=NO, you must specify the TCP parameters, and define a TCP port to accept API signonsand commands. The MAXUSER parameter controls the number of concurrent API signons. Thefollowing screen shows an example:

Chapter 2. Configuration Guide 73

SNA=NOTCP=OESTCP.LISTEN=(199.1.1.2,4199)TCP.API.LISTEN=(199.1.1.2,4198)MAXUSERS=10

This sample configuration allows IBM Connect:Direct to initialize without SNA, support only TCPconnections, and authorize up to 10 concurrent API signons using TCP/IP.

2. Define the network map entries. See Maintaining the Network Map for information.

Define LOCAL node with the second positional parameter as NO-VTAM. The LOCAL node definitionis used to define the SNA ACBNAME that IBM Connect:Direct opens in an SNA environment. Whenyou specify NO-VTAM, IBM Connect:Direct does not attempt to open the VTAM ACB. See the examplebelow.

Define the PNODE=SNODE adjacent node entry as TCP and specify a TCPAPI parameter. ThePNODE=SNODE adjacent node entry is required to enable API signons. This node definition enablesIBM Connect:Direct to run Processes that loop back to this primary node and allows for API signonwithout the API specifying the transport protocol. Use the LDNS parameter to assign the domain nameor define the IP address within the adjacent node entry. The following screen shows an example:

LOCAL.NODE=(( CD.OS390 , NO-VTAM , SUPERUSR) - TCQ=( CD.TCX - CD.TCQ) )/* *//* Pnode=Snode Adjacent node entry *//* Allows for Pnode=Snode processes and *//* allows for API signons thru TCP/IP *//* */ ADJACENT.NODE=(( CD.OS390, 4199, 10.20.200.2, TCP) - PARSESS=(53 2) - TCPAPI=(4198,10.20.200.2) )Or ADJACENT.NODE=(( CD.OS390, 4199, , TCP) - PARSESS=(53 2) - LDNS=long.domain.name - TCPAPI=(4198,) )

3. From $CD.SDGAJCL, execute DGAJLOAD, the network map installation job, to load the network map.

If IBM Connect:Direct uses SNA, you can initialize IBM Connect:Direct even if SNA is not available. Thistask is accomplished by setting the SNA= initialization parameter to YES.

If the SNA= initialization parameter is YES and you try to start IBM Connect:Direct when SNA is notavailable, or if SNA becomes unavailable during a session, the system displays the following message:

VTAM or Connect:Direct inactive, Type CANCEL, CONTINUE, RETRY or NOVTAM

The following table describes each option:

Option Description

Cancel IBM Connect:Direct does not initialize.

Continue IBM Connect:Direct continues initializing without SNA and keeps trying toestablish the SNA session. IBM Connect:Direct sends a message to the operatorevery 20 minutes indicating that it is trying to start the SNA session, until thesession is established.

Any SNA Processes that are queued or submitted during this time period areplaced in the Wait queue. These Processes can execute after the SNA session isestablished.

74 IBM Connect:Direct for z/OS: Documentation

Option Description

Retry IBM Connect:Direct tries to establish the SNA session before continuinginitialization. After 20 attempts, it displays the “VTAM or IBM Connect:Directinactive” message again. You can again choose one of the options in this table.

NoVTAM IBM Connect:Direct continues initializing without SNA support and does not tryto establish the SNA session. Any SNA Processes that are queued or submittedare placed in the Wait queue, where they remain until an SNA session is laterestablished.

Overriding IBM Connect:Direct for z/OS Default Language Environment Run-Time Options

Language Environment run-time options can be overridden in Connect:Direct by adding a CEEOPTS DD tothe Connect:Direct startup JCL. This DD should point to a dataset or PDS member. The CEEOPTS datasetor PDS must be RECFM=F or FB. Output will be directed to the CEEOUT DD if it is present. If there is noCEEOUT DD, it will be dynamically allocated to SYSOUT.

For example, to see the Language Environment run-time options report, specify:

RPTOPTS(ON)

To see that report and the Language Environment storage report, specify:

RPTOPTS(ON) ,RPTSTG(ON)

These Language Environment reports are generated at Connect:Direct SHUTDOWN time, but only ifthe Language Environment enclave ends "normally." Thus, you will not see them if you cancel yourConnect:Direct job. An example of the use of the Language Environment storage report would be to tunethe HEAP and HEAPPOOLS runtime options so that Language Environment will more efficiently allocatestorage resources to multiple concurrent COPY tasks.

Note: For more information on Language Environment run-time options, refer to the LanguageEnvironment Customization guide for the current level of z/OS.

The following table lists the default settings of the Language Environment run-time options.

OPTION DEFAULT VALUE

ABPERC NONE

ABTERMENC RETCODE

AIXBLD OFF

ALL31 ON

ANYHEAP 1M, 4M, ANYWHERE, FREE

BELOWHEAP 32K, 32K, FREE

CBLOPTS OFF

CBLPSHPOP OFF

CBLQDA OFF

CHECK OFF

COUNTRY US

Chapter 2. Configuration Guide 75

OPTION DEFAULT VALUE

DEBUG OFF

DEPTHCONDLMT 10

ENVAR '_CEE_ENVFILE=DD:ENVIRON'

ERRCOUNT 0

ERRUNIT 6

FILEHIST OFF

HEAP 16M,16M, ANYWHERE, FREE, 4K, 4K

HEAPCHK OFF, 1, 0

HEAPPOOLS ON, 48, 1, 88, 1, 416,1 , 1464, 1, 2200, 1, 9000, 1, 12496,1,1 6384,1, 32768, 1, 34920, 1, 49256, 1, 64536, 28

INQPCOPN ON

INTERRUPT OFF

LIBSTACK 1K,1K, FREE

MSGFILE CEEOUT, FBA,121, 0, ENQ

MSGQ 15

NATLANG ENU

NOAUTOTASK null

NOTEST ALL, *, PROMPT, INSPPREF

NOUSRHDLR ''

OCSTATUS ON

PC OFF

PLITASKCOUNT 20

POSIX ON

PROFILE OFF, ''

PRTUNIT 6

PUNUNIT 7

RDRUNIT 5

RECPAD OFF

RPTOPTS OFF

RPTSTG OFF

RTEREUS OFF

SIMVRD OFF

STACK 128K, 128K, ANYWHERE, KEEP, 512K,128K

STORAGE NONE, NONE, NONE, 8K

TERMTHDACT UADUMP

THREADHEAP 4K, 4K, ANYWHERE, FREE

76 IBM Connect:Direct for z/OS: Documentation

OPTION DEFAULT VALUE

THREADSTACK ON, 512K,128K, ANYWHERE, KEEP, 512K,128K

TRACE OFF, 8192, DUMP, LE=3

TRAP ON, NOSPIE

UPSI 00000000

VCTRSAVE OFF

XPLINK OFF

XUFLOW AUTO

IBM Connect:Direct Enqueue Resource ManagementThis topic includes definitions of IBM Connect:Direct resources for a Multi-Image Manager (MIM) orGlobal Resource Serialization (GRS) system.

Major (Qname) Minor (Rname) Scope Description

NDMGDG GDG BaseDSName

SYSTEMS Issued during allocation of a GDG datasetwhen GDGENQ=YES.

NDMNTMAP APPLID SYSTEMS Issued while processing the APPLID recordfor a signon. When the APPLID is found andopened successfully, the DEQ is issued. ThisENQ could be held for awhile depending onthe number of signons and the number ofAPPLIDs in the list.

NDMUPDNM NetmapDSName

SYSTEMS Issued during signon while processing theNetmap. Also, issued while processing aNetmap update and held for the entire update.To lock out all API while the Netmap is beingupdated, NDMUPDNM could be held awhiledepending on the parameters in the updatefile.

NDMTCX TCQ indexDSName (TCX)

SYSTEMS Issued from several places to lock out all APIand other TCQ updates.

TCXESF TCQ indexDSName (TCX)

SYSTEMS Issued during initialization to lock all ESFupdates. Released after initialization of theTCQ/TCX is complete. Also issued during anESF submit. Serialize processing between ESFsubmits and initialization.

Note: MIM now handles the cleanup of its QCB control blocks and the use of SCOPE=ALL is no longervalid. Use one of the following parameters appropriate for your system:

• Code SCOPE=RESERVE if single system.• Code SCOPE=SYSTEMS if using shared DASD (for example, SDF).• Code SCOPE=SYSTEM if not using shared DASD.• When in doubt, code SCOPE=SYSTEMS.

Chapter 2. Configuration Guide 77

Initialization ErrorsThis topic describes the causes of common errors, such as inadequate storage or errors in the statisticslog, that may occur when you initialize Connect:Direct for z/OS.

Note: For all initialization errors related to Strong Password Encryption, see Troubleshooting Possible SPEProblems in the IBM Connect:Direct Secure Plus for z/OS Implementation Guide.

For initialization warnings related to certificate validation checks, see Troubleshooting in the IBMConnect:Direct Secure Plus for z/OS Implementation Guide.

In addition to the initialization errors described in this topic, you may see different error messages intraces, which are also related to initialization:

• If you receive a return code of 16, initialization terminates and error messages appear in the JES log.The messages inform you if one or more of the initialization parameters cannot co-exist with any of theother parameters specified in the initialization parameters file. IBM Connect:Direct initializes only whenyou remove the incorrect parameters.

• If you receive a return code of 4 when you stop IBM Connect:Direct, be sure to review the NDMLOG forSITA995I messages indicating obsolete parameters. Once you remove the parameters, these messagesno longer appear in the NDMLOG trace and IBM Connect:Direct ends with a return code of 0. For moreinformation on traces, see Isolating Problems in the IBM Connect:Direct for z/OS Administration Guide.

• If you receive a return code of 8A in the RPLERRCK trace when you start IBM Connect:Direct and youhave multiple TCP/IP stacks defined, the message, No such device or address (STCO999E), appears inthe trace. If you have only one TCP/IP stack defined, this is normal and no cause for alarm. If you are inan environment where multiple TCP/IP stacks are defined, you will want to investigate the situation andmake sure the correct TCP stack is specified.

Overriding IBM Connect:Direct Initialization ParametersInitialization parameters are set up during installation. When an error occurs, it may be necessary to alterthese initialization parameters. For example, refresh the TCQ if Processes are hanging and the queuebecomes corrupted.

You can override individual initialization parameters by specifying the override on the EXEC statement inthe startup job stream as shown in the following figure.

Note: In a IBM Connect:Direct/Plex, only override initialization parameters allowed in the localinitialization parameters file. Use the PARM= keyword in the EXEC statement at system startup.

In a IBM Connect:Direct/Stand-alone Server environment, however, you can override global initializationparameters with the PARM= keyword in the EXEC statement.

In this example, the startup job is specifying a cold start of the IBM Connect:Direct TCQ (TCQ=COLD),overriding the TCQ= value specified in the initialization parameters file.

78 IBM Connect:Direct for z/OS: Documentation

//JOBNAME JOB (ACCT),NAME,CLASS=M,NOTIFY=TSOID,MSGCLASS=X,TIME=1440 //* //* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ //* IBM Connect:Direct */ //* THIS JOB STREAM WILL INVOKE THE CONNECT:DIRECT DTF. */ //* CHANGE $CD TO YOUR HIGH-LEVEL PREFIX FOR CONNECT:DIRECT. */ //* */ //* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ //* //CDITST PROC CDPREF=,PARMMEM= //CDITST EXEC PGM=DGADINIT, // PARM=(’&CDPREF..PARMLIB(&PARMMEM),’, // ’TCQ=COLD’), // REGION=3000K //SYSUDUMP DD SYSOUT=* //STEPLIB DD DSN=&CDPREF..SDGALINK, // DISP=SHR //DMPUBLIB DD DSN=&CDPREF..SDGAPROC, // DISP=SHR //ESTAE DD SYSOUT=* //RPLERRCK DD SYSOUT=* // PEND //*//CDITST EXEC DGAJNETL,CDPREF=$CD,PARMMEM=DGAINT01

Initialization ErrorsThis section describes the causes of common errors associated with initializing IBM Connect:Direct.

Condition: Inadequate StorageIBM Connect:Direct does not initialize because of inadequate storage (GETMAIN or FREEMAIN requestfailed).

Error Messages

SITA037I SITA042I SITA043I SITA044I SITA045I SITA047I

SITA049I SITA050I SITA078I SITA080I SITA096I SITA097I

SITA098I SITA099I SITA122I

Use the following table to troubleshoot the storage problem.

Cause Action Data to Collect

Inadequate addressspace is allocated to theIBM Connect:Direct DTFregion.

Review the short and long text messages.Check the IBM Connect:Direct startup jobstream and the amount of storage allocatedto the IBM Connect:Direct region by checkingthe region parameter on the job card. UseREGION=0M or as advised by CustomerSupport.

• IBM Connect:Direct errormessage

• Region/partition size

Condition: Server Initialization Error (SXTA101I) with ABEND U1024The CDPLEX.MAXSERVER value has been exceeded by Server A.

Chapter 2. Configuration Guide 79

Error Cause Action

ABEND U1024 The IBM Connect:Direct/Plex Server A(where A is the name of a particularserver in a IBM Connect:Direct/Plexenvironment) has been rejected by theIBM Connect:Direct Manager. Server Aterminated with a User ABEND code ofU1024.

Correct the CDPLEX.MAXSERVER globalinitialization parameter by increasingthe value to cover the number ofservers in the IBM Connect:Direct/Plexenvironment, and restart the server.

Condition: ABEND U0044Use the following table to troubleshoot this abnormal end condition (ABEND).

Error Cause Action Collect

ABENDU0044

GETMAIN failed 1. JCL set REGION=0M2. Initialization parameters set

MEMLIMIT=2M3. Initialization parameters set

TRACE.BUFFER=0

If there is still an issue aftertaking the recommended actions,collect the SVCDUMP and job log.

Condition: Error While Allocating or Opening Initialization Parameters FileAn error occurs while allocating or opening the initialization parameters file.

Error Messages

SITA063I SITA070I SITA121I SITA123I SITA291I SITA292I

SITA293I SITA294I SITA501I SITA502I SITA505I

Cause Action Data to Collect

IBM Connect:Directinitialization parametersfile does not exist, or theparameter on the EXECstatement is specifiedincorrectly.

Review the short and long text messages.Look at the IBM Connect:Direct startup JCLfor the EXEC statement. Ensure that thespecified initialization parameters datasetexists and is correct.

• IBM Connect:Directstartup JCL

• DMGSCMAP STARTUP file

Condition: Initialization Parameter ErrorsIBM Connect:Direct does not initialize because of initialization parameter errors.

Error Messages

SITA003I SITA014I SITA018I SITA021I SITA038I SITA039I

SITA040I SITA041I SITA063I SITA071I SITA072I SITA073I

SITA079I SITA082I SITA083I SITA084I SITA085I SITA086I

SITA087I SITA088I SITA089I SITA091I SITA092I SITA093I

SITA094I SITA095I SITA104I SITA105I SITA106I SITA148I

SITA201I SITA202I SITA213I SITA214I SITA215I SITA216I

SITA217I SITA220I SITA221I SITA222I SITA223I SITA224I

80 IBM Connect:Direct for z/OS: Documentation

Error Messages

SITA225I SITA226I SITA227I SITA228I SITA230I SITA231I

SITA232I SITA233I SITA234I SITA242I SITA250I SITA251I

SITA252I SITA253I SITA254I SITA260I SITA261I SITA262I

SITA263I SITA270I SITA271I SITA272I SITA273I SITA280I

SITA281I SITA282I SITA283I SITA285I SITA286I SITA287I

SITA300I SITA506I SITA507I SITA508I SITA509I SITA510I

SITA511I SITA512I SITA513I SITA514I SITA515I SITA516I

SITA517I SITA518I SITA540I

Use the following table to troubleshoot the initialization parameters problem.

Cause Action Data to Collect

Syntax errors or errors inthe values specified existfor one or more initializationparameters.

Review the short and long textmessages. Note the messages thatyou see on the console duringinitialization to determine the reasonfor the error. Verify that any commentspreceding parameters are followedby ‘*/'. Refer to the appropriate IBMConnect:Direct installation guide forthe valid parameter values. Correctthe parameter in the initializationparameters file, and restart IBMConnect:Direct.

• IBM Connect:Direct errormessage

• Initialization parameters file

Condition: IBM Connect:Direct VSAM File ErrorIBM Connect:Direct does not initialize because of an error with one of the IBM Connect:Direct VSAM files:the message file, authorization file, type file, network map file, statistics file, checkpoint file, or TCQ file.

Error Messages

SITA055I SITA056I SITA057I SITA059I SITA060I SITA061I

SITA062I SITA064I SITA065I SITA066I SITA075I SITA076I

SITA077I SITA100I SITA101I SITA102I SITA103I SITA110I

SITA111I SITA112I SITA113I SITA130I SITA131I SITA132I

SITA133I SITA160I

Use the following table to troubleshoot the Connect:Direct for z/OS VSAM file error.

Chapter 2. Configuration Guide 81

Cause Action Data to Collect

An error occurred whileopening the file, or VSAMencountered a physical orlogical error. The VSAMfile cannot be definedand loaded correctly, thename of the file mightbe specified incorrectly,or the file might becorrupted.

Review the short and long text messages.Verify that the name of the file is specifiedcorrectly in the initialization parameters file.Also, verify that the file is a correctly definedVSAM dataset and loaded. Refer to VSAMFiles DASD Requirement and Description andDefine the IBM Connect:Direct VSAM Files .

• IBM Connect:Directmessages

• Any messages issued bythe VSAM AMS InterfaceProgram (IDCAMS) whenthe IBM Connect:DirectVSAM file was defined andloaded

Condition: VTAM Initialization ErrorsIBM Connect:Direct does not initialize because of errors with VTAM initialization.

Error Messages

SITA004I SITA005I SITA048I SITA051I SITA052I SITA053I

SITA054I SITA090I user ABEND U0075

Use the following table to troubleshoot the VTAM initialization error.

Cause Action Data to Collect

The IBM Connect:DirectDTF APPLID is definedincorrectly, the APPLIDlogmode table is incorrector is not found,the DTF APPLID hasa VTAM passwordassociated with it, or theIBM Connect:Direct DTFAPPLID is not active.

Review the short and long text messages.Ensure that the DTF APPLID is active.Ensure that the APPLID specified in theLOCAL.NODE entry of the network map iscorrectly specified and is defined to VTAM.Check the ESTAE output for additional errorinformation. If a VTAM password is associatedwith the IBM Connect:Direct APPLID, removeit, and do not refer to it in the network map.

• ESTAE output• IBM Connect:Direct

network map• APPLID definition• Logmode table entry

Condition: Invalid Security Environment (SITA997I)Use the following table to troubleshoot the security environment error.

Cause Action Data to Collect

The thread-level securityis not valid between IBMConnect:Direct and z/OSUNIX System Services.

If your installation implemented ProgramAccess to Datasets (PADS) functionalitywithin your security system (such as RACF,TSS, ACF2), include the IBM Connect:Directdatasets in your Program Control List (PCL).

• SYSLOG from IBMConnect:Direct startup

• Security system profilesfor the resources deniedin the SYSLOG

Condition: Statistics Log ErrorIBM Connect:Direct does not initialize because of an error in the statistics log.

Error Messages

SSTI004I SSTI005I SSTI006I SSTI007I SSTI008I SSTI009I

SSTI010I SSTI011I SSTI012I SSTI013I SSTI014I SSTI015I

82 IBM Connect:Direct for z/OS: Documentation

Error Messages

SSTI016I SSTI017I SSTI018I SSTI019I SSTI020I SSTI021I

SSTI022I

SITA059I and user ABEND U0070 follow one of the previous error messages. The cause and necessaryaction to take depend on the SSTIxxxI message as explained in the following sections.

SSTI004IFile pair ESDS dataset has invalid CI SIZE.

Cause Action

The ESDS CI SIZE is less than 2048.The minimum acceptable CI SIZE for thisdataset is 2048.

Review short and long text messages. Delete and redefinethe file pair ESDS dataset and ensure a CI SIZE that isgreater than or equal to 2048.

SSTI005IInvalid KSDS dataset type in file pair.

Cause Action

Review both the short text and long text IBMConnect:Direct messages. While verifyingthe dataset, it was found that the datasettype was not KSDS.

Verify that the statistics file pair KSDS dataset is correctlyallocated. If no allocation is correct, delete and redefinethe KSDS dataset.

SSTI006IInvalid KSDS dataset key length.

Cause Action

The key length of the file pair KSDS datasetis invalid.

Review short and long text messages. Refer to theplatform-specific IBM Connect:Direct installation andadministration guide for the correct length.

SSTI007IInvalid file pair KSDS dataset key offset.

Cause Action

The key offset for the KSDS dataset is not 0. Review short and long text IBM Connect:Direct messages.Delete and redefine the KSDS with the correct key offset.

SSTI008IFile pair has empty ESDS but non-empty KSDS.

Chapter 2. Configuration Guide 83

Cause Action

The ESDS dataset is empty, but the KSDSdataset has data in it. One possible reasonis that the ESDS dataset was reset, but theKSDS was not.

Review both short and long text messages. The ESDS andKSDS datasets must both be empty or must both containdata. Either delete and redefine the KSDS dataset,restore the ESDS dataset, or specify STAT.INIT=COLD.IBM Connect:Direct opens both datasets with RESET atinitialization time.

SSTI009IFile pair has empty KSDS but non-empty ESDS.

Cause Action

The KSDS dataset is empty, but the ESDSdataset has data in it. One possible reasonis that the KSDS dataset was reset, but theESDS was not.

Review both short and long text messages. Both KSDSand ESDS datasets must be empty or contain data. Eitherdelete and redefine the ESDS dataset, restore the KSDSdataset, run batch utility DMSTBKEY to rebuild the KSDSdataset, or specify STAT.INIT=COLD. IBM Connect:Directthen opens both datasets with RESET at initializationtime.

SSTI010IError reading the file pair KSDS control record.

Cause Action

While attempting to read the KSDS controlrecord, an error code was returned.

Review both short and long text messages. Verify that theKSDS dataset is correctly defined. Register 15 containsthe VSAM GET return code. To reuse the dataset, specifySTAT.INIT=COLD in the initialization parameters andrestart IBM Connect:Direct.

SSTI011IKSDS control record ESDS name does not match.

Cause Action

The KSDS control record contains thename of the matching or paired ESDSdataset. When the KSDS and ESDS datasetnames are built by IBM Connect:Direct atinitialization time based on STAT.DSN.BASE,the ESDS dataset name that the system builtdid not match the ESDS dataset name in theKSDS control record.

Review both the short text and long text IBMConnect:Direct messages. Do one of the following:

• Run batch utility DMSTBKEY to rebuild the KSDSdataset control record.

• Delete and redefine both KSDS and ESDS datasets.• Specify STAT.INIT=COLD (Connect:Direct opens all file

pairs with RESET.).

SSTI012IKSDS control record ESDS CI SIZE do not match.

84 IBM Connect:Direct for z/OS: Documentation

Cause Action

The KSDS control record contains the CISIZE of the matching or paired ESDSdataset. The CI SIZE from the KSDS controlrecord is not equal to the CI SIZE of thepaired ESDS dataset that is opened.

Review the short and long text messages. Verify that thestatistics file pair is identified with the STAT.DSN.BASEand STAT.FILE.PAIRS initialization parameters. If the CISIZE of the ESDS file has changed, you must run theDMSTBKEY batch utility to rebuild the information in thekey-sequenced cluster.

SSTI013IError reading the ESDS control record.

Cause Action

While attempting to read the ESDS controlrecord, an error code was returned.

Review both the short and long text messages. Verifythat the ESDS dataset is correctly defined. Register 15contains the VSAM GET return code. To reuse the dataset,specify STAT.INIT=COLD in the initialization parametersand restart IBM Connect:Direct.

SSTI014IInvalid ESDS control record.

Cause Action

IBM Connect:Direct read the first record inthe ESDS dataset; however, it was not thecontrol record. Either the file is not a IBMConnect:Direct statistics file, or the file wascorrupted after being written.

Review both the short text and long text messages. Verifythat the statistics file pair is correctly defined usingthe STAT.DSN.BASE and STAT.FILE.PAIRS initializationparameters. If the file was corrupted and it is the KSDScluster of the pair, then the information can be rebuiltby running the DMSTBKEY batch utility for the file pair.If the file was corrupted and it is the ESDS cluster ofthe pair, then the statistics information in the file pairis lost. In this case, both files of the pair must beempty before IBM Connect:Direct initializes successfully.Specify STAT.INIT=COLD in the initialization parametersto initialize successfully.

SSTI015IInvalid file pair sequence.

Cause Action

The files that comprise the statistics filepair list are not arranged in chronologicalorder. IBM Connect:Direct requires that allnon-empty statistics file pairs be orderedchronologically based on the date and timeof the oldest data in each pair.

Note:

Review the short and long text IBM Connect:Directmessages. Verify that the statistics file pair list is correctlydefined using the STAT.DSN.BASE and STAT.FILE.PAIRSinitialization parameters. If the reason for the problem isnot apparent, it might be necessary to archive or copyall ESDS file pairs to preserve the current statistics data.Then delete and redefine all statistics file pair clusters.

Note: Although IBM Connect:Direct processes the statistics file pair list in a circular or wrap aroundmethod, the first file pair in the list does not always contain the oldest data.

IBM Connect:Direct verifies the order using the following steps:

Chapter 2. Configuration Guide 85

1. IBM Connect:Direct locates the file pair containing the oldest data.2. From that point, IBM Connect:Direct examines each non-empty file pair in the list. If the oldest data

is not located in the first file pair, when the search reaches the last file pair in the list, it wraps to thebeginning of the list. Each successive non-empty file pair must have a later date than the previous pair.

IBM Connect:Direct always maintains statistics records in strict chronological order. If the records arenot in chronological order at initialization, IBM Connect:Direct assumes that the list or the files areincorrectly altered since IBM Connect:Direct last wrote them.

SSTI016IWARNING: KSDS of file pair may be too small.

Cause Action

The size of the key-sequenced cluster of thefile pair named is less than 10% of the sizeof the associated entry sequenced cluster.This condition can lead to premature fillingof the key-sequenced cluster and wastedspace in the entry-sequenced cluster.

Review the short and long text IBM Connect:Directmessages. Examine the SSTS005I message issued whenthe file pair fills to determine the amount of the file IBMConnect:Direct was able to use. Set the key-sequencedcluster to 15% of the size of the entry-sequenced cluster.

SSTI017IWARNING: KSDS of file pair may be too large.

Cause Action

The size of the key-sequenced cluster of thefile pair named is more than 30% of the sizeof the associated entry-sequenced cluster.This condition can lead to premature fillingof the entry-sequenced cluster and wastedspace in the key-sequenced cluster.

Review both the short text and long text IBMConnect:Direct messages. Examine the SSTS005Imessage issued when the file pair fills to determine theamount of the file IBM Connect:Direct was able to use.Set the key-sequenced cluster to 15% of the size of theentry-sequenced cluster.

SSTI018IFile pair WHERE condition found.

Cause Action

During statistics initialization, a warningmay have been issued specifying the KSDSdataset is either too small or too large. Thismessage contains the FILE PAIR where thissituation occurred

None

SSTI019INo active file pair found.

Cause Action

Statistics initialization could not determinewhich of the statistics file pairs was theactive pair. The ESDS of each pair contains astatus flag that indicates which pair is active.The active flag was not found in any of theESDS clusters.

Review both the short text and long text IBMConnect:Direct messages. Archive or copy all ESDS filepairs to preserve the current statistics data. Then deleteand redefine all statistics file pair clusters.

86 IBM Connect:Direct for z/OS: Documentation

SSTI020IMore than one file pair active.

Cause Action

For any given sequence of statistics filepairs, only one set can be active at atime. During IBM Connect:Direct statisticsinitialization, more than one set was foundto be active. This condition occurs whenmixing old file pairs with current ones

Review both the short text and long text IBMConnect:Direct messages. Empty the files by deleting andredefining the file pairs. None of the file pairs are active.Another alternative is to set STAT.INIT=COLD forcing IBMConnect:Direct to open each set of file pairs with RESETat initialization time. If you are interested in retaining thedata in the files, archive them first, then continue withone of the previous two methods.

SSTI021IMore than one file pair is both not complete and not empty.

Cause Action

The mixing of old file pair datasets withcurrent file pairs can cause this result.Another cause is incorrect modificationof file pairs between executions of IBMConnect:Direct.

Review both the short text and long text IBMConnect:Direct messages. Verify that the statistics filepair list is correctly defined using the STAT.DSN.BASEand STAT.FILE.PAIRS initialization parameters, andrestart IBM Connect:Direct. You can also use theSTAT.INIT=COLD startup parameter.

SSTI022IInvalid ESDS dataset type in file pair.

Cause Action

While verifying the ESDS dataset, it wasdetermined that the dataset type was notESDS

Review both the short text and long text IBMConnect:Direct messages. Verify that the statistics filepair ESDS dataset is correctly allocated. If the datasetis not correctly allocated, delete and redefine the ESDSdataset.

SSTI028I

Cause Action

A KSDS is not at the current level.IBM Connect:Direct was started withStat.INIT=WARM and is using a Stat File Pairthat was last reset by a different level of IBMConnect:Direct.

See accompanying message SSTI029I.

Chapter 2. Configuration Guide 87

SSTI029ICause Action

See accompanying message SSTI028I. SELECT STATISTICS search by SNODE results areunpredictable until one of the following options isperformed:

1. Archive all inactive ESDSs reported by SSTI028Icontaining records you wish to keep. Then Switch StatFile Pairs. Lastly, archive the newly inactive Stat FilePair ESDS.

2. Shut down CD and run DMSTBKEY on all Stat FilePairs reported by SSTI028I. Then start CD withSTAT.INIT=WARM.

3. Shut down CD and archive all pairs reported bySSTI028I. Then restart CD with STAT.INIT=COLD.

Condition: TCQ.THRESHOLD Parameter Error (SITA186I)Use the following table to troubleshoot when the TCQ.THRESHOLD parameter has not been properlydefined.

Cause Action Data to Collect

If you receivethese messages duringinitialization, theTCQ.THRESHOLD parameteris not specified.

Specify the TCQ.THRESHOLD parameter as YES,NO, or a defined percentage value in the range0-99.

None

88 IBM Connect:Direct for z/OS: Documentation

Chapter 3. CICS Administration and User Guide

CICS InterfaceThe Customer Information Control System (CICS®) Interface provides a number of components thatenable users and applications to access, control, and transfer data across networks. The majorcomponents:

Component Description

Interactive UserInterface (IUI)

Enables users to transfer files, initiate applications, and monitor activity in a user-friendly environment.

ApplicationProgram Interface(API)

Enables the IUI and CICS Administration to communicate to the Data TransmissionFacility (DTF) through the session manager. The API interprets the commands, butit is the responsibility of the session manager to establish communication sessionsand perform standard session management functions.

Data TransmissionFacility (DTF)

Controls information distribution to other nodes in the network. In an IBMIBM Connect:Direct/Plex environment, the IBM Connect:Direct/Manager and IBMConnect:Direct/Servers form the DTF.

Extended SubmitFeature (ESF)Mode

Enables users to submit data for transmission even if the DTF is not active.IBM Connect:Direct requests sent to an inactive node are routed to the sendingTransmission Control Queue (TCQ) until the inactive node is initiated.

Components of the CICS InterfaceThe IBM Connect:Direct for z/OS installation offers an optional selection to use the CICS interface. Thefollowing figure illustrates a CICS implementation.

© Copyright IBM Corp. 1993, 2021 89

90 IBM Connect:Direct for z/OS: Documentation

CICS Screen ConventionsThis section describes the conventions for the CICS Interface. The screens are based on the standard IBM3270 Model 2 display. Use a terminal or terminal emulator that can handle the 3270 Model 2 mode.

The CICS Interface has the following screen conventions to help you input data and navigate within thesystem:

• All variable data is highlighted.• Variable fields contain underscore characters to indicate the size of each field.• Required fields are highlighted and optional fields are displayed at normal intensity.• Each screen in the User System contains information fields of various widths and attributes for user data

and for system-displayed data.

System FieldsAs you perform your user activities, the CICS Interface displays several system fields with currentinformation about your data, updates of system information, and responses to your Processes. Thesystem fields include the following:

Field Description

DATE The 8-character DATE field contains the system date expressed as month, day, andyear (MM/DD/YY) and occurs in the upper right corner of the screen.

TIME The 8-character TIME field contains the system time expressed as hours, minutes,and seconds (HH:MM:SS) and occurs in the upper right corner of the screen.

ESF MODE The 8-character ESF MODE field occurs in the upper right corner of the screen,and contains the ESF MODE flag in the event that the DTF is not working, and youare working under ESF. If the field contains the flag ESF MODE, you are workingunder ESF; if the field is blank, you are working with the DTF. A blank field indicatesnormal operation.

NODE The 16-character NODE field, displayed in the upper right corner of the screen,contains the name of your connected node.

MESSAGE The 75-character MESSAGE field occurs near the bottom of the screen. It containsthe system messages associated with the success or failure of your CICS Interfaceactivities. CICS Interface messages that can occur during normal operations arelisted in Product Messages .

Note: Some messages issued by the CICS Interface are actually Connect:Directfor z/OS messages (inquire with your administrator about the IBM Connect:Directmessage file, or select option MD from the PRIMARY MENU to exercise theMESSAGE DISPLAY screen features, or select PF2 to view the LAST MESSAGEscreen).

PF KeysFor those screens that have programmable function (PF) keys defined, you can select standard PF keys toassist you in the performance of CICS Interface activities, while you are at the current screen. You cannotredefine PF keys.

The following table describes the function of each PF key.

Keys Function

PF3 Exits the current screen, and takes you to the previous screen

PF5 Adds an entry to the list on the screen

Chapter 3. CICS Administration and User Guide 91

Keys Function

PF6 Deletes an entry from the list on the screen

PF7 Scrolls backward through the list of available data on the screen

PF8 Scrolls forward through the list of available data on the screen

PF9 Applies updates to screen information

PF10 Scrolls to the left on the screen

PF11 Scrolls to the right on the screen

ENTER Refreshes screen data or processes a line command

CLEAR Resets the data on the screen to default values

About the IBM Connect:Direct for z/OS CICS DocumentationThe documentation related to an IBM Connect:Direct for z/OS installation is for programmers and networkoperations staff who use the CICS interface to maintain Connect:Direct for z/OS. This This documentationassumes knowledge of the IBM z/OS operating system and CICS/TS. If you are not familiar with the IBMz/OS operating system or CICS/TS, refer to the IBM library of manuals.

Configuring the CICS Interface

Activate the CICS Component - OptionalActivation of the CICS Component of Connect:Direct for z/OS requires additional items to be updated. Anoverview is presented followed by a task checklist.

CICS Customization OverviewTo run the CICS Component, IBM Connect:Direct contains code that runs as an exit in CICS/TS to handlethe data movement between CICS and IBM Connect:Direct. To perform the install, several transactionsmust be defined. These transactions are in the RDO source provided. The default transaction codes startwith "DGA".

The interface between CICS and IBM Connect:Direct can start up during the CICS start, or it may bemanually activated after CICS is running. If you want the interface to start up automatically, you mustmodify the CICS PLTPI. If you want the interface to shut down automatically, you must customize theCICS PLTSD.

If you want to process Event Data within CICS, you must customize and install DGAQ247. If you need tocustomize DGAQ249 and DGAQM98, search for Using ESS with the CICS API. If you do not want to usethem, you can remove these entries from DGACCSD.

DGAQ249 reads Event Records out of the TDQ. If you need to add logic to DGAQ249 to do more than justread some records, you must customize it. Otherwise, you can remove its entries from DGACCSD.

You must define a few files, including the CONFIG file, which is handled with a REXX exec.

The CICS component has a set of transaction codes that you can accept as they are, or you may set yourown. The CICS component uses the following default transaction codes:

Transaction Code Description

DGA User Transaction

DGAA Administrator Transaction

DGAE Event Services

92 IBM Connect:Direct for z/OS: Documentation

Transaction Code Description

DGAI Initial Startup

DGAM API Monitor

DGAN User ESS Process Interface

DGAP Printer Driver Transaction

DGAT User Read/Process ESS

CICS Customization Checklist• Customize the RDO source.

The members to be customized are located in $CD.SDGACNTL.

Member Description

DGACCSD RDO source containing the Transactions, Program, File, Mapset, TDQ, andList definitions

DGACBCKO RDO source to remove prior release(s)

DGACBACK RDO source to back out the 5.1 release

• If you plan to migrate to this release from a prior release, review the IBM Connect:Direct for z/OS ReleaseNotes® for migration instructions. See Build the CICS Configuration File through ISPF for the panels thatthe REXX will display.

Build the CICS Configuration File through ISPFTo install the CICS feature, complete the following CICS panels:

• Configuration File - Control Parameter Record Creation• CICS DTF Record Creation• Configuration File - Network Record Creation

For detailed information on the field descriptions for this series of CICS-related panels, search for therecord type, namely, control, DTF node, or network records. You can also use the CICS AdministrationSystem later to modify the configuration information entered during the installation process.

You can use the following PF keys on the CICS screens.

PF Key Function

Enter Continue with the installation.

PF3 Return to the previous menu.

PF5 Terminate the installation.

1. Execute the CONFIG file REXX from a TSO/ISPF session, using option 6 from the ISPF Command Shell.($CD is the High Level Qualifier from the SMP/E install.)

EX '$CD.SDGAISPC(DGA#CONF)' '$CD'

2. Define the appropriate fields in the CICS Feature CONFIGURATION FILE - CONTROL PARAMETERRECORD CREATION panel and press Enter.

Chapter 3. CICS Administration and User Guide 93

------------- Connect:Direct CICS Feature ------ DATE-yyyy/mm/dd CONFIGURATION FILE - CONTROL PARAMETER RECORD CREATION TIME-hh:mm CMD ==> THIS PANEL IS USED TO GENERATE THE CONTROL.PARMS INFORMATION FOR USE BY Connect:Direct CICS. AUTO.SIGNON Y Y OR N SIGNON.REENTRY N Y OR N CONNECT:DIRECT.EQ.CICSID Y Y OR N SKIP.SIGNON.PANEL N Y OR N CICS.TRANSACTION.CODE (MONITOR) DGAM CICS.TRANSACTION.CODE (STARTUP) DGAI CICS.TRANSACTION.CODE (PRINT) DGAP CICS.TRANSACTION.CODE (ESO) DGAE CST.RETRY.INTERVAL 000500 HHMMSS SESSION.RETRY.INTERVAL 0100 MMSS ESF.RETRY.INTERVAL 001500 HHMMSS WORK.RETRY.INTERVAL 0015 MMSS MONITOR.INTERVAL 30 SS INACTIVE.INTERVAL 003000 HHMMSS MAX.SIGNON 0100 MAX.TASKS 02 01-99 STORAGE.SUBPOOL 127 002-127 MENU OPTIONS: CF Y SB Y SS Y SP Y SD Y SN Y MD Y Y OR N

3. Define the appropriate fields in the CICS Feature - CICS DTF RECORD CREATION menu and pressEnter. You must enter a DTF NODE NAME.

------------- Connect:Direct CICS Feature ------- DATE-yyyy/mm/dd CICS DTF RECORD CREATION TIME=hh:mm

CMD ==>

THIS PANEL ALLOWS YOU TO GENERATE A CONNECT:DIRECT CICS IUI.NODE RECORD TO BE USED TO INITIALLY LOAD THE CONFIGURATION FILE. THIS RECORD CAN BE UPDATED ONLINE USING THE 'DGAA' TRANSACTION.

PARAMETER VALUE ----------------------------- ------------------ DTF NODE NAME CD.DEV______ NETMAP DDNAME NETFINP_ DUMMY ID FOR DTF SIGNON CICSUSER SUPPRESS CONNECTION AT STARTUP Y Y OR N ESF SIGNON ALLOWED Y Y OR N MAXIMUM WORKER SUBTASKS 04 ENTRIES IN WORK QUEUE 050 OUTPUT RECORD LIMIT 01000 SLOW RESPONSE NOTIFICATION 0030 MMSS

4. Define the appropriate fields in the CICS Feature CONFIGURATION FILE - NETWORK RECORDCREATION menu and press Enter. You must enter information for at least one network node record.

94 IBM Connect:Direct for z/OS: Documentation

------------- Connect:Direct CICS Feature ------- DATE-yyyy/mm/dd CONFIGURATION FILE - NETWORK RECORD CREATION TIME-hh:mm

CMD ==>

THIS PANEL ALLOWS YOU TO GENERATE UP TO TEN NETWORK.NODE RECORDS TO BE USED TO INITIALLY LOAD THE CONFIGURATION FILE. THESE RECORDS CAN BE UPDATED ONLINE USING THE 'DGAA' TRANSACTION.

NODE NAME NODE DESCRIPTION NODE TYPE ------------------ -------------------------------- --------- ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ ________________ ______________________________ __ VALID NODE TYPES VALUES: 1=OS/390 2=VM 3=VSE 4=VMS 5=TANDEM 6=WIN95 7=OS/2 8=OS/400 9=UNIX 10=NETWARE 11=WINDOWS 12=MSP 13=MVS

5. Edit, customize, and submit member DGAJCICS in the $CD.SDGAJCL data set. This job loads the CICSConfiguration dataset using the data collected from the execution of DGA#CONF.

Load IBM Connect:Direct CICS Option into the CICS System DefinitionUse the following procedure to load the IBM Connect:Direct CICS option into the CICS system definition:

1. Edit, customize and submit $CD.SDGAJCL(DGAJCSDL).

This JOB creates and loads the CICS CONFIGuration data set using the data collected during theexecution of DGA#CONF.

This JOB also installs the DGACCSD contents into your CICS CSD.2. If you plan to upgrade from a prior release of IBM Connect:Direct, review Upgrading to IBM

Connect:Direct Version 5.1 in the IBM Connect:Direct for z/OS Release Notes.3. Edit, customize and submit $CD.SDGAJCL(DGAJCSDO).

This JOB uninstalls the prior IBM Connect:Direct CICS feature from your CICS CSD.4. If you need ESS processing, you must customize DGAQ247. You must also customize DGAQM98,

depending on changes to DGAQ247, and, possibly, DGAQ249. These are located in $CD.SDGASAMP.Search for Using ESS with the CICS API in the documentation.

5. If you customized ESS:

Customize, edit and run DGAXASMB to Assemble DGAQM98.

Customize, edit and run DGAXASMC for DGAQ247 or DGAQ249, or both.6. Modify the CICS startup JCL/JOB for the CICS that uses the CSD where the RDO source was installed

based on the information in $CD.SDGASAMP(DGAXCJCL).7. Bring up CICS and verify the install by performing the procedure in Starting the Connect:Direct for z/OS

CICS Interface.

Customize the CICS Interface OverviewCustomizing the CICS interface consists of the following tasks:

• Customizing and Installing the IBM Connect:Direct CICS Resource Definition Source• Modifying Your CICS Startup• Starting the IBM Connect:Direct CICS Interface

Chapter 3. CICS Administration and User Guide 95

Customize and Install the IBM Connect:Direct CICS Resource DefinitionSourceAll program, transaction, file, and associated definitions are provided in $CD.SDGACNTL(DGACCSD).DGACCSD contains Resource Definition source code, which you may need to customize to meet yoursite's needs.

CAUTION: If the CICS option was installed in a release prior to IBM Connect:Direct for z/OSversion 5.1, you must back out of the previous Resource Definition CSD source code by using theJCL in $CD.SDGAJCL(DGAJCSD) prior to running the $CD.SDGAJCL(DGAJCSDL) job referred to inthe following procedure.

To customize and install the IBM Connect:Direct CICS resource definition source:

1. Review the source (DGACCSD). Use the GROUP and LIST names provided or change them in order tohave unique names, if necessary.

2. Update the FILE definitions if any files have different High Level Qualifiers than what were specified inthe ISPF panels.

For each IBM Connect:Direct DTF that your CICS system will have an IUI with, you must have a Filedefinition statement that points to the network map used by that IBM Connect:Direct DTF. To tell theIUI what FILE definition CICS is using for the network map, the FILE name (DDName) must match theNETMAP DDName entered in the DTF NODE CONFIGURATION record for that IBM Connect:Direct DTF.

3. (Optional step) If you want to initialize IBM Connect:Direct during CICS startup or add IBMConnect:Direct CICS interface shutdown to the CICS shutdown, review $CD.SDGASAMP(DGAXPLT).This member contains macro source and instructions for the CICS systems programmer to build orupdate PLTPI and PLTSD entries.

Note: To make the IUI available immediately upon CICS startup, you must use the LIST name in theSIP GRPLIST (keyword) parameter list.

4. Verify that the JOB and PARM information is correct in $CD.SDGAJCL(DGAJCSDL).5. Shut down all CICS transaction servers.6. Run the $CD.SDGAJCL(DGAJCSDL) job.

Modify Your CICS StartupTo modify your CICS startup:

1. Review the $CD.DGASAMP(DGAXCJCL) member for a list of DD statements and their purposes. Copythe applicable DD statements from DGAXCJCL to your CICS startup JCL (PROC or JOB).

Note: Any DD that is normally controlled by RDO should not be replicated in the JCL.2. Modify any of the copied DD statements to use the correct High Level Qualifiers for dataset names as

needed.3. For any additional customization that may be required, see Using ESS with the CICS API in the IBM

Connect:Direct for z/OS Facilities Guide.4. Submit your CICS JCL for execution.

Starting the Connect:Direct for z/OS CICS InterfacePerform this task only if IBM Connect:Direct CICS is not part of the Program Load Table (PLT) initialization.

After starting CICS, start the IBM Connect:Direct CICS interface as follows:

1. Type the DGAA transaction code, and press Enter.2. Select option I from the PRIMARY MENU and press Enter to go to the INTERFACE screen.3. From the INTERFACE screen, select option A, and press Enter. When the message INTERFACE HAS

BEEN STARTED is displayed, press Enter to refresh the status information, and wait until ACTIVE isdisplayed in the INTERFACE STATUS field, and a transaction number is displayed in the MONITORTASK NUMBER field.

96 IBM Connect:Direct for z/OS: Documentation

4. Press PF3 to return to the PRIMARY MENU, select option N on the PRIMARY MENU, and press Enter togo to the NODE STATUS screen.

5. On the NODE STATUS screen, for each node you want to activate, select the line command A in thefield to the far left of each NODE STATUS line. When the date and time are displayed under theSESSION DATE/TIME heading, the node is activated.

Note: The node may already be active if the message SUPPRESS CONNECTION AT STARTUP = N isdisplayed on the DTF NODE screen during the installation procedures.

6. Press PF3 several times to exit the DGAA transaction, and then sign on to IBM Connect:Direct usingthe DGA transaction code.

Tune the CICS InterfaceTune IBM Connect:Direct CICS interface to enhance performance. Connect:Direct for z/OS CICS interfaceexits are not "threadsafe” and may cause performance issues if this application is not isolated to anon-threadsafe AOR.

Actual resource usage varies according to the implemented configuration, including the number of DTFnodes that can be signed on to by the CICS interface, the number of subtasks defined per node, and otherconsiderations, such as the types of commands executed.

You may want to tune your IBM Connect:Direct system, based upon guidelines provided to assist you inestimating the impact of Connect:Direct for z/OS on your CICS online environment for the file I/O buffers,auxiliary or main temporary storage, and transaction priorities and class assignments

File I/O BuffersYou can reduce file I/O buffers to correspondingly lighten the load on your virtual and real storage, butat the expense of increasing disk I/O activity. The configuration and user profile datasets are type VSAMand can participate in Local Shared Resource (LSR) buffer pools, designated for light-to-medium usagedatasets.

Auxiliary or Main Temporary StorageYou can choose main or auxiliary temporary storage as a trade off between using more real storage (main)and increasing disk I/O activity (auxiliary). The CICS interface makes heavy use of temporary storage,especially during SELECT PROCESS and SELECT STATISTICS operations.

CICS Dynamic Storage Area (DSA) UsageThe CICS interface uses the CICS DSA as follows:

• Approximately 1 KB is used by the CICS Task Control global exit.• Approximately 10–20 KB is used for transaction-related storage and temporary storage records by the

DGA and DGAA transactions.

In addition, the SELECT PROCESS (SP) and SELECT STATISTICS (SS) functions are heavy users of CICSTemporary Storage. Results returned by these functions are written to Temporary Storage as a series of300-byte records.

Parameters are provided on the DTF NODE configuration screen of the DGAA transaction (OUTPUTRECORD LIMIT) and on the IUI.NODE statement of the IBM Connect:Direct CICS Configuration Loadprogram (TDLIMIT) to limit the amount of data returned by these commands.

Above-the-Line StorageNon-CICS storage above the 16-megabyte line is used by the CICS interface as follows:

• Approximately 340 KB is used for IBM Connect:Direct API programs.

Chapter 3. CICS Administration and User Guide 97

• The CICS interface signon table, node table, and subtask tables are allocated above the line, with thetotal amount required calculated as follows.

36 + (18*(T+W)) + (304*S) + (224*N) + (144*T)

The following table describes the variables in the preceding example:

Variable Description

T The sum of the maximum subtask per node values or all nodes eligible to besigned on to by the CICS interface (MAXIMUM WORKER SUBTASKS on the DTF NODEconfiguration screen or VTAM®.SESSIONS on the IUI.NODE parameter of the CICSinterface Configuration Load program).

W The total number of entries in the WORK QUEUE for all DTF nodes.

S The value of the MAX.SIGNON parameter of the Configuration Parameters screen orCONTROL.PARMS statement of the Configuration Load program.

N The number of nodes eligible to be signed on to by the CICS interface (the number ofDTF.NODE records defined in the CICS interface configuration file).

Transaction Priorities and Class AssignmentsIf you find that heavy usage of the CICS interface is causing resource shortages in CICS, you may want toconsider imposing transaction class limits on the IBM Connect:Direct transaction. You can impose classlimits by first assigning a transaction class to the transaction, and then placing a limit on the number oftransactions in that class. You may also want to assign the IBM Connect:Direct transaction to a lowerpriority than those of other tasks in your system to increase system throughput.

Using the Administration SystemThe Administration System helps you configure and control the interface. Tasks you perform while usingthis system include:

• Configuring Connect:Direct for z/OS to provide functionality to users while maintaining optimumperformance

• Defining IBM Connect:Direct DTFs to which Connect:Direct for z/OS submits requests• Activating and deactivating the IBM Connect:Direct interface• Activating and deactivating the interface with specific IBM Connect:Direct DTFs• Adding, modifying, and deleting default user signon characteristics• Monitoring user activity and intervening if those activities compromise IBM Connect:Direct or the CICS

environment

The system guides you through a series of menus, prompts you for input, and performs the requestedfunction. If errors occur during the processing of your request, the system informs you of the cause of theerror and, in some cases, suggests remedial action.

Structure of the Administration SystemThe menu structure of the Administration System follows.

98 IBM Connect:Direct for z/OS: Documentation

By typing the correct data in the Administration menus and screens, perform the following tasks:

• Check and control user status (USER STATUS)• Add, update, and delete user signon characteristics (SIGNON DEFAULTS)• Activate and deactivate the IBM Connect:Direct DTF-to-CICS Interface (INTERFACE)• Monitor and control node status (NODE STATUS)• Monitor and control the work queue (WORK QUEUE)• Modify the global control parameters (CONTROL RECORD)• Add, delete or modify any DTF node parameters (DTF NODE RECORDS)• Add, delete or modify any network node configurations (NETWORK NODE RECORDS)

The Administration Primary MenuThe IBM Connect:Direct for z/OS ADMINISTRATION PRIMARY MENU is the root of the administrationmenu hierarchy and is the access key to all the other features of the IBM Connect:Direct AdministrationSystem. Following is an example of the Administration Primary Menu.

Chapter 3. CICS Administration and User Guide 99

IBM Connect:Direct for z/OS ADMINISTRATION PRIMARY MENU 10:17:29

OPTION ==> _

C ... CONFIGURATION I ... INTERFACE STATUS N ... NODE STATUS S ... SIGNON DEFAULTS U ... USER STATUS

To restrict U : CICS USERID ==> _____________ CICS TERMID ==> _____ Connect:Direct NODE ==> _________________________

Licensed Materials - property of IBMIBM Connect:Direct for z/OS(C) Copyright IBM Corp, 1982, 2011 All Rights Reserved.IBM is a Trademark of International Business Machines

PF keys: 3 Exit

Note: In order to use the Administration System, both CICS and IBM Connect:Direct must be installed andworking on your mainframe. Display the Administration Primary Menu by using the DGAA transaction.

The following table describes each option.

Option Description

C Select this option to maintain CICS Interface configuration information.

I Selecting this option takes you to the INTERFACE STATUS menu. If you need to activate ordeactivate the IBM Connect:Direct interface, select this option.

N Selecting this option takes you to the NODE STATUS menu. If you need to view the status ofnodes that users of the CICS Interface can sign on to, and information about the sessions andtasks under the node, select this option.

S Selecting this option takes you to the SIGNON DEFAULTS menu. If you need to maintain usersignon default information, select this option.

U Selecting this option takes you to the USER STATUS menu. If the you need to check on aparticular userid and the IBM Connect:Direct activities associated with that userid, or if youneed to cancel a user task or signon, select this option.

The following fields are not required under option U, but you can use them to limit the scope of thedisplay:

Field Description

CICS USERID This 8-character field contains the IBM Connect:Direct CICS signon ID.

CICS TERMID This 4-character field contains a valid terminal ID.

Connect:Direct NODE This 16-character field contains a valid IBM Connect:Direct node name.

Maintaining Configuration InformationThe CICS Interface provides a variety of configuration options to allow you to define the resources thatcan be accessed, limit the scope of functions provided to users, and optimize the performance of the

100 IBM Connect:Direct for z/OS: Documentation

system. All CICS Interface configuration information is contained in a single file (CONFIG), which isdefined and initially loaded at installation.

Configuration CategoriesThe configuration parameters are divided into the following categories:

• Control Record• DTF Node Records• Network Node Records

Control RecordThe Connect:Direct for z/OS Control Record contains information defining the operational characteristicsof the Connect:Direct for z/OS system. This information includes flags that activate or deactivate system-wide features of the CICS Interface and parameters that govern the performance of the system.

The Control Record is initially loaded during the installation process. The CICS Interface onlineadministration facilities allow you to modify the contents of this record only. Any modifications performedwhile the CICS Interface is active are immediately reflected in the execution environment.

DTF Node RecordsA CICS Interface user has the ability to access multiple IBM Connect:Direct DTFs for the purpose ofcopying files from that node to other nodes, submitting Processes, and gathering and reporting onstatistical information.

The DTF Node Records contain information identifying any node eligible to be signed on to by the CICSInterface and defining the rules governing access to that node (such as ESF access, output limits, and soforth).

Note: One DTF Node Record is required for each IBM Connect:Direct DTF to which the CICS Interface cansign on directly. The first of these records is defined and loaded at product installation.

IBM Connect:Direct DTF node information describes each DTF node available to the CICS Interface. At thestartup of the Interface, a subtask called CST (controller subtask) is attached by CICS. The CST in turnattaches other subtasks, called WSTs (worker subtasks).

WSTs establish and manage a VTAM session with a DTF, passing IBM Connect:Direct commands, andreceiving returned information. One WST communicates with only one DTF, but multiple WSTs cancommunicate with one DTF.

Network Node RecordsTo facilitate the task of copying files from one node to another, the CICS Interface provides a means ofpredefining frequently used nodes, relieving you of the need to know specific information about nodesto be accessed. Nodes defined in Network Node Records display as a numbered list in the COPY FILEBETWEEN NODES screen. You can select nodes by number and provide only that information relating tothe file to be sent or received.

Accessing the Configuration ScreenTo access the CONFIGURATION screen, select option C from the PRIMARY MENU (DGAA transaction). TheCONFIGURATION screen enables you to display and maintain the Control Record, DTF Node Records, andthe Network Node Records. Following is an example of the screen.

Chapter 3. CICS Administration and User Guide 101

CONNECT:DIRECT ADMINISTRATION 10:25:28 CONFIGURATION

OPTION ==> _

C ... CONTROL RECORD D ... DTF NODE RECORDS N ... NETWORK NODE RECORDS

PF keys: 3 Exit

The following table describes each configuration option.

Option Description

C Selecting this option, and pressing Enter takes you to the CONTROL RECORD screen.If you need to update the CONTROL RECORD with information affecting the operatingcharacteristics of the CICS Interface, select this option.

D Selecting this option, and pressing Enter takes you to the DTF NODE RECORDS screen. Ifyou need to view the characteristics of a DTF NODE, such as node name, number of workersubtasks, and entries in the work queue, select this option.

N Selecting this option, and pressing Enter takes you to the NETWORK NODE RECORDS screen.If you need to view the characteristics of a NETWORK NODE, such as node name, nodedescription, and node type, select this option.

Updating the Control RecordTo access the CONTROL RECORD UPDATE screen, select option C from the CONFIGURATION screen,and press Enter. Only one CONTROL RECORD exists for the CICS Interface system. This control recordcontains global configuration parameters. Following is an example of the screen.

CONNECT:DIRECT ADMINISTRATION 16:13:15 CONTROL RECORD UPDATE

AUTO.SIGNON ............................ Y Y OR N SIGNON.REENTRY ......................... N Y OR N CONNECT:DIRECT.EQ.CICSID ............... Y Y OR N SKIP.SIGNON.PANEL ...................... N Y OR N CICS.TRANSACTION.CODE (MONITOR) ........ DGADM CICS.TRANSACTION.CODE (STARTUP) ........ DGAI CICS.TRANSACTION.CODE (PRINT) .......... DGAP CICS.TRANSACTION.CODE (ESS) ............ DGAE CST.RETRY.INTERVAL ..................... 000500 HHMMSS SESSION.RETRY.INTERVAL ................. 0100 MMSS ESF.RETRY.INTERVAL ..................... 001500 HHMMSS WORK.RETRY.INTERVAL .................... 0015 MMSS MONITOR.INTERVAL ....................... 30 SS INACTIVE.INTERVAL ...................... 003000 HHMMSS MAX.SIGNON ............................. 0100 MAX.TASKS .............................. 02 01-99 STORAGE.SUBPOOL ........................ 127 002-127

MENU OPTIONS: CF Y SB Y SS Y SP Y SD Y SN Y MD Y Y OR N

PF keys: 3 Exit 9 Update Enter Edit Clear Reset

The entry fields are:

102 IBM Connect:Direct for z/OS: Documentation

Field Description

AUTO.SIGNON Specifies whether Connect:Direct for z/OS automaticallysigns you on if a signon defaults record is defined with aCICS userid matching the userid that you specify at CICSsignon. The signon defaults record for that CICS user mustspecify a valid IBM Connect:Direct userid, password andDTF node name. If you specify Y, auto-signon is usedif the required information is available; if you specify N,auto-signon is not used. The default is Y.

SIGNON.REENTRY Specifies whether the CICS Interface remembers that aCICS user previously signed on to the IUI. If this feature isenabled, the user is able to exit the IBM Connect:DirectCICS Interface to perform another CICS function andreenter without signing on again.

Signon reentry is not performed for a user who signs offCICS itself and then signs back on again to CICS. Signonreentry is only in effect after the first signon to the IBMConnect:Direct CICS Interface. If you specify Y, signonreentry is performed when appropriate; if you specify N,signon reentry is not performed. The default is N.

CONNECT:DIRECT.EQ.CICSID Specifies whether the CICS Interface denies a signonattempt if the IBM Connect:Direct userid does not matchthe CICS userid specified at CICS signon. If you specify Y, asignon is rejected if the IDs do not match; if you specify N,no check takes place. The default is Y.

SKIP.SIGNON.PANEL Specifies an optional CICS signon interface that does notrequire you to retype a userid and password. Validityof this approach depends upon a secure environmentexisting prior to you selecting the CICS Interface; inother words, userid and password validation by a securitysubsystem (CA-ACF2, RACF®, and so forth) upon originalsignon to the system. Enable this option by typing Y forthis parameter on the Control Record Update screen. Thecontrol record can also be set during installation by typingSKIP.SIGNON.PANEL=Y on the CONFIGURATION FILE -CONTROL PARAMETER RECORD screen. The default is N.

CICS.TRANSACTION.CODE (MONITOR) Specifies the 1-4 character transaction codes to be usedfor the CICS Interface monitor transaction. The monitortransaction scans for pending requests from users and forcompleted work by IBM Connect:Direct. If the MONITORTRANSACTION CODE is not specified during installation, itdefaults to DGAM. If you change this parameter, you mustalso change the supplied transaction definition.

CICS.TRANSACTION.CODE (STARTUP) Specifies the 1-4 character transaction codes to beused for the CICS Interface start transaction. If youuse the startup PLT to activate the CICS Interfaceat CICS initialization, this transaction is submittedto run immediately following the completion of CICSinitialization processing. If you do not specify the STARTUPTRANSACTION CODE parameter during installation, itdefaults to DGAI. If you change this parameter, you mustalso change the supplied transaction definition.

Chapter 3. CICS Administration and User Guide 103

Field Description

CICS.TRANSACTION.CODE (PRINT) Specifies the 1-4 character transaction codes to be usedfor the CICS Interface print transaction. This transactionis attached to the CICS printer in response to CICS printrequests. If the PRINTER TRANSACTION CODE parameteris not specified during installation, it defaults to DGAP.If you change this parameter, you must also change thesupplied transaction definition. Print requests are handledby writing print lines to the CICS Transient Data Area(TDA). When the data is ready for output, a transactionsends the data to the CICS printer specified in the SIGNONDEFAULTS.

CICS.TRANSACTION.CODE (ESS) Specifies the 1-4 character transaction code to be used forthe Connect:Direct for z/OS Event Services Support. If thisparameter is not specified during installation, it defaults toDGAE. If you change this parameter, you must also changethe supplied transaction definition.

CST.RETRY.INTERVAL Specifies the time interval (in hours, minutes and seconds)between attempts to restart an ABEND of CST (controllersubtask). The controller subtask is an operating systemsubtask responsible for monitoring the worker subtasksresponsible for interaction with active IBM Connect:DirectDTFs defined in DTF Node Records (that is, DTFs towhich CICS users can sign on). The default is 000500 (5minutes).

SESSION.RETRY.INTERVAL Specifies the time interval (in minutes and seconds)between attempts to establish a VTAM session with a DTFdefined in a DTF Node Record (that is, a DTF to which CICSusers can sign on directly). The default is 100 (1 minute).

ESF.RETRY.INTERVAL Defines the time interval (in hours, minutes and seconds)between attempts to establish a primary session with aIBM Connect:Direct DTF when, during a prior attempt, theDTF is not active and the node is activated in ESF mode.A node is activated in ESF mode only if the DTF it definessupports ESF. The default is 001500 (15 minutes).

WORK.RETRY.INTERVAL Specifies the time interval (in minutes and seconds)between the time a unit of work is submitted but cannotbe placed in the work queue for a particular node and thetime that unit of work is cancelled. The size of the workqueue for a particular node is governed by the ENTRIESIN WORK QUEUE parameter in the DTF Node Record. Thedefault is 0015 (15 seconds).

MONITOR.INTERVAL Contains the time interval, expressed as seconds, betweenscans for work by the monitor transaction. This parameteris a 2-character field. The monitor watches all Processes,queues, tasks, and task lengths, and regulates the flow oftasks in the system to ensure that any particular task doesnot seize the computer resources. When all Processes andtasks are completed or pending action by the DTF, themonitor waits for the specified interval before rescanningthe work queue. The default is 30 (seconds).

104 IBM Connect:Direct for z/OS: Documentation

Field Description

INACTIVE.INTERVAL Specifies the amount of time (in hours, minutes andseconds) that a worker subtask (WST) is allowed to beinactive before it is detached by the controller subtask(CST). The default is 003000 (30 minutes).

MAX.SIGNON Contains the maximum number of CICS users and reflectsthe relative size of the signon table file. This parameter is a4-character field. The default is 100 entries.

MAX.TASKS Contains the maximum number of simultaneous subtasksthat can be attached in the CICS address space. Thisparameter is a 2-character field. Specify this field asthe total of the worker subtask counts for all DTF NodeRecords defined to the CICS Interface. The default is 2.

STORAGE.SUBPOOL Contains the number of the operating system storagesubpool from which the CICS Interface acquires operatingsystem storage. This parameter is a 3-character field.Numbers 002-127 are user-defined (numbers 000, 001,128-255 are system-defined) areas of storage related toeach other usually by the requirements of your session.DTF keeps track of all storage for a given user Process andtask. The default is subpool 127.

Menu OptionsThe following options contain a Y or N which enables or disables the options on the PRIMARY MENU ofthe general user. You can use these Y/N flags to determine the level of functionality to be provided by IBMConnect:Direct.

These options affect all users of Connect:Direct for z/OS. If you want to limit the functionality availableto specific users, you must use either the authorization functions of IBM Connect:Direct (select only theappropriate options when defining that user in the IBM Connect:Direct Authorization File) or the IBMConnect:Direct Security exit (set an Authorization Bit Mask to allow or restrict the appropriate options).

Option Description

CF Contains the toggle to turn off the COPY FILE option on the PRIMARY MENU. The field isone character long; Y permits you to copy files; N denies permission.

SB Contains the toggle to turn off the SUBMIT PROCESS option on the PRIMARY MENU. Thefield is one character long; Y permits you to submit Processes; N denies permission.

SS Contains the toggle to turn off the SELECT STATISTICS option on the PRIMARY MENU. Thefield is one character long; Y permits you to select statistics; N denies permission.

SP Toggle to turn off the SELECT PROCESS option on the PRIMARY MENU. The field is onecharacter long; Y permits you to select Processes; N denies permission.

SD Contains the toggle to turn off the SIGNON DEFAULTS option on the PRIMARY MENU. Thefield is one character long with a Y or N; Y grants permission to change default signonoptions; N denies permission.

SN Contains the toggle to turn off the CHANGE SIGNON option on the PRIMARY MENU. Thefield is one character long with a Y or N; Y grants permission; N does not.

MD Contains the toggle to turn off the MESSAGE DISPLAY option on the PRIMARY MENU. Thefield is one character long with a Y or N; Y grants permission to use this option; N does not.

Chapter 3. CICS Administration and User Guide 105

Updating DTF Node RecordsThe DTF NODE RECORDS screen is accessed by selecting option C on the PRIMARY MENU, then byselecting option D on the CONFIGURATION screen, and pressing Enter. One DTF node record exists foreach DTF node which IBM Connect:Direct users can sign on to directly. Following is an example of thescreen.

Note: Changes made to the DTF node record parameters are immediately reflected in the active system.

CONNECT:DIRECT ADMINISTRATION 16:17:53 DTF NODE RECORDS

DTF NODE NAME ________________NETMAP DDNAME ________DUMMY ID FOR DTF SIGNON ________SUPPRESS CONNECTION AT STARTUP _ Y OR NESF SIGNON ALLOWED _ Y OR NMAXIMUM WORKER SUBTASKS __ENTRIES IN WORK QUEUE ___OUTPUT RECORD LIMIT _____SLOW RESPONSE NOTIFICATION ____ MMSS

PF keys: 3 Exit 5 Add 6 Delete 7 Prev 8 Next 9 Update Enter Read/Edit Clear Reset

The following table describes the Entry fields:

Field Description

DTF NODE NAME Contains the name of a DTF node. This is a 16-characterfield.

NETMAP DDNAME Specifies the DDNAME of the IBM Connect:Direct networkmap file to be used when initiating a signon to this node.The network map must have an adjacent node definitionfor this node, but need not be exactly the same networkmap file the node is using. You must code this value; nodefault is available.

The NETMAP DDNAME is defined to CICS using RDO and isthe FILENAME used by CICS. You must have one networkmap file for each node and you must have the DTF noderecord for each node you want to sign on to.

DUMMY ID FOR DTF SIGNON Specifies the IBM Connect:Direct userid to be used toinitially establish the VTAM session with the DTF. MultipleCICS userids are required if a DTF can have multipleCICS Interface systems signed on concurrently. If youare using the DGASECUR macro to define your IBMConnect:Direct security exit, this parameter must matchthe CICS parameter coded for that macro. You must codethis value; no default is available.

SUPPRESS CONNECTION AT STARTUP Contains the toggle for startup connections. Thisis a 1-character field. If the field contains Y, theconnection between the specified DTF node and theIBM Connect:Direct system is suppressed when the IBMConnect:Direct software is started. If the field contains N,then the connection is made. The default is Y.

106 IBM Connect:Direct for z/OS: Documentation

Field Description

ESF SIGNON ALLOWED Specifies whether the Extended Submit Facility is to besupported for this node by IBM Connect:Direct. The DTFidentified in this record must support ESF in order to signon in ESF mode using IBM Connect:Direct. The default isN.

MAXIMUM WORKER SUBTASKS Specifies the maximum number of WSTs (worker subtasks)to be used for this node. Define one WST per parallelsession defined for this node. Do not exceed the MAXTASKS value in the Control Record with the total numberof worker subtasks defined for all DTF NODE records in thesystem. The default is 2.

ENTRIES IN WORK QUEUE Specifies the maximum number of actual requests to beallowed on the pending work queue for this node. Anexcessive value here could result in an inordinate responsetime for terminal users. During installation, the default isthe MAXIMUM WORKER SUBTASKS specification.

OUTPUT RECORD LIMIT Specifies the upper limit on the number of lines of outputthat are accepted in response to a SELECT PROCESSor SELECT STATISTICS command. Output from thesecommands is stored in CICS temporary storage untilviewed or explicitly deleted. The default is a limit of 80080-byte records.

SLOW RESPONSE NOTIFICATION Contains the time interval, expressed as minutes andseconds, after which IBM Connect:Direct notifies youof potential problems with slow response. This is a 4-character field. The default is 0200 (2 minutes).

Updating Network Node RecordsTo access the Connect:Direct ADMINISTRATION NETWORK NODE RECORDS screen, select option C fromthe PRIMARY MENU, select option N from the CONFIGURATION screen, and press Enter. The screen fieldsare scrollable, and allow you to view the contents of the network node records. Following is an example ofthe screen.

CONNECT:DIRECT ADMINISTRATION 16:02:23 NETWORK NODE RECORDS

NETWORK NODE NAME ________________

NETWORK NODE DESCRIPTION ______________________________

NODE TYPE __ 1=OS/390 2=VM 3=VSE 4=VMS 5=TANDEM 6=WIN95 7=OS/2 8=OS/400 9=UNIX 10=NETWARE 11=WINDOWS 12=MSP 13=MVS

PF keys: 3 Exit 5 Add 6 Delete 7 Prev 8 Next 9 Update Enter Read/Edit Clear Reset

Because you can type the node name and environment on the COPY FILE BETWEEN NODES screen, it isnot required that you define every node participating in a COPYFILE on the NETWORK NODE RECORDSscreen.

Chapter 3. CICS Administration and User Guide 107

Note: Changes made to the Network Node Record parameters are immediately reflected in the activesystem.

The following table describes the entry fields.

Field Description

NETWORK NODENAME

(16-character field) contains the name of the node.

NETWORK NODEDESCRIPTION

(30-character field) contains a description of the node.

NODE TYPE (1-character field) contains the environment number. Valid environment numbersare as follows:

1 for OS/390®

2 for VM3 for VSE4 for VMS5 for TANDEM6 for WIN957 for OS/28 for OS/400®

9 for UNIX10 for NETWARE11 for WINDOWS13 for MVS™

Working with the Administration InterfaceTo access the IBM Connect:Direct ADMINISTRATION INTERFACE screen, select option I from thePRIMARY MENU and press Enter.

IBM CONNECT:DIRECT ADMINISTRATION 10:30:37 INTERFACE

OPTION ==> CONNECT:DIRECT VER VV REL RR MOD MM

A ... ACTIVATE INTERFACE M ... START MONITOR I ... SHUTDOWN INTERFACE (IMMEDIATE) S ... SHUTDOWN INTERFACE (NORMAL)

INTERFACE STATUS ACTIVE PENDING REQUEST NONE MONITOR TASK NUMBER 25 ACTIVE TASKS 0

PF keys: 3 Exit ENTER Refresh/Process

The INTERFACE screen is the key to activating, monitoring, and shutting down the CICS Interfacebetween CICS and the active IBM Connect:Direct DTF nodes. From the INTERFACE screen, you canmanually initialize and terminate the operating system subtasks that perform the interaction with IBMConnect:Direct.

The following table describes each option for the INTERFACE screen.

108 IBM Connect:Direct for z/OS: Documentation

Options Description

A Selecting this option, and pressing Enter activates the interface and automatically starts themonitor transaction.

M Selecting this option, and pressing Enter starts the monitor transaction. Only use this optionin the event of a monitor transaction ABEND.

I Selecting this option, and pressing Enter performs an immediate (hard) shutdown of theinterface. All IBM Connect:Direct user sessions are terminated, regardless of status.

S Selecting this option, and pressing Enter, performs a normal (soft) shutdown of the interface.All IBM Connect:Direct user sessions are allowed to complete execution.

The following table describes the system fields:

Field Description

VER (2-character field) contains the version number of the CICS Interface software.

REL (2-character field) contains the release number of the CICS Interface software.

MOD (2-character field) contains the modification number of the CICS Interfacesoftware.

INTERFACESTATUS

(21-character field) contains ACTIVE or INACTIVE, depending upon the state ofthe interface. The field contains ACTIVE if the interface is active and changes toINACTIVE if the interface is deactivated.

PENDINGREQUEST

(18-character field) contains either NONE, if no activate or shutdown request ispending, or the type of request being processed.

MONITOR TASKNUMBER

(11-character field) contains the number of the monitor transaction or a messagesuch as NOT RUNNING, if the interface is not active.

ACTIVE TASKS (2-character field) contains the number of the active tasks.

Operating the CICS InterfaceIn order for the CICS user interface to perform its function, a connection must exist between it and aIBM Connect:Direct DTF. This facility can be local (within the same VTAM domain) or remote (residing inanother domain).

This connection is accomplished using operating system subtasks that are attached in the CICS addressspace at the CICS Interface startup. The subtasks perform two types of functions:

One or more Worker Subtasks (WSTs) are attached for each active link to a IBM Connect:Direct DTF. Thesesubtasks are responsible for establishing a link to the DTF, passing commands to it, and receiving anyresults.

A single Controller Subtask (CST) is created to monitor the work of all WSTs in the system and performcommunications functions with the user interface portion of CICS.

Initialization of the CICS Interface invokes programs that perform the following functions:

• Acquires CICS Interface work areas, such as the signon table and work queue areas• Enables a task control global exit point and its associated global work area• Reads the configuration information from the configuration file and places that information in the global

work area• Attaches the CST subtask• Checks for any DTF nodes that are to be activated at initialization and passes information to the CST

task to allow it to create the appropriate WSTs and establish the link with the DTF.

Chapter 3. CICS Administration and User Guide 109

Note: The CICS Interface module is also available for the interface autostart at CICS startup. When themodule is in the PLTPI, you can start CICS without starting the interface by including a special DD cardin the CICS startup JCL deck: //NDMINIT DD DUMMY. If present, NDMINIT will not start the interface aspart of CICS initialization. The interface can then be started manually.

Monitor TransactionIn addition to these operating system subtasks, a CICS monitor transaction is created to accept inputfrom the user interface, pass it to the CST, and route the output to the appropriate user. This transaction isalso responsible for detecting a loss of the CST subtask due to an error condition and performing a restart.The monitor transaction is activated at the CICS Interface startup and remains in the system for the life ofthe online region. Monitor activities include the following:

• Restarting the interface in case of an ABEND• Watching for DTF requests which are taking too long• Forcing retry of requests still in the queue• Forcing retry of DTF node session establishment• Attempting to switch from ESF to primary (DTF connected) mode• Clearing non-terminal signon table entries, at end of transaction• Clearing signon table entries in case of ABENDs

Interface TasksAlthough CICS runs a number of subtasks (such as journaling and VSAM handling), CICS can be regardedas a single task. All CICS transactions that can generate IBM Connect:Direct requests run from this singleCICS task. The CICS Interface runs as a set of separate tasks in the CICS address space. At the startup ofthe CICS Interface, a subtask called CST (controller subtask) is attached by CICS.

Interface StartupThis isolates CICS from all the non-CICS work involved in communicating to the IBM Connect:Direct DTFthrough the IBM Connect:Direct API. A CICS Interface monitor transaction is also invoked as part ofinterface startup to support and monitor interface operation.

The CST in turn attaches other subtasks, called WSTs (worker subtasks), organized by node. The WSTsestablish and manage the DTF sessions, passing IBM Connect:Direct commands, and receiving returnedinformation. The CST controls traffic between all CICS Interface transactions and each WST.

Interface Subtask ManagementEach WST handles requests for CICS users through the CST. One WST communicates with only one DTF,but multiple WSTs can communicate with one DTF. The DTF-connected WSTs are not associated with anyparticular CICS transactions. The various IBM Connect:Direct requests generated by CICS Interface usersare handled by any of the multiple WSTs which are for a particular DTF node. The CST oversees all theWSTs, and is responsible for coordinating work generated by CICS transactions.

One WST is attached per node at the CICS Interface startup, as defined in the CONFIGURATION file.Additional WSTs for a node are attached as needed, based on concurrent CICS Interface user demand.The maximum number of WSTs (tasks) attached globally for the interface and per DTF node is definedwith CONFIGURATION control and DTF node parameters. The DTF node connection limit is edited to beno larger than the number of CICS interactive applications specified in the Network Map for that node.

When an attached WST becomes inactive (is not used for any requests) for a period of time, it is detachedby CST. The inactive interval is defined with a CONFIGURATION control option. You can suppress WSTactivation by DTF node with a CONFIGURATION DTF node parameter.

110 IBM Connect:Direct for z/OS: Documentation

Interface Request ManagementCICS user requests are placed on a work queue with one queue per node. The one or more WSTsattached per node dispatch work from the queue. Maximum queue length by node is defined with aCONFIGURATION DTF node parameter which defines the number of queue entries.

When WST (session limit) is reached and additional WSTs cannot be attached to dispatch work from thequeue, requests remain on the work queue until a WST becomes available. When the number of allowedWSTs for a given node is held to a minimum, yet user activity for the given node is high, increase thenumber of queue entries.

Work queue size is also affected by the CONFIGURATION control option worker retry interval whichdefines the time elapsed between attempts to obtain a free WST to dispatch work present on the workqueue. IBM Connect:Direct user requests are rejected with a DTF busy message, when a DTF node queuereaches its maximum allowed number of entries.

The CONFIGURATION DTF node parameter defines worry time. A message is written to the log whena request to that node takes longer than the specified amount of time. No action is taken by the CICSInterface to automatically abort any requests which take too long.

The CICS Interface also has one system queue for system commands (for example, SHUTDOWN andQUIESCE) to dispatch system requests. You cannot adjust the system queue size.

Interface VTAM SessionIn cases where a WST/DTF VTAM session is active, but becomes inactive, the CICS Interface quiesces thenode. Pending requests are allowed to complete, even though they can fail. The number of WSTs for thenode is reduced to one.

At this point, if the WST is in session with a local DTF, and ESF mode is allowed, the WST switches to ESFmode. An ESF MODE message is displayed to IUI users, stating that a IBM Connect:Direct session erroroccurred, but ESF MODE is available. Under ESF operation, only the SUBMIT options are displayed on thePRIMARY MENU.

ESF mode operation is enabled for the entire interface through a CONFIGURATION control parameter;ESF mode operation is enabled for each user through a user profile parameter. When a WST fails toestablish or drops a DTF session, and ESF is not allowed, then the WST remains attached, but all userrequests for the node are rejected.

The WST periodically tries to establish or re-establish (retry) a session with the associated DTF. TheCONFIGURATION control parameter session retry interval defines the time lapsed between retries forsession connection. An additional CONFIGURATION control parameter, the ESF session retry interval,defines the time elapsed between retries of a dummy DTF session to check if ESF mode has returned toprimary mode.

Viewing Node StatusThe Node Status screen enables you to check the status of all DTF nodes eligible for access by the CICSInterface, and you can selectively activate, deactivate, and view pending work for all DTF nodes. The CICSuser interface provides the ability to log on to any IBM Connect:Direct DTF in your network and performIBM Connect:Direct operations using that node as your Process primary node. DTFs to be accessed mustbe identified in DTF Node Records in the configuration file along with the configuration parameters to beused when communicating with that node.

To scroll backward and forward, through the list of DTF nodes connected to the Connect:Direct for z/OSsession, press PF7 and PF8, respectively.

1. To access the CONNECT:DIRECT ADMINISTRATION NODE STATUS screen, select option N from theADMINISTRATION PRIMARY MENU and press Enter.

Following is an example of the Node Status screen.

Chapter 3. CICS Administration and User Guide 111

CONNECT:DIRECT ADMINISTRATION 10:30:37 NODE STATUS

CICS ADMIN SESS SESSION DATE/TIME MAX CURR CURR DTF NODE NAME STATUS REQUEST TYPE OR SESSION MSGID TASKS TASKS WORK ------------- ------ ------- ---- ----------------- ----- ----- ----_ NODE1 INACT NONE 3 0 0_ NODE2 ACTIVE PRIM 06/19/1998 09:57:18 2 1 0

Line commands: A Activate (start first task) I Shut immediate W Work queue display S Shut normal

PF keys: 3 Exit ENTER Refresh/Line cmd

The following table describes the fields on the NODE STATUS screen:

Field Description

DTF NODE NAME (16-character field) contains the DTF node name as typed in the DTF NodeRecord.

CICS STATUS (6-character field) contains the status of the node, such as ACTIVE and INACT.

ACTIVE - The node is activated, either by the CICS Interface initialization ormanually.

INACT - The node is not active.

ADMIN REQUEST This 8-character field contains the type of administrative request affecting thestatus of the node, such as ACTIVATE, SHUTIMM, or SHUTNORM.

ACTIVATE - The node is activated.

SHUTNORM - A normal shutdown of the node is requested, and the node isquiescing.

SHUTIMM - An immediate shutdown of the node is requested, and the link withthat DTF is being terminated.

SESS TYPE This 4-character field contains the type of session held with this DTF node, asfollows:

NONE - No session currently exists with this DTF node.

PRIM - The CICS Interface is currently in session with the DTF node.

ESF - The DTF is not active, but supports the Extended Submit Facility. The CICSInterface is accepting requests allowed in ESF mode.

SESSION DATE/TIME

This 17-character field contains either the date and time that the connection tothis DTF is activated, or the MSGID of the last message issued for this DTF nodeduring activation or deactivation.

MAX TASKS This 5-character field contains the maximum number of subtasks that areattached to Process requests directed at this node.

CURR TASKS This 5-character field contains the current number of subtasks attached toProcess requests directed at this node.

CURR WORK This 5-character field contains the number of subtasks currently processingrequests directed at this node.

2. Take one of the following actions in the line command column to the left of the DTF node name:

• To activate the node, type A and press Enter.• To access the WORK QUEUE screen for a node where work is being processed, type W and press

Enter.

112 IBM Connect:Direct for z/OS: Documentation

• To perform an immediate (hard) shutdown of the node to force all Processes to stop, regardless ofstatus, type I and press Enter.

• To perform a normal (soft) shutdown of the node to allow all Processes to complete execution, type Sand press Enter.

Viewing the Work Queue ScreenThe IBM Connect:Direct Work Queue is defined for each node to dispatch IBM Connect:Direct requestsand responses. The DTF node configuration file contains information required by the CICS Interface tomanage the DTF VTAM or ESF sessions. Each WST uses the standard IBM Connect:Direct API to managethe DTF or ESF session.

To access the WORK QUEUE screen for a node where work is being processed, type W and press Enter.

The WORK QUEUE screen fields contain the data describing the tasks in the work queue for each CICSuser on a IBM Connect:Direct DTF node. Following is an example of the screen.

CONNECT:DIRECT ADMINISTRATION 10:30:37 WORK QUEUE - NODE "nodename" Page 01 of 01

CICS LAST CURR REQUEST WORKCICS ID USERID TERM TASK# CMD DATE/TIME TD CTR TASK------- -------- ---- ----- --- ----------------- ------ ----ID1 ID1 M064 00271 SB 06/21/1998 11:47:13 00282 0346

PF keys: 3 Exit 7 Bwd 8 Fwd 12 Node USER STATUS ENTER Refresh

Scroll backward using PF7 and forward using PF8 to view the entries. Press PF12 to view to the USERSTATUS screen, and then press PF3 to get back to the WORK QUEUE screen.

The system fields are as follows:

Field Description

NODE (16-character field) contains the node name associated with the work queue data.

Page XX of YY (13-character field) contains the number of the current page for the work queuelist.

CICS ID (8-character field) contains the CICS userid of the user submitting the work.

USERID (8-character field) contains the CICS userid of the user submitting the work.

CICS TERM (4-character field) contains the terminal ID from which the work is submitted.

LAST TASK# (5-character field) contains the transaction number of the task submitting thisrequest.

CURR CMD (2-character field) contains the representation of the current command executedby the task (for example, CF, SB, SS).

REQUEST DATE/TIME

(17-character field) contains the date and time the work is submitted.

TD CTR (5-character field) contains the number of bytes (counted by the transient datacounter) indicating how much data is written by the exit module for a transaction.

WORK TASK (4-character field) contains the number of the work task.

Chapter 3. CICS Administration and User Guide 113

Signon DefaultsIBM Connect:Direct enables you to set default CICS signon information. This information is not requiredbut it can make IBM Connect:Direct easier to use.

The system automatically uses a CICS userid to read the profile dataset when a transaction is entered. Ifit finds a profile record, IBM Connect:Direct uses the record's information to control what the user can do.

If the user's signon defaults record includes a userid and password, IBM Connect:Direct automaticallysigns on the user. If the signon defaults record does not include a userid and password, IBMConnect:Direct prompts the user for a userid and password before allowing access.

After accessing IBM Connect:Direct, you can change your own signon defaults using the SD function.

Accessing the Signon Defaults ScreenTo access the Connect:Direct Administration Signon Defaults screen, type S and press Enter on theAdministration Primary Menu . The screen is shown in the following figure.

CONNECT:DIRECT ADMINISTRATION 14:59:46 SIGNON DEFAULTS

CICS USERID ==> ________

**Connect:Direct** USERID ==> ________________________________________________________________ PASSWORD==>

DEFAULT NODE ==> ________________ ESF MODE ALLOWED ==> _ Y OR N UPPER CASE PRINT ==> _ Y OR N CICS PRINTER ==> ____ PNODE ACCT DATA ==> _______________________________________________ SNODE ACCT DATA ==> _______________________________________________

Do you want all commands for this session to be CASE sensitive? ==> NO_

PF keys: 3 Exit 5 Add 6 Delete 7 Prev 8 Next 9 Update Enter Read/Edit Clear Reset

The following table describes the entry fields.

Field Description

CICS USERID (8-character field) is the acceptable userid for the CICS signon.

USERID (64-character field) is the acceptable userid for the IBM Connect:Direct signon.

PASSWORD (64-character field) is the valid password associated with the IBM Connect:Directuserid.

DEFAULT NODE (16-character field) is the name of the default IBM Connect:Direct node. The useris automatically signed on to this node if it is active, or is denied access if it is notactive.

ESF MODEALLOWED

(1-character field) is the permission for use of the ESF. If the field contains Y,permission is allowed. If the field contains N, permission is denied.

UPPER CASEPRINT

(1-character field) is the switch for upper case printing. If the field contains Y, allprinted output is upper case. If the field contains N, the printed output is upper andlower case.

CICS PRINTER (4-character field) is the designation for the CICS printer used for print requestsfrom this user.

PNODE ACCTDATA

(50-character field) is the primary node accounting data for allocation of budget toCPU time, I/O, and other computer resources.

114 IBM Connect:Direct for z/OS: Documentation

Field Description

SNODE ACCT DATA (50-character field) is the secondary node accounting data for allocation of budgetto users for CPU, I/O, and computer resource time.

The following table describes the system field.

Field Description

PASSWORDMESSAGE

(44-character field) indicates whether the user's signon defaults record has apassword. This field is displayed to the right of the PASSWORD field.

Viewing User StatusPeriodically view the status of a user to determine:

• User access to a resource• Actions users are performing while using a resource• Resolve problems encountered by users

IBM Connect:Direct provides the user status function for you to view information about users of thesystem and, if necessary, intervene to resolve error situations. You can either view all users of thesystem, a single user (optionally qualified by CICS userid or terminal ID) or a group of users (optionallyqualified by IBM Connect:Direct DTF node).

You have the option, while on the PRIMARY MENU screen, to restrict the scope of the status display.Restrict the scope by specifying the CICS userid, terminal ID and IBM Connect:Direct node that you wantto display on the USER STATUS screen. To see all signed-on users, do not restrict your selection.

1. To access the CONNECT:DIRECT ADMINISTRATION USER STATUS screen, type U and press Enter onthe PRIMARY MENU,.

Following is an example of the USER STATUS screen.

CONNECT:DIRECT ADMINISTRATION 10:30:37 USER STATUS

CICS SESS LAST CICS ID TERM TYPE USERID DTF NODE NAME STATUS TASK # MSGID ------- ---- ---- ------ ------------- ------ ------ -----_ MASTER M064 PRIM ID1 "dtfnodename" CICS 45 SAFA000I

Line commands: F Free user C Free user and cancel user's subtask T Free user and terminate user's signon

PF keys: 3 Exit 10 Left 11 Right ENTER Refresh/Process

2. Take one of the following actions in the underscore field to the left of the CICS userid when a usersecurity violation or resource allocation is abused:

• To free a user from use of the CICS Interface system, type F and press Enter.• To free a user from use of the CICS Interface system and cancel that user's subtask, type F and press

Enter.• To free a user from use of the CICS Interface system and and terminate that user's signon, type T

and press Enter.

The following table describes the systems fields:

Chapter 3. CICS Administration and User Guide 115

Field Description

CICS ID (8-character field) contains the CICS userid of all currently signed-on users.

CICS TERM (4-character field) contains the CICS terminal ID of all currently signed-on users.

SESS TYPE (4-character field) contains the session type (PRIM or NONE).

USERID (8-character field) contains the IBM Connect:Direct userid of all currently signed-on users.

DTF NODE NAME (16-character field) contains the DTF node name the user is signed on to.

STATUS (7-character field) contains the STATUS of a user.

LAST TASK # contains the last task number of a user Process.

MSGID contains the message ID of the last message for a given user.

3. To see the following additional system fields, press PF11 to scroll right on the screen.

Field Description

TD CTR (5-character field) contains the number of bytes (counted by the transient datacounter) indicating how much data is written by the exit module for a transaction.

LAST SIGNON contains the time of the last signon.

LAST REQUEST contains the time of the last request.

Operational Considerations

Signing On to Multiple DTFs from a Single IUIUse the Connect:Direct for z/OS IUI to sign on to multiple IBM Connect:Direct DTFs on either local orremote processors. To take advantage of this facility, consider the following:

• Provide VTAM access to the DTF you want to sign on to. For local DTFs (within the control of the sameVTAM subsystem), you must provide IUI APPLIDs that may be used by ISPF or CICS IUI facilities. If theDTF facilities are located on remote processors, you must define the IUI APPLIDs for those DTFs to thelocal VTAM subsystem as cross-domain resources.

• For each DTF you want to access through the CICS IUI, you must define a DTF Node Record for thatfacility in your CICS configuration file. You can define the DTF Node Record by using the configurationupdate facilities of the DGAA transaction.

Note:

All DTF nodes do not have to use the same Network Map file; for instance, if you want to communicatewith two DTFs with different Network Map contents, you can specify an alternate Network Map in theCICS JCL (or using the RDO) and in the DTF node record in order to communicate with the second DTF,as long as that DTF is defined as an adjacent node in the Network Map.

• The DTF node record in your configuration file must include the DD name of a Network Map file in orderto communicate with the remote IBM Connect:Direct DTF. This Network map must have the remote DTFdefined as an adjacent node.

• All Processes to be submitted to a remote DTF facility must reside in the Process library (DD nameDMPUBLIB) defined for your CICS system.

Signing On to a Single DTF from Multiple IUI FacilitiesNot only can you sign on to multiple DTF facilities from a single CICS IUI, but you can also sign on to a DTFfrom multiple CICS IUI systems. To sign on to a DTF from multiple CICS IUI systems, note the following:

116 IBM Connect:Direct for z/OS: Documentation

• If you are using the DGASECUR macro to generate your DTF security exit and provide a value for theCICSID keyword at exit generation, all CICS systems accessing that DTF must specify the same CICSIDin their signon requests as specified in the CICSID keyword. The password for the CICS signon to a DTFis always CICSIUI.

– If the CICSID keyword is not specified in the DGASECUR macro, no checking of CICSIDs for CICSsignon requests are performed in the signon exit; however, the CICSID value with a password ofCICSIUI are passed to your security facility (if available) or to the IBM Connect:Direct AuthorizationFacility for validation. The CICSID to be used when signing on to a particular DTF is specified in theCICS DTF NODE configuration record for that DTF.

– The CICSID equals the userid that is specified on the DTF NODE RECORDS SCREEN. If you let CICSIDdefault at installation time, the value is CICSUSER. For example, CICSID=CICSUSER.

– Reassemble the supplied security exit for the value to take effect.• If you do not want to use the DGASECUR macro to generate your DTF security exit, you can recognize

the Connect:Direct for z/OS dummy signon by checking the password, which is always CICSIUI. When adummy signon is received from Connect:Direct for z/OS, your security exit returns an Authorization BitMask (ABM) of binary zeros.

• To implement the CICS IUI on a base IBM Connect:Direct that has Stage 2 security turned on, modifythe supplied security exit. The exit to be modified depends on which security product is running on thesystem.

Performing an Immediate or Uncontrolled ShutdownThe CICS IUI facility provides two facilities for orderly termination of the interface, as follows:

• Termination is performed automatically by the CICS monitor transaction upon detection of a normaltermination of CICS (through a CEMT PERFORM SHUTDOWN command) when the PLTSD in usespecifies the Connect:Direct for CICS shutdown program.

• You can terminate the interface manually by using the DGAA transaction.

If you perform an immediate CICS shutdown (through the CEMT PERFORM SHUTDOWN IMMEDIATEcommand) or if CICS terminates abnormally, you may receive system A03 ABENDs from the z/OSinterface. The ABENDs are generated as a result of region termination without detaching all theoperating system subtasks created by the CICS IUI facility.

In order to avoid the additional ABENDs, you must terminate the CICS IUI facility manually, through theDGAA transaction, before you issue the CEMT PERFORM SHUTDOWN IMMEDIATE command.

Restarting Task ABENDSAdministrative options exist to either quiesce (allowing pending requests to complete) or immediatelyshut down a specific node or the entire CICS Interface. After the shutdown has completed, anotheradministrative option enables you to restart the CICS Interface.

In case the entire CICS Interface ABENDs, CICS is notified. The abnormal termination is recorded inthe CICS CWA. When the CICS Interface monitor transaction detects that the interface failed, tries toautomatically restart the interface. Users with requests to the interface when it crashed are freed by theCICS Interface monitor and the users are sent a message explaining the problem.

If a WST ABENDs, then the CST is notified. If any request from a CICS user is pending, CST fills in thereturn code and message for the user, informing the user that the command might have failed. If thefailing WST is the only one running for a node, CST attempts to reattach the WST.

Accessing Accounting and Logging InformationIBM Connect:Direct accounting is accomplished by the DTF. Accounting and statistics are gatheredaccurately as the DTF enables the userid to be extracted from the UICB for each IBM Connect:Directcommand entered.

Chapter 3. CICS Administration and User Guide 117

CICS logging is accomplished in the background of CICS operations, but does not record all CICS eventsand does not duplicate any other IBM Connect:Direct logs. Some events also display on the systemconsole, where major CICS events and errors are reported, such as the following:

• Interface startup• CST attach• WST attach• Node signon of dummy CICS ID• WST session failure• WST detach• CST detach• CST termination• Administrative commands affecting sessions and requests• Return information for CICS users who issue a request and then abnormally exit CICS without waiting

for the response

Using the Extended Submit Facility (ESF)ESF mode is invoked when an active IBM Connect:Direct DTF session fails or when session establishmentfails. In order for Connect:Direct for z/OS to activate ESF, you must install the ESF option on the local DTFand you must enable the option in the configuration file.

The user must also include the parameter ESF=YES in the SIGNON command. In ESF mode, a node isavailable for use only for SUBMIT commands which the user writes directly to the local DTF TCQ file. ESFSUBMIT requests can be issued only by those users who specify ESF as a profile (signon defaults) option.

Specifying IBM Connect:Direct Signon ParametersFour parameters in the IBM Connect:Direct SIGNON command explicitly support the CICS IUI as follows:

Parameter Description

TYPE=CICS Enables a SIGNON command to be embedded in the middle of anAPI session. This parameter serves no other function and is invalidfor a normal signon.

TDEXIT=modname Enables specification of the exit to receive control for temporarydata set I/O. This parameter is mutually exclusive with the TMPDD,TMPDSN, UNIT, and VOLSER parameters. This exit is called forOPENs, CLOSEs, and WRITEs to the temporary data set.

TDLIMIT=nnnnn Restricts the number of IBM Connect:Direct statistics. Data isreturned from the DTF for the IUI Select Statistics (SS) function. TheIBM Connect:Direct API SIGNON (used by CICS WSTs to connect toa IBM Connect:Direct DTF) includes a LIMIT= PARAMETER RECORDSreturned by the DTF. The DTF truncates data sent to the IBMConnect:Direct WST API and appends a final record indicating thatexcessive output is truncated.

NETDD=ddname Enables a SIGNON command to specify the DDNAME of a IBMConnect:Direct Netmap data set which is already allocated.

118 IBM Connect:Direct for z/OS: Documentation

About IBM Connect:Direct CICS DataThis section lists files and other data used by IBM Connect:Direct DTF and CICS.

IBM Connect:Direct DTF and CICS DataThe following data, accessed in read-only mode under CICS, is used by IBM Connect:Direct DTF and theCICS Interface:

Data Description

NETMAP

(DDN=NETFINP)

At least one netmap file exists for each CICS region. The file isdefined as a CICS file. It is updated in batch and contains all IBMConnect:Direct nodes available to this CICS environment. Some ofthe information for the network IBM Connect:Direct nodes is alsocontained in the Configuration File along with additional fields thatyou can update.

PROCESS

(DDN=DMPUBLIB)

One DD name exists for each CICS region. Several files can beconcatenated. It is not defined as a CICS file. It is allocated by CICSand used at the subtask level by the IBM Connect:Direct API only. Ifnecessary, you can dynamically allocate and deallocate it using CICStransaction DGAN.

MESSAGE

(DDN=NDMMSG)

One file exists for each system. It is defined as a CICS file and isallocated and opened by CICS. It is updated in batch using the IBMConnect:Direct message load utility.

TCQ One Transmission Control Queue (TCQ) file exists for each IBMConnect:Direct node. It is not defined as a CICS file. It holds submit(ESF) requests when IBM Connect:Direct DTF is down. It is used atthe subtask level by the IBM Connect:Direct API only. It is allocatedby CICS and opened by a subtask. If necessary, you can dynamicallyallocate and deallocate it using the CICS transaction DGAN.

RPLERRCK

(DDNAME)

It is not defined as a CICS file nor is it in the RDO. It contains VTAMerrors written to a sequential file by the IBM Connect:Direct interfaceand is defined as SYSOUT.

EVENT RESTART

(DDN=NDMEVNT)

One file exists for each CICS region. It is defined as a CICS file, andis allocated and opened by CICS. It is updated by the Event ServicesSupport, and is used for restarting ESS.

Trace Files Several files within the IBM Connect:Direct API are dedicated tosystem trace functions, but are not explicitly used by the CICSInterface. The IBM Connect:Direct API design enables trace data tobe written when they are available. To capture trace data, add theappropriate DD name statements to the CICS startup JCL. The filesmust be present at CICS initialization.

Note: Do not dynamically allocate trace files after CICS initializes.Each IBM Connect:Direct API (one per WST) writes trace data tothese files when present. An example is NDMCMDS, which you canuse to view all commands submitted to the API.

IBM Connect:Direct CICS Data SetsThe following data sets, used only by Connect:Direct for z/OS, are for the CICS Interface environment andare updated under CICS:

Chapter 3. CICS Administration and User Guide 119

Data Set Description

CONFIGURATION One file exists for each CICS region. It is defined as a CICS file.You can update it online through administrator functions. It is aVSAM KSDS file. It contains all IBM Connect:Direct nodes availableto this Connect:Direct for z/OS environment as does NETMAP, butCONFIGURATION contains system parameters that control the IBMConnect:Direct CICS API environment.

USER PROFILE (SIGNONDEFAULTS)

One file exists for each CICS region. It is defined as a CICS file thatis a VSAM KSDS file with the CICS userid as key. Update it usingthe signon defaults function and use it to set up auto-signon to IBMConnect:Direct.

Temporary Data SetThe IBM Connect:Direct API TDEXIT parameter configures the routing of IBM Connect:Direct statisticsrecords to CICS Temporary Storage. CICS Temporary Storage, containing the data, is retained until theuser exits the SELECT STATISTICS screen. CICS Temporary Storage containing the data is then deleted.

Signing On and Off CICS

Signing OnYou must install both CICS and IBM Connect:Direct and they must be working on your mainframe. Youmust also be using an IBM 3270 terminal or equivalent. In order to use the CICS Interface, you must firstsign on. The SIGNON screen is the first screen displayed, unless you are authorized for auto-signon orauto-resignon. Sign on as follows:

1. Sign on to CICS using the CESN transaction (if needed).2. Sign on to Connect:Direct for z/OS, using the DGA transaction.3. Complete the prompted signon information.

The IBM Connect:Direct for z/OS SIGNON screen shows prompts for your userid, password, and nodename. Following is an example.

IBM Connect:Directfor z/OS 10:13:12 SIGNON

USER ID ==> _________________________________________________________________PASSWORD ==>NODE NAME ==> _________________Do you want all commands for this session to be CASE sensitive? ==> NOLicensed Materials - Property of IBMIBM(R) IBM Connect:Direct(R) for z/OS(R)(C) Copyright IBM Corp, 1982, 2011 All rights reserved.IBM is a Trademark of International Business Machines

PF keys: 1 Help 3 Exit

4. Type the userid, password, and node name information on this screen. After you have successfullysigned on, you see the PRIMARY MENU screen.

The following table describes the entry fields for the IBM Connect:Direct for z/OS SIGNON screen:

120 IBM Connect:Direct for z/OS: Documentation

Field Description

USER ID Following the USERID prompt, type in your userid. The 64-character fieldcontains the acceptable Connect:Direct for z/OS password for the CICSInterface. The CICS Interface administrator has an option to force your IBMConnect:Direct userid to be the same as the CICS userid. This option supportssecurity systems designed to use a single ID per user. When this option is set, theCICS Interface fills the signon screen with the CICS userid. The signon USERIDfield is then protected from update.

PASSWORD Following the PASSWORD prompt, type in your password. The 64-character fieldcontains the acceptable Connect:Direct for z/OS password for the CICS interface.The field is darkened to maintain security.

NODE NAME Following the NODE NAME prompt, type in the name of the IBM Connect:Directnode to which you want to sign on. Include the name of the 16-character field ofan active node.

Do you want allcommands forthis session to beCASE Sensitive?

Following this question, indicate whether you want to allow mixed case input.This option is available as a session default, and you can specify the optionduring signon. You can override the specified default on commands that apply touserid, password, and data set name. When you submit commands and specifyYES, IBM Connect:Direct includes the CASE=YES parameter with your command.

Note: Terminals used for the IBM Connect:Direct CICS interface must be definedwith UCTRAN(NO) if mixed case data is required.

Auto-SignonIf you are authorized for auto-signon, the SIGNON screen is displayed with an IN PROGRESS message.IBM Connect:Direct uses information stored in your user profile to complete the signon process. If you arenot authorized for auto-signon or your user profile does not contain signon information, you must sign onto IBM Connect:Direct manually.

Note: IBM Connect:Direct uses the CICS userid key to access profile information even when the CICSuserid does not equal the IBM Connect:Direct userid.

Auto-ReSignonIf configured for resignon, the CICS Interface automatically resigns on those returning to CICS, afterexiting CICS to use other CICS transactions. Resignon is canceled when you sign off CICS.

Note: When you attempt to reenter the CICS IUI, your userid and password are reverified by the DTF.

Status Alert ScreenIf you attempt to use the CICS Interface without first signing on to CICS, you see the Connect:DirectSTATUS ALERT screen.

The STATUS ALERT MESSAGE displayed near the center of the screen indicates a failure of your SIGNONattempt. If you encounter this screen, press PF3 to go to a blank screen with the message DGATRANSACTION ENDED in the upper left corner. At this point, sign on to CICS and then type in the DGAtransaction, followed by Enter to go to the PRIMARY MENU.

If the signon transaction at your site is defined with CICS security or with RACF, CA-ACF2, or CA-TOPSECRET security, messages are displayed from the appropriate security facilities instead of the STATUSALERT screen messages.

If the CICS Interface is not active, the STATUS ALERT screen is displayed with a message indicating thatthe interface is not active. In this case, you must activate the CICS Interface using the DGAA transaction.In addition, if your node is not active to the CICS Interface, either through the interface or through the

Chapter 3. CICS Administration and User Guide 121

node, you cannot sign on to that node. Ask your administrator to activate your session, your interface, oryour node. See the IBM Connect:Direct for z/OS Administration Guide.

Using the Primary MenuThe IBM Connect:Direct for z/OS PRIMARY MENU is the root menu of the menu hierarchy and is theaccess key to all other features of the CICS Interface.

The PRIMARY MENU contains a list of authorized IUI functions based on your IBM Connect:Directfunction authorization. Your administrator can globally restrict these IUI functions in the systemConfiguration file, so some options may not be available to you. In addition, under ESF operation, theoptions are restricted to submit and utility options only. Following is an example of the PRIMARY MENU.

IBM Connect:Direct for z/OS PRIMARY MENU 15:52:53

node.nameOPTION ==> __ CF COPY FILE SB SUBMIT PROCESS

SP SELECT PROCESS SS SELECT STATISTICS

MD MESSAGE DISPLAY SD SIGNON DEFAULTS SN CHANGE SIGNON

Licensed Materials - property of IBMIBM Connect:Direct for z/OS(C) Copyright IBM Corp, 1982, 2011 All Rights Reserved.IBM is a Trademark of International Business Machines

SAFA000I - Connect:Direct signon process completed.PF keys: 1 Help 2 Msg 3 Exit 6 Id

The 2-character OPTION field contains your option selection as follows.

Option Screen Accessed

CF COPY FILE BETWEEN NODES

SB SUBMIT PROCESS

SP SELECT PROCESS

SS SELECT STATISTICS

MD MESSAGE DISPLAY

SD SIGNON DEFAULTS

SN SIGNON

Press Enter after making your selection. Options CF, SB, SP, SS, and SD are described in other sectionsthat follow. Options SD and SN are described in this section.

Using the SN Option for Multiple Terminal SignonThe signon SN option also displays the signon screen. You can sign on to a IBM Connect:Direct node usingsignon information other than that specified in your user profile. You can sign on as you want, withoutupdating your user profile.

By using the SN signon option, you can sign on to multiple IBM Connect:Direct nodes, by signing on tomultiple CICS terminals. This is a convenience, not a multiple signon.

122 IBM Connect:Direct for z/OS: Documentation

If you sign on to multiple terminals, only the latest DTF signon authorization rules apply. The latestauthorization rules are used for all terminals where you previously signed on.

Updating Your Signon DefaultsYou can use the CICS IUI Signon Defaults (SD) menu option to type your signon defaults, which arestored as part of your user profile and used for subsequent CICS IUI access. The administrator canalso assign your user profile information. If you are authorized for auto-signon, you can bypass the IBMConnect:Direct for z/OS SIGNON screen by providing signon defaults.

Note: User profile information is keyed by CICS userid.

Use the SIGNON DEFAULTS screen to update your IBM Connect:Direct password, default node, ESFmode allowance, uppercase printing, CICS session printer, and sending and receiving node accountinginformation.

1. To access the SIGNON DEFAULTS screen, select option SD on the PRIMARY MENU and press Enter.Following is an example.

SIGNON DEFAULTS 11:51:48 node.name

CICS USERID ==> ________

**CONNECT:DIRECT** USERID ==> XXXXX1 PASSWORD==>

DEFAULT NODE ==> NODE.NAME ESF MODE ALLOWED ==> Y Y OR N UPPER CASE PRINT ==> Y Y OR N CICS PRINTER ==> LPT1 PNODE ACCT DATA ==> _______________________________________________ SNODE ACCT DATA ==> _______________________________________________

Do you want all commands for this session to be CASE sensitive? ==> NO

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id 9 Update Enter Edit Clear Reset

2. To display your current information, type your IBM Connect:Direct userid and password and pressEnter.

3. To change information, use the ARROW, TAB, and RETURN keys to move the cursor to the field youwant to change. Press PF9 to update the file.

The following table describes the fields on this screen:

Field Description

CICS USERID This 8-character system field contains your CICS userid. If you have a CICSuserid that is shared, then your update to the signon defaults affect all usersof that userid.

CONNECT:DIRECTUSERID

This 64-character field contains your IBM Connect:Direct userid. This field isrequired.

CONNECT:DIRECTPASSWORD

This 64-character field contains your IBM Connect:Direct password for theIBM Connect:Direct session. The field is darkened to maintain security.

DEFAULT NODE This 16-character field contains the name of your default node.

UPPER CASE PRINT This 1-character field contains the Y or N toggle to force uppercase printingon the CICS printer. Y means that all of the printed reports and summary tableprintouts from this user are in uppercase.

Chapter 3. CICS Administration and User Guide 123

Field Description

CICS PRINTER This 4-character field contains the designation for the printer connected toyour environment.

PNODE ACCT DATA This 50-character field contains your accounting data for the primary node.You can use it for your cost billing for CPU, I/O, and system resource time,materials, and personnel.

SNODE ACCT DATA This 50-character field contains your accounting data for the secondary node.You can use it for your cost billing for CPU, I/O, and system resource time,materials, and personnel.

Using the ESF Session Mode OptionESF MODE enables you to continue to submit processes when an active Connect:Direct for z/OS DTFsession fails or when session establishment fails. The ESF MODE interface differs from the primary nodein that the PRIMARY MENU only displays the SUBMIT options. You must install the ESF option on the localDTF and you must enable the ESF option in the Configuration file.

Note: In ESF MODE, the local node is available for use only through SUBMIT commands.

ESF SUBMIT requests can only be issued by those who have the ESF specified as a profile (SIGNONDEFAULTS) option.

Note: This option is restricted to the local node. The administrator can globally disallow it.

ESF MODE operation is toggled on for the entire Connect:Direct for z/OS interface through anadministrator parameter. ESF MODE operation is also toggled on for each user through a user profileparameter.

For the non-terminal user of the interface, the switch to primary mode (DTF MODE) is attempted until thattask completes. This limitation prevents having to abort the non-terminal processing (which could notcontinue in primary mode without another signon).

ESF Session Signon and NotificationAfter you sign on to ESF mode, Connect:Direct for z/OS notifies users that the session is in ESF mode inthe following ways:

• A message is displayed on all user screens that the session is in ESF mode• When a node session switches from ESF to primary mode, or from primary mode to ESF mode, all

terminal users of that node are notified on their next IUI access

DTF NotificationConnect:Direct for z/OS periodically attempts to establish or reestablish a failed DTF session. When ESFmode switches back to primary mode, Connect:Direct for z/OS prompts you for primary mode signon.

Connect:Direct for z/OS displays a special screen informing IUI users that the DTF has become activeor inactive. This screen gives you the option either to exit Connect:Direct for z/OS or to resignon in ESFmode.

Signing OffThe signoff sequence is as follows:

1. Press PF3 repeatedly until you reach the PRIMARY MENU or press PF4 once from your current screento go to the PRIMARY MENU.

2. Press PF3 again, and you see a blank screen with the message -- DGA TRANSACTION ENDED -- in theupper left corner.

3. Type CESF LOGOFF and press Enter.

124 IBM Connect:Direct for z/OS: Documentation

About Copying FilesThe Copy File menus are a series of panels that collect information used for copying files between nodes.You can use the following four screens to build a COPY Process:

Screen Name Description

COPY FILEBETWEEN NODESMenu

Specifies the sending and receiving nodes of the COPY and the submissionparameters for your COPY Process.

Security OverrideMenu

Collects information about userid, password, and accounting data. This optionalpanel is displayed only if you request it on the first panel.

SENDING FILEMenu

Collects information for the Process variables for the sending file.

RECEIVING FILEMenu

Collects the information for the Process variables for the receiving file.

The relationship of these four panels is illustrated in the following diagram.

Chapter 3. CICS Administration and User Guide 125

RequirementsTo copy a file between nodes the following must be true:

• You must be authorized to perform COPY Processes on both nodes• You must have access to the appropriate files on both nodes• Both nodes must be active• All interfaces must be started

Generating a Copy File from Connect:Direct for CICSIn the following procedure, you can skip Step 4 which involves the Security Override screen, if you do notenter Y in the OVERRIDE SECURITY field on the second Copy File Between Nodes screen.

To obtain Help on the field content of any screen, press the PF1 key.

1. To access the COPY FILE BETWEEN NODES first screen, select option CF on the PRIMARY MENU andpress ENTER.

COPY FILE BETWEEN NODES 15:34:14 node.name NODE NAME DESCRIPTION 01 MSDOS.NODE - MS-DOS NODE 02 MVS.NODE - MVS NODE 03 NETWARE.NODE - NETWARE NODE 04 OS2.NODE - OS/2 NODE 05 OS400.NODE - OS/400 NODE 06 VSE.NODE - VSE DTF 07 TANDEM.NODE - TANDEM NODE 08 UNIX.NODE - UNIX NODE 09 VM.NODE - VM NODE 10 VMS.NODE - VMS NODE 11 OS390.NODE1 - Z/OS NODE 12 OS390.NODE2 - Z/OS NODE SENDING NODE NUMBER => __ or NODE NAME=> ________________ ENV=> ________RECEIVING NODE NUMBER=> __ or NODE NAME=> ________________ ENV=> ________PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id 7 Bwd 8 Fwd

The top half of the COPY FILE screen presents a scrollable list of all the IBM Connect:Direct nodes thatcan participate in a COPY FILE Process (as defined in the CONFIGURATION file by the administrator).The list consists of a symbolic node name, a descriptive node name, and a node selection number.

2. Specify the copy file sending and receiving nodes by selecting the corresponding node selectionnumbers. If you do not see the node that you need, press PF8 to scroll the data forward in the list andpress PF7 to scroll the data backward.

When specifying a sending or a receiving node, you have two options:

• You can use the number from the scrollable list• You can use the node name and the environment

Note: If you do not provide this information, the default is the node that you are currently signed on to.

The ENV fields are updated automatically when you type the node number or node name from thescrollable list, but you must fill in the ENV field manually if the node name is not in the list.

The current node (as determined from the Network Map) is highlighted in the list and you must selectit as the sending or receiving default node. You can save the node choice numbers and display themagain the next time you enter this screen.

If the COPYFILE node is not listed, you must type both the copy node names and environment types.

The nodes in the scrollable list must be added using the DGAA transaction.

The following table defines each entry field on the Copy File Between Nodes panel.

126 IBM Connect:Direct for z/OS: Documentation

Entry Field Description

SENDING NODENUMBER

This 2-character field contains the sending node number. In the scrollable fieldto the left of the node name field are listed the associated node numbers. Ifyou specify neither, the sending node defaults to the node you are signed on to.When you identify the sending node and press ENTER, the environment field isfilled with the appropriate sending node.

NODE NAME This 16-character field contains the sending node name.

ENV This 8-character field contains the sending environment. If you do not selectfrom the list, you must specify the environment. Valid sending environmentsfor Connect:Direct for CICS are OS/390, VSE, VM, VMS, Tandem, OS/400,UNIX, and Windows (for Windows NT).

RECEIVING NODENUMBER

This 2-character field contains the receiving node number. In the scrollabletable to the left of the node name field the associated node numbers arelisted. If you specify neither, the receiving node defaults to the node that youare signed on to. When you identify the receiving node and press ENTER, theenvironment field is filled with the appropriate receiving node.

NODE NAME This 16-character field contains the receiving node name.

ENV This 8-character field names the receiving environment. Valid receivingenvironments for Connect:Direct for CICS are OS/390, VSE, VM, VMS, Tandem,OS/400, UNIX, and Windows (for Windows NT).

After the successful submission of the COPY FILE Process, this first screen in the panel series isredisplayed and a PROCESS NUMBER message is displayed. The PROCESS NUMBER message containsthe number assigned to your Process by IBM Connect:Direct.

3. After you provide the sending and receiving node names, press ENTER.

COPY FILE BETWEEN NODES 15:36:47 node.name

SENDING NODE NAME => OS390.NODE1 ENV=> OS390 RECEIVING NODE NAME=> OS390.NODE2 ENV=> OS390

NEW PROCESS NAME=> COPYCF__ CLASS => ___ (NUMERIC) HOLD => N (Y, N, or C-Call) PRIORITY => __ (RANGE: 0 to 15) REQUEUE => N (Y or N) RETAIN on TCQ => N (Y, N, OR I-Initial) START DATE => ________ START TIME=> __________ (HH:MM:SSXM) CHECKPOINT => ______ (BYTE INTERVAL - nK|nM) PLEXCLASS => ________ ________ (PNODE SNODE) COMPRESS => N____ (Y, N, E-Extended, X'xx', or C'c') OVERRIDE SECURITY=> N (Y or N)

Do you want values for this copy to be CASE sensitive? ==> NO

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

On the second COPY FILE BETWEEN NODES screen you can specify the parameters of the copy. Thefollowing table describes the system fields for this screen which contain information specified on thefirst COPY FILE BETWEEN NODES screen.

System Fields Description

SENDING NODE NAME This dual field contains the sending node name and environmentthat you provided in the previous screen.

Chapter 3. CICS Administration and User Guide 127

System Fields Description

RECEIVING NODE NAME This dual field contains the receiving node name and environmentthat you provided in the previous screen.

The following table describes each of the parameters you can specify for the copy.

Parameter Description

NEW PROCESSNAME

This 8-character field contains your selection for a new unique Process name tobe assigned to the COPY operation.

HOLD This 1-character field contains the Y, N, or C toggle for a Process to be keptin the HOLD queue. This field is optional. Y (yes) holds the Process until it isdeleted or released N (no) does not hold the Process (default) C (call) holdsthe Process in the Wait queue until the secondary node requests work. If theProcess consumes computer resources during periods of heavy system use, youcan place the Process temporarily in the Hold queue, and release it during a timeof infrequent use.

PRIORITY This 2-character field contains the priority number for Process execution. Thisfield is optional. Valid priority numbers range from 0-15 (highest).

REQUEUE This optional field specifies whether a copy step requeues if the Processterminates abnormally.

RETAIN on TCQ This 1-character field contains the Y, N, or I toggle to keep a copy of a Process ina queue after execution. Filling this field is optional. Y (yes) keeps the Process inthe queue after execution N (no) deletes the Process after execution I (initialize)schedules the Process for execution every time IBM Connect:Direct is initialized

START DATE This field contains the starting date for the copy operation expressed as month,day, and year. If you leave this field blank, the Process takes place on the currentdate. Fill in this field if you want to start the Process at some future time.

START TIME This 10-character field contains the starting time for the copy operationexpressed as hours, minutes, and seconds, AM or PM (HH:MM:SSXM). The defaultis a 24-hour clock. If a 12-hour clock is used, the AM or PM is required.

The starting time works in conjunction with the starting date, but the field isoptional. If you do not specify a time and the date is the current day, the Processbegins immediately.

If the date is set for a future date and the START TIME is not specified, theProcess begins at 12:00 AM. The START TIME field is optional. Use this field ifyou want to start the Process at some future time.

CHECKPOINT The CHECKPOINT field specifies the byte interval for checkpoint support, whichenables restart of interrupted transmissions at the last valid transmission point.This feature avoids the need to restart transmission from the beginning. Kdenotes thousands; M denotes millions. A checkpoint value of zero stopsautomatic checkpointing.

128 IBM Connect:Direct for z/OS: Documentation

Parameter Description

PLEXCLASS The PLEXCLASS field specifies the class that directs the Process to onlycertain servers in a IBM Connect:Direct/Plex. Only use this parameter in a IBMConnect:Direct/Plex. Each server in a IBM Connect:Direct/Plex can be designatedto support only certain PLEXCLASSes through the CDPLEX.PLEXCLASSESinitialization parameter. Processes can then be limited to only those servers byspecifying the PLEXCLASS in the Process definition. The PNODE class controlswhich IBM Connect:Direct/Server runs the Process. The SNODE class controlswhat other node is used with the Process. The PNODE class and SNODE classare each 1–8 characters long. Use an asterisk (*) to indicate that the Processcan run on any server with an asterisk designated in the CDPLEX.PLEXCLASSESinitialization parameter. If no PLEXCLASS is specified, the Process runs on anyIBM Connect:Direct/Server that supports PLEXCLASS. If a Process must run on aspecific IBM Connect:Direct/Server, specify the IBM Connect:Direct/Server namein this field. The Process runs only on that server.

COMPRESS The COMPRESS field specifies that IBM Connect:Direct is to compress the data.This feature reduces the amount of data transmitted as the file copies fromone node to another. IBM Connect:Direct automatically decompresses the fileat its destination. The default subparameter for the COMPRESS parameter isPRIMEchar=X'40'.

OVERRIDESECURITY

If you want to type security information such as userid and password, type a Yat the OVERRIDE SECURITY prompt. IBM Connect:Direct displays the SECURITYOVERRIDE screen. (See the next step.)

CASE Sensitive Following this question, indicate whether you want to allow mixed case input.This option is available as a session default, and you can specify the optionduring signon. You can override the specified default on commands that applyto userid, password, and data set name. When you submit commands withYES specified, IBM Connect:Direct includes the CASE=YES parameter with yourcommand.

CICS only interprets mixed case data if your terminal is defined to accept it. TheCICS RDO or CEDA definition must be defined with UCTRAN=NO for mixed casedata to be input to IBM Connect:Direct from a CICS terminal.

4. If you typed Y in the Override Security prompt on the COPY FILE BETWEEN NODES screen, IBMConnect:Direct the optional SECURITY OVERRIDE screen is displayed.

COPY FILE BETWEEN NODES 17:28:36 node.name

SECURITY OVERRIDE

SENDING NODE NAME => OS390.NODE1 ENV => OS390

SECURITY ID: ________________________________________________________________PASSWORD : NEW PASSWORD: ACCT DATA : ________________________________________________________________

RECEIVING NODE NAME => OS390.NODE2 ENV => OS390

SECURITY ID: ________________________________________________________________PASSWORD : NEW PASSWORD: ACCT DATA : ________________________________________________________________

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

The screen contains the same entry fields for both the sending and receiving nodes. The followingtable describes each entry field.

Chapter 3. CICS Administration and User Guide 129

Entry Field Description

SECURITY USERID This optional field specifies the 1-64 character security ID that passes to asecurity exit.

PASSWORD This optional field specifies the 1-64 character current security password topass to a security exit.

NEW PASSWORD This optional field specifies the new 1-64 character security password to bepassed to a security exit. The exit can change the current password to thisvalue.

ACCT DATA This optional field specifies accounting data to be passed to the security exit.

5. The values selected in the Sending and Receiving Node Name and Environment fields on the firstscreen determine which Sending and Receiving screens display to complete your COPY statement.The following example shows the Sending File screen for z/OS. (The valid Environment values forsending COPY files are: OS/390, OS/400, WIN95, VM, VMS, VOS, VSE, TANDEM, and UNIX.)

COPYFILE - SENDING FILE (OS/390) 17:28:36 node.name

SENDING NODE: ...=> OS390.NODE1

SENDING DSNAME => ___________________________________________UNIT => (________________________________)VOLUME => (___________________________________________________)

SYSOPTS => “ _________________________________________________ _________________________________________________ _________________________________________________ _________________________________________________ _________________________________________________”PDS ONLY:SELECTION CRITERIA => ______________________________________ => ______________________________________ => ______________________________________ => ______________________________________REPLACE => N (Y OR N)

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

Note: For a complete description of the valid parameters of a COPY Statement and examples, see IBMConnect:Direct for z/OS Process Language Reference Guide.

a) Fill in the appropriate values for the SENDING FILE screen.b) When you finish typing the values on the SENDING FILE screen, press PF3 to proceed to the

RECEIVING FILE screen.6. The values selected for the Receiving Node Name and Environment fields on the first screen determine

which Receiving screen is displayed to complete your COPY statement.The following example shows the Receiving File screen for z/OS.

130 IBM Connect:Direct for z/OS: Documentation

COPYFILE - RECEIVING FILE (OS/390) 17:28:36 node.name

RECEIVING NODE => OS390.NODE2

RECEIVING DSNAME => _______________________________________

DISP => ( NEW , CATLG )UNIT => ( ________________________________ )VOLUME => ( ___________________________________________________ )DCB => ( _________________________________________________________ )LABEL => ( ________________________________ )SPACE => ( ________________________________ )

TYPEKEY => ________

SYSOPTS => “ _________________________________________________ _________________________________________________ _________________________________________________ _________________________________________________ _________________________________________________”

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

a) Fill in the appropriate values for the RECEIVING FILE screen.b) When you finish typing the values on the RECEIVING FILE screen, press PF3 to process the copyfile

request and exit.

Copying a File from Your Node to Your NodeUse Connect:Direct for z/OS CICS to copy a file from your node back to your node, by performing thefollowing procedure:

1. Select option CF from the PRIMARY MENU and press ENTER to display the COPY FILE BETWEENNODES screen.

Note: You are signed on to a z/OS node for this example. Ensure that your node name is in the nodelist at the top of the screen. If it does not display, ask the administrator to start your node on thenetwork. Alternatively, you can type in your node number, node name, and environment directly.

2. Type in your node number in the SENDING NODE NUMBER field.3. Type in your node number in the RECEIVING NODE NUMBER field and press ENTER.4. Ensure that all your entries are correct and press ENTER.5. Assuming the sending file is cataloged, on the COPYFILE - SENDING FILE (z/OS) screen, type in the

SENDING DSNAME and press ENTER.6. On the COPYFILE - RECEIVING FILE (z/OS screen, type in the RECEIVING DSNAME and press ENTER.7. When the Process is submitted to IBM Connect:Direct, the COPY FILE BETWEEN NODES screen with

the PROCESS NUMBER message is displayed. This number indicates the number assigned to yourProcess.

8. Press PF4 to go to the PRIMARY MENU.9. Select option SP to go to the SELECT PROCESS screen to check on the status of your Process.

10. On the SELECT PROCESS screen select option O for OPERATOR TABLE, select A for all queues, typein the PROCESS NUMBER you observed from the COPY FILE BETWEEN NODES screen, and pressENTER to display the status.

Chapter 3. CICS Administration and User Guide 131

Building, Modifying, and Submitting Processes through CICS

Submit Process ScreenUse the SUBMIT PROCESS screen to execute a Process by identifying the Process name, secondary node,times and dates, priority, requeue, class, hold and retain status, and symbolic parameters. The Process islocated in the local node IBM Connect:Direct Process library.

You can specify symbolic parameters before you submit the Process to the IBM Connect:Direct DTFfor execution. The IUI then submits the IBM Connect:Direct COPY Process to the connected IBMConnect:Direct DTF (the DTF specified on the Connect:Direct for z/OS CICS signon). A PROCESSSUBMITTED message is returned after the Process is successfully submitted to the DTF.

To access the SUBMIT PROCESS screen, select option SB on the PRIMARY MENU screen and press Enter.Following is an example.

SUBMIT PROCESS 11:24:50 node.name

PROCESS NAME ==> ________

SECONDARY NODE ==> ________________ HOLD PROCESS ==> _ (Y=YES, N=NO, C=CALL) REQUEUE PROCESS ==> _ (Y=YES, N=NO) RETAIN PROCESS ==> _ (Y=YES, N=NO, I=INIT) PRIORITY ==> __ CLASS ==> ___ START DATE ==> __________ TIME ==> __________ NEW PROCESS NAME ==> ________ PLEXCLASS ==> ________ ________ (PNODE SNODE) SYMBOLIC PARAMETERS ==> _____________________________________________________ ______________________________________________________________________________

OVERRIDE SECURITY=> N (Y or N)

Do you want values for this process to be CASE sensitive? ==> NO

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

The following table describes the Entry fields:

Field Description

PROCESS NAME 8-character field contains the name of the Process to be submitted. Field isrequired.

SECONDARYNODE

This 16-character field contains the name of the secondary node (destination node)to which the Process is to be submitted. This field is optional. The value defaults tothe SNODE specified in the Process.

HOLD PROCESS This 1-character field contains the Y, N, or C toggle for a Process to be kept in theHOLD queue. This field is optional.

• Y (yes) holds the Process until it is deleted or released.• N (no) does not hold the Process. This value is the default.• C (call) holds the Process in the Wait queue until the secondary node requests

work. If the Process consumes computer resources during periods of heavysystem use, you can place the Process temporarily in the Hold queue, and releaseit during a time of infrequent use.

REQUEUEPROCESS

This optional field specifies whether a copy step requeues if the Process terminatesabnormally.

132 IBM Connect:Direct for z/OS: Documentation

Field Description

RETAIN PROCESS This 1-character field contains the Y, N, or I toggle to keep a copy of a Process in aqueue after execution. This field is optional.

• Y (yes) keeps the Process in the queue after execution.• N (no) deletes the Process after execution.• I (initialize) schedules the Process for execution every time IBM Connect:Direct is

initialized.

PRIORITY This 2-character field contains the priority number for Process execution. This fieldis optional. Valid priority numbers range from 0–15 (highest).

CLASS This 3-character field contains the Process class assignment for a submittedProcess. Filling the field is optional. Acceptable values range from 1–255.

TIME This 10-character field contains the start time expressed as hours, minutes, andseconds AM or PM (HH:MM:SSXM). This field is optional. Enter the start time on thebasis of a 12- or 24-hour clock. If AM or PM is not used, the default is a 24-hourclock (2:00 PM or 14:00).

NEW PROCESSNAME

8-character field contains a new name for a submitted Process. This field isoptional.

PLEXCLASS =(pnode class,snode class)

Specifies the class that directs the Process to only certain servers in a IBMConnect:Direct/Plex. This parameter is only used in a IBM Connect:Direct/Plex.

Each server in a IBM Connect:Direct/Plex can be designated to support onlycertain PLEXCLASSes through the CDPLEX.PLEXCLASSES initialization parameter.Processes can then be limited to only those servers by specifying the PLEXCLASS inthe Process definition.

The PNODE class controls which IBM Connect:Direct/Server runs the Process. TheSNODE class controls what other node is used with the Process.

The PNODE class and SNODE class are each 1-8 characters long. Use an asterisk(*) to indicate that the Process can run on any server with an asterisk designatedin the CDPLEX.PLEXCLASSES initialization parameter. If no PLEXCLASS is specified,the Process runs on any IBM Connect:Direct/Server that supports PLEXCLASS.

If a Process must run on a specific IBM Connect:Direct/Server, specify the IBMConnect:Direct/Server name in this field. The Process runs only on that server.

SYMBOLICPARAMETERS

This 2-line field contains the symbolic parameters that you want substituted for theitems in the SUBMIT PROCESS operation. This field is optional. Enter the symbolicsas follows: &PARAMETER=SUBSTITUTION, and so forth. You can specify as manysymbolic parameters as fit on the lines provided. Each must be separated by atleast one space.

SECURITYOVERRIDE

This optional field is for PNODE and SNODE security checking. Type a Y or N.You can check or modify security information on PNODE or SNODE on the SubmitProcess screen. Refer to Security Override Screen.

Chapter 3. CICS Administration and User Guide 133

Field Description

CASE Sensitive Following this question, indicate whether you want to allow mixed case input. Thisoption is available as a session default, and you can specify the option duringsignon. You can override the specified default on commands that apply to userid,password, and data set name. When you submit commands with YES specified, IBMConnect:Direct includes the CASE=YES parameter with your command.

Note: CICS only interprets mixed case data if your terminal is defined to acceptit. The CICS TCT MACRO or RDO TYPETERM definition must be defined withUCTRAN=NO for mixed case data to be input to IBM Connect:Direct from a CICSterminal.

The following table describes the one system field which is displayed after you successfully submit aProcess.

Field Description

PROCESSNUMBER number

This 21-character field contains the PROCESS NUMBER number message after thesuccessful completion of a SUBMIT PROCESS task, where number is the system-generated Process number.

Security Override ScreenThe security override panel provides the opportunity to check or modify PNODE and SNODE security. Thispanel is displayed when you specify yes for the OVERRIDE SECURITY prompt of the SUBMIT PROCESSscreen.

SUBMIT PROCESS 11:38:25 node.name

SECURITY OVERRIDE

<<PNODE>>

SECURITY ID: ________________________________________________________________ PASSWORD : NEW PASSWRD: ACCT DATA : ________________________________________________________________

<<SNODE>>

SECURITY ID: ________________________________________________________________ PASSWORD : NEW PASSWRD: ACCT DATA : ________________________________________________________________

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

The SUBMIT PROCESS SECURITY OVERRIDE screen contains the following entry fields, one set for thePNODE and one for the SNODE:

Field Description

SECURITY USERID This optional field specifies the 1–64 character security ID that passes to a securityexit.

PASSWORD This optional field specifies the 1–64 character current security password to passto a security exit.

NEW PASSWORD This optional field specifies the new 1–64 character security password to bepassed to a security exit. The exit changes the current password to this value.

ACCT DATA This optional field specifies accounting data to be passed to the security exit.

134 IBM Connect:Direct for z/OS: Documentation

Selecting a Process through CICS

Determining the Status of a Submitted ProcessThe Select Process and Select Process - Operator Table screens allow you to view information about theProcesses you have submitted.

1. To access the SELECT PROCESS screen to view information about your Processes, type SP on thePRIMARY MENU and press Enter.

Following is an example of the SELECT PROCESS screen.

SELECT PROCESS 11:39:56 node.name

OPTION ==> O (O - OPERATOR TABLE P - PRINT REPORT)

QUEUE ==> _ (A-ALL,W-WAIT,E-EXECUTE,H-HOLD,T-TIMER)

PROCESS NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______PROCESS NAMES: ==> ________ ==> ________ ==> ________ ==> ________SERVER NAMES: ==> ________ ==> ________ ==> ________ ==> ________

STATUS: (HO,HR,HI,HE,HC,HP,HS,RH,RA,WC,H,R,W) ==> __ ==> __ ==> __ ==> __ DESTINATION NODES: ==> ________________ ==> ________________ ==> ________________ ==> ________________ USER ID: NODE ID: ==>.node1 ==> node.name ==> ________________________________________________________________ ==> ________________

Do you want values for this command to be CASE sensitive? ==> NO

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

The following table describes the entry fields on this screen:

Field Description

QUEUE This 1-character field contains your selection of the Process queues for display:A (to select all queues), W (for the Wait queue), E (for the execution queue), H(for the Hold queue), or T (for the Timer queue). This field is optional.

PROCESSNUMBERS

These four fields of six characters each contain the numbers of Processes to beselected. The field is optional. If you select nothing, all Processes in the selectedqueue are displayed.

PROCESS NAMES These four fields of eight characters each contain the names of Processes to beselected. The field is optional. If you select nothing, all Processes in the selectedqueue are displayed.

SERVER NAMES These four fields contain the IBM Connect:Direct/Server names to selectProcesses from. The server name is a 1–8 character name assigned to eachserver in a IBM Connect:Direct/Plex through the CDPLEX.SERVER initializationparameter. This field only applies to a IBM Connect:Direct/Plex.

Chapter 3. CICS Administration and User Guide 135

Field Description

STATUS This optional field indicates specific queue status selection by use of thefollowing characters:

HO, held by operator. The Process was submitted without hold specified andlater was changed with the CHANGE PROCESS command.

HR, held retain. The Process was submitted with RETAIN=YES specified.

HI, held initially. The Process was submitted with HOLD=YES specified.

HE, held in error. The Process was submitted, but the submitter is not defined onthe SNODE.

HC, held for call. The Process was submitted with HOLD=CALL specified. Asession started from the other node causes this Process to be put on the waitqueue in WC status.

HP, held Process error. An error occurred during initiation of Process execution.This condition can occur if the session is lost before any Process Statementsbegin to execute.

HS, held for suspension. The operator issued a SUSPEND PROCESS command.The Process can be released later.

RH, restart Held. A checkpointed Process was executing when an error such as alost session or an I/O error occurred. This enables the copy to be restarted whenthe session is lost and reestablished.

RA, held for restart allocation error. During Process execution, an allocation erroroccurred matching those specified in the initialization parameters. This statusenables the Process to be restarted after the allocation problem is resolved.

STATUS WC, wait for connection. Session establishment attempted, including retries ifspecified, and failed. This Process is put on the wait queue and processed ifa session with that node is established later. It can also be released by theoperator.

WT, wait for transport. The transport protocol is not available. The Process runsas soon as the transport protocol is available.

WX, wait for server. The Process is waiting for an eligible IBM Connect:Direct/Server to become available. The Process runs as soon as an eligible IBMConnect:Direct/Server is available.

An eligible IBM Connect:Direct/Server is an active server that supports theProcess PLEXCLASS and the transport protocol (SNA, TCP, or CTCA). Thetransport protocol must also be available on the server for it to be eligible.

H, all Held Processes. This selection enables you to view a list of all heldProcesses from the Select Process screen.

R, all restarted Processes. This selection enables you to view a list of all restartedProcesses from the Select Process screen.

W, all waiting Processes. This selection enables you to view a list of all waitingProcesses from the Select Process screen.

DESTINATIONNODES

This optional field indicates the destination site identifier (NODE NAME).

USER ID This optional field is an alphanumeric userid corresponding to a selectedProcess.

136 IBM Connect:Direct for z/OS: Documentation

Field Description

NODE ID This optional field identifies the submitter node corresponding to a selectedProcess. NODE ID is required if USER ID is specified.

Do you wantvalues for thiscommand to beCASE Sensitive?

Following this question, indicate whether you want to allow mixed case input.This option is available as a session default, and you can specify the optionduring signon. You can override the specified default on commands that apply touserid, password, and data set name. When you submit commands and specifyYES, IBM Connect:Direct includes the CASE=YES parameter with your command.

Note: CICS only interprets mixed case data if your terminal is defined to acceptit. The CICS RDO TYPETERM definition must be defined with UCTRAN(NO) formixed case data to be input to IBM Connect:Direct from a CICS terminal.

2. Take one of the following actions in the OPTION field:

• To print a report on your default printer (defined in your signon defaults), type P and press Enter.• To access the SELECT PROCESS - OPERATOR TABLE screen and create a 1-line summary of each

selected Process, specify the entry fields listed above, then type O (alphabetic, not zero) and pressENTER.

Viewing Summary InformationYou can use the SELECT PROCESS - OPERATOR TABLE screen to view summary information aboutProcesses pending or executing, including name, number, sending and receiving nodes, queue type andstatus, and last message received.

1. To access the SELECT PROCESS - OPERATOR TABLE screen, access the SELECT PROCESS screeen, fillin the entry fields to specify the Processes, and type O (alphabetic, not zero) and press Enter.

Following is an example of the SELECT PROCESS - OPERATOR TABLE screen.

SELECT PROCESS - OPERATOR TABLE 11:02:05 node.name

Cmd ProcName ProcNum Submitter Node Secondary Node QType QStat Last Msgid --- -------- ------- ---------------- ---------------- ----- ----- ----------

_ COPYNC 202 OS390.NODE MVS.NODE TIMER WC

_ COPYJC 203 OS390.NODE MVS.NODE TIMER WC

Line commands: M Last Msgid S Select process detail

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id Enter Refresh

The following table describes the fields on the SELECT PROCESS - OPERATOR TABLE screen:

Field Description

PAGE XXXX OFYYYY

This 17-character field contains the current page number XXXX out of YYYY totalpages of SELECT PROCESS -- OPERATOR TABLE data.

ProcName This 9-character field contains the Process name.

ProcNum This 6-character field contains the Process number.

Submitter Node This 16-character field contains the node name of the primary node.

Secondary Node This 16-character field contains the node name of the secondary node.

Chapter 3. CICS Administration and User Guide 137

Field Description

QType This 5-character field contains the type of queue:

• EXEC - Process is currently executing• HOLD - Process is held• WAIT - Process is waiting for execution• TIMER - Process is to execute at a given time

QStat This 2-character field contains the current status of the queue:

• EX - currently executing• HC - is held for call• HE - held in error• HI - held initially• HO - held by the operator• HP - an error occurred during initiation of Process execution• HR - submitted with RETAIN=YES• HS - is held for suspension• RA - is held for restart allocation error• RH - is held for restart• RS - is being restarted• WA - is awaiting acknowledgement• WC - is awaiting connection• WP – is waiting on PARSESS (Parallel Session) availability.• WR - is awaiting restart• WS - is awaiting the designated start time• WT - is awaiting transport protocol• WX - is awaiting an eligible IBM Connect:Direct/Server

Last Msgid This 8-character field contains the designation of the last message received forConnect:Direct for z/OS operations.

2. Take one of the following actions in the Cmd column next to the ProcName:

• To display the text of the last message received for this Process, type M and press Enter.• To display the SELECT PROCESS -- PROCESS DETAIL screen, type S and press Enter.

Viewing Process DetailYou can use the SELECT PROCESS - PROCESS DETAIL screen to view detailed information about pendingor executing Processes selectively, by choosing any one of the Process details, such as name, number,queueing priority, schedule time, retain status, I/O bytes, and so forth.

1. To access the SELECT PROCESS - PROCESS DETAIL screen, type S and press Enter on the SELECTPROCESS - OPERATOR TABLE screen.

Following is an example.

138 IBM Connect:Direct for z/OS: Documentation

SELECT PROCESS - PROCESS DETAIL 11:21:16OPTION ==> S (M or S) node.name

Options: M - Last Msgid; S - Select process detail RECEIVING SIDE Process Name => SEQ001 Number => 3 Step => STEP1 Other Node => SC.SC1.SWOOD2 Status => EX Commid => 26221;10.20.129.168 Queue => EXEC Function => COPY Sub State => State => FILE I/O Server Name => SDWSERV1 PLEXCLASS => ( * ) Submitter => SC.SC1.SWOOD1 Userid => SYS002 Scheduled Time => Date => Day => Queueing Prty => 10 Class => 1 Retain => NO Submitted Class=> NONE Max Class => NONE Sess.Id=> PNOD Session restrt => 0 Dyn restrt=> 0 RouteID=> Last Msgid => Last RC => 00000000 RetProc=>

Sending File => CSDQA1.TESTFILE.BENCH.M10 Receiving File => SWOOD1.TEMPM10 Volume seq no. => 1 Volser => USER28 TTRN => 000B0100 Blks => 23 Recs => 0 RUs => I/O bytes => 642,160 Member => VTAM bytes => 436,224 Compression Factor =>

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id Enter Refresh

The following table describes the fields on the SELECT PROCESS - PROCESS DETAIL screen:

Field Description

SIDE This 14-character field contains the message SENDING SIDE if the PROCESSDETAIL parameters are from the sender and the message RECEIVING SIDE if thePROCESS DETAIL parameters are from the receiver. The field occurs in the upperright corner below the NODE field.

Process Name This 8-character field contains the name of the selected Process.

Number This 6-character field contains the Process number.

Step This 8-character field contains the name of the currently executing step of theselected Process.

Other Node This 16-character field contains the name of the node identified as thedestination of the Process.

Chapter 3. CICS Administration and User Guide 139

Field Description

Status This 2-character field contains the current status of the queue:

• EX - currently executing• HC - is held for call• HE - held in error• HI - held initially• HO - held by the operator• HP - an error occurred during initiation of Process execution• HR - submitted with RETAIN=YES• HS - is held for suspension• RA - is held for restart allocation error• RH - is held for restart• RS - is being restarted• WA - is awaiting acknowledgement• WC - is awaiting connection• WP – is waiting on PARSESS (Parallel Session) availability.• WR - is awaiting restart• WS - is awaiting the designated start time• WT - is awaiting transport protocol• WX - is awaiting an eligible IBM Connect:Direct/Server

Commid This 46-character field contains the SNA VTAM APPLID (applicationidentification) of the destination IBM Connect:Direct node. If the destinationnode is TCP/IP, this field contains the port and IP address of the remote node inthe format port_number;IP_address.

Queue This 5-character field contains the name of the queue where the selectedProcess resides: WAIT, TIMER, EXEC, or HOLD.

Function This 8-character field contains the name of the function being performed by theProcess.

Sub State This 12-character field contains the name of the current session macro inexecution.

State This 8-character field contains the current state of the Process.

Server Name The name of the IBM Connect:Direct/Server where the Process runs. This fieldonly applies to a IBM Connect:Direct/Plex.

PLEXCLASS The class that directs the Process to only certain servers in a IBMConnect:Direct/Plex. This field only applies to a IBM Connect:Direct/Plex.

Submitter This 16-character field contains the name of the submitting node.

Userid This 8-character field contains the userid that submitted the Process.

Scheduled Time This 8-character field contains the time when the Process is scheduled toexecute.

Date This 8-character field contains the date when the Process is scheduled toexecute.

Day This 10-character field contains the name of the day when the Process isscheduled to execute.

140 IBM Connect:Direct for z/OS: Documentation

Field Description

Queueing Prty This 3-character field contains the queueing priority of the selected Process. Therange of priorities is 0–15 (highest).

Class This 4-character field contains the class or parallel session used.

Retain This 4-character field contains YES or NO to indicate the retain status.

Submitted Class This 4-character field contains the submitted class.

Max Class This 4-character field contains the maximum number of parallel sessionsallowed.

Sess. Id This 4-character field contains the session ID (P for SNA primary and S for SNAsecondary).

Session restrt This 3-character field contains the number of consecutive session attemptfailures.

Dyn restrt This 3-character field contains the number of failed attempts to perform a copyto an unavailable file.

RouteID This 8-character field contains the userid to notify upon completion of a step orProcess.

Last Msgid This 8-character field contains the last message number received by thisProcess. Selecting option M displays the text of the message.

Last RC This 8-character field contains the last step return code, if the Process went intoexecution.

RetProc The retained Process number.

Sending File This 44-character field contains the name of the sending file.

Receiving File This 44-character field contains the name of the receiving file.

Volume seq no. This 3-character field contains the volume sequence number.

Volser This 6-character field contains the volume serial number.

TTRN This 8-character field contains the TTR address (disk) or relative block (tape)currently accessed.

Blks This 9-character field contains the number of blocks sent or received.

Recs This 14-character field contains the number of records sent or received as aresult of the Process.

RUs This 9-character field contains the number of request units sent or received.

I/O bytes This 22-character field contains the number of bytes read or written fromexternal storage.

Member This 8-character field contains the name of the copied member during a PDScopy operation.

VTAM bytes This 22-character field contains the number of bytes transmitted.

CompressionFactor

This 6-character field contains the percentage of savings from the use of datacompression from a copy Process.

2. Take one of the following actions in the OPTION field:

• To display the text of the last message received for this Process, type M and press Enter.• To refresh the SELECT PROCESS -- PROCESS DETAIL parameters, type S and press Enter.

Chapter 3. CICS Administration and User Guide 141

Selecting Statistics through CICS

Viewing Process StatisticsUse the SELECT STATISTICS screen to view Process statistics, by choosing any combination of Processnames, numbers, start and stop times and dates, and condition codes. Process statistics summarize theIBM Connect:Direct Process execution event log information for a DTF.

1. To access the SELECT STATISTICS screen, type SS and press ENTER on the PRIMARY MENU. Followingis an example.

SELECT STATISTICS 11:34:47 node.name

OPTION ==> _

PROCESS NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______PROCESS NAMES: ==> ________ ==> ________ ==> ________ ==> ________

START DATE ==> ________START TIME ==> ___________ (HH:MM:SSXM)STOP DATE ==> ________STOP TIME ==> ___________ (HH:MM:SSXM)CONDITION CODE ==> __ __________EXCLUDE MEMBER RECS ==> N (Y OR N)EXCLUDE WTO RECS ==> Y (Y OR N)

OPTIONS: S ... SUMMARY TABLE P ... PRINT REPORT

PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

2. Take one of the following actions:

• To generate a printed report of the Process statistics on the printer (defined in your signon defaults),fill in the criteria using the entry fields, and in the OPTION field, type P and press ENTER.

• To access the SELECT STATISTICS - SUMMARY TABLE screen where a summary of Process statisticsare displayed, fill in the criteria using the entry fields, and in the OPTION field, type S and pressENTER.

The following table describes the entry fields for the SELECT STATISTICS screen:

Field Description

OPTION This 1-character field contains the S or P option as follows:

• S to access the SELECT STATISTICS - SUMMARY TABLE screen where a summary of Processstatistics are displayed.

• P to generate a printed report of the Process statistics on the printer (defined in your signondefaults).

PROCESSNUMBERS

These four fields of eight characters each contain the numbers of Processes selected forstatistical information. You can type one to four Process numbers for statistics selection.

PROCESSNAMES

These four fields of eight characters each contain the names of Processes selected forstatistical information. You can type one to four Process names for statistics selection.

142 IBM Connect:Direct for z/OS: Documentation

Field Description

START DATE This 8-character field specifies the date from which the statistics records are selected. Youcan specify the day (D), month (M), and year (Y).

To specify the order of a Gregorian day, month, and year, you must define the DATEFORMinitialization parameter. If you do not specify the DATEFORM parameter, Connect:Direct forz/OS defaults to MDY date format.

After you have specified the order in the DATEFORM initialization parameters, you can use thefollowing formats according to the order you selected:

• DATEFORM=MDY specifies the use of the following formats:

– mmddyy or mmddyyyy– mm/dd/yy or mm/dd/yyyy– mm.dd.yy or mm.dd.yyyy

• DATEFORM=DMY specifies the use of the following formats:

– ddmmyy or ddmmyyyy– dd/mm/yy or dd/mm/yyyy– dd.mm.yy or dd.mm.yyyy

• DATEFORM=YMD specifies the use of the following formats:

– yymmdd or yyyymmdd– yy/mm/dd or yyyy/mm/dd– yy.mm.dd or yyyy.mm.dd

• DATEFORM=YDM specifies the use of the following formats:

– yyddmm or yyyyddmm– yy/dd/mm or yyyy/dd/mm– yy.dd.mm or yyyy.dd.mm

IBM Connect:Direct processes Julian dates the same as previous releases. The followingformats are valid:

• yyddd or yyyyddd• yy/ddd or yyyy/ddd• yy.ddd or yyyy.ddd

START TIME This 10-character field contains the start date expressed as hours, minutes, and seconds,and AM or PM (HH:MM:SSXM). You can specify either a 12-hour or 24-hour time or thewords NOON or MIDNIGHT. If you use 12-hour time, designate AM or PM; if you do not,Connect:Direct for z/OS CICS assumes a 24-hour time format. Processes that started after thetime specified are selected for reporting.

STOP DATE This 8-character field specifies the date from which the statistics records are selected. Specifythe day (D), month (M), and year (Y).

To specify the order of a Gregorian day, month, and year, you must define the DATEFORMinitialization parameter. If you do not specify the DATEFORM parameter, Connect:Direct forz/OS defaults to MDY date format.

After you have specified the order, you can specify formats. See the START DATE field for adescription of the formats that you can use.

Chapter 3. CICS Administration and User Guide 143

Field Description

STOP TIME This 10-character field contains the stop date expressed as hours, minutes, and seconds AMor PM (HH:MM:SSXM). You can specify either a 12-hour or 24-hour time or the words NOONor MIDNIGHT. If you use 12-hour time, designate AM or PM; if you do not, Connect:Direct forz/OS CICS assumes a 24-hour time format. Processes that started before the time specifiedare selected for reporting.

CONDITIONCODE

This dual field contains the condition code for the selected Process; the first 2-characterfield contains a logical operator (LT, LE, GT, GE, NE, or EQ); and the second 8-character fieldcontains the condition code to be checked. If a condition code is specified, all Processesterminating with the specified code are selected for reporting.

EXCLUDEMEMBERRECS

This 1-character field contains the Y or N toggle to include or omit member records from PDScopy statistical information.

EXCLUDE WTORECS

This 1-character field contains the Y or N to include or omit Write To Operator records in thedisplayed statistical information. If you do not want WTO records to be displayed, select Y; ifyou do, select N.

Viewing Statistics Summary InformationUse the SELECT STATISTICS - SUMMARY TABLE screen to view a list of Process statistics, includingfunction type, Process name and number, sending and receiving nodes, last message received, end timeand date, and the return code.

1. To access the SELECT STATISTICS - SUMMARY TABLE screen, select option S on the SELECTSTATISTICS screen, and press ENTER.

Following is an example.

SELECT STATISTICS - SUMMARY TABLE 17:36:45 node.name Cmd Function ProcName ProcNum Submitter Node Secondary Node Last Msgid RC (M) Submitter P/Snode End date End time --- -------------------------------------------------------------------------- _ SUB-CMD COPYNC 0 OS390.NODE OS390.NODE SPQL001I 0C OPER PNODE 05/05/1998 12:37:46 _ SUB-CMD FROMMVS 0 OS390.NOD OS390.NODEE SPQL001I 0C OPER PNODE 05/05/1998 12:40:06 _ SUB-CMD FROMMVS 0 OS390.NOD OS390.NODEE SPQL001I 0C SCIVSE5 PNODE 05/05/1998 12:44:19 _ SUB-CMD FROMMVS 1 OS390.NOD OS390.NODEE SSPA001I 00 SCIVSE5 PNODE 05/05/1998 12:59:05 _ PROC-END FROMMVS 1 OS390.NOD OS390.NODEE ACF01012 0C SCIVSE5 PNODE 05/05/1998 12:59:20 _ SUB-CMD FROMMVS 2 OS390.NOD OS390.NODEE SSPA001I 00 SCIVSE5 PNODE 05/05/1998 13:03:55 _ COPY-END FROMMVS 2 OS390.NOD OS390.NODEE SCPA000I 00 SCIVSE5 PNODE 05/05/1998 13:04:35 _ PROC-END FROMMVS 2 OS390.NOD OS390.NODEE SVTM100I 00 SCIVSE5 PNODE 05/05/1998 13:04:35 Page 1 of 42 SOPS000I - Select Statistics command successfully completed. PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id 8 Fwd

2. To go to the LAST MESSAGE screen and display the text of the last message received by a particularProcess, in the Cmd column next to the the line containing the Process, type M and press ENTER.

The following table describes the system fields for the SELECT STATISTICS - SUMMARY TABLE:

Field Description

PAGE 17-character field contains the current page number and total pages of SELECTSTATISTICS - SUMMARY TABLE data.

144 IBM Connect:Direct for z/OS: Documentation

Field Description

FUNCTION 9-character field contains the function designation for Connect:Direct for z/OSProcess statistics.

PROCNAME This 8-character field contains the Process name.

PROCNUM This 6-character field contains the Process number.

SUBMITTERNODE

This 16-character field contains the node name of the primary node.

SECONDARYNODE

This 16-character field contains the node name of the secondary node.

LAST MSGID This 8-character field contains the designation of the last message received bythe Process.

RC This 2-character field contains a system-generated return code as a result of thesuccess or failure of your Process, as follows:

• 00 - Processes that completed successfully• 04 - Processes that completed successfully and have one minor error such as

an incorrect file disposition• 08 - Processes that did not complete successfully but that have several errors• 12 - Processes with major errors

SUBMITTER This 8-character field contains the userid of the submitted Process.

P/SNODE This 5-character field contains the primary or secondary node name designation,either PNODE or SNODE.

END DATE This 8-character field contains the ending date of the displayed Process,expressed as month, day, and year (MM/DD/YY).

END TIME This 8-character field contains the ending time of the displayed Process,expressed as hours, minutes, and seconds (HH:MM:SS).

Displaying CICS Messages

Displaying Product MessagesUse the MESSAGE DISPLAY screen to view the contents of a message, the software module producing themessage, some details of system action, and suggested response on your part.

Note: The CICS Interface messages use the prefix SCCS to distinguish them from non-CICS IBMConnect:Direct messages.

1. To access the MESSAGE DISPLAY screen, type MD and press ENTER on the PRIMARY MENU screen.(The MD option is completed as part of CICS transaction processing and does not require access to theIBM Connect:Direct DTF API.)

Following is an example.

Chapter 3. CICS Administration and User Guide 145

MESSAGE DISPLAY 06:15:43 node.name MESSAGE ID ==> __________ MODULE ID ==> SHORT TEXT==> LONG TEXT==> ==> ==> ==> ==> ==> ==> ==> ==> ==> PF keys: 1 Help 2 Msg 3 Exit 4 Menu 6 Id

2. To display a message type its 8-character string in the MESSAGE ID field and press ENTER.

The following table describes the system fields for the MESSAGE DISPLAY screen:

Field Description

MODULE ID 64-character field contains the name of the software module that produced themessage.

SHORT TEXT 64-character field contains the short version of the message as it is displayed whensent.

LONG TEXT Fields of twelve 64-character lines contain the long version of the message, withfurther descriptions of system action and suggested responses.

Displaying the Last MessageUse the LAST MESSAGE screen to recall and view the contents of the last message received during yourConnect:Direct for z/OS CICS activities, the software module producing the message, some details ofsystem action, and suggested response on your part.

To access the LAST MESSAGE screen you have the following two options:

• Type M and press ENTER in the CMD field of the SELECT STATISTICS -- SUMMARY TABLE screen. (The Mcommand is completed as part of CICS transaction processing and does not require access to the IBMConnect:Direct DTF API.)

• Press PF2 from any screen that defines PF2, except from the PRIMARY MENU where PF2 is notdisplayed. The last message may have nothing to do with the current screen activities, when you pressPF2.

Following is an example of the LAST MESSAGE screen.

LAST MESSAGE 06:15:43 node.name MESSAGE ID ==> SAFA000I MODULE ID ==> DMSGNON SHORT TEXT==> Connect:Direct signon process completed. LONG TEXT==> Connect:Direct signon processing completed. The user ==> record was found on the Authorization Data Set. The user ==> supplied password was valid. ==> ==> ==> ==> SYSTEM ACTION: Return to invoker with RC=0. ==> ==> ==> RESPONSE: NONE. ==> ==> PF keys: 3 Exit 4 Menu

146 IBM Connect:Direct for z/OS: Documentation

The following table describes the system fields for the LAST MESSAGE screen:

Field Description

HEADER This 41-character field contains the system-generated message identificationinformation and occurs right below the screen title. The HEADER field works inconjunction with the SELECT STATISTICS - SUMMARY TABLE screen and displaysthe current screen upon the selection of the line command M in the CMD field.

MESSAGE ID This 8-character field contains the message identification number.

MODULE ID This 64-character field contains the name of the software module issuing themessage.

SHORT TEXT This 64-character field contains the short version of the message as it is displayedwhen sent.

LONG TEXT This field of 12 lines of 64 characters contains the long version of the message, withfurther descriptions of system action and suggested responses.

Displaying Your CICS User ProfileTo access the USER INQUIRY screen, press PF6 from any screen that defines PF6, except from thePRIMARY MENU, where PF6 is not displayed. Following is an example of the USER INQUIRY screen.

USER INQUIRY 17:45:32 node.name

CICS USERID ==> SYSA CONNECT:DIRECT VERSION ==> VV CONNECT:DIRECT USERID ==> SYSA CONNECT:DIRECT RELEASE ==> RR CICS LUNAME ==> BAN06061 CONNECT:DIRECT MOD-LEVEL ==> MM CICS TERMID ==> 6061 CONNECT:DIRECT NODE ==> CD.ESA13

PRIMARY MENU OPTION AUTH? --------------------- ----- CF COPY FILE YES SB SUBMIT PROCESS YES SP SELECT PROCESS YES SS SELECT STATISTICS YES MD MESSAGE DISPLAY YES SD SIGNON DEFAULTS YES SN CHANGE SIGNON YES

PF keys: 3 Exit 4 Menu

The following table describes the system fields:

Field Description

CICS USERID This 8-character field contains your CICS userid.

CONNECT:DIRECTUSERID

This 8-character field contains your IBM Connect:Direct userid.

CICS LUNAME This 8-character field contains your CICS logical unit name (netname).

CICS TERMID This 4-character field contains your CICS terminal designation.

CONNECT:DIRECTNODE

This 16-character field contains the name of the IBM Connect:Direct node to whichyou are currently signed on.

CONNECT:DIRECTVERSION

This 2-character field contains the version number of the CICS Interface software youare using.

Chapter 3. CICS Administration and User Guide 147

Field Description

CONNECT:DIRECTRELEASE

This 3-character field contains the release number of the CICS Interface software youare using.

CONNECT:DIRECTMOD-LEVEL

This 3-character field contains the modification level number for the CICS Interfacesoftware you are using.

COPYFILE This 3-character field contains YES or NO to show your authorization to perform aCOPY operation.

SUBMIT PROCESS This 3-character field contains YES or NO to show your authorization to submit aProcess.

SELECT PROCESS This 3-character field contains YES or NO to show your authorization to select aProcess.

SELECT STATISTICS This 3-character field contains YES or NO to show your authorization to selectstatistics.

MESSAGE DISPLAY This 3-character field contains YES or NO to show your authorization to displaymessages.

SIGNON DEFAULTS This 3-character field contains YES or NO to show your authorization to update yoursignon defaults record.

SIGNON This 3-character field contains YES or NO to show your authorization to change yoursignon.

CICS Messages and Problem Isolation

Product MessagesThese messages from the system software are arranged in alphabetical order.Activate rejected, node is already active - node name

This message is displayed if you select option A in the field beside an active node.

All values reset from config file

This message is displayed if you press Clear.

All values reset from signon defaults file

This message is displayed if you press CLEAR on the SIGNON DEFAULTS screen.

A printer must be specified in your Signon Defaults in order to use 'P'

This message is displayed if you forgot to type in a printer ID, before you selected option P, and thenpressed Enter.

Auto-return in progress...

This message is displayed after you exited the Connect:Direct for z/OS CICS program, and retypedthe IBM Connect:Direct transaction. The automatic return feature must be enabled before any use,however.

CICS USERID required

This message is displayed if you pressed Enter with a blank screen present or with no CICS USERIDentry present.

Control record successfully updated

This message is displayed after an edit session when you press PF9.

148 IBM Connect:Direct for z/OS: Documentation

DTF NODE NAME required

This message is displayed if you pressed Enter, or PF5, or PF6, with a blank screen.

End of file

This message is displayed when you scroll forward to the bottom of the file through repeated use ofthe PF8 key.

End of file; values read from config file

This message is displayed when you scroll forward to the end of file and then press PF8.

End of file; values read from signon defaults file

This message is displayed if you press PF8 repeatedly and attempt to access data beyond the end offile.

End of node list

This message is displayed if you press PF8 while you are at the bottom of the available node list.

FILENAME and FILETYPE are required

This message is displayed if you pressed Enter on a blank screen, without typing the filename andtype of file.

First page

This message is displayed if you press PF7 repeatedly on a screen with more than one page andattempt to go up past the first page.

Immediate shutdown rejected; interface is shut.

This message is displayed if option I is already selected, and the interface is already inactive.

Immediate shutdown started

This message is displayed if you select option I. The INTERFACE STATUS field changes to INACTIVE.

Interface has been started

This message is displayed if you select option A and press Enter.

Interface is already active

This message is displayed if you select option A, and the interface is already active or in the process ofstarting.

Interface must be active to start monitor.

This message is displayed if you select option M, and the interface is not active. You must selectoption A before option M.

Last Msgid field is blank

This message is displayed if you select the M option, and press Enter, with the LAST MSGID fieldblank.

Last page

This message is displayed if you press PF8 repeatedly on a screen with more than one page andattempt to go down past the last page.

Left page

This message is displayed if you repeatedly press PF10 and attempt to access data past the left edgeof the screen.

Line command invalid

This message is displayed if you select a different line command other than those defined and pressEnter.

Chapter 3. CICS Administration and User Guide 149

M and S are the only valid line commands

This message is displayed, if you select a line command other than those defined in the CMD field andpress Enter.

M is the only valid line command

This message is displayed if you type in a character other than M in the command line and press Enter.

Monitor has been started.

This message is displayed if you select option M.

Monitor is already running.

This message is displayed if option M is already selected and you select option M again.

MYNODE.OS.USERID NODE invalid

This message is displayed if the node name you typed in is not authorized for signon.

NETWORK NODE NAME required

This message is displayed if you press Enter, or PF5, or PF6, with a blank screen present or with theNETWORK NODE NAME field entry blank.

Network node successfully added - node name

This message is displayed when the DTF NODE RECORDS screen has your correct data in the fields,and you press PF5.

Network node successfully deleted - node name

This message is displayed when the DTF NODE RECORDS screen has your correct data in the fields,and you press PF6.

No active work queue entries for node node name

This message is displayed if you select option W, and no active subtasks are in the work queue.

Node activation started, node node name

This message is displayed if you select option A in the field beside an inactive node.

Node has been restarted - node name

This message is displayed in the STATUS ALERT MESSAGE field when the NETWORK NODE RECORDShave been updated to activate a node.

NODE invalid

This message is displayed if the node name you typed in is not authorized for signon.

NODE NUMBER invalid

This message is displayed if you typed in a node number that is not in the list of available nodes andpressed Enter.

NODE NUMBER or NODE NAME required

This message is displayed if you press Enter, with nothing typed in.

NODE required

This message is displayed if you pressed Enter on a blank screen without typing in a node name.

NODE TYPE invalid

This message is displayed if the DTF NODE NAME contains an unacceptable naming convention.

No help available

This message is displayed if you press PF1 while at a screen with no online help facilities available.

150 IBM Connect:Direct for z/OS: Documentation

No password is currently on file

This message is displayed in the IBM Connect:Direct PASSWORD field if you typed an unacceptable orblank IBM Connect:Direct PASSWORD.

Normal shutdown rejected; interface is inactive.

This message is displayed if already select option S, and you select option S again.

Normal shutdown started

This message is displayed if you select option S, press Enter. If you press Enter again, the MONITORTASK NUMBER field changes to NOT RUNNING.

No signed-on users

This message is displayed if the administrative user selected line command T from the USERSTATUS and pressed Enter, thereby terminating the administrative user session. This message is alsodisplayed if you type U from the PRIMARY MENU and no signed-on users of IBM Connect:Direct exist.

No users meeting selection criteria

This message is displayed if a CICS userid is typed in the CICS USERID field that did not match thoseusers logged on. First, check the USER STATUS screen to see who is logged on for a match.

OPTION invalid

This message is displayed if you type in an option other than those defined on the PRIMARY MENU.

OPTION required

This message is displayed if you press Enter, without typing in an option.

Password is on file, but not displayed

This message is displayed if you type a IBM Connect:Direct password that is already in the SIGNONDEFAULT record.

Password is present

This message is displayed if the PASSWORD field on the SIGNON DEFAULTS screen is filled with yourpassword. The PASSWORD field is darkened to maintain security.

Password is absent

This message is displayed if you have not typed your PASSWORD in the field on the SIGNONDEFAULTS screen. As soon as you type the password, the rest of the required data, and press Enter,the message changes to PASSWORD IS PRESENT.

Past end of file - 'Prev' not available

This message is displayed when you scroll backward to the top of the file and then press PF7.

PF key invalid

This message is displayed in the MESSAGE field if you pressed a PF key other than those defined onthe screen.

Press Enter to continue

This message is displayed if you typed in all required data correctly and pressed Enter. This messageindicates your chance to abort the COPY file Process.

PROCESS NAME required

This message is displayed if you pressed Enter without typing in the Process name.

PROCESS NUMBER number

This message is displayed after a successful execution of a COPY file Process, where number is thesystem-generated Process number.

Chapter 3. CICS Administration and User Guide 151

Record cannot be deleted, it is not on file

This message is displayed if you type in the DTF NODE NAME and then press PF6. No match existsbetween the DTF NODE NAME and those specified in the configuration file, and therefore the recordcannot be deleted.

Record cannot be updated, it is not on file

This message is displayed if you type in the DTF NODE NAME and then press PF9. No match existsbetween the DTF NODE NAME and those specified in the configuration file, and therefore the recordcannot be updated.

Record not found; hit any key when ready.

This message is displayed if you type in the DTF NODE NAME and press Enter, but no match exists inthe DTF NODE RECORDS screen.

Right page

This message is displayed if you repeatedly press PF11 and attempt to access data past the right edgeof the screen.

SAFA000I - Connect:Direct signon process completed.

This message is displayed if you signed on successfully.

SCBI190I - Process specified not in process library.

This message is displayed if you typed in a Process name that is not recognized by the system, andpressed Enter. Check the contents of your PROCESS.LIB to determine those available.

SCIA011I - Connect:Direct/DTF not active. Extended Submit Facility now available.

This message is displayed if the DTF is not working under IBM Connect:Direct. ESF is a substitute forthe DTF in this case, but is limited to one Process per user.

SCCS002I - No room available on work queue for this node. The Connect:Direct for CICS work queuefor this DTF node is full.

This message is displayed when the work queue reaches its maximum capacity of tasks. Try yourrequest again at a lower usage time.

SCCS003I - Connect:Direct for CICS monitor is not active.

This message is displayed when the DGAM transaction is not running.

SCCS007I - DTF node not active to Connect:Direct for CICS.

This message is displayed if the node name you typed in is not active in the IBM Connect:Directsystem.

SCCS007I - DTF node not active to Connect:Direct CICS.

This message is displayed if the node name you typed in is not active in the IBM Connect:Directsystem. If you are an administrator, check the NODE STATUS screen.

SCCS008I - Connect:Direct for CICS signon failure.

This message is displayed when a system logic error prevented your Connect:Direct for z/OS CICSsignon.

SCCS009I - Connect:Direct for CICS connection to DTF node is being shut.

This message is displayed when the logical connection from Connect:Direct for z/OS CICS to the DTFnode is being shut down.

SCCS010I - Connect:Direct for CICS has been shut down.

This message is displayed when the Connect:Direct for z/OS CICS interface has been shut down by asystem administrator, without waiting for active requests to complete execution.

152 IBM Connect:Direct for z/OS: Documentation

SCCS011I - Connect:Direct for CICS subtask has been shut.

This message is displayed when the Connect:Direct for z/OS CICS subtask assigned to process yourrequest has been shut down, without waiting for active requests to complete execution.

SCCS013I - Copyfile successfully submitted.

This message is displayed if you typed in all the required data on the SENDING FILE screen andthe RECEIVING FILE screen, and pressed Enter. You are returned to the COPYFILE screen fromthe RECEIVING FILE screen. The message is displayed only when a COPY file Process successfullycompletes under DTF.

SCCS014I - Output limit has been exceeded.

This message is displayed if the total number of lines returned to the DTF node exceeded the limitdefined for the node during a SELECT operation.

SCCS016I - Connect:Direct for CICS connection to DTF node is being shut.

This message is displayed when the logical connection from Connect:Direct for z/OS CICS to the DTFnode is being shut down.

SCCS018I - Request could not be assigned to a subtask.

This message is displayed if you typed in incorrect data or unknown data. The system could not placethe signon request in the work queue assigned to the DTF node for the length of time required tocomplete the signon process. Number of maximum users was exceeded, or incorrect entries in theSIGNON DEFAULTS record caused the failure.

SCCS023I - DTF node now available in ESF mode only.

This message is displayed if the DTF is down.

SENDING DSNAME required

This message is displayed if you pressed Enter, without typed a filename.

Sending or receiving node must equal current node - MYNODE.OS.USERID

This message is displayed if you typed in a different node number from yours in the sending numberfield and pressed Enter.

SESF000I - Process successfully submitted via ESF.

This message is displayed if you typed in all the required data on the SENDING FILE screen andthe RECEIVING FILE screen and pressed Enter. You are returned to the COPYFILE screen from theRECEIVING FILE screen. The message is displayed only when you complete successfully a COPY fileProcess under ESF (when DTF is not working).

Shut immediate started, node node name

This message is displayed if you select option I, and you press Enter on an active node.

Shut normal started, node node name

This message is displayed if you select option N, and you press Enter, on an active node. The STATUSfield changes to INACT, and the REQUEST field changes to SHUTNORM.

Shut rejected; node already inactive - node name

This message is displayed if you select option S and you press Enter on an inactive node.

Signon Defaults successfully updated - userid

This message is displayed if you press PF9 while at the SIGNON DEFAULTS screen.

SOPA000I - Select process command was successful.

This message is displayed if you select option S and press Enter.

Chapter 3. CICS Administration and User Guide 153

SOPA006I - No process(es) found matching the search criteria.

This message is displayed if you typed in values on the SELECT PROCESS screen, pressed Enter, andno match was found.

SOPA011I - One or more processes SELECTed.

This message is displayed if you press Enter without selecting a line command option.

SOPS000I - Select Statistics command successfully completed.

This message is displayed if you type in the correct data on the SELECT STATISTICS screen and pressEnter.

SOPS006I - No statistics were found matching the criteria specified.

This message is displayed if you type in the correct data on the SELECT STATISTICS screen and pressEnter, but there was no Process data in Connect:Direct for z/OS CICS that matched your data.

START DATE invalid

This message is displayed if you typed in a start date that is unrecognizable by Connect:Direct for z/OSCICS.

Start of file

This message is displayed if you scroll back to the top of the file through repeated use of the PF7 key.

Start of file; values read from config file

This message is displayed when the you press PF7 repeatedly to get to the top of the configurationfile, then PF8, and then PF7.

Start of file; values read from signon defaults file

This message is displayed if you press PF7 repeatedly and attempt to access data before thebeginning of the file.

Start of node list

This message is displayed if you press PF7 while you are already at the top of the available node list.

START TIME invalid

This message is displayed if you pressed Enter, with nothing typed in on the screen, or if you typed in astart time that is unrecognizable by Connect:Direct for z/OS CICS and pressed Enter.

UNSUPPORTED FUNCTION

This message is displayed if the CICS Interface is not started or if you typed in a command unknownto the system.

User does not have active work

This message is displayed if you select line commands F or C and no active subtask exists in the USERSTATUS.

USS Command Completed Successfully

This message is displayed when the CICS signon is successful.

Value must be numeric if typed

This message is displayed if you typed in other characters than 0 to 9 and pressed Enter.

Values read from config file * * * * *

This message is displayed if you press PF9. The screen is updated with the values recorded in theconfiguration file.

Note: The following message begins with a variable field and can change as the node names arechanged.

154 IBM Connect:Direct for z/OS: Documentation

node name not NETWORK NODE IN NETMAP specified

This message is displayed if you type in the DTF NODE NAME and then press PF5. No match existsbetween the DTF NODE NAME and those specified in the NETMAP.

You must sign on to CICS before using Connect:Direct for CICS

This message is displayed in the STATUS ALERT MESSAGE field if you attempted to sign on to IBMConnect:Direct before CICS.

Problem IsolationUse the following suggested solutions to software problems when troubleshooting.

DTF Busy MessageThe terminal is clocked when you press a PF key or Enter on a IBM Connect:Direct screen. If theprocessing of the IBM Connect:Direct transaction requires communications with a IBM Connect:Directnode, then your request is put into a CICS WAIT state.

The terminal clock is freed when the CICS Interface handles your request. The CICS Interfaceadministrative function provides an inquiry capability for problem analysis in the event that the clockis not freed. A CICS Interface administrative function exists that aborts any specific IBM Connect:Directcommand that is in progress. This command frees the terminal clock and an error message is returned.

The IBM Connect:Direct request is not cancelled, unless the request is not yet in progress, meaning thatyour request is allowed to complete, but the response is not sent back to you.

You cannot type another IBM Connect:Direct command for the same node until the first requestcompletes (only one command is allowed per user per node at a time).

CICS Transaction ABENDsIf a CICS transaction abends, then you are returned to CICS transaction mode. You can try to retype thetransaction that abended, but you must start over, either on the SIGNON screen or on the PRIMARY MENU(if auto-signon is enabled).

In case the transaction abends while a IBM Connect:Direct command is in process (because of a failure ofthe terminal, or because a CICS operator force-abended his transaction), the same situation occurs.

However, you cannot issue any further IBM Connect:Direct requests until the prior request completes.Completion information from the outstanding request is not returned to you.

Your Terminal Hangs—No ResponseCICS Interface requests are placed in a work queue, with one queue per node. IBM Connect:Directrequests are rejected with a DTF busy error message, when a queue for a node reaches its maximumallowed length. If this condition occurs, contact your system administrator.

Chapter 3. CICS Administration and User Guide 155

156 IBM Connect:Direct for z/OS: Documentation

Chapter 4. Administration Guide

Basic System AdministrativeThe Administrative Options Menu provides access to system administration functions. To access thismenu, do one of the following:

• Select ADMIN from the Primary Options Menu.• Type =ADMIN on any IBM Connect:Direct screen command line and press ENTER.

The following figure is an example of the Administrative Options Menu. To access a function, type thefunction abbreviation on the command line and press ENTER.

Note: Various functions on the Administrative Options Menu may not be available to all users. Access iscontrolled through the User Authorization file.

View Modify Control Delete Secure+ Help------------------------------------------------------------------------------CD.ART Connect:Direct Administrative Options MenuOption ===>

Select one of the following:

ST - View type record ********************* IT - Insert/Update type record * * DT - Delete type record * Today: 08.30.2018 * SU - View user authorization record * Time: 14:05 * IU - Insert/Update user authorization record * UID: EPETE1 * DU - Delete user authorization record * * TS - View Connect:Direct tasks * OPT Enabled * TF - Flush a Connect:Direct task * OPT Part-Enabled * S - Execute Secure Plus Commands * OPT Disabled * MD - Modify Connect:Direct trace characteristics * * C - Enter a native Connect:Direct command ********************* SN - Terminate Connect:Direct ARS - ARS reporting facility NM - View information in the Connect:Direct network map UNM - Update the Connect:Direct network map INQ - Inquire about DTF internal status STAT - Perform statistics functions

Execute Secure Plus Commands option is not displayed, unless you have functional authority forConnect:Direct Secure Plus. See Functional Authority Privileges (specifically the information in BYTE8in the DGA$MFLG macro).

Select the following options from the Connect:Direct Administrative Options Menu.

• To maintain the Type Defaults file with file attribute information used during Process submission, usethe following options.

Option Description

ST Displays the Select Type screen where you can examine a record in the Type file and selectthe output to go to a file, table, or printer.

IT Displays the Insert/Update Type screen where you can add or change a record in the TypeDefaults file.

DT Displays the Delete Type screen where you can remove a record from the Type file.

• To maintain the User Authorization file that controls access to functions, use the following options.

© Copyright IBM Corp. 1993, 2021 157

Option Description

SU Displays the Select User screen where you examine the user profile in the Authorization file.

IU Displays the Insert/Update User screen where you can add a user to the system or changeuser privileges on the system.

DU Displays the Delete User screen where you can remove a user from the Authorization file.

• To select and flush tasks, use the following options:

Option Description

TS Accesses the Select Task screen where you determine the task ID, type, and task number.

TF Displays the Flush Task screen where you can remove a task from the execution queue.

• To perform Connect:Direct Secure Plus functions, use the following options. You must first select theExecute Secure Plus Commands from the Connect:Direct Administrative Options Menu.

Option Description

CR Executes the Certificate Expiration Validation Command on demand to let you see warningsboth for certificates that have expired and will soon expire.

RF Executes the Refresh Secure Plus Environment Command to update the SSL and TLSenvironments after you have changed security-related information.

SA Executes the Connect:Direct Secure Plus Admin Tool and displays the Connect:DirectSecure Plus Admin Tool Main Screen. See the IBM Connect:Direct Secure Plus for z/OSImplementation Guide for more information on using Connect:Direct Secure Plus.

• To initialize traces, suspend and resume sessions, modify initialization parameters, type nativecommands, terminate IBM Connect:Direct, and access ARS, use the following options.

Option Description

MD Displays the Modify Command screen where you can request traces and modify systemfunctions. For information on the MODIFY command and trace and debug settings, see IBMConnect:Direct MODIFY Command. For information on the MODIFY SESSIONS command,see Suspending and Resuming Quiesce and Trace Settings . For information on theMODIFY INITPARMS command, see Modifying Initialization Parameter Settings while IBMConnect:Direct is Running.

C Displays the Native Command screen where you can type and execute any Connect:Directfor z/OS command by providing it in native syntax. For information, see IBM Connect:DirectNative Command Structure .

SN Displays the Stop IBM Connect:Direct screen where you stop the operation of IBMConnect:Direct. For more information, see Stopping IBM Connect:Direct.

ARS Displays the ARS REPORT OPTIONS menu. While IBM Connect:Direct produces statistics,the Activity Reporting System (ARS) gives you access to more information and also providessorting capabilities. For more information, see the IBM Connect:Direct for z/OS FacilitiesGuide.

• To view and maintain the network map and translate TCP/IP names, use the following options.

158 IBM Connect:Direct for z/OS: Documentation

Option Description

NM Displays the Select Network Map screen, where you choose to display or print, the definedIBM Connect:Direct nodes from the network map file and translation of TCP/IP host namesand network addresses. For more information on the SELECT NETMAP command and theSELECT TCPXLT command, see The Network Map in IBM Connect:Direct for z/OS User Guide.

UNM Enables you to update the network map dynamically. For more information, see Updatingthe Netmap through the IUI Interface.

• To inquire about DTF internal status and perform statistics functions, use the following options.

Option Description

INQ Displays the Inquire C:D Internal Status screen, from which you can request informationabout the:

• Statistics archive file directory (see Viewing the Statistics Archive Directory through theIUI Interface)

• IBM Connect:Direct/Plex environment (see “Displaying IBM Connect:Direct/Plex Status”on page 172)

• Statistics logging facility (see Statistics Inquiry through the IUI Interface)• SNMP Trap Table (see INQUIRE SNMP Command Displays the SNMP Trap Table )• TCP Listen Status (see Viewing a TCP Listen Status Report)• Current DEBUG settings (see Displaying DEBUG Settings)• Initialization parameters settings (see Displaying Initialization Parameter Settings)• Module Maintenance History (see “Displaying Module Maintenance History” on page

173 )

STAT Displays the Statistics Command screen from which you can request functions relatedto the Statistics files, such as initiating statistics file pair switching, confirm statistics filearchival, enable statistics recording, and disable statistics recording. For more information,see Retrieving Statistics with the SELECT STATISTICS Command.

IBM Connect:Direct Native Command StructureYou use the Native Command structure to build a more detailed list of parameters than you can fromthe command panels. You can type any IBM Connect:Direct command or series of IBM Connect:Directcommands using the Native Command structure.

To access the Native Command Screen, select option C from the Administrative Options Menu.

Chapter 4. Administration Guide 159

node.name NATIVE COMMAND SCREEN hh:mm CMD ==>

ENTER COMMAND TEXT:

==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________

Observe the following rules when you type your command:

• Start keywords on the next line or break them by a separator (blank or comma).• To use comments on the Native Command Screen, type an asterisk in the first column of the input line.

Typing an asterisk enables you to issue commands without retyping them.• You cannot continuously wrap commands across lines on the Native Command Screen.

A command that creates a temporary file displays the temporary file for you to browse after the commandexecutes.

ExamplesIn the following example, when you press ENTER, you submit the Process called TEST2.

node.name NATIVE COMMAND SCREEN hh:mm CMD ==>

ENTER COMMAND TEXT:

==> SUBMIT PROC=TEST2 _____________________________________________ ==> _______________________________________________________________ ==> *SELECT PROCESS WHERE (PNAME=TEST2) ___________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________

To monitor the progress of TEST2, type an asterisk in column 1 of the first input line (before SUBMIT),delete the asterisk from the third input line (before SELECT), and press ENTER.

You can also submit a Process from the command line. In the following example, the Process TEST2is submitted from the command line. The SELECT PROCESS (line 3) takes place just as in the previousexample. The screen sample follows.

160 IBM Connect:Direct for z/OS: Documentation

node.name NATIVE COMMAND SCREEN hh:mm CMD ==> SUBMIT PROC=TEST2

ENTER COMMAND TEXT:

==>________________________________________________________________ ==> _______________________________________________________________ ==> SELECT PROCESS WHERE (PNAME=TEST2) ___________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________ ==> _______________________________________________________________

Managing TasksIBM Connect:Direct tasks perform and manage work in a DTF. This section describes how to display taskinformation and remove (flush) tasks.

The following table lists the IBM Connect:Direct tasks and their functions:

Type Task Function

System Master (M) Controls the dispatching and logon processing for the DTF

Timer (T) Performs timer services for the master task and Process-related timer functions

Operator interface (C) Enables you to communicate to the DTF through the operatorconsole

Extended Submit FacilityScan (W)

Scans the TCQ at predefined intervals and moves submittedProcesses that are not on the current processing queue (PCQ)to the PCQ

System Open/Close Task (O) Manages the VTAM ACB open/close and TPEND exit

TCP Task (U) Monitors incoming TCP/IP session requests

XCF Communication (Q) Manages communications between Manager and Servers in aIBM Connect:Direct/Plex

TCP API Task (D) Monitors incoming TCP/IP IBM Connect:Direct API sessionrequests

LOGON (L) Reserved for use during logon processing

Statistics (A) Controls status logging

Session Creation TCA (F) Manages Processes and tasks

Statistics Archive SubmitTask (Z)

Submits the Statistics File Archive Process

CTCA Server Task (Y) Manages the CTCA tasks

IBM Connect:Direct/PlexQueue Manager Task (Q)

Manages the VTAM ACB open/close and TPEND exit

User PNODE Task (P) Manages the work related to a request that initiated thecurrent session

Chapter 4. Administration Guide 161

Type Task Function

SNODE Task (S) Manages the work related to a partner PNODE task

IUI Task (I) Manages the requests from a session with an IUI user

Background (Batch) Task(B)

Manages the request from a batch user

Displaying Task StatusUse the SELECT TASK command to select and display the status of IBM Connect:Direct tasks. It has thefollowing format and parameters.

Label Command Parameters

(optional) SELect TASK PRint | Operator Table | DISplay

WHERE (SERVER = server name)

The required SELECT TASK parameters are:

Parameter Description

PRint | Operator Table |DISplay

PRint specifies the command is output in hard copy to a printer.

TABLE specifies the command is output to a table.

DISplay specifies the command is output to the screen.

The optional SELECT TASK parameters are:

Parameter Description

WHERE(SERVER =server name)

This parameter specifies the name of the IBM Connect:Direct/Plex memberwhere the SELECT TASK command is performed. The server name parameteris the 1–8 character name assigned to a IBM Connect:Direct/Server by theCDPLEX.SERVER initialization parameter.

This parameter only applies to a IBM Connect:Direct/Plex environment. If thisparameter is not specified in a IBM Connect:Direct/Plex environment, the SELECTTASK is performed on the IBM Connect:Direct/Manager.

ExamplesThe following SELECT TASK command example sends output to the log printer:

SEL TASK PRINT

The following SELECT TASK example is performed on a IBM Connect:Direct/Server named SERVER3 andsends the output to your terminal in operator table format.

SEL TASK O WHERE(SERVER=SERVER3)

Selecting a Task through the Batch InterfaceTo use the SELECT TASK command from the batch interface:

1. Place your commands in a batch job stream.2. Submit the job while IBM Connect:Direct is running.

162 IBM Connect:Direct for z/OS: Documentation

3. Verify your results.

Selecting a Task through the IUIYou must select the appropriate output for the SELECT TASK report. You can either display (in report oroperator table format) or print the report.

1. Select option TS from the Administrative Options Menu.

The SELECT TASK screen is displayed.

node.name SELECT TASK hh:mm CMD ==> CMD: OPR CMD: O ... OPERATOR TABLE P ... PRINT REPORT D ... DISPLAY REPORT SERVER => ________

2. Select one of the following display types.

Option Description

D Displays the report on your screen and is captured in the TMPDSN specified in theSIGNON defaults of the user.

O or OPR Displays the report to your screen in the operator table format.

P Sends the report to a printer.

Note: If you are running in a IBM Connect:Direct/Plex environment, type the member name on whichyou want to perform the SELECT TASK in the SERVER field. If you leave this field blank in a IBMConnect:Direct/Plex environment, the SELECT TASK is performed on the IBM Connect:Direct/Manager.If you are running in a IBM Connect:Direct/Stand-alone Server environment, leave this field blank.

3. Press ENTER.

• If you selected Display from the Select Task screen, the following screen is displayed:

BROWSE--XXXXXXXX.XXXXXXX.XXXXX.XXXXXX.XXXXX--LINE 00000000 COL 001 080COMMAND ===> SCROLL ===> CSR******************************* TOP OF DATA *************************=========================================================== SELECT TASK for C:D/Plex Manager=========================================================== TASK TASK XMIT PNAME/ ID NUM STATE STATE PNUM___________________________________________________________ M 001 INACTIVE___________________________________________________________ T 002 TIMER___________________________________________________________ A 003 INACTIVE___________________________________________________________ Z 004 INACTIVE___________________________________________________________ C 005 MISC I/O___________________________________________________________ F 006 INACTIVE___________________________________________________________ U 007 SUBTASK TCP MAIN TAS

• If you selected the operator table format, the following screen is displayed:

Chapter 4. Administration Guide 163

-------------------------------OPERATOR TABLE-------------- Row 1 to 20 of 22==> SCROLL ===> PAGEOPTION TID TASKNO STATE SUB-STATE PNAM/UID PNUM------------------------------------------------------------------------------- M 1 INACTIVE T 2 TIMER A 3 INACTIVE Z 4 INACTIVE C 5 MISC I/O F 6 INACTIVE U 7 SUBTASK TCP MAIN TAS U 8 ST RUNNG TCP ACCEPT D 9 SUBTASK TCP MAIN TAS D 10 API RUN TCP ACCEPT O 11 INACTIVE I 13 VTAM I/O RECEIVE SJONES2 I 14 RUNNING BSMITH1 W 12 TIMER Q 37 WAIT4WRK Q 38 WAIT4WRK Q 39 WAIT4WRK Q 40 WAIT4WRK Q 41 WAIT4WRK Q 73 WAIT4WRK

You can perform the following operations from the Operator Table:

• Type F next to the task ID to flush and suspend nonsystem tasks.• Type P to suspend a task.

Refresh the OPERATOR TABLE screen by typing Q line and pressing ENTER.

Removing Tasks from ExecutionUse the FLUSH TASK command to remove a task from execution. Identify the task by its task number. Youcannot flush system or IUI tasks.

Note: Only use the FLUSH TASK command if you cannot flush the Process using the FLUSH PROCESScommand.

The FLUSH TASK command has the following format and associated parameters. Required parameters arein bold print.

Label Command Parameters

(optional) FLush TASK WHERE (

TASK = (tasknumber | (list),

SERVER = server name

)

FORCE

The required FLUSH TASK parameter is:

164 IBM Connect:Direct for z/OS: Documentation

Parameter Description

WHERE (TASK = (tasknumber | (list),SERVER=server name)

(tasknumber | (list) specifies the tasks to flush either by tasknumber or a list of task numbers.

This parameter is required. SERVER=server name specifies thename of the IBM Connect:Direct server where the FLUSH TASK isperformed. The server name parameter is the 1–8 character nameassigned to a IBM Connect:Direct/Server by the CDPLEX.SERVERinitialization parameter. This parameter is only valid in a IBMConnect:Direct/Plex environment. If you omit this parameterin a IBM Connect:Direct/Plex environment, the FLUSH TASK isperformed on a IBM Connect:Direct/Manager.

The optional FLUSH TASK parameter is:

Parameter Description

FORCE Specifies that flush task is forced. Do not use the FORCE parameterwhen the task is executing on a LU6.2 session. The session terminatesimmediately and statistics are not exchanged between the two nodes.

If you do not specify the FORCE option for the FLUSH TASK command,then an indicator notifies the program executing on behalf of the taskthat a FLUSH TASK command was issued for that task. If that programis not in control (for example, if it is waiting on a request outside of IBMConnect:Direct to complete), then it does not recognize the FLUSH TASKindicator, and the task is not flushed; otherwise, the program recognizesfor the FLUSH TASK indicator and takes the appropriate action.

When you specify the FORCE option, then the action taken depends onthe STATE and SUBSTATE of the task for which you issued the FORCEFLUSH. See Connect:Direct Process Language for the actions taken forthe specific STATE and SUBSTATE.

Note: Use the SELECT TASK command to determine the STATE andSUBSTATE of the task.

ExamplesThe following example shows the FLUSH TASK command force flushing three tasks:

FLUSH TASK WHERE (TASK=(100,105,120)) FORCE

The following example shows the FLUSH TASK command flushing a task running on a IBM Connect:Direct/Server named OSGOOD:

FLUSH TASK WHERE (TASK=9,SERVER=OSGOOD)

Removing Tasks from Execution through the Batch InterfaceTo use the FLUSH TASK command from the batch interface, perform the following steps:

1. Place your commands in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

Chapter 4. Administration Guide 165

Removing Tasks from Execution through the IUIRefer to the example of the SELECT TASK Operator Table for information about how to flush a task usingthe Operator Table.

To flush a task using the Flush a Task screen:

1. Select option TF from the Administrative Options Menu to access the Flush a Task screen.

node.name FLUSH A TASK hh:mm CMD ==>

SERVER ==> ________

TASK NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______ ==> ______ ==> ______ ==> ______ ==> ______

FORCE: ('Y'-YES, 'N'-NO) FORCE FLUSH A TASK ON A LU 6.2 SESSION MAY ==> _ TERMINATE THE SESSION IMMEDIATELY AND NO STATISTICS OF THE TASK WILL BE EXCHANGED

2. If you are running in a IBM Connect:Direct/Plex environment, type the IBM Connect:Direct/Plex servername. If you leave this field blank, the Flush Task is performed on the IBM Connect:Direct Manager.

Leave this field blank if you are running in a IBM Connect:Direct/Stand-alone Server.3. Type the numbers of the tasks you want to flush.4. In the FORCE field, type Y to force the flush. Type N if you do not want to force the flush. The default is

N.

A list of the requested tasks is displayed to indicate a successful flush.

Connect:Direct Secure Plus CommandsWhen you select the Execute Connect:Direct Secure Plus Commands on the Connect:DirectAdministrative Options Menu, the following screen is displayed:

CD.ART Execute Secure Plus Commands 14:02CMD ==>

CR - Certificate Expiration Validation Command ********************* RF - Refresh Secure Plus Environment Command * * SA - Secure Plus Admin Tool * Today: 08.30.2018 * * Time: 14:02 * * UID: EPETE1 * * * * OPT Enabled * * OPT Disabled * * * *********************

Certificate Validity Check Used by Connect:Direct Secure PlusTo check the validity of certificates using Connect:Direct Secure Plus, define the following initializationparameters:

• SECURE.DSN - the name of the parameter file• CHECK.CERT.EXPIRE to perform a certificate validation check• CHECK.CERT.EXPIRE.TIME to perform certificate validation checks• CHECK.CERT.EXPIRE.WARNING.DAYS to indicate how many days before certificate expiration to issue a

warning message

After certificate validation check is enabled, IBM Connect:Direct automatically monitors the status of thecertificates as specified and whenever IBM Connect:Direct and Connect:Direct Secure Plus are initialized.

166 IBM Connect:Direct for z/OS: Documentation

When the certificate validation checks are performed, IBM Connect:Direct verifies the label name andnode name of all certificates in the Connect:Direct Secure Plus parameter file. After verifying all trustedcertificates in the key store, IBM Connect:Direct reads and validates each individual certificate label.When a certificate expires, IBM Connect:Direct displays a CSPA601E error message indicating whichcertificate expired so that you can take appropriate action to generate or obtain a new certificate. Whena certificate is soon to expire, IBM Connect:Direct displays a CSPA600W warning message indicating thespecific certificate and the date it will expire.

In addition to issuing messages, IBM Connect:Direct generates statistic records to document the statusof the certificate and which node name the certificate is defined for. You can use IBM® Control Centeror the SELECT STATS command to audit the certificates and nodes that need attention. On the SELECTSTATISTICS panel, type Y in the CHANGE EXTENDED OPTS field, and then specify CX as a RECORD TYPEon the SELECT STATISTICS EXTENDED OPTIONS panel.

Note: If IBM Connect:Direct cannot validate the contents of the Connect:Direct Secure Plus parameterfile, it displays a CSPA607W message indicating that it could not retrieve the necessary information for aparticular certificate. Make sure that the certificate exists along with the correct label name—note that thelabel is case-sensitive and must match exactly.

Note that expiration dates in certificates include both a date and time. IBM Connect:Direct uses bothdate and time to validate the exact expiration period when checking a certificate's validity. For example,if the certificate is set to expire on 12/31/2010 at 10:00:00 and the validation check is performed on12/01/2010 at 09:00:00 with CHECK.CERT.EXPIRE.WARN.DAYS=30, this certificate will not be flaggedwith a warning message until a check is performed after 10:00:00 on 12/01/2010.

The Certificate Expiration Validation CommandTo perform a certificate validation check upon demand, select the CR option, Execute CertificateExpiration Validation Command, when the Execute Secure Plus Commands menu is displayed.

IBM Connect:Direct displays any warning or error messages related to certificates should such a conditionexist.

A TLS/SSL Environment RefreshWhen you update security-related information effecting the SSL/TLS environment or database, such asupdating the path to the key database or key ring or a certificate’s label, use the Execute Refresh SecurePlus Environment Command. By updating the SSL and TLS environment, you ensure that all changes cantake effect immediately. To execute this on-demand command, type RF and press Enter when the ExecuteSecure Plus Commands menu is displayed.

Chapter 4. Administration Guide 167

Connect:Direct Secure Plus DisplayTo display the Connect:Direct Secure Plus Admin Tool: Main Screen when the Execute Secure PlusCommands menu is displayed, type SA and press Enter.

File Edit Help _____________________________________________________________________________ CD.ZOS.NODE Secure+ Admin Tool: Main Screen Row 1 of 7 Option ===> __________________________________________________ Scroll CSR Table Line Commands are: U Update node H View History D Delete node I Insert node V View node Node Filter : *_______________ Secure+ External Client LC Node Name Type Protocol Override Encryption Auth Auth -- ---------------- ---- -------- -------- ---------- -------- -------- __ .CLIENT R * N * * * __ .EASERVER R TLSV10 N * N * __ .PASSWORD R Disabled * * * * __ CD.UNIX.NODE R TLSV10 * * * * __ CD.UNIX.NODE2 R TLSV12 * * * * __ CD.ZOS.NODE L Disabled Y N N N __ CD.ZOS.NODE2 R * * * * * ********************************* BOTTOM OF DATA ****************************

Displaying Initialization Parameter SettingsUse the INQUIRE INITPARM command to view the current global and local initialization parametersettings.

The INQUIRE INITPARM command has the following format and parameter.

Label Command Parameter

(optional) INQuire INITparm WHERE (SERVER=server name)

The INQUIRE INITPARM parameter is:

Parameter Description

WHERE(SERVER=servername)

This parameter is optional. This parameter specifies the IBM Connect:Direct/Plex server initialization parameters you want to view. The server nameparameter is the 1–8 character name assigned to a IBM Connect:Direct/Server by the CDPLEX.SERVER initialization parameter. If you do not specifythis parameter, the IBM Connect:Direct/Manager initialization parameters aredisplayed. You do not need this parameter for a IBM Connect:Direct/Stand-alone Server.

Sample ReportThe following figure shows a partial sample report.

168 IBM Connect:Direct for z/OS: Documentation

==============================================================================node.name *INQUIRE INITPARM* DATE: mm.dd.yyyy TIME: hh:mm:ss C:D/Plex *** MANAGER ** in Group SDWGRP==============================================================================ABEND.CODES.NODUMP => (SX37 SX13 U0728 SXD9 S9FC)ABEND.RUNTASK => ABEND.CODES.NODUMPALLOC.CODES => (020C 0210 0218 0220 0234)ALLOC.RETRIES => 3ALLOC.WAIT => 00:00:30ALLOCATION.EXIT =>CDPLEX => YesCKPT => 0CKPT.DAYS => 4CKPT.MODE => (RECORD BLOCK PDS NOPDS VSAM VSAM)CTCA => NoDATEFORM => MDYDEBUG => '00003001'DESC.CRIT => (2)TBD

Using the INQUIRE INITPARM Command from the Batch InterfaceTo use the INQUIRE INITPARM command from the batch interface:

1. Place your commands in a batch job stream.2. Submit the job while IBM Connect:Direct is running.

Note: You must set the fifth character of the DGADBATC output parameter specification to Y to printthe result of the command that is in the temporary data set.

3. Verify the results.

Issuing the INQUIRE INITPARM Command through the IUITo display the DTF initialization parameters from the IUI:

1. Select option INQ from the Administrative Options Menu.

The Inquire DTF Internal Status screen is displayed.2. If you are running in a IBM Connect:Direct/Plex environment and want to view the initialization

parameters of a IBM Connect:Direct/Server, type the server name in the Server field. If you wantto view the initialization parameters of a IBM Connect:Direct/Manager, leave the Server field blank.

If you are running in a IBM Connect:Direct/Stand-alone Server, leave this field blank.3. Select the IPRM option.4. Press ENTER.

The current DTF initialization parameter settings are displayed.

Modifying Initialization Parameter Settings while IBM Connect:Direct isRunningYou can update certain initialization parameters in the initialization parameter member, and then usethe MODIFY INITPARMS command to update IBM Connect:Direct with the new initialization parametersettings without restarting, using one of the following methods:

• Using the MODIFY INITPARMS Command from the Batch Interface• Issuing the MODIFY INITPARMS Command through the IUI• Performing Configuration Management of Initparms through Control Center. For more information, refer

to the documentation for Control Center.

You cannot update local initialization parameters with the MODIFY INITPARMS command using the firsttwo methods listed above but you can using Control Center.

Chapter 4. Administration Guide 169

To ensure continuity in operation, create backup copies of the global and local initialization parametermembers to use if IBM Connect:Direct cannot initialize after initparm updates. For information, seeBacking up the Global and Local Initialization Parameter Files.

The following list contains the initialization parameters that you can update while IBM Connect:Direct isrunning:

Note: The MODIFY INITPARMS command updates parameters in the following list, after all parameters(global and local) are parsed for correct syntax. Since the MODIFY INITPARMS command reads the entireglobal initialization parameter member (and local INITPARM members), the entire global initializationparameter member is used for the update (along with local INITPARM members). Therefore, you cannotupdate individual parameters with the MODIFY INITPARMS command.

ABEND.CODES.NODUMP ABEND.RUNTASK ALLOC.CODES

ALLOC.RETRIES ALLOC.WAIT CDPLEX.WLM.GOAL

CHECK.CERT.EXPIRE CHECK.CERT.EXPIRE.TIME CHECK.CERT.EXPIRE.WARN.DAYS

CKPT CKPT.DAYS CKPT.MODE

COMPRESS.EXT COMPRESS.NEGO.FAIL COMPRESS.NETMAP.OVERRIDE

COMPRESS.NETMAP.STD CRC DESC.CRIT

DESC.NORM DESC.TAPE ECZ.COMPRESSION.LEVEL

ECZ.MEMORY.LEVEL ECZ.WINDOWSIZE ESF.WAIT

EXPDT GDGALLOC GDGENQ

INVOKE.ALLOC.EXIT INVOKE.ALLOC.EXIT.ON.RESTART

MAX.AGE

MAX.AGE.TOD MAXRETRIES MAXSTGIO

MULTI.COPY.STAT.RCD NETMAP.CHECK.ON.CALL PDSE.SHARING

PDSENQ PRTYDEF REQUEUE

RESET.ORIGIN.ON.SUBMIT REUSE.SESSIONS ROUTCDE.CRIT

ROUTCDE.NORM ROUTCDE.TAPE RUNTASK.RESTART

SNMP SNMP.DSN SNMP.MANAGER.ADDR

SNMP.MANAGER.PORTNUM STAT.EXCLUDE SYSOUT

TAPE.PREMOUNT TCP.API.TIMER TCP.CONNECT.TIMEOUT

TCQ.THRESHOLD THIRD.DISP.DELETE TRANS.SUBPAS

WTMESSAGE WTRETRIES ZEDC

ZEDC.EXCLUDE ZFBA ZIIP.EXTCOMP.DATASIZE.THRESHOLD

The MODIFY INITPARMS command has the following format.

Label Command Parameter

(optional) MODify INITparms

170 IBM Connect:Direct for z/OS: Documentation

This command has no parameters.

Using the MODIFY INITPARMS Command from the Batch InterfaceTo use the MODIFY INITPARMS command features from the batch interface: 1. 2.

1. Update the initialization parameters in the initialization parameter data set.2. Place the MODIFY INITPARMS command in a batch job stream.3. Submit the job while IBM Connect:Direct is running. A message is displayed indicating the results of

the refresh action.

Note: You must set the fifth character of the DGADBATC output parameter specification to Y to printthe result of the command that is in the temporary data set.

Issuing the MODIFY INITPARMS Command through the IUITo use the MODIFY INITPARMS command features through the IUI:

1. Update the initialization parameters in the initialization parameter data set.2. Request option MD from the Connect:Direct Administrative Options Menu to access the MODIFY

COMMAND screen.

node.name MODIFY COMMAND 14:34 CMD ==>

Server ==> ________ 00000000 (Current DEBUG Settings) MODIFY DEBUG ==> ________ (nnnnnnnn) MODIFY BITS.ON ==> ________ (nnnnnnnn) MODIFY BITS.OFF ==> ________ (nnnnnnnn) MODIFY DDNAME ==> ___________ (ddname,nn) MODIFY CLOSE ==> ________ (ddname) MODIFY MODDIR.TRACE ==> ___ (YES) MODIFY DYN ==> ____________________________________________________________ MODIFY SESSIONS ==> _ (Quiesce or Resume) NODE ==> ________________ MODIFY NODE.TRACE.ON ==> ( ________________ ________ ) MODIFY NODE.TRACE.OFF ==> ________________ MODIFY NODES ==> ___ (YES) MODIFY INITPARMS ==> ___ (YES) MODIFY ZIIP ==> _________ (ALL NONE EXTCOMP SSLTLS PROJECT) MODIFY ZFBA ==> ___(YES or NO)

3. Type YES in the MODIFY INITPARMS field.4. Press ENTER. A report is displayed indicating the results of the action.5. Review the report and perform any corrections if necessary.6. Press ENTER to clear the report.

Repeat the procedure if you updated the initialization parameter data set.

Backing up the Global and Local Initialization Parameter FilesControl Center has the ability to configure global initialization parameters for stand-alone IBMConnect:Direct servers and local initialization parameters for members of a IBM Connect:Direct/Plexenvironment. As part of the possible changes, the original INITPARM member is overwritten with theupdates Control Center makes.

You can save a copy of the global initialization parameter file and local initialization parameter files usingthe INITPARM.BACKUP and CDPLEX.INITPARM.BACKUP initialization parameters. These backup filesprotect against inappropriate or failed updates from Control Center or other facilities capable of updatinginitialization parameters. IBM Connect:Direct will use these members to complete a backout of failedupdates. This also provides you with the ability to manually back out using the specified backup memberswhich contain the last set of initialization parameters used to successfully start IBM Connect:Direct.

Note: If you commented out the members names for the backup initialization parameters, specify newnames.

Chapter 4. Administration Guide 171

1. Specify the name of the backup member using the global initialization parameter, INITPARM.BACKUP= member. In a IBM Connect:Direct/Plex environment, you also specify the local initializationparameter, CDPLEX.INITPARM.BACKUP = member for the IBM Connect:Direct Plex/Manager and eachIBM Connect:Direct/Plex server.

2. Start Connect:Direct for z/OS.

When IBM Connect:Direct initializes successfully, it places a copy of the initialization parametermember in the backup member specified in the INITPARM.BACKUP parameter (and does the samething for each IBM Connect:Direct/Plex-related backup parameter). If ISPF STATS are ON for the PDS,the statistics for the initparms are also copied to the backup member. If ISPF STATS are not ON, thebackup member will have ISPF statistics generated based on the current date and time.

Space Requirements for Using the Backup FeatureThe PDS containing the initialization parameters must have enough directory and disk space for thefollowing items:

• The backup members for the global initialization parameter file and local initialization parameter files• Changes to the global and local initialization parameters• ISPF formatted statistics

If the initparm PDS runs out of space, an Sx37 (or similar) ABEND occurs and the system attempts to backout the changes by copying the initparm backup file (including the ISPF STAT information). To recoverspace inside the PDS, compress the PDS prior to starting IBM Connect:Direct.

Manually Backing Out or RestoringIn the event a manual backout or restore of the original initialization parameters is required, follow thisprocedure:

1. Restore the damaged global initialization parameter member using the backup global initializationparameter member. Do the same thing for the backup initialization parameter members for all IBMConnect:Direct/Plex members.

2. Start Connect:Direct for z/OS.

Displaying IBM Connect:Direct/Plex StatusThe INQUIRE CDPLEX command displays IBM Connect:Direct/Plex status information. It has thefollowing format.

Label Command Parameter

(optional) INQuire CDPLEX

The INQUIRE CDPLEX command has no parameters.

ExampleThe following figure shows a partial sample report.

======================================================================Inquire CDPLEX mm.dd.yyyy hh:mm:ss======================================================================XCF Group Name : TPXCFGRP When Activated : mm.dd.yyyy hh:mm:ssSYSPLEX Sys Name : CSGB JOB/STC Name : CD$MGRActive Servers : 1 Maximum Servers : 32Server : SERVER1 When Activated : mm.dd.yyyy hh:mm:ssSYSPLEX Sys Name : CSGB JOB/STC Name : CD$SRV1Active Processes : 0 Maximum Processes : 250Server Supports : CTCA SNA IPv4Server PLEXCLASSES:(A B 1 * )

172 IBM Connect:Direct for z/OS: Documentation

Using the INQUIRE CDPLEX Command from the Batch Interface1. Place your command in a batch job stream.2. Submit the job while IBM Connect:Direct is running.

A report is displayed.

Note: You must set the fifth character of the DGADBATC output parameter specification to a Y to printthe result of the command that is in the temporary data set.

Issuing the INQUIRE CDPLEX Command through the IUI1. Select option INQ from the Administrative Options Menu. The Inquire DTF Internal Status screen is

displayed.2. Select the IPLX option.3. Press ENTER.

A report is displayed.

Displaying Module Maintenance HistoryUse the INQUIRE MAINT command to automatically trace and list modules maintenance history of aConnect:Direct server.

The INQUIRE MAINT command has the following format and parameter.

Label Command Parameter

(optional) INQuire MAINT WHERE (SERVER=server name)

The INQUIRE MAINT parameter is:

Parameter Description

WHERE(SERVER=servername)

This parameter is optional. This parameter specifies the IBM Connect:Direct/Plex server module maintenance history you want to view. The server nameparameter is the 1–8 character name assigned to a IBM Connect:Direct/Serverby the CDPLEX.SERVER initialization parameter. If you do not specify thisparameter, the IBM Connect:Direct/Manager maintenance history is displayed.You do not need this parameter for a IBM Connect:Direct/Stand-alone Server.

Sample ReportThe following figure shows a partial sample report.

Chapter 4. Administration Guide 173

======================================================================CDZOSA.SKUMA1 ** INQ MAINT ** DATE: 04.17.2020 TIME: 11:25:51SYSTEM INITIALIZED ----------------------- 04.17.2020 05:40:43---------------------------------------------------------------------- - PTF MODULE MAINTENANCE - ** Base Release Date =04/06/20 **======================================================================

DGADIMNT EP=980DFEC8 SIZE=00001138 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DGADNMPR EP=97FC5028 SIZE=00000260 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMABMB EP=97DA9000 SIZE=00006000 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMADDUSR EP=97DBF320 SIZE=00001CE0 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMAMF EP=97DC6CC0 SIZE=00001340 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCBCOPY EP=97E53000 SIZE=00011000 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCBDIR EP=9809DA88 SIZE=00000578 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCBGOTO EP=97DC64C8 SIZE=000007F8 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCBIF EP=97E64D30 SIZE=000012D0 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCBPEND EP=97E17170 SIZE=00000CE0 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCBRJRT EP=97E80000 SIZE=00004000 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCBSUBM EP=97E2B000 SIZE=00028000 ID=V6R01M00P00.0000 04/06/20 13.03 PTF R000000DMCERTCK EP=97ED5450 SIZE=00000BB0 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCHGPRC EP=97DCB000 SIZE=00009000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCNOSMG EP=97EDC7E8 SIZE=00000818 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCONATX EP=980AF000 SIZE=00002000 ID=V6R01M00P00.0000 04/06/20 13.02 PTF R000000DMCONERR EP=97BD0718 SIZE=00000328 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCONINT EP=97BE6000 SIZE=00006000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCONLOG EP=97D94000 SIZE=00015000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCONLOX EP=980B1000 SIZE=00012000 ID=V6R01M00P00.0000 04/06/20 13.02 PTF R000000DMCONLSX EP=0002F558 SIZE=00001AA8 ID=V6R01M00P00.0000 04/06/20 13.02 PTF R000000DMCONLU6 EP=98029000 SIZE=00005000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCONNSX EP=00031000 SIZE=00003000 ID=V6R01M00P00.0000 04/06/20 13.02 PTF R000000DMCONSCX EP=980C3000 SIZE=0000A000 ID=V6R01M00P00.0000 04/06/20 13.02 PTF R000000DMCONSRV EP=97D8F000 SIZE=00005000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCOPYRT EP=97CA2000 SIZE=0007B000 ID= DMGCPCPY EP=17CA2000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000 DMGCPDBC EP=17CA9900 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000 DMGCPMIS EP=17CABC08 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000 DMGCPPDS EP=17CBA068 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000 DMGCPRCV EP=17CC0560 ID=V6R01M00P00.0000 04/06/20 13.05 PTF R000000 DMGCPSND EP=17CC9B10 ID=V6R01M00P00.0000 04/06/20 13.05 PTF R000000DMCTCASM EP=98064000 SIZE=00002000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCTCASS EP=98066000 SIZE=00002000 ID=V6R01M00P00.0000 04/06/20 13.04 PTF R000000DMCXSUBM EP=00035650 SIZE=000009B0 ID=V6R01M00P00.0000 01/07/20 02.38 PTF R000000

Using the INQUIRE MAINT Command from the Batch Interface

1. Place your command in a batch job stream.2. Submit the job while IBM Connect:Direct is running.

A report is generated in DMPRINT DD of executed BATCH JOB .

Note: You must set the fifth character of the DGADBATC output parameter specification to a Y to printthe result of the command that is in the temporary data set.

Issuing the INQUIRE MAINT Command through the IUI

1. Select option INQ from the Administrative Options Menu. The Inquire DTF Internal Status screen isdisplayed.

2. Select the IMNT option.3. Press ENTER.

A report is displayed.

Using the Native Command Screen

1. To access the Native Command Screen, select option C from the Administrative Options Menu.2. Enter the INQUIRE MAINT command.3. Press ENTER.

174 IBM Connect:Direct for z/OS: Documentation

A report is displayed.

Using Spool Transfer Interface

1. Issue the following command against a job whose maintenance history you'd like to display.

/F <CD SERVER JOB NAME>, CMD INQUIRE MAINT

2. Press ENTER.A report is displayed.

A report is generated and appended to JESMSGLG DD of JOB mentioned in CMD.

Stopping IBM Connect:DirectThe STOP CD command stops IBM Connect:Direct through one of five types of shutdowns:

• Force• Immediate• Step• Quiesce• Run Task Immediate

This command is usually used for system maintenance.

If you are running IBM Connect:Direct/Plex, shut down the IBM Connect:Direct/Manager, the individualIBM Connect:Direct/Servers or the IBM Connect:Direct/Plex environment. Specify if the extendedrecovery standby system processes the work performed by the system being shut down.

The STOP CD command has the following format and parameters.

Label Command Parameters

(optional) STOP CD [Force | Immediate | Quiesce | Runtaskimm | Step]

[CDPLEX | WHERE (SERVER=server name)| MANAGER]

RECOVER

The parameters for the STOP CD command are:

Parameter Description

Force Stops IBM Connect:Direct through a user U4082 ABEND, and produces a dump. Use thisoption only when problems occur.

Immediate Terminates all active transmissions immediately after any executing Run Task Processescomplete. IBM Connect:Direct writes the statistics record, closes the files, and shuts down.All Processes resume execution when IBM Connect:Direct is reinitialized. If a Process is setfor checkpointing and IBM Connect:Direct stops with this parameter, IBM Connect:Directstarts from the last checkpoint and resumes transferring data when the Process resumes.IMMEDIATE is the default.

Note: You can change how the Immediate parameter interprets the shutdown commandby using the IMMEDIATE.SHUTDOWN initialization parameter. If IMMEDIATE.SHUTDOWN=I(the default), an immediate shutdown functions as described in the preceding paragraph.However, if IMMEDIATE.SHUTDOWN=R, an immediate shutdown functions as a runtaskimmshutdown, terminating any executing Run Task Processes before shutting down IBMConnect:Direct.

Refer to IMMEDIATE.SHUTDOWN = I | R | (I, nnn | 60) | (R, nnn | 60) for more information.

Chapter 4. Administration Guide 175

Parameter Description

Quiesce Enables all active transmissions to run until all executing Process steps complete. No newtransmissions are started, and no additional Processes are accepted. All interactive sessionsare terminated except for the issuer of the STOP CD command. All active Processes mustcomplete and then you must sign off before IBM Connect:Direct stops.

Runtaskimm Terminates any Run Task Processes before stopping IBM Connect:Direct. After the Processesare terminated, IBM Connect:Direct writes the statistics record, closes the files, and shutsdown. This parameter is provided because the Immediate parameter does not terminatea Run Task until it reaches an interrupt point, such as a checkpoint. A long-running RunTask could delay IBM Connect:Direct shutdown until it completes. When IBM Connect:Directrestarts, if the RUNTASK.RESTART initialization parameter is YES, the checkpoint records forthe terminated Run Task restart the Run Task.

Step Enables active transmissions to run until the current step of each executing Process finishes.IBM Connect:Direct then writes the statistics records, closes the files, and shuts down. AllProcesses resume execution when IBM Connect:Direct is reinitialized.

CDPLEX Shuts down the entire IBM Connect:Direct/Plex environment. You cannot use this parameterin a IBM Connect:Direct/Stand-alone Server.

WHERE(SERVER=servername)

Specifies which IBM Connect:Direct/Server in a IBM Connect:Direct/Plex environment toshut down. The server name parameter is the 1–8 character name assigned to a IBMConnect:Direct/Server by the CDPLEX.SERVER initialization parameter. You cannot use thisparameter in a IBM Connect:Direct/Stand-alone Server.

Use this parameter if you only want to shut down a particular IBM Connect:Direct/Server,but leave the rest of the IBM Connect:Direct/Plex environment running. (Use the INQUIRECDPLEX command described in “Displaying IBM Connect:Direct/Plex Status” on page 172 tofind the name of a server.)

Note: When you shut down a IBM Connect:Direct/Plex environment, you must specifyCDPLEX. If you are shutting down a server, you must also specify WHERE(SERVER=).

MANAGER Shuts down IBM Connect:Direct/Manager. You cannot use this parameter in a IBMConnect:Direct/Stand-alone Server.

RECOVER Specifies if the extended recovery standby system continues processing work from thesystem that is shutting down.

ExamplesThe following example stops IBM Connect:Direct, and terminates all transactions immediately.

STOP CD I

The following example stops an entire IBM Connect:Direct/Plex environment after all Processes arecomplete.

STOP CD Q CDPLEX

The following example stops IBM Connect:Direct/Manager, and terminates all transactions on Managerimmediately, but Servers continues processing.

STOP CD I MANAGER

176 IBM Connect:Direct for z/OS: Documentation

The following example force stops a IBM Connect:Direct/Server named WALTER, but continuesprocessing on the extended recovery standby system.

STOP CD F WHERE(SERVER=WALTER) RECOVER

Stopping IBM Connect:Direct through the Batch InterfaceTo use the STOP CD command from the batch interface:

1. Place your command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify the results.

Stopping IBM Connect:Direct through the IUITo issue the STOP CD command through the IBM Connect:Direct IUI:

1. Select SN from the Connect:Direct Administrative Options Menu.

node.name STOP Connect:Direct hh:mm CMD ==>

Q ==> Continue active transmissions until the end of process

S ==> Continue active transmissions until the end of a step

I ==> Immediately stop all active transmissions (wait for RUN TASKS to complete)

R ==> Immediately stop all active transmissions (do not wait for RUN TASKS to complete)

F ==> Force Connect:Direct to stop via an ABEND

EXTENDED.RECOVERY and C:D/Plex Options:

Server ==> ________ (C:D/Plex server name or '*' for entire C:D/Plex)or 'M' for C:D/Plex manager)

Recover => ___ (Yes|No) Should EXTENDED.RECOVERY standby takeover?

2. Type one of the five options on the command line.Refer to “Stopping IBM Connect:Direct” on page 175 for a description of these options. Quiesce (Q) isthe default.

3. If you want to shut down a IBM Connect:Direct/Server in IBM Connect:Direct/Plex environment, typethe server name in the SERVER field.

If you want to shut down the IBM Connect:Direct/Manager, type ‘M’ in the SERVER field.

If you want to shut down the entire IBM Connect:Direct/Plex environment, leave the SERVER fieldblank.

4. If you want the extended recovery standby system to continue processing work, type Yes in theRECOVER field. Type No or leave the field blank if you do not want the extended recovery standbysystem to continue processing work.

5. Press ENTER.

A shutdown message is displayed for Immediate, Quiesce, and Step shutdowns. No message isdisplayed for Force shutdowns.

Suspending and Resuming Quiesce and Trace SettingsIBM Connect:Direct uses a node table to manage Quiesce and Trace settings for the adjacent nodes in theNetmap. When IBM Connect:Direct is initialized, it adds all Netmap adjacent node records to a new node

Chapter 4. Administration Guide 177

table. It applies the Quiesce and Trace INITPARMs to the node table entries. After IBM Connect:Direct isinitialized, node table entries are added or deleted by Netmap updates.

If a Netmap update adds a new node, the node is added to the node table with TRACE OFF and QUIESCEOFF. If a Netmap update does a $$REPLACE or a $$DELETE followed by a $$INSERT in the same run, anypre-existing node table settings for that node are preserved. If a Netmap update does a $$DELETE and asubsequent Netmap update run adds the node back, the node is added to the node table with TRACE OFFand QUIESCE OFF.

The Modify Nodes screen and the output from the INQUIRE DEBUG command list all of the adjacentnodes in the node table.

For information about Trace and Debug settings, refer to IBM Connect:Direct Function Traces.

Use the MODIFY SESSIONS command to suspend processing on a single node, multiple nodes, orall nodes, and to resume processing on any or all suspended nodes. For example, you can suspendprocessing on a node because of problems but leave other nodes operating. Another example would bethe suspension of a node that you know will be down for some time.

Note: Node-level MODIFY commands only apply to existing nodes in the node table. If you add a nodeusing Netmap update, enter a node-level MODIFY command to change that node's default settings.

The MODIFY SESSIONS command has the following format and parameters.

Label Command Parameters

(optional) MODIFY SESSIONS = Quiesce | Resume (WHERE(NODE=node name))

The following table describes the parameters of the MODIFY SESSIONS command.

178 IBM Connect:Direct for z/OS: Documentation

Parameter Description

SESSIONS = Quiesce | Resume

(WHERE(NODE=node name))

Controls the automatic establishment of DTF-to-DTF sessions.

Quiesce specifies that no new DTF-to-DTF sessions are started afterexecuting Processes complete. Interactive users can sign on. AnyProcesses that normally execute are placed in the WAIT queue.

Resume terminates a quiesce state and returns to normal operation.

The WHERE(NODE=) parameter enables you to suspend or resumeprocessing on a single node, multiple nodes, or all nodes. You can usethis parameter in the following circumstances:

• To suspend processing on specific nodes because of problems, butallow other nodes to continue processing.

• If you know that a node will be down for some time• To suspend or resume processing on all nodes.

The node name subparameter is the 1–16 character local node namespecified in the network map of the affected node. You can alsouse the * (for a string) and ? (for an individual character) wildcardcharacters to specify a generic node name. For example, the followingcommand suspends processing on all node names that begin withNODE.CHICAGO.

SESSIONS=QUIESCE (WHERE(NODE=NODE.CHICAGO*))

Note: If you use the * wildcard, and it is not the last character,you must put the entire node name in single quotes. Otherwise,the node name is truncated at the first *, and more nodes maybe selected than was intended. For example, node names startingwith NODE.CHICAGO can be specified either as NODE.CHICAGO* or'NODE.CHICAGO*'. But node names containing NODE.CHICAGO mustbe specified as '*NODE.CHICAGO*', not *NODE.CHICAGO* whichwould be functionally equivalent to all nodes since the first characteris *.

You can specify * as the node name to suspend or resume processingon all nodes. For example, the following command suspendsprocessing on all nodes.

SESSIONS=QUIESCE (WHERE(NODE=*))

If you omit the WHERE(NODE=) parameter, the command appliesto the entire IBM Connect:Direct system. However, a system-wide RESUME command does not override the processingof any individually suspended nodes. You must issue theSESSIONS=RESUME command with WHERE(NODE=*) to resumeprocessing on individually suspended nodes.

Note: If the command is issued on an SNODE to quiesce processingwith a PNODE, the session with the PNODE is established. However,as soon as the PNODE node name is determined, the session isterminated. No processing of data occurs.

Suspending or Resuming Processing on a Node through the Batch Interface1. Place the MODIFY SESSIONS command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify the results by issuing an INQUIRE DEBUG command.

Chapter 4. Administration Guide 179

Note: For information about INQUIRE DEBUG, see Displaying DEBUG Settings .

The following example suspends processing on all nodes that begin with CD.CHICAGO.

SESSIONS=QUIESCE (WHERE(NODE=CD.CHICAGO*))

The resulting output from the INQUIRE DEBUG command follows.

======================================================================NODE.NEWYORK *INQ DEBUG/QUIESCE* DATE: mm.dd.yyyy TIME: hh:mm:ssSYSTEM INITIALIZED --------(0000)-------- mm.dd.yyyy hh:mm:ss======================================================================

DEBUG => '00200000'QUIESCE => NoTCQ DSN => PROD.CD.ABC.TCQTCX DSN => PROD.CD.ABC.TCXTCQ Threshold => NoTCQ File 0% Full. Max.# CI: 1000 # Used CI: 0

NODE TABLE => NODE NAME QUIESCE DEBUGNODE ENTRY 1 => CD.CHICAGO1 YesNODE ENTRY 2 => CD.CHICAGO2 Yes

Suspending or Resuming Processing on a Node through the IUI1. Request option MD from the Connect:Direct Administrative Options Menu to access the MODIFY

COMMAND screen.2. Type Q in the MODIFY SESSIONS field to suspend processing.

Type R in the MODIFY SESSIONS field to resume processing on a suspended node.3. Type the 1–16 character node name in the NODE field. (If you use the * wildcard, and it is not the last

character, put the entire node name in single quotes.)4. Press ENTER.

The results will be displayed, for example, MODIFY SESSIONS QUIESCE successful.

Suspending or Resuming Processing on Nodes through the Modify NodesScreenTo suspend or resume processing on nodes through the Modify Nodes screen:

1. Request option MD from the Connect:Direct Administrative Options Menu to access the MODIFYCOMMAND screen.

2. Type YES in the MODIFY NODES field.3. Press ENTER. The Modify Nodes screen is displayed.

180 IBM Connect:Direct for z/OS: Documentation

CD.PRD MODIFY NODES (Unsaved Changes) Row 1 of 1054 CMD ==> SCROLL ===> PAGE(CMD commands: CLEAR DEBUG/TRACE QUIESCE RESUME; CANCEL END REFRESH SAVE)(SEL commands: C=Clear Q=Quiesce R=Resume. Overtype Debug setting.) SEL Node Name Quiesce Debug Chg --- ---------------- ------- -------- --- CD.PRD.CSGA OFF 11111111 CD.PRD.CSGB OFF 11111111 CD.PRD.CSGD OFF 11111111 CD.PRD.CSGE OFF 11111111 CD.PRD.CSGF ON 11111111 Y CD.PRD.CSGG OFF 11111111 CD.PRD.VIPA OFF 11111111 CD.TST OFF FFFFFEFF CD.TST.%%%%% OFF FFFFFEFF CD.TST.CSGA ON Y CD.TST.CSGB OFF FFFFFEFF CD.TST.CSGD OFF FFFFFEFF CD.TST.CSGG OFF FFFFFEFF CD.TST.CTCA1 OFF FFFFFEFF CD.TST.CTCA2 OFF FFFFFEFF CD.TST.CTCA3 OFF FFFFFEFF

4. Use one of the following methods to suspend processing of specific nodes:

• Type Q in the SEL column next to the matching node names. The Chg field for those nodes willdisplay Y.

• From the CMD line, use the QUIESCE nodename command to turn the Quiesce setting on for therows with matching nodenames.

Note: You can use the * (for a string) and ? (for an individual character) wildcard characters to specifya generic node name. Unlike the MODIFY SESSIONS command, you do not have to enclose the nodename in single quotes if you use the * wildcard and it is not the last character. In fact, if you do, as aresult, there will probably not be any matches since quotes are treated like any other character.

Use one of the following methods to resume processing of a specific node:

• Type R in the SEL column next to the matching node names. The Chg field for those nodes willdisplay Y.

• From the CMD line, use the RESUME nodename command to turn the Quiesce setting off for the rowswith matching nodenames. Refer to the Suspending and Resuming Quiesce and Trace Settings forinformation about the RESUME command.

5. Type SAVE in the CMD field and press ENTER to save your changes.

Modify Nodes ScreenUse the Modify Nodes screen to Quiesce or Resume processing for all nodes or specified nodes. (Toaccess the Modify Nodes screen, follow Steps 1 through 3 in Suspending or Resuming Processing onNodes through the Modify Nodes Screen.) You can also use the Modify Nodes screen to modify debug andtrace settings for all nodes or specific nodes. See Modify Trace and Debug Settings Through the ModifyNodes Screen for more information.

CMD CommandsCMD commands are entered in the CMD input field. Unknown commands and syntax errors will resultin error messages. CMD commands operate on all nodes in the node table, not just the rows that arecurrently being displayed.

The CMD input field accepts the following commands:

CMD Description

CANCEL Unconditionally exits the Modify Nodes screen, discarding any changes. You canabbreviate CANCEL to CAN, CANC or CANCE.

Chapter 4. Administration Guide 181

CMD Description

END Exits the Modify Nodes screen if there are no unsaved changes outstanding. Ifthere are unsaved changes, the END command causes the dialog to issue an errormessage and redisplay the ISPF table.

SAVE Commits all changes en masse to the DTF. It then gets a new copy of the nodetable from the DTF. Also, all the ISPF table change indicators are cleared.

CLEAR nodename Clears the quiesce and debug settings for the rows with a matching node name. Itis equivalent to doing both a DEBUG OFF and a RESUME against the node name.

The nodename operand can have any number of * or ? wildcard characters in anyposition.

DEBUG nodenameON debug-bits

Turns on debugging and completely replaces the Debug setting with the debug-bitsoperand for the rows with a matching node name. This overrides the global DEBUGsetting for the individual nodes. 00000000 is a valid debug-bits value and is notthe same as DEBUG OFF.

The nodename operand can have any number of * or ? wildcard characters in anyposition.

DEBUG nodenameOFF

Turns off debugging and blanks out the debug setting for the rows with a matchingnodename. This allows the nodes to revert to using the global DEBUG setting.

The nodename operand can have any number of * or ? wildcard characters in anyposition.

DEBUG nodenameBITSON debug-bits

Turns on the bits in the debug-bits operand without changing any other bits inthe row's debug setting, but only if the rows with a matching node name have anon-blank debug setting. It does not turn debugging on or off. Though 00000000 isa valid debug-bits value, if it is specified in DEBUG BITSON, the command has noeffect.

The nodename operand can have any number of * or ? wildcard characters in anyposition.

DEBUG nodenameBITSOFF debug-bits

Turns off the bits in the debug-bits operand without changing any other bits inthe row's debug setting, but only if the rows with a matching node name have anon-blank debug setting. It does not turn debugging on or off. Though 00000000 isa valid debug-bits value, if it is specified in DEBUG BITSOFF, the command has noeffect.

The nodename operand can have any number of * or ? wildcard characters in anyposition.

QUIESCEnodename

Turns the Quiesce setting on for the rows with a matching nodename. See theCLEAR command above for the description of the nodename operand.

The nodename operand can have any number of * or ? wildcard characters in anyposition.

REFRESH Discards any pending changes and gets a new copy of the node table from the DTF.It is the equivalent of doing a CANCEL, and then reentering the dialog.

RESUMEnodename

Turns the Quiesce setting off for the rows with a matching nodename. See theCLEAR command above for the description of the nodename operand.

The nodename operand can have any number of * or ? wildcard characters in anyposition.

182 IBM Connect:Direct for z/OS: Documentation

CMD Description

TRACE nodenameBITSOFF debug-bits

TRACE is an alias of DEBUG. They have the same syntax and can be usedinterchangeably.

SEL commands are entered in the SEL input field for each row. Change the Debug field on each row byovertyping. You can update as many rows as are displayed when you press Enter.

The SEL input field accepts the following line commands:

• C - Clear all settings for the node (same as Debug OFF plus RESUME)• Q - Quiesce the node (turn Quiesce ON)• R - Resume the node (turn Quiesce OFF)

Type over the Debug field in any row to change its value. The Debug field accepts the same debug bits asthe DEBUG command. Blanking out the Debug field in a row is equivalent to issuing a DEBUG OFF on thatnodename.

If you change the Debug field to a non-blank value in a specific row, issue a CMD command for the samerow, and press Enter, only the CMD command will take effect.

If you enter a CMD command and one or more SEL commands, when you press Enter, the SEL commandsare processed before the CMD command.

Node Table ProcessingWhen you issue a CMD command, a SEL command, or change the Debug field, the node table is notupdated until you enter the SAVE command. Until then, MODIFY commands generated by these actionsare stacked in first-in-first-out (FIFO) order in a MODIFY command queue.

You can enter a SAVE command only if one or more nodes are flagged as changed. If you change a nodeand then change it back before you issue the SAVE command, the change flag is cleared. If you backout all node changes, the MODIFY command queue is cleared. However, if any rows remain flagged aschanged, SAVE sends all MODIFY commands queued since the last time there were no changed rows.

If multiple IUI users work on a copy of the node table simultaneously, it can be difficult to determine whatchanges are in effect. If you suspect that another user has changed the node table, discard your changesand retrieve a fresh copy of the node table by issuing the REFRESH command.

Global Signon DefaultsThe IBM Connect:Direct administrator can define global signon defaults so that users do not have toindividually alter their signon default values to increase their allocation. By implementing a global signondefault, you can avoid insufficient space being allocated for the temporary data set upon signon as well asSB37 ABENDs.

A temporary data set (TEMP DSN) is allocated at SIGNON to the IUI, which uses the system defaultallocation parameters. At times, this allocation is insufficient causing SB37 failures if a large amount ofdata is returned for a command request. The facilities available via SIGNON defaults (SD) are not globaland each individual user must alter their default values to increase the allocation.

Also, the option to skip the IUI SIGNON panel when using the Stage1 Security exit can be specified usingthe SSOP option described below. Likewise, the values for the Signon Dummy Passwords can be changedusing parameters described below.

To change the default values, use member DGAXCXDF from $CD.SDGASAMP to assemble and linkmodule DGAXCXDF with the new values for TEMP DSN. You can edit and submit $CD.SDGAJCL memberDGAJCXDF to do the assembly and link edit. Once the module is assembled and linked, all user who signon via an API will be subject to the new default global signon settings.

After you implement global signon defaults, allocation parameters during SIGNON can come from thefollowing three sources, which are listed from lowest to highest precedence:

Chapter 4. Administration Guide 183

• Defaults from macro DGA$UICB specified by programs such as DGADBATC, DGADCHLA, andDGADCMDP. This is considered a legacy source of SIGNON allocation parameters.

Note: Users including the administrator, do not have control over these programs.

• The SIGNON command, whose parameters come from wherever the invoker of the command decides,for example, the IUI can save SIGNON parameters in a user's ISPF profile dataset. Like the DGA$UICBmacro, this is considered a legacy source of SIGNON allocation parameters.

• The DGAXCXDF load module, which the administrator can control.

DGA$XDEF Syntax and Parameters$CD.SDGASAMP member DGAXCXDF consists of one statement, the macro DGA$XDEF, in $CD.SDGAMACand should not be changed. To modify the DGAXCXDF member, first copy it and then alter it to suit yourinstallation's requirements.

The following shows the DGA$XDEF syntax and defaults:

DMCXDEFS DGA$XDEF OVERRIDE=ALLOW, DISALLOW,ALLOW,ALLOWGT,ALLOWLT + ALOCTYPE=CYL, CYL,TRK,BLK + ALOCPRI=1, PRIMARY SPACE AMOUNT + ALOCSEC=1, SECONDARY SPACE AMOUNT + ALOCUNIT=, UNITNAME + ALOCVOL=, VOLSER + SSOP=N, SKIP SIGNON PANEL W/STG1 + PSWFRC=N, FORCE USE OF DUMMY PASSWORDS + PSWBAT=BATCH, DEFAULT PSW FOR BATCH TASKS + PSWIUI=IUI, DEFAULT PSW FOR TSO/IUI TASKS + PSWSTC=STC DEFAULT PSW FOR STC TASKS

The following table lists the parameters that make up the DGA$XDEF load module:

Parameter Description

OVERRIDE Specifies when a legacy source can override the global signon defaults assigned by theDGA$XDEF load module. If not specified, defaults to ALLOW (a null value is invalid).

Values are:

• DISALLOW— DGA$XDEF always supplies all allocation parameters.• ALLOW—A legacy source can override DGA$XDEF parameter by parameter.• ALLOWGT—A legacy source can override DGA$XDEF if the maximum space it

would allocate is greater than the maximum space that DGA$XDEF would allocate.Otherwise, DGA$XDEF overrides the legacy source. With this setting, whicheversource can supply more space will be used. Note that, unlike ALLOW, the winningsource in ALLOWGT is required to supply all allocation parameters.

• ALLOWLT—A legacy source can override DGA$XDEF if the maximum space it wouldallocate is less than the maximum space that DGA$XDEF would allocate. Otherwise,DGA$XDEF overrides the legacy source. With this setting, whichever source limitsthe maximum space more is used. Note that, like ALLOWGT, the winning source inALLOWLT is required to supply all allocation parameters.

ALOCTYPE Specifies the allocation type. If not specified, defaults to space allocation by cylinder–CYL (a null value is invalid).

ALOCPRI Specifies the primary allocation of storage. If not specified, defaults to a o1.

ALOCSEC Specifies the secondary allocation of storage. If not specified, defaults to a o1.

ALOCUNIT Specifies the unit type of the TEMP DSN. If not specified, has no default.

ALOCVOL Specifies volume serial number of the TEMP DSN. If not specified, has no default.

184 IBM Connect:Direct for z/OS: Documentation

Parameter Description

SSOP Specifies whether to skip the IUI SIGNON panel when Stage 1 Security exit is beingused. With the Stage 1 Security exit, user is coming from a secured environment sothat passwords are not required. Therefore, the SIGNON panel can be skipped. Validvalues are Y to skip the panel or N to continue invoking the SIGNON panel. Default is N.

PSWFRC Specifies whether to force the use of Signon Dummy Password values based on thehost environment. Valid values can be N (the default) which will not force the useof Signon Dummy Passwords or Y which will use Signon Dummy Passwords evenis a password is supplied by the user. Give careful consideration before setting thisparameter to Y. This parameter is implemented by code in the Stage 1 Security exit.

PSWBAT Specifies the value to use for Signon Dummy Passwords when coming from a batchJOB environment. Default is BAT but can be set to any 8 character alphanumeric value.This value is used by both the Stage 1 and Stage 2 Security exits.

PSWIUI Specifies the value to use for Signon Dummy Passwords when coming from a TSO IUIenvironment. Default is IUI but can be set to any 8 character alphanumeric value. Thisvalue is used by both Stage 1 and Stage 2 Security exit.

PSWSTC Specifies the value to use for Signon Dummy Passwords when coming from a StartedTask environment. Default is STC but can be set to any 8 character alphanumeric value.This value is used by both Stage 1 and Stage 2 Security exits.

The other DGA$XDEF macro parameters are converted into the well known JCL space parameters. AllDGA$XDEF macro parameters other than OVERRIDE are converted into the JCL SPACE parameters andcan take any valid value that can be specified in JCL. The one exception is that the ALOCTYPE parametersupports only TRK (Track) and CYL (Cylinder).

ISPF Messages Displayed During SignonIf the DGAXCXDF load module was successfully located at IUI SIGNON, new ISPF messages aredisplayed upon entry to the IUI Signon Defaults (SD) panel. (If DGAXCXDF was not present at IUISIGNON, no ISPF message is displayed.) Both the short and long message components are generated.The exact text of the ISPF messages is based on:

• Settings in the DGAXCXDF load module,at the time of SIGNON• The user's ISPF profile variables for the temporary data set

The user will see one of the following ISPF short messages, which states what the DGAXCXDF OVERRIDEsetting was when they signed on:

• OVERRIDE=DISALLOW• OVERRIDE=ALLOW• OVERRIDE=ALLOWGT• OVERRIDE=ALLOWLT

The ISPF long message component provides the following information:

• The values for the current temporary data set allocation• An explanation of where the values came from and why

The following is an example of a typical ISPF long message example:

Chapter 4. Administration Guide 185

.------------------------------------------------------------------. | The current Temporary Data Set space settings are: ALLOCATION | | TYPE=CYL, PRIMARY SPACE=00000001, SECONDARY SPACE=00000001, UNIT | | TYPE=, VOL=SER=. These are from the Global Signon Default | | module DGAXCXDF, because OVERRIDE=ALLOWGT is specified, and the | | maximum space specified by this panel/DGA$UICB was not greater | | than that specified by DGAXCXDF. | '------------------------------------------------------------------'

Note: In the message above, the phrase, this panel/DGA$UICB, is the same thing as saying a legacysource of SIGNON allocation parameters.

Implementing SecurityIBM Connect:Direct provides a range of security options to meet diverse security requirements. Theseoptions can be part of IBM Connect:Direct, part of interfaces to other security software, sample exits, oravailable from user-customized exit routines.

IBM Connect:Direct provides support for passwords and/or passphrases up to 64 characters. Passwordcan also mean passphrase in most instances with exception when referencing dataset passwords.

When PROCESSes supply PNODEID and/or SNODEID passwords, password longer than 8 characterscannot be used when the PROCESS is using PNODE-SNODE, SNA or SNUF protocols.

Note: Be aware that when a user signs on to Connect:Direct using a passphrase (a password that is longerthan 8 characters), all PROCESSes submitted must override the PNODEID and SNODEID userids andpasswords if the process is to use PNODE=SNODE, SNA or SNUF protocols (these protocols only supportpasswords of 8 characters or less).

Note: All sample exits define the proper AMODE and RMODE settings within the source memberthemselves. All user exits should be link-edited with AMODE=31 and capable of executing in 31-bit mode.Each user exit should preserve the mode in which it was invoked and return to the caller in the propermode. Modules written to execute in 31-bit mode can be link-edited with RMODE=ANY or RMODE=24.Check the source for the sample exits to see how IBM Connect:Direct defines the proper AMODE andRMODE settings.

Connect:Direct for z/OS provides the following security features:

Security Option Description

Security exits Secures signon processing, job streams, and application programs. IBMConnect:Direct provides four security exits and includes samples in the samplelibrary. See Security Exits for more information.

SECURITY.EXITinitializationparameter

Specifies a stage 2 security exit. This exit is invoked during signon and Processstart and data set access. Signon or file access requests are passed directlyto the security exit for authorization checking. For more information, see“SECURITY.EXIT | SECURITY” on page 490.

IBM Connect:DirectAuthorization Facility

Provides signon security and assigns IBM Connect:Direct functional authority ifyou do not specify or comment out the SECURITY.EXIT initialization parameter.Use this facility if your installation does not have a security package. See IBMConnect:Direct Functional Authority for information.

Note: The IBM Connect:Direct Authorization Facility provides no data setaccess security checking. Authorization File describes the User Authorizationfile in detail.

IBM SterlingConnect:Direct SecurePoint-of-Entry

Secures the entry of an outside user to your system. Point-of-entry processingoccurs before security exits are called. See Sterling Connect:Direct SecurePoint-of-Entry for more information.

186 IBM Connect:Direct for z/OS: Documentation

Security Option Description

Trusted Node Security Enables you to enforce more restrictive security parameters on specific nodesin your network. For example, each adjacent node can be defined as internal orexternal in its relationship to the local node of that network map. See TrustedNode Security for more information.

IBM Connect:Direct supports the following security options:

Security Option Description

Connect:Direct SecurePlus

Provides enhanced security for IBM Connect:Direct. It uses cryptographyto secure data during transmission. You select the security protocol, ciphersuites, and other encryption options to use with the Connect:Direct SecurePlus product. One such option is Strong Password Encryption (SPE), whichyou can use to secure passwords at rest within the TCQ and AUTH files.SPE uses the TDESCBC112 encryption algorithm of Connect:Direct SecurePlus so if you have the Connect:Direct Secure Plus component configured,and then take the necessary steps to enable the SPE feature, SPE will bein effect. See the IBM Connect:Direct Secure Plus for z/OS ImplementationGuide for more information.

CA-ACF2 External security package that secures files, users, and IBM Connect:Directfunctions.

IBM® Resource AccessControl Facility (RACF®)

External security package that secures files, users, and IBM Connect:Directfunctions.

CA-TOP SECRET External security package that secures files, users, and IBM Connect:Directfunctions.

Firewall Navigation Enables you to control access to a IBM Connect:Direct system runningbehind a firewall. See Configuring Firewall Navigation.

Security ExitsIBM Connect:Direct provides the following security exits:

• Stage 1 signon security exit• Stage 2 security exit• Run Job security exit• Run Task security exit

The IBM Connect:Direct sample library provides the following security exit routines for use with CA-ACF2,IBM RACF, and CA-TOP SECRET. The High-Level Assembler is required to assemble the sample securityexits.

Exit Description

DGACXSIG Stage 1 signon security exit interface

DGAXACRJ RUN JOB security exit

DGAXACFT RUN TASK security exit

DGAXRACJ RUN JOB security exit for SAF or IBM RACF

DGAXRACT RUN TASK exit

DGAMGSAF Security Exit Stage 2

DGAXSAFT RUN TASK security interface

Chapter 4. Administration Guide 187

The DGA$SAFW macro in $CD.SDGAMAC provides maps of the security and interface work area usedby the security exits. This area allows for information that can be passed between the exits. IBMConnect:Direct has two major processing flows that invoke security exits, the SIGNON commandsequence and the Process execution sequence. This section describes how security exits are invokedduring these two Processes.

SIGNON Command SequenceThe SIGNON command sequence is the first flow through which a IBM Connect:Direct terminal user,console operator, or batch application gains access to IBM Connect:Direct functions. During thissequence, one or more of the following control points is invoked:

• Stage 1 signon security exit• Stage 1 ESF signon Security exit• IBM Connect:Direct Authorization Facility• Stage 2 security exit

Security during Signon CommandWhen you execute a SIGNON command through the batch, interactive, or operator interface, securitycontrol points exist in the IBM Connect:Direct user region (or API) and the IBM Connect:Direct DTF region.

The stage 1 signon security exit is the initial control point, as shown in the following figure. This optionalcontrol point is a user exit that gains control in the region of the user. The exit can inspect and modify theSIGNON command parameters.

The next control point occurs in the DTF region and can be a stage 2 security exit or the IBMConnect:Direct Authorization Facility.

The following SIGNON command flow traces the security flow. The step numbers correspond to the stepsin the illustration.

188 IBM Connect:Direct for z/OS: Documentation

1. When you issue a SIGNON command, the API SIGNON command processor calls the stage 1 signonexit. If the stage 1 exit is not found, normal signon processing continues.

When invoked, the stage 1 exit receives a pointer to the User Interface Control Block (UICB) thatcontains information regarding the signon attempt. For a listing of UICB fields, refer to the chapter onthe application programming interface in IBM Connect:Direct for z/OS User Guide.

If you specify a password on the SIGNON command, the stage 1 exit returns control to IBMConnect:Direct without making any modifications to the UICB, and signon processing proceeds. Thestage 2 exit verifies the USERID and PASSWORD that are coded on the SIGNON command for systementry validation and all subsequent security calls.

If you do not specify a password on the SIGNON command, the stage 1 exit extracts the USERID fromthe security system control block built for this address space (when the TSO user logged on to TSO orwhen the BATCH job began execution) and puts that USERID into the UICB.

Note: Stage 1 exit keys off the password, not the user ID. So, if you do not specify a password but dospecify a user ID, the stage 1 exit ignores that user ID and overlays it with the address space user IDthat is picked up from the security system control block.

When the user ID is moved to the UICB, the exit fills in a Signon Dummy Password supplied by theGlobal Signon Defaults module (DGAXCXDF alias DMCXDEFS), depending upon what environment thesignon comes from (IBM Connect:Direct cannot access the password for the address space user ID),and control returns to IBM Connect:Direct. The default passwords are IUI, BATCH or STC. To changethose values, refer to “Global Signon Defaults” on page 183.

The benefit of running with a stage 1 signon exit is that IBM Connect:Direct batch jobs do not needhardcoded passwords in their SYSIN data streams.

The sample stage 1 exit supplies these Signon Dummy Password values from the Global SignonDefaults module or from an internal copy of that module, not contained in the sample exit code.Change these passwords for each installation to avoid the chance that another site is using the sameSignon Dummy Passwords. You can change these passwords by editing and assembling the GlobalSignon Defaults module. If a user id has a security subsystem password that matches one of theSignon Dummy Passwords, that user id will be unable to sign on to IBM Connect:Direct under somecircumstances until the password is changed.

2. If the stage 1 processing is successful, the API SIGNON command processor passes the SIGNONcommand to the DTF where the DTF SIGNON command processor is invoked.

3. The DTF SIGNON command processor calls the stage 2 security exit or the IBM Connect:DirectAuthorization Facility. The stage 2 exit recognizes the Signon Dummy Passwords by matching againstthe same values from the Global Signon Defaults module used by the stage 1 exit. Calls to the securitysystem for verification for these SIGNONs verify authorizations by user ID only.

4. No code changes to either stage 1 or stage 2 Security exits are required to use or change these SignonDummy Password values. Refer to Global Signon Defaults for how to change them.

Regardless of how your system is implemented, this processing flow verifies the authority of therequesting user to perform IBM Connect:Direct functions by checking the ABM (Authorization Bit Mask)for this user. The ABM is built through the stage 2 security exit or through the IBM Connect:DirectAuthorization Facility at signon and Process start. If signon to the DTF fails, then the Stage 1 ESF SIGNONexit (DGACXESF) is called to supply the ABM. If that exit is not found, a default ABM is used.

Process Execution SequenceThe Process execution sequence is the second flow through which IBM Connect:Direct services execute auser request. During this sequence, one or more of the following control points is invoked:

• Process start invokes the stage 2 security exit.• Copy statement invokes the stage 2 security exit.• Run Task statement invokes the Run Task security exit.• Process end invokes the stage 2 security exit.

Chapter 4. Administration Guide 189

• Run Job statement invokes the stage 2 security exit or the Run Job security exit.

When IBM Connect:Direct executes a Process for a user, several DTF security control points exist, asshown in the following figure:

Refer to the numbers in the illustration as you trace the following Process flow:

1. Process start—This point in the stage 2 security exit gains control whenever a Process begins initialexecution or restart execution, and enables verification of the authority of the requesting user toperform the IBM Connect:Direct functions contained in the Process.

2. File access—This point in the stage 2 security exit gains control during Process execution whenever aCOPY or RUN JOB statement is encountered. It enables verification of the access of the user to read orwrite the file defined in the COPY statement.

With the RUN JOB statement, the exit enables verification of the user to read the file containing the jobstream to be submitted.

3. Run Job—This exit point enables job stream validation and gains control when the following conditionsexist:

• RUN JOB statement is encountered during Process execution• RUN.JOB.EXIT initialization parameter is specified

190 IBM Connect:Direct for z/OS: Documentation

4. Run Task—This exit point enables program validation and gains control when the following conditionsexist:

• RUN TASK statement is encountered during Process execution• RUN.TASK.EXIT initialization parameter is specified

5. Process end—This point in the stage 2 security exit gains control whenever a Process terminates,whether normally or abnormally. This exit point assists in cleaning up the security resources involvedin Process execution.

Note: Copy, Run Job, and Run Task exit functions are entered for every occurrence of the associatedstatement in a IBM Connect:Direct Process.

Implementing Security ExitsThis section describes how to implement each type of security exit, and includes information for specificsecurity environments such as, IBM RACF, CA-ACF2, and CA-TOP SECRET.

Note: You must have the High-level Assembler to assemble the sample exits.

CAUTION: To avoid out-of-storage ABENDS in Connect:Direct for z/OS, examine all user exitsto verify that all obtained storage either via GETMAIN or STORAGE OBTAIN is freed. For eachGETMAIN/STORAGE OBTAIN that an exit issues, the exit must also issue a correspondingFREEMAIN/STORAGE RELEASE to avoid accumulating storage. If an exit opens a file, you mayneed to issue a FREEPOOL after the file is closed.

Stage 1 Signon Security ExitThis control point enables the verification of the format and contents of the SIGNON command. Thefollowing requirements and restrictions apply:

• Implement the IBM Connect:Direct stage 1 signon exit as an executable load module.• Name the load module DGACXSIG. To assemble, link-edit the appropriate name with an alias of

DMCXSIGN by using DGAJCXSG.• Do not specify NCAL.• Link-edit the module with either RENT or NORENT, depending on whether it is reentrant or not.• Link-edit the module with either REUS or NOREUS, depending on whether it is reusable or not.• Link-edit the module with an authorization code (AC) of 0 or omit the SETCODE parameter.• For the TSO IUI, the Stage 1 Signon Security exit module can come from a library in the LINKLIST,

STEPLIB, TSOLIB, ISPLLIB, or LIBDEF-ISPLLIB concatenation. However, if there is a LIBDEF-ISPLLIBin effect, all Connect:Direct load modules (including the Stage 1 exits) must come from a library in theLINKLIST or the LIBDEF-ISPLLIB concatenation or a combination of the two.

• IBM Connect:Direct will only use the stage 1 signon security exit module if the module is deemedauthorized. To be deemed authorized, the module must come from the LINKLIST or an APF-authorized library (partitioned data set). The entire concatenation does not need to be APF-authorized.Connect:Direct branches via BASSM to the Stage 1 exit, so the exit inherits the APF authorization thecaller has. The IUI always executes APF unauthorized, so a Stage 1 exit running under the IUI alwaysexecutes APF unauthorized.

• If a stage 1 signon security exit exists but is not deemed authorized, the SIGNON command fails.• For DGADBATC and DGADCHLA, the module search is limited to the LINKLIST, JOBLIB, or STEPLIB. For

more information, see “IBM Connect:Direct Exits” on page 322.• Because the information that is passed to the exit by IBM Connect:Direct is located above the 16-

megabyte line, and because IBM Connect:Direct branches via BASSM to the stage 1 exit, you mustlink-edit the module with AMODE 31 to allow it to access the information that is passed to it.

• The $CD.SDGASAMP library contains a sample source module exit called DGACXSIG. Edit this moduleand modify the variable &SECTYPE to reflect the security system in use. Assemble and link-edit the exit.

Chapter 4. Administration Guide 191

For IBM RACF or CA-TOP SECRET, use the character string RACF for &SECTYPE. For CA-ACF2, use thecharacter string ACF2.

Member DGAUSEC in $CD.SDGASAMP is a sample SMP/E USERMOD to assist with such changes.

All IBM Connect:Direct nodes in cross-domain signon (or multi-session signon) with a IBMConnect:Direct node that uses the stage 1 signon exit must also use the stage 1 signon exit.

Signon ErrorsIf you are receiving signon errors about the stage 1 exit, allocate the special DDNAME APISECUR forspecial diagnostic output using one of the following methods

If you are using the DGADBATC, to route the trace output to SYSOUT, add the following DD statement tothe DGADBATC JCL.

//APISECUR DD SYSOUT=*

If you are using the IUI, to route the trace output to the screen, issue the following TSO command.

TSO ALLOC F(APISECUR) DA(*)

To route the trace output to a data set, issue the following TSO command:

TSO ALLOC F(APISECUR) SHR DSN(’data-set’)

You must preallocate the data set with the following DCB attributes.

DSORG=PSRECFM=VBALRECL=121,BLKSIZE=125 or greater

To route the output to spool, issue the following TSO command:

TSO ALLOC F(APISECUR) SYSOUT(*)

Skipping the SIGNON PanelSince the TSO user ID has already been authenticated when logging on to TSO, you can bypass the IBMConnect:Direct IUI SIGNON panel when using the Stage1 Security exit. To implement this feature, simplyuse the Global Signon Default feature and set the SSOP option to Y and assemble the Global SignonDefault module. For more information, see “Global Signon Defaults” on page 183.

Stage 2 Security ExitThis control point applies to all environments and is implemented as a user-supplied exit. It providesa standard interface for user ID and password verification and for establishing IBM Connect:Directfunctional authority and file access verification. Although you can use it for many different purposes,the stage 2 security exit is designed to provide the interface to your security system. You can also use it toinvoke an exit to test new applications and customer connections. For more information, see Process Exitfor Testing (DGAXPRCT).

The following requirements and restrictions apply:

• The stage 2 security exit is implemented as an executable load module.

192 IBM Connect:Direct for z/OS: Documentation

• The name of the load module is user-defined, but it cannot conflict with any IBM Connect:Direct loadmodules.

• Specify the SECURITY.EXIT initialization parameter to activate the stage 2 security exit. This parameteralso specifies whether the exit is used for ALL security checking or just DATASET access validation.

• You must link-edit the module as re-entrant and reusable and place it in a load library that the IBMConnect:Direct DTF can access. Do not specify NCAL. For more information, see “IBM Connect:DirectExits” on page 322.

• To prevent a remote node's security from using Signon dummy passwords, you can use the initializationparameter, REMOTE.DUMMY.PASSWORD. See REMOTE.DUMMY.PASSWORD=[ YES | INTERNAL ] formore details.

• Because information passed to the exit by IBM Connect:Direct is located above the 16-megabyte line,you must link-edit the module with AMODE 31 to make it capable of executing in 31-bit mode. Also, youmust use RMODE 24 for PARM validation to work properly. You must link-edit the module as re-entrantand reusable and place it in a load library that the IBM Connect:Direct DTF can access. Do not specifyNCAL. Use SDGAJCL member DGAJSAF to perform assembly and link. For more information, see “IBMConnect:Direct Exits” on page 322.

Considerations for Systems with z/OS UNIX System ServicesThe following considerations apply to systems with z/OS UNIX System Services:

• Access to HFS files is controlled by UNIX System Services. The user ID under which the DTF runsmust have UPDATE authority to the BPX.SERVER facility. In addition, the submitter ID/password, thePNODEID/password, or SNODEID/password must be valid. z/OS UNIX System Services enables ordenies access based on the UNIX permission rules.

• IBM Connect:Direct can also check HFS access without requiring a password. To use a password lengthof zero, you must set up an IBM RACF profile BPX.SRV.userid in class SURROGAT and make sure that theConnect:Direct started task userid has READ access to this profile. For more information, see Defining aSurrogate for User IDs with No Password.

• UNIX System Service (BPX) calls are executed in the IBM Connect:Direct IUI under the TSO or BatchUser ID. BPX calls require that a user ID has an OMVS segment defined to it within the external securityproduct, such as IBM RACF, ACF2 or CA-TOP SECRET.

Note: The BPX calls are used to resolve the TCP/IP name or address for reporting purpose in SelectStatistics. For more information on adding an OMVS segment to a user ID, see IBM Connect:Direct forz/OS Release Notes.

Sample Source Modules in the SDGASAMP LibraryThe $CD.SDGASAMP library contains sample source modules for several release levels of z/OS securitysystems. These sample routines invoke a common macro called DGASECUR. This macro is the actualsource code for the sample exits and is conditionally assembled based on the security system in use.Samples are provided for CA-ACF2, IBM RACF, and CA-TOP SECRET. You can accommodate other systemsby using the sample code as a model.

DGAMGSAF is a sample exit routine for all security software supporting the RACROUTE interface. It usesthe z/OS Security Access Facility (SAF). The TCB Extensions Feature (TCBSENV) must be present forcorrect operation.

DGASECUR ParametersYou can edit the parameters in the DGASECUR macro to select the appropriate parameters.

The parameters are described in each source module and summarized in the following table. Theparameters related to functional authority levels are listed separately in IBM Connect:Direct FunctionalAuthority.

Parameter Description

TYPE=[SAF] Identifies the type of exit.

Chapter 4. Administration Guide 193

Parameter Description

STAGE1=[YES,NO] Identifies whether the stage 1 signon exit is implemented.

NOPASS=[YES,NO] Specifies if data set validity calls to the security subsystem areto be made without using passwords.

SECSYS=[ACF,TSS,RACF] Identifies the security system package installed on your z/OSsystem.

APPLID=[NOMFA | applid] NOMFA is the default and indicates a Multi-FactorAuthentication environment is not present. When Multi-FactorAuthentication is present and active in your External Securitysystem, you must supply an application id (aaplid) that isdefined to that security system to allow IBM Connect:Directto bypass Multi-Factor Authentication. Refer to Multi-FactorAuthentication section below this table.

AUTHENTRY=[YES | NO | EXTERNAL] NO specifies to have the exit work like it always has or disabledthis feature;

YES specifies to require an AUTH file entry for all UIDs using aDUMMY-PWD

EXTERNAL specifies to only require it from external PNODEs.

Note: If an AUTH file entry is required but not defined, messageRACF018* is issued (see AUTHMSG).

AUTHXLAT=[YES | NO] NO specifies that the AUTH file entry does not have to havea Security UID/PWD and if it doesn't, the logic works like itdoes today - only the submitter UID is checked by the securityproduct.

YES specifies that the AUTH file entry must have a valid SecurityUID/PWD. If a valid Security UID/PWD is required but notdefined in the AUTH file entry, new message RACF019* is issued(see AUTHMSG).

AUTHMSG=[WARN | FAIL] FAIL indicates that if:

• AUTHENTRY requirements are not satisfied the process willfail with RC=8 and MSGID RACF018E

• AUTHXLAT requirements are not satisfied the process will failwith RC=8 and MSGID RACF019E.

A value of WARN changes the RC to 0 and the last letter of theMSGID to 'W'.

AUTHWTO=[YES | NO] Specifies that if any of the above new MSGIDs is set, themessage ID only appears in the completion message, if present,and the PT STAT record. YES also causes the message to befilled in with the submitter node and user ID and issued via WTO,so that it appears in the JOB LOG and the WT STAT record.

NEWPASS=[YES,NO] Specifies whether the security system password of a user can bechanged at signon time.

PNODEID=[YES,NO] Specifies if this exit enables security override of a PNODE userID if one is used in a Process statement.

SNODEID=[YES,NO] Specifies if this exit enables an incoming node to use aSNODEID.

194 IBM Connect:Direct for z/OS: Documentation

Parameter Description

RESTRICT=[YES,NO] (ACF2 only) Indicates if a user can specify a restricted ID (an IDwith no ACF2 password) to access IBM Connect:Direct.

When running a stage 1 signon exit, this parameter has nomeaning. The stage 1 exit inserts a dummy password into theuser security record. In an environment with a stage 1 exit,all data set validity calls to the security subsystem are madewith a NOPASS option. Therefore, the security subsystem doesnot differentiate between a restricted ID and an ID with a validpassword.

PROTECTD=[NO,YES, AUTH] (IBM RACF only) Indicates if a user can specify a protectedID (an ID with no IBM RACF password) to access IBMConnect:Direct. The User IDs are defined to IBM RACF withthe NOPASSWORD and NOIDCARD parameters. A protected IDcannot be used in situations requiring a password.

Specifying SECSYS=RACF, PROTECTD=YES, allows users toaccess Connect:Direct using User IDs without passwords whenthe Connect:Direct DTF is started with a protected User ID.Therefore, Processes may specify PNODEID=|SNODEID withoutspecifying a password..

Specifying SECSYS=RACF, PROTECTD=AUTH, works likespecifying PROTECTD=YES, except that the RACF protected IDmust be specified as the SEC ID in an AUTH file entry for theUSERID/NODE being verified. Also, the initialization parameterINVOKE.SPOE.ON.SNODEID must be YES

Note: For PNODEID protected id processing, specifyingPROTECTD=AUTH is the same as specifying PROTECTD=YESand no entry needs to be in the AUTH file as no SPOE processingis performed for PNODEID overrides.

Specifying SECSYS=RACF, PROTECTD=NO generates no supportfor IBM RACF Protected User IDs.

NPFAIL=[YES,NO] Specifies whether to refuse a request to copy a file that is notprotected. This parameter is only valid for IBM RACF and CA-TOP SECRET users.

TRACE=[NO,DEBUG] Specifies whether tracing will be turned on for this security exit.

TRACE=DEBUG turns control of tracing over to the DEBUG bitsettings and/or the existence of the SECURITY DD statement.You can direct the SECURITY DD to SYSOUT or a disk file withattributes of RECFM=VBA, LRECL=121, and BLKSIZE=125 orgreater.

For more information about starting a security trace, seeSecurity Traces.

CICSID=name Specifies the dummy USERID name for establishing the initialsession between the CICS Interface and a IBM Connect:DirectDTF. Use this parameter for security when using the CICSinterface.

Chapter 4. Administration Guide 195

Parameter Description

PASSTK=[YES|NO] Results in the generation of a routine in the Stage 2 exit.This routine generates an IBM RACF PassTicket for PNODEprocessing and receives a PassTicket for SNODE processing.If PASSTK=NO is coded, no IBM RACF PassTicket processingis done. For more information, see Generating IBM RACFPassTickets.

PROCEXIT=[DGAXPRCT,NO] Specifies if the DGAXPRCT exit (Process Exit for testing) is to beused or not. To invoke the exit, specify DGAXPRCT. To preventthe DGAXPRCT exit from being invoked, specify NO. For moreinformation, see Setting Up and Using the DGAXPRCT Exit.

UID=local ID Specifies the local identifier which appears in NDMLOG outputalong with the PTF maintenance listing.

CLASS=DATASET | FACILITY Provides ability to use the IBM RACF DATASET or FACILITY classto define user authorization profiles within IBM Connect:Direct.For more information, see IBM Connect:Direct FunctionalAuthority.

PPHRASE=[YES | NO ] Provides the ability to force password / passphrase truncationat 8 characters for those environments that do not supportpassphrases. This is to allow compatibility with legacyenvironments. Default is YES which supports all environments.NO will truncate password / passphrase fields at 8 characters.

Multi-Factor Authentication

Currently, IBM Connect:Direct cannot use Multi-Factor Authentication and if a short lived token isattempted with a process, the most likely outcome is a "RACF002I Invalid Password" as an error. The IBMConnect:Direct application must be excluded from MFA and the users must use their normal password orpassphrase when using IBM Connect:Direct.

In RACF, this is accomplished by defining a profile in the MFADEF class.

RDEF MFADEF MFABYPASS.APPL.applid OWNER(ssadmin) UACC(NONE)

Where applid is the application name supplied with the APPLID parameter.

Then permitting users access to the profile.

PE MFABYPASS.APPL.applid CL(MFADEF) ID(cduser) ACC(READ)

Where cduser is the userid being granted read access to this profile. The userid that runs IBMConnect:Direct will need this access as well as each userid that accesses IBM Connect:Direct.

After using these commands, the profiles in the MFADEF class may need to be refreshed.

SETR RACLIST(MFADEF) REFRESH

Generating IBM RACF PassTicketsAn IBM RACF PassTicket is a temporary one-time password that is good for only a short period of time.The generation of the PassTicket requires a Userid and an Application Profile Name. To validate thePassTicket, the same Userid and same Application Profile Name must be used. The Application ProfileName must be defined to IBM RACF as the name of a PTKTDATA profile. IBM Connect:Direct allows thespecification of a PassTicket Application ID in the AUTH file.

To identify a node as capable of generating PassTickets, the third parameter in the SECURITY.EXITinitialization parm must specify PSTKT as shown in the following example:

SECURITY.EXIT=(module name,DATASET|ALL,PSTKT)

196 IBM Connect:Direct for z/OS: Documentation

If a session is established with another Connect:Direct for z/OS that also supports PassTicket generation,a PassTicket is generated under the following conditions:

• The PNODE is PassTicket capable.• The SNODE is PassTicket capable.• SNODEID= is specified without a password.• The AUTH file contains an entry for this SNODEID/SNODE and PassTicket information is defined. The

Application Profile Name is passed to the Stage 2 security exit to generate the PassTicket.• The PassTicket is generated using the Application Profile Name and the SNODEID userid.

A generated PassTicket is passed to the SNODE as the Security Password for the SNODEID, along withan indication that a PassTicket is being used. When the SNODE receives a session start with an indicationthat a PassTicket is being used, it attempts to retrieve the Application Profile Name by looking in the AUTHfile for an entry for the SubmitterID/PNODE with the PassTicket information defined. The ApplicationProfile Name and SNODEID userid are used to validate the PassTicket.

PassTickets can also be used to access HFS files.

Return CodesThe following table describes the valid return codes from the stage 2 exit for signon, Process start, orsecurity delete.

RC Description

0 No error

8 Insufficient access authority; an SAFB008I is issued

20 Security system inactive (ACF only); an SAFB020I is issued

If none of the return codes in the previous table are returned, IBM Connect:Direct issues the messageSAFB003I.

Note: If SQMSGYES is on, IBM Connect:Direct does not overlay the message ID set by the exit, and theProcess ends with the message set by the exit.

The valid return codes for the data set create security call are:

RC Description

0 No error

8 Insufficient access authority; an SVSA908I ABEND is issued

12 Invalid data in SQCB; a U2250 ABEND is issued

16 No storage available for GETMAIN; a U2251 ABEND is issued

20 Security system inactive; IBM Connect:Direct performs a STOP IMMEDIATE

24 ADJ node not allowed to send (RACF100I) or receive (RACF101I) and the nodeexecuting the exit is PNODE

28 ADJ node not allowed to send (RACF100I) or receive (RACF101I) and the nodeexecuting the exit is SNODE

After control is returned from the exit to the DTF, the return code is set to 8 if the exit was run fromPNODE and to 12 if the exit was run from SNODE.

If none of the return codes in the previous table are returned, IBM Connect:Direct ends abnormally with aU2252 ABEND.

Chapter 4. Administration Guide 197

IBM Connect:Direct Functional AuthorityWhen you sign on to a IBM Connect:Direct running with security (or when a Process you submit beginsexecuting), you are assigned a 20-byte authorization bit mask (ABM) based on a recommendation bythe stage 2 security exit or the IBM Connect:Direct Authorization file. The ABM describes your uniquefunctional authority within IBM Connect:Direct .

IBM Connect:Direct provides four standard security levels in the DGAMGSAF exit described in thefollowing table. The ADMVOL, OPRVOL, DBAVOL, and GENVOL parameters indicate the volumes on whichthese data sets reside. If you do not specify volume names in the DGAMGSAF stage 2 security exit, theexit provides default volume names for monitoring by your security subsystem.

Note:

If the CLASS=DATASET is defaulted or specified, IBM Connect:Direct uses the four standard securitylevels described above. If the CLASS=FACILITY is specified, IBM Connect:Direct uses these same fourstandard security levels as defined in the following table. However, the volser information is not needed orused by the STAGE2 security exit (as provided with the installation media).

Note: To add new functional authority levels or change the privileges in the standard functional authoritylevels, see Functional Authority Privileges. There are also 10 user-defined functional levels (US0DSN-US9DSN). For more information about these functional levels, see “Example 3 - Defining AdditionalLevels of Functional Authority” on page 205 and “Example 4 - Assigning Read-Only Authority to a UserAuthorization Level” on page 205.

Parameter Description

ADMDSN=file nameADMVOL=volser

Specifies full administrator authority. The specified user isauthorized to execute all Process language statements andcommands.

DBADSN=file nameDBAVOL=volser

Specifies DB2 Data Base Administrator.

OPRDSN=file nameOPRVOL=volser

Specifies operator authority. The specified user is authorized todelete, change, display, flush, and submit Processes; stop IBMConnect:Direct; start and stop traces; and display, add, delete, andupdate type.

GENDSN=NULLFILE|filenameGENVOL=volser

Specifies general authority. The specified user is authorized todelete, change, display, and flush his own Processes, submitProcesses, and display, add, delete, and update Type.

If NULLFILE is coded, a user who logs on to IBM Connect:Directwithout specific administrator or operator authorization is, bydefault, classified as a general user. The following is a sample UserAuthorization screen, showing commands available to a general user.

If a bit in one of these standard ABMs is set to one, you are authorized to perform the IBM Connect:Directcommand that is associated with that bit, according to the security levels.

For example, if you have the authority to read the ADMDSN, you are given the administrator bit maskthat enables you to perform administrator functions. If you do not have ADMDSN authority, OPRDSN readauthority is checked, and so on, according to the sequence described in Functional Authority ValidationSequence.

To assign IBM Connect:Direct functional authority, define four data sets or resources on your system tocorrespond to the administrator, operator, database administrator, and general user data sets.

You can specify IBM Connect:Direct functional authority to individual users by verifying access to one ofthe named resources. These resource names refer to IBM Connect:Direct functional authority grouped bythe four categories. IBM Connect:Direct users are given access to the resource that corresponds to theirlevel of authority.

198 IBM Connect:Direct for z/OS: Documentation

In addition, you can modify the standard ABMs provided by IBM Connect:Direct to change the defaultprivileges for a functional authority level. See Functional Authority Privileges. In addition, you can expandthe number of functional authority levels by creating authorization bit masks for new user-defined levels.See Defining Additional Levels of Functional Authority.

Example Functional Authority ProfilesIn the sample screens below, YES next to a command means that the security level is authorized toexecute the command, NO means that the security level is not authorized to execute the command,and SUB means that the security level is authorized to execute the command only if the Process wassubmitted by the particular user.

The following example shows the User Authorization screen for the administration authority(ADMDSN=file name, ADMVOL=volser).

Note: You can access the User Authorization screen through the IBM Connect:Direct Primary OptionsMenu. This menu and its options are discussed in the chapter on the Interactive User Interface in IBMConnect:Direct for z/OS User Guide. The User Authorization screen lists all the commands a particular useris authorized and not authorized to execute.

.

node.name USER AUTHORIZATION 13:30 CMD ==>

AUTH COMMAND AUTH COMMAND --------------------------- --------------------------- 1) YES - CHANGE PROCESS 15) YES - SELECT TASK 2) YES - DELETE PROCESS 16) YES - SELECT TYPE 3) YES - DELETE TYPE 17) YES - SELECT USER 4) YES - DELETE USER 18) YES - SUBMIT PROCESS 5) YES - FLUSH PROCESS 19) YES - SUBMIT WITHIN PROC 6) YES - FLUSH TASK 20) YES - SUSPEND PROCESS 7) Y/Y - INSERT/UPDATE TYPE 21) YES - STAT COMMAND 8) Y/Y - INSERT/UPDATE USER 22) YES - EVENT COMMAND 9) YES - MODIFY (TRACE) 23) YES - VIEW PROCESS 10) YES - STOP Connect:Direct 24) YES - PERFORM CRC OVERRIDES 11) YES - UPDATE NETWORK MAP 25) NO - CONFIRM DELETE 12) YES - SELECT NETWORK MAP 26) NO - CONFIRM DEL OFF 13) YES - SELECT PROCESS 27) Y/Y - SECURE+ ADMIN/CMDS 14) YES - SELECT STATISTICS 28) NO - UPDATE INITPARM

The following example shows the User Authorization screen for the DB2 data base administrator authority(DBADSN=file name, DBAVOL=volser).

node.name USER AUTHORIZATION hh:mm CMD ==>

AUTH COMMAND AUTH COMMAND --------------------------- --------------------------- 1) SUB - CHANGE PROCESS 15) SUB - SELECT TASK 2) SUB - DELETE PROCESS 16) YES - SELECT TYPE 3) YES - DELETE TYPE 17) NO - SELECT USER 4) NO - DELETE USER 18) YES - SUBMIT PROCESS 5) SUB - FLUSH PROCESS 19) YES - SUBMIT WITHIN PROC 6) SUB - FLUSH TASK 20) SUB - SUSPEND PROCESS 7) Y/Y - INSERT/UPDATE TYPE 21) NO - STAT COMMAND 8) N/N - INSERT/UPDATE USER 22) NO - EVENT COMMAND 9) NO - MODIFY (TRACE) 23) SUB - VIEW PROCESS 10) NO - STOP Connect:Direct 24) YES - PERFORM CRC OVERRIDES 11) NO - UPDATE NETWORK MAP 25) NO - CONFIRM DELETE 12) NO - SELECT NETWORK MAP 26) NO - CONFIRM DEL OFF 13) SUB - SELECT PROCESS 27) N/N - SECURE+ ADMIN/CMDS 14) YES - SELECT STATISTICS 28) NO - UPDATE INITPARM

The following example shows the User Authorization screen for the operator authority (OPRDSN=filename, OPRVOL=volser).

Chapter 4. Administration Guide 199

node.name USER AUTHORIZATION hh:mm CMD ==>

AUTH COMMAND AUTH COMMAND --------------------------- --------------------------- 1) YES - CHANGE PROCESS 15) YES - SELECT TASK 2) YES - DELETE PROCESS 16) YES - SELECT TYPE 3) YES - DELETE TYPE 17) NO - SELECT USER 4) NO - DELETE USER 18) YES - SUBMIT PROCESS 5) YES - FLUSH PROCESS 19) YES - SUBMIT WITHIN PROC 6) YES - FLUSH TASK 20) YES - SUSPEND PROCESS 7) Y/Y - INSERT/UPDATE TYPE 21) NO - STAT COMMAND 8) N/N - INSERT/UPDATE USER 22) NO - EVENT COMMAND 9) YES - MODIFY (TRACE) 23) YES - VIEW PROCESS 10) YES - STOP Connect:Direct 24) YES - PERFORM CRC OVERRIDES 11) NO - UPDATE NETWORK MAP 25) NO - CONFIRM DELETE 12) NO - SELECT NETWORK MAP 26) NO - CONFIRM DEL OFF 13) YES - SELECT PROCESS 27) N/N - SECURE+ ADMIN/CMDS 14) YES - SELECT STATISTICS 28) NO - UPDATE INITPARM

The following example shows the User Authorization screen for the general user authority(GENDSN=NULLFILE|filename, GENVOL=volser).

node.name USER AUTHORIZATION hh:mm CMD ==>

AUTH COMMAND AUTH COMMAND --------------------------- --------------------------- 1) SUB - CHANGE PROCESS 15) SUB - SELECT TASK 2) SUB - DELETE PROCESS 16) YES - SELECT TYPE 3) YES - DELETE TYPE 17) NO - SELECT USER 4) NO - DELETE USER 18) YES - SUBMIT PROCESS 5) SUB - FLUSH PROCESS 19) YES - SUBMIT WITHIN PROC 6) SUB - FLUSH TASK 20) SUB - SUSPEND PROCESS 7) Y/Y - INSERT/UPDATE TYPE 21) NO - STAT COMMAND 8) N/N - INSERT/UPDATE USER 22) NO - EVENT COMMAND 9) NO - MODIFY (TRACE) 23) SUB - VIEW PROCESS 10) NO - STOP Connect:Direct 24) YES - PERFORM CRC OVERRIDES 11) NO - UPDATE NETWORK MAP 25) NO - CONFIRM DELETE 12) NO - SELECT NETWORK MAP 26) NO - CONFIRM DEL OFF 13) SUB - SELECT PROCESS 27) N/N - SECURE+ ADMIN/CMDS 14) YES - SELECT STATISTICS 28) NO - UPDATE INITPARM

Functional Authority Validation SequenceThe security-checking sequence follows:

1. When the stage 2 security exit is called to determine IBM Connect:Direct functional authority for a user(at signon or Process start), it first checks with the security subsystem (that is, CA-ACF2, IBM RACF, orCA-TOP SECRET) to determine if the user can read the Administrator data set. If so, the authority ofthe user is set as an Administrator.

2. If the user is not allowed to read the Administrator data set, the exit checks to see if the user can readthe Operator data set. If yes, the user is given Operator authority.

3. If the user is not allowed to read the Operator data set, the exit checks to see if the user can read theData Base Administrator data set. If so, the user is given Data Base Administrator authority.

4. If the user is not allowed to read the Data Base Administrator data set, and the stage 2 exit includesGENDSN=NULLFILE, the user is given General User authority. If you specify a data set name forGENDSN, the exit either assigns the user General User authority if the user can read the data set, ordisables the IBM Connect:Direct function requested (signon or Process execution) if the user cannotread the data set.

Functional Authority PrivilegesThe privileges set for each of the four standard IBM Connect:Direct functional authority levels are thedefault privileges provided in the base product. This section describes how to change the privileges in thestandard functional authority levels or add new functional authority levels.

200 IBM Connect:Direct for z/OS: Documentation

You can modify the IBM Connect:Direct stage 2 security exit macro, DGAXAUTH, to change the functionsa user can perform in a particular authorization level. The $CD.SDGAMAC library contains a macro calledDGA$MFLG that describes each of the 20 bytes of functional authorization.

The following is the generic 20 byte mask that is mapped by a dummy section (DSECT) in the DGA$MFLGmacro along with a definition of each byte, the general function that the bits represent, and the specificsettings:

Byte Function Setting

BYTE00 Reserved for future use

BYTE01 Display, Add, Update, and Delete UserCommands

ADDUSR–Add user

UPDUSR–Update user

DELUSR– Delete user

DSPUSR–Display user

BYTE02 Reserved for future use

BYTE03 Reserved for future use

BYTE04 Display, Add, Update, and Delete Network MapCommands

ADDNET–Add network map

UPDNET–Update network map

DELNET–Delete network map

DSPNET–Display network map

BYTE05 Change and Delete Process Commands CHGPRC–Change Process

DELPRC–Delete Process

BYTE06 Display Process, Statistics, and Traces, FlushProcess, and Use Stats commands

DSPPRC–Display Process

DSPSTA–Display Statistics

DSPTRC–Display Trace

FLSPRC–Flush Process

STATCMD–Use Statistics Commands

BYTE07 Start/Stop IBM Connect:Direct, Start/StopTraces, Modify Init parms, Suspend/ResumeSessions, Use Event Services, Update APKeycommands, and Update initialization parametersin Control Center

STPNDM–Start/Stop IBMConnect:Direct

SSTRAC–Start/Stop Traces and ModifyInitparms

EVENTCMD–Use Event ServicesCommands

REFSH–Update init parms

UPDKEY–Update license key

Chapter 4. Administration Guide 201

Byte Function Setting

BYTE08 Perform Connect:Direct Secure Plus Parm fileand netmap administration functions in ControlCenter

S#RNCR–Read Connect:Direct SecurePlus parm file

S#WNCR–Write to Connect:DirectSecure Plus parm file

DSPNCR–Display netmap controlfunctions in Control Center

UPDNCR–Allow netmap updatefunctions in Control Center

BYTE09 Display, Add, Update, and Delete Typecommands

ADDTYP–Add type

UPDTYP–Update type

DELTYP–Delete type

DSPTYP–Display type

BYTE10 Use COPY, RUN JOB, MODALS, and SUBMITStatements, and View Process and CRC Overridecommands

GCOPY–Use COPY statement

GRUNJ–Use RUN JOB statement

GMODALS–Use MODAL statement

GSUBMIT–Use SUBMIT statement

VIEWPR–View Process

GOVCRC–Perform CRC overrides

BYTE11 Use Submit within a Process and RUN TASKstatements,

display Confirm Delete prompt, and turn ConfirmDelete

prompt off for a session.

Note: The Confirm Delete function also includesthe Flush and Suspend commands, that is, theuser is prompted to confirm before the Flush andSuspend Commands in addition to the Deletecommand.

GSUB–Use Submit within a Processstatement

GRUNT–Use RUN TASK statement

GCDEL–Display Confirm Delete,

Flush, and Suspend prompts

GCDELOFF–Turn off Confirm delete

prompt off for session

BYTE12 General User Functions– Select, Delete, Flush,Change, and View Process, and Display Statistics,and Display Plex environment (the last commandfor an Administrator only).

Note: The General User functions enable youto restrict applying each command to Processesassociated with a submitter ID.

GDSPPRC–Display Process

GDELPRC–Delete Process

GDFLSPRC–Flush Process

GDSPSTA–Display Statistics

GCHGPRC–Change Process

GVIEWPR–View Process

DSPPLX–Display Plex Environment

BYTE13 Reserved for future use

202 IBM Connect:Direct for z/OS: Documentation

Byte Function Setting

BYTE14 Certificate Based User Authentication

Process Library Read and Update

File Agent Configuration Read & Update

External Statistics Logging

CERTAUTH – Cert User Auth

PRLBRD – Read Process Library

PRLBWR – Update Process Library

FACR – Read File Agent

FACU – Update File Agent

STLG – External Statistics Logging

BYTE15 Reserved for future use

BYTE16 Reserved for future use

BYTE17 Reserved for future use

BYTE18 Reserved for future use

BYTE19 Reserved for future use

The sample exit macro DGAXAUTH contains authorization bit masks for the four standard IBMConnect:Direct authority groups. The default settings shown in the following ABMs are in the DGAXAUTHmacro in the $CD.SDGAMAC library. The DGA$MFLG bit mask contains all possible functions for each bytewhereas the bit masks for a particular IBM Connect:Direct authority group may contain only a subset ofthe available functions. For example, BYTE 10 (DBA10) in the DB2 data base authority level authorizationbit mask (DBAABM) below does not contain the View Process function (VIEWPR) while BYTE 10 in theABM for the Operator authority level does. (Bytes reserved for future use are not shown.)

DGAXAUTH Authorization Bit Mask ExamplesThe following example shows the authorization bit mask for the Administrator authority level (ADMABM).

ABYTE1 DC AL1(ADDUSR+UPDUSR+DELUSR+DSPUSR)ABYTE4 DC AL1(ADDNET+UPDNET+DELNET+DSPNET)ABYTE5 DC AL1(CHGPRC+DELPRC)ABYTE6 DC AL1(DSPPRC+DSPSTA+FLSPRC+STATCMD)ABYTE7 DC AL1(STPNDM+SSTRAC+EVENTCMD+UPDKEY)ABYTE8 DC AL1(UPDNCR+DSPNCR+S#WNCR+S#RNCR)ABYTE9 DC AL1(ADDTYP+UPDTYP+DELTYP+DSPTYP)ABYTE10 DC AL1(GCOPY+GRUNJ+GMODALS+GSUBMIT+VIEWPR+GOVCRC)ABYTE11 DC AL1(GSUB+GRUNT)ABYTE12 DC AL1(DSPPLX)

The following example shows the authorization bit mask for the Operator authority level (OPERABM).

OPER1 DC XL1(00) NULL - Not SetOPER4 DC XL1(00) NULL - Not SetOPER5 DC AL1(CHGPRC+DELPRC) DELETE/CHANGE PROCESSOPER6 DC AL1(DSPPRC+DSPSTA+FLSPRC) DISPLAY/FLUSH PROCESS* DISPLAY STATISTICSOPER7 DC AL1(STPNDM+SSTRAC) STOP START-STOP TRACE OPER9 DC AL1(ADDTYP+UPDTYP+DELTYP+DSPTYP) * DISPLAY/ADD/DELETE TYPEOPER10 DC AL1(GCOPY+GRUNJ+GMODALS+GSUBMIT+VIEWPR+GOVCRC)* COPY/RUN JOB/MODALS/SUBMITOPER11 DC AL1(GSUB+GRUNT) REMOTE SUBMIT/RUN TASK

The following example shows the authorization bit mask for the DB2 data base authority level (DBAABM).

Chapter 4. Administration Guide 203

DBA1 DC XL1(00) NULL - Not SetDBA4 DC XL1(00) NULL - Not SetDBA9 DC AL1(ADDTYP+UPDTYP+DELTYP+DSPTYP)* DISPLAY/ADD/DELETE TYPEDBA10 DC AL1(GCOPY+GRUNJ+GMODALS+GSUBMIT+GOVCRC)*DBA11 DC AL1(GSUB+GRUNT) COPY/RUN JOB/MODALS/SUBMITREMOTE SUBMIT/RUN TASK

The following example shows the authorization bit mask for the General User authority level (GUSRABM).

GUSR1 DC XL1(00) NULL - Not SetGUSR4 DC XL1(00) NULL - Not SetGUSR9 DC AL1(ADDTYP+UPDTYP+DELTYP+DSPTYP)* DISPLAY/ADD/DELETE TYPEGUSR10 DC AL1(GCOPY+GRUNJ+GMODALS+GSUBMIT+GOVCRC)* COPY/RUN JOB/MODALS/SUBMITGUSR11 DC AL1(GSUB+GRUNT) REMOTE SUBMIT/RUN TASKGUSR12 DC AL1(GDSPPRC+GDELPRC+GFLSPRC+GDSPSTA+GCHGPRC+GVIEWPR)* DISPLAY/CHANGE/FLUSH/STATS FOR* SUBMITTERS PROCESS ONLY

To change the bits in any given authorization byte, locate the bit labels in the DGA$MFLG macro andupdate the DGAXAUTH macro. To implement any changes made and put your new exit into effect, youmust stop and restart IBM Connect:Direct.

Example 1 - Broadening Privileges for General UsersTo authorize general users to perform a SELECT PROCESS command and a SELECT STATISTICS commandfor Processes submitted with any user ID rather than just with the ID of the submitter, perform thefollowing steps:

1. Look in the DGA$MFLG macro for the bits that allow the user to perform these two commands. Thesebits are located in BYTE06 of DGA$MFLG.

2. Find the bits that allow these two commands only for the ID of the submitter. These bits are located inBYTE12 of DGA$MFLG.

3. Locate the label in the DGAXAUTH macro that indicates the General User authorization bit mask(GUSRABM). General user BYTES 06 and 12 are currently set to the following values.

GUSR6 DC XL1’00’GUSR12 DC AL1(GDSPPRC+GDELPRC+GFLSPRC+GDSPSTA+GCHGPRC+GVIEWPR)

4. To allow general users to perform SELECT PROCESS and SELECT STATISTICS commands for any userID, remove GDSPPRC and GDSPSTA from BYTE12 and copy the DSPPRC and DSPSTA bits from BYTE06in the DGA$MFLG authorization bit mask and put them in BYTE06 in the GUSRABM, changing thesebytes to the following values:

GUSR6 DC AL1(DSPPRC+DSPSTA)GUSR12 DC AL1(GDELPRC+GFLSPRC+GCHGPRC+GVIEWPR)

5. Reassemble and link-edit your security module that uses the DGAXAUTH macro.6. To put the new exit into effect, stop and restart IBM Connect:Direct.

Example 2 - Forcing the Confirm Prompt for General UsersIf a user has the authority to delete, flush or suspend a Process, the default setting allows the userto perform the action automatically. As soon as the user enters the command, it is executed instantly.However, you can modify this default privilege and require a user to confirm the action before it isexecuted. In addition, you can specify whether a user can turn off the Confirm Delete/Flush/SuspendCommand prompt for a particular session after the prompt displays at least one time.

204 IBM Connect:Direct for z/OS: Documentation

The following sample procedure shows you how to turn on the Confirm Delete/Flush/Suspend Commandprompt for users in the general user authority category but at the same time allow them to turn off theprompt for a particular session.

1. Locate BYTE11 in the DGA$MFLG macro. Two of the four bits, GCDEL and GCDELOFF, turn on theConfirm Delete/Flush/Suspend Command prompt and if turned on, permit a user to turn off theConfirm Delete/Flush/Suspend Command prompt temporarily for the current session. (The other twobits pertain to the Submit within a Process and RUN TASK commands.)

2. Locate the label in the DGAXAUTH macro that indicates the General User authorization bit masksetting (GUSRABM). General user BYTE 11 is currently set to the following values.

GUSR11 DC AL1 (GSUB+GRUNT)

3. To ensure that the Confirm/Delete/Suspend Command prompt displays for all users in the general usercategory, add GCDEL to change BYTE11 as follows:

GUSR11 DC AL1 (GSUB+GRUNT+GCDEL)

4. To let users in the general user category turn off the Confirm/Delete/Suspend Command prompt for aparticular session, add GCDELOFF to change BYTE11 as follows:

GUSR11 DC AL1 (GSUB+GRUNT+GCDEL+GCDELOFF)

5. Reassemble and link-edit your security module that uses the DGAXAUTH macro.6. To put the new exit into effect, stop and restart IBM Connect:Direct.

Example 3 - Defining Additional Levels of Functional AuthorityIBM Connect:Direct provides additional authorization bit masks (US0DSN through US9DSN) that you canuse to expand the number of functional authority levels beyond the standard four levels.

The following example shows the authorization bit mask for the user-definable ABM.

U0BYTE1 DC XL1(00) NULL - Not SetU0BYTE4 DC XL1(00) NULL - Not SetU0BYTE5 DC AL1(CHGPRC+DELPRC) DELETE/CHANGE PROCESSU0BYTE6 DC AL1(DSPPRC+DSPSTA+FLSPRC) DISPLAY/FLUSH PROCESS* DISPLAY STATISTICSU0BYTE7 DC AL1(STPNDM+SSTRAC) STOP START-STOP TRACEU0BYTE8 DC XL1'00' NOT USEDU0BYTE9 DC AL1(ADDTYP+UPDTYP+DELTYP+DSPTYP)* DISPLAY/ADD/DELETE TYPEU0BYTE10 DC AL1(GCOPY+GRUNJ+GMODALS+GSUBMIT+VIEWPR+GOVCRC)* COPY/RUN JOB/MODALS/SUBMITU0BYTE11 DC AL1(GSUB+GRUNT) REMOTE SUBMIT/RUN TASK

1. To create your own authorization level, locate the user-definable ABM you want to use, and change thebytes.

2. Add the data set and volume names to the DGAMGSAF stage 2 security exit.3. Assemble and link-edit the DGAMGSAF exit.4. To implement the new authorization level, into effect, you must stop and restart IBM Connect:Direct.

Example 4 - Assigning Read-Only Authority to a User Authorization LevelTo define a new security profile to allow read-only authority for users, follow this procedure. After youimplement it, when a user signs on to IBM Connect:Direct, they are assigned an authorization bit maskthat allows them to display and view Processes, and display statistics but they cannot submit or run aProcess.

1. Modify the DGASECUR macro by locating the USR0ABM label and making the following changes:a) Delete both the CHGPRC and DELPRC bits in BYTE05.

Chapter 4. Administration Guide 205

b) Delete the FLSPRC bit in BYTE06.c) Delete both the STPNDM and SSTRAC bits in BYTE07.d) Delete all bits in BYTE09.e) Delete all bits in BYTE10 except for VIEWPR.f) Delete all bits in BYTE11.

The USR0ABM should look like the following:

USR0ABM DS 0XL20 DEFINES User Group Zero ABM FlagsU0BYTE0 DC XL1’00’ NOT USEDU0BYTE1 DC XL1’00’ NOT USEDU0BYTE2 DC XL1’00’ NOT USEDU0BYTE3 DC XL1’00’ NOT USEDU0BYTE4 DC XL1’00’ NOT USEDU0BYTE5 DC XL1’00’ DELETE/CHANGE PROCESSU0BYTE6 DC AL1(DSPPRC+DSPSTA) Display Process* DISPLAY STATISTICSU0BYTE7 DC XL1’00’ STOP START-STOP TRACEU0BYTE8 DC XL1’00’ NOT USEDU0BYTE9 DC XL1’00’ DISPLAY/ADD/DELETE TYPEU0BYTE10 DC AL1(VIEWPR) View Process onlyU0BYTE11 DC XL1’00’ REMOTE SUBMIT/RUN TASKU0BYTE12 DC XL1’00’ NOT USED

2. Modify the DGAMGSAF example in the $CD.SDGASAMP library to assign a file name to the newUS0DSN parameter and indicate which volume it resides on.

DGAMGSAF DGASECUR TYPE=SAF, X . X . X ADMDSN=$CD.ADMIN, X ADMVOL=VOLSER, X OPRDSN=$CD.OPER, X OPRVOL=VOLSER, X DBADSN=$CD.DBA, X DBAVOL=VOLSER, X GENDSN=$CD.GUSER, X GENVOL=VOLSER, X US0DSN=$CD.NEW.USER.LEVEL, X US0VOL=VOLSER

3. Assemble and link-edit the DGAMGSAF module using the sample JCL in $CD.SDGAJCL(DGAJSAF).

//ASM EXEC PGM=ASMA90,// PARM=’OBJECT,NODECK,XREF(SHORT),RENT,USING(WARN(0),NOMAPX// ),FLAG(NOCONT),SYSPARM(GEN),NOTEST’//SYSIN DD DISP=SHR,DSN=connect.direct.SDGASAMP(DGA*****)//SYSLIB DD DISP=SHR,DSN=connect.direct.samplib// DD DISP=SHR,DSN=SYS1.MACLIB// DD DISP=SHR,DSN=SYS1.AMODGEN// DD DISP=SHR,DSN=SYS1.AMACLIB// DD DISP=SHR,DSN=security.maclib//SYSLIN DD DISP=(,PASS),DSN=&&OBJ,// UNIT=SYSDA,SPACE=(CYL,(1,1)),// DCB=(DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=3120)//SYSPRINT DD SYSOUT=*//SYSTERM DD SYSOUT=*//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1))//*************************//* LKED *//*************************//LKED EXEC PGM=IEWL,COND=(0,LT,ASM),// PARM=(’SIZE=(256K,13K),LIST,LET,XREF,RENT’,// ’REUS’)//SYSLIB DD DISP=SHR,DSN=connect.direct.SDGALINK// DD DISP=SHR,DSN=security.loadlib//SYSLIN DD DISP=(OLD,DELETE),DSN=&&OBJ//SYSLMOD DD DISP=SHR,DSN=connect.direct.SDGALINK(DGA*****)//SYSPRINT DD SYSOUT=*//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1),,CONTIG)

206 IBM Connect:Direct for z/OS: Documentation

4. If necessary, update the IBM Connect:Direct initialization parameter, SECURITY.EXIT, to specify thenew exit.

SECURITY.EXIT = (mod-name,ALL)

5. Initialize IBM Connect:Direct.

Example 5 - Defining a New Administrator LevelTo define a new security profile giving the administrator all normal administrator functions except theability to run Processes, follow this procedure. Authorization BYTES 10 and 11 represent the functionsthat are to be disallowed. If you have used USR0DSN to define another level, use USR1DSN for this newprofile.

1. Modify the DGASECUR macro by locating the USR1ABM label and updating the various bytes asfollows:

USR1ABM DC 0XL20U1BYTE0 DC XL1’00’ NOT USEDU1BYTE1 DC AL1(ADDUSR+UPDUSR+DELUSR+DSPUSR)U1BYTE2 DC XL1’00’ NOT USEDU1BYTE3 DC XL1’00’ NOT USED U1BYTE4 DC AL1(ADDNET+UPDNET+DELNET+DSPNET)U1BYTE5 DC AL1(CHGPRC+DELPRC)U1BYTE6 DC AL1(DSPPRC+DSPSTA+FLSPRC+STATCMD)U1BYTE7 DC AL1(STPNDM+SSTRAC+EVENTCMD+UPDKEY)U1BYTE8 DC AL1(UPDNCR+DSPNCR)U1BYTE9 DC AL1(ADDTYP+UPDTYP+DELTYP+DSPTYP)U1BYTE10 DC AL1(VIEWPR)U1BYTE11 DC XL1’00’U1BYTE12 DC AL1(DSPPLX)U1BYTE13 DC XL1’00’U1BYTE14 DC XL1’00’

2. Modify the DGAMGSAF example in THE $CD.SDGASAMP library to define the new US1DSN parameterwith the new security profile as follows:

DGAMGSAF DGASECUR TYPE=SAF, X . X . X ADMDSN=$CD.ADMIN, X ADMVOL=VOLSER, X OPRDSN=$CD.OPER, X OPRVOL=VOLSER, X DBADSN=$CD.DBA, X DBAVOL=VOLSER, X GENDSN=$CD.GUSER, X GENVOL=VOLSER, X US0DSN=$CD.NEW.USER.LEVEL, X US0VOL=VOLSER, X US1DSN=$CD.NEW.ADMIN, X US1VOL=VOLSER

3. Assemble and link-edit the DGAMGSAF module using the sample JCL in $CD.SDGAJCL(DGAJSAF).4. If necessary, update the initialization parameter, SECURITY.EXIT, to specify the new exit.5. Initialize IBM Connect:Direct in the normal manner.

Example 6 - Defining a Surrogate for User IDs with No PasswordUse the BPX.SERVER profile to set the scope of z/OS resources that the server can access when acting asa surrogate for its clients. BPX.SERVER UPDATE access lets the server establish a thread level (task-level)security environment for clients connecting to the server. When the IBM RACF identity of the applicationserver is granted UPDATE authority to BPX.SERVER in the IBM RACF FACILITY class, the server can act asa surrogate for the client.

This procedure contains sample IBM RACF commands. For more information, refer to IBM RACF manuals.For more information about how to define SURROGAT in other external security products, such as ACF2 orCA-TOP SECRET, refer to the manuals of the specific vendor.

Chapter 4. Administration Guide 207

1. Make sure that the Stage 2 Security exit can verify if Stage 1 has set the dummy password in SQCB.The DGASECUR macro contains label STG1NPW which includes the following instruction:

OI SQFLAG,SQDUMMY DUMMY PASSWORD USED P768101

2. Identify all user IDs that will access HFS without supplying their password.3. To activate the SURROGAT class support in IBM RACF, if it has not already been set up on your

system, issue the following command:

SETROPTS CLASSACT(SURROGAT)

Note: You only have to activate this feature one time.4. If you want to cache the SURROGAT profiles in storage to enable you to refresh and immediately put

all IBM RACF changes in effect immediately, issue the following command:

SETROPTS RACLIST(SURROGAT)

Note: If you do not use the RACLIST option, the changes made during this procedure will not takeeffect until the next IPL.

5. To create the SURROGAT class profile for a particular user, issue the following command:

RDEFINE SURROGAT BPX.SRV.UUUUUUUU UACC(NONE)

where UUUUUUUU is the user ID you are creating a profile for.6. Repeat Step 5 for each user ID that requires HFS support without a password with a SURROGAT

profile.

Note: To define all users in one command, you can specify BPX.SRV.* .7. To give a user the authority to create a thread-level security environment for another user, issue the

following command:

PERMIT BPX.SRV.UUUUUUUU CLASS(SURROGAT) ID(CDIRECT) ACCESS(READ)

where the DTF user called CDIRECT is the user you are granting permission to create the securityenvironment for another user called UUUUUUUU.

8. Repeat Step 8 for each user ID that requires HFS support without a password with a SURROGATprofile.

Note: To define all users in one command, you can specify BPX.SRV.* .9. Verify that the DTF User ID has sufficient access to HFS files along with both IBM RACF access and

z/OS UNIX System Services permissions.10. If you are using the RACLIST option, issue the following command to refresh and put your changes in

effect for the SURROGAT class:

SETROPTS RACLIST(SURROGAT) REFRESH

11. To check whether the DTF Userid has been defined to the BPX.SRV.uuuuuuuu SURROGAT classprofile, use the following RLIST command:

RLIST SURROGAT BPX.SRV.uuuuuuuu AUTHUSER

where uuuuuuuu is the user ID whose requests IBM Connect:Direct needs to process.

208 IBM Connect:Direct for z/OS: Documentation

The system displays the user ID (which should be the DTF Userid) and access rights of the user IDthat can act as a surrogate for uuuuuuuu.

CAUTION: Be aware of the REMOTE.DUMMY.PASSWORD and Adjacent Node settings for Nodeto Node communication.

SAFB022I – DGADABMB - Dummy password usage by Adjacent Node rejected. An attempt was made by an Adjacent Node to use a dummy password to authorize access to the Connect:Direct local node. If the Init Parm REMOTE.DUMMY.PASSWORD setting is INTERNAL, only Adjacent Nodes having the INTERNAL attribute in the Netmap may use a dummy password for this purpose.

Run Job Security ExitThe Run Job security exit control point provides a standard interface for security verification of jobstreams before they are submitted to the job entry system. Specific implementation details include thefollowing:

• The Run Job exit is implemented as an executable load module.• The name of the load module is user-defined and cannot conflict with any IBM Connect:Direct load

module names.• Specify RUN.JOB.EXIT=(modname) in the initialization parameters to activate the Run Job exit.• You must link-edit the module as re-entrant and place it in a load library that the IBM Connect:Direct

DTF can access.• Because information passed to the exit is located above the 16 megabyte line, you must link-edit the

module with AMODE ANY to make it capable of executing in 31-bit mode.

For additional information about exits, see “IBM Connect:Direct Exits” on page 322.

Sample Run Job Security ExitsThe $CD.SDGASAMP library contains a sample source module for the most used z/OS security systems.Sample exit routines are:

• DGAXRACJ for IBM RACF and CA-TOP SECRET• DGAXACRJ for CA-ACF2• DGAXSBRX

The sample exits are designed to ensure that correct security information is coded on each JOBstatement in the job stream.

• For IBM RACF and CA-TOP SECRET, a check is made for a valid USER and PASSWORD on each JOB card.If not found, a USER=submitter keyword is added to each JOB card.

• For CA-ACF2, a JOBFROM=submitter keyword is added immediately following each JOB card to ensurethat the correct security information is transferred to each submitted job.

• An IBM Connect:Direct Stage2 Exit, DGAXSBRX can be used on the SNODE as RUN JOB EXIT to restrictand reject the use of RUN JOB function. As an exception, node names of PNODEs that are allowedto execute this function on this SNODE are defined in a node table of DGAXSBRX. If the nodenamein process matches an entry in the table the function is allowed to continue otherwise the process isrejected with a return code of 8 and msgid of SVTM667I.

If you use one of these exits without coding a value for the RUN.JOB.EXIT initialization parameter, IBMConnect:Direct does not use the default for the RUNJOBID initialization parameter.

Note: Use the Run Job security exit to achieve user propagation for security checks when the job thatexecutes is submitted by the user ID assigned to IBM Connect:Direct rather than the user ID thatsubmitted the job. In most environments, this Exit is not needed.

Chapter 4. Administration Guide 209

Run Task Security ExitThe Run Task security exit control point provides a standard interface to verify that the user is authorizedto run the specified program. IBM Connect:Direct passes the exit security information about the user, theprogram name, and the parameters being passed to the program. Specific implementation details includethe following:

• The Run Task exit is implemented as an executable load module.• The name of the load module is user-defined, but cannot conflict with any IBM Connect:Direct load

module names.• Specify RUN.TASK.EXIT=(modname) in the initialization parameters to activate the Run Task exit.• You must link-edit the module as re-entrant and place it in a load library that the DTF can access.• Because information passed to the exit by IBM Connect:Direct is located above the 16 megabyte line,

you must link-edit the module with AMODE ANY to make it capable of executing in 31-bit mode.

For additional information about exits, see “IBM Connect:Direct Exits” on page 322.

Sample Run Task Security ExitThe $CD.SDGASAMP library contains a sample source module for the most used security systems. Sampleexit routines are:

• DGAXRACT for IBM RACF and CA-TOP SECRET• DGAXACFT for CA-ACF2• DGAXSAFT for CA-ACF2 using the Security Access Facility• DGAXSBRX

An IBM Connect:Direct Stage 2 Exit, DGAXSBRX can be used on the SNODE as RUN TASK EXIT to restrictand reject the use of RUN TASK function. As an exception, node names of PNODEs that are allowed toexecute this function on this SNODE are defined in a table. If the nodename in process matches an entryin the table the function is allowed to continue otherwise the process is rejected with a return code of 8and msgid of SVTM667I.

You can use the sample exit as a model to implement specific requirements.

IBM Connect:Direct Secure Point-of-EntryYou need security on the local node because adjacent nodes need access to local nodes in order totransfer files. IBM Connect:Direct administrators have three options for security on transfers initiated at aremote node:

• No security for either functional authority or data protection• Matching user ID/password combinations for all adjacent nodes• SNODEID/SNODE password overrides on incoming access requests

Point-of-entry security secures the entry of an outside user to your system. It works with your currentsecurity setup (including all current exits) to provide additional security that addresses concerns aboutusers from other nodes knowing a user ID and password combination on your system. Both dataprotection and IBM Connect:Direct functional authority are accomplished with exits.

Point-of-Entry Processing is internal within IBM Connect:Direct, and happens prior to calling the securityexit for validations.

The following figure illustrates the flow of security checking for secure point-of-entry:

210 IBM Connect:Direct for z/OS: Documentation

Security checks are made automatically for every incoming Process, so no parameter is needed toactivate point-of-entry security. To implement point-of-entry, add user ID and node name combinationsto your Authorization file. For instructions on manipulating the IBM Connect:Direct Authorization file, seeAuthorization File.

The security exit determines if a secure point-of-entry translation was performed on a user ID by checkingthe bit SQIDXLAT of the SQCB control block (DGA$SQCB macro in the $CD.SDGAMAC library).

Point-of-Entry ConceptWhen a Process is submitted by another node, the receiving IBM Connect:Direct node has access to theuser ID of the person who submitted the Process and the name of the node of the submitted Process.

For example, the local node is CD.HOUSTON, and a user SMITH submits a Process on CD.CHICAGO tocopy a file to CD.HOUSTON. By placing an entry of SMITH/CD.CHICAGO into the local IBM Connect:Directauthorization file, the security administrator for CD.HOUSTON can associate this user with a valid user IDand password on the local system. The IBM Connect:Direct Authorization file has the following values:

USERID = SMITHNODE = CD.CHICAGOSECURITY ID = JONESSECURITY PSWD = DALLAS

In this scenario, when user ID SMITH on node CD.CHICAGO submits a Process to run with nodeCD.HOUSTON, the functional authority and the data set validation for that Process are done under theauthority of user ID JONES, which is a valid user ID on CD.HOUSTON. The user from the Chicago nodenever needs to know the related valid user ID and password on the CD.HOUSTON node.

USERID = SMITHNODE = CD.HOUSTONSECURITY ID = JONESSECURITY PSWD = DALLAS

Chapter 4. Administration Guide 211

Secure Point of Entry Optional VariationsNote the following variations:

• If the CD.HOUSTON node enables SNODEID overrides and user SMITH puts an SNODEID parameter inthe Process, the Authorization file is not checked and the translation of the user ID and password is notdone.

Note: If the INVOKE.SPOE.ON.SNODEID initialization parameter is set to YES, then the Authorizationfile is checked and the user ID and password are translated.

For example, if the incoming Process in the previous example is coded with SNODEID=(BROWN,PWB),even if it is submitted by SMITH from CD.CHICAGO, the CD.HOUSTON node will send the user IDBROWN, not user ID JONES to the security subsystem for validation.

Note: To produce a completely secure point-of-entry security system, disable SNODEID overrides. Todisable SNODEID overrides, specify SNODEID=NO in your stage 2 security exit.

• Although the point-of-entry system requires some maintenance of the Security ID and SecurityPassword fields in the Authorization file, you can assign the same user ID and password combination onyour system to multiple incoming users.

For instance, you can specify JONES/DALLAS as the user ID and password for all users coming intoyour node from CD.CHICAGO. In addition, if you are running a stage 1 signon exit, you can specify thesecurity password for all users as IUI, BATCH, or STC, and avoid the need to update the Authorizationfile as the password changes.

• IBM® IBM Connect:Direct® for OpenVMS is not able to pass an OpenVMS password with the OpenVMSuser ID. If you are using secure point-of-entry with incoming OpenVMS nodes, you must leave the UserPassword field blank in your z/OS authorization file, or all incoming OpenVMS Processes will fail.

Trusted Node SecurityThe Trusted Node Security feature enables you to enforce more restrictive security parameters whendealing with specific nodes in your network, enabling you to define each adjacent node in the networkmap as internal or external in its relationship to the local node of that network map.

When a Process begins execution, the security exit gets control and a bit in the Security Control Block(SQCB), SQEXTNOD, turns on if the adjacent node is defined as EXTERNAL. If the adjacent node is definedas INTERNAL, the bit turns off. Based on this information, the administrator can code the security exit totake the appropriate action.

In the adjacent node definition, the fifth positional parameter is required for the Trusted Node Securityoption. The parameter description follows:

Parameter Description

EXTERNAL|EXT Indicates that the node is external.

INTERNAL|INT Indicates that the node is internal. This value is the default.

Cross-Domain Signon EnvironmentThe cross-domain signon environment is an extension of the Trusted Node Security feature. This featureenables you to easily identify whether a signon is entering from an internal or external node.

You can use the same network map parameters for cross-domain Trusted Node Security as the node-to-node Trusted Node Security enhancement, for example, EXTERNAL or INTERNAL in the adjacent nodedefinition. The SQEXTSGN bit in the security exit Control Block (SQCB) designates this feature.

When a cross-domain signon is entering from a node defined as EXTERNAL in the local node network mapdefinition, the SQEXTSGN bit is on when the security exit gets control during signon processing. You canthen modify the security exit to take whatever action is appropriate for that installation.

212 IBM Connect:Direct for z/OS: Documentation

The DGASECUR macro, included in the $CD.SDGASAMP library, contains the code to implement thisenhancement. The lines of code with 117200 identify the Trusted Node Security feature in the cross-domain signon environment.

Data Direction RestrictionIn addition to the Trusted Node feature, the Data Direction Restriction specifies whether each adjacentnode can initiate a RECEIVE, SEND, or RECEIVE and SEND to or from the local node in the network map.The bits located in the SQCB, SQRECV, and SQSEND indicate the sending and receiving status.

In the adjacent node definition, the sixth positional parameter enables you to restrict the direction ofdata on a transfer with a specific adjacent node. This security applies regardless of where the Process issubmitted, for example, local or remote node. The parameter descriptions follow:

Parameter Description

RECEIVE|RECV Indicates that when the adjacent node initiates a transfer, it is only allowed toreceive data from this node. It is never allowed to send data to this node.

SEND Indicates that when the adjacent node initiates a transfer, it is only allowed to senddata to this node. It is never allowed to receive data from this node.

BOTH Indicates that when the adjacent node initiates a transfer, it is allowed to both sendand receive data from this node. This value is the default.

NONE Indicates that when the adjacent node initiates a transfer, it is neither allowed tosend or receive data from this node.

The following example represents the Trusted Node Security and Data Direction Restriction featuresdefined in the network map. The parameters are the fifth and sixth positional parameters in the adjacentnode definition.

LOCAL.NODE=(CD.LOCAL LOCAPPL,,SUPUSRPW) - TCQ=(CD.TCX CD.TCQ))ADJACENT.NODE=(PARSESS=(4 2) (CD.LOCAL LOCAPPL - APPLIDS=(1011 1012 1013))ADJACENT.NODE=(PARSESS=(4 2) - (CD.REMOTE RMTAPPL , , , EXTERNAL,RECV) - APPLIDS=(1011 1012 1013))

The following two bits are identified in the security exit:

Bit Description

SQSNODE Identifies if the node where the security exit is running is the SNODE for thisProcess. The bit is on if the node is the SNODE and off if the node is the PNODE.

SQIDXLAT Identifies if a point-of-entry security ID translation was performed prior to callingthe security exit. If a PNODEID/SNODEID is not specified when the Process issubmitted and a match is found in the Authorization file for that USERID and NODEcombination, then the bit turns on when the security exit gets control.

Implementing a CA-ACF2 EnvironmentWhen assembling both the stage 1 signon exit and the stage 2 security exit, you must provide thefollowing data definition (DD) statements.

1. For the assembly step, ensure that the SYSLIB concatenation contains the following information:

Chapter 4. Administration Guide 213

//SYSLIB DD DSN=ACF.MACLIB// DD DSN=$CD.SDGAMAC// DD DSN=SYS1.MODGEN// DD DSN=SYS1.MACLIB

2. Replace $CD with the high-level qualifier for your IBM Connect:Direct data sets.3. For the link-edit step, provide the following DD statements.

//SYSLIB DD DSN=SYS1.ACFMOD// DD DSN=SYS1.ACFAMOD// DD DSN=$CD.SDGALINK

Note: You must have the High-Level Assembler for correct assembly. Do not specify NOALIGN as anoption. The correct option is ALIGN.

4. Specify the IBM Connect:Direct DTF logon ID (LID) with the following attributes:

LID Attribute Comment

MUSASS Required for ACF2.

NON-CNCL Only required if you are not running DGAMGSAF.

NO-SMC Required.

SECURITY Only required if NEWPASS=YES is specified for the stage 2 security exit.

ACCOUNT Only required if NEWPASS=YES is specified for the stage 2 security exit.

JOBFROM Only required if the Run Job statement is allowed and the Run Job exit is active.

STC Required if IBM Connect:Direct is run as a started task.

RESTRICT Optional.

PROMPT Optional. Enables IBM Connect:Direct to receive prompts from the operatingsystem. For example, with the PROMPT attribute, IBM Connect:Direct receivesa prompt for the password of a password protected data set if it was not suppliedin the COPY statement DSN=filename/password.

If you are executing IBM Connect:Direct as a started task, CA-ACF2 monitors started tasks and theIBM Connect:Direct logon ID specifies STC=YES. See the GSO OPTS field STC/NOSTC in the CA-ACF2Administrator's Guide for more information.

If you are using the program-pathing facility of CA-ACF2 that requires that the user logon ID be definedwith the RESTRICT and SUBAUTH attributes, then the program name specified in the PROGRAMattribute for the user logon ID must be BPXPTATT for IBM Connect:Direct authorization.

The SAF interface requires definitions (SAFDEF) for both BPXPTATT and DGADRNT$.

Implementing an IBM RACF EnvironmentWhen assembling both the stage 1 signon exit and the stage 2 security exit, you must provide thefollowing DD statements.

1. For the assembly step, ensure that the SYSLIB concatenation contains the following information:

//SYSLIB DD DSN=$CD.SDGAMAC// DD DSN=SYS1.MODGEN// DD DSN=SYS1.MACLIB

2. Replace $CD with the high-level qualifier for your IBM Connect:Direct data sets.3. For the link-edit step, provide the following DD statement.

214 IBM Connect:Direct for z/OS: Documentation

//SYSLIB DD DSN=$CD.SDGALINK

Note: You must have Assembler H or the High Level Assembler for correct assembly. Do not specifyNOALIGN as an option. The correct option is ALIGN.

4. Observe the following restrictions or requirements:

• If the z/OS Task Control Block (TCB) Extension Feature is installed, give IBM Connect:Direct updateauthority to IBM Connect:Direct system files, such as the TCQ and network map. These prerequisitesallow IBM Connect:Direct to use the Security Access Facility (SAF) of z/OS.

• If you are using the IBM RACF PROGRAM ACCESS authority to set up access authority by programname and user ID, define the program name DMGATTIS to IBM RACF for IBM Connect:Direct.

Providing Program Access to Data Sets (PADS)If your system has z/OS UNIX System Services or if you use PADS functionality in your security system,include all data sets in the IBM Connect:Direct JCL STEPLIB DD concatenation in your Program ControlList (PCL). If any data set in the STEPLIB concatenation is not in the PADS list, the “dirty bit” will beturned on, and IBM Connect:Direct initialization will fail and display message SITA997I. Use the followingprocedure:

1. Type the following command to display the data sets (libraries) in the PCL.

rlist program *

The access-controlled data sets are displayed.

CLASS NAME----------- -----PROGRAM *MEMBER CLASS NAME--------- ------ ------PMBRDATA SET NAME VOLSER PADS CHECKING-------------------------- ------- ----------------CEE.SCEERUN NOTCPIP.SEZALINK NOUSER01.HOST4100.LOADLIB NO

2. Define the IBM Connect:Direct libraries to IBM RACF PADS. The following screen is an example of adefinition.

RDEFINE PROGRAM ** UACC(READ) ADDMEM + ('$CD.LOADLIB'//NOPADCHK)SETROPTS WHEN(PROGRAM) REFRESH

Note: Refer to the IBM RACF documentation to verify IBM RACF command formats and keywords.

Implementing a CA-TOP SECRET EnvironmentWhen assembling both the stage 1 signon exit and the stage 2 security exit, you must provide thefollowing DD statements.

1. For the assembly step, ensure that the SYSLIB concatenation contains the following information:

//SYSLIB DD DSN=$CD.SDGAMAC// DD DSN=SYS1.MODGEN// DD DSN=SYS1.MACLIB

2. Replace $CD with the appropriate high-level qualifier for your IBM Connect:Direct data sets.

Chapter 4. Administration Guide 215

3. For the link-edit step, provide the following DD statements.

//SYSLIB DD DSN=$CD.SDGALINK

Note: You must have Assembler H or the High-Level Assembler for correct assembly. Do not specifyNOALIGN as an option. The correct option is ALIGN.

4. Add IBM Connect:Direct as a CA-TOP SECRET Facility.5. Observe the following restrictions or requirements:

• If you are using CA-TOP SECRET Release 4 or later, issue the following commands.

TSS CREATE(NDM) NAME('...') DEPT(...) MASTFAC(NDM) FAC(STC) PASSWORD(NOPW)TSS ADDTO(STC) PROC(NDM) ACID(NDM)TSS PERMIT(NDM) DSN(NDM) ACCESS(ALL)

Issue TSS MODIFY commands to obtain the following list of attributes.

NDM PGM=DMG ID=your choiceATTRIBUTES=ACTIVE, SHRPRF, ASUBM, MULTIUSER, NOXDEF, SIGN(M) NORNDPW NOAUDIT, RES, NOABEND, NOPROMPT, NOTSOC

• If you are using CA-TOP SECRET Release 4 or later, and if the z/OS TCB Extension Feature isinstalled, IBM Connect:Direct only needs update authority to its system files, such as TCQ andnetwork map. These prerequisites allow IBM Connect:Direct to use the SAF of z/OS. Otherwise,the ACID referenced previously must provide full access authority to all files IBM Connect:Directaccesses. Alternatively, you can identify IBM Connect:Direct in the privileged program name table ashaving access to all files by setting bit 6 (bypass password checking) in the program properties table(IEFSDPPT) to 1.

Configuring Firewall NavigationFirewall navigation enables controlled access to a IBM Connect:Direct system running behind a packet-filtering firewall without compromising your security policies or those of your trading partners. You controlthis access by assigning a specific TCP source port number or a range of source port numbers with aspecific destination address (or addresses) for IBM Connect:Direct sessions.

Before you configure source ports in the IBM Connect:Direct initialization parameters, you need to reviewthe information in this section.

1. Coordinate IP address and associated source port assignment with the local firewall administratorbefore updating the firewall navigation record in the initialization parameters file.

2. Add the following parameters to the IBM Connect:Direct initialization parameters file as needed:

• TCP.SRC.PORTS• TCP.SRC.PORTS.LIST.ITERATIONS

In a IBM Connect:Direct/Plex environment, specify these parameters in the local initializationparameters file of the IBM Connect:Direct/Plex member that communicates with an external firewall.

3. Reinitialize Connect:Direct for z/OS.4. Coordinate the specified port numbers with the firewall administrator at the remote site. These ports

must also be available for IBM Connect:Direct communications on the firewall of your trading partner.

Firewall Navigation Rules OverviewFirewall rules need to be created on the local firewall to allow the local IBM Connect:Direct node tocommunicate with the remote IBM Connect:Direct node. A typical packet-filtering firewall rule specifies

216 IBM Connect:Direct for z/OS: Documentation

that the local firewall is open in one direction (inbound or outbound) to packets from a particular protocolwith particular local addresses, local ports, remote addresses, and remote ports.

TCP Firewall Navigation RulesIn the following table, the TCP rules are presented in two sections: the first section applies to rules thatare required when the local node is acting as a PNODE; the second section applies to rules that arerequired when the local node is acting as an SNODE. A typical node acts as a PNODE on some occasionsand an SNODE on other occasions; therefore, its firewall will require both sets of rules.

TCP PNODE Rules

Rule Name Rule Direction Local Ports Remote Ports

PNODE session Outbound Local IBM Connect:Directsource ports

Remote IBMConnect:Direct listeningport

TCP SNODE Rules

Rule Name Rule Direction Local Ports Remote Ports

SNODE session Inbound Local IBM Connect:Directlistening port

Remote IBMConnect:Direct sourceports

Firewall Configuration ExamplesIn the firewall configuration examples for TCP the following IP addresses and source ports will be used:

Note: The IP addresses in the examples are samples and are not intended to be valid IP addresses.

• The local node has IP address 222.222.222.222 and listening port 2264. Its source ports forcommunicating with the remote node are 2000–2200.

• The remote node has IP address 333.333.333.333 and listening port 3364. Its source ports forcommunicating with the local node are 3000–3300.

TCP Firewall Configuration ExampleThe IBM Connect:Direct administrator configures the local node to listen on port 2264, and the followinginitialization parameter settings are used to configure the local node's source ports:

• TCP.SRC.PORTS = (333.333.333.333, 2000–2200)• TCP.SRC.PORTS.LIST.ITERATIONS = 1

This configuration specifies to use a source port in the range 2000–2200 when communicating with theremote node's address 333.333.333.333 and to search the port range one time for an available port. Thelocal node will act as both a PNODE and an SNODE when communicating with the remote node.

Based on this scenario, the firewall rules for the local node are the following:

Rule Name Rule Direction Local Ports Remote Ports

PNODE session request Outbound 2000–2200 3364

SNODE session Inbound 2264 3000–3300

Chapter 4. Administration Guide 217

Session EstablishmentSession establishment affects how you set up firewall rules and configure the firewall navigationinitialization parameters in IBM Connect:Direct.

TCP Session EstablishmentA IBM Connect:Direct TCP client contacts a IBM Connect:Direct TCP server on its listening port. The IBMConnect:Direct client scans the list of ports (specified using the TCP.SRC.PORTS initialization parameter)and looks for a port to bind to. The number of times IBM Connect:Direct scans the list is specified usingthe TCP.SRC.PORTS.LIST.ITERATIONS initialization parameter. If IBM Connect:Direct finds an availableport, communication with the remote node proceeds.

Common Problems in Establishing a SessionThe following message indicates that IBM Connect:Direct cannot find an idle port.

SCPA001I - TGT.ADDR=nnn.nnn.nnn.nnn, TCP.SRC.PORTS exhausted

If this message occurs frequently, increase the pool of available ports.

You may need to reserve ports in TCP/IP to ensure they are available for firewall navigation. Reserve portswith the PORT statement in IBM TCP/IP. An example follows:

PORT 5000 TCP connect-jobname NOAUTOLOG ; Connect:Direct Firewall pool 5001 TCP connect-jobname NOAUTOLOG ; Connect:Direct Firewall pool 5002 TCP connect-jobname NOAUTOLOG ; Connect:Direct Firewall pool 5003 TCP connect-jobname NOAUTOLOG ; Connect:Direct Firewall pool 5004 TCP connect-jobname NOAUTOLOG ; Connect:Direct Firewall pool 5005 TCP connect-jobname NOAUTOLOG ; Connect:Direct Firewall pool

A pool of available ports that is too small can affect performance because the outbound connections arelimited.

Troubleshooting Security ErrorsSecurity errors can show up at signon, at Process start, or at any step of a Process. In general, a returncode of 8 means that the error occurred on the PNODE, and a return code of C means the error occurredon the SNODE. This section tells you how to determine the cause of security errors.

Many IBM Connect:Direct security-related messages begin with the prefix RACF. This fact does not meanthat IBM RACF was necessarily involved with the failure. It is merely a naming convention for IBMConnect:Direct message identifiers.

Often, it is helpful to run a security trace to determine exactly where and why a security failure occurred.See Security Traces, for information on security traces.

Condition: Signon DeniedWhen you sign on from either batch or the IUI, you receive the a message that indicates the Stage 1Signon Exit has failed.

218 IBM Connect:Direct for z/OS: Documentation

Error Cause Action Collect

RACF0971 The Stage 1 Signonexit, DGACXSIG, failedto execute properly.

In the Connect:Directfor z/OS IUI, verify thatDGACXSIG is in an APFauthorized library andcorrectly allocated.

Review both the shorttext and long textIBM Connect:Directmessages. If you arereceiving the messageduring signon to theIUI, run a batch jobafter verifying thatDGACXSIG is availableto the job. For eitherbatch or interactivesignon, allocate theAPISECUR DD asdescribed in SecurityTraces. You will be ableto view the progressionof BLDLs, along withoutput showing whereIBM Connect:Directlooked for DGACXSIGand the results from thesearch.

• Output written to the APISECUR DDwhen you allocated APISECUR asdescribed in Security Traces.

Condition: Lack Authority to Perform a Connect:Direct for z/OS FunctionYou attempt to perform a Connect:Direct for z/OS function but receive a message that says you are notauthorized to perform that function.

Error Messages

SCBB001I SCBC030I SCBD001I SCBE001I SCBF001I SCBF063I

SCBF064I SCBG001I SCBH001I SCBI001I SCBJ001I SCBK005I

SCBL001I SCBN001I SCBO001I SCBP001I SCBR002I SCBS001I

SCBT005I SCBU003I SCBV001I SCBW001I SCBX001I SCBY001I

SCPA008I SFIA002I SFIA003I SRJA014I SRTA008I SSUB100I

Chapter 4. Administration Guide 219

Cause Action Collect

If you are running a Stage 2security exit, your user ID isdefined using an authorizationbit mask that does not includethe function you are attempting.A security trace will show youthe general category of IBMConnect:Direct user assignedto your userid (administrator,operator, or general user).See Security Traces for moreinformation about how to initiate asecurity trace. If you are using theIBM Connect:Direct authorizationfile, the functional authority ofyour userid does not include thefunction you are trying to perform.

Review both the short text andlong text IBM Connect:Directmessages. Have the IBMConnect:Direct administratorat your site ensure thatyour userid has the authoritynecessary to perform thefunction, either by updatingyour userid record in the IBMConnect:Direct authorizationfile or by assigning theauthority. within the Stage 2security exit

Output from a security traceshowing the validation of yourauthority to perform the IBMConnect:Direct function

Condition: Access Denied to File or Data Set on COPY StepYou are denied access to a data set or a file on a COPY step.

Error Cause Action Collect

RACF095I The security subsystemeither on your node(RC=8) or the remotenode (RC=C) has deniedyour userid access to thedata set.

Review both the shorttext and long text IBMConnect:Direct messages.Ensure that your useridhas the correct accessto the data set. Ifyou continue getting thismessage, run a securitytrace. See Security Tracesfor more informationabout how to initiate asecurity trace. It mightbe necessary to use aPNODEID or SNODEIDstatement to send a validuserid and password tothe security system.

• Output from a security trace

Condition: User Record not Found in the Authorization Data SetWhen you sign on to IBM Connect:Direct or submit a Process to another node, you receive messageSAFA002I, The user record was not found in the Authorization Data Set.

220 IBM Connect:Direct for z/OS: Documentation

Error Cause Action Collect

SAFA002I If you are usingthe IBM Connect:Directauthorization file forsecurity, be aware thatthe key to that file isa combination of useridand node name. Forexample, if you aresigned on to node CDAwith userid USERA andtransmitting to nodeCDB (not using anSNODEID override), theauthorization file onCDB must have an entryfor the userid USERAand node CDA.

Review both the shorttext and long textIBM Connect:Directmessages. Checkthe appropriateIBM Connect:Directauthorization fileand verify thatthe correct userid/node combinationis specified. Userrecords in theIBM Connect:Directauthorization file canbe added or modifiedwith the Insert Useror Update Usercommands.

None

Maintaining User AuthorizationThe IBM Connect:Direct Authorization Facility controls access to IBM Connect:Direct functions. It is analternative source of security information to the Stage 1 Signon and Stage 2 Security exits. If you use theAuthorization Facility, you must identify all IBM Connect:Direct users in all nodes that execute Processes.

The following example shows how the IBM Connect:Direct Authorization Facility is used. This exampleincludes two IBM Connect:Direct nodes, called SYSTEMA and SYSTEMB. Joe has access to SYSTEMAunder the IBM Connect:Direct user ID of JOEA and access to SYSTEMB under the IBM Connect:Direct userID of JOEB.

Joe requires two entries in the Authorization Facility of each system, as illustrated in the following tables.These entries give him access to IBM Connect:Direct on both systems and the authorization to move filesbetween both systems.

SYSTEMA Authorization FIle

Node User ID Password Authorized Functions

SYSTEMA JOEA [pswd] Y,Y,N,Y . . . . .

SYSTEMB JOEB [pswd] N,Y . . . . .

SYSTEMB Authorization FIle

Node User ID Password Authorized Functions

SYSTEMA JOEA [pswd] Y,Y,N,Y . . . . .

SYSTEMB JOEB [pswd] N,Y . . . . .

The combination of logical node name and user ID is used to access the Authorization file on the remotenode to obtain the user ID, password, and associated functional authority.

For example, if Joe sent a file from SYSTEMA to SYSTEMB, the combination of SYSTEMA and JOEAenables him to access the authorization file on SYSTEMB. This entry then determines what IBMConnect:Direct functional authority Joe has on SYSTEMB when coming from SYSTEMA.

Chapter 4. Administration Guide 221

Note: The password is optional, but if specified in the Authorization Facility, you must specify it onthe SIGNON command. Make the password available at Process execution time through the signon orSNODEID override.

Authorization FileThe Authorization file contains user attribute default records. Each record defines which IBMConnect:Direct features the user can access for each node.

Individual users can access the User Authorization screen to display information about their ownauthorization record. The following table describes the User Authorization file maintenance commands:

Command Description

INSERT USER Inserts a User record in the Authorization file.

UPDATE USER Updates a User record in the Authorization file.

DELETE USER Deletes a User record from the Authorization file.

SELECT USER Selects a User record from the Authorization file.

You can execute these commands through the batch interface, the Interactive user interface (IUI), or theoperator interface.

INSERT USER and UPDATE USER CommandsThe INSERT USER and UPDATE USER commands add or update a user in the IBM Connect:DirectAuthorization file. The commands have the following format and parameters. The required parametersand keywords are in bold. (The NAME parameter is required only for INSERT USER.) Default values forparameters and subparameters are underlined.

Label Command Parameters

(optional) INSert USER | UPDate USER USERID = (nodename, user ID)

NAME ='username'

ADD TYPE = Y | N

ALTER TYPE = Y | N

READ TYPE = Y | N

REMOVE TYPE = Y | N

ADD USER = Y | N

ALTER USER = Y | N

READ USER = Y | N

REMOVE USER = Y | N

CASE = Y | N

CDEL = Y | N

Note: Valid only in the Interactive user interface.

CDELOFF = Y | N

Note: Valid only in the Interactive user interface.

222 IBM Connect:Direct for z/OS: Documentation

Label Command Parameters

CHange = Y | N

Note: The setting for this parameter overrides the settingspecified for the GEN.CHG.PROCESS parameter.

COPY = Y | N

DELPR = Y | N

Note: The setting for this parameter overrides the settingspecified for the GEN.DEL.PROCESS parameter.

EVENTCMD = Y | N

FLUSH = Y | N

Note: The setting for this parameter overrides the settingspecified for the GEN.FLS.PROCESS parameter.

GEN.CHG.PROCESS = Y | N

Note: Valid only in the Interactive user interface.

GEN.DEL.PROCESS = Y | N

Note: Valid only in the Interactive user interface.

GEN.FLS.PROCESS = Y | N

Note: Valid only in the Interactive user interface.

GEN.SEL.PROCESS = Y | N

Note: Valid only in the Interactive user interface.

GEN.SEL.STATISTICS = Y | N

Note: Valid only in the Interactive user interface.

GVIEW = Y | N

Note: Valid only in the Interactive user interface.

MAXSA = max signon attempts

MODALS = Y | N

MODIFY = Y | N

NSUBMIT = Y | N

OVCRC = Y | N

PASSword = initial password

PHone = 'phone number'

PTKTDATA = (APPL profile name, secured signon key)

RESETSA

RUNJOB = Y | N

RUNTASK = Y | N

SECURERD= Y | N

Chapter 4. Administration Guide 223

Label Command Parameters

SECUREWR = Y | N

SECURITY = (security id, security pswd)

SELNET = Y | N

SELPR = Y | N

Note: The setting for this parameter overrides the settingspecified for the GEN.SEL.PROCESS parameter.

SELSTAT = Y | N

Note: The setting for this parameter overrides the settingspecified for the GEN.SEL.STATISTICS parameter.

STATCMD = Y | N

STOPCD = Y | N

SUBMIT = Y | N

SUBMITTER.CMDS = ( Y | N, Y | N, Y | N, Y | N, Y | N )

Note: This parameter is valid only in the batch interface.

UPDNET = Y | N

REFSH = Y | N

Note: This parameter updates the INITPARM file.

VIEW PROCESS = Y | N

Note: The setting for this parameter overrides the settingspecified for the GEN.VIEW.PROCESS parameter.

CERTUSERAUTH = Y | N

READ PROCLIB = Y | N

ALTER PROCLIB = Y | N

READ FILEAGENT = Y | N

ALTER FILEAGENT = Y | N

EXTERNAL.STATS = Y | N

Required ParametersThe following parameters are required for the INSERT USER command. The USERID parameter is requiredfor the UPDATE USER command, but the NAME parameter is not.

224 IBM Connect:Direct for z/OS: Documentation

Parameter Description

USERID = (nodename,user ID)

Specifies the user node and user ID of the record being added or updated.

nodename specifies the user node of the User record. It is a 1–16 characteralphanumeric string.

Note: Connect:Direct for z/OS does not accept the following characters forthe node name:

• < less than• ¬ logical not• , comma• > greater than• = equal sign• / forward slash• * asterisk• \ backward slash• ' single quote• " double quote• ( open parenthesis• ) close parenthesis

Important: Characters used in Netmap Node Names (or Secure+ NodeNames or Secure+ Alias Names) should be restricted to A-Z, a-z, 0-9 and@ # $ . _ - to ensure that the entries can be properly managed by ControlCenter, Connect:Direct Browser User Interface, or Sterling Connect:DirectApplication Interface for Java (AIJ) programs.

user ID specifies the user ID of the User record. The user ID can contain1–64 characters of any kind.

NAME = ‘username' Specifies the full name of the user. The NAME is a string of 1–20 characters.If blanks are embedded in the NAME parameter, you must enclose the NAMEin single quotation marks. This parameter is not required by the UPDATEUSER command.

Optional Authorization Record ParametersOptional parameters for INSERT and UPDATE USER commands are separated into two categories:authorization record parameters and functional authorization parameters.

The following table describes the authorization record parameters for the INSERT USER and UPDATEUSER commands. You can authorize each user to add, alter, read, or remove a record. Specify theauthorization by indicating the action (ADD, ALTER, READ, REMOVE) followed by the record type. If you donot specify an action for a Type or User record, the action defaults to No.

Parameter Description

ADD TYPE = Y | N Specifies whether the user is allowed to insert new records into the TypeDefaults file.

ALTER TYPE = Y | N Specifies whether the user is allowed to update records in the Type Defaultsfile.

READ TYPE = Y | N Specifies whether the user is allowed to read records from the Type Defaultsfile.

Chapter 4. Administration Guide 225

Parameter Description

REMOVE TYPE= Y | N Specifies whether the user is allowed to delete records from the Type Defaultsfile.

ADD USER = Y | N Specifies whether the user can insert new records into the Authorization file.

ALTER USER = Y | N Specifies whether the user is allowed to update records in the Authorizationfile.

READ USER = Y | N Specifies whether the user is allowed to read records from the Authorizationfile.

REMOVE USER = Y | N Specifies whether the user is allowed to delete records from the Authorizationfile.

Optional Functional Authorization ParametersFollowing are the functional authorization parameters for INSERT USER and UPDATE USER:

Parameter Description

CASE = Y | N Specifies whether accounting data, user ID, password, and data set nameparameters are case sensitive. This choice overrides the case designationselected at session signon, and is in effect only for this command. The defaultis the designation made at session signon.

CDEL = Y | N Specifies whether the Confirm Delete/Suspend/Flush Command promptdisplays for a particular user.

CDELOFF = Y | N Specifies whether the user can turn off the Confirm Delete/Flush/SuspendCommand prompt for the current session. If you do not change the defaultof No to Yes, the user will always see the Confirm Delete/Flush/SuspendCommand prompt and will not be given this option.

CHange = Y | N Specifies whether the user is allowed to use the CHANGE PROCESS command.

COPY = Y | N Specifies whether the user is allowed to use the COPY statement.

DELPR = Y | N Specifies whether the user is allowed to use the DELETE PROCESS command.

EVENTCMD = Y | N Specifies whether the user is allowed to use the Event Services Supportcommands.

FLUSH = Y | N Specifies whether the user is allowed to use the FLUSH PROCESS andSUSPEND PROCESS commands.

GEN.CHG.PROCESS = Y| N

Specifies whether the user can change any Processes or only Processes thatare submitted. If you specify GEN.CHG.PROCESS=Y, the user can only changeProcesses that he or she submitted (valid only in the IUI). Can be overriddenby the CHange parameter setting.

GEN.DEL.PROCESS = Y |N

Specifies whether the user can delete any Processes or only Processes thatare submitted. If you specify GEN.DEL.PROCESS=Y, the user can only deleteProcesses that he or she submitted (valid only in the IUI). Can be overriddenby the DELPR parameter setting.

GEN.FLS.PROCESS = Y |N

Specifies whether the user can flush any Processes or only Processes that theuser submitted. If you specify GEN.FLS.PROCESS=Y, the user can only flushProcesses that he or she submitted (valid only in the IUI). Can be overriddenby the FLUSH parameter setting.

226 IBM Connect:Direct for z/OS: Documentation

Parameter Description

GEN.SEL.PROCESS = Y |N

Specifies whether the user can select any Processes or only Processes thatthe user submitted. If you specify GEN.SEL.PROCESS=Y, the user can onlyselect Processes that he or she submitted (valid only in the IUI). Can beoverridden by the SELPR parameter setting.

GEN.SEL.STATISTICS =Y | N

Specifies whether the user can select any statistics or only statistics forProcesses that the user submitted. If you specify GEN.SEL.STATISTICS=Y, theuser can only select statistics for Processes that he or she submitted (validonly in the IUI). Can be overridden by the SELSTAT parameter setting.

GVIEW = Y | N Specifies whether the user can view only Processes submitted with amatching USERID or all Processes regardless of who submitted them. Canbe overridden by the VIEW PROCESS parameter setting.

MAXSA = max signonattempts

Specifies the maximum number of signon attempts the user is allowed perhour. The range is 0–99. The default is 60. Zero (0) indicates no maximumnumber. (See the RESETSA parameter to see how to temporarily reset thisvalue.)

MODALS = Y | N Specifies whether the user is allowed to use the modal statements IF, ELSE,EIF, GOTO, and EXIT.

MODIFY = Y | N Specifies whether the user is allowed to request traces and modifyinitialization parameters.

NSUBMIT = Y | N Specifies whether the user is allowed to use the SUBMIT statement to submita Process.

OVCRC = Y | N Specifies whether the user is allowed to use the CRC statement to override theinitial CRC settings.

PASSword = initialpassword

Defines the initial password for the user ID. The password is a 1–64 characteralphanumeric string.

PHone = 'phonenumber'

Phone number of the user. Enclose the phone number in single quotationmarks. The quotation marks allow for a space after the area code.

PTKTDATA=(APPL profname, secured signonkey)

Specifies the values required for the Stage 2 security exit to rewrite an IBMRACF PassTicket password. APPL prof name is the value specified when theprofile is defined for the PTKTDATA class. The secured signon key is the valueassociated with the PTKTDATA class and the name specified in the APPL Profname. See Generating IBM RACF PassTickets .

RESETSA Specifies that the signon attempt count is reset to 0. (See the MAXSAparameter to see how to set the signon attempt count.) This parameterenables the user to try to sign on, even if he or she has previously exceededthe maximum number of signon attempts. This parameter is used in theUPDATE USER command only.

RUNJOB = Y | N Specifies whether the user is allowed to use the RUN JOB statement.

RUNTASK = Y | N Specifies whether the user is allowed to use the RUN TASK statement.

SECURERD = Y | N or

SECURE.READ =Y | N

Specifies whether the user can display (read) the Connect:Direct Secure PlusParameters file in Control Center.

SECUREWR = Y | N or

SECURE.WRITE = Y | N

Specifies whether the user can update (write to) the Connect:Direct SecurePlus Parameters file in Control Center.

Chapter 4. Administration Guide 227

Parameter Description

SECURITY = (securityID, security pswd)

Specifies the security ID and security password to identify the fileauthorization of the user. Security support includes CA-ACF2, CA-TOPSECRET, and IBM RACF.

Security ID specifies the 1–64 character security system ID for the user. ThisID must meet the standards of the security subsystem at the location of theuser. The security ID is required if this parameter is specified.

Security pswd specifies the 1–64 character security system password for theuser. This password must meet the standards of the security subsystem at thelocation of the user.

SELNET = Y | N Specifies whether the user is allowed to use the SELECT NETMAP command.

SELPR = Y | N Specifies whether the user is allowed to use the SELECT PROCESS command.

SELSTAT = Y | N Specifies whether the user is allowed to use the SELECT STATISTICScommand.

STATCMD = Y | N Specifies whether the user is allowed to use the STATISTICS COMMANDcommand.

STOPCD = Y | N Specifies whether the user is allowed to use the STOP CD command.

SUBMIT = Y | N Specifies whether the user is allowed to use the SUBMIT statement to defineand submit within a Process.

SUBMITTER.CMDS = (Y| N Y | N Y | N Y | N Y | N)

Specifies whether the user is allowed to issue certain commands concerningthe Processes that he or she submitted (valid only in the batch interface).These commands are:

• SELECT PROCESS• DELETE PROCESS• FLUSH PROCESS• CHANGE PROCESS• SELECT STATISTICS

For more information, see the IUI definitions for these commands inFunctional Authorization Parameters for the INSERT and UPDATE USERCommand . (The IUI definitions begin with GEN and the command name isabbreviated.)

REFSH = Y | N Specifies whether the user is allowed to update the initialization parametersfile in Control Center.

UPDNET = Y | N Specifies whether the user is allowed to use UPDATE NETMAP.

VIEW PROCESS = Y | N Specifies whether the user is allowed to use VIEW PROCESS.

CERTUSERAUTH = Y | N Specifies whether the user can perform certificate authentication for clientAPI connections.

Y — Enables client certificate authentication for a user

N — Disables client certificate authentication for a user

READ PROCLIB = Y | N Specifies whether the user can read Process Library.

User can perform List or Get operations on Process Library when value is Y.

228 IBM Connect:Direct for z/OS: Documentation

Parameter Description

ALTER PROCLIB = Y | N Specifies whether the user can update Process Library.

User can perform List, Add, Delete, Rename or Get operations on ProcessLibrary when value is Y.

READ FILEAGENT = Y |N

Specifies whether the user can read File Agent Configuration.

ALTER FILEAGENT = Y |N

Specifies whether the user can update File Agent Configuration.

EXTERNAL.STATS = Y |N

Specifies whether the user is allowed to use WRITE EXSTATS.

Inserting and Updating Users through the Batch InterfaceTo use the INSERT or UPDATE USER commands from the batch interface, follow this procedure.

1. Place your command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

Example of Adding a User RecordThe following example shows a User record for user ID Smith being added to the Authorization file:

SIGNON USERID=(user ID, password)

INSERT USER USERID=(DALLAS, SMITH) - NAME=’RB SMITH’ PASS=XYZZY - PH=’214 555-5555’ - ADD USER=Y ALTER USER=Y - READ USER=Y REMOVE USER=Y - SUBMIT=Y - SUBMITTER.CMDS=(Y Y Y Y N Y)SIGNOFF

In the example definition, the user Smith can perform the following functions:

• Add users to the Authorization file• Update and read User records• Delete User records• Define and submit Processes for execution• Select, delete, flush/suspend, and change submitted Processes

In the example, Smith cannot perform the Select Statistics command on any Processes, regardless of whosubmitted them. Smith’s initial password is XYZZY, and Smith’s phone number is (817) 555-5555.

Example of Updating a User RecordThe following commands update the record of a user named Smith in the Authorization file.

UPDATE USER USERID=(DALLAS, SMITH) - NAME=’RB SMITH’ - PASS=XYZZY - PH=’214 555-5555’ - ADD USER=Y ALTER USER=Y - READ USER=Y REMOVE USER=Y - CH=Y FLUSH=Y DELPR=Y

With these updates, Smith can perform the following functions:

• Add Users to the Authorization file

Chapter 4. Administration Guide 229

• Update and read User records• Delete User records• Change a Process in the TCQ• Delete an executing Process from the TCQ• Delete an inactive Process from the TCQ

Inserting and Updating Users through the IUIUse the Insert/Update/Select/Delete User Record screen (following) to insert, update, select, or delete arecord. Select option IU from the Administrative Options Menu to access this screen.

CD.ART INSERT/UPDATE/SELECT/DELETE USER RECORD 15:04CMD ==>

FUNCTION ==> SEL ('I'-INS, 'U'-UPD, 'S'-SEL , 'D'-DEL)ENTER USER INFORMATION: NAME ==> ____________________ USER ID ==> ________________________________________________________________ USERNODE==> CD.ART PHONE ==> ______________ PASSWORD==> ________________________________________________________________ SEC ID ==> ________________________________________________________________ SEC PASS==> ________________________________________________________________ MAX SIGNON ATTEMPTS===> 60 PASSTICKET DATA ==> ( ________ , )

DO YOU WANT VALUES FOR THIS COMMAND TO BE CASE SENSITIVE? ==> NO_

DEFINE USER FUNCTIONS: (RESPOND WITH 'Y'-YES OR 'N'-NO)

FLUSH PROCESS => _ SELECT NETMAP => _ UPDATE NETMAP => _ INSERT USER => _ SELECT PROCESS => _ MODALS FUNCTION => _ DELETE USER => _ SUBMIT PROCESS => _ RUNTASK FUNCTION => _ SELECT USER => _ SUBMIT WITHIN PROC => _ INSERT TYPE => _ UPDATE USER => _ RUNJOB FUNCTION => _ DELETE TYPE => _ COPY FUNCTION => _ CONTROL TRACING => _ SELECT TYPE => _ CHANGE PROCESS => _ STOP Connect:Direct=> _ UPDATE TYPE => _ DELETE PROCESS => _ SELECT STATISTICS => _ GEN.FLS.PROCESS => _ STAT COMMAND => _ GEN.DEL.PROCESS => _ RESET SIGNON => N GEN.SEL.PROCESS => _ GEN.SEL.STATISTICS => _ VIEW PROCESS => _ GEN.CHG.PROCESS => _ EVENT COMMAND => _ CRC OVERRIDES => _ GEN.VIEW.PROC => _ CONFIRM DELETE => _ CONFIRM DEL OFF => _ SECURE+ ADMIN => _ SECURE+ COMMANDS => _ UPDATE INITPARM => _ CERT USER AUTH => N READ PROC LIB => _ UPDATE PROC LIB => _ READ FILE AGENT => _ UPDATE FILE AGENT => _ EXT STAT LOGGING => _

The DEFINE USER FUNCTIONS portion of the screen is scrollable. More + or - indicates additional data.Press PF8 to scroll forward. Press PF7 to scroll back. See the description of the INSERT and UPDATEUSER command parameters in “Optional Functional Authorization Parameters” on page 226 for the validvalues of the fields, or press the PF1 key for Help.

Deleting Users from the Authorization FileThe DELETE USER command removes a User record from the Authorization file. Following is the commandformat and parameters. The required parameters and keywords appear in bold print.

Label Command Parameters

(optional) DELete USER WHERE (

USERID = (nodename, user ID) | (list)

)

CASE = YES | NO

230 IBM Connect:Direct for z/OS: Documentation

Parameter Description

WHERE

(USERID = (nodename, userID) | (list) )

This parameter specifies which user records to delete.

USERID = (nodename, user ID) | (list)

This parameter specifies the record to delete from the IBMConnect:Direct Authorization file.

nodename specifies the node ID of the User record that is searched.The nodename is a 1–16 character alphanumeric string.

Note: Connect:Direct for z/OS does not accept the following charactersfor the node name:

• < less than• ¬ logical not• , comma• > greater than• = equal sign• / forward slash• * asterisk• \ backward slash• ' single quote• " double quote• ( open parenthesis• ) close parenthesis

Important: Characters used in Netmap Node Names (or Secure+ NodeNames or Secure+ Alias Names) should be restricted to A-Z, a-z, 0-9and @ # $ . _ - to ensure that the entries can be properly managedby Control Center, Connect:Direct Browser User Interface, or SterlingConnect:Direct Application Interface for Java (AIJ) programs.

The user ID parameter specifies the user ID of the User record. Thecomplete user ID consists of the nodename and the user ID enclosedin parentheses and separated by a comma.

The list parameter specifies a list of user IDs.

CASE is the only optional parameter.

Parameter Description

CASE = Yes | No This parameter specifies whether nodename and user ID parameters are casesensitive. This choice overrides the case designation selected at session signonand is in effect only for this command. The default is the designation made atsession signon.

Deleting Users through the Batch InterfaceTo use the DELETE USER command from the batch interface , follow this procedure.

1. Place your command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

Chapter 4. Administration Guide 231

Example of Deleting a User Record

The following example shows how to delete single and multiple User records:

* DELETES A SINGLE User record DELETE USER WHERE (USERID=(MPLS, SMITH))

* DELETES MULTIPLE User records DELETE USER WHERE (USERID=(DALLAS, JONES), - (MPLS, SMITH), (CHICAGO, BROWN)))

Deleting Users through the IUIYou can delete a user in the IBM Connect:Direct IUI using the Delete A User Record screen or the Insert/Update/Select/Delete User Record screen.

To delete a User record using the Insert/Update/Select/Delete User Record screen, select the IU optionfrom the Administrative Options Menu. See the description of the DELETE USER command parameters forthe valid values of the fields on this screen, or pressthe PF1 key for Help.

You can delete up to four user records simulataneously on the Delete A User Record screen.

To delete a user from the Delete A User Record screen, follow this procedure.

1. Select option DU from the Administrative Options Menu to display the Delete A User Record screen.2. Type the user ID and user node of the records to delete.3. Press ENTER.4. Verify your results.

Selecting User Information from the Authorization FileThe SELECT USER command displays a User record in the Authorization file. You can specify the searchcriteria and the format in which the information is presented.

The command has the following format and parameters. Required parameters and keywords appear inbold. Default values for parameters and subparameters are underlined.

Label Command Parameters

(optional) SELect USER WHERE (

USERID = (nodename, user ID) |

(generic | (list))

EXCLUDE = (AUTH)

)

PRint | TABle

CASE = YES | NO

WHERE is the only required parameter for the SELECT USER command and USERID is the only requiredsubparameter.

232 IBM Connect:Direct for z/OS: Documentation

Parameter Description

WHERE

(USERID = (nodename, user ID) |(generic | list))

EXCLUDE = (AUTH)

This parameter specifies which User records you want toexamine.

USERID = (nodename, user ID) | (generic | list)

This parameter specifies the record to search for inthe Authorization file. This subparameter of the WHEREparameter is required. The complete user ID consists of thenodename and the user ID enclosed in parentheses andseparated by a comma.

nodename specifies the node ID of the User record that issearched. Type a 1–16 character alphanumeric string. If theuser node is not specified, nodename defaults to the IBMConnect:Direct system that receives the command.

Note: Connect:Direct for z/OS does not accept the followingcharacters for the node name:

• < less than• ¬ logical not• , comma• > greater than• = equal sign• / forward slash• * asterisk• \ backward slash• ' single quote• " double quote• ( open parenthesis• ) close parenthesis

Important: Characters used in Netmap Node Names (orSecure+ Node Names or Secure+ Alias Names) should berestricted to A-Z, a-z, 0-9 and @ # $ . _ - to ensurethat the entries can be properly managed by ControlCenter, Connect:Direct Browser User Interface, or SterlingConnect:Direct Application Interface for Java (AIJ) programs.

user ID specifies the user ID of the User record.

generic specifies generic selection of user IDs. To specifyuser nodes and user IDs generically, type a 1–7 characteralphanumeric string with the first character alphabetic, plusan asterisk (*). For instance, if you specify a user ID of B*,examine records for BLACK, BRADFORD, and BROWN.

list specifies a list of user IDs.

EXCLUDE = (AUTH)

This parameter specifies that the function-by-functionauthorization description is not included in the output. Thissubparameter of the WHERE parameter is not required.

The following table describes the optional parameters for the SELECT USER command:

Chapter 4. Administration Guide 233

Parameter Description

PRint | TABle This parameter specifies the output destination.

PRINT specifies that the output of the SELECT USER command is printed ratherthan displayed. Printed output is in tabular format, the same as that produced bythe TABle parameter. Output is routed to the destination specified in the PRINTkeyword of the IBM Connect:Direct SIGNON command.

TABle specifies that the output of the SELECT USER command is stored in atemporary file in tabular format and is displayed upon successful completion ofthe command. The default for the output is TABLE.

CASE = Yes | No This parameter specifies whether parameters associated with nodename anduser ID are case sensitive. This choice overrides the case sensitivity designationselected for the session at signon and is in effect only for this command. Thedefault is the designation made at session signon.

Selecting a User through the Batch InterfaceTo use the SELECT USER command from the batch interface, follow this procedure.

1. Place your command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

The following command searches for user BILL at the local (default) node.

SELECT USER WHERE (USERID=(, BILL))

Selecting a User through the IUI InterfaceThe Select a User Record screen enables you to simultaneously display user information and authorizedfunctions for up to four users. You can also use the Insert/Update/Select/Delete User Record screen(option IU) to select users. See the SELECT USER command parameters in “Selecting User Informationfrom the Authorization File” on page 232 for a description of the valid values for the fields or press PF1 forHelp.

1. From the Administrative Options Menu, select option SU to display the Select a User Record screenand press Enter.

2. Type the user ID and user node for the records you want to view.3. Indicate the output destination, the case sensitivity, and whether you want to exclude the function-by-

function authorization description.4. Press Enter.

Certificate-based Authentication for Client ConnectionsThe API connection certificate authentication feature allows clients to connect to a Connect:Direct serverby using only an SSL/TLS Certificate with a Common Name (CN) specified as a user name.

If the intended client usage does not include submitting a process, the user name does not have to be areal z/OS system user name and only needs to be defined in the Connect:Direct z/OS user authorizationfile. If a process is to be submitted, then user specified in the Common Name (CN) must be a realZ/OS system user or real z/OS system user id must be specified in the Security ID parameter of userauthorization record with Common Name (CN) as user id. You can configure this feature using the userauthorization file of a Connect:Direct node. The API certificate authentication requires no user passwordto be presented.

234 IBM Connect:Direct for z/OS: Documentation

This feature improves password management in large deployments of Connect:Direct, as it removes theextra administrative steps resulting from password usage.

Note: This feature is specific only to API connections. These connections must also be AIJ-based. Whenyou use the authentication feature, ensure that the AIJ version is at least 1.1.00 Fix 000025. Thisversion includes updates that allow blank passwords to be used. This version contains updates that allowblank passwords for systems that use AIJ. These AIJ version requirements also apply if you use theauthentication feature in IBM Control Center. API connection certificate authentication is not supportedfor the IUI/DMBATCH, or the Connect:Direct native C/C++/C# non Java APIs.

Configuring API certificate authenticationClient Authentication must be enabled on the Connect:Direct Secure Plus .Client record. Clientauthentication is not enabled by default in Connect:Direct Secure Plus. During an API connection, apeer certificate is required from Control Center or the AIJ client. That certificate must contain a commonname field of an SSL/TLS certificate whose contents match a Connect:Direct local user record in theConnect:Direct node. That certificate must be imported into Secure Plus key database. You also must usea blank password in order for Connect:Direct to trigger the API certificate authentication process.

A new user authorization parameter CERTUSERAUTH is added to authorization file. The parameterspecifies whether a specific user can log in as a client via API certificate authentication, and it mustbe set to Yes when you configure API certificate authentication.

If you want to allow only specific API connections for certificate authentication, then you must specifythese API connections (Address and Port) in the ALT.COMMunication of the PNODE=SNODE Local NodeNetmap entry.

For example, if only API connections from 10.120.10.130:4399 and 10.120.10.131:4399 are allowed forcertificate authentication, then update the PNODE=SNODE Local Node Netmap entry as displayed below:

$$UPDATE ADJACENT.NODE=(( CDZ.LOCAL M1DEVMW1) - LDNS=ZOSIRV - ENVIRONMENT=ZOS - TCPAPI=(4198,) - PARSESS=(4 2) - APPLIDS=(M1DEVMW2 M1DEVMW3 M1DEVMW4) - ALT.COMM=(ALT.DIR=TOP, - (ALT.ADDR=10.120.10.130 - ALT.PORT=4399,ALT.TYPE=TCP) - (ALT.ADDR=10.120.10.131 - ALT.PORT=4399,ALT.TYPE=TCP) – ))

Maintaining the Type FileThe Type file contains file attribute records. Each record is associated with a Type key. The key is used bythe TYPE parameter in the COPY statement to create new files or access existing files.

The following example illustrates a Copy Process using the TYPE parameter.

COPY1 COPY FROM (DSN=MYFILE) - TO (DSN=YOURFILE TYPE=TEXT)

The Type file serves two purposes:

• Saves retyping parameters such as DCB, DISP, and SPACE within Processes for files with commonattributes.

• Facilitates the use of previously-defined attribute specifications of non-z/OS systems. This usage isespecially useful for remote users who are not familiar with z/OS data set organizations and allocationparameters.

Chapter 4. Administration Guide 235

The Type key that is referenced in the TYPE= parameter must be in the Type file on the destinationsystem, which is the system responsible for allocating the new file.

To maintain the Type file, use the INSERT TYPE, UPDATE TYPE, DELETE TYPE, and SELECT TYPEcommands. Type these commands through the IUI, Batch or Operator interface.

Overriding File AttributesIf you specify file attributes in conjunction with the TYPE parameter on the COPY statement, theparameters in the COPY statement override similar parameters in the Type record. Use this functionalitywhen you want to override a specific Type record subparameter.

Type Keys

Four predefined Type keys are provided to communicate with other IBM Connect:Direct nodes:

• TEXT• DF• DF2• BINARY

The four Type keys contain file allocation information as defined in the following figure.

TYPE KEY => TEXT DISP=(RPL,CATLG,DELETE) DCB=(DSORG=PS,LRECL=255,BLKSIZE=2554,RECFM=VB) SPACE=(TRK,(10,10)) UNIT=SYSDA

TYPE KEY => DF (Data File) DISP=(RPL,CATLG,DELETE) DCB=(DSORG=PS,LRECL=255,BLKSIZE=2554,RECFM=VB) SPACE=(TRK,(10,10)) UNIT=SYSDA

TYPE KEY => DF2 (Data File 2) DISP=(RPL,CATLG,DELETE) DCB=(DSORG=PS,LRECL=80,BLKSIZE=3120,RECFM=FB) SPACE=(TRK,(10,10)) UNIT=SYSDA

TYPE KEY => BINARY DISP=(RPL,CATLG,DELETE) DCB=(DSORG=PS,BLKSIZE=6144,RECFM=U) SPACE=(TRK,(10,10))

INSERT TYPE and UPDATE TYPE CommandsUse the INSERT TYPE command to insert a new Type record into the Type file. Use the UPDATE TYPEcommand to update an existing Type record. These commands use the following format and parameters.The required parameters appear in bold. Default values for parameters are underlined.

Label Command Parameters

(optional) INSert TYPE | UPDate TYPE TYPEKEY=typekey

DCB=(BLKSIZE = no. bytes ,DSORG = (DA | PS | PO | VSAM) ,LRECL = no. bytes ,RECFM = record format)

236 IBM Connect:Direct for z/OS: Documentation

Label Command Parameters

DISP=((NEW | OLD | MOD | RPL | SHR) (,KEEP , CATLG , DELETE) (,KEEP , CATLG , DELETE))

DSNTYPE=PDS|LIBRARY|BASIC|LARGE|EXTPREF|EXTREQ

VERSION=1|2

MAXGENS=0-2000000000

AVGREC=(U|K|M)

DATACLAS=data_class_name

KEYLEN=bytes

KEYOFF=offset_to_key

LIKE=model_data_set_name

LRECL=bytes

MGMTCLAS=management_class_name

RECORG=(KS|ES|RR|LS)

SECMODEL=(profile_name [,GENERIC])

STORCLAS=storage_class_name

SPACE=(CYL | TRK | blk, (prim, sec, (dir)) (,RLSE|,(CONTIG|,)(ROUND|)) (ave_rec_len,(primary_rcds,secondary_rcds))

UNIT=unit type

VOL=SER = volume serial number

IOEXIT=exitname|(exitname[,parameter,parameter...])

Following is the required parameter for the INSERT TYPE or UPDATE TYPE command.

Parameter Description

TYPEKEY=typekey Name associated with the entry being added or updated. The Type key is a 1–8character alphanumeric string. The first character must be alphabetic.

Following are the optional parameters for the INSERT TYPE or UPDATE TYPE command:

Chapter 4. Administration Guide 237

Parameter Description

DCB=([BLKSIZE=no.bytes,DSORG=[DA|PS|PO|VSAM], LRECL=no.bytes,RECFM=record format])

This parameter specifies DCB information associated with the data setname on the COPY statement.

BLKSIZE specifies the length of the block in bytes.

DSORG specifies the file organization. File organizations supported areDA, PS, PO, and VSAM.

LRECL specifies the length of the records in bytes.

RECFM specifies the format of the records in the file. Specify any validformat, such as F, FA, FB, FBA, FBM, FM, U, V, VB, VBA, VBM, and VBS.

Any file attributes specified on the COPY statement take precedenceover those in the Type file. If you do not include attributes on the COPYstatement, attributes in the Type file take precedence. If attributes aredefined in the COPY TO or the Type file, the attributes are taken from theFROM side (source).

238 IBM Connect:Direct for z/OS: Documentation

Parameter Description

DISP=([NEW|OLD|MOD|RPL|SHR][,KEEP|,CATLG|,DELETE][,KEEP|,CATLG|,DELETE])

This parameter specifies the default destination file status on thereceiving node.

The first DISP subparameter specifies the status of the file. Only the OLDand RPL dispositions apply to VSAM files.

NEW (default) specifies that the Process step creates the destination file.

OLD specifies that the destination file existed before the Process beganexecuting and that the Process is given exclusive control of the file.The destination file can be a VSAM file, a SAM file, or a PDS (IBMConnect:Direct for z/OS).

MOD specifies that the Process step modifies the SAM file by adding datato the end of the file. If a system failure occurs when MOD is specified,the system is designed not to restart because data loss or duplication isdifficult to detect.

RPL specifies that the destination file replaces any existing file orallocates a new file. You can specify DISP=RPL for SAM or VSAM files. Ifthe file is VSAM, you must define it with the REUSE attribute. You cannotspecify RPL if VOL=SER is specified.

SHR specifies that the source file existed before the Process beganexecuting and that the file can be used simultaneously by another jobor Process.

The second subparameter specifies the normal termination disposition.It does not apply to VSAM files.

KEEP specifies that the system keeps the file after the Process stepcompletes. If DISP=(NEW,KEEP), you must also specify a volume serialnumber.

CATLG (default) specifies that the system keeps the file after the Processstep completes and places an entry in the catalog.

DELETE specifies that the system deletes the file after the Process stepcompletes.

The third subparameter specifies abnormal termination disposition. Itdoes not apply to VSAM files. This subparameter has no default.

KEEP specifies that the system keeps the file after the Processterminates abnormally.

CATLG (default) specifies that the system keeps the file after the Processstep terminates abnormally and places an entry in the catalog.

DELETE specifies that the system deletes the file after the Process if IBMConnect:Direct terminates abnormally.

The third subparameter specifies abnormal termination disposition. Itdoes not apply to VSAM files. This subparameter has no default.

Chapter 4. Administration Guide 239

Parameter Description

DSNTYPE = LIBRARY | PDS | BASIC| LARGE | EXTPREF | EXTREQ

Specifies the DSNTYPE of a new data set.

LIBRARY specifies a partitioned data set extended (PDSE).

PDS specifies a partitioned data set.

BASIC specifies a sequential data set which can have no more than65535 tracks per volume.

LARGE specifies a sequential data set which can contain more than65535 tracks per volume.

EXTPREF specifies that the extended attribute is preferred. If anextended format data set cannot be allocated, a data set is createdwithout the attribute.

EXTREQ specifies that the extended attribute is required.

VERSION = 1 | 2 Specifies the DSNTYPE VERSION for a new data set. VERSION is onlyallowed when DSN-TYPE=LIBRARY, EXTREQ or EXTPREF.

MAXGENS = 0-2000000000 Specifies the maximum number of generations for a new PDSE V2.

MAXGENS is only allowed when DSNTYPE=LIBRARY and VERSION=2.

AVGREC=(U | K | M) Requests that IBM Connect:Direct allocate the data set in records. Theprimary and secondary space quantities represent the number of recordsrequested in units, thousands, or millions of records. This parameter ismutually exclusive with the TRK, CYL, and ABSTR subparameters of theSPACE keyword.

U specifies a record request where primary and secondary spacequantities are the number of records requested. It is a multiple of 1.

K specifies a record request where primary and secondary spacequantities are the number of records requested in thousands of records.It is a multiple of 1024.

M specifies a record request where primary and secondary spacequantities are the number of records requested in millions of records.It is a multiple of 1,048,576.

DATACLAS=data_class_name Requests the data class for a new data set. The class selected must bepreviously defined by the SMS administrator. You can use this keywordwith VSAM data sets, sequential data sets, or partitioned data sets.

data_class_name specifies the 1–8 character name of the data class towhich this data set belongs. The name of the data class is assigned bythe SMS administrator.

KEYLEN=bytes This parameter specifies the length of the keys in the file. This keyword isnot restricted as a subparameter of the DCB keyword to support use withVSAM KS data sets.

bytes specifies the length in bytes of the keys used in the file. You mustspecify this value with a decimal integer from 0–255 for non-VSAM datasets or 1–255 for VSAM data sets.

240 IBM Connect:Direct for z/OS: Documentation

Parameter Description

KEYOFF=offset_to_key This parameter specifies the offset within the record to the first byte ofthe key in a new VSAM KS data set. The relative first byte of the record isbyte 0. The range is 0–32760.

offset_to_key specifies the position of the first byte of the key in therecord.

LIKE=model_data_set_name Requests that allocation attributes for a new data set are copied froman existing cataloged data set. Any or all of the following attributes arecopied to the new data set: RECORG or RECFM, LRECL, KEYLEN, KEYOFF,DSNTYPE, AVGREC, and SPACE. Any attributes specified for the data setoverride the values from the model data set. Neither EXPDT nor RETPD iscopied from the model data set.

model_data_set_name specifies the name of the data set from which theallocation attributes are copied.

LRECL=bytes This parameter specifies the length in bytes of the records in the newdata set. This parameter is allowed outside of the DCB keyword to allowuse with SMS VSAM data sets. Do not specify LRECL with RECORG=LStype data sets.

bytes specifies the length of the records in the data set. For a non-VSAMdata set, this length is 1–32760 bytes. For VSAM data sets, this lengthis 1–32761 bytes. The LRECL must be longer than the KEYLEN value forVSAM KS data sets.

MGMTCLAS=management_class_name

Determines to which of the previously defined management classes thisnew data set belongs. The attributes in this class determine such thingsas when a data set is migrated and when the data set is backed up.

management_class_name specifies the 1–8 character name of themanagement class to which this data set belongs. The name of themanagement class is assigned by the SMS administrator.

RECORG=(KS|ES|RR|LS) Defines the organization of records in a new VSAM data set. If RECORGis not specified, then SMS assumes that the data set is either a physicalsequential (PS) data set or a partitioned (PO) data set.

KS specifies a VSAM key-sequenced data set

ES specifies a VSAM entry-sequenced data set

RR specifies a VSAM relative record data set

LS specifies a VSAM linear space data set

SECMODEL=(profile_name,GENERIC)

Copies an existing IBM RACF profile as the discrete profile for thisnew data set. The following information is copied along with theprofile: OWNER, ID, UACC, AUDIT/GLOBALAUDIT, ERASE, LEVEL, DATA,WARNING, and SECLEVEL.

profile_name specifies the name of the model IBM RACF profile, discretedata set profile, or generic data set profile that is copied to the discretedata set profile created for the new data set.

GENERIC identifies that the profile_name refers to a generic data setprofile.

Chapter 4. Administration Guide 241

Parameter Description

STORCLAS=storage_class_name This parameter specifies the storage class to which the data set isassigned. The SMS administrator must define the storage class nameto the SMS system by the SMS administrator. The storage class definesa storage service level for the data set and replaces the UNIT andVOLUME keywords for non-SMS data sets. You cannot use JCL keywordsto override any of the attributes in the storage class. You can use anAutomatic Class Selection (ACS) routine to override the specified class.

storage_class_name specifies the 1–8 character name of the storageclass to which this data set is assigned.

SPACE= (CYL | TRK | blk, (prim, [sec],[dir]) [,RLSE |, ][,CONTIG |, ] [,ROUND]) |(ave_rec_len,[primary_rcds,secondary_rcds])

This parameter specifies the amount of storage allocated for new files onthe destination node. If SPACE is specified, the DISP of the destinationfile must be NEW. If SPACE is not specified and the DISP is either NEWor CATLG, space allocation defaults to the value obtained from the sourcefile. The default is blk (blocks) with the ROUND option, which providesdevice-independent space allocation.

If the AVGREC keyword is specified, the allocation of the data set is doneon a record size basis instead of TRK, CYL, or BLK. This restriction is alsotrue when the AVGREC keyword is present in the COPY statement.

CYL specifies that space is allocated in cylinders.

TRK specifies that space is allocated in tracks.

blk specifies that space is allocated by the average block length of thedata. The system computes the number of tracks to allocate. If thesubparameter ROUND is also specified, the system allocates the spacein cylinders. ROUND is preferred because allocation is performed oncylinders in a device-independent manner.

prim specifies the primary allocation of storage.

sec specifies the secondary allocation of storage.

dir specifies the storage allocated for the PDS directory.

RLSE releases the unused storage allocated to the output file.

CONTIG specifies that the storage for the primary allocation must becontiguous.

ROUND specifies that the storage allocated by average block length berounded to an integral number of cylinders.

ave_rec_len specifies the average record length, in bytes, of the data.IBM Connect:Direct computes the BLKSIZE and the number of tracks toallocate. The record length must be a decimal value from 1–65535.

primary_rcds specifies the number of records that the data set contains.IBM Connect:Direct uses this number and the value of the AVGRECkeyword to compute the primary space allocation.

secondary_rcds specifies the number of additional records to allocatespace for when the primary space is exhausted. IBM Connect:Direct usesthis value and the AVGREC keyword to compute the number of tracks toallocate.

UNIT = unit type This parameter indicates the unit address, device type, or user-assignedgroup name that contains the data. For SAM-to-SAM copies, where thedestination file is new and the UNIT parameter is not coded with the TOparameter, the device type from the source file is used.

242 IBM Connect:Direct for z/OS: Documentation

Parameter Description

VOL = SER = volume serial number This parameter specifies the volume serial number containing the file. IfVOL=SER is not specified with the FROM parameter, you must cataloguethe file.

IOEXIT = exitname | (exitname[,parameter, parameter,...])

This parameter indicates that a user-written program is given control toperform I/O requests for the associated data.

exitname specifies the name of the user-written program given controlfor I/O related requests for the associated data. The character length forIOEXIT is a variable of 1–510 characters.

parameter | (parameter,parameter,...) specifies a parameter, or list ofparameters, passed to the specified exit. A parameter consists of a datatype followed by the value in single quotes, for example C'ABC'. For afull description of valid parameter formats, see the RUN TASK statementparameters in the Connect:Direct Process Language help.

Inserting and Updating Type Files through the Batch InterfaceTo use the INSERT TYPE or UPDATE TYPE command from the batch interface, perform the followingsteps:

1. Place your command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

The following example adds a Type record named NEWALLOC to the Type file:

INSERT TYPE TYPEKEY=NEWALLOC - DCB=(DSORG=PS) - DISP=(NEW,CATLG) - UNIT=3380

IBM Connect:Direct users can then use the NEWALLOC Type key in a COPY command to allocate a newphysical sequential file on a 3380 unit device that is cataloged on normal termination.

The following example updates a record in the Type file. When referring to the NEWALLOC Type key,the destination file is an existing PS file allocated on a 3390 disk pack:

UPDATE TYPE TYPEKEY=NEWALLOC - UNIT=3390

Inserting and Updating Type Files through the IUITo access the Type Record Selection List to perform this procedure, follow these steps.

1. Select option IT from the Administrative Options Menu. The Insert/Update Type Record screen isdisplayed.

The Insert/Update Type Record screen prompts you for the action to perform (Insert or Update) andthe Type key.

2. Type the requested information and press ENTER. IBM Connect:Direct displays an error message if youattempt to insert an existing record or update a nonexistent record.

3. From the Type Record Selection List screen, select either the General Dataset Attributes, IOEXITParameters, or the SMS/VSAM Attributes option by typing an S next to the appropriate entry andpressing Enter.

Chapter 4. Administration Guide 243

node.name Type Record Selection List hh:mm CMD ==>

Operation ==> UPDATE Type Key ==> X

_ General Dataset Attributes _ IOEXIT Parameters _ SMS/VSAM Attributes

Select the entries above to view and/or update the respective parameters.

Enter the END command to perform the updates. -or- Enter the CANcel command to abandon your changes.

4. Type END from the Type Record Selection List or select another option to perform the update.5. From the Type Record General Dataset Attributes screen, define or update the file attributes for the

Type record. See “INSERT TYPE and UPDATE TYPE Commands” on page 236 for a description of thefields on this screen you can update.

node.name Type Record General Dataset Attributes hh:mmCMD ==>

(DISP=) Initial file status ==> ___ (SHR,NEW,OLD,MOD,RPL) Normal step termination ==> ______ (KEEP,CATLG,DELETE) Abend step termination ==> ______ (KEEP,CATLG,DELETE)

(DCB=) DSORG ==> ____ LRECL ==> _____ BLKSIZE ==> _____ RECFM ==> ____

(SPACE=) Allocation type ==> __________ (CYL,TRK,Average blksize) Primary extent ==> __________ (Required with CYL,TRK,BLK) Secondary extent ==> ________ (Optional) Directory storage ==> ________ (Optional) RLSE,CONTIG,ROUND ==> ( _ , _ , _ ) ('Y'-Yes, 'N'-No)

(UNIT=) Unitname ==> ________

(VOL=SER=) Volume serial ==> ______

Type the END command to return to the Type Record Selection List.6. The Type Record IOEXIT Parameters screen (a TSO edit screen) enables you to define or update the

IOEXIT parameters associated with the Type record. Refer to the IOEXIT parameter description forvalid values.

node.name Type Record IOEXIT Parameters hh:mm Cmd ==> Scroll ===> PAGE

IOEXIT Specifications (exitname,{parameter,parameter,...})--------------------------------------------------------------------------------- ****** ***************************** Top of Data ******************************* RIOEX01,(C'MAXLEN',X'0120')

****** **************************** Bottom of Data ******************************

After defining or updating the IOEXIT specifications, type the END command to return to the TypeRecord Selection List.

7. The Type Record SMS/VSAM Parameters screen enables you to define or update parameters related toSMS controlled data sets and VSAM files.

244 IBM Connect:Direct for z/OS: Documentation

CD.ART Type Record SMS/VSAM Attributes 16:20 CMD ==>

Operation ==> UPDATE Type Key ==> PDSEV2

(SMS=) Data Class ==> ________ Management Class ==> ________ Storage Class ==> ________

(Other=) EATTR ==> OPT (OPT or NO) DSNTYPE ==> LIBRARY (BASIC, EXTREQ, EX-TPREF, LARGE, LIBRARY, PDS) Version ==> 2 (1 - PDSE V1, 2 - PDSE V2) MAXGENS ==> 1234567890 (0-2000000000)

(MODEL=) Like Data Set Name ==> ____________________________________________ Security Profile ==> ____________________________________________ Generic Profile ==> ___ (YES or NO)

(SPACE=) Average Record Value ==> _ (U, K or M)

(VSAM=) Organization ==> __ (ES - ESDS, KS - KSDS, RR - RRDS, LS - LDS) Key Offset ==> _____ (0 - 32760) Key Length ==> ___ (1 - 255)

After defining or updating the SMS/VSAM attributes, type the END command to return to the TypeRecord Selection List.

DELETE TYPE CommandUse the DELETE TYPE command to delete a Type record from the Type file. Use the following format andparameters. The required parameters and keywords are in bold print.

Label Command Parameters

(optional) DELete TYPE WHERE (TYPEKEY = typekey | (list))

WHERE is the required parameter for the DELETE TYPE command. No optional parameters exist for thiscommand.

Parameter Description

WHERE

(TYPEKEY =typekey | (list))

This parameter specifies which records in the Type file to delete. You can specify oneType key or a list of Type keys.

typekey specifies the name associated with the record being deleted. The Type key is a1–8 character alphanumeric string, with the first character alphabetic.

list specifies multiple Type keys. Specify a list of keys by enclosing them inparentheses.

Deleting Types Files through the Batch InterfaceTo use the DELETE TYPE command from the batch interface, follow this procedure.

1. Place your command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

For example, the following commands delete the records under the Type keys MYALLOC, NEWALLOC,and RPLALLOC from the Type file.

Chapter 4. Administration Guide 245

/* DELETES A SINGLE TYPE RECORD */ DELETE TYPE WHERE (TYPEKEY=MYALLOC)/* DELETES MULTIPLE TYPE RECORDS */ DELETE TYPE WHERE (TYPEKEY=(NEWALLOC RPLALLOC))

Deleting Type Files through the IUITo issue the DELETE TYPE command from the IBM Connect:Direct IUI, follow this procedure.

1. Select DT from the Administrative Options Menu.2. Type in the names of the TYPE KEYs that you want to delete.3. Press ENTER.

A list of the deleted records is displayed. If the delete is unsuccessful, a list of the records not deletedis displayed.

4. Press PF3/END to return to the Delete Data Set Type Defaults screen.5. Use the Delete Data Set Type Defaults message display to verify a successful delete request.

SELECT TYPE CommandThe SELECT TYPE command enables you to examine a record in the Type file. You can specify the searchcriteria and the form in which the information is presented.

The SELECT TYPE command uses the following format and parameters. The required parameters andkeywords are in bold print. Default values for parameters and subparameters are underlined.

Label Command Parameters

(optional) SELECT TYPE WHERE (

TYPEKEY = typekey | generic |(list)

)

PRint | TABle

WHERE is the required parameter for the SELECT TYPE command.

Parameter Description

WHERE

(TYPEKEY =typekey | generic |(list))

This parameter specifies which records in the Type file to select.

TYPEKEY = typekey | generic | (list)

specifies the key or list of keys of the records to select.

typekey specifies the name associated with the record selected. You created thetypekey name when originally adding the entry to the Type file. The typekey is a1–8 character alphanumeric string, with the first character alphabetic.

generic specifies generic selection of type keys. To specify type keys generically,type a 1–7 character alphanumeric string, with the first character alphabetic, plusan asterisk (*). For instance, if your network includes the type keys SENDDAY,SENDMO, and SENDWK, a specification of SEND* provides information about thosekeys.

list specifies multiple type keys. A list of keys is specified by enclosing them inparentheses.

The optional parameter is described below.

246 IBM Connect:Direct for z/OS: Documentation

Parameter Description

PRInt | TABle Parameters specify the method of display for the output of the select.

PRint specifies that the output to a printer in tabular format. Output is routed to thedestination specified in the PRINT keyword of the SIGNON command.

TABle specifies that the output is stored in a temporary file in tabular format andis displayed upon successful completion of the command. This parameter is thedefault.

Example of Selecting a Type RecordThe following command selects a record in the TYPE file.

SELREC SELECT TYPE WHERE (TYPEKEY=DF*)

The output follows.

=========================================================== SELECT TYPE DEFAULTS=========================================================== Type Key => DF Date Created => mm/dd/yyyy

DISP=(RPL,CATLG,DELETE) DCB=(DSORG=PS,LRECL=255,BLKSIZE=2554,RECFM=VB) SPACE=(TRK,(10,10)) UNIT=SYSDA

Selecting Type Records through the Batch InterfaceTo use the SELECT TYPE command from the Batch Interface, follow this procedure.

1. Place your command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Use the output to verify your results.

Selecting Type Records through the IUITo issue the SELECT TYPE command through the IBM Connect:Direct IUI, follow this procedure.

1. Access the Select Data Set Type Defaults screen by selecting option ST from the AdministrativeOptions Menu.

2. Type the typekey for each member you want to select. Refer to the description of parameters for the“SELECT TYPE Command” on page 246, or press PF1 to view the Help.

3. Indicate the output destination in the Output Destination field.4. Provide the requested information and press ENTER.

An output destination of DIS produces a display similar to the following figure.

Chapter 4. Administration Guide 247

BROWSE -- XXXXXXXX.XXXXXXX.XXXXX.XXXXXX.XXXXXX ---- LINE 00000000 COL 001 080 COMMAND ===> SCROLL ===> CSR********************************* TOP OF DATA ********************************============================================================================== SELECT TYPE DEFAULTS============================================================================== Type Key => BINARY Date Created => mm/dd/yyyy

DISP=(RPL,CATLG,DELETE) DCB=(DSORG=PS,BLKSIZE=6144,RECFM=U) SPACE=(TRK,(10,10))__________________________________________________________________________

Type Key => DF Date Created => mm/dd/yyyy

DISP=(RPL,CATLG,DELETE) DCB=(DSORG=PS,LRECL=255,BLKSIZE=2554,RECFM=VB) SPACE=(TRK,(10,10)) UNIT=SYSDA__________________________________________________________________________

Maintaining the Network MapThe network map (also known as the NETMAP) identifies the local IBM Connect:Direct node and thenodes it communicates with. It consists of one local node entry and one or more adjacent node entriesthat identify the communication name and protocol of each IBM Connect:Direct node.

The network map source is generated during installation. The network map load utility, DGADNTLD, usesthis source to create a network map (a VSAM file).

See the IBM Connect:Direct for z/OS Configuration Guide for rules governing the network map for cross-domain VTAM definitions.

Local Node EntryThe local node entry specifies the logical name of the local IBM Connect:Direct and its associatedcommunications name. The local node entry also contains the name of the Transmission Control Queue(TCQ) and the SUPERUSR ID password, if specified. The syntax is displayed in the following figure.

LOCAL.NODE=( - (node name,communications name,,superuser password) - TCQ=(tcxdsn, tcqdsn) - CONTACT.NAME="name" - CONTACT.PHONE="phone information" - DESCRIPTION="description information" - )

248 IBM Connect:Direct for z/OS: Documentation

Local Node Positional ParametersThe network map local node entry contains the following positional parameters.

Parameter Description

node name The first positional parameter is the 1–16 alphanumeric character node name. Itspecifies the logical name of the local IBM Connect:Direct DTF.

Note: Connect:Direct for z/OS does not accept the following characters for thenode name:

• < less than• ¬ logical not• , comma• > greater than• = equal sign• / forward slash• * asterisk• \ backward slash• ' single quote• " double quote• ( open parenthesis• ) close parenthesis

Important: Characters used in Netmap Node Names (or Secure+ Node Names orSecure+ Alias Names) should be restricted to A-Z, a-z, 0-9 and @ # $ . _ - toensure that the entries can be properly managed by Control Center, Connect:DirectBrowser User Interface, or Sterling Connect:Direct Application Interface for Java(AIJ) programs. However, use of ‘@’ characters in a node name is discouraged, as itwill cause some clients to display proxy records incorrectly. If the ‘@’ character isat the end of a node name, client display of a proxy record with this node name willfail.

communicationsname (for SNAonly)

The second positional parameter is the 1–8 character communications name. Itspecifies the VTAM APPLID that IBM Connect:Direct uses to communicate over thenetwork.

If the node uses only TCP/IP communications (SNA=NO is specified in theinitialization parameters), define this parameter as NO-VTAM. Refer to InitializingIBM Connect:Direct without SNA Support in the IBM Connect:Direct for z/OSConfiguration Guide for more information.

null The third positional parameter is not used.

superuserpassword

The fourth positional parameter is the 1–8 character SUPERUSR ID password. Theinitial value for this parameter is specified during installation.

The SUPERUSR ID is provided to bypass your usual security system at signon. Thisbypass can be necessary if IBM Connect:Direct is configured improperly, resultingin the inability to signon. SUPERUSR still goes through usual data set verificationdone by the Stage 2 security exit.

Note: The default SUPERUSR ID is SUPERUSR and it is recommended that youchange it.

Chapter 4. Administration Guide 249

Local Node Keyword ParametersThe network map local node entry contains the following keyword parameters:

Parameter Description

TCQ=

(tcxdsn,tcqdsn)

The TCQ is a VSAM relative record data set (RRDS) that holds allProcesses submitted to IBM Connect:Direct.

The TCQ parameter specifies the two files that comprise theTransmission Control Queue (TCQ). This parameter is required.

Note: Use the correct order (tcxdsn,tcqdsn) when you specify thetwo files.

tcxdsn identifies the data set name of the TCQ index (TCX).

tcqdsn identifies the data set name of the TCQ.

CONTACT.NAME=”name”CONTACT.PHONE=”phone information”DESCRIPTION=”description information”

These are free-form text parameters, which provide additionalgeneral information about an adjacent node entry. TheCONTACT.NAME and CONTACT.PHONE parameters are limited to amaximum of 40 characters. The DESCRIPTION parameter is limitedto a maximum of 255 characters.

When to Define the Local Node as the Adjacent NodeYou must also define the local node as an adjacent node to:

• Specify the VTAM application IDs that are used for IUI and batch sessions. The APPLIDS match thosedefined during installation preparation as described in the IBM Connect:Direct for z/OS ConfigurationGuide.

• Provide the ability to run Processes where the local node is both the initiating and target node (PNODEand SNODE). The communications name matches the APPLID defined during installation preparation.

• Supply the communication address for a TCP API, if it is not specified during the user signon.

If you are using TCP/IP only and SNA is set to NO, refer to Initializing IBM Connect:Direct without SNASupport in the IBM Connect:Direct for z/OS Configuration Guide.

Adjacent Node EntryAdjacent node entries specify network nodes that the local IBM Connect:Direct can communicate with.Each entry specifies a locally used IBM Connect:Direct name, its associated network communications

250 IBM Connect:Direct for z/OS: Documentation

name, and session control parameters for these nodes. The syntax in the following figure is for a typicaladjacent node entry.

ADJACENT.NODE=( - (nodename, - communications name | channel-range-start-addr, - remote library name | IP address or Alias | addr-count, - session type, - security node type, - data direction restriction) - PARSESS=(max,default) - ZFBA = (addr1 , addrn) - COMPRESS.EXT=ALLOW | DISALLOW | FORCE - COMPRESS.STD=ALLOW | DISALLOW | FORCE - COMPRESS.STD.PRIMECHAR=C'x'| X'xx' - SOURCEIP=IP address - FASP=NO|SSP FASP.BANDWIDTH=nnn | nM, nG FASP.FILESIZE.THRESHOLD=nnn | nM | nG FASP.POLICY=FAIR | HIGH | LOW | FIXED SESS.SNODE.MAX = 255 - LDNS=hostname - ENVIRONMENT=operating environment - LOGMODE=logmode entry name - APPLIDS=(vtam applid1 [,vtam applid2,...] ) - BATCHAPPLIDS=(batch.applid1 [,batch.applid2,...] ) - TSO.APPLIDS=(tso.applid1 [,tso.applid2,...] ) - INTERACTIVE.APPLIDS=(interactive.applid1 [,interactive.applid2,...] ) - CICS.APPLIDS=(cics.applid1 [,cics.applid2,...] ) - NETID=networkid | CTCA server name - PNODE.LUS=(luname1 [,luname2,...] ) - SNODE.LUS=(luname1 [,luname2,...] ) - PNODE.LAST.USED=(02.10.2020,09:44:20) - SNODE.LAST.USED=(03.17.2020,16:17:52) - USE.SERVER.NODE = NO | YES - TCPAPI= (port number, IP address) - CRC= (OFF | ON | DEFAULT) - PLEXCLASS= (* | plexclass, * | plexclass) - BUFFER.SIZE= 3072–2097152|3K-2M - ALTernate.COMMinfo = (ALTernate.RESTART=YES | NO, - ALTernate.DIRection=BALANCE | TOP, - (ALTernate.ADDRess= | ALTernate.NODEDEF=, ALTernate.PORT=, - SOURCEIP=IP address, - ALTernate.TYPE=SNA | TCP | LU62 - ALTernate.LOGmode=logmode entry name, - ALTernate.USE.OUTbound=YES | NO) - ) - CDFTP.PLUGIN="name or location of the plugin" - CDFTP.TEMPFILE"fully qualified file path and name" - CONTACT.NAME=”name” - CONTACT.PHONE=”phone information” - DESCRIPTION=”description information”)

In an environment when one IBM Connect:Direct system (either a IBM Connect:Direct/Plex environmentor IBM Connect:Direct/Stand-alone Server) communicates with a IBM Connect:Direct/Plex environment,add the following statement to each ADJACENT.NODE entry that defines the other IBM Connect:Direct/Manager.

ENVIRONMENT=ZOS

Note: When a Connect:Direct for z/OS system communicates with another IBM Connect:Direct systemin a IBM Connect:Direct/Plex environment and ENVIRONMENT=ZOS|OS390 is not specified, Processredirection does not function correctly.

See “TCP/IP Addressing” on page 265 for network map entry requirements for TCP/IP nodes.

See Channel-to-Channel Support for a discussion of channel-to-channel support.

Chapter 4. Administration Guide 251

Positional Parameters for Adjacent Node EntriesThe network map adjacent node entry contains positional and keyword parameters. Following are thepositional parameters for the network map adjacent node entry:

Parameter Description

nodename The first positional parameter is the 1–16 alphanumeric character node name. Thisname represents the partner IBM Connect:Direct and is used in communicationswith the local IBM Connect:Direct. This parameter is required. The node nameis always changed to upper case in the network map, regardless of the remoteplatform.

Note: Connect:Direct for z/OS does not accept the following characters for thenode name:

• < less than• ¬ logical not• , comma• > greater than• = equal sign• / forward slash• * asterisk• \ backward slash• ' single quote• " double quote• ( open parenthesis• ) close parenthesis

Important: Characters used in Netmap Node Names (or Secure+ Node Names orSecure+ Alias Names) should be restricted to A-Z, a-z, 0-9 and @ # $ . _ - toensure that the entries can be properly managed by Control Center, Connect:DirectBrowser User Interface, or Sterling Connect:Direct Application Interface for Java(AIJ) programs.

communicationsname | channel-range-start-addr

The second positional parameter is the 1–8 alphanumeric charactercommunications name. It specifies the network name of the partner IBMConnect:Direct. It can be an SNA VTAM APPLID or a TCP/IP port number. Thisparameter is optional.

For SNA, this field must contain the VTAM APPLID of the remote IBMConnect:Direct node that the local DTF uses for DTF-to-DTF communications withthe remote node.

This name is the same name that is defined for the communications name in thenetwork map of the remote IBM Connect:Direct node.

For OpenVMS and HP NonStop, use the PNODE.LUS and SNODE.LUS parametersand leave this field blank.

For TCP/IP, this field contains the TCP/IP port number of the remote partner IBMConnect:Direct. You do not need to use this field if the partner IBM Connect:Directis initialized using the default TCP/IP port number. This port number does notchange the port number for the host IBM Connect:Direct that is defined atinitialization. See “Multiple Port TCP/IP Listen” on page 267 for more informationabout the TCP/IP port number.

For CTCA, this field contains the CCUU of the first CTCA address used by this node.

252 IBM Connect:Direct for z/OS: Documentation

Parameter Description

remote libraryname | IP addressor Alias | addr-count

The third positional parameter is for the Host ID (DNS), or IP Address, or Libraryname. This is for I5/OS or TCP/IP nodes only.

For I5/OS nodes, this parameter specifies the name of the library where theIBM® Connect:Direct for I5/OS program SMMAIN resides for the partner IBMConnect:Direct.

For TCP/IP nodes, this parameter specifies the IPv4 address (1-15 dotted decimalcharacters), DNS alias name (1-16 alphanumeric characters) or the IPv6 address(1-39 colon separated hexadecimal characters) to establish the TCP/IP session.

For DNS alias names greater than 16 characters, leave this field blank and use theLDNS parameter.

For CTCA, this parameter specifies the number of CTCA addresses used by thisnode. Specify this with an even number value (a minimum of 2).

session type The fourth positional parameter is the session type. It specifies the type of sessioncommunications protocol to use for communications with this adjacent node. Thisparameter is required for i5/OS adjacent nodes and any node using a protocolother than LU0. Valid values are:

SNA (for LU0 protocol)

SNUF (for LU0 protocol for the i5/OS)

LU62 (for LU6.2 protocol)

TCP (for TCP/IP protocol)

CTCA (for Channel to Channel connections)

Note: SNA is the default if this positional parameter is left blank.

security node type The fifth positional parameter is the security node type. It classifies the node asan internal or external node. Specify this parameter for Trusted Node security. It isoptional if you do not use Trusted Node security.

For further information on Trusted Node security refer to Trusted Node Security .

EXTERNAL|EXT specifies an external security classification for this node.

INTERNAL|INT specifies an internal security classification for this node. This is thedefault.

Chapter 4. Administration Guide 253

Parameter Description

data directionrestriction

The sixth positional parameter is the data direction restriction. It identifies thecopy initiation abilities of this adjacent node with the local node. For furtherinformation on data direction restriction, refer to Data Direction Restriction. Thisparameter is optional. Valid data direction values are:

RECEIVE|RECV indicates that when the adjacent node initiates a transfer, it is onlyallowed to receive data from this node. It is never allowed to send data to thisnode.

Note: For CTCA, RECEIVE|RECV indicates that the first address in channel-range-start-addr is used for inbound traffic; the next address is used for outbound traffic.For two IBM Connect:Direct systems to communicate through CTCA, one adjacentnode must specify SEND and the other must specify RECEIVE|RECV.

SEND indicates that when the adjacent node initiates a transfer, it is only allowedto send data to this node. It is never allowed to receive data from this node.

Note: For CTCA, SEND specifies that the first address specified in channel-range-start-addr is is used for outbound traffic; the next address is used for inboundtraffic.

For two IBM Connect:Direct systems to communicate through CTCA, one adjacentnode must specify SEND and the other must specify RECEIVE|RECV.

BOTH indicates that when the adjacent node initiates a transfer, it is allowed toboth send and receive data from this node. This value is the default.

NONE indicates that when the adjacent node initiates a transfer, it is neitherallowed to send or receive data from this node.

254 IBM Connect:Direct for z/OS: Documentation

Keyword Parameters for Adjacent Node EntriesThe network map adjacent node entry contains keyword parameters. The following are the positionalparameters for the network map adjacent node entry:

Parameter Description

PARSESS=(max,default) This is an optional parameter that uses two CLASS values for eachsession between the PNODE and SNODE to define the total numberof concurrent sessions or classes defined by the NETMAP entry. Eachsession is assigned a range of session class values that are obtainedfrom the ADJACENT.NODE entry of the SNODE, which is specified bythe PROCESS statement keyword, SNODE. The PARSESS parameter alsodefines the default Process CLASS value used by the Process when thePROCESS statement does not specify the CLASS keyword.

max specifies the maximum number of simultaneous DTF-to-DTFsessions that the local IBM Connect:Direct node can initiate with thisadjacent node. The range of this subparameter is 2–255. Each session isrepresented by a corresponding class value. This class value determinesthe execution eligibility of a Process. Leave this field blank if parallelsessions are not available.

default specifies the class assigned to a Process if one is not specifiedon the Process statement or when the Process is submitted. The rangeof this subparameter is 1-the value coded for parallel sessions. If you donot code this parameter, the node is not parallel session-capable, and themax and default values are set to 1. This parameter is required if you doPNODE=SNODE processing.

Note: If you do not specifically code the PARSESS parameter on anadjacent node definition, a default of PARSESS=(1,0) is set by the system,which allows only a single session. The default class 0 means no CLASSwhich shows up as a CLASS of NONE in an executing Process. You cannotcode the default PARSESS=(1,0) on an ADJACENT.NODE definition—theminimum value that can be coded is PARSESS=(2,1).

The following formula is a quick way to determine the number of parallelsessions available when class is not defined for a Process (the defaultclass is used): Default Parsess value = (max – default) +1

For CTCA connections, this value is automatically set to 1/2 of the addr-count. Do not try to reset this parameter for CTCA connections.

For best results when using Independent LU6.2, code PARSESS the samefor both the local and remote nodes.

Selecting a Class

IBM Connect:Direct selects a class in which a Process is to run bystarting with the default class, or the coded class, and proceedsupward in class values until an available class slot is found, or until allpossible class values are tested.

For more information on Process class, see the Connect:Direct ProcessLanguage help.

For more information about parallel sessions, refer to Building,Modifying,and Submitting Processes Queueing in the IBM Connect:Direct for z/OSUser Guide.

Chapter 4. Administration Guide 255

Parameter Description

ZFBA=(addr,addm) The ZFBA parameter has no default value; if it is not specified, the nodewill be ineligible for ZFBA transfers.

The range is specified as a pair of 4-hex-digit device addresses separatedby a comma or space; the second value must be greater than the firstvalue. Adjacent.node example defines 4 devices, 2000-2003 as the zFBAdevice range.

COMPRESS.EXT=ALLOW |DISALLOW | FORCE

This is an optional parameter that can be used to control how extendedcompression will be used on a node.

ALLOW specifies that extended compression may be used. In this case,extended compression may be specified within the Process or by theother node.

DISALLOW specifies that extended compression cannot be used.

FORCE specifies that extended compression is required.

COMPRESS.STD=ALLOW |DISALLOW | FORCE

This is an optional parameter that can be used to control how standardcompression will be used on a node.

ALLOW specifies that standard compression may be used. Standardcompression may be specified within the Process or by the other node.

DISALLOW specifies that standard compression cannot be used.

FORCE specifies that standard compression is required.

COMPRESS.STD.PRIMECHAR=C'x' | X'xx'

This is an optional parameter used for text data or single-characterrepetitive data to specify the primary compression character. It isspecified as either two hex digits preceded by “X” or a single characterpreceded by “C”, for example, COMPRESS.STD.PRIMECHAR=C'$', or thiscan also be expressed as COMPRESS.STD.PRIMECHAR=X'4B'

Note: If COMPRESS.STD is specified and COMPRESS.STD.PRIMECHAR isnot specified, then the Process default for COMPRESS.STD.PRIMECHAR,which is X'40' (an EBCDIC space), will be in effect.

SOURCEIP = IP address If an IPv6 or IPv4 address is required for the network map, thisparameter defines the source IP address that is bound to duringoutbound connection requests. If the SOURCEIP parameter is notspecified, the local or default address is bound. The destination addressis obtained from the network map. The source port is obtained asassigned by TCP/IP, or through the TCP.SRC.PORTS table. If the addressfrom the SOURCEIP cannot be bound during Process execution, theProcess is placed in a TI RE state (Timer Queue Retry Status).

Note:

• If the network map adjacent node contains a IPv6 address, but IBMConnect:Direct is not enabled to support it, the submit of a Processfor that network map entry fails. For information about enabling IBMConnect:Direct for IPv6 support, refer to TCP/IP Addressing.

• If the address from the SOURCEIP cannot be bound at Process start,the Process is placed in WA or WT state.

256 IBM Connect:Direct for z/OS: Documentation

Parameter Description

SESS.SNODE.MAX = nnn This is an optional parameter that can be used to control the numberof concurrent sessions that an adjacent node can initiate as the SNODE.The range for SESS.SNODE.MAX is 1 to 255. The default value is 255.In a IBM Connect:Direct/Plex environment, this parameter controls thenumber of sessions that an adjacent node can initiate with each IBMConnect:Direct/Plex server.

Note: For use with TCP/IP and LU6.2 only.

LDNS=hostname LDNS is an optional parameter that specifies the host name in thenetwork map adjacent node entry.

If you use this parameter, you can leave the third positional parameter(IP address or alias) blank. You must also specify TCP as the fourthpositional parameter (session type).

hostname specifies the host name for this node. The host name length isfrom 1–256 characters.

To see an example of a long DNS record, see The Network Map in the IBMConnect:Direct for z/OS User Guide.

ENVIRONMENT= operatingenvironment

The ENVIRONMENT parameter identifies the adjacent node operatingsystem environment. This parameter is required when the session typepositional parameter specifies LU6.2 protocol for i5/OS systems andwhen one IBM Connect:Direct system (either a IBM Connect:Direct/Plexenvironment or IBM Connect:Direct/Stand-alone Server) communicateswith a IBM Connect:Direct/Plex environment. Other protocols can use itfor documentation purposes.

Valid values are: GIS, HPNONSTOP, I5OS, LINUX, OPENVMS, OS400,SELECT, VOS, STRATUS, UNIX, VM, VMS, WINDOWS, and ZOS.

Note: When an OS/390 or z/OS IBM Connect:Direct systemcommunicates with another IBM Connect:Direct system in a IBMConnect:Direct/Plex environment and ENVIRONMENT=ZOS|OS390 is notspecified, Process redirection does not function correctly.

LOGMODE=logmode entry name Identifies the VTAM logmode entry that defines the communicationprotocol for this node.

This parameter is only required for LU6.2 nodes.

It is optional for LU0 connections. If you specify this parameter for LU0connections, the RUSIZE defined within this LOGMODE is used for anytransfer with this node. For a host-to-host transfer, the LOGMODE entryin the VTAM MODETAB of the SNODE determines the RUSIZE. For ahost-to-PC transfer, the LOGMODE entry in the host VTAM MODETAB isused.

This parameter is not valid for TCP/IP nodes or CTCA connections.

Refer to Sample VTAM Definitions in the IBM Connect:Direct for z/OSConfiguration Guide for information about VTAM definitions.

Chapter 4. Administration Guide 257

Parameter Description

APPLIDS=(vtam applid1 [,vtamapplid2,...] )

or

BATCHAPPLIDS=(batch.applid1 [,batch.applid2,...] )TSO.APPLIDS=(tso.applid1 [,tso.applid2,...] )INTERACTIVE.APPLIDS=(interactive.applid1 [,interactive.applid2,...] )CICS.APPLIDS=(cics.applid1 [,cics.applid2,...] )

The APPLIDS parameter specifies the VTAM APPLIDs that establish asession between the local IBM Connect:Direct SNA LU0 API and the IBMConnect:Direct DTF. APPLIDs are defined on the local nodes adjacentnode record for LU0 sessions to this DTF and are defined on the remotenodes adjacent node record for SNA LU0 multi-session signon to thoseremote DTFs. This parameter is valid only for z/OS and VM/ESA nodes,and the actual VTAM APPLIDs must be defined and active on the VTAMsystem where the SNA LU0 IUI / API signon is taking place.

To isolate or separate the VTAM pools to specific user interfaces, you canuse the following parameters to define special-purpose APPLIDS or justuse the APPLIDS parameter itself:

• BATCH.APPLIDS with the batch user interface• INTERACTIVE or TSO APPLIDS with the ISPF user interface• CICS.APPLIDS with the CICS user interface

NETID=networkid | servername The NETID parameter specifies the 1–8 character network ID for thisnode. When a Process starts, the network ID provided at the session startis verified against the network ID in the network map for the adjacentnode. If they do not match, the Process is terminated with an error.

For multiple session signons, the network ID of the node signing on isverified against the network map network ID of the node being signed onto. If they do not match, the signon fails.

If this keyword is not coded or the IBM Connect:Direct initializationparameter NETMAP.CHECK is set to NO, the network ID is not checked atProcess start or multiple session signon.

For a CTCA connection in a IBM Connect:Direct/Plex environment, thisparameter specifies the 1–8 character name of the IBM Connect:Direct/Server.

PNODE.LUS=(luname1[,luname2,...] ) )

The PNODE.LUS parameter specifies the logical units used by a remotenode to initiate a session with this local node. Do not specify thecommunications name when you use this parameter.

Applies to OpenVMS nodes. It is not valid for CTCA connections.

258 IBM Connect:Direct for z/OS: Documentation

Parameter Description

SNODE.LUS=(luname1[,luname2,...] ) )

For OpenVMS, the SNODE.LUS parameter specifies the logical unit namesused by the local node to initiate a session with this remote node. For allother platforms, it specifies the logical units used for all communicationswith the remote node.

Communications to nodes that cannot handle parallel sessions canrequire a pool of logical units. If an adjacent node is defined in its hostenvironment to use more than one logical unit for communications, theneach of the logical unit names that can communicate with the local nodemust be defined to the local node on the corresponding adjacent nodenetwork map entry.

HP NonStop and i5/OS adjacent node entries use the SNODE.LUSkeyword only to define the LU pool.

OpenVMS nodes assign the logical units in the pool as either ACTIVE,session initiating, PASSIVE, or listening for session requests. Thisdistinction in function is defined to the z/OS node by specifying theACTIVE logical units with the PNODE.LUS keyword and the PASSIVElogical units with the SNODE.LUS keyword.

This parameter is not valid for CTCA connections.

PNODE.LAST.USED=(mm.dd.yyyy,hh:mm:ss)

The date and time the Adjacent Node was last used as the PNODE thatis, the Local Node was the SNODE. This parameter is only unloadedby program DGADNTLD if the usage (US) record exists for the AdjacentNode, and the PNODE last used fields in the US record are not binaryzeroes.

SNODE.LAST.USED=(mm.dd.yyyy,hh:mm:ss)

The date and time the Adjacent Node was last used as the SNODE thatis, the Local Node was the PNODE. This parameter is only unloadedby program DGADNTLD if the usage (US) record exists for the AdjacentNode, and the SNODE last used fields in the US record are not binaryzeroes.

USE.SERVER.NODE = YES | NO Setting this parameter to YES tells a IBM Connect:Direct/Server to useits CDPLEX.SERVER.NODE initialization parameter as identification whencommunicating with this adjacent node. If this parameter is set to NO,the IBM Connect:Direct/Server identifies itself to this adjacent node asthe same local node as all other members of the IBM Connect:Direct/Plex environment. (See CDPLEX.SERVER.NODE = node name for moreinformation.)

This parameter is required if a remote IBM Connect:Direct system,using NETMAP checking, communicates with more than one IBMConnect:Direct/Server in a IBM Connect:Direct/Plex environment.

This parameter is ignored in a IBM Connect:Direct/Stand-alone Server.

Chapter 4. Administration Guide 259

Parameter Description

TCPAPI=(port number, IP address) This parameter defines the adjacent node communication address usedby an external API that uses TCP to communicate with the node.This value must be the same as the TCP.API.PORTNUM initializationparameter of the node that you are communicating with.

If the adjacent node is an SNA node, include both the port number and IPaddress.

If the adjacent node is a TCP node, you must supply the port number,but do not need to supply the IP address. If you do not supply the IPaddress, you must define the IP address in the Adjacent node record. SeeAPI Signons for more information.

CRC =(OFF|ON|DEFAULT) Determines if you will perform CRC checking for any TCP/IP Processsending to this node. If overrides are allowed, this parameter enables youto override the CRC setting in the initialization parameters for this node.

Note: Although DEFAULT is an acceptable value, it is the equivalent ofnot specifying the network map parameter at all and would normallyonly be seen in the output of the network map file unload when no CRCspecification had been supplied previously.

PLEXCLASS= (* | plexclass, * |plexclass)

This parameter specifies a default PLEXCLASS for the PNODE (thefirst parameter) and SNODE (the second parameter). This IBMConnect:Direct/Server checks this PLEXCLASS to determine if it can runthe Process. (See the initialization parameter, “CDPLEX.PLEXCLASSES =(*,plexclass,…,plexclass)” on page 512, for more information.)

Each PLEXCLASS name is 1–8 characters long. An asterisk (*) is alsoan acceptable entry, which indicates that the IBM Connect:Direct/Serversupports any Process that does not specify a PLEXCLASS, or specifies aPLEXCLASS of ‘*'.

BUFFER.SIZE=V2.buffer override V2.buffer override defines the buffer size for the adjacent node. It is onlyvalid for TCP and CTCA session types. Use it to dynamically override theV2.BUFSIZE value of the local node during TCP buffer size negotiation.This parameter is generally coded to reduce the V2.BUFSIZE value sothat IBM Connect:Direct provides less data on each TCP send. Validvalues are 3072–2097152 | 3K–2M.

260 IBM Connect:Direct for z/OS: Documentation

Parameter Description

ALTernate.COMMinfo=

(ALTernate.RESTART=YES | NO

ALTernate.DIRection=

BALANCE | TOP,

(ALTernate.ADDRess= |ALTernate.NODEDEF=,ALTernate.PORT=, SOURCEIP=,

.

.

.

This parameter enables you to specify multiple remote node addressesfor NETMAP checking.'

Note: The number of ALT.ADDR parameters can not exceed the maximumlength of the Netmap Alternate Address Record.

ALTernate.RESTART indicates if an alternate communications path isconsidered when a Process must restart.

Note: Do not specify ALT.NODEDEF if you use ALT.RESTART. All alternatecommunications paths must use ALT.ADDR and the same protocol (allVersion 1 or Version 2). For example, if you use ALT.TYPE=SNA, specifyall alternate addresses as ALT.TYPE=SNA (Version 1 protocol). SinceLU62 and TCP are Version 2 protocols, you can use LU62 or TCP whenspecifying alternate addresses.

ALTernate.DIRection specifies the direction of the communications pathsare selected as the primary path. BALANCE (default) indicates a balancedapproach; that is, all current sessions are scanned for this same adjacentnode and the least used path is selected as the primary path for theProcess. The list is processed forward from there.

Note: BALANCE does not guarantee a truly balancing between allalternate paths. It is simply used to select the first path attempted andthe Connect:Direct Process may not necessarily execute on that path.TOP indicates the paths are processed from the top.

ALTernate.ADDRess specifies either a TCP/IP address or an SNA addressas appropriate.

If ALT.TYPE=SNA or ALT.TYPE=LU62, ALT.ADDR must be a 1–8 characterAPPLID. If ALT.TYPE=TCP, ALT.ADDR must be a 15-character IPv4 or39-character IPv6 TCP/IP address or a 1–256 character LDNS name. Thissubparameter is required if you do not specify ALTernate.NODEDEF.

ALTernate.NODEDEF specifies an alternate node definition to use forNETMAP checking. This subparameter references another entry inthe NETMAP. This subparameter is required if you do not specifyALTernate.ADDRess.

ALTernate.PORT specifies the alternate address port number if thealternate address is TCP/IP. This field is not required. This subparameterdefaults to the port of the adjacent node record. If not specified inthe adjacent node record, the default is 1364. You can only use thissubparameter if ALT.TYPE=TCP.

Note: If ALTernate.DIRection=BALANCE is specified, the value specifiedfor ALTernate.PORT is not used.

SourceIP, which has no short form, specifies an alternate IPv6 orIPv4 address that is bound to during outbound connection requests.The source port is obtained as assigned by TCP/IP, or through theTCP.SRC.PORTS table. If the address from the SOURCEIP cannot bebound during Process execution, the Process is placed in WA or WT state.

If SourceIP is specified for this ADJACENT NODE but not in theALT.COMM entry, the value specified for the ADJACENT NODE alsoapplies to this ALT.COMM entry.

Note: If the network map adjacent node contains a IPv6 address,but IBM Connect:Direct is not enabled to support it, the submit of aProcess for that network map entry fails. For information about enablingConnect:Direct for IPv6 support, refer to TCP/IP Addressing.

Chapter 4. Administration Guide 261

Parameter Description

ALTernate.COMMinfo=

.

.

.

ALTernate.TYPE=SNA | TCP | LU62,ALTernate.LOGmode=

logmode entry name,ALTernate.USE.OUTbound=Yes |No)

(Continued from previous page)

ALTernate.TYPE specifies the protocol used for the alternate address.This value defaults to that of the adjacent node record. Validvalues are SNA, TCP, LU62. This subparameter is only used withALTernate.ADDRess. This subparameter is required if you do not specifyALTernate.NODEDEF.

ALTernate.LOGmode specifies an SNA logmode used whenALTernate.TYPE=SNA or LU62. This parameter is required for LU62 if theadjacent node is not defined as LU62.

ALTernate.USE.OUTbound specifies whether the alternatecommunications path is used for outbound Processes, providing sessionfailover for Processes sent to this adjacent node. Valid values are Yes(default) and No.

For more information on this parameter, refer to Using AlternateCommunications Paths.

CDFTP.PLUGIN=”fully qualifiedinstallation directory of the IBMConnect:Direct FTP+ Plug-in”

IBM Connect:Direct FTP+ for z/OS gets its configuration informationabout remote systems it connects to from the Netmap.

Configure the CDFTP.PLUGIN parameter in your Netmap to specify wherethe IBM Connect:Direct FTP+ Plug-in is installed on each remote systemthat IBM Connect:Direct FTP+ for z/OS connects to.

This parameter is not required when the Netmap entry defines a z/OSsystem.

CDFTP.TEMPFILE=”fully qualifiedname of the IBM Connect:DirectFTP+ temporary file”

IBM Connect:Direct FTP+ for z/OS gets its configuration informationabout remote systems it connects to from the Netmap.

Configure the CDFTP.TEMPFILE parameter in your Netmap to specify thefully qualified name of the IBM Connect:Direct FTP+ temporary file foreach remote system that IBM Connect:Direct FTP+ for z/OS connects to.

The FTP+ Plug-in creates a temporary file to store the results of adirectory command RUNTASK operation.

Note: If no variables are used in the CDFTP.TEMPFILE, then IBMConnect:Direct FTP+ for z/OS appends the job userid and the ASID andCPUID to the CDFTP.TEMPFILE parameter as a further specification ofuniqueness.

Several variables are available for substitution in the CDFTP.TEMPFILEspecification. These variables are:

• &userid;—The remote userid (lower case)• &USERID;—The remote userid (upper case)• &lusrid;—The local userid padded to 8 characters with '$'• &lcpuid;—The first 8 bytes of the local CPUID with "C" overlaying thefirst byte

• &asid;—The 4 character Address Space ID prefixed with "AS"

For example, you can specify CDFTP.TEMPFILE= with a variable, such as"&userid;". IBM Connect:Direct FTP+ for z/OS inserts the remote userid inplace of the “&userid;”.

262 IBM Connect:Direct for z/OS: Documentation

Parameter Description

CONTACT.NAME=”name”

CONTACT.PHONE=”phoneinformation”

DESCRIPTION=”descriptioninformation”

These are free-form text parameters, which provide additional generalinformation about an Adjacent Node entry. The CONTACT.NAME andCONTACT.PHONE parameters are limited to a maximum of 40 characters.The DESCRIPTION parameter is limited to a maximum of 255 characters.

FASP = (NO | SSP , NO | SSP) The first positional parameter is used for when this IBM Connect:Directz/OS Server is the PNODE and the second is for when this IBMConnect:Direct z/OS Server is the SNODE. The default of NO indicatesthat the FASP via SSP support is globally set to FASP=NO. IBMConnect:Direct Processes should not attempt to use the FASP transportunless overridden by the NETMAP or Process. SSP indicates that the IBMConnect:Direct Processes should request the FASP transport when insession with SSP unless override by the NETMAP or Process.

FASP.BANDWIDTH = nnn | nK | nM |nG

This is an optional FASP configuration parameter that specifies how muchbandwidth each transfer can use. The default is taken from the licenseand is negotiated with the remote to the smaller of the values. The valuecannot exceed the value defined in the license and SSP will ensure thesmaller is used. This value is represented as number of bits and 1Kequals 1000.

FASP.FILESIZE.THRESHOLD = nnn |nK | nM | nG

The default of 1G defines the threshold to limit the use of the FASPtransport to specific file sizes. If the estimated file size is less than thisthreshold, IBM Connect:Direct for z/OS will proceed as FASP=NO for thatfile transfer. This value is represented as number of bytes and 1K equals1024. The sending IBM Connect:Direct Server will apply the thresholdusing the PNODE's setting.

FASP.POLICY = FAIR | FIXED |HIGH | LOW

This is an optional FASP configuration parameter that specifies the'fairness' of each transfer. The default is FAIR.

Using Alternate Communications PathsUse the ALT.COMM parameter to set up alternate communications paths. To see an example ofusing alternate communications paths in a IBM Connect:Direct/Plex environment, see Strategies forCommunicating with Non-Plex Servers.

Note the following:

• The protocol and number of alternate communications paths depend on the capability of the remotenode.

• If you use alternate communications paths, the remote IBM Connect:Direct node must have thecapability to support the ALT.COMM parameter and have a defined method of performing network mapchecking for these alternate paths.

• If you are using either the SSL or TLS protocol with Connect:Direct Secure Plus, all communicationspaths must be TCP.

• Since each ALT.COMM entry varies in size and each ALT.NODE and ALT.ADDR entry is also variable, thenumber of entries that may be added to a single ADJACENT.NODE varies. The limit will be determinedby how many entries fit within a single Netmap record and it may vary from 20 to 30 entries, dependingon parameters and values for each entry.

Alternate Communications Paths with Current Node as Primary NodeThe adjacent node record defines a communications path. You can use the ALT.COMM parameter in theadjacent node record to define alternate communications paths.

Chapter 4. Administration Guide 263

When a Process is submitted, the primary communications path is selected based on thealternate.direction subparameter. If alternate.direction=BAL, all communications paths are scannedto find the least used path, including the path defined in the adjacent node record, and all pathsdefined in the alternate.address subparameters. The least used path becomes the primary path. Ifalternate.direction=TOP, the communications path defined in the adjacent node record is used as theprimary path.

If the Process fails to establish a session using the primary communications path, the network mapis processed to determine the next eligible communications path. This is repeated until the sessionis successfully established or the number of communications paths is reached. When this number isreached, the primary communications path is restored and the Process is placed in timer retry (TI RE)status. After all session retries (MAXRETRIES) are reached, the original communications path is restoredand the Process is placed in hold (HO WC) status.

Each failed attempt to establish a session produces the following result:

• Message SVTM310I SESSION NOT ESTABLISHED WITH SNODE=xxxx• Session Begin statistics record that identifies the communications path used at the time of the failure• Diagnostics to RPLERRCK• When the MAXRETRIES is reached and the Process is placed in the HOLD queue, the following message

is issued in addition to the previous message(s):

SVTM105I PNAME=pnam, PNUM=pnum MOVED TO Q=HOLD, QSTATUS=WC

When the Process establishes a session, the Session Begin statistics record identifies thecommunications path that was successfully used. That communications path is used for the life of theProcess, unless ALTernate.RESTART is coded for the node, in which case the communications path maychange if the Process restarts. For more information on ALTernate.RESTART, see the description for theALTernate.COMMinfo parameter.

Alternate Communications Paths with Current Node as Secondary NodeWhen the current IBM Connect:Direct node is the secondary node (SNODE), the ALT.COMM parameter isused for network map checking purposes only.

Outbound ProcessesThe ALT.COMM parameter is used for outbound Processes when following conditions are true:

• The current IBM Connect:Direct is the PNODE.• The Process is not in restart (the default ALT.RESTART=NO is in effect).

Note: If you specify ALT.RESTART=YES, IBM Connect:Direct considers alternate communications pathsif the path used to establish a session fails and the Process restarts. For an example, see RestartingProcesses using an Alternate Communications Path

• The Process is not PNODE=SNODE.• The Process is not SNODE=TCPNAME=.

PNODE=SNODE ProcessingIBM Connect:Direct can initiate Processes where the local node is both the initiating and target node(PNODE and SNODE). You enable PNODE=SNODE processing by creating an adjacent node entry with thesame node name as the local node entry in the network map.

If the PNODE=SNODE connection is SNA, SNA=YES is specified in the initialization parameters.

Observe the following rules when setting up the adjacent node:

264 IBM Connect:Direct for z/OS: Documentation

• Define an LU0 communications name for the PNODE=SNODE network map entry. Do not specify anLU6.2 logmode entry name for the common name of the adjacent node entry.

• The communications name for the adjacent node must be different from the communications name ofthe local node. If the names are the same, PNODE=SNODE processing is disabled at initialization.

• Code the PARSESS=(max, default) parameter in the network map adjacent node entry to govern thenumber of simultaneous PNODE=SNODE connections.

TCP/IP ConsiderationsA network map entry is not required for every TCP/IP node. A default entry provides a standard setof parameters. If the standard set of parameters is not adequate, you can code a network map entryfor that node to override the default entry. If network map entries are not used for TCP/IP, you mustsubmit Processes by using the SNODE=TCPNAME keyword. For more information, see Example - Defininga TCP/IP Default Entry.

Note: If you set the NETMAP.CHECK=TCP initialization parameter, you must define the TCP/IP node in thelocal network map.

The APPLIDS and LOGMODE keywords and the remote library name positional parameter are not used onany TCP/IP node and cannot be coded in the network map. A warning is generated for any unnecessarykeyword or subparameter, and the coded value is ignored when the network map is loaded.

TCP/IP AddressingEach host on a TCP/IP network is assigned a unique address known as an IP address. Applicationsrunning on a TCP/IP host that connect to the network are assigned one or more port numbers of the IPaddress.

IBM Connect:Direct supports both IPv4 and IPv6 protocols, where IPv6 allows a much larger addressrange than IPv4. During product initialization, IBM Connect:Direct determines if the TCP Stack is IPv6 oronly IPv4. (IPv6 must be enabled within TCP/IP itself.) If IBM Connect:Direct initializes on a system whereIPv6 is not enabled, any function involving an IPv6 address fails, including attempts to resolve an addressor name using the DNS name resolution. For information about enhancing and extending IPv6 through theTCP.LISTEN parameter, see Multiple Port TCP/IP Listen.

Command Syntax for IPv4 AND IPv6 AddressingThe following examples demonstrate the command syntax for IPv4 and IPv6 addressing.

Note: The address must be specified on a single line. You cannot break the address between lines.

The following example demonstrates how to break the command syntax over an additional line:

(SC.DUB.MWATL3,4399, -1111:2222:3333:4444:5555:6666:7777:8888,TCP)

The following example demonstrates the appropriate network syntax:

/* *//* IPV6 ADDRESS *//* */ ADJACENT.NODE=( - (SC.DUB.MWATL3,4399,1111:2222:3333:4444:5555:6666:7777:8888,TCP) - PARSESS=(00000255 00000001) - APPLIDS=(M1CDI7P6 M1CDI7P7 M1CDI7P8) )/* *//* IPV4 ADDRESS *//* */ ADJACENT.NODE=( - (SC.DUB.MWATL3,4399,111.222.333.444,TCP) - PARSESS=(00000255 00000001) - APPLIDS=(M1CDI7P6 M1CDI7P7 M1CDI7P8) )

Chapter 4. Administration Guide 265

The following example demonstrates the appropriate command syntax for a multiple listen for IPv6addresses through the initialization parameter:

TCP.LISTEN=((10.20.201.2,4199), - (fd00:0:0:20cc::2,4299), - (10.20.201.2,4399), - (10.20.201.2,4499) )

The following two examples represent a simple specification for a single listen for either an IPv4 or IPv6address through the initialization parameters:

/* *//* IPV4 address *//* */ TCP.LISTEN = (111.222.333.444,01364)

/* *//* IPV6 address *//* */ TCP.LISTEN = (1111:2222:3333:4444:5555:6666:7777:8888,01364)

The following example represents a simple specification for a single listen for either an IPv4 or IPv6address through the Process syntax:

/* *//* IPV6 Address *//* */label PROCESS - SNODE=TCPNAME=1111:2222:3333:4444:5555:6666:7777:8888;nnnnn/* *//* IPV4 Address *//* */label PROCESS SNODE=TCPNAME=111.222.333.444;nnnnn(where nnnnn is the 5 digit port number)

Domain Name ResolutionBecause IP addresses are difficult to remember and not descriptive of the host it is assigned to, TCP/IPenables meaningful names to map to the IP address. TCP/IP provides a function called Domain NameResolution to map the name to the IP address. Refer to your TCP/IP implementation documentation forinformation on the setup and use of Domain Name Resolution.

Releasing Processes Serially from Connect:Direct for Microsoft WindowsTo support dial-up connections from a Connect:Direct for Microsoft Windows node and release Processesserially, define the Connect:Direct for Microsoft Windows node in an adjacent node entry using a null IPaddress of 0.0.0.0. You can let the port number default to 1364 on the node where the network mapresides since it will be resolved at connection time. Processes submitted to nodes defined in this mannerdefault to HOLD=CALL status and are not executed since the connection cannot be resolved.

To release the HOLD=CALL Processes, create a NULL or ENABLE Process from the Connect:Directfor Microsoft Windows SNODE. (A NULL Process is an empty one with no steps and is only valid inConnect:Direct for Microsoft Windows.) When the Connect:Direct for Microsoft Windows node establishesa connection with Connect:Direct for z/OS and sends the NULL Process, Connect:Direct for z/OS uses thesame session and runs any HOLD=CALL Processes one at a time. Checkpoint restart is supported for suchnodes.

266 IBM Connect:Direct for z/OS: Documentation

TCP/IP Port NumberThe initialization parameters TCP.LISTEN and TCP.API.LISTEN provide the best method for defining asingle port or multiple ports for IBM Connect:Direct to listen to and accept incoming TCP/IP connectionrequests. You can define a single port for establishing a listen task, or define multiple ports byestablishing a list of IP address and port number combinations. Multiple port listening allows IBMConnect:Direct to accept incoming traffic from a variety of addresses.

Single Port TCP/IP ListenIBM Connect:Direct implements a standard TCP client/server architecture. Each IBM Connect:Direct nodein the TCP/IP network can function as both the client and the server simultaneously.

The server establishes a connection with the TCP/IP network and waits for session requests from otherIBM Connect:Direct clients. When a session request is received and validated, the server accepts theconnection to the client.

The IBM Connect:Direct client requests a session that is established through the TCP/IP network to aIBM Connect:Direct server. When the session is accepted by the server, a dynamic port is assigned by thenetwork. This dynamically assigned port is used for the actual data transfer. When the data transfer iscomplete, the port is released back to the network and the session is terminated.

IBM Connect:Direct uses a predefined TCP/IP port number for both client and server. This port is definedin TCP/IP as a TCP service and requires the same port for all IBM Connect:Direct TCP/IP nodes in yournetwork. Refer to your TCP/IP implementation documentation for how to define TCP servers. If youcannot use the predefined TCP/IP port, you can override it for both the client and server.

This initialization parameter defaults to port number 1364.

Client Override Port NumberThe client override port number is coded on the adjacent node record in the second positional parameter.The IBM Connect:Direct client requests sessions to the IBM Connect:Direct server through this port. Theport number coded on the adjacent node record is used by client functions only and does not change theport number used by the server functions. You must code the network map entry in your network map inorder to use the override port number.

Server Override Port NumberThe server override port number is coded in the TCP.LISTEN initialization parameter. The IBMConnect:Direct server waits for a IBM Connect:Direct client request on this port. The initialization portnumber is used by server functions only and does not change the port number used by the clientfunctions.

Multiple Port TCP/IP ListenIBM Connect:Direct accepts incoming traffic from a variety of addresses. The initialization parametersTCP.LISTEN and TCP.API.LISTEN support both IPv4 and IPv6 protocols. They also allow for a list of IPaddress and port number combinations.

The first address defined in the parameter becomes the local or default address. Up to eight differentaddresses/ports can be defined for each server.

For information about multiple port listening in a IBM Connect:Direct/Plex environment, refer to A NewIBM Connect:Direct/Plex Environment.

Viewing a TCP Listen Status ReportTo view the TCP listening status through the IUI interface, follow this procedure.

1. Access the INQUIRE TCP command by selecting option INQ from the Connect:Direct AdministrativeOptions Menu. The Inquire DTF Internal Status screen is displayed.

Chapter 4. Administration Guide 267

2. Type ITCP and press ENTER to display the status report. The following report is an example of theoutput.

Menu Utilities Compilers Help ------------------------------------------------------------------------------------------- BROWSE SYS18242.T154700.RA000.EPETE1.NDMAPI.H0F Command ===>******************************************************************* Top of Data ******======================================================================CD.ART * INQUIRE TCP * DATE: 08.30.2018 TIME: 15:47:04======================================================================

ADDRESS PORT FAMILY TYPE STATUS======================================= ===== ======== ==== ==========10.120.131.91 5610 IPV4 NODE LISTEN10.100.130.91 5610 IPV4 NODE ERROR - CANNOT ASSIGN ADDRESSFD00:0:0937:6F00::0091 5610 IPV6 NODE LISTEN10.120.131.91 5620 IPV4 API LISTENFD00:0:0937:6F00::0091 5620 IPV6 API LISTEN******************************************************************* Bottom of Data ****

VTAM IndependenceVTAM independence enables IBM Connect:Direct to initialize without SNA support. It also enables IBMConnect:Direct to continue functioning if VTAM is not available, and to reattach to VTAM when it isrestored.

To use VTAM independence, you must specify SNA=YES in the initialization parameters. You must alsospecify a valid VTAM APPLID in the network map local node record.

If SNA= YES is specified in the initialization parameters and you try to start IBM Connect:Direct whenSNA is not available, or if SNA becomes unavailable during a session, the system prompts the operator foraction.

See “SNA = YES | NO” on page 492 for more information about the SNA initialization parameter. See APISignons for more information about operator actions.

TCP/IP API CommunicationsThe TCP.API.LISTEN initialization parameter enables an API to communicate with a IBM Connect:Directusing TCP/IP via OE sockets. Also, you can use the TCPAPI keyword parameter in the adjacent noderecord to define a default protocol for API communication.

The API must also use the SIGNON command to specify a transport type and communications address.See API Signons for more information. Additionally, refer to Managing Sessions in IBM Connect:Direct forz/OS User Guide for more information about the SIGNON command.

Example - Defining a TCP/IP Default EntryThe following example defines a TCP/IP default record using ADJACENT.NODE entries.

/* *//* The following entry is for the TCP/IP default entry *//* */ ADJACENT.NODE=(PARSESS=(8,1) - ENVIRONMENT=ZOS - (TCP.IP.DEFAULT, 2048,, TCP))

Note: For a TCP/IP default entry, the nodename parameter must be TCP.IP.DEFAULT and the session typemust be TCP. A TCP/IP default entry is required if any Process uses SNODE=TCPNAME=.

In the previous example, nodename=TCP.IP.DEFAULT, communications name=2048, and sessiontype=TCP. For information about adjacent node entries, see Adjacent Node Entry.

When a Process is submitted, the port number value is determined in the following order:

268 IBM Connect:Direct for z/OS: Documentation

1. If the node name within a Process is defined in the network map, the port number associated with thenode name entry is used.

2. If the node name within a Process is not defined in the network map, the port number associated withthe default entry is used.

3. If no port number exists in the communications name field of the default entry, the TCP.LISTENinitialization parameter is used.

4. If the TCP.LISTEN initialization parameter is not defined, the port number defaults to 1364.

The PARSESS value for the SNODE is determined in the following order:

1. If the node name within a Process is defined in the network map, the PARSESS value associated withthe nodename entry is used.

2. If the node name within a Process is not defined in the network map, the PARSESS value associatedwith the default entry is used.

3. If no PARSESS value is in the default entry, the PARSESS value defaults to (1,0). A PARSESS value of(1,0) means that Processes to the nodes for which the default entry is used are single-threaded.

Channel-to-Channel SupportConnect:Direct for z/OS provides channel-to-channel support for direct channel links between z/OSplatforms using the IBM ESCON CTCA or IBM 3088 CTCA support.

The syntax for creating a CTCA adjacent node follows.

ADJACENT.NODE=( - (nodename, - channel-range-start-addr, addr-count, CTCA,, - SEND| RECV)) - NETID=server name - PARSESS=(max default) - ENVIRONMENT=operating environment - )

Node Usage Information MaintenanceWith v6.1, node usage date and time stamps are maintained in a new US record in the Netmap. There isone US record for each Adjacent Node (NN) record. Note that there is no US record for the Local Nodeentry, but there is one for the Adjacent Node entry used for PNODE=SNODE. Connect:Direct maintains thedate and time for the following events in the life of a Netmap Adjacent Node entry.

Chapter 4. Administration Guide 269

Event Effect of Event on US Record and its Date and Time fields

US Record NodeAddedFields

NodeUpdatedFields

Node Last Usedas PNODE fields

Node Last Usedas SNODE fields

Netmap LoaderProgram

DGADNTLD

LOAD Created Set toprogramexecutiondate andtime

Set tobinaryzeroes

Set fromparameterPNODE.LAST.USED if present;otherwise set tobinary zeroes.

Set fromparameterSNODE.LAST.USED if present;otherwise set tobinary zeroes.

UNLOAD Notunloaded

Notunloaded

Unloaded asparameterPNODE.LAST.USED if the US recordexists and hasnon-zero date andtime in thePNODE Last Usedfields.

Unloaded asparameterSNODE.LAST.USED if the US recordexists and hasnon-zero date andtime in theSNODE Last Usedfields

Netmap UpdateProgram

DGADUPNT

$DELETE Deleted

$INSERT Created Set toprogramexecutiondate andtime

$REPLACE Deletedthencreated

Set toprogramexecutiondate andtime

$UPDATE Set toprogramexecutiondate andtime

Connection AdjacentNode isthe PNODE

Set to connectiondate and time

AdjacentNode isthe SNODE

Set to connectiondate and time

PNODE=SNODE

Set to connectiondate and time

Set to connectiondate and time

Netmap Conversion and FallbackIt is recommended that when switching from an earlier version to v6.1 follow these Netmap conversionsteps to ensure that Connect:Direct v6.1 immediately begins to maintain node usage information for allAdjacent Nodes:

1. Execute the old version of program DGADNTLD to unload the Netmap.

270 IBM Connect:Direct for z/OS: Documentation

2. Execute v6.1 version of program DGADNTLD to re-load the Netmap using the data set created in step 1as input. This creates US records for all Adjacent Nodes and initialize their Node added fields.

It is recommended that if you must fall back from 6.1 to an old version, follow the steps givenbelow since previous Connect:Direct version's DGADNTLD will not recognize the new *NODE.LAST.USEDparameters:

1. Use v6.1 version of DGADNTLD to unload the Netmap.2. If you want to preserve the *NODE.LAST.USED information for later when you re-upgrade to v6.1, then

make a copy of the output data set.3. Manually edit the unload output data set and remove the PNODE.LAST.USED and SNODE.LAST.USED

parameters. If you do not do this before reloading, an old version of 6.1 DGADNTLD will issue an errormessage and end with RC 16. It will not reload the Netmap.

4. Reload the Netmap using Pre-6.1 DGADNTLD with the edited data set as input.

Neither the conversion nor fallback steps are required. If you don’t complete the conversion steps whengoing from an old version to 6.1, Connect:Direct v6.1 will not maintain node usage information for anynode, unless it is replaced (not updated) using the DGADUPNT program. If you don’t complete thefallback steps when going from v6.1 to an old version, the pre-6.1 Connect:Direct will ignore the USrecords in the Netmap.

API SignonsThe communication address used to establish a connection to IBM Connect:Direct is determined by theTRANSPORT parameter defined in the SIGNON command. The default for the TRANSPORT parameter isNET (NETMAP), which means that the protocol defined in the NETMAP adjacent node entry is used.

Parameter Value Description

TRANSPORT = NET Default. When TRANSPORT is defined as NET, the signon process retrieves theadjacent node entry to determine if the TCPAPI parameter has been defined. IfTCPAPI exists, then a TCP connection is attempted using the communicationsaddress defined. The communications port number is obtained from the TCPAPIparameter, and if the IP address exists in the TCPAPI parameter, it is also used. Ifthe IP address does not exist in the TCPAPI parameter, it must be obtained fromeither the adjacent node or the LDNS parameter.

If the TCPAPI does not exist, the APPLID parameter is retrieved, and SNA is usedas the protocol.

TRANSPORT = SNA When TRANSPORT is defined as SNA, the signon process retrieves the adjacentnode entry to determine the APPLID parameter, and SNA is used as the protocol.If the APPLID parameter does not exist, then an ESF SIGNON is performed.

TRANSPORT = TCP When the TRANSPORT is defined as TCP, the communications address must bespecified on the SIGNON command.

To initialize IBM Connect:Direct without SNA support, refer to InitializingIBM Connect:Direct without SNA Support in the IBM Connect:Direct for z/OSConfiguration Guide.

Adjacent Node API Signon Definition ExamplesTo only allow SNA API signons:

/* PNODE=SNODE WITH SNA API SIGNON ONLY */ ADJACENT.NODE=(( CD.ZOS.NODE,M1DEV93C) PARSESS=(53 2) - APPLIDS=(M1CDI701 M1CDI702 M1CDI703) - )

Chapter 4. Administration Guide 271

To only allow TCP API signons using the IP address:

/* PNODE=SNODE WITH TCP API SIGNON ONLY USING IP ADDRESS */ ADJACENT.NODE=(( CD.ZOS.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,111.222.333.444) - )

To only allow TCP API signons using the LDNS parameter:

/* PNODE=SNODE WITH TCP API SIGNONON ONLY USING LDNS */ ADJACENT.NODE=(( CD.ZOS.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,) - LDNS=long.domain.name - )

To allow both SNA and TCP API signons:

/* PNODE=SNODE WITH BOTH SNA AND TCP API SIGNON */ ADJACENT.NODE=(( CD.ZOS.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,111.222.333.444) - APPLIDS=(M1CDI701 M1CDI702 M1CDI703) - )or/* PNODE=SNODE WITH BOTH SNA AND TCP API SIGNON */ ADJACENT.NODE=(( CD.ZOS.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,) - LDNS=long.domain.name - APPLIDS=(M1CDI701 M1CDI702 M1CDI703) - )

Examples of Local and Adjacent Node RecordsThis section contains examples of local and adjacent node records for various platforms.

Local Node and Corresponding Adjacent Node RecordThe following is an example of a local node entry and its corresponding adjacent node entry. Noticethat the local and adjacent node names are the same (CD.DALLAS), but the local and adjacentcommunications names (NDMAPP1 and NDMAPP2) are different. The local node shows a superuserpassword of XYZZY.

LOCAL.NODE=((CD.DALLAS,NDMAPP1,,XYZZY) - TCQ=(DSC.DALLAS.TCX DSC.DALLAS.TCQ))/* *//* THE FOLLOWING ENTRY IS FOR THE LOCAL NODE *//* */ADJACENT.NODE=(PARSESS=(12,2) (CD.DALLAS,NDMAPP2) - APPLIDS=(NAI01 NAI02 NAI03 CDDD12 - CDDD17 CDDD18 CDDD32 CDDD41 CDDD42))

The following is an example of a local node entry and its corresponding adjacent node entry whereTCPAPI is defined.

LOCAL.NODE=((CD.DALLAS,NDMAPP1,,XYZZY) - TCQ=(DSC.DALLAS.TCX DSC.DALLAS.TCQ))/* *//* THE FOLLOWING ENTRY IS FOR THE LOCAL NODE WHERE TCPAPI IS DEFINED *//* FOR USE BY Connect:Direct APIs TO SIGNON USING TCP/IP *//* */ADJACENT.NODE=(PARSESS=(12,2) (CD.DALLAS,NDMAPP2) - TCPAPI=(1363,111.222.333.444) - APPLIDS=(NAI01 NAI02 NAI03 CDDD12 - CDDD17 CDDD18 CDDD32 CDDD41 CDDD42))

272 IBM Connect:Direct for z/OS: Documentation

The following is an example of an adjacent node entry that defines a pool of zFBA devices.

ADJACENT.NODE=((CD.UNIX , 1364 , UNIXHOST , TCP ) - ENVIRONMENT=UNIX PARSESS=(8,2) - ZFBA=(2000,2003) - APPLIDS=(M1CDI7P6 M1CDI7P7 M1CDI7P8) )

Alternate Communications Path ExamplesThe following examples show two different ways of using alternate communications paths.

Specifying ALT.ADDR and ALT.NODEDEFThe following is an example of an adjacent node entry that has four alternate communications pathsthat can be used if the main communication path specified for the adjacent node (TCP/IP address of199.1.4.1) cannot be used. Three of the alternate communications paths are defined using the ALT.ADDRparameter while one uses the ALT.NODEDEF parameter.

ADJACENT.NODE=((CD.NODE,1364,199.1.4.1,TCP) - PARSESS=(6 2) -ALT.COMM=((ALT.ADDR=1.1.1.2,ALT.TYPE=TCP), - (ALT.ADDR=VTAMAPL1,ALT.TYPE=SNA), - (ALT.NODEDEF=TEST.NODE), - (ALT.ADDR=1.1.1.3,ALT.PORT=4374,ALT.TYPE=TCP)) -)

Restarting Processes using an Alternate Communications PathIn the following example, the adjacent node in the previous example has been redefined to allow analternate communications path which only supports Version 2 flows. In this system, IBM Connect:Directis running on a machine with two Network Interface Cards (NICs), which means that there are two IPaddresses for this machine. On the remote IBM Connect:Direct system, both of these IP addresses areincluded in the network map adjacent node entry for the original IBM Connect:Direct system.

In this example, assume a Process is started by the remote IBM Connect:Direct to this adjacent node withtwo NICs. The first path (TCP/IP address of 1364,199.1.4.1) is selected when the Process establishes itssession. For some reason, the NIC fails on the machine, and the Process fails and goes into retry.

If ALT.RESTART=NO (the default), this Process can never restart successfully because it will always usethe path used during initial session establishment (in this case, the failed NIC). When ALT.RESTART=YESis specified, the Process will try all ALT.COMM paths and will restart successfully because an additionalpath is available (ALT.ADDR=1.1.1.3,ALT.PORT=4374). ALT.NODEDEF points to another network entry andonly uses the primary address for that node. Connection failure using the primary address does not resultin running that node's ALT.COMM parameters (assuming it has any).

ADJACENT.NODE=((CD.NODE,1364,199.1.4.1,TCP) - PARSESS=(6 2) -ALT.COMM=(ALT.RESTART=YES,ALT.DIR=TOP,- (ALT.ADDR=1.1.1.3,ALT.PORT=4374,ALT.TYPE=TCP)) - )

Connect:Direct for z/OS Adjacent Node ExamplesThe following examples show how to define adjacent z/OS nodes.

SNA LU0The following example shows an adjacent z/OS node named CD.NYCZOS, with the communications name(VTAM APPLID) of CDDD10. The APPLIDS parameter indicates nine API sessions are possible.

Chapter 4. Administration Guide 273

ADJACENT.NODE=(PARSESS=(4,2) (CD.NYCZOS,CDDD10) - APPLIDS=(CDAPI01 CDAPI02 CDAPI03 CDAPI04 - CDAPI05 CDAPI06 CDAPI07 CDAPI08 CDAPI09))

CTCAThe following example shows an adjacent z/OS node named CD.DALLAS.ZOS1 which uses channel-to-channel adapter addresses E001-E008. The first address of each pair is used for outbound traffic; thesecond address is used for inbound traffic.

ADJACENT.NODE=(PARSESS=(4,1) - ENVIRONMENT=ZOS - (CD.DALLAS.ZOS1,E001,8,CTCA,,SEND))

In the network map entry of the adjacent node, an adjacent node entry for the other side of the CTCAconnection is in the following example. The z/OS node named CD.DALLAS.ZOS2 uses channel-to-channeladapter addresses F001–F008. The first address of each pair is used for inbound traffic. The secondaddress of each pair is used for outbound traffic.

ADJACENT.NODE=(PARSESS=(4,1) - ENVIRONMENT=ZOS - NETID=SERVER1 - (CD.DALLAS.ZOS2,F001,8,CTCA,,RECV))

TCP/IPThe following example shows three adjacent node entries with session protocol types of TCP/IP:

• The first, with a TCP/IP net name of ZOS.CD.CHICAGO, specifies the default TCP/IP port number byleaving the communications name positional parameter null.

• The second, with a TCP/IP net name of ZOS.CD.DALLAS, specifies a TCP/IP port number of 4444. The IPaddress will default to the node name, to be resolved by domain name resolution.

• The third, with a TCP/IP net name of ZOS.CD.AUSTIN, specifies a TCP/IP port number of 4443 and an IPaddress of 199.8.8.8.

• The fourth defines a TCPAPI to use port number 4442 and obtain the IP address from the adjacent noderecord.

• The fifth defines the LDNS parameter.

ADJACENT.NODE=(PARSESS=(4,2) - (ZOS.CD.CHICAGO,,199.1.4.51,TCP) - ENVIRONMENT=ZOS)

ADJACENT.NODE=(PARSESS=(4,2) - (ZOS.CD.DALLAS,4444,,TCP) - ENVIRONMENT=ZOS)

ADJACENT.NODE=(PARSESS=(4,2) - (ZOS.CD.AUSTIN,4443,199.8.8.8,TCP) - ENVIRONMENT=ZOS)

ADJACENT.NODE=(PARSESS=(4,2) - (ZOS.CD.AUSTIN,4443,199.8.8.8,TCP) - TCPAPI=(4442,) - ENVIRONMENT=ZOS)

ADJACENT.NODE=(PARSESS=(4,2) - (ZOS.CD.AUSTIN,4443, , TCP) - LDNS=(TCP.AUSTIN.DOMAIN) - TCPAPI=(4442, ) - ENVIRONMENT=ZOS)

274 IBM Connect:Direct for z/OS: Documentation

SNA LU6.2The following example shows an adjacent node entry for a node named CD.LAZOS with a communicationsname (APPLID) of APPLLAI and a session protocol type of LU6.2. The operating environment of thisadjacent node is z/OS, and the VTAM logmode entry which defines the session protocol used whencommunicating with this node is LU62MOD4. The LOGMODE parameter is required for LU6.2.

ADJACENT.NODE=(PARSESS=(4,2) - (CD.LAZOS,APPLLAI,,LU62) - ENVIRONMENT=ZOS LOGMODE=LU62MOD4 - APPLIDS=(CDDD2,CDDD3,CDDD4))

Trusted NodeThe following example shows an adjacent node entry for a node named SC.NODE.A with a security type ofexternal (EXT) and data direction restriction of SEND.

ADJACENT.NODE=(PARSESS=(4,2) - (SC.NODE.A,NZOSD20,,,EXT,SEND) - APPLIDS=(NZOSA36,NZOSA37,NZOSA38))

VM/ESA SNA LU0 Adjacent Node ExampleThe following example shows an adjacent node named CD.BOSTON.VM, with a communications name(APPLID) of CDDD16.

ADJACENT.NODE=(PARSESS=(4,2) (CD.BOSTON.VM,CDDD16) - APPLIDS=(CDAPI01 CDAPI02 CDAPI03 CDAPI04 - CDAPI05 CDAPI06 CDAPI07 CDAPI08 CDAPI09))

OpenVMS Adjacent Node ExampleThe following example shows an adjacent node named CD.DALLAS.VMS. The SNODE.LUS parameterspecifies the logical unit names used by the local node to initiate a session with this remote node.

ADJACENT.NODE=((CD.DALLAS.VMS) -PARSESS=(8,1) -PNODE.LUS=(N91LU09 N91LU0A N91LU0B N91LU0C - N91LU0D N91LU0E N91LU0F N91LU10) -SNODE.LUS=(N91LU07 N91LU08))

Microsoft Windows Adjacent Node ExampleThe following example show how to define adjacent Microsoft Windows nodes.

ADJACENT.NODE=( - (WIN.TCPIP.NODE,1364,123.4.5.67,TCP) - PARSESS=(20,1) - ENVIRONMENT=WINDOWS - )

UNIX Adjacent Node ExamplesThe following examples show how to define adjacent UNIX nodes.

TCP/IP Adjacent Node ExampleThe following example shows two adjacent node entries with session protocol types of TCP/IP:

Chapter 4. Administration Guide 275

• The first entry specifies the default TCP/IP port number by leaving the communications name positionalparameter null. The IP address will default to the node name to be resolved by domain name resolution.

• The second entry specifies a TCP/IP port number of 5555 and an IP address of 199.5.5.5.

ADJACENT.NODE=(PARSESS=(6,2) - (UNIX.CD.CHICAGO,,,TCP) - ENVIRONMENT=UNIX)ADJACENT.NODE=(PARSESS=(6,2) - (UNIX.CD.DALLAS,5555,199.5.5.5,TCP) - ENVIRONMENT=UNIX)

Notice that no APPLID or LOGMODE keywords are used for any TCP/IP node. A warning is generated forany unneeded keyword or subparameter, and the coded value is ignored.

LU6.2 Adjacent Node ExampleThe following example shows an adjacent UNIX node with a communications name (APPLID) of D1UNIXand a session protocol type of LU6.2. The logmode entry name is LU62MODE. The LOGMODE parameter isrequired for LU6.2.

ADJACENT.NODE=(PARSESS=(6,2) - (UNIX.LU62.DALLAS,D1UNIX,,LU62) - LOGMODE=LU62MODE - ENVIRONMENT=UNIX)

Stratus VOS Adjacent Node ExamplesThe following examples show how to define adjacent Stratus VOS nodes.

TCP/IPThe following example shows an adjacent node entry with a session protocol type of TCP/IP, a TCP netname of CD.STRAT, a TCP port number of 3333, and an IP address of 199.1.1.11.

ADJACENT.NODE=(PARSESS=(12,1) - (CD.STRAT,3333,199.1.1.11,TCP) - ENVIRONMENT=STRATUS)

LU0The following example shows an adjacent Stratus VOS node with a communications name (APPLID) ofM1T20404 and a session protocol type of LU0. The logmode entry name is CDPCLU0. The LOGMODEparameter is optional for LU0.

ADJACENT.NODE=(( CD.STRAT,M1T20404,,SNA) - LOGMODE=CDPCLU0)

i5/OS Adjacent Node ExamplesThe following examples show how to define adjacent i5/OS nodes.

i5/OS SNUF

The following example shows an adjacent node named AS400.CD.TX with a remote library name ofLBNAME and session protocol type of LU0 (SNUF). The SNODE.LUS parameter defines the dependent LUpool.

276 IBM Connect:Direct for z/OS: Documentation

ADJACENT.NODE=(PARSESS=(4,2) - (AS400.CD.TX,,LBNAME,SNUF) - SNODE.LUS=(N11LU01,N11LU02,N11LU03,N11LU04))

LU6.2 with Independent LUThe following example shows an adjacent node named AS400.CD.LA with an independent LUcommunications name of APPLLA1, a remote library name of CDLIB1, a session protocol type of LU6.2,and a logmode entry name of LU62MOD2. The ENVIRONMENT=OS400 parameter is required for i5/OSnodes using the LU6.2 protocol. The LOGMODE parameter is required for the LU6.2 protocol.

ADJACENT.NODE=(PARSESS=(6,2) - (AS400.CD.LA,APPLLA1,CDLIB1,LU62) - ENVIRONMENT=OS400 LOGMODE=LU62MOD2)

LU6.2 with Dependent LUThe following example shows an adjacent i5/OS node named AS400.CD.NY with a remote library nameof CDLIB1, a session protocol type of LU6.2, and a logmode entry name of LU62MOD3. The SNODE=LUSparameter defines the dependent LU pool. The ENVIRONMENT=OS400 parameter is required for i5/OSnodes using the LU6.2 protocol. The LOGMODE parameter is required for the LU6.2 protocol.

ADJACENT.NODE=(PARSESS=(4,2) - (AS400.CD.NY,,CDLIB1,LU62) - ENVIRONMENT=OS400 LOGMODE=LU62MOD3 - SNODE.LUS=(NYLU01,NYLU02,NYLU03,NYLU04))

TCP/IPThe following example shows an adjacent node entry with a node name of OS400.TCP.NODE, sessionprotocol type of TCP, a TCP port number of 1364, and an IP address of 199.1.1.11.

ADJACENT.NODE=( - (OS400.TCP.NODE,1364,199.1.1.11,TCP,INT,BOTH) - CRC=DEFAULT - PARSESS=(20,2))

How to Update the Network MapThe network map is created during installation, when the network map source is input to the network mapload program.

The network map source contains one local node entry and multiple adjacent node entries. It can contain$$ACTION verbs added during previous maintenance.

You can update the network map source while IBM Connect:Direct is not executing or dynamically whileIBM Connect:Direct is executing.

Note: To test connectivity to an ADJACENT.NODE, use the DGAPHTBT Process (see $CD.SDGASAMP). ThisProcess makes a connection to the ADJACENT.NODE and executes a RUN TASK at the local node. Beaware that the connection causes both IBM Connect:Direct nodes to search their TCQ files for Processesdestined for the other node.

Updating the Network Map while IBM Connect:Direct is Not ExecutingYou can update the network map using the network map source and the DGAJLOAD JCL which loaded thesource at initialization.

Chapter 4. Administration Guide 277

You can only update the local node by performing the following steps:

1. Change the network map source. The network map source is loaded at installation into$CD.SDGACNTL(NETMAP01)

2. Stop IBM Connect:Direct.3. Delete and redefine the network map. Refer to the JCL in $CD.SDGAJCL(DGAJJDEF).4. Reload the network map. Refer to the JCL in $CD.SDGAJCL(DGAJLOAD).5. Restart IBM Connect:Direct.

Updating the Network Map while IBM Connect:Direct is RunningYou can update the network map without deleting and redefining it. In addition, you can update thenetwork map source without stopping IBM Connect:Direct, by using the UPDATE NETMAP command.

After updating the network map with UPDATE NETMAP, you can refresh the network map for anyProcesses in the Wait queue with the Change Process command. See the IBM Connect:Direct for z/OSUser Guide for a description of the Change Process command.

Note: Any changes to the CTCA definition do not take effect until IBM Connect:Direct is reinitialized.

As with most commands, you can execute the command through a batch job or through the IUI. Bothmethods use $$ACTION verbs as part of the network map source.

Note: This method of updating the network map is only available for adjacent nodes.

The format of the UPDATE NETMAP command follows.

Label Command Parameters

(optional) UPDATE NETMAP WHERE (

NETINput= filename(member name)

NETLOG =[ddname | NONE]

)

DIS | PRT

Note: Reinitialize IBM Connect:Direct before CTCA definition changes or additions are effective.

Required ParameterWHERE is the only required parameter for the UPDATE NETMAP command.

278 IBM Connect:Direct for z/OS: Documentation

Parameter Description

WHERE

(NETINput = filename(member name)

NETLOG = [ddname |NONE] )

Network map source file and where the update activity is reported.

NETINput = filename (member name) specifies the name of the network mapsource file. This file can be sequential or a PDS member. The network mapsource can contain multiple basic action verbs, multiple special purpose actionverbs, or a combination of both. The source that updates the network map canbe the entire network map source or a subset of it.

NETLOG = [ddname | NONE] specifies where the update activity is reported.

ddname specifies the data definition name allocated to the IBM Connect:DirectDTF where the update activity is reported. The first two characters of theddname must be CD.

NONE specifies that no update activity is reported.

If the parameter is left blank the update activity is reported to the CDLOGdata set. Regardless of which option is selected the activity is recorded in theStatistics file as WTO records.

Optional ParameterParameter Description

DIS | PRT Use the DIS or the PRT optional parameter to specify the output destination.

DIS indicates that the activity is reported in display format, either to the screen forIUI requests or to the DDNAME for batch requests.

PRT indicates that the output is routed to SYSOUT for batch requests and to theprint destination specified by the PRINT FILE DESTINATION parameter in thesignon defaults.

Using $$ACTION VERBS in the Network MapAdd $$ACTION verbs to the network map source as described in the description of the NETINPUTparameter of the UPDATE NETMAP command. For more information on the required parameter,NETINPUT, refer to “Updating the Network Map while IBM Connect:Direct is Running” on page 278.Each verb defines the action to take for the node entry immediately following the action verb. Three basicaction verbs and three special purpose action verb pairs exist. For effect of the $$ACTION verbs on thenode usage information see, “Node Usage Information Maintenance” on page 269.

Note: The PNODE.LAST.USED and SNODE.LAST.USED parameters are not supported by the $$ACTIONverbs.

The following table describes the action verbs:

Action Verb Description

$$INSERT Inserts the following node entry into the network map.

$$UPDATE Updates the following existing network map node entry. Node entry updates areperformed as a replacement at the keyword level. Therefore, updates of list-typekeywords, like APPLIDS, require that you specify the entire list.

Do not use $$UPDATE to update network map node entries which already containthe LDNS parameter. Use $$DELETE and $$ INSERT to change nodes whichcontain an LDNS parameter.

Note: You can use $$UPDATE to add the LDNS parameter to a node which did notpreviously contain one.

Chapter 4. Administration Guide 279

Action Verb Description

$$REPLACE Replaces the present node entry with the one following the $$REPLACE verb. Thisverb first does a $$DELETE and then a $$INSERT. It can be used in place of$$UPDATE.

$$DELETE Deletes the following existing network map node entry.

$$SYNTAX and $$ENDSYNTAX

Performs a syntax check of the network map control statements following thisverb.

$$VERIFY and $$ENDVERIFY

Verifies that the node definitions following this verb match those in the networkmap.

$$BLKxxxxxx and$$ENDxxxxxx

Performs the basic action verb defined by xxxxxx for the block of node entriesfollowing this verb. Replace xxxxxx with either INSERT, UPDATE, or DELETE.

Updating the Netmap through the Batch InterfaceTo issue the UPDATE NETMAP command through the IBM Connect:Direct batch utility, follow thisprocedure.

1. Change the network map source using the $$ACTION verbs.2. Place the UPDATE NETMAP commands in the batch job stream.3. Ensure that IBM Connect:Direct is running.4. Submit the job.5. Correct any errors identified on the activity report and resubmit if necessary.6. Verify the results.

Updating the Netmap through the IUI InterfaceTo issue the UPDATE NETMAP command through the IBM Connect:Direct IUI, perform the followingsteps.

Note: Updating the network map through the IUI can take significant time. For mass updates, considerbatch processing.

1. To change or create a new member with your updates, change the network map source to use the$$ACTION verbs.

2. Ensure that IBM Connect:Direct is running.3. Access the Update network map screen by selecting option UNM from the Administrative Options

Menu.

node.name UPDATE NETWORK MAP hh:mm CMD ==>

WARNING: THIS COMMAND CAN TAKE SIGNIFICANT TIME. FOR MASS UPDATES, BATCH PROCESSING SHOULD BE CONSIDERED!

ENTER NETMAP INPUT FILE NAME: ==> ____________________________________________

ENTER MEMBER NAME: (OPTIONAL) ==> ________

ENTER DDNAME FOR LOG FILE OR "NONE": (DEFAULTS TO "CDLOG", ==> ________ FIRST TWO CHARACTERS MUST BE “CD”)

OUTPUT DESTINATION ==> DIS (DIS-DISPLAY,PRT-PRINT)

4. Type the network map source file name and appropriate optional parameters and press ENTER. Unlessyou select PRINT on the Update NETMAP screen, the report routes to your terminal.

280 IBM Connect:Direct for z/OS: Documentation

5. Verify the results on the activity report.6. Correct any errors identified on the activity report and re-type if necessary.

$$ACTION Verb ExamplesThe following are examples of updating the network map through the use of action verbs.

$$INSERT ExampleThe following $$INSERT command inserts an adjacent node into the network map.

$$INSERT ADJACENT.NODE=((CD.NODE2 APPLID2 ) - PARSESS=(5,2) - APPLIDS=(RAPPL1))

The output follows.

= = > * * * START NETMAP UPDATE * * *= = > DATE: 02/27/2003 TIME=14:59:26= = > SMUPNLGI NETLOG=NONE REQUIRED, LOGGING INACTIVE==============================================================*INSERT THE FOLLOWING NODE DEFINITION$$INSERT ADJACENT.NODE=(( CD.NODE2 APPLID2 ) - PARSESS=(5,2) - APPLIDS=(RAPPL1 ))= = > SMUP032I APPLIDS RECORD INSERTED= = > SMUP034I ADJACENT.NODE RECORD INSERTED= = > SMUP008I REQUEST SUCCESSFUL FOR NODE=CD.NODE2============================================================

The first message, SMUPNLGI, shows that logging is not requested; therefore, IBM Connect:Direct doesnot keep a record of the transaction (except in the statistics file). The last messages indicate that theinformation for the specified adjacent node was successfully inserted.

$$UPDATE ExampleThe following $$UPDATE command updates an adjacent node in the network map by adding the RAPPL2APPLID and changing the maximum parallel sessions to four.

$$UPDATE ADJACENT.NODE=(( CD.NODE2 APPLID2 ) - PARSESS=(4,2) - APPLIDS=(RAPPL1 RAPPL2 ))

The output follows.

Chapter 4. Administration Guide 281

= = > * * * START NETMAP UPDATE * * *= = > DATE: 02/27/2003 TIME=14:59:26= = > SMUPNLGI LOGGING ACTIVE - LOG DDNAME=CDLOG===============================================================

*UPDATE THE FOLLOWING NODE DEFINITION ADDING RAPPL2*CHANGING MAXIMUM PARALLEL SESSIONS TO FOUR (4).$$UPDATE ADJACENT.NODE=(( CD.NODE2 APPLID2 ) - PARSESS=(4,2) - APPLIDS=(RAPPL1 RAPPL2))

= = > SMUP032I APPLIDS RECORD UPDATED= = > SMUP034I ADJACENT.NODE RECORD UPDATED= = > SMUP008I REQUEST SUCCESSFUL FOR NODE=CD.NODE2================================================================

The first message, SMUPNLGI, shows that logging is requested and that a record of the transaction isrecorded in CDLOG. The last messages indicate that the adjacent node information was successfullyupdated.

$$REPLACE ExampleThe following $$REPLACE command deletes then inserts an adjacent node in the network map.

$$REPLACEADJACENT.NODE=((CD.NODE2 APPLID2) -PARSESS=(4,2) -APPLIDS=(RAPPL1 RAPPL2))

The output follows.

==> * * * S T A R T N E T M A P U P D A T E * * *

==> DATE: 04.02.2010 TIME=14:18:47

==> SMUPLOGI LOGGING ACTIVE - LOG DDNAME=CDLOG

======================================================================

$$REPLACE ADJACENT.NODE=( - (CD.NODE2,APPLID2) - PARSESS=(6 2) - APPLIDS=(RAPPL1 RAPPL2) - )

==> SMUP034I ADJACENT.NODE record "DELETED ".==> SMUP032I APPLIDS record "INSERTED".==> SMUP034I ADJACENT.NODE record "INSERTED".==> SMUP008I Request successful for Node=CD.NODE2======================================================================

==> SMUP000I C:D Network Map processing completed.

==> DATE: 04.02.2010 TIME=14:18:47

==> * * * E N D N E T M A P U P D A T E * * *

$$DELETE ExampleThe following $$DELETE command deletes an adjacent node from the network map.

282 IBM Connect:Direct for z/OS: Documentation

$$DELETE ADJACENT.NODE=((CD.NODE2 APPLID2) - PARSESS=(4,2) - APPLIDS=(RAPPL1 RAPPL2))

The output follows.

= = > * * * START NETMAP UPDATE * * *= = > DATE: 02/27/2003 TIME=15:09:36= = > SMUPNLGI NETLOG=NONE REQUIRED, LOGGING INACTIVE=================================================================$$DELETE ADJACENT.NODE=((CD.NODE2 APPLID2) - PARSESS=(4,2) - APPLIDS=(RAPPL1 RAPPL2 ))= = > SMUP032I APPLIDS RECORD DELETED= = > SMUP034I ADJACENT.NODE RECORD DELETED= = > SMUP008I REQUEST SUCCESSFUL FOR NODE=CD.NODE1================================================================

The first message, SMUPNLGI, indicates that logging is not requested, so IBM Connect:Direct does notkeep a record of the transaction. The last messages indicate that the APPLIDs and adjacent node recordsare successfully deleted.

$$SYNTAX ExampleThe following $$SYNTAX command performs a syntax check on the specified nodes.

$$SYNTAX LOCAL.NODE=((CD.NODE1 APPLID1 ,, SUPERUSR) - TCQ=( TCQ TCX )) ADJACENT.NODE=((CD.NODE1 APPLID1) - PARSESS=(5,2) - APPLIDS=(LAPPL1 LAPPL2 LAPPL3)) ADJACENT.NODE=((CD.NODE2 APPLID2) - PARSESS=(5,2) - APPLIDS=(RAPPL1 )) $$ENDSYNTAX

The output follows. The messages are numbered in the example for clarification; they are not numberedon the actual output.

= = > * * * START NETMAP UPDATE * * * = = > DATE: 02/27/2003 TIME=13:49:16(1) = = > SMUPNLGI NETLOG=NONE REQUIRED, LOGGING INACTIVE===================================================================== $$SYNTAX(2) = = > SMUP011I 'SYNTAX ' ACTION STARTED===================================================================== LOCAL.NODE=(( CD.NODE1 APPLID1 ,, SUPERUSR) - TCQ=( TCQ TCX ))(3) = = > SMUP005I LOCAL.NODE RECORD PROCESSING NOT ALLOWED BYPASSED===================================================================== ADJACENT.NODE=(( CD.NODE1 APPLID1 ) - PARSESS=(5,2) - APPLIDS=(LAPPL1 LAPPL2 LAPPL3))(4) = = > SMUP008I REQUEST SUCCESSFUL FOR NODE=CD.NODE1===================================================================== ADJACENT.NODE=(( CD.NODE2 APPLID2 ) - PARSESS=(5,2) - APPLIDS=(RAPPL1))(4) = = > SMUP008I REQUEST SUCCESSFUL FOR NODE=CD.NODE2===================================================================== $$ENDSYNTAX(5) = = > SMUP012I 'SYNTAX ' ACTION STOPPED=====================================================================

Chapter 4. Administration Guide 283

The numbers in parentheses indicate:

1. Logging is not requested; therefore, no record is kept of the transaction.2. Syntax check of network map control statements starts.3. No processing is allowed against the local node record.4. Requests for syntax checking on nodes are successful.5. Syntax checking completes.

$$VERIFY ExampleThe following $$VERIFY command verifies the definition of the specified adjacent node record prior toupdating the network map.

$$VERIFY ADJACENT.NODE=((CD.NODE2 APPLID2) - PARSESS=(5,2) - APPLIDS=(RAPPL1))$$ENDVERIFY

The output follows. The messages are numbered in the example for clarification; they are not numberedon the actual output.

= = > * * * START NETMAP UPDATE * * * = = > DATE: 02/27/2003 TIME=15:35:16(1) = = > SMUPNLGI NETLOG=NONE REQUIRED, LOGGING INACTIVE===================================================================== $$VERIFY

(2) = = > SMUP011I 'VERIFY ' ACTION STARTED=====================================================================

ADJACENT.NODE=(( CD.NODE2 APPLID2 ) - PARSESS=(5,2) - APPLIDS=(RAPPL1 ))(3) = = > SMUP092I APPLIDS RECORD DID NOT MATCH = = > SMUP094I ADJACENT.NODE RECORD DID NOT MATCH = = > SMUP096I RECORDS DO NOT MATCH - VERIFICATION FAILED FOR NODE =CD.NODE2=====================================================================

$$ENDVERIFY

(4) = = > SMUP012I 'VERIFY ' ACTION STOPPED=====================================================================

The number in parentheses indicate the following steps:

1. Logging is not requested; therefore, no record is kept of the transaction.2. Verification of the node definition to the network map file has started.3. The APPLIDs and adjacent node records did not match the network map file definitions.4. Verification is complete.

284 IBM Connect:Direct for z/OS: Documentation

Viewing the Network MapYou can view the network map online through the IUI interface or view the contents of the network mapby unloading the network map VSAM file source.

Viewing the Netmap through the IUI InterfaceTo view the network map using the IBM Connect:Direct IUI, select option NM from the Primary OptionsMenu to display the SELECT NETMAP OR TCP INFORMATION screen. For more information, see TheNetwork Map in the IBM Connect:Direct for z/OS User Guide.

Unloading the Network Map to the Source Format

IBM Connect:Direct provides a utility to unload the network map to its source format. You can then viewthe source format to see network map settings. This utility is provided in the DGAJUNLD member in the$CD.SDGAJCL data set.

To unload the network map, submit the DGAJUNLD member. You can unload the network map while IBMConnect:Direct is running.

An example of the JCL follows.

//STEP EXEC PGM=DGADNTLD,PARM='UNLOAD'//NETMAP DD DSN=NETMAP.DATASET,DISP=SHR//UNLOAD DD DSN=NETMAP.UNLOAD,DISP=(NEW,CATLG),// DCB=(DSORG=PS,RECFM=FB,BLKSIZE=0,LRECL=80),// UNIT=SYSDA,SPACE=(TRK,(4,2,))

The network map source is unloaded to the data set specified in the JCL.

Configuring a IBM Connect:Direct/Plex EnvironmentIBM Connect:Direct runs in two configurations:

• IBM Connect:Direct Stand-alone Server, which is a single IBM Connect:Direct system operating withinan IBM z/OS environment.

• IBM Connect:Direct/Plex, which is a IBM Connect:Direct system operating in an IBM z/OS sysplexor parallel sysplex environment consisting of a IBM Connect:Direct Manager and one or more IBMConnect:Direct Servers.

Differences Between Stand-Alone and Plex EnvironmentsA IBM Connect:Direct Stand-alone Server and a IBM Connect:Direct/Plex environment have the followingconfiguration differences:

• Initialization parameters

The two sets of initialization parameters in IBM Connect:Direct are global and local.

A IBM Connect:Direct Stand-alone Server uses only global initialization parameters to set system-widevalues, as shown in the following illustration.

Chapter 4. Administration Guide 285

A IBM Connect:Direct/Plex environment uses both global and local initialization parameters. Globalinitialization parameters apply to each member of the IBM Connect:Direct/Plex environment. Localinitialization parameters apply to specific members of the IBM Connect:Direct/Plex environment andcan override some global initialization parameters affecting that member. Each IBM Connect:Direct/Plex member must have its own local initialization parameter member with the parameter,“CDPLEX.MANAGER = NO | YES” on page 512, as the first statement in the member.

Note: You can save a copy of a local initialization parameters member to have as a backup in case IBMConnect:Direct cannot start up successfully after initparm updates have been applied. Specify the nameof the backup file using the local initialization parameter, CDPLEX.INITPARM.BACKUP = member. Be sureto specify this parameter for each IBM Connect:Direct/Plex member.

If an update of the global and local initialization parameter files is performed using Control Center andfails during the process, IBM Connect:Direct will use the backup members to restore the parameters. IBMConnect:Direct will never use the backup members to initialize the DTF unless you explictily instruct thesystem to do so by updating the JCL to use the backup members as the initparm members.

Global initialization parameters are stored in a file shared by all IBM Connect:Direct/Plex members. Inthe EXEC statement (IBM Connect:Direct Stand-alone Server and IBM Connect:Direct/Plex), the PARM=keyword specifies the name and location of the global initialization parameters file.

The local initialization parameters of each IBM Connect:Direct/Plex member are stored in a unique PDSmember for each system (one for the Plex Manager and one for each server). The location of the localinitialization parameters file is specified by the //CDPLEX DD in the startup JCL of each member.

In a IBM Connect:Direct/Plex environment, you can override only the initialization parameters allowed inthe local initialization parameters member by using the PARM= keyword in the EXEC statement at systemstartup.

In a IBM Connect:Direct Stand-alone Server environment, however, you can override global initializationparameters with the PARM= keyword in the EXEC statement.

The following illustration shows how global and local initialization parameters are used in a IBMConnect:Direct/Plex environment.

• VTAM APPLIDs

286 IBM Connect:Direct for z/OS: Documentation

A IBM Connect:Direct Stand-alone Server obtains its VTAM APPLIDs from the network map.

In a IBM Connect:Direct/Plex environment, the IBM Connect:Direct/Manager obtains its VTAM APPLIDsfrom the network map, but each IBM Connect:Direct Server obtains its VTAM APPLIDs from its localinitialization parameters file.

• TCP/IP addresses and ports

A IBM Connect:Direct Stand-alone Server obtains its TCP/IP listen ports from the global initializationparameters file.

In a IBM Connect:Direct/Plex environment, the IBM Connect:Direct Manager and IBM Connect:DirectServers obtain their TCP/IP addresses and listen port numbers from their local initialization parametersmembers. However, if the TCP port number is not specified in the local initialization parametersmember of the IBM Connect:Direct Manager, the IBM Connect:Direct Manager obtains its listen portnumber from the global initialization parameters member.

Each server overrides the global initialization parameters by specifying those parameters in thatserver's local initialization parameters. The first address defined in the parameter becomes the localor default address. For more information about defining TCP/IP listening tasks, see TCP/IP Port Number.

The CDPLEX.REDIRECT local initialization parameter is used by the IBM Connect:Direct/Plex Manager inthe IBM Connect:Direct/Plex environment to determine the redirection address that is presented to theremote node. This parameter allows you to specify redirection addresses based on the security nodetype (internal or external) and session type (TCP/IP) of the adjacent node in the network map.

When an address is specified, an internal address and external address is defined and each can havea specified redirection port defined. When the adjacent node entry is defined with the INT flag, theappropriate internal address is returned. Conversely, when the EXT flag is defined, the appropriateexternal address is returned.

Note: If your environment requires additional external redirection addresses to enable aremote IBM Connect:Direct server to run Processes, see the local initialization parameter,CDPLEX.REDIRECT.EXCEPTION = ((Mgr-IP, Ext_Svr-IP, Ext_Svr-port, Exception-IP, Exception-port),...).

Up to eight different addresses or ports can be defined for each server. However, in the IBMConnect:Direct/Plex server that defines CDPLEX.REDIRECT only two are effectively used when Processredirection occurs. To use the additional port in the IBM Connect:Direct/Plex servers, those serversmust be contacted directly by the remote node.

Note: A special consideration exists if the IBM Connect:Direct/Plex Manager is initialized on a systemthat is not IPv6 enabled, and one or more of the servers supports IPv6. When the IBM Connect:Direct/Plex is the SNODE, the IBM Connect:Direct/Plex Manager accepts connection requests for IPv4 only.However, if the IBM Connect:Direct/Plex is the PNODE, the IBM Connect:Direct/Plex Manager canassign outbound processes to a IBM Connect:Direct Server that supports IPv6.

• System files

In a IBM Connect:Direct Stand-alone Server, the system files (network map, Statistics Pairs, CKPT,AUTH, Message, TCQ and TCX files) are stored in one location and apply to the entire DTF. If two IBMConnect:Direct Stand-alone Server systems operate in a sysplex environment, each system must haveits own system files.

In a IBM Connect:Direct/Plex environment, the system files are also stored in one location and areshared by all IBM Connect:Direct/Plex members, as in the earlier illustration. Only one set of systemfiles is needed for all IBM Connect:Direct/Plex members.

A New IBM Connect:Direct/Plex EnvironmentUse this setup for a new installation. The setup in this section assumes the following:

• You have installed and started a single IBM Connect:Direct DTF.• You are changing a IBM Connect:Direct Stand-alone Server into a IBM Connect:Direct/Plex environment

with three members: the IBM Connect:Direct Manager and two IBM Connect:Direct Servers. The IBM

Chapter 4. Administration Guide 287

Connect:Direct Servers are named SERVER1 and SERVER2. SERVER1 has tape drive access for copyProcesses requiring tapes.

• The global and local initialization parameters files are located in $CD.PLEX.INITPARM (a PDS, not aPDSE, that you have built). The JCL to bring up the IBM Connect:Direct/Plex environment is located in$CD.PLEX.JCL. You can either allocate these data sets or use existing data sets in their place. Do not useIBM Connect:Direct's SMP/E target PDSes for these data sets.

Setting Up a New IBM Connect:Direct/Plex EnvironmentTo set up a IBM Connect:Direct/Plex environment:

1. Create a PDS (which will be referred to as $CD.PLEX.INITPARM in this procedure) to hold theinitialization parameters for the IBM Connect:Direct Plex environment, with sufficient directory spaceto handle ISPF Statistics. Create a PDS (which will be referred to as $CD.PLEX.JCL) to hold the JCL.

2. Copy your current DTF's INITPARM member into $CD.PLEX.INITPARM as member CDPLX.3. Copy your current IBM Connect:Direct Stand-alone Server startup JCL into $CD.PLEX.JCL as member

CDMGR.4. Add the following initialization parameters to the CDPLX member in $CD.PLEX.INITPARM. This

member becomes the IBM Connect:Direct/Plex global initialization parameters file.

CDPLEX=YESCDPLEX.MAXSERVER = number of servers | 4XCF.NAME=8-char-name

The CDPLEX=YES parameter indicates a IBM Connect:Direct/Plex environment. It also directs theDTF to read its local initialization parameters from the file specified in the //CDPLEX DD statement inthe startup JCL.

The CDPLEX.MAXSERVER parameter specifies the maximum number of servers the Connect:Direct/Plex Manager will manage. For more information, see Storage Requirements in a IBM Connect:DirectEnvironment in the IBM Connect:Direct for z/OS Configuration Guide.

The XCF.NAME parameter specifies a unique name used by the z/OS Cross Systems CommunicationFacility (XCF) to assist communications among IBM Connect:Direct/Plex members. This nameindicates that the IBM Connect:Direct Manager and IBM Connect:Direct Servers are part of the sameXCF group.

5. Add the following optional parameters to the CDPLX member in $CD.PLEX.INITPARM.

• CDPLEX.TIMER specifies the time-out value for XCF communications in minutes.• CDPLEX.WLM.GOAL specifies whether IBM Workload Manager (WLM) Goal Mode queries are made.

This parameter is optional.6. Create a local initialization parameters file for the IBM Connect:Direct Manager:

a) Copy the MANAGER sample local initialization parameters member from the IBM Connect:Directinstallation $CD.SDGAPARM(DGAIPMGR) into $CD.PLEX.INITPARM.

b) Change the TCP.LISTEN parameter of the MANAGER member to specify the TCP/IP stack addressused by the IBM Connect:Direct Manager.

CDPLEX.MANAGER=YESTCP.LISTEN=(nnn.nnn.nnn.nnn,port)CDPLEX.SERVER.JOBDSN=$CD.PLEX.JCLCDPLEX.SERVER.JOBMEM=((CDSRV1,SERVER1), - (CDSRV2,SERVER2))

7. Create a local initialization parameters file for IBM Connect:Direct SERVER1:a) Copy the sample local initialization member $CD.SDGAPARM(DGAISRV1), into

$CD.PLEX.INITPARM as member SERVER1.b) Change the CDPLEX.VTAM parameter in the SERVER1 member as follows:

288 IBM Connect:Direct for z/OS: Documentation

• Replace the applid11 value with the VTAM APPLID used by this IBM Connect:Direct Server forSNA (Node to Node/PROCESS use, as opposed to API use).

• Replace the applid12 value with the PNODE-SNODE APPLID.

These APPLIDs must be unique across the IBM Connect:Direct/Plex environment and cannot bethe same as those specified in the network map.

CDPLEX.MANAGER=NOCDPLEX.SERVER=SERVER1CDPLEX.VTAM=(applid11,applid12)CDPLEX.PLEXCLASSES=(TAPE,*)TCP.LISTEN=(nnn.nnn.nnn.nnn,port)

The TCP.LISTEN initialization parameters specifies the TCP listen address and port numbercombinations. Use a different listen port number than the one used in the existing initializationparameters file.

Note: The CDPLEX.PLEXCLASSES parameter in SERVER1 specifies a ‘TAPE' PLEXCLASS. ForProcesses that require tape drives, specify the ‘TAPE' PLEXCLASS in their Process definitions.These Processes run on SERVER1. (See the chapters about building Processes and controllingProcesses in the TCQ in IBM Connect:Direct for z/OS User Guide for more information on usingPLEXCLASS in a Process.)

8. Create a local initialization parameters file for IBM Connect:Direct SERVER2:a) Copy the sample local initialization member $CD.SDGAPARM(DGAISRV2), into

$CD.PLEX.INITPARM as member SERVER2.b) Change the CDPLEX.VTAM parameter in the SERVER2 member as follows:

• Replace the applid21 value with the VTAM APPLID used by this IBM Connect:Direct Server forSNA copy Processes.

• Replace the applid22 value with the PNODE-SNODE APPLID.

These APPLIDs must be unique across the IBM Connect:Direct/Plex environment and cannot bethe same as those specified in the network map.

CDPLEX.MANAGER=NOCDPLEX.SERVER=SERVER2CDPLEX.VTAM=(applid21,applid22)CDPLEX.PLEXCLASSES=(*)TCP.LISTEN=(nnn.nnn.nnn.nnn,port)

9. Add the CDPLEX DD statement in the following example to the CDMGR member in $CD.PLEX.JCL.

This statement directs the startup JCL to the global initialization parameters file.

//DTF EXEC DGADINIT,// PARM='$CD.PLEX.INITPARM(CDPLX)'//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(MANAGER)

10. Create CDSRV1 in $CD.PLEX.JCL and copy the CDMGR member into it.11. Make the following changes to the CDSRV1 member:

a) Change the job name so that this job can run simultaneously with the CDMGR JCL.b) Change the member name in the CDPLEX DD statement to SERVER1, as follows. This change

directs the CDSRV1 JCL to its local initialization parameters file.

//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(SERVER1)

12. Create a CDSRV2 member and copy CDSRV1 into it.13. Make the following changes to the CDSRV2 member:

Chapter 4. Administration Guide 289

a) Change the job name so that this job can run simultaneously with the CDMGR JCL and CDSRV1JCL.

b) Change the member name in the CDPLEX DD statement to SERVER2, as follows. This changedirects the CDSRV2 JCL to its local initialization parameters file.

//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(SERVER2)

Note: Route jobs to a different z/OS image by specifying the local node name of the other systemin an XEQ statement in the IBM Connect:Direct Manager or Server startup JCL, as follows:

/*XEQ njenode[JES2]//*ROUTE XEQ njenode [JES3]

This example routes the job to the z/OS image identified by the local node name NJENODE.14. Submit the CDMGR JCL to bring up the IBM Connect:Direct/Plex server.

After the IBM Connect:Direct Manager initializes, it submits the CDSRV1 JCL and CDSRV2 JCL to bringup the two IBM Connect:Direct Servers.

15. After IBM Connect:Direct Manager initializes, use the IUI to signon.

You can then submit Processes and perform other functions through the IUI.

Advanced IBM Connect:Direct:/Plex Configuration ConsiderationsExamples of complex configurations include:

• Converting an Existing Stand-Alone Server to a Plex Environment• Converting Two Existing Stand-Alone Server Systems to a Plex Environment

Before attempting a complex configuration, be aware of the following issues.

IBM Connect:Direct/Plex System File ConsiderationsAll IBM Connect:Direct:/Plex members share a single set of IBM Connect:Direct system files. If youcombine multiple existing IBM Connect:Direct systems into one IBM Connect:Direct/Plex environment,you may need to merge some IBM Connect:Direct system files from the individual systems.

Do not merge system files that are listed in the following table.

File Comment

CKPT file You cannot merge the CKPT files from multiple IBM Connect:Direct images. You musteither:

• Define a new CKPT file using the DGAXCKPD JCL in the $CD.SDGASAMP library, or• Use the CKPT file from one of the existing IBM Connect:Direct systems. However, the

existing CKPT file size may not be sufficient for a IBM Connect:Direct/Plex environment.

Messagefile

You can use any existing IBM Connect:Direct Message file. You do not need to combineMessage files from the individual IBM Connect:Direct systems.

Statisticsfiles

You cannot merge statistics files from multiple IBM Connect:Direct images. You canreference them using a IBM Connect:Direct/Plex environment as archived statistic files.You can create new statistics file pairs by using the DGAXSTAD JCL in the $CD.SDGASAMPlibrary.

290 IBM Connect:Direct for z/OS: Documentation

File Comment

TCQ andTCX files

You cannot merge TCQ and TCX files from multiple IBM Connect:Direct images. You musteither:

• Define new TCQ and TCX files using the DGAXTCQD JCL in the $CD.SDGASAMP library, or• Use the TCQ and TCX files from one of the existing IBM Connect:Direct systems.

However, the existing TCQ and TCX file sizes may not be sufficient for a IBMConnect:Direct/Plex environment.

The following table lists system files that you need to merge.

File Comment

AUTH file If unique entries exist in the existing IBM Connect:Direct systems' AUTH files:

1. Define a new AUTH file using the DGAXAUTD JCL found in the $CD.SDGASAMP library.2. Copy the existing AUTH files into the new AUTH file using the DGAXAUTC JCL found in

the $CD.SDGASAMP library.

PLEXAUTC is an IDCAMS REPRO that specifies NOREPLACE. If any duplicate records exist,only the first one is saved.

If unique entries do not exist, use one of the existing AUTH files.

NETMAPfile

You need to create a new network map source file.

The new network map source file uses information from the existing systems' networkmaps. (If the existing IBM Connect:Direct systems' network map source is not available,create the source files by performing network map unloads for the existing systems'network map files. See Unloading the Network Map to the Source Format for moreinformation.)

To create a new network map source file:

1. Copy the network map source from an existing IBM Connect:Direct system asNETMAPLX.

2. Copy the remote definitions from all other existing network map source files intoNETMAPLX.

3. Remove all duplicate entries.4. Define the new network map file using the DGAXNETD JCL found in the

$CD.SDGASAMP library.5. Load the new network map file using the DGAXNETL JCL found in the $CD.SDGASAMP

library.6. Check the output from network map load and correct any errors.7. Rerun the network map load if necessary.

TYPE file If unique entries exist in the existing IBM Connect:Direct systems' TYPE files:

1. Define a new TYPE file using the DGAXTYPD JCL found in the $CD.SDGASAMP library.2. Copy the existing TYPE files into the new TYPE file using the DGAXTYPC JCL found in

the $CD.SDGASAMP library.

The PLEXTYPC is an IDCAMS REPRO that specifies NOREPLACE. If any duplicate recordsexist, only the first one is saved.

If unique entries do not exist, use one of the existing TYPE files.

Chapter 4. Administration Guide 291

Local Node Naming ConsiderationsThe network map contains the local node name for the IBM Connect:Direct/Plex environment. The nodename used in the network map varies according to the type of configuration:

• Installing a new IBM Connect:Direct/Plex environment

If you are installing a new IBM Connect:Direct/Plex environment, you must create a new local nodename. You must provide the new node name, along with the APPLID and/or TCP/IP address andport number to all IBM Connect:Direct partner nodes. The partner Nodes must provide you the sameinformation for use in your local network map.

• Replacing an existing IBM Connect:Direct system with a IBM Connect:Direct/Plex environment

If you are replacing an existing IBM Connect:Direct system with a IBM Connect:Direct/Plexenvironment, use the existing system node name as the IBM Connect:Direct/Plex local node name, youmust provide new APPLIDs for the IBM Connect:Direct Manager. One IBM Connect:Direct Server usesthe existing APPLIDs in its local initialization parameters. Any additional servers require new APPLIDs.

• Replacing multiple existing IBM Connect:Direct systems with a IBM Connect:Direct/Plex environment

If you are replacing multiple IBM Connect:Direct systems with a IBM Connect:Direct/Plex environment,create a new local node name for the IBM Connect:Direct/Plex. Use the existing node names in theCDPLEX.SERVER.NODE initialization parameter of the IBM Connect:Direct Server. All adjacent nodeentries in the network map must include USE.SERVER.NODE=YES. You must provide new APPLIDs forthe IBM Connect:Direct Manager. Each IBM Connect:Direct Server uses the existing APPLID from itscorresponding IBM Connect:Direct Stand-alone Server image in its local initialization parameters.

Refer to the setup procedure in “ Converting Two Existing Stand-Alone Server Systems to a PlexEnvironment” on page 296 for more details.

Strategies for Communicating with Non-Plex ServersA IBM Connect:Direct/Plex environment can perform workload balancing among the IBM Connect:DirectServers. However, if the IBM Connect:Direct/Plex environment communicates with an external non-IBMConnect:Direct/Plex system, the other IBM Connect:Direct system may have problems with Processesfrom the same IBM Connect:Direct adjacent node, but with a different VTAM APPLID or TCP/IP addressthan specified in their network map.

IBM Connect:Direct/Plex offers three ways of avoiding this problem.

Using Alternate Communication Paths to Define the IBM Connect:Direct/PlexThe advantages to this approach are you only have to define one entity, the IBM Connect:Direct/Plex, andthen copy that same definition to the network maps of the non-Plex Servers and you can still use theNETMAP-checking feature.

To define a IBM Connect:Direct/Plex that has servers running on several hosts, you can use theALT.COMM parameter in the network map of each non-Plex Server that will communicate with the IBMConnect:Direct/Plex.

1. Specify USE.SERVER.NODE=NO in the IBM Connect:Direct/Plex network map entry of each non-PlexServer so that all servers in the IBM Connect:Direct/Plex environment appear as one node.

2. Define the IBM Connect:Direct/Plex node as an adjacent node with all possible IP addresses of thehosts that the Manager can run on specified using the ALT.COMM definition.

The following is an example of the ALT.COMM parameter:

292 IBM Connect:Direct for z/OS: Documentation

ADJACENT.NODE=( - (CDMGR,1366,10.1.1.1,TCP,EXT,BOTH) - ENVIRONMENT=ZOS - PARSESS=(00000010 00000002) - ALT.COMM=(ALT.DIR=TOP - (ALT.ADDR=10.1.1.2,ALT.PORT=1366,- ALT.TYPE=TCP , ALT.USE.OUT=NO ) (ALT.ADDR=10.1.1.3,ALT.PORT=1366,- ALT.TYPE=TCP , ALT.USE.OUT=NO ) (ALT.ADDR=10.1.1.4,ALT.PORT=1366,- ALT.TYPE=TCP , ALT.USE.OUT=NO )) -

3. Copy this ALT.COMM definition and put it in the network map of each non-Plex Server that willcommunicate with the IBM Connect:Direct/Plex.

Forcing All Processes to One IBM Connect:Direct ServerThis approach does not take advantage of IBM Connect:Direct/Plex workload balancing. To direct allProcesses between the IBM Connect:Direct/Plex environment and the external IBM Connect:Direct to oneIBM Connect:Direct Server, follow this procedure.

1. Specify a default PLEXCLASS parameter in the IBM Connect:Direct/Plex network map adjacent nodeentry for the external IBM Connect:Direct system.

2. Specify that PLEXCLASS parameter in only one local initialization parameter of the IBM Connect:DirectServer.

3. Specify the VTAM APPLID or TCP/IP address of the specific IBM Connect:Direct Server all Processesare being forced to in the network map of the external non-Plex IBM Connect:Direct system.

Define a Unique Node Name for Each IBM Connect:Direct ServerBy defining a node name for each IBM Connect:Direct Server, the IBM Connect:Direct/Plex environmentcan initiate Processes to the external IBM Connect:Direct system through any available IBMConnect:Direct/Plex server. For each IBM Connect:Direct server, you must define a USE.SERVER.NODEnetwork map parameter and a CDPLEX.SERVER.NODE initialization parameter.

To avoid making your IBM Connect:Direct/Plex configuration more complex than necessary, use theUSE.SERVER.NODE and CDPLEX.SERVER.NODE parameters only if your system meets all of the followingconditions:

• The external IBM Connect:Direct system must connect to two or more IBM Connect:Direct Servers inthe IBM Connect:Direct/Plex environment.

• The external IBM Connect:Direct system uses network map checking.• The external IBM Connect:Direct system has non-Plex servers, which cannot communicate directly with

the IBM Connect:Direct Manager.

The disadvantages of this approach are you must manually direct Processes initiated by the external IBMConnect:Direct system to each IBM Connect:Direct Server and you may need to create additional networkmap entries for remote systems.

Converting an Existing Stand-Alone Server to a Plex EnvironmentYou can convert an existing production IBM Connect:Direct Stand-alone Server into a IBM Connect:Direct/Plex environment with two servers. This configuration takes advantage of the IBM Connect:Direct/Plexsingle image and workload balancing capability for Processes initiated by this IBM Connect:Direct/Plexenvironment. This configuration also supports external IBM Connect:Direct systems without requiring anychanges to the external systems.

The following illustration shows how the network map and initialization parameter values from theexisting stand-alone IBM Connect:Direct system map to the new IBM Connect:Direct/Plex environmentfor this configuration.

Chapter 4. Administration Guide 293

The setup example assumes the following:

• You are currently running a production IBM Connect:Direct Stand-alone Server.• The global and local initialization parameter files for the IBM Connect:Direct/Plex environment are

located in $CD.PLEX.INITPARM (a PDS that you set up for this purpose). The JCL to bring up the IBMConnect:Direct/Plex environment is located in $CD.PLEX.JCL (a PDS that you set up for this purpose).

You can either allocate these data sets or use existing data sets in their place.• The IBM Connect:Direct/Plex environment identifies itself to external systems with the same node

name as the production IBM Connect:Direct Stand-alone Server.

Converting an Existing Production Server to a Plex EnvironmentTo convert an existing production IBM Connect:Direct Stand-alone Server into a IBM Connect:Direct/Plexenvironment:

1. Copy the existing INITPARMs member into $CD.PLEX.INITPARM as member CDPLX.2. Copy the existing IBM Connect:Direct Stand-alone Server startup JCL into $CD.PLEX.JCL as member

CDMGR.3. Change the network map source to specify new APPLIDs for the LOCAL.NODE and the PNODE/SNODE

ADJACENT.NODE.

The existing APPLIDs are used for the IBM Connect:Direct SERVER1, which means that you do notneed to change the connections to external IBM Connect:Direct systems.

4. Add the following initialization parameters to the CDPLX member in $CD.PLEX.INITPARM. Thismember becomes the IBM Connect:Direct/Plex global initialization parameters file.

CDPLEX=YESCDPLEX.MAXSERVER = number of servers | 4XCF.NAME=8-char-name

The CDPLEX=YES parameter indicates a IBM Connect:Direct/Plex environment. It also directs theDTF to read its local initialization parameters from the file specified in the //CDPLEX DD statement inthe startup JCL.

The CDPLEX.MAXSERVER parameter specifies the maximum number of servers the Connect:Direct/Plex Manager will manage. For more information, see Storage Requirements in a IBM Connect:DirectEnvironment in the IBM Connect:Direct for z/OS Configuration Guide.

The XCF.NAME parameter specifies a unique name used by the z/OS Cross Systems CommunicationFacility (XCF) to assist communications among IBM Connect:Direct/Plex members. This nameindicates that the IBM Connect:Direct Manager and IBM Connect:Direct Servers are part of the sameXCF group.

5. You can add the following optional parameters to the CDPLX member in $CD.PLEX.INITPARM.

• “CDPLEX.TIMER = 5 | number of minutes” on page 460 specifies the time-out value for XCFcommunications in minutes.

294 IBM Connect:Direct for z/OS: Documentation

• “CDPLEX.WLM.GOAL = (NO | YES, exitname)” on page 460 specifies whether IBM WorkloadManager (WLM) Goal Mode queries are made. This parameter is optional.

6. Create the local initialization parameter files for each IBM Connect:Direct/Plex member:a) Copy the DGAITMGR, DGAISRV1, and DGAISRV2 sample local initialization parameters members

from the IBM Connect:Direct $CD.SDGAPARM library into $CD.PLEX.INITPARM as membersMANAGER, SERVER1, and SERVER2.

b) Change the TCP.LISTEN parameter (following in bold) to specify the TCP/IP stack address that isused by the IBM Connect:Direct Manager.

You do not need to change any other parameters in the MANAGER member.

CDPLEX.MANAGER=YES TCP.LISTEN=(nnn.nnn.nnn.nnn,port) CDPLEX.SERVER.JOBDSN=$CD.PLEX.JCL CDPLEX.SERVER.JOBMEM=((CDSRV1,SERVER1), - (CDSRV2,SERVER2))

c) Change the CDPLEX.VTAM parameter in the SERVER1 member as follows:

• Replace the applid11 value with the VTAM APPLID that is defined in the existing network mapfor SNA copy Processes.

• Replace the applid12 value with the VTAM APPLID that is defined in the existing network mapfor the PNODE-SNODE APPLID.

These APPLIDs must be unique across the IBM Connect:Direct/Plex environment and cannot bethe same as specified in the new network map.

CDPLEX.MANAGER=NO CDPLEX.SERVER=SERVER1 CDPLEX.VTAM=(applid11,applid12) CDPLEX.PLEXCLASSES=(TAPE,*) TCP.LISTEN=(nnn.nnn.nnn.nnn,port)

d) The TCP.LISTEN initialization parameters specifies the TCP listen address and port numbercombinations. Use a different listen port number than the one used in the existing initializationparameters file.

Note: The CDPLEX.PLEXCLASSES parameter in SERVER1 specifies a ‘TAPE' PLEXCLASS. ForProcesses that require tape drives, specify the ‘TAPE' PLEXCLASS in their Process definitions.These Processes run on SERVER1. (See Building, Modifying, and Submitting Processes in the IBMConnect:Direct for z/OS User Guide for more information on using PLEXCLASS in a Process.)

e) Change the CDPLEX.VTAM parameter in the SERVER2 member as follows:

• Replace the applid21 value with a new VTAM APPLID you have defined for SNA copy Processes.• Replace the applid22 value with a new VTAM APPLID you have defined for the PNODE-SNODE

APPLID.

These APPLIDs must be unique across the IBM Connect:Direct/Plex environment and cannot bethe same as specified in the new network map or used for SERVER1.

CDPLEX.MANAGER=NO CDPLEX.SERVER=SERVER1 CDPLEX.VTAM=(applid21,applid22) CDPLEX.PLEXCLASSES=(*) TCP.LISTEN=(nnn.nnn.nnn.nnn,port)

f) The TCP.LISTEN initialization parameters specify the TCP listen address and port numbercombinations. Use a different listen port number than the one used in the existing initializationparameters file.

7. Add the CDPLEX DD statement in the following example to the CDMGR member in $CD.PLEX.JCL (thisJCL is the startup JCL copied earlier).

Chapter 4. Administration Guide 295

//DTF EXEC DGADINIT,// PARM='$CD.PLEX.INITPARM(CDPLX)'//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(MANAGER)

8. Create the CDSRV1 member and copy CDMGR into it.9. Make the following changes to the CDSRV1 member:

a) Change the job name so that this job can run simultaneously with the CDMGR JCL.b) Change the member name in the CDPLEX DD statement to SERVER1, as follows. This change

directs the CDSRV1 JCL to its local initialization parameters file.

//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(SERVER1)

10. Create the CDSRV2 member and copy CDSRV1 into it.11. Make the following changes to the CDSRV2 member:

a) Change the job name so that this job can run simultaneously with the CDMGR JCL and CDSRV1JCL.

b) Change the member name in the CDPLEX DD statement to SERVER2, as follows. This changedirects the CDSRV2 JCL to its local initialization parameters file.

//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(SERVER2)

Note: You can route jobs to a different z/OS image by specifying the local node name of the othersystem name in an XEQ statement in the IBM Connect:Direct Manager or Server JCL as follows:

/*XEQ njenode[JES2]//*ROUTE XEQ njenode [JES3]

This example routes the job to the z/OS image identified by the local node name NJENODE.12. Submit the CDMGR JCL to bring up IBM Connect:Direct/Plex.

After the IBM Connect:Direct Manager initializes, it submits the CDSRV1 JCL and CDSRV2 JCL to bringup the two IBM Connect:Direct Servers.

13. After the IBM Connect:Direct Manager initializes, use the IUI to signon to the IBM Connect:DirectManager.

You can then submit Processes and perform other functions through the IUI.

Converting Two Existing Stand-Alone Server Systems to a Plex EnvironmentThis section illustrates how to convert existing production IBM Connect:Direct Stand-alone Serversystems into a IBM Connect:Direct/Plex environment with two servers. This configuration takes advantageof the IBM Connect:Direct/Plex single image and workload balancing capability for Processes initiated bythis IBM Connect:Direct/Plex environment. This configuration also supports external IBM Connect:Directsystems without requiring any changes to the external systems.

In the following illustration, two separate IBM Connect:Direct Stand-alone Server systems run in a z/OSsysplex environment.

296 IBM Connect:Direct for z/OS: Documentation

The procedure in this section combines the separate systems into the single IBM Connect:Direct/Plexenvironment as follows.

In this configuration, the original CD.PROD1 system becomes the IBM Connect:Direct Manager andIBM Connect:Direct Server1. The CD.PROD2 system becomes the IBM Connect:Direct Server2. The IBMConnect:Direct/Plex environment is given the node name CD.PROD1. No changes are made to the remotenodes' network maps. The remote nodes communicate with the IBM Connect:Direct/Plex environment asif they communicated with a single IBM Connect:Direct image.

To create this configuration you must:

• Define new APPLIDs for the IBM Connect:Direct/Plex environment• Use the APPLIDs from the existing CD.PROD1 system in the Server1 local initialization parameters• Use the APPLIDs from the existing CD.PROD2 system in the Server2 local initialization parameters

The following illustration shows how the network map and initialization parameter values from theexisting IBM Connect:Direct systems map to the IBM Connect:Direct/Plex environment.

Chapter 4. Administration Guide 297

This example assumes the following:

• You are running two production IBM Connect:Direct Stand-alone Server systems: CD.PROD1 andCD.PROD2.

• The global and local initialization parameter files are located in $CD.PLEX.INITPARM. The JCL thatbrings up the IBM Connect:Direct/Plex environment is located in $CD.PLEX.JCL. You can either allocatethese data sets or use existing data sets in their place.

• The IBM Connect:Direct/Plex environment identifies itself to external systems with a new node name.Each IBM Connect:Direct Server identifies itself to external systems with the same node name it used asa IBM Connect:Direct Stand-alone Server.

Converting a Standalone Server System into One IBM Connect:Direct/PlexSetupTo convert two existing IBM Connect:Direct Stand-alone Server systems into one IBM Connect:Direct/Plexenvironment:

1. Copy the the INITPARMs member for CD.PROD1 into $CD.PLEX.INITPARM as member CDPLX.2. Resolve any differences (other than data set names) between the new INITPARMS member and the

CD.PROD2 INITPARMS member.3. Copy the CD.PROD1 IBM Connect:Direct/Plex startup JCL into $CD.PLEX.JCL as member CDMGR.4. Resolve any differences, such as trace DDs, with the CD.PROD2 startup JCL.5. Merge the existing AUTH and TYPE files from both systems as described in IBM Connect:Direct/Plex

System File Considerations, using the same files names used for CD.PROD1.6. Create new TCQ/TCX, CKPT, and statistics file pairs as discussed in CKPT file, using the same file

names used for CD.PROD1.7. Merge the source from the individual network map files as described in NETMAP file.8. Change the new network map source (created from the merged network map files) as follows:

a) Specify new APPLIDs and a new LOCAL.NODE name for the LOCAL.NODE and the PNODE/SNODEADJACENT.NODE.

Because the existing APPLIDs are used for SERVER1, you do not need to change the external IBMConnect:Direct connections.

b) Specify USE.SERVER.NODE=YES on all ADJACENT.NODE records.c) Use the same local node name that is used for CD.PROD1.

298 IBM Connect:Direct for z/OS: Documentation

d) Load the network map.9. Add the following initialization parameters to the CDPLX member in $CD.PLEX.INITPARM. This

member becomes the IBM Connect:Direct/Plex global initialization parameters file.

CDPLEX=YESCDPLEX.MAXSERVER = number of servers | 4XCF.NAME=8-char-name

The CDPLEX=YES parameter indicates a IBM Connect:Direct/Plex environment. It also directs theDTF to read its local initialization parameters from the file specified in the //CDPLEX DD statement inthe startup JCL.

The CDPLEX.MAXSERVER parameter specifies the maximum number of servers the Connect:Direct/Plex Manager will manage. For more information, see Storage Requirements in a IBM Connect:DirectEnvironment in the IBM Connect:Direct for z/OS Configuration Guide.

The XCF.NAME parameter specifies a unique name used by the z/OS XCF to assist communicationsamong IBM Connect:Direct/Plex members. This name indicates that the IBM Connect:Direct Managerand IBM Connect:Direct Servers are part of the same XCF group.

10. You can add the following optional parameters to the CDPLX member in $CD.PLEX.INITPARM:

• “CDPLEX.TIMER = 5 | number of minutes” on page 460 specifies the time-out value for XCFcommunications in minutes.

• “CDPLEX.WLM.GOAL = (NO | YES, exitname)” on page 460 specifies whether IBM WorkloadManager (WLM) Goal Mode queries are made. This parameter is optional.

11. Create the local initialization parameters files for each IBM Connect:Direct/Plex member:a) Copy the DGAITMGR, DGAISRV1, and DGAISRV2 sample local initialization parameters members

from the IBM Connect:Direct $CD.SDGAPARM library into $CD.PLEX.SDGAPARM as membersMANAGER, SERVER1, and SERVER2.

b) Change the TCP.LISTEN parameter of the MANAGER member to specify the TCP/IP stack addressused by the IBM Connect:Direct/Plex Manager.

You need not change any other parameters need in the MANAGER member.

CDPLEX.MANAGER=YESTCP.LISTEN=(nnn.nnn.nnn.nnn,port)CDPLEX.SERVER.JOBDSN=$CD.PLEX.JCLCDPLEX.SERVER.JOBMEM=((CDSRV1,SERVER1), - (CDSRV2,SERVER2))

c) Change the CDPLEX.VTAM parameter in the SERVER1 member as follows:

• Replace the applid11 value with the VTAM APPLID from CD.PROD1 for SNA copy Processes.• Replace the applid12 value with the VTAM APPLID from CD.PROD1 for the PNODE-SNODE

APPLID.

These APPLIDs must be unique across the IBM Connect:Direct/Plex and cannot be the same asthose specified in the new network map.

CDPLEX.MANAGER=NOCDPLEX.SERVER=SERVER1CDPLEX.VTAM=(applid11,applid12,applid13)CDPLEX.PLEXCLASSES=(TAPE,*)TCP.LISTEN=(nnn.nnn.nnn.nnn,port)

d) Change the TCP.LISTEN parameter in the SERVER1 member to specify the TCP/IP stack addressused by this IBM Connect:Direct/Plex server.

e) Change the TCP.LISTEN parameter in SERVER1 member to the TCP.LISTEN value from CD.PROD1.

Chapter 4. Administration Guide 299

Note: The CDPLEX.PLEXCLASSES parameter in SERVER1 specifies a ‘TAPE' PLEXCLASS. ForProcesses that require tape drives, specify the ‘TAPE' PLEXCLASS in their Process definitions.These Processes run on SERVER1. (See Building, Modifying, and Submitting Processes in IBMConnect:Direct for z/OS User Guide for more information on using PLEXCLASS in a Process.)

f) Add the following statement to the SERVER1 member.

CDPLEX.SERVER.NODE=CD.PROD1

g) Change the CDPLEX.VTAM parameter in the SERVER2 member as follows:

• Replace the applid21 value with the VTAM APPLID from CD.PROD2 for SNA copy Processes.• Replace the applid22 value with the VTAM APPLID from CD.PROD2 for the PNODE-SNODE

APPLID.

These APPLIDs must be unique across the IBM Connect:Direct/Plex and cannot be the same asthose specified in the new network map or used for SERVER1.

CDPLEX.MANAGER=NOCDPLEX.SERVER=SERVER2CDPLEX.VTAM=(applid21,applid22)CDPLEX.PLEXCLASSES=(*)TCP.LISTEN=(nnn.nnn.nnn.nnn,port)

h) Change the TCP.LISTEN parameter in the SERVER2 member to specify the TCP/IP stack addressused by this IBM Connect:Direct/Plex server.

i) Change the TCP.LISTEN parameter in the SERVER2 member to the TCP.LISTEN value fromCD.PROD2.

j) Add the following statement to the SERVER2 member.

CDPLEX.SERVER.NODE=CD.PROD2

12. Add the CDPLEX DD statement in the following example to the CDMGR member in $CD.PLEX.JCL.(This JCL is the startup JCL copied earlier.)

//DTF EXEC DGADINIT,// PARM='$CD.PLEX.INITPARM(CDPLX)'//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(MANAGER)

13. Create the CDSRV1 member and copy CDMGR into it.14. Make the following changes to the CDSRV1 member:

a) Change the job name so that this job can run simultaneously with the CDMGR JCL.b) Change the member name in the CDPLEX DD statement to SERVER1 as follows. This directs the

CDSRV1 JCL to its local initialization parameters file.

//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(SERVER1)

15. Create the CDSRV2 member and copy CDSRV1 into it.16. Make the following changes to the CDSRV2 member:

a) Change the job name so that this job can run simultaneously with the CDMGR JCL and CDSRV1JCL.

b) Change the member name in the CDPLEX DD statement to SERVER2 as follows. This directs theCDSRV2 JCL to its local initialization parameters file.

//CDPLEX DD DISP=SHR,DSN=$CD.PLEX.INITPARM(SERVER2)

300 IBM Connect:Direct for z/OS: Documentation

Note: You can route jobs to a different z/OS image by specifying the local node name of the othersystem name in an XEQ statement in the IBM Connect:Direct Manager or Server JCL as follows:

/*XEQ njenode[JES2]//*ROUTE XEQ njenode [JES3]

This example routes the job to the z/OS image identified by the local node name NJENODE.17. Submit the CDMGR JCL to bring up the IBM Connect:Direct/Plex.

After the IBM Connect:Direct Manager initializes, it submits the CDSRV1 JCL and CDSRV2 JCL to bringup the two IBM Connect:Direct Servers.

18. After the IBM Connect:Direct Manager initializes, use the IUI to signon to the IBM Connect:DirectManager.

You can then submit Processes and perform other functions through the IUI.

Additional IBM Connect:Direct/Plex Configuration ExamplesThis topic illustrates additional IBM Connect:Direct/Plex configuration examples. While your siteconfiguration can vary due to the number of external nodes, use this topic as a guide in determiningthe best way to configure a IBM Connect:Direct/Plex.

Note: The examples in this section are high-level descriptions for use as a configuration model.They do not describe all configuration changes to set up a IBM Connect:Direct/Plex. See A New IBMConnect:Direct/Plex Environment for detailed information.

Configuration Examples Using One Connect:Direct for z/OS SystemThis section assumes the following IBM Connect:Direct environment exists.

In this environment, two Connect:Direct for UNIX nodes (UNIX.CD and UNIX.CD2) communicate witha Connect:Direct for z/OS system (ZOS.CD). The ZOS.CD system uses the APPLID “AP1.” The UNIX.CDsystem uses the APPLID “UN1”, while the UNIX.CD2 system uses the APPLID “UN2.” The network mapentries define the adjacent nodes.

Chapter 4. Administration Guide 301

Although this example uses Connect:Direct for UNIX as the external nodes, the relationship is the samewhen any IBM Connect:Direct platform is an external node.

Scenario 1 – External Nodes Communicate with One IBM Connect:Direct ServerThis section describes the simplest IBM Connect:Direct/Plex configuration – both external nodescommunicate with the same IBM Connect:Direct Server.

In the following illustration, the ZOS.CD system is configured as a IBM Connect:Direct/Plex consisting of aIBM Connect:Direct Manager and two IBM Connect:Direct Servers. Both external Connect:Direct for UNIXsystems communicate only with SERVER1.

To accomplish this setup, assign the APPLID from the original IBM Connect:Direct system (AP1) toSERVER1 through the local initialization parameters of SERVER1 (callout 1 in the preceding illustration).Note that you must create new APPLIDs for the SERVER2 (AP2) and the IBM Connect:Direct Manager(AP3).

Then, specify SERVER1 as the default PLEXCLASS in the IBM Connect:Direct/Plex network map (callout2). This routes all work and communication among the nodes through SERVER1.

The advantage of this approach is that the Connect:Direct for UNIX nodes do not need to change anyinitialization parameter or network map definitions. They do not have any knowledge of the change to thez/OS node.

The disadvantage of this approach is that you cannot use IBM Connect:Direct/Plex workload balancingto its full potential. You cannot perform workload balancing on Processes received from or sent to theexternal nodes. However, work originating and done entirely on the Connect:Direct for z/OS system canuse IBM Connect:Direct/Plex workload balancing.

Scenario 2 – External Nodes Communicate with Individual IBM Connect:Direct ServersIn this configuration, each external IBM Connect:Direct node communicates with a specific IBMConnect:Direct Server. This configuration makes better use of the IBM Connect:Direct/Plex environmentby spreading the work from the external nodes between the IBM Connect:Direct Servers.

302 IBM Connect:Direct for z/OS: Documentation

To accomplish this configuration, change the UNIX.CD2 network map to point to the APPLID for SERVER2(callout 1).

Then, make the following changes to the IBM Connect:Direct/Plex network map (callout 2):

• Route all Processes from UNIX.CD to SERVER1 by defining SERVER1 as the default PLEXCLASS in theadjacent node definition for UNIX.CD.

• Route all Processes from UNIX.CD2 to SERVER2 by defining SERVER2 as the default PLEXCLASS in theadjacent node definition for UNIX.CD2.

The advantage of this approach is that work from each UNIX node runs on a different IBM Connect:DirectServer, so work from one node does not interfere with work from the other. You do not need to changeProcesses submitted from either node to run on the specified servers (unless the Process itself specifies aTCP/IP address).

The disadvantage of this approach is that you still cannot use the IBM Connect:Direct/Plex workloadbalancing to its full potential. You cannot perform workload balancing on Processes received from or sentto the external nodes. Work originating and done entirely on the Connect:Direct for z/OS system can useIBM Connect:Direct/Plex workload balancing.

Chapter 4. Administration Guide 303

Scenario 3 – External Nodes Communicate with Both IBM Connect:Direct ServersThis configuration uses the IBM Connect:Direct/Plex workload balancing capability. In this environment,both external nodes can communicate with either IBM Connect:Direct Server.

In this configuration, the network map of each Connect:Direct for UNIX node is changed to point to bothIBM Connect:Direct Servers. However, because the IBM Connect:Direct/Plex normally is displayed as asingle node to external systems, you must first create a unique node name for SERVER2. To create aunique node name, specify:

• CDPLEX.SERVER.NODE = ZOS.CD2 in the SERVER2 local initialization parameters (callout 1)

You do not need to specify the CDPLEX.SERVER.NODE initialization parameter for SERVER1 because ituses the local node (ZOS.CD).

• USE.SERVER.NODE=YES in the IBM Connect:Direct/Plex network map adjacent node definitions (callout2)

The ZOS.CD2 node name is then added to the external nodes' network maps (callouts 3 and 4).

The advantage of this configuration is that you can perform workload balancing on outgoing Processesfrom the IBM Connect:Direct/Plex. However, you cannot perform automatic workload balancing onProcesses received from the external nodes; you must manually balance them by changing the SNODE.

304 IBM Connect:Direct for z/OS: Documentation

Configuration Example Using Two Connect:Direct for z/OS SystemsThis configuration describes a more complex IBM Connect:Direct/Plex configuration. It assumes that thefollowing IBM Connect:Direct environment exists.

In this environment, two Connect:Direct for UNIX nodes (UNIX.CD and UNIX.CD2) communicate with twodifferent Connect:Direct for z/OS systems (ZOS.CD and ZOS.CD2).

To change this setup to a IBM Connect:Direct/Plex, the ZOS.CD and ZOS.CD2 systems are merged into asingle IBM Connect:Direct/Plex. ZOS.CD is designated as the IBM Connect:Direct Manager and SERVER1,while ZOS.CD2 is designated as the IBM Connect:Direct Server SERVER2. (See Converting Two ExistingStand-Alone Server Systems to a Plex Environment for more information.)

Chapter 4. Administration Guide 305

The initialization parameter CDPLEX.SERVER.NODE=ZOS.CD2 is added to the SERVER2 local initializationparameter (callout 1). USE.SERVER.NODE=YES is added to the IBM Connect:Direct/Plex network mapadjacent node definitions (callout 2).

The advantages of this approach are:

• Changes to the z/OS nodes have no affect on the Connect:Direct for UNIX nodes. Therefore, no changesare required to the Connect:Direct for UNIX nodes.

• You can perform workload balancing on Processes sent from ZOS.CD to the Connect:Direct for UNIXnodes.

• The IBM Connect:Direct/Plex provides a single administrative and operating environment.

The disadvantage of this approach is that you must manually balance Processes coming from theConnect:Direct for UNIX nodes.

Connect:Direct Workload RecoveryFor v6.0 and before when a Connect:Direct/Plex Manager terminates abnormally, or shuts down, theServers also terminate and are no longer available to execute processes.

With release 6.1, in a situation when Connect:Direct/Plex Manager terminates abnormally, or shuts down:

• Connect:Direct/Servers are still available to execute any running processes• Processes continue to run uninterrupted• Statistics could be queried on other Node• Process execution status could be queried on other Node• You will not able to login to Connect:Direct/Plex Environment. Login into ESF mode is however possible.• You will still be able to submit processes and execute them from other Nodes to Connect:Direct/Servers

(as SNODE) directly.

Connect:Direct/Servers can be added as Alternate Communication Address (ALT.COMM) inConnect:Direct/Manager entry of PNODE’s Netmap. Example Netmap entry with Connect:Direct/Plexsupporting two server. Here, one is added as ALT.ADDR and other as ALT.NODEDEF in Connect:Direct/Plex Manager Netmap entry in PNODE.

$$DELETE ADJACENT.NODE=(( CDZSRV1)) $$INSERT ADJACENT.NODE=(( CDZSRV1,30003,10.1.1.21,TCP) - /* Server 1 node entry */ PARSESS=(2 1) - SESS.SNODE.MAX=1 - TCPAPI=(30004,10.1.1.21) - APPLIDS=(M1CDI7P6 M1CDI7P7 M1CDI7P8) - )$$DELETE ADJACENT.NODE=(( CDZMGR))$$INSERT ADJACENT.NODE=(( CDZMGR,30001,10.1.1.21,TCP) - /* Manager node entry */ PARSESS=(2 1) - SESS.SNODE.MAX=1 - TCPAPI=(30002,10.1.1.21) - APPLIDS=(M1CDI7P6 M1CDI7P7 M1CDI7P8) - ALT.COMM=( - (ALT.NODEDEF=CDZSRV1) - /* Server 1 as NodeDef */ (ALT.ADDR=10.1.1.21 ALT.PORT=30005 ALT.TYPE=TCP) - /* Server 2 as Address */ ))

When a Connect:Direct/Plex Manager restarts:

– Manager syncs-up with all supporting Servers. Statistics Data (STAT), Process Data (TCQ) andCheckpoint Data (CKPT) will be re-synced.

– Users can log into Connect:Direct/Plex Manager and query the in-execution or completed processesstatus that were still running when Manager had shut down

306 IBM Connect:Direct for z/OS: Documentation

- All active process executions will be continued and can be queried on Manager- Statistics for all the completed processes can be queried on Manager

– Processes that started on Servers (as SNODE) after the Manager terminates or shuts downabnormally, will continue to be executed and their status can be queried on Manager.

– Statistics for processes that started on Servers (as SNODE) after Manager terminates or shuts downabnormally, and completed before the Manager restarted, can be queried on Manager.

Note: It is recommended to use Extended Recovery setup with Connect:Direct/Plex Manager so thatStandby Manager takes over immediately as soon as the Manager shuts down. This is required toavoid load on Server’s physical memory as syncing data might accumulate over a period.

You can still submit processes and execute them from other Nodes to Connect:Direct/Servers (asSNODE) directly.

Connect:Direct/Plex Manager should be restarted with TCQ initialization parameter set to WARM elseManager/Servers could abend as TCQ will be synced with Servers during Manager restart.

Configuring Extended RecoveryIBM Connect:Direct uses the IBM Extended Recovery Facility (XRF) to quickly recover and resumeprocessing after an abnormal termination. This recovery is accomplished by using a standby IBMConnect:Direct system that waits to resume processing if the active IBM Connect:Direct system fails.

Both the IBM Connect:Direct/Stand-alone Server and IBM Connect:Direct/Plex configurations supportextended recovery. This chapter describes how to set up extended recovery in either environment.

Setting Up Extended Recovery for a IBM Connect:Direct/Stand-Alone ServerTo configure a IBM Connect:Direct/Stand-alone Server to use extended recovery, follow this procedure.

1. Specify the XCF.NAME in the initialization parameters file. The XCF.NAME is a unique 8-character stringthat identifies a IBM Connect:Direct/Stand-alone Server using extended recovery.

The following example shows a IBM Connect:Direct/Stand-alone Server assigned the XCF.NAME ofMNPLS.

XCF.NAME=MNPLS

Note: XCF group names cannot begin with the letters A through J or with the letters SYS because theseare reserved by IBM.

2. Add the following parameter to the initialization parameters file.

EXTENDED.RECOVERY=YES

3. Add the XRFJOB DD statement to the IBM Connect:Direct startup JCL as follows.

//XRFJOB DD DISP=SHR,DSN=$CD.SDGAJCL(CDJOBX)

$CD.SDGAJCL is the PDS where the active (current) IBM Connect:Direct startup JCL is located. TheCDJOBX member is the standby IBM Connect:Direct startup JCL or startup command to run as astarted task, which will be created later.

4. To run as a started task, use one of the following, or skip to step 5 if you are not running as a startedtask.

• To run the IBM Connect:Direct standby image as a started task on the same z/OS image as the IBMConnect:Direct active image, use the following as the first statement in the JCL.

Chapter 4. Administration Guide 307

START=membername,parms

In this example, START= indicates to issue a START command. When the START command is issued,the equal sign (=) is replaced with a blank, and the entire statement is passed to z/OS as a command.

For example, if START=HOSTJCL,X is the first statement, then START HOSTJCL,X is issued to z/OS.• To run the IBM Connect:Direct standby image as a started task on an z/OS image in the sysplex that

is not the IBM Connect:Direct active image, use the following as the first statement in the JCL.

/*$VS,‘command'

Where command is the command you want the Job Entry Subsystem (in this case, a JES2environment) to send to z/OS. Because the statement does not begin with START=, IBMConnect:Direct submits the statement to JES. JES identifies the /*$VS and issues the commandto z/OS rather than placing it in the job queue.

For example, if /*$VS,‘RO CSGB,S CDICOMB' is submitted in the JCL, the

RO CSGB,S CDICOMB command is issued rather than placed in the job queue.5. Copy the IBM Connect:Direct startup JCL to the CDJOBX member if you are submitting the JCL.6. Change the job name in CDJOBX so that it runs simultaneously with the active IBM Connect:Direct

image. (Both the active IBM Connect:Direct image and the standby IBM Connect:Direct image run atthe same time.)

7. Change the XRFJOB DD statement in the standby IBM Connect:Direct startup JCL to reference the IBMConnect:Direct startup JCL or command to run as a started task, as in the following example (whereCDJOB is replaced by the member name that actually has your IBM Connect:Direct JCL).

//XRFJOB DD DISP=SHR,DSN=$CD.SDGACNTL(CDJOB)

8. Submit the CDJOB JCL to bring up IBM Connect:Direct using extended recovery.

After IBM Connect:Direct initializes, the JCL specified in the startup JCL initializes the standbyIBM Connect:Direct system. The standby IBM Connect:Direct image partially initializes, then beginsmonitoring the active IBM Connect:Direct image.

If the active IBM Connect:Direct image terminates abnormally, the standby IBM Connect:Direct imageresumes initialization, becomes the active IBM Connect:Direct image, and submits the JCL in itsXRFJOB DD statement. This JCL initializes the original active IBM Connect:Direct image, which nowbecomes the standby system.

If the active IBM Connect:Direct image shuts down normally, the standby IBM Connect:Direct imagealso terminates normally.

Setting Up Extended Recovery for a IBM Connect:Direct/Plex EnvironmentThis section describes how to configure the IBM Connect:Direct/Plex environment to use extendedrecovery.

1. Add the following parameter to the initialization parameters file.

EXTENDED.RECOVERY=YES

2. Add the XRFJOB DD statement to the IBM Connect:Direct startup JCL as follows:

//XRFJOB DD DISP=SHR,DSN=$CD.PLEX.JCL(CDMGRX)

308 IBM Connect:Direct for z/OS: Documentation

$CD.PLEX.JCL is the PDS where the active (current) IBM Connect:Direct startup JCL is located. TheCDMGRX member is the standby IBM Connect:Direct startup JCL or command to run as a startedtask, which will be created later.

3. To run as a started task, use one of the following, or skip to step 4 if you are not running as a startedtask.

• To run the IBM Connect:Direct standby image as a started task on the same z/OS image as the IBMConnect:Direct active image, use the following as the first statement in the JCL.

START=membername,parms

In this example, START=indicates to issue a START command. When the START command is issued,the equal sign (=) is replaced with a blank, and the entire statement is passed to z/OS as acommand.

For example, if START=HOSTJCL,X is the first statement, then START HOSTJCL,X is issued toConnect:Direct for z/OS.

• To run the IBM Connect:Direct standby image as a started task on a different z/OS image in thesysplex as the IBM Connect:Direct active image, use the following as the first statement in the JCL.

/*$VS,‘command'

Where command is the command you want JES to send to z/OS (in this case, a JES2 environment).Because the statement does not begin with “START=”, IBM Connect:Direct submits the statementto JES. JES identifies the /*$VS and issues the command to z/OS rather then placing it in the jobqueue.

For example, if /*$VS,‘RO CSGB,S CDICOMB' is submitted as JCL, the

RO CSGB,S CDICOMB command is issued rather than placed in the job queue.4. Create the CDMGRX member from the member that contains your MANAGER's JCL..5. Change the job name in CDMGRX so that it runs simultaneously with other IBM Connect:Direct/Plex

members.6. Change the XRFJOB DD statement in CDMGRX to point to the CDMGR member, as in the following

example.

//XRFJOB DD DISP=SHR,DSN=$CD.PLEX.JCL(CDMGR)

7. Add the following DD statement to the CDSRV1 member (the SERVER1 startup JCL) in $CD.PLEX.JCL.

//XRFJOB DD DISP=SHR,DSN=$CD.PLEX.JCL(CDSRV1X)

8. Copy the changed CDSRV1 JCL member to CDSRV1X.9. Change the job name in CDSRV1X so that it runs simultaneously with other IBM Connect:Direct/Plex

members.10. Change the XRFJOB DD statement in CDSRV1X to point to CDSRV1, as in the following example.

//XRFJOB DD DISP=SHR,DSN=$CD.PLEX.JCL(CDSRV1)

11. Add the following DD statement to the CDSRV2 member (the SERVER2 startup JCL) in $CD.PLEX.JCL.

//XRFJOB DD DISP=SHR,DSN=$CD.PLEX.JCL(CDSRV2X)

12. Copy the changed CDSRV2 member to CDSRV2X.

Chapter 4. Administration Guide 309

13. Change the job name in CDSRV2X so it can run simultaneously with other IBM Connect:Direct/Plexmembers.

14. Change the XRFJOB DD statement in CDSRV2X to point to CDSRV2, as in the following example.

//XRFJOB DD DISP=SHR,DSN=$CD.PLEX.JCL(CDSRV2)

15. Submit the CDMGR JCL to bring up the IBM Connect:Direct image using extended recovery.

Each IBM Connect:Direct member initializes using extended recovery and submits the JCL specifiedin its XRFJOB DD statement. This JCL starts the standby IBM Connect:Direct members. Each standbyIBM Connect:Direct member partially initializes, then begins monitoring its active IBM Connect:Directmember.

If the active member terminates abnormally, or is shut down with a STOP CD CDPLEX RECOVERcommand, the standby member resumes initialization, becomes the active member, and submitsthe JCL in its XRFJOB DD statement. This JCL initializes the original active IBM Connect:Direct/Plexmember, which now becomes the standby member.

Note: If you want the standby member to run on a different z/OS image in the sysplex, you mustdefine the VTAM APPLID as dynamic in both z/OS images, and you must define TCP/IP addresses asdynamic VIPA addresses.

Configuring Process Library supportPrior to version 6.2, DTF Server could only submit process from process library dataset defined in DDDMPUBLIB specified in DTF Startup JCL.

From version 6.2 onwards, a new feature, Process Library, added on Connect:Direct Web Services allowsyou to perform List, Add, Delete, Rename and Get operations on process members within process librarydataset via Connect:Direct Web Services. To avail Process Library feature, you must specify ProcessLibrary dataset as 1st concatenation dataset of DD DMPUBLIB in DTF Startup JCL.

Note: From version 6.2 onwards, DD DMPUBLIB is mandatory on DTF Startup JCL. In case, DD DMPUBLIBnot specified then, Connect:Direct startup will fail with error message SITB100E. MVS PDS(E) dataset orOMVS USS directory can be configured as Process Library dataset

For example, to specify MVS PDS(E) dataset CD.PROCESS.LIB as Process Library, define DD DMPUBLIB inDTF Startup JCL as follows:

//DMPUBLIB DD DISP=SHR,DSN=CD.PROCESS.LIB // DD DISP=SHR,DSN=JSMITH.PROCESS.LIB

To specify OMVS USS directory ‘/u/cd/processlibrary’ as Process Library, define DD DMPUBLIB in DTFStartup JCL as follows:

//DMPUBLIB DD PATH='/u/cd/processlibrary',// FILEDATA=TEXT,// PATHOPTS=(ORDONLY),// RECFM=FB,LRECL=80,BLKSIZE=800

Operations on Process Library supportFollowing operations can be performed on Process Library via Connect:Direct Web Services UI.

• List – Lists the existing process members of Process Library. Following parameters can be specified

– offset=n – skip first n numbers of process members. For example, if offset=10, then first 10 processmembers are skipped, and list starts from 11th process member.

– limit=n – list up to n process members. For example, if limit=10, then only 10 process members arelisted.

310 IBM Connect:Direct for z/OS: Documentation

– filter – list specific members only as per filter value. Wild cards, ‘*’ (placeholder for multiplecharacters ), or ‘?’ (placeholder for single character) can be used in filter value. For example, iffilter=’ABC*’, then list all process members whose name start with ABC.

Note: Offset option value is ignored when filter option is used.• Add – Adds new process member into Process Library. Following parameters can be specified

– name – name of the new process member– overwrite – overwrite if process member already exists

• Delete – Deletes an existing process member from Process Library. Following parameters can bespecified:

– name – name of process member to be deleted• Rename – Renames an existing process member of Process Library. Following parameters can bespecified;

– name – name of process member to be renamed– newname – new Name of process member

• Get – Fetches the contents of existing process member of Process Library. Following parameters can bespecified:

– name – name of process member whose contents to be fetched.

For invocation details of above operations on Process Library via Connect:Direct Web Services, referProcess Library support.

After each operation on Process Library, a statistical record ‘PL’ is generated. This record reports thedetails of operation performed. Connect:Direct provides two permissions, Process Library Read andProcess Library Update, via authorization bit mask (ABM) to control user operations on Process Library.User with Process Library Read permission can perform List and Get operations on Process Library whileuser with Process Library Update permission can perform all operations – List, Add, Delete, Rename andGet, on Process Library. User without either of these two permissions will not be allowed to perform anyoperation on Process Library from Connect:Direct.

Note: In addition to above permissions, user must have proper authorized access via external security toProcess Library dataset to perform operations.

Configuring Integrated File Agent SupportFrom version 6.2 onwards, File Agent will be packaged with Connect:Direct. This File Agent variant willonly be able to connect with a single Connect:Direct Node. File Agent Install Anywhere.jar fileis loaded by DGAFAJAR member in $CD.SDGADATA.

Following sample JCL utilities are provided in $CD.SDGASAMP library to support File Agent:

JCL Utility Name Description

DGAFAINS This sample JCL can be used to install File Agent

DGAFAREI This sample JCL can be used to reinstall File Agent

DGAFASTA This sample JCL can be used to start File Agent execution

DGAFASTO This sample JCL can be used to stop File Agent execution

Installing File AgentFollowing these steps to install Integrated File Agent.

Chapter 4. Administration Guide 311

1. Open JCL utility DGAFAINS which resides in library $CD.SDGASAMP.2. Provide values for following input parameters:

• FADIR - Absolute Directory Path where File Agent will be installed• CDAPIADR - Connect:Direct API Listen TCP/IP Addr or Host name• CDPORT - Connect:Direct API Listen Port• CDUID - Connect:Direct User ID• CDPWD - Connect:Direct User password• FAUNAME - File Agent Unique Name• CDVER – Connect:Direct Version.

For example, for File Agent with unique name ‘CD File Agent’ to be installed on path /u/FileAgentand connected to Connect:Direct 6.2 version Node with API Listen TCP/IP address 1.1.1.1, port 2222,user-id ‘user1’ and password ‘xxxxxxx’

//** User Inputs:// SET FAJARDSN='$CD.SDGADATA(DGAFAJAR)'// SET FADIR='/u/FileAgent'// SET CDAPIADR='1.1.1.1'// SET CDPORT='2222'// SET CDUID='user1'// SET CDPWD='xxxxxxxx'// SET CDVER='6.02.00'// SET FAUNAME='CD File Agent'

Note: Ensure that the user ID used for installing File Agent is the same as user ID, which starts theConnect:Direct. Otherwise, there may be access related issues during Connect:Direct initialization.

3. Submit DGAFAINS JCL.File Agent will be installed.

Configuring File AgentOnce Integrated File Agent is installed, update the initialization parameter FILE.AGENT.PATH with FileAgent’s absolute directory path and start/restart Connect:Direct Node.

Once File Agent is installed and the Connect:Direct Node is started, File Agent can be configured viaConnect:Direct Web Services. For details, refer Connect:Direct Web Services.

Connect:Direct provides two permissions, Read File Agent & Update File Agent, via authorization bit mask(ABM), to restrict users from performing operations on the File Agent Configuration.

• Users with Read File Agent permission can request to view File Agent Configurations via Connect:DirectWeb Services.

• Users with Update File Agent permission can request to update File Agent Configuration.• Users not having either of these permissions, are not allowed to perform any operation on the File Agentconfiguration from Connect:Direct.

Note: Use Authorization Bit Mask (ABM) to enable External Stats Logging permission for theuser ID through which you will logon to Connect:Direct and submit process from Integrated FileAgent to allow File Agent to write statistics record to Connect:Direct. Initialization parameterEXTERNAL.STATS.ALLOWED should also be specified to allow external statistics record identifier ‘YF’.For example,

EXTERNAL.STATS.ALLOWED = (YF,)

Reinstalling File AgentFollowing these steps to install Integrated File Agent after maintenance is applied.

1. Open JCL utility DGAFAREI which resides in $CD.SDGASAMP.

312 IBM Connect:Direct for z/OS: Documentation

2. Provide values for the following input parameters:

• FADIR - Absolute Directory Path where File Agent is installed and will be reinstalled. This directoryshould contain the File Agent Installation that needs to be updated/repaired with the latestmaintenance fix.

• CDVER – Connect:Direct Version

For example, for File Agent located on path /u/FileAgent and connected to Connect:Direct 6.2 version

//** User Inputs:// SET FAJARDSN='$CD.SDGADATA(DGAFAJAR)'// SET FADIR='/u/FileAgent'// SET CDVER='6.02.00'

3. Submit DGAFAREI JCL. File Agent will be reinstalled.

The old File Agent Installation will be backed up at location FADIR.bkCCYYMMDDhhmmss, whereFADIR is the File Agent Directory Path, CC is century, YY is year, MM is month, DD is day of month,hh is hours, mm is minutes, and ss is seconds. So, if re-installation is not satisfactory, then the oldinstallation can be restored from the backup location.

For example, for File Agent reinstalled on location /u/FileAgent at mid-night 1st January 2021, theold File Agent will be backed up at location /u/FileAgent.bk20210101000001.

You will not have to redefine File Agent configuration again after re-installing. The DGAFAREI job willautomatically copy the configuration from old File Agent.

Note:

• Before starting the DGAFAREI job, ensure that File Agent is not running, otherwise re-installationmay fail, or File Agent may not be reinstalled properly and may be missing some files.

• Ensure that the user ID used for reinstalling File Agent is the same as user ID, which starts theConnect:Direct. Otherwise, file access related issues may occur during Connect:Direct initialization.

Starting and stopping File Agent

Starting File AgentFollow these steps to start file agent:

1. Open JCL utility DGAFASTA which resides in $CD.SDGASAMP.2. Provide values for the following input parameter:

• FADIR - Absolute Directory Path where File Agent is installed.

For example, for File Agent located on path /u/FileAgent :

//** User Inputs:// SET FADIR='/u/FileAgent'

3. Submit DGAFASTA JCL. File Agent execution will start.

Stopping File AgentFollow these steps to stop file agent:

1. Open JCL utility DGAFASTO which resides in $CD.SDGASAMP.2. Provide values for the following input parameter:

• FADIR - Absolute Directory Path where File Agent is installed.

Chapter 4. Administration Guide 313

For example, for File Agent located on path /u/FileAgent :

//** User Inputs:// SET FADIR='/u/FileAgent'

3. Submit DGAFASTO JCL. File Agent execution will stop.

Configuring SNMP SupportThe Simple Network Management Protocol (SNMP) defines a set of protocols that describe managementdata and the protocols for exchanging that data between systems. This management data is a set ofdefined variables called the Management Information Base (MIB).

Three primary functional entities are defined for SNMP: managers, agents, and subagents. A manager isa network management application, like Netview or HP OpenView. The agent is a server that responds torequest for management data from a network manager. Subagents provide support for particular MIBS tothe agent.

The primary function of an SNMP environment and the communication between these functional entitiesis to enable the network manager to poll a device or application to inquire about specific managementdata that the device or application is monitoring. The device or application can alert the network managerof certain conditions by sending traps to reflect the status of that condition. Traps are asynchronous,unsolicited messages sent to the network manager, when the agent and/or subagent detect certainconditions.

IBM Connect:Direct provides support for an SNMP agent to send SNMP traps to alert a network managerof certain events. An event is any IBM Connect:Direct message that is written to the console using IBMConnect:Direct members. Each event is triggered by the IBM Connect:Direct message ID and the trap text(short message text of that IBM Connect:Direct message). The IBM Connect:Direct events generated aredefined by category and type.

The IBM Connect:Direct Trap Table can hold up to 127 entries. It is built using the input from the dataset specified by the SNMP.DSN initialization parameter. One entry is generated for each message that cantrigger a SNMP trap. The predefined IBM Connect:Direct traps are triggered by 61 messages. A maximumof 66 additional user messages can be used to trigger SNMP traps. To see information about each SNMPtrap defined in the table along with its status, see INQUIRE SNMP Command Displays the SNMP TrapTable.

Define message traps using the SNMP.DSN initialization parameter and a data set that contains thevariables associated with traps.

Identifying Trap VariablesTraps are defined as alarm or status alerts which enable the network manager to display the trap in theappropriate color on the network manager console. Alarm trap variables signal events that are criticalto the operation of IBM Connect:Direct. Status trap variables signal events that are not critical to theoperation of IBM Connect:Direct, but show valuable information. The tables in the following sectionsdescribe the predefined traps, the message that triggers the trap, and a description of the trap andassociated text.

Following are the six categories for trap variables:

• Type events• Initialization events• Shutdown events• API events• Execution events• STATS events• Miscellaneous events

314 IBM Connect:Direct for z/OS: Documentation

Valid values for all events is YES to enable and NO to disable.

Type EventsUse the events in the following table to enable or disable all alarm events or all status events.

Trap Event Description Event

sendAlarmTraps NO disables all Alarm Trap Variables regardless of settings.YES enables all Alarm Trap Variables, allowing you to disableindividual Alarm Trap Variables

Alarm

sendStatusTraps NO disables all Status Trap Variables regardless of settings.YES enables all Status Trap Variables, allowing you to disableindividual Status Trap Variables

Status

Initialization EventsThe following table details alarm and status events that occur at initialization.

Trap Event Description Trap Trigger Short MessageText

Event

Initializationcomplete The initialization of this nodecompleted successfully. In a IBMConnect:Direct Plex environment,the member is named in themessage text.

SITA036I IBMConnect:Directrel-level for z/OSInitializationComplete.

Status

snaNotAvailable The SNA support is temporarilyunavailable, because the SNA=NOinitialization parameter is specified,the VTAM ACB is inactive andcould not be opened, the VTAMACB is disabled during IBMConnect:Direct processing or theIBM Connect:Direct VTAM APPLIDis already used.

SVTJ018I SNA Support isNot Available.

Status

snaNowAvailable The VTAM ACB is successfullyopened and IBM Connect:Directnow supports all SNA functions.

SVTJ019I SNA Support isNow Available.

Status

tcpNotAvailable The TCP support is temporarilyunavailable either because theTCP=NO initialization parameter isspecified, the TCP/IP connectioncannot be established, or theconnection to TCP/IP is terminated.

STCP103I TCP Support isNot Available.

Status

tcpNowAvailable The connection to TCP/IP issuccessful and all TCP functions arenow supported.

STCP104I TCP Support isNow Available.

Status

Shutdown EventsThe following table details alarm and status events that occur at shutdown.

Chapter 4. Administration Guide 315

Trap Event Description Trap Trigger Short MessageText

Event

abnormalShutdown An abnormal termination occurred. SSHA021I Abnormaltermination ofIBMConnect:Direct.

Alarm

shutdownRequest A IBM Connect:Direct Stopcommand issued.

SSHA002I IBMConnect:DirectQUIESCEshutdownbegun.

Status

SSHA003I IBMConnect:DirectRun TaskIMMEDIATEshutdownbegun.

SSHA004I IBMConnect:DirectIMMEDIATEshutdownbegun.

SSHA019I IBMConnect:DirectSTEP shutdownbegun.

normalShutdownComplete

IBM Connect:Direct normalshutdown completed successfully.

SITB001I IBMConnect:DirectTerminationComplete.

Status

API EventsThe following table details alarm and status events that occur from the API.

Trap Event Description Trap Trigger Short MessageText

Event

maxUserReached MAXUSER is reached. STAA004I Task not created,MAX IUI/APItask countreached.

Status

Execution EventsThe following table details alarm and status events that occur when a Process executes.

316 IBM Connect:Direct for z/OS: Documentation

Trap Event Description Trap Trigger Short MessageText

Event

processFailure A IBM Connect:Direct Processfailed with a return code greaterthan 0, due to abnormal sessiontermination, NETMAP check failure,or FM72 Security failure.

SVTM024I &var1EXECPROC:FMH-72¬RECEIVED;

Alarm

SVTM026I SESSION(&class) NOTESTABLISHEDWITH&node=&snode

SVTM030I &var1 FMH-74¬RECEIVEDAFTER STEPERROR:

SVTM050I &var1 PROCESSINTERRUPTED:RECOVERYINITIATED

SVTM052I &stpnm &func&pname(&pnum) &node=&snode&var1

SVTM054I &var1 SNODEREQUESTINGSESSIONSHUTDOWN F/END_OF_STEP

SVTM063I PASSWORD NOTMATCHED IN C:DAUTH FILE--MSG=SAFB005I

SVTM102I MSGID=&mgid&msgtext,NODE=&snodeSENSE=&senseLUNAME=&slu

sessionRetryExceeded The IBM Connect:Direct Processexceeded the session retrythreshold and is placed in the Holdqueue.

SVTM505I Session Retryexceeded for&pname &pnum

Alarm

processRetryExceeded The IBM Connect:Direct Processexceeded the process retrythreshold and is placed in the Holdqueue.

SVTM506I Process Retryexceeded for&pname &pnum

Alarm

maxProcess MAXPROCESS value is reached. STAA010I Task not created.Max Processcount reached.

Alarm

Chapter 4. Administration Guide 317

Trap Event Description Trap Trigger Short MessageText

Event

maxPnode The maximum number of PNODEProcesses is reached.

STAA006I Task not created.Max primarytask countreached.

Alarm

ProcessNotStarted Process was not started becauseIBM Connect:Direct quiesced and atask could not be created.

STAA011I SNODE task notcreated, SessionQuiesce inprogress

Alarm

STAA012I PNODE task notcreated, SessionQuiesce inprogress

STAA008I Task not created.No free TCAavailable.

STAA003I Task not created.IBMConnect:Direct isquiescing.

maxSnode The maximum number of SNODEProcesses is reached.

STAA005I Task not created.Max secondarytask countreached.

Alarm

tcpCloseFailure A TCP Close failed leavingthe TCP/IP socket in use andunavailable.

STCP105I TCP CloseSocket Failure

Alarm

userMessageAlarm A user-defined IBM Connect:Directmessage is issued.

User-defined message text Alarm

tcqMovement A IBM Connect:Direct Process ismoved to the Hold queue due toerrors during Process execution.

SVTM105I PNAME=&pname,PNUM=&pnumMOVED TOQ=&q,QSTATUS=&qstat

Status

tcqMovement A IBM Connect:Direct Process ismoved to the Process Retain queue.

SVTM105I PNAME=&pname,PNUM=&pnumMOVED TOQ=&q,QSTATUS=&qstat

Status

processFlushed A IBM Connect:Direct Process isflushed.

SOPD049I IBMConnect:DirectProcess,&pnam&pnum, flushedby &userid.

Status

318 IBM Connect:Direct for z/OS: Documentation

Trap Event Description Trap Trigger Short MessageText

Event

userMessageStatus A user-defined IBM Connect:Directmessage is issued.

User-defined message text Status

STATS EventsThe following table details alarm and status events that occur due to the STATS queue.

Trap Event Description Trap Trigger Short MessageText

Event

statsDisabled An error occurred that caused theSTATS logging to be disabled.

SSTL001I Statistics loggingfunction isdisabled.

Alarm

statsStress IBM Connect:Direct STATS queue isunder stress.

SSTL041I Statistics facilityunder stress,waiting on queueelements.

Alarm

statsStressResolved The STATS Queue stress isresolved.

SSTL042I Statistics facilitystress resolved.

Alarm

statsSwitchOccurred A IBM Connect:Direct STATS fileswitch has occurred.

SSTL013I Statistics filepair switch from&a to &b

Status

Miscellaneous EventsThe following table details other alarm and status events.

Trap Event Description Trap Trigger Short MessageText

Type

tracesEnabled A IBM Connect:Direct MODIFYDEBUG command is issued.

STRA028I IBMConnect:DirectTraces enabled.

Status

netmapUpdate Dynamic update of the IBMConnect:Direct NETMAP occurred.

SMUP191I IBMConnect:DirectNETMAP fileupdated.

Status

authUpdate Dynamic update of the IBMConnect:Direct AUTH file occurred

SAFC005I IBMConnect:DirectAUTH fileupdated.

Status

typeUpdate Dynamic update of the IBMConnect:Direct TYPE file occurred

SAFI013I IBMConnect:DirectTYPE fileupdated.

Status

initparmRefresh Dynamic update of the IBMConnect:Direct INITPARM fileoccurred

SITA992I INITPARMRefresh by&useridcompleted

Status

Chapter 4. Administration Guide 319

Trap Event Description Trap Trigger Short MessageText

Type

changeProcess A CHANGE PROCESS commandoccurred.

SOPB017I Change Processcommand by&useridcompleted.

Status

deleteprocess A DELETE PROCESS commandoccurred.

SOPC011I Delete Processcommand by&useridcompleted

Status

tcqFull TCQ file is full. SPQL001I TCQ File Full Alarm

tcqThreshold TCQ file becoming full. SPQL002I TCQ Full&VAR1% Full.Max.# CI:&VAR2 # UsedCI: &VAR3

Alarm

tcqThresholdResolved TCQ is now below the definedthreshold.

SPQL003I TCQ File is nowbelow the userdefinedThreshold of%%.

Status

Setting Up SNMPUse the following procedure to set up SNMP Support.

Note: Before performing this procedure, migrate the CDMIB and IBM Connect:Direct Trap Configurationfiles to HP OpenView. Refer to Customizing SNMP in Installing IBM Connect:Direct in the IBMConnect:Direct for z/OS Configuration Guide for more information.

1. Specify SNMP=YES in the initialization parameters file.2. If you want to exclude or disable any trap event or define additional trap triggers described in

Identifying Trap Variables, create a data set containing all the trap events that you want to disable.Following is an example.

Note: All traps are enabled by default.

sendStatusTraps = NstatsDisabled = NstatsStress = NstatsStressResolved = NuserMessageAlarm = ( SVTM100I , SVTM101I )

A sample SNMP.DSN file is in the $CD.SDGASAMP data set, member DGAXSNMP.

If you do not want to exclude any trap events, go to step 4.3. Set the SNMP.DSN initialization parameter to the data set name created in step 2.

SNMP.DSN=data set name

4. Set the SNMP.MANAGER.ADDR initialization parameter. This parameter is the TCP/IP address orhostname of the host where the SNMP Network Manager is initialized. By default, this addressis the same as the TCP/IP address that IBM Connect:Direct is using or the local hostname. In aIBM Connect:Direct/Plex environment, the default is the TCP/IP address of the IBM Connect:DirectManager. This parameter is required if the network manager resides on a different host or is required touse a different TCP/IP address. Following is an example.

320 IBM Connect:Direct for z/OS: Documentation

SNMP.MANAGER.ADDR=123.4.5.6

5. Set the SNMP.MANAGER.PORTNUM initialization parameter. This port is the TCP/IP port that is definedfor UDP traffic to the network manager. The default is 162. This parameter is required if the definedUDP port number is something other than 162. Following is an example.

SNMP.MANAGER.PORTNUM=163

After SNMP SetupAt IBM Connect:Direct installation, the SNMP trap table is initialized and whenever any event occurs afterthe SITA628I message is issued, IBM Connect:Direct determines if the event is a trap trigger and issuesthe appropriate trap to a network manager. The following messages are common at initialization:

• SITA001I Connect:Direct for z/OS initialization has begun.• SITA002I Connect:Direct parameter file allocated and open.• SITA022I Loading Connect:Direct modules.• SITA601I The TCP server modules are loaded.• SITA067I MESSAGE file is open.• SITA628I SNMP Trap Agent Initialization Complete.

If any error occurs during initialization of SNMP, the appropriate message is issued to indicate that theSNMP Trap Agent is disabled or that the initialization will terminate.

You can refresh and modify the SNMP initialization parameters after initialization completes by using theMODIFY INITPARM command.

INQUIRE SNMP Command Displays the SNMP Trap TableThe INQUIRE SNMP command displays the contents of the SNMP trap table. The INQUIRE SNMPcommand has the following format.

Label Command Parameter

(optional) INQuire SNMP

Issuing the INQUIRE SNMP Command through the IUITo display the contents of the SNMP trap table from the IUI, follow this procedure.

1. Select option INQ from the Connect:Direct Administrative Options Menu.

The Inquire DTF Internal Status screen is displayed.2. Select the ITRP option.3. Press ENTER.

The contents of the SNMP trap table are displayed, as in the following sample.

Chapter 4. Administration Guide 321

************************************************************************************************** BROWSE SYS11069.T114309.RA000.MWATL1.NDMAPI.H01 Line 00000056 Col 001 132 Command ===> Scroll ===> CSR==============================================================================SC.DUB.MWATL3 *SNMP TRAP TABLE* DATE: 2011.03.10 TIME: 11:43:22==============================================================================TRAP TRIGGER TRAP NAME TRAP STATUS TRAP TYPE============================================================================== SVTM506I PROCESSRETRYEXCEEDED ENABLED STATUS SVTM105I TCQMOVEMENT ENABLED STATUS SOPD049I PROCESSFLUSHED ENABLED STATUS SSTL013I STATSSWITCHOCCURRED ENABLED STATUS STRA028I TRACESENABLED ENABLED STATUS SMUP191I NETMAPUPDATE ENABLED STATUS SAFC005I AUTHUPDATE ENABLED STATUS SAFI013I TYPEUPDATE ENABLED STATUS SITA992I INITPARMREFRESH ENABLED STATUS SOPB017I CHANGEPROCESS ENABLED STATUS SOPC011I DELETEPROCESS ENABLED STATUS SPQL003I TCQTHRESHOLDRESOLVED ENABLED STATUS******************************************** Bottom of Data **************************************

Using the INQUIRE SNMP Command from the Batch InterfaceTo use the INQUIRE SNMP command from the Batch interface, follow this procedure.

1. Place your commands in a batch job stream as demonstrated in the IBM Connect:Direct for z/OS UserGuide.

2. Submit the job while IBM Connect:Direct is running. The settings are displayed.

Note: You must set the fifth character of the DGADBATC output parameter specification to Y to printthe result of the command that is in the temporary data set.

IBM Connect:Direct ExitsNote: APARs and PTFs from IBM have "HOLD for ACTION" directives that identify if reassembly of exitsis required. Reassemble exits accordingly. If you upgrade, reassemble your exits to pick up any macro orcontrol block changes.

IBM Connect:Direct provides several sample exits some of which can be used to customize the onlineexecution of IBM Connect:Direct. One of these exits, the Stage 2 Security exit, can be used to test newapplications and customer connections. For more information, see Process Exit for Testing (DGAXPRCT).

Before coding or using an exit, read the Special Considerations section below to ensure that the exitexecutes properly.

Note: All sample exits provided in IBM Connect:Direct define the proper AMODE and RMODE settingswithin the source member themselves. All user exits should be link-edited with AMODE=ANY andcapable of executing in 31-bit mode (calls to user code will have the parameter list passed using 31-bitaddresses). Each user exit should preserve the mode in which it was invoked and return to the callerin the proper mode. Modules written to execute in 31-bit mode can be link-edited with RMODE=ANY orRMODE=24. Check the source for the sample exits to see how IBM Connect:Direct defines the properAMODE and RMODE settings.

To notate modifications by user in the the module maintenance history section of NDMLOG, include thelocal user ID by specifying the &UID SETC 'xxxx' local identifier in IBM Connect:Direct exits as part of theSCENTER macro. This value can contain up to 8 characters.

Sample JCL for assembling user exits is provided in $CD.SDGASAMP library members DGAXSTG1 andDGAXSTG2.

322 IBM Connect:Direct for z/OS: Documentation

Special ConsiderationsThe following special considerations apply to Connect:Direct for z/OS exits:

• Avoiding Out-of-Storage ABENDS

– To avoid out-of-storage ABENDS in IBM Connect:Direct, examine all user exits to verify that allobtained storage either via GETMAIN or STORAGE OBTAIN is freed. For each GETMAIN/STORAGEOBTAIN that an exit issues, the exit must also issue a corresponding FREEMAIN/STORAGE RELEASEto avoid accumulating storage. If an exit opens a file, you may need to issue a FREEPOOL after the fileis closed.

• Using Exits in 31-Bit Addressing Environments

– Because information passed to the exit by IBM Connect:Direct is located above the 16 megabyte line,you must link-edit the module with AMODE 31 to make it capable of executing in 31-bit mode. Referto the section in this chapter describing the particular exit to see if this requirement applies.

– IBM Connect:Direct honors the addressing mode (AMODE) and residence mode (RMODE) attributesof user exits. The exit modules are loaded based on the RMODE specification and given control in theaddressing mode specified in the AMODE attribute. Link exits that run above 16 megabytes in 31-bitmode to AMODE=31, RMODE=ANY.

– Verify that your exits are coded to receive control and execute in the AMODE with which they arelinked.

– Exits must return control to IBM Connect:Direct in the AMODE in effect when IBM Connect:Directinvokes the exit. IBM Connect:Direct calls your exit through Branch and Save and Set Mode (BASSM),and you return to IBM Connect:Direct through Branch and Set Mode (BSM).

Note: All sample exits provided in IBM Connect:Direct define the proper AMODE and RMODE settingswithin the source member themselves. All user exits should be link-edited with AMODE=31 and capableof executing in 31-bit mode (calls to user code will have the parameter list passed using 31-bitaddresses). Each user exit should preserve the mode in which it was invoked and return to the callerin the proper mode. Modules written to execute in 31-bit mode can be link-edited with RMODE=ANY orRMODE=24. Check the source for the sample exits to see how IBM Connect:Direct defines the properAMODE and RMODE settings.

• Linkage Editor Attribute Requirements

– You must create all exits that execute in the DTF address space and link-edit them as RENT andREUS. Only the Stage 1 exits (DGACXSIG and DMCXSUBM) do not require re-entrancy.

Statistics ExitIBM Connect:Direct generates and logs statistics to an online journal, then writes the information to theIBM Connect:Direct statistics log as individual records.

Each record contains information about a single event, and is identified by a 2-character record type. Forexample, type CT is a copy termination record and FP is a flush Process record.

IBM Connect:Direct provides a statistics exit that gives a user-written program access to the statisticsrecords as they are generated. This exit can:

• Output the records or data generated from the records to a user-defined journal, including an SMF log• Include or exclude the logging of any record to IBM Connect:Direct by return codes

CAUTION: Statistics records are often essential in debugging IBM Connect:Direct problems.Excluding records from the statistics log makes problem determination more difficult or evenimpossible.

The statistics exit runs as a subtask in the IBM Connect:Direct DTF address space. IBM Connect:Directuses the STATISTICS.EXIT initialization parameter to specify the exit module name. You define this name,but it cannot conflict with the name of any IBM Connect:Direct module. If a user-defined journal isrequired, you must add the necessary data definition (DD) statements to the IBM Connect:Direct startupjob stream.

Chapter 4. Administration Guide 323

Note: In a IBM Connect:Direct /Plex environment, the statistics exit, by default, only runs on the IBMConnect:Direct /Manager. For more information on how to cause the statistics exit to run on the IBMConnect:Direct /Plex server, see “STATISTICS.EXIT = modname | (modname[,MANAGER | SERVER |BOTH])” on page 498.

The statistics exit indicates if a record is logged by setting a return code set in the SQUSER field of theSQCB. The return code is initialized to zero before the exit is invoked.

You do not have to rewrite existing exits if you do not want to exclude records. Existing exits do not alterthe SQUSER field and operate the same as before.

Sample Statistics ExitsIBM Connect:Direct provides the following sample statistics exits in $CD.SDGASAMP library:

Exits Description

DGAXSMF This sample exit logs IBM Connect:Direct statistics records to the SMF log. It logsrecords to the SMF log by prefixing each statistics record with an SMF record header,and then uses the SMFWTM macro to write to the SMF log. The SMF record is type 132.

DGAXEV01 This sample exit provides a means for an application to access event data. For moreinformation on how to use the Event Services Support (ESS) facility with this exit, seethe IBM Connect:Direct for z/OS Facilities Guide.

This exit writes each event record to a predefined data set. You must modify DGAXEV01to specify the name of your event exit data set, and define the data set to accommodaterecords up to 2048 bytes in length.

DGAXSACC This exit documents the path to log user accounting data from the copy termination (CT)records.

This exit is invoked for every IBM Connect:Direct statistics record written to thestatistics file, but only processes CT records.

DGAXSXIT This sample exit simply checks for copy termination records. When IBM Connect:Directencounters a copy termination, the system issues a WTO.

DGAXSXMC This sample exit precludes the logging of PDS member copy (MC) records that have goodreturn codes. It enables the logging of records of this type only when they have non-zeroreturn codes. It also enables the logging of all other record types regardless of theirreturn codes.

DGAXSCPU This sample Statistics exit no longer adds CPUTIME=xxxxxxxx to the end of the StepTermination records. Beginning with Release 5.1, CPU time fields have been presentin record extensions addressed by offsets from the beginning of the Statistics recordfor Copy Termination (DGA$CTR), Run Task Termination (DGA$RTTR) and ProcessTermination (DGA$PTR). Run Job Termination (DGA$RJTR) contains no CPU time fields.

This sample code shows how to access those CPU time fields as well as other fieldsin the record extension areas. For demonstration purposes, this code produces reportoutput for each Copy Step showing Process Name, Number and SNODE Name pluscounts for records and blocks read / written and finally the time on CP plus time onZIIP for both sending and receiving as captured in the CT record. This output goes toDDNAME=SCDIAG or can be directed to another DD.

Note: The sole purpose of this sample exit is to demonstrate accessing fields in StatRecord extensions. We do not recommend it be run in production environments.

Statistics Exit Calling ConventionsIBM Connect:Direct calls the statistics exit once for each statistics record generated. Standard linkageconventions apply.

324 IBM Connect:Direct for z/OS: Documentation

The exit is given control with register 1 pointing to a list of two parameters. They are:

• The first parameter is a pointer to the statistics record.• The second parameter is a pointer to an SQCB that you need for setting a return code if record exclusion

is appropriate.

The first 2 bytes of the record contain the record length in binary format. The third and fourth bytes of therecord contain the 2-chharacter record identifier. Refer to “Statistics Records” on page 325 to see a tablecontaining a list of the record type identifiers.

The second word of the record contains the time of day that the record is generated. The third wordcontains the date the record is generated.

Additional information in the records depends on the record type.

Assembler macros are provided in $CD.SDGAMAC library to generate dummy sections (DSECTS) to mapall the record types. The exit program includes the DSECTS that map the record types to the exitprocesses.

A return code of 0 indicates that the record is logged. A return code of 4 indicates that the record is notlogged.

The following figure depicts the information passed to the exit.

Statistics RecordsIBM Connect:Direct calls the statistics exit once for each statistics record generated in the DTF. The inputto the exit is a pointer to the statistics record that is ready to be logged and a pointer to an SQCB. Therecord can be any record type. The exit must examine the record type identifier at a displacement of X'02'bytes from the beginning of the record to determine the record type and the DSECT that describes itscontents.

Record TypesThe following table lists the statistics record types, their corresponding record type identifiers, andthe name of the assembler macro in $CD.SDGAMAC library that generates the DSECT describing therecord contents. For information about selecting, displaying, and printing statistics information for IBMConnect:Direct activities, see IBM Connect:Direct for z/OS User Guide.

The statistics records in this section also apply to Event Services Support.

Chapter 4. Administration Guide 325

Record ID Description Macro

CE Copy I/O Start DGA$STEP

CH Change Process DGA$CPTR

CI Copy Step Start DGA$STEP

CS Statistics Command DGA$SCMD

CT Copy Termination DGA$CTR

CX Check Certificate Validity DGA$XCR

DC Directory Commands DGA$DTR

DP Delete Process DGA$DPTR

DT Select Task DGA$DTR

DU Delete User DGA$AER

EI Event Services Start Command DGA$EVR

ES Write External Statistics Command DGA$ESR

ET Event Services Stop Command DGA$EVR

EV Event Services Command DGA$EVR

FA IGWFAMS Message DGA$FAMS

FI Long File Name Record DGA$FIR

FP Flush Process DGA$FPTR

FS Suspend Process DGA$FPTR

FT Flush Task DGA$DTR

GO Process Modal - GOTO, ELSE, or EXIT Statement DGA$MODL

H2 High Concurrent Session Count DGA$H2R

HW High Concurrent Session Count DGA$HWR

IA Inquire Statistics DGA$DTR

IB Inquire Debug DGA$DTR

ID Inquire STATDIR DGA$DTR

IF Process Modal - IF Statement DGA$MODL

IK Inquire APKey File DGA$DTR

IP Inquire Initialization parameters DGA$DTR

IT Inquire SNMP Trap Table DGA$DTR

IU Insert User DGA$AER

IX Inquire IBM Connect:Direct/Plex DGA$DTR

JI Run Job Start DGA$STEP

JS JSON Command DGA$JSR

LF ICO Log File Record DGA$FRER

M2 Multiple Copy Record DGA$MCR

326 IBM Connect:Direct for z/OS: Documentation

Record ID Description Macro

MC PDS Member Copy DGA$MCR

NL Process modal - EIF or PEND statement DGA$MODL

NM NETMAP Updated DGA$NMR

OP Operator Clist DGA$OPR

PE IBM Connect:Direct/Plex Error Record DGA$PER

PI Process Start DGA$PIR

PR Performance Measurement Record DGA$PRRB

PL Process Library Command DGA$PLR

PS Process Submit DGA$PSSR

PT Process Termination DGA$PTR

PX IBM Connect:Direct/Plex Activity (Leave or Join IBMConnect:Direct/Plex)

DGA$PXR

QE Queue Change to EXEC Queue DGA$QCR

QH Queue Change to HOLD Queue DGA$QCR

QT Queue Change to TIMER Queue DGA$QCR

QW Queue Change to WAIT Queue DGA$QCR

RE ICO Report Record DGA$FRER

RF Refresh/Update initialization parameters DGA$AER

RJ Run Job DGA$RJTR

RO ICO Event Record DGA$OEVT

RT Run Task DGA$RTTR

S2 Statistics Logging Statistics DGA$S2R

SB Session Begin DGA$SSCR

SE Session End DGA$SECR

SC Statistics Control Record DGA$SCR

SD Start IBM Connect:Direct DGA$SDC

SF Statistics Format DGA$SFRC

SI Signon DGA$SFR

SN Select Netmap DGA$DTR

SO Signoff DGA$SFR

SP Select Process DGA$DTR

SS Select Statistics DGA$DTR

ST Stop IBM Connect:Direct DGA$STDC

SU Select User DGA$AER

SW Submit within a Process DGA$PSSR

SY SYSOPTS DGA$SYR

Chapter 4. Administration Guide 327

Record ID Description Macro

TF TCQ Threshold Full DGA$TXR

TI Run Task Start DGA$STEP

TL TCQ Threshold Low DGA$TXR

TP Throughput Record Statistics DGA$TPR

TR Trap Event Record DGA$TRP

TS Suspend Task DGA$FPTR

TW TCQ Threshold Warning DGA$TXR

UM Update Network map DGA$AER

UU Update User DGA$AER

VP View Process DGA$DTR

WO WTO DGA$FWTO

WS Select Stat Command DGA$DTR

XO Trace On/Off DGA$XOR

YA-YZ, Y0-Y9,Y@, Y#, Y$,Y%

Reserved for External Statistics Records DGA$EXST

ZI SNODE Process Start DGA$PIR

ZT SNODE Process Terminated DGA$PTR

Record Control Block MapsThe following table lists the statistics record control block maps.

Macro Name Description

DGA$AER Authorization Event Statistics Record

DGA$CPTR Change Process Statistics Record

DGA$CTR Copy Termination Statistics Record

DGA$DPTR Delete Process Statistics Record

DGA$DTR Display Termination Record

DGA$ESR WRITE EXSTATS Command Record

DGA$EVR Event Services Command Statistics Record

DGA$FAMS IGWFAMS (File and Attribute Management Services) Macro Statistics Record

DGA$FIR Long File Name Statistics Record

DGA$FPTR Flush and Suspend Process Statistics Record

DGA$FRER InterConnect Report Record containing text line from SYSPRINT (Record Type is RE)

DGA$FRER InterConnect Log File Records produced if LOG=YES is specified for ADD andEXTRACT operations (record type is LF)

DGA$FWTO WTO Statistics Record

328 IBM Connect:Direct for z/OS: Documentation

Macro Name Description

DGA$H2R High Concurrent Session Count

DGA$HWR High Concurrent Session Count Statistics Record

DGA$JSR File Agent Configuration Command Record

DGA$LSR Log Swap Statistics Record

DGA$MCR PDS Member Copy Record

DGA$NMR NETMAP Updated

DGA$OEVT InterConnect Report Event Record containing one record per report written (RecordType is RO)

DGA$OPR Operator Clist Record

DGA$PER XCF Error Message Statistics Record (from Sysplex)

DGA$PIR Process Initiation Statistics Record

DGA$PLR Process Library Record

DGA$PRRB Performance Measurement Statistics Record

DGA$PSSR Submit Process Statistics Record

DGA$PTR Process Termination Record

DGA$PXR Sysplex (IBM Connect:Direct /Plex) Statistics Record

DGA$QCR Process Queue Change Statistics Record

DGA$RJCB Run Job exit

DGA$RJTR Run Job Termination Record

DGA$RTTR Run Task Termination Record

DGA$S2R Statistics Logging Record

DGA$SCMD Statistics Command Record

DGA$SCR Statistics ESDS Control Record

DGA$SDC Start IBM Connect:Direct Statistics Record

DGA$SFR Signon/Signoff Statistics Record

DGA$SFRC Statistics Format Record

DGA$SGNB Connect:Direct Secure Plus Statistics Record

DGA$SSCR Session Begin Record

DGA$SECR Session End Record

DGA$STDC Stop IBM Connect:Direct Statistics Record

DGA$STEP Step Start/Copy Start Statistics Record

DGA$SYR SYSOPTS Record

DGA$TPR Throughput Record Statistics

DGA$TQGT GOTO Statement

DGA$TQIF If Statement

DGA$TQNL NULL Statement

Chapter 4. Administration Guide 329

Macro Name Description

DGA$TRP Trap Event Record

DGA$TXR TCQ Threshold Warning

TCQ Threshold Full

TCQ Threshold Low

DGA$WRP Statistics File Wrap Record

DGA$XOR TRACE On/Off Statistics Record

Submit ExitThere are two kinds of Submit exits, Stage 1 and Stage 2. The Stage 1 Submit exits always run at thetime of the Submit, in the address space of the submitter (API submit) or the DTF being submitted to(SUBMIT Statement in a Process, sometimes called SUBMIT WITHIN). The Stage 2 Submit exit runs in theDTF address space before it queues the Process for execution, usually very soon after Stage 1 processingcompletes. But, if the DTF is not active when the Process is submitted (e.g. ESF Submit), the intervalbetween the time Stage 1 and Stage 2 exits run can be large.

The Unauthorized Stage 1 Submit exit is just the new name for the pre-C:D 6.2 Stage 1 Submit exit. Itprovides an interface to a user-written program when you submit a Process. With this interface, the userprogram can change Process information, such as Process name, priority, class, and secondary node, andcopy step information such as data set name.

The Authorized Stage 1 Submit exit is new to Connect:Direct 6.2. It can do anything the UnauthorizedStage 1 Submit Exit can do, as well as run APF authorized. It is invoked after the legacy Stage 1 Submitexit.

It is possible for an API submitter to circumvent the Stage 1 Submit exits if they can omit them from theload module search sequence. To prevent this, you can deny the ordinary user UPDATE access to an APFauthorized library, because the Submit exits must be loaded from an APF authorized library.

The Stage 2 Submit exit runs APF Authorized in the DTF address space. If this exit is active, it is notpossible for the Submitter to circumvent its execution. If TCQE flag TQSUBAOK is ON, it indicates theSubmit was allowed by the Authorized Stage 1 Submit exit. If it is OFF the Authorized Stage 1 Submit exitwas not present during Stage 1 Submit. The flag can be tested in a Stage 2 Submit exit to ensure an APIsubmitter invoked the Authorized Stage 1 Submit exit. If the Authorized Stage 1 Submit exit runs and doesnot allow the Submit, the flag will be OFF, and the Stage 2 Submit exit will not be called, since the Submitwas already rejected by Stage 1 processing.

Sample Submit ExitsIBM Connect:Direct provides the following sample submit exits in $CD.SDGASAMP library.

Exits Description

DGAXSUBA This is an Authorized Stage 1 Submit Exit, new to Connect:Direct 6.2. It uses RACROUTEto call SAF to verify that the Submitter ID is authorized to submit a process to theSNODE using an SNODEID (either the default or one specified in the process). If an erroroccurs or the RACROUTE RC>0, DGAXSUBA returns RC=8 (Fail Mode) or 5 (Warn mode).If 8, the user is not authorized and the Submit is rejected and the process is not put onthe TCQ. The exit may require customization by the installation. See the exit source codein DGASAMP for more documentation. The exit must be link-edited with either a Nameor Alias of DMCXSUBA.

DGAXSUBC This exit sets a 0 return code to pass back to the calling program. It also locates andincrements the Process class by 1. It runs either as a stage 1 or stage 2 exit.

330 IBM Connect:Direct for z/OS: Documentation

Exits Description

DGAXSUBD This exit documents the control block path to locate the source and destination dataset names specified in the Process. It sets a 0 return code to pass back to the callingprogram. It also locates and increments the Process class by 1. It runs either as a stage1 or stage 2 exit.

DGAXSUBX This exit sets a return code of 0 to pass back to the calling program. It runs either as astage 1 or stage 2 exit.

DGAXSUBN This exit turns off all compression flags in the Process for a node defined as EXTernal,which is a function of the Stage2 Security exit and indicated in the NETMAP.

If it is named DMCXSUBM, it is invoked as a Stage1 submit exit for normal submits aswell as a Stage2 submit exit for submits within a Process.

DGAXSUBP This exit determines if the submitted Process contains a RUN JOB statement. If theProcess contains a RUN JOB statement and the exit encounters a stage 1 password,the exit returns an error. You must then provide either a PNODEID or an SNODEID,depending on which node the Process is executing. Use the PNODEID or SNODEIDto validate the RUN JOB submitted job stream through the user=uid, password=pwdparameter built by the RUN JOB exit.

DGAXSUBR This exit rejects all submits by setting TARTNCD as 16, TQMSGID of SCBI159I andsetting specific text in UIERRM1 and UIERRM2.

DGAXORR This exit documents the control block path to determine whether the Process isperforming a send or receive. It sets a return code of 0 to pass back to the callingprogram. It runs either as a stage 1 or stage 2 exit.

DGAXACCT This exit is a Stage 1 SUBMIT exit example that shows how to update the Primary andSecondary Node accounting (PACCT and SACCT) information in the submitted Process.

Note: To update accounting information, you must also update your SUBMIT exit.

DGAXSBRX This is a Stage 2 Submit Exit sample.

User can include this in SUBMIT.EXIT to restrict SUBMIT command from all PNODEs, butallow only from those present in node table of DGAXSBRX exit.

Chapter 4. Administration Guide 331

Submit Exit Processing FlowThe following figure illustrates the execution order of the SUBMIT command:

The Submit exit processing flow is:

1. 1. After you issue an IBM Connect:Direct SUBMIT command or SUBMIT statement, the API SUBMITcommand processor calls the Unauthorized Stage 1 Submit exit, if it exists. If it doesn’t exist or returnsRC=0, the API SUBMIT command processor calls the Authorized Stage 1 Submit exit, if it exists. If itreturns RC<8 or doesn’t exist, the submit is successful and the process is put on the TCQ.

2. If the API submit is successful, the DTF SUBMIT command processor calls the Stage 2 Submit exit, if itexists. If it returns RC=0, the Submit has completed successfully.

IBM Connect:Direct provides a sample Submit exit in $CD.SDGASAMP library, called DGAXSUBX, whichyou can use as a model for either the Unauthorized Stage 1 (DMCXSUBM) exit, or the Stage 2(SUBMIT.EXIT = modname) exit.

IBM Connect:Direct also provides a sample Submit exit in $CD.SDGASAMP library, called DGAXSUBA,which you can use as a model for the Authorized Stage 1 Submit Exit (DMCXSUBA).

Stage 1 Submit ExitBeginning with Connect:Direct 6.2, there are two Stage 1 Submit exits. First, the legacy APF UnauthorizedStage 1 Submit exit (DMCXSUBM) is called. If it sets RC>0, then the submit is disallowed. Otherwise, theAPF Authorized Stage 1 Submit exit (DMCXSUBA) is called. If it sets RC>=8, then the submit is disallowed.Otherwise, the Submit is allowed. Both exits are optional and for each its absence is the same as settingRC=0. The Stage 1 Submit exits execute in the API address space when a SUBMIT command is processedand in the DTF address space when a SUBMIT statement is encountered in a Process. Observe thefollowing restrictions and requirements:

• The IBM Connect:Direct Stage 1 Submit exits are implemented as executable load modules.• You must give the load modules either Names or Aliases of DMCXSUBM and DMCXSUBA for the

Unauthorized and Authorized exits, respectively.• Both should be link-edited as RENT, REUS and AMODE 31.• The Unauthorized exit (DMCXSUBM) can be link-edited with an authorization code of 0, since it does

not execute APF Authorized. The Authorized exit (DMCXSUBA) must be link-edited with an authorizationcode of 1, otherwise it will not be called in an APF authorized environment for every type of caller.

332 IBM Connect:Direct for z/OS: Documentation

• The Unauthorized exit (DMCXSUBM) must come from an authorized load library. The Authorized exit(DMCXSUBA) must come from an authorized concatenation.

• In TSO there are many ways to make the load modules available to the IUI. You can have them in theLINKLIST, a STEPLIB, TSOLIB, or ISPLLIB DD, or in LIBDEF ISPLLIB. Not all methods work when usingthe Stage 1 Submit exits. The following shows various combinations and the issues they can run into.

--------------------------------------------------------------------------------------------------------- | LINKLIST | STEPLIB | TSOLIB | ISPLLIB | LIBDEF | Results | | | | | | ISPLLIB | | | | | | | | | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD+EXIT | | | | | OK - preferred | | | PROD+EXIT | | | | OK | | | | PROD+EXIT | | | OK | | | | | PROD+EXIT | | OK - see note 1 | | | | | | PROD+EXIT | OK - see note 1 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD+EXIT | | | | PROD+EXIT | OK | | | PROD+EXIT | | | PROD+EXIT | OK | | | | PROD+EXIT | | PROD+EXIT | OK | | | | | PROD+EXIT | PROD+EXIT | OK - see note 1 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD+EXIT | | | | non-C:D | OK | | | PROD+EXIT | | | non-C:D | OK | | | | PROD+EXIT | | non-C:D | OK | | | | | PROD+EXIT | non-C:D | OK - see note 1 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD | EXIT | | | | OK - Use to test exits via STEPLIB | | PROD | | EXIT | | | OK - Use to test exits via TSOLIB | | PROD | | | EXIT | | OK - Use to test exits via ISPLLIB | | PROD | | | | EXIT | OK - Use to test exits via LIBDEF ISPLLIB | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD | | | | EXIT | OK | | | PROD | | | EXIT | Exits not found - see Note 2 | | | | PROD | | EXIT | Exits not found - see Note 2 | | | | | PROD | EXIT | Exits not found - see Note 2 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | EXIT | | | | PROD | OK - see note 1 | | | EXIT | | | PROD | Exits not found - see Note 3 | | | | EXIT | | PROD | Exits not found - see Note

Chapter 4. Administration Guide 333

3 | | | | | EXIT | PROD | Exits not found - see Note 3 | ---------------------------------------------------------------------------------------------------------

Where: non-C:D - does not contain C:D load modules or the Stage 1 exit(s) PROD - contains all C:D product load modules except the exit(s) EXIT - contains only Stage 1 exits (e.g. DMCXSUBA and DMCXSUBM) PROD+EXIT - contains both C:D product load modules and the Stage 1 exit(s)

Notes: 1. In these cases, the exits are found either in LIBDEF ISPLLIB or in the normal MVS Load Module search sequence starting with ISPLLIB. But when the Authorized Stage 1 Submit exit (DMCXSUBA) is invoked, it executes in an APF authorized environment, which means the exit is running under a TCB under IKJEFT02, not ISPTASK, and so MVS cannot search the LIBDEF ISPLLIB or the ISPLLIB DD for load modules called by DMCXSUBA. MVS can and does search any TSOLIB and STEPLIB DDs, and finally the LINKLIST. The distributed Authorized Stage 1 Submit exit attempts to use the C:D DISPLAY macro to issue debug messages. DISPLAY does an MVS LOAD on DMGRAT. But DMGRAT is non-reentrant and was loaded earlier by the IUI when it was running non-APF authorized. MVS rejects the in-storage copy of DMGRAT as unsafe, and tries to load a fresh copy. If MVS cannot find a fresh copy in the TSOLIB DD, STEPLIB DD or the LINKLIST it issues the error message:

CSV027I REQUESTED MODULE DMGRAT NOT ACCESSED, APF PROTECTION INADEQUATE

Fortunately, this merely prevents the exit from issuing debug messages. Other than that and the above message issued to the TSO user, the exit works normally. The CSV027I error message can be suppressed using the TSO command PROFILE NOWTPMSG. Alternately, the sample exit DGAXSUBA has a switch to turn off the debug messages, thereby preventing the problem. This problem does not occur with the Unauthorized exit.

2. In these cases, the IUI LOADs a C:D module (DMDYNALO) using DCB=(LIBDEF-ISPLLIB-DCB) and gets S806-04. This is because with LOAD DCB=(LIBDEF-ISPLLIB-DCB) MVS searches that DCB concatenation, and if the module is not found, skips any ISPLLIB, TSOLIB, and STEPLIB DDs, and resumes searching with the LINKLIST. If you are running another instance of the IUI on another ISPF logical screen, then that instance's in-storage copy of DMDYNALO will be found. But if there is only one instance, then not finding DMDYNALO causes DMISTART to clear the pointer to the LIBDEF ISPLLIB DCB and not use it again. Subsequent searches for load modules are done with DCB=0, thus bypassing LIBDEF ISPLLIB. Thus the exits in LIBDEF ISPLLIB will not be found (unless they’re also in the LINKLIST).

3. In these cases, DMISTART LOADs DMDYNALO using DCB=(LIBDEF-ISPLLIB-DCB) and finds it. From there on, the IUI load modules use LOAD with DCB=(LIBDEF-ISPLLIB-DCB). When this form of LOAD is used, the MVS load module search sequence skips searching the ISPLLIB, TSOLIB, and STEPLIB DDs. If the exits are in one of those DDs, they will not be found (unless they’re also in the LINKLIST

• A new sample exit member, DGAXSUBA, is supplied which is configurable for multiple security productsand profile naming schemes. It also has several other configuration options. It must be linked withAC=1 and a name or alias of DMCXSUBA into an APF authorized library. The APF authorized libraryshould be the same one the rest of the product is installed into. A new sample JCL member, DGAXSTGA,is supplied to assemble and link DGAXSUBA and assign it an alias of DMCXSUBA.

• In order to call the new APF authorized exit from the IUI (or other TSO caller), DMCXSUBA must beincluded in SYS1.PARMLIB(IKJTSOxx) AUTHTSF list.

• In order to call the new APF authorized exit from DGADBATC (DMBATCH), DGADBATC now executes asan APF authorized jobstep program (linked with AC=1). Thus, DGADBATC must be loaded from an APFauthorized concatenation.

334 IBM Connect:Direct for z/OS: Documentation

Authorized Stage 1 Submit Exit Processing Return Codes and MessagesThe following table shows the possible return codes and messages that can occur during AuthorizedStage 1 Submit Exit processing, their outcomes, and possible User Action.

Stage 2 Submit ExitThe stage 2 Submit exit control point executes in the DTF address space when a SUBMIT command or aSUBMIT statement is encountered. Observe the following restrictions and requirements:

• The stage 2 Submit exit is implemented as an executable load module.• The name of the load module is user-defined, but cannot conflict with any IBM Connect:Direct load

module names.• Activate the stage 2 Submit exit by specifying SUBMIT.EXIT=(modname) in the IBM Connect:Direct

initialization parameters.• You must link-edit the module as re-entrant and place it in a load library that the IBM Connect:Direct

DTF can access.• The module must come from an authorized library.• Because information passed to the exit by IBM Connect:Direct is located above the 16 megabyte line,

you must link-edit the module with AMODE ANY to make it capable of executing in 31-bit mode.

Control Block FormatBecause Submit exits are invoked in different environments, some control block fields may not be filledin. This section presents the control blocks passed to the exits. Upon entry to the Submit exits, Register 1points to a parameter list (PLIST) as shown in the following figure. This list may contain the addresses ofthe following components:

• TCQE• SQCB• Composite NETMAP record (The node usage (US) record is not a part of the composite NETMAP record.)• A fullword that contains 1 or 2 indicating whether this is a Stage 1 or Stage 2 exit• UICB (User Interface Control Block)• Address of 25 fullword work area (Authorized Stage 1 Submit exit only.)

Note: The SQCB, UICB and composite NETMAP record addresses may be zero. For the Authorized Stage1 Submit Exit, the 2nd word in the PLIST, rather than having the SQCB address (which is not available forany Stage 1 Submit exit), has a pointer to the instruction that invoked the exit. Also, For the AuthorizedStage 1 Submit Exit only, there is a 6th FW in the PLIST which contains the address of 25 FW’s of storagefor use by the exit.

Chapter 4. Administration Guide 335

If the Process submission is to be rejected, the Unauthorized Stage 1 Submit exit and the Stage 2 Submitexit must set a positive non-zero value in Register 15 and the return code field (TQRTNCD) of the TCQE.A message ID in the TQMSGID field in the TCQE should also be set. The same is true of the AuthorizedSubmit exit except that the RC must be >= 8 to reject the submission.

The only modifiable field in the UICB are UIERRM1 and UIERRM1 for which you can return your ownmessage text to Connect:Direct, the exit must put up to 64 bytes of text into UIERRM1. If desired, upto 64 more bytes can be put into UIERRM2. If nothing is returned in UIERRM1, then both UIERRM1 andUIERRM2 will be ignored.

The following figure illustrates the layout of the TCQE. In the Process contained in the Statement ControlBlock, DMxxxxxx represents the macro name for the statement (COPY, RUN JOB, RUN TASK, SUBMIT,etc.).

TCQ Header macro= DMTCQE

DSECT= TCQE

Command Statement Header Section macro= DGA$TQSH

DSECT= TCQSH

Statement Control Block macro= DMxxxxxx

Displacement values found in the TCQE and pointers in the TCQSH to the next or previous TCQSH arefrom the top of the TCQE and may need to be multiplied by 16 (if the Process is larger than 64K).Displacement values found in the statement control blocks are from the top of the TCQSH associated withthat statement control block.

The following figure illustrates the layout of the composite NETMAP record.

336 IBM Connect:Direct for z/OS: Documentation

COMPOSITE NETMAP RECORD

$$NN - displacement to ADJACENT NODE Record

$$AA - displacement to ALT.COMM Record

$$BA - displacement to BATCH.APPLI Record

$$CA - displacement to CICS.APPLID

$$DN - displacement to LDNS Record

$$NA - displacement to APPLIDS Record

$$ND - displacement to LUPOOL Record

$$NT - displacement to TCP.API Record

$$TA - displacement to TSO.APPLIDS Record

$$N6 - displacement to IPv6 Record

$$NU - displacement to UDT Record (obsolete)

$$CM - displacement to COMMENT 13 Record

macro= DGA$NETE

DSECT= $$REC

ADJACENT NODE Record macro= DGA$NETD

DSECT= NNODEREC

ALT.COMM Record macro= DGA$NETL

DSECT= ALTADDRH

LDNS Record macro= DGA$NET$

DSECT= DNREC

APPLIDS Record macro= DGA$NETA

DSECT= NAAPLREC

LUPOOL Record macro= DGA$NET@

DSECT= NDLUPREC

TCP.API Record macro= DGA$NETT

DSECT= NTAPIREC

IPv6 Record macro= DGA$NET6

DSECT= N6TCPREC

Displacement values found in the composite network map record are from the top of the compositenetwork map.

Note: Modifying fields in the composite network map record is prohibited.

Example of Created Control BlockThis sample section shows how a Process is submitted and the control block that is created when theSubmit exit is invoked. The following figure shows the submitted Process.

Chapter 4. Administration Guide 337

TEST01 PROCESS SNODE=THERESTEP01 COPY FROM (DSN=THIS.DATA.SET) - TO (DSN=THAT.DATA.SET DISP=OLD)IF01 IF (STEP01=0) THENSTEP02 RUN JOB (DSN=Z99.CONTROL(RUNJ))PNODE ELSESTEP03 RUN TASK - (PGM=RTEXAMPL,PARM=(CL44'THIS.DATA.SET')) - PNODE EIFSTEP04 SUBMIT DSN=Z99.PROCLIB(TEST02) HOLD=Y

The following figure illustrates the resulting layout of the Process control block after submitting theProcess named TEST01.

Modifiable TCQE FieldsThe following table describes TCQE fields that you can examine or modify using the Submit exit.

338 IBM Connect:Direct for z/OS: Documentation

TCQE Field Content

TQCBHLNG contains the length of the entire TCQE header. This length added to the address of theTCQE gives the address of the TCQSH.

TQSTMTN contains the number of statements in this Process.

TQUNODE contains the symbolic node name for the submitter of this Process.

TQUID contains the user ID for the submitter of this Process.

TQUPAS contains the password for the submitter of this Process.

TQPUID contains the security user ID at the primary node.

TQOPPAS contains the old security password at the primary node.

TQNPPAS contains the new security password at the primary node.

TQSUID contains the security user ID at the secondary node.

TQOSPAS contains the old security password at the secondary node.

TQNSPAS contains the new security password at the secondary node.

TQRTNCD contains the Process completion code. The user exit changes this field when an error isencountered in the exit or if the Process is no longer submitted upon return from the exit.

TQMSGID contains the Process message ID. The user exit includes a message ID related to anyreturn codes set in the exit.

TQCSPRD contains the displacement to the first Process statement from the TCQE. This lengthadded to the address of the TCQE gives the address of the TCQSH.

Note: If TQGT64K in TQFLAGA is 1, this displacement must be multiplied by 16.

TQPARSES contains the value of the maximum number of parallel sessions allowed for the SNODEwhen submitting a Process.

TQPRSBYT contains parallel session class. See the following section for details.

TQPRSBIT contains parallel session class. See the following section for details.

TQPROCNM contains the name of the submitted Process.

TQSCHDTE contains the Julian date the Process is scheduled to submit.

TQSCHTME contains the time of day the Process is scheduled to submit.

TQSCHDAY contains the day of the week that the Process is scheduled to submit.

TQPRTY contains the priority for Process selection.

TQRETAIN contains the retain status for the Process.

TQTODFLG contains the following interval control flags:

- If TQTODTD is on, a Process has a scheduled time and date it is submitted.

- If TQTOTME is on, a Process has a scheduled time it is submitted.

- If TQTODDAY is on, a Process has a scheduled day of the week it is submitted.

- If TQTODINT is on, a Process is scheduled to run when a specified interval expires.

TQPNODE contains the symbolic node ID of the primary node.

TQSNODE contains the symbolic node ID of the secondary node.

TQSTATUS contains the Process status.

Chapter 4. Administration Guide 339

An exception to the table entry TQPARSES occurs in the stage 1 Submit exit. The stage 1 exit runs inthe user address space (API) and the network map associated with that address space is where thisinformation is retrieved. The network map used by the API may not be the same network map used bythe DTF. The stage 2 Submit exit runs in the DTF address space and is invoked for every submit that takesplace; therefore, the stage 2 Submit exit is more reliable.

Conversion of Parallel Session ValuesThe session class value is stored in two bytes (TQPRSBYT and TQPRSBIT) in the TCQE. The specified classcan be derived from these values. The following table shows a sample of the two bytes for the first 16classes (maximum is 256).

TQPRSBYT TQPRSBIT CLASS

00 80 1

00 40 2

00 20 3

00 10 4

00 08 5

00 04 6

00 02 7

00 01 8

01 80 9

01 40 10

01 20 11

01 10 12

01 08 13

01 04 14

01 02 15

ALLOCATION EXITThe IBM Connect:Direct allocation exit provides an interface to a user-written program. If you supplya user exit in the initialization parameters, IBM Connect:Direct invokes the exit prior to any allocationactivity by the receiving IBM Connect:Direct. Through the exit, you can change information that IBMConnect:Direct uses during the allocation Process. You can examine or modify information such as dataset name (DSN) and type record name or set fields to terminate the copy step prior to allocation.

Sample Allocation ExitsIBM Connect:Direct provides the following sample allocation exits in the $CD.SDGASAMP library.

Exits Description

DGAXADSN This exit documents the path of the data set name and unit that receives data during a COPY.It runs just prior to data set allocation. It is invoked for every COPY step on the receiving endof a transfer.

340 IBM Connect:Direct for z/OS: Documentation

Exits Description

DGAXUNIQ This exit creates a unique z/OS PDS member name, if the data set name specified in the COPYTO statement is found in the PDS directory.

Each request can only specify one member name. The COPY TO statement must specify themember name. The COPY TO statement must also specify SYSOPTS=”UNIQUE=YES”.

The exit only supports copying sequential files to a PDS member.

DGAXALOX This exit enables a Data exit to be invoked for any or every copy performed by IBMConnect:Direct.

DGAXA390 This exit converts UNIT=3390 to UNIT=SYSDA.

DGAXALEX This exit shows how to access the VSAMPL and the TCQSH, and both the source anddestination description in the TCQSH. It shows how to change a value in the Data SetDescription Control Blocks (DGA$DDSR or DGA$SDCR) and set a return code and messageID before return.

Chapter 4. Administration Guide 341

Exits Description

DGAXARCL In a COPY Process, this exit checks if a data set is archived or migrated. If the data set isarchived, the exit requests retrieval and tells the COPY Process to go to the Timer Retry queue(TI RE), from which it is retried based on the ALLOC.WAIT and ALLOC.RETRIES initializationparameters. To ensure that the serially reusable operating system SYSZTIOT resource is freedup for subsequent users and does not cause the IBM Connect:Direct region to hang in await condition, use the DMGALRCL exit and specify ARCH as the value for the ALLOC.CODESinitialization parameter. Change the setting of the INVOKE.ALLOC.EXIT global initializationparameter to BOTH if using this exit. If running with the CA-DMS product, you must modify thesample exit code as described in the comments at the beginning of the sample code. If youuse this exit, add the following DD Statement to the DTF JCL:

//READER DD SYSOUT=(A,INTRDR)

Note: This exit is not necessary to process migrated or archived data sets. IBM Connect:Directprocesses recalled data sets synchronously and the COPY Process remains in the Executionqueue instead of being diverted to the Timer Retry queue and potentially to the Hold queueshould retry limits be exceeded.

In releases prior to Version 4.7, when the DGAXARCL (alias of DMGALRCL) allocation exitattempted to recall a migrated or archived data set offline, the Process went into fail stateand was taken out of the Execution queue and put into the Timer Retry (TI RE) queue. As IBMConnect:Direct waited for the allocation and recall to be performed asynchronously, it wouldretry the Process based on the ALLOC.WAIT and ALLOC.RETRIES initialization parameters.If the Process exceeded the maximum time limit specified for retrying it (number of retriesas specified by the ALLOC.RETRIES initialization parameter multiplied by the amount of timethat IBM Connect:Direct waits between retries as specified by the ALLOC.WAIT initializationparameter), the Process was put into the Hold queue requiring manual intervention.

In Version 4.7 and later, when IBM Connect:Direct executes a COPY Process without theDMGALRCL exit being present, it will use the ARCHRCAL macro synchronously, which meansthat the Process stays in the Execution queue not having to loop between the Execution,Timer, and Hold queues. The Process does not terminate while the recall operation is beingperformed but if the recall is unsuccessful, the COPY step produces a return code indicatingthe unsuccessful data set recall and instructs the user to correct the error and resubmit theProcess.

Although it is not needed for data recall, the DGAXARCL exit will continue to be supportedand invoked prior to any allocation activity if the ALLOCATION.EXIT=DGAXARCL initializationparameter is specified. However, this exit is no longer required to process migrated orarchived data sets.

Caution: If the sample exit is not being used and a migration/recall product is not active,installed, or is temporarily down, the following messages are displayed:

ARC0050A DFSMSHSM IS NOT ACTIVE - START DFSMSHSMARC0051A JOB xxxxxxxx WAITING FOR DFSMSHSM TO RECALL DSN=dsname*73 ARC0055A REPLY 'GO' OR 'CANCEL'

To proceed with the allocation, you must reply. Please refer to IBM documentation regardingthe ARCxxxxA messages. If you reply CANCEL to the ARC0055A message, the Processcompletes with MSGID=SDE021CI. If 21C is in the ALLOC.CODES= list, the Process retries;otherwise, the Process terminates.

DGAXPALL This exit provides %PNUM substitution in a Process.

342 IBM Connect:Direct for z/OS: Documentation

Restrictions and RequirementsObserve the following restrictions and requirements:

• The name of the allocation exit load module is user-defined, but it must not conflict with any other IBMConnect:Direct load module names.

• Because the control blocks provided by IBM Connect:Direct that the exit must access are located instorage requiring 31-bit addressability, you must link-edit the module with AMODE ANY to make itcapable of executing in 31-bit mode.

• To activate the exit, specify ALLOCATION.EXIT=modname in the IBM Connect:Direct initializationparameters file. You must link-edit the allocation exit as re-entrant and place it in a load library that theIBM Connect:Direct DTF can access.

• If an exit is not working, check the setting of the INVOKE.ALLOC.EXIT global initialization parameter,which should be one of the following:

– RECV - Invokes the allocation exit when receiving a file.– SEND - Invokes the allocation exit when sending a file.– BOTH - Invokes the allocation exit both when sending and receiving a file. This is the default setting.

How the Allocation Exit ExecutesThe allocation exit executes in the DTF address space when the following conditions exist:

• The allocation exit is specified in the initialization parameters.• A file is being received, and the Process step that initiated the copy is not in restart mode.

The following figure illustrates the structure of the parameter list for the allocation exit.

The following table is a list of the allocation exit parameters.

Parameter Explanation

R1 Register 1 that contains the address of a standard parameter list upon entry into theuser-written allocation exit

PLIST Stands for standard parameter list

SQCB Security control block

VSAMPL Stands for VSAM parameter list, whose address is the first full word in the PLIST

VSCCBADR Address of the Process step header and is contained in VSAMPL

TCQSH Process step header portion of the Copy control block (each step of a Process generatesa TCQSH)

SDESCR Source data set descriptor portion of the Copy control block

DDESCR Destination data set descriptor portion of the Copy Control Block (a sample of theDDESCR Control Block is included in this section)

The following macros map the control block structures.

Chapter 4. Administration Guide 343

Macro Explanation

DGA$VSMP Macro that defines the VSAMPL control block

DGA$TQSH Macro that defines the TCQSH portion of the Copy control block

DGA$SDCR Macro that defines the SDESCR portion of the Copy control block

DGA$DDSR Macro that defines the DDESCR portion of the Copy control block

How to Calculate Addresses and ValuesUpon entry into the user-written allocation exit, register 1 contains the address of a standard parameterlist. The first entry in the PLIST contains the address of the VSAMPL. The second entry in the PLISTcontains the address of the SQCB, if available. The VSCCBADR field in the VSAMPL contains the addressof the Process step header, TCQSH. The SDESCR and DDESCR following the TCQSH is found by addingdisplacements to the TCQSH address.

• To calculate the location of SDESCR, add the length of TCQSH (TSHCBHLN) to the TCQSH address(VSCCBADR).

• To calculate the location of DDESCR, add the length of SDESCR (S1SVSLNG) to the SDESCR address.

All displacement values in the Copy control block are referenced from the beginning of the TCQSH controlblock.

SDESCR and DDESCR contain both fixed length fields and offsets to variable length fields. The allocationexit modifies any fixed length field in DDESCR.

The fields that are referenced in SDESCR and DDESCR using displacement values are variable in length.Do not modify them with the allocation exit.

The DSN field is created with enough space to hold a 100-character name only if the TSEXPDSN bit is on(set) in the TCQSH. If the TSEXPDSN bit is off in the TCQSH, then the Copy control block does not containthe room to expand the DSN. This lack of expansion room means that this copy originated from a IBMConnect:Direct node that did not build the copy control block with an expandable DSN field.

You can find the DSN field by adding D1DDSN to the address of the TCQSH. The DSN field contains a2-byte length field followed by the DSN. Even though the field can be up to 100 bytes long, the 2-bytelength field contains the actual length of the DSN. If you change the length of the DSN, you must modifythe 2-byte length field accordingly. The other variable length fields are created with their current valuesand cannot be lengthened. Do not modify the D1DDSN field.

When allocating the destination file, IBM Connect:Direct first uses values from DDESCR, as specified inthe IBM Connect:Direct COPY statement. Any values needed, but not set in DDESCR, are taken from theType record, if one was specified. Any remaining values are taken from the SDESCR portion of the copycontrol block.

Note: If the D1DTYPE field is modified by the allocation exit, the exit must clear fields in the DDESCRportion of the copy control block that overrides the corresponding Type fields from the Type record.

Copy Control Block DefinitionsCopy control block definitions are generated in the allocation exit program by including the macro namefollowed by DSECT=YES, as follows:

• DGA$VSMP DSECT=YES• DGA$TQSH DSECT=YES• DGA$DDSR DSECT=YES• DGA$SDCR DSECT=YES

344 IBM Connect:Direct for z/OS: Documentation

Copy Control Block ModificationsModify only the VSAMPL and DDESCR control blocks. For the VSAMPL control block, you are required tomodify the VSRTNCD and VSMSGID fields as follows:

• Set the VSRTNCD field (and R15) to 0 to allow the Copy step to execute.• Set the VSRTNCD field (and R15) to a nonzero value to fail the Copy step.• Insert a message ID into the VSMSGID field, if the VSRTNCD is set to a nonzero value. Take precaution

to avoid duplicating existing message IDs.• Place the message text corresponding to these message IDs in the IBM Connect:Direct message file.

DDESCR Control Block FormatThe DGA$DDSR member of the $CD.SDGAMAC library lists the DDESCR control block format. You canmodify the control block fields listed in the following table. Do NOT modify any displacement fields listedin the member.

Note: Turning a flag on means setting the bit in the byte where the flag is located to one. Turning a flag offmeans setting the bit in the byte where the flag is located to a zero.

Attention:

Do not modify the fields D1DMEMB, D1DDSN, and D1DVOLN. These fields representdisplacements to their corresponding values. However, after calculating the address of the values(by adding the displacement to the address of the TCQSH) IBM Connect:Direct can change theactual values. At the calculated address, you will find a halfword field representing the length ofthe data that follows. If you change the length of the data, you must also change this halfwordto reflect the new length. If the displacement to one of these fields is 0, do not insert a value ordisplacement. For example, if D1DMEMB=0, no member name was specified and a member namecannot be inserted. Do not set on the D1MEMNAM flag if D1DMEMB=0.

The same applies to D1DDSN. For D1DVOLN, if the displacement is 0, you cannot modify this fieldor turn on the D1DVOLSER flag. Also, you cannot add volume serial numbers to this list. You candelete volume serial numbers from the list or change the volume serial number. If volume serialnumbers are deleted, decrement the length field by 6 for each one deleted. If all volume serialnumbers are deleted, make D1DVOLN=0 and turn off the D1VOLSER bit.

Field Explanation Use Instructions

D1DTYPE entry in the IBMConnect:Direct typedefaults file

N/A

D1BLKSIZ block size To use the block size in the destination data set descriptionportion of the copy control block, set D1BLKSZE flag on. To usethe block size in the Type record, set the D1BLKSZE flag off.

D1DEN tape density To use the tape density indicated in the destination data setportion of the Copy control block, set the D1DENSTY flag on.

D1DSORG data set organization To use this value, set the D1DSORGN flag on. To use the valueindicated in the type record, set the D1DSORGN flag off.

D1LRECL logical record length To use this value, set the D1LRECLN flag on. To use the valueindicated in the type record, set the D1LRECLN flag off.

D1RECFM record format To use this value, set the D1RECFMT flag on. To use the valueindicated in the type record, set the D1RECFMT flag off.

D1RKP relative key position To use this value, set the D1RKYP flag on.

D1TRTCH 7-track recordingmode

To use this value, set the D1TRKTCH flag on.

Chapter 4. Administration Guide 345

Field Explanation Use Instructions

D1LABTYP label type To use this value, set the D1LABEL flag on.

D1RETPD retention period To use this value, set the D1RETPRD flag on. To use the valueindicated in the D1EXPDT field, set the D1RETPRD flag off.

D1EXPDT retention period To use this value, set the D1EXPDTE flag on.

D1PRILOC primary allocationamount

All of the following bits must be set off to use the spaceallocation values specified in the type record: D1TRK, D1CYL,D1BLK.

D1SECLOC secondary allocationamount

To use this value, set the D1SECALL flag on. Set all of thefollowing bits to off to use the space allocation values specifiedin the type record: D1TRK, D1CYL, D1BLK.

D1DIRBLK number of directoryblocks

To use this value, set the D1DIRBLK flag on. Set all of thefollowing bits to off to use the space allocation values specifiedin the type record: D1TRK, D1CYL, D1BLK.

D1UNIT unit type or groupname

To use this value, set the D1GRPTYP flag on. To use the valueindicated in the type record, set the D1GRPTYP off. Set all of thefollowing bits to off to use the UNIT value specified in the typerecord: D1UNCNT, D1P, D1DEFER, D1GRPTYP.

D1VOLSEQ volume sequencenumber

To use this value, set the D1VOLSQ flag on.

D1VOLCT volume count To use this value, set the D1VOLCNT flag on.

D1PASSWD data set password To use this value, set the D1PWD flag on.

D1DMEMB displacement to themember name field†

N/A

D1DDSN displacement to thedata set name field†

N/A

D1DVOLN displacement tothe volume serialnumber†

N/A

† See the Caution that precedes this table.

I/O ExitThe IBM Connect:Direct I/O exit provides an interface to user-written programs, allowing them to readand write data to or from a file whose organization IBM Connect:Direct does not support or wouldimproperly access. Examples are internal format access to CA-LIBRARIAN or CA-PANVALET files.

Note: Checkpoint/restart is not supported for I/O exits.

If you plan to use an I/O exit, consider the following items:

• All I/O exits must be re-entrant, AMODE 31, follow IBM Assembler linkage standards, and reside inan authorized load library on the node where they are referenced. These exits must not alter any IBMConnect:Direct control block fields (except in the EXTCB as indicated in I/O Exit Access to ControlBlocks). If other IBM Connect:Direct control block fields are altered, the results are unpredictable.

• If an ALLOCATION EXIT is specified, it is not given control when the COPY statement contains anIOEXIT keyword.

• Add any message IDs specified by an I/O exit to the IBM Connect:Direct Message file. See CustomMessages in the Message Library for instructions.

346 IBM Connect:Direct for z/OS: Documentation

• Return from the I/O exit in the AMODE under which it was called. For example, if the I/O exit is calledin 31-bit mode, the return must be in that mode. Therefore, if IBM Connect:Direct is running on an XAsystem, return from an I/O exit through a Branch Set Mode (BSM) instruction rather than a Branch (BR)instruction.

After you write the I/O exit to satisfy your specific data set requirements, implement it by specifyingthe exit name on the IOEXIT keyword on a COPY statement, or on the INSERT and UPDATE TYPE filecommands.

Sample I/O ExitThe following sample I/O exit is provided in $CD.SDGASAMP library.

Exits Description

DGAXIOX1 This exit processes external data sets whose formats are not supported. It allocates,opens, reads, closes and deallocates a sequential data set.

Note: The I/O exit, DGADSIOX, enables you to copy SMS-compressed data without decompressing andalso provides support for copying wildcard-named files. However, you cannot modify this I/O exit. Formore information, see Utility Programs in IBM Connect:Direct for z/OS User Guide.

Specifying the I/O Exit in the COPY StatementInclude the IOEXIT keyword on the COPY statement to indicate that an I/O exit is used. The IOEXITformat on the COPY statement follows.

Statement Parameters

COPY FROM (IOEXIT= exitname |(exitname[,parameter,...]))

TO (IOEXIT= exitname |(exitname[,parameter,...]))

The subparameters of the IOEXIT parameter of the COPY statement are:

Parameter Description

exitname Name of the user-written program to receive control for I/O-related requests.

parameter Parameter or list of parameters passed to the exit. Their format is the same formatas those parameters which you can specify on the RUN TASK statement.

The IOEXIT keyword is valid in either the FROM or TO areas of the COPY statement. This capabilityenables you to specify a different user-written I/O exit on each side as illustrated in following example.

COPY FROM (PNODE, - IOEXIT=(INEXT01,C'DB0A05',X'0E')) - TO (SNODE, - IOEXIT=OUEXT03)

If you specify an exit, it can ignore the values of other parameters in the COPY statement (the DCBinformation). This issue is beyond the control of IBM Connect:Direct. For information on using the I/O exitthrough the COPY statement, see the Connect:Direct Process Language help.

Chapter 4. Administration Guide 347

Specify the I/O Exit in the TYPE FileAnother method of specifying an I/O exit is to include the IOEXIT keyword on the INSERT and UPDATEType file commands. The format is the same as the COPY statement. If you specify an IOEXIT parameteron the COPY statement, it overrides any IOEXIT in the Type file entry. The type defaults record mustreside on the copy side (source or destination) that references it.

I/O Exit Access to Control BlocksOn entry to the exit, register 1 (R1) contains the address of the pointer to the EXTCB (Exit Control Block).The parameter list addresses point to a 2-byte length followed by the value.

All parameter lists end with the high order bit on in the last address in the list. The macro DGA$XTCBgenerates the EXTCB. DGA$XTCB is supplied in the $CD.SDGAMAC library.

I/O Exit RequestsThe I/O exit is called with IBM Connect:Direct requests that are found in EXTOPER, which is a field inEXTCB. The following are the requests that the input and output I/O exits receive:BEGIN Request

IBM Connect:Direct makes a BEGIN request to an I/O exit when it begins communication with theexit. The BEGIN is when the exit must allocate work areas in preparation for future requests and is thefirst request that an I/O exit receives.

OPEN Request

IBM Connect:Direct makes an OPEN request to an I/O exit when the exit allocates and opens the file.EXTDIR contains either S (Send) or R (Received) to indicate whether the file is to be read or written.The I/O exit uses EXTWKARA to anchor any storage obtained and set EXTMAXLN to the maximumrecord length.

INFO Request

IBM Connect:Direct makes an INFO request to an I/O exit when it wants the exit to retrieve the fileattributes and place them into the INFO area (mapped by the DMINFO macro) which is pointed to byEXTVSWRK. These data set attributes are required by IBM Connect:Direct.

Set the following fields in the INFO control block. The values listed are an example of those neededfor a sequential data set.

INBLKSZ = F’80’ block sizeINLRECL = F’80’ record sizeINTYPE = CL4’PS’ data set organizationINRECFM = CL4’ ’ blankINUNIT = CL8’ ’ blankINBLKS = F’0’ nullsINUSEBLK = F’0’ nullsINBLKTRK = F’0’ nullsINTRKCYL = F’0’ nullsIN2NDRY = 8C’0’ character zerosINLOCTYP = CL3’ ’ blanks

GET Request

IBM Connect:Direct makes a GET request to an I/O exit when it wants a record/block read into thebuffer. EXTINLNG is set to the length of the data. EXTINARA points to the record obtained.

The exit must indicate normal END-OF-DATA condition to IBM Connect:Direct by returning a valueof EXTRCEOD in EXTRTNCD. You may indicate other conditions by providing other values in thepreviously mentioned fields. The EXTRCEOD in EXTRTNCD values enable IBM Connect:Direct to issuemessages that are added to the IBM Connect:Direct message file.

The IOEXIT must allocate a buffer for the input record/block. To determine if IBM Connect:Directis expecting a record or block, the IOEXIT must examine the source LRECL, BLKSIZE, RECFM anddestination LRECL, BLKSIZE, RECFM fields in the EXIT control block. If the source and destination

348 IBM Connect:Direct for z/OS: Documentation

data set attributes match, then IBM Connect:Direct is expecting a physical block from the IOEXIT,otherwise a logical record is expected.

ADD Request

IBM Connect:Direct makes an ADD request to an I/O exit when it wants a record/block to be inserted.EXTOTLNG is set to the length of the data. EXTOTARA points to the new record/block.

IBM Connect:Direct always sends RECFM=VS and RECFM=VBS files in segments rather than records.If EXTSPAN is set to Y, the data pointed to by EXTOTARA has two segments. Refer to the IBM libraryof manuals for information on the format of spanned records. The buffer referenced by EXTOTARAcontains a physical block if the source and destination data set attributes match; otherwise, itcontains a logical record.

CLOSE Request

IBM Connect:Direct makes a CLOSE request to an I/O exit when the file closes. Errors returned by theexit on this request are ignored. The EXTABN flag is activated if the CLOSE request is due to abnormaltermination.

END Request

IBM Connect:Direct makes the END request to an I/O exit to end communication with the exit. Theexit releases any work areas allocated when it received the BEGIN request. This request is the lastrequest an I/O exit receives.

Normal Input Calling SequenceThe following figure illustrates the normal call sequence for an I/O exit used for input.

Chapter 4. Administration Guide 349

Normal Output Calling SequenceThe following figure illustrates the normal calling sequence of an I/O exit used for output.

Data ExitThe Data exit functions similarly to the I/O exit; however, the Data exit does not require the I/Omanagement that the I/O exit requires. The Data exit provides an interface to user-written programs,allowing them to add, delete, change, or insert records.

The Data exit is called through the DATAEXIT parameter in the COPY statement or a keyword parametersupplied within the SYSOPTS string.

Note: Checkpoint/restart is supported for Data exits.

DATAEXIT FormatThe DATAEXIT format in the COPY statement follows.

Statement Parameters

COPY FROM (DATAEXIT= exitname|(exitname[,parameter,...]))

TO (DATAEXIT= exitname|(exitname[,parameter,...]))

The DATAEXIT subparameters are:

Parameter Description

exitname The name of the user-written program that receives control for data requests.

parameter A parameter or list of parameters passed to the exit. See the RUN TASK statement.

350 IBM Connect:Direct for z/OS: Documentation

The following example shows the DATAEXIT parameter in the COPY statement.

COPY01 COPY FROM (PNODE DSN=GJONES1.FROM.DSN - DATAEXIT=(CD$DGAXDXX01,CL6'WEEKLY') - ) - TO (SNODE DSN=GJONES1.TO.DSN - DCB=(DSORG=PS,LRECL=80,BLKSIZE=32000) - DISP=(NEW,DELETE,DELETE) - SPACE=(CYL,(1,0,0)) - DATAEXIT=(CDDATAEX,CL44'GJONES1.TO.DSN') - UNIT=SYSDA)

The following example shows DATAEXIT used as a SYSOPTS parameter.

COPY01 COPY FROM (PNODE DSN=GJONES1.FROM.DSN - SYSOPTS="DATAEXIT=(CD$DXX01,CL6'WEEKLY')" - ) - TO (SNODE DSN=GJONES1.TO.DSN - DCB=(DSORG=PS,LRECL=80,BLKSIZE=32000) - DISP=(NEW,DELETE,DELETE) - SPACE=(CYL,(1,0,0)) - DATAEXIT=(CDDATAEX,CL44'GJONES1.TO.DSN') - UNIT=SYSDA)

Sample Data ExitsThe following DATAEXIT samples are provided in $CD.SDGASAMP library.

Exits Description

DGAXDXX1 This sample Data exit examines or changes records from a COPY Process based on inputdata. You can use it to insert, replace, or delete records.

DGAXDXX2 This sample Data exit converts data from EBCDIC to ASCII if sending a file, or fromASCII to EBCDIC if receiving a file.

If you plan to use a Data exit, consider the following items:

• All Data exits must be re-entrant, follow IBM Assembler linkage standards, and reside in an authorizedload library on the node where they are referenced. These exits must not alter any IBM Connect:Directcontrol block fields (except in the EXTCB as indicated in Data Exit Access to Control Blocks). If otherIBM Connect:Direct control block fields are altered, the results are unpredictable.

• Add any message IDs specified by a Data exit to the IBM Connect:Direct Message file. See CustomMessages in the Message Library for instructions.

• Return from the Data exit in the AMODE under which it was called. For example, if the Data exit is calledin 31-bit mode, the return must be in that mode. Return from a Data exit through a Branch Set Mode(BSM) instruction rather than a Branch (BR) instruction.

After you write the Data exit to satisfy your specific data set requirements, implement it by specifying theexit name on the DATAEXIT keyword on a COPY statement.

Data Exit Access to Control BlocksOn entry to the exit, register 1 (R1) contains the address of the pointer to an 8-byte parameter list. Theaddress consists of:

• +Pointer to a 4K storage area that is constant throughout the Data exit step. This area is mapped usingthe DXPARM label within the DGA$VSMP macro in $CD.SDGAMAC library.

• +Pointer to the EXTCB (mapped by the DGA$XTCB macro in $CD.SDGAMAC library).

If parameters are passed to the Data exit, the EXTPARML field in EXTCB points to a standard z/OSparameter list, pointing to the parameters (half-word length followed by the parameter itself) passed to

Chapter 4. Administration Guide 351

the Data exit. If no parameters are passed to the Data exit, EXTPARML points to a full-word field of binaryzeros.

For example, if two parameters are passed to the Data exit, EXTPARML in EXTCB points to two full wordpointers (the second pointer will have the high order bit on indicating the last parameter). Each of thepointers point to a half-word length followed by the parameter value as follows.

As another example, assume the following Data exit call.

DATAEXIT= = (MYTASK,CL44'DATA.BASE.PI' - F'0010',XL8'FFAB')

Based on this call, the information passed to the exit program is displayed as follows.

To adhere to common linkage standards, IBM Connect:Direct sets the list termination bit (X'80') in theParameter 3 address.

Data Exit RequestsThe Data exit is called with IBM Connect:Direct requests that are found in EXTOPER, which is a field inEXTCB. Input and output Data exits receive the following requests:

Note: Upon return from the Data exit, any nonzero value in EXTRTNCD causes the Process to terminatewith RC=8 and an SCPA049I message.

BEGIN Request

IBM Connect:Direct makes a BEGIN request to a Data exit when it begins communication with theexit. The exit is passed to a 4K work area that remains constant throughout this step in the Process. Ifadditional storage is required, it can be obtained and anchored in the 4K work area.

OPEN Request

IBM Connect:Direct makes an OPEN request to a Data exit after the file is open and before the firstdata record is read.

GET Request

IBM Connect:Direct makes a GET request to a Data exit before adding the record to the buffer fortransmission to the remote. At this point, the Data exit instructs IBM Connect:Direct to pass the recordunchanged, change the record, delete the record, or insert records by setting the appropriate flag bitin EXTEAI in the EXTCB.

Flag bit setting Action

All bits off Pass the record unchanged

352 IBM Connect:Direct for z/OS: Documentation

Flag bit setting Action

EXTEAIRR Replace the record. Update EXTINARA to point to the new record and EXTINLNGwith the new record length.

EXTEAIRD Delete the record.

EXTEAIRI Insert a new record. (The next call present the original record again and you cancontinue to insert records.) If pointing to a new record, set EXTEAIRR. UpdateEXTINARA to point to the new record and EXTINLNG with the new record length.

If records are inserted in place of an original record, the original record deletethe original record after the inserted records are passed.

PUT Request

IBM Connect:Direct makes a PUT request to the Data exit before sending the record to the z/OS I/Osystem (IOS). At this point, the Data exit instructs IBM Connect:Direct to pass the record unchanged,change the record, delete the record, or insert records by setting the appropriate flag bit in EXTEAI inthe EXTCB.

Flag bit setting Action

All bits off Pass the record unchanged.

EXTEAIRR Replace the record. Update EXTOTARA to point to the new record andEXTOTLNG with the new record length.

EXTEAIRD Delete the record.

EXTEAIRI Insert a new record. (The next call presents the original record again and youcan continue to insert records.) If pointing to a new record, set EXTEAIRR.Update EXTOTARA to point to the new record and EXTOTLNG with the newrecord length.

If records are inserted in place of an original record, delete the originalrecord after the inserted records are passed.

CLOSE Request

IBM Connect:Direct makes a CLOSE request to a Data exit when the file is to close.

END Request

IBM Connect:Direct makes the END request to a Data exit to end communication with the exit. Theexit releases any work areas allocated when it received the BEGIN request. This request is the lastrequest a Data exit receives.

Chapter 4. Administration Guide 353

Normal Input Calling SequenceThe following figure illustrates the normal call sequence for a Data exit used for input.

354 IBM Connect:Direct for z/OS: Documentation

Normal Output Calling SequenceThe following figure illustrates the normal calling sequence of a Data exit used for output.

WLM ExitIf you code the initialization parameter CDPLEX.WLM.GOAL=YES, IBM Connect:Direct invokes theIWMWSYSQ macro when necessary to query the status of systems in a sysplex. IBM Connect:Direct usesthe information returned from the query to determine which system can best handle additional Processwork. If you want to override the decision IBM Connect:Direct makes, you can specify a different choicewith the WLM exit.

Activate the WLM exit by coding the following initialization parameter:

CDPLEX.WLM.GOAL=(YES,exitname)

Where exitname is the name of the WLM exit.

Exit Calling ConventionThree parameters are passed to the WLM exit by IBM Connect:Direct.

• The first parameter points to the WLM System Capacity Information Area (IWMWSYSI).• The second parameter points to a list of system names that were found in goal mode by the WLM query.

At least one of these systems must have a IBM Connect:Direct/Plex server active.

Chapter 4. Administration Guide 355

• The third parameter is used for the WLM exit return code. The following describes the possible returncodes:

Return Code Description

0 This indicates all systems are considered equal and no choice is made.

Negative value This indicates that no systems are selected.

1-n This indicates the chosen system by an index into the eligible system list.

The following figure depicts the information passed to the WLM exit:

Sample WLM ExitThe following sample WLM exit is provided in $CD.SDGASAMP library.

Exit Description

DGAXWLMX This exit analyzes the IWMWSYSI info returned from an IBM Workload Managerquery and indicates the least busy system with a return code.

Tapemount ExitThe IBM Connect:Direct tapemount exit provides an interface to StorageTek Tape Silo Software. If yousupply a user exit in the initialization parameters, IBM Connect:Direct invokes the exit prior to a tapeVOLSER mount request. Using the return codes resulting from this exit, you can obtain the status of thevolumes needed to satisfy the mount request prior to the Tape premount message being displayed. (TheTAPE.PREMOUNT = YES | NO | LIST parameter determines if a tape premount message will be displayedor not.) If any volume is not available for the Silo to process, the tape mount request is automaticallycancelled and an exit return code of 8 or higher is issued to indicate that the Process is being held in error.

Exit ReturnCode

Explanation

0 The Tape Premount message will be suppressed.

4 The Tape Premount message will be issued.

8 or higher The Mount Process will be “Held in Error.”

356 IBM Connect:Direct for z/OS: Documentation

Sample Tapemount ExitIBM Connect:Direct provides the following sample tapemount exit in the $CD.SDGASAMP.

Exits Description

DGAXTAPX This exit interfaces with the StorageTek Tape Silo via SLA macro calls. You can modifythis member to work with other vendors' Tape Silo products.

You can use the sample JCL, DGAXATAP located in $CD.SDGASAMP, to assemble and link-edit the exit.

Observe the following restrictions and requirements:

• The name of the tapemount exit load module is user-defined, but it must not conflict with any other IBMConnect:Direct load module names.

• Because the control blocks provided by IBM Connect:Direct that the exit must access are located instorage requiring 31-bit addressability, you must link-edit the module with AMODE ANY to make itcapable of executing in 31-bit mode.

• To activate the exit, specify “TAPEMOUNT.EXIT = modname” on page 499 in the IBM Connect:Directinitialization parameters file. You must link-edit the tapemount exit as re-entrant and place in a loadlibrary that the IBM Connect:Direct DTF can access.

The TAPEMOUNT.EXIT parameters are:

Parameter Explanation

NOVOLS Used to define the return code if all volumes for a tape mount request are not in the silo.Code with a value of 00, 04, or 08.

VIRTVOL Tell the exit how to treat a virtual tape VOLSER. Code with a value of OKAY or ERROR.

TEST Used to supply diagnostic test messages to a DD statement named to match theassembled program name. Code with a value of YES or NO.

UID Optional local identifier which appears in NDMLOG output with the PTF maintenancelisting.

Process Exit for Testing (DGAXPRCT)The Process Exit for Testing (DGAXPRCT) allows you to perform the following functions:

• Test new applications and customer connections• Prevent future production work from executing until testing is complete after you have terminated all

active production work using the Flush Process command• Resume regular production work after testing• Control individual file transfers by application• Enable and disable individual nodes and applications

While testing is being conducted, only Processes, particularly file transfers, involved with the testingactivity are executed. No production data is transferred to applications being tested while at the sametime no test data is transferred to production applications.

Flow of the DGAXPRCT ExitFirst you tell DGAXPRCT which IBM Connect:Direct Processes to run and not run by storing yourpreferences as text records in a parameter table stored as a Partitioned Data Set (PDS) member. Youcan specify the following criteria for DGAXPRCT to use to find matches for one or more Processes toinclude (using the “I” command code) or exclude (“X” command code) from execution:

• A partial or full Process name• A partial or full remote node name

Chapter 4. Administration Guide 357

• A partial or full IBM Connect:Direct submitter ID and submitter node combination• A combination of Process name, remote node name and submitter ID/submitter node, all of which must

match

In addition to telling IBM Connect:Direct which Processes to run, you tell the system what to do withthe Processes which do not get executed. You can specify the following dispositions for Processes notpermitted to run:

• Place the Process in the Hold queue• Place the Processes in the Timer queue for session retry• Flush the Processes from the queue

To see different ways the DGAXPRCT exit can be used, see Sample Test Scenarios.

The DGAXPRCT exit is invoked by the Stage 2 Security exit before the security checks for a IBMConnect:Direct Process about to be executed have been performed. For information on how the Stage2 Security exit is processed, see Stage 2 Security Exit.

The Process Exit for Testing reads and validates the DGAXPRCT parameter table each time it is invokedwhen a Process is executed. If a syntax or other error occurs, IBM Connect:Direct places the Processes inthe hold queue and returns a non-zero return code and error message ID. If the table is valid, DGAXPRCTscans the parameter table looking for a pattern that matches the Process that is about to be executed.If a match is found, the Process is permitted to execute if the "I" (Include) command code is in effect. Ifcommand code "X" (Exclude) is in effect, the process is not permitted to execute. If a match is not foundin the table, DGAXPRCT performs the opposite processing from the case where a match is found, that is, ifno match is found and command code "I" is in effect, the Process is not permitted to execute, whereas ifcommand code "X" is in effect, the Process is permitted to execute.

Note: To reverse an action taken, use the “R” (Reverse) command code. If a match is found in an Includelist and the “R” command code is also in effect, the Process is excluded. Conversely, if a match is found inan Exclude list and the “R” command code is also in effect, the Process is included.

If a Process is not to be permitted to execute, DGAXPRCT uses the disposition specified in the DGAXPRCTparameter table to either hold, retry, or flush the Process after the DGAXPRCT exit returns with a non-zeroreturn code.

Note: For Processes initiated on remote nodes, the DGAXPRCT exit functions in the same manner as itdoes for Processes submitted on the local IBM Connect:Direct node. The DGAXPRCT Parameter Tableis searched for a matching entry and the remotely initiated Process is either permitted to execute orexcluded from execution. However, because the local node is the SNODE for this type of transfer, itcannot enforce the Process disposition setting in the DGAXPRCT Parameter Table. The remote PNODEdetermines how the Process is handled. Typically, the remote node places the Process in the Hold queuewith a status of "HE" (Held in Error) if SECURITY.NOTIFY=HOLD is specified or the DGAXPRCT exit issupported on the remote node. If the remote node does not support SECURITY.NOTIFY=HOLD or theDGAXPRCT exit, the Process terminates.

When both the PNODE and the SNODE invoke the DGAXPRCT exit and the SNODE excludes a Processfrom executing, the PNODE automatically places the Process in the Timer queue for session retryregardless of the disposition setting in the DGAXPRCT Parameter Table on the PNODE. This processingis necessary because of technicalities in the handling of an SNODE error at the point in the IBMConnect:Direct protocol.

Setting Up and Using the DGAXPRCT ExitTo set up and use the DGAXPRCT Exit, complete the following steps. This roadmap is a high-level view ofthe procedure. For more information on each step, go to the section referenced in that step.

1. Review Overview of Security Options for information on security including interfaces to other securitysoftware and sample exits.

2. Assemble the DGAXPRCT member in $CD.SDGASAMP library.

358 IBM Connect:Direct for z/OS: Documentation

3. To activate the stage 2 security exit which invokes the DGAXPRCT exit, specifySECURITY.EXIT=modname in the IBM Connect:Direct initialization parameters file (seeSECURITY.EXIT = (module name, DATASET | ALL, PSTKT) | OFF SECURITY = (module name, DATASET| ALL, PSTKT) | OFF for information). You can modify the sample security exit, DGAMGSAF, provided inthe $CD.SDGASAMP library, to use as the base code for your stage 2 security exit.

4. Change the PROCEXIT parameter in the DGASECUR macro to DGAXPRCT. See Enable the DGAXPRCXTExit.

5. Create a PDS member to store parameters specifying how you want to implement the DGAXPRCT Exit,that is, preferences such as which Processes to run and not run and which queue to place unexecutedProcesses. See Edit the DGAXPRXCT Parameter Table.

6. Add DD statements to allocate the DGAXPRCT table and log information. See Include Required DDStatements.

7. Reassemble and link-edit the Stage 2 exit source code. Because the control blocks provided by IBMConnect:Direct that the exit must access are located in storage requiring 31-bit addressability, youmust link-edit the module with AMODE 31 to make it capable of executing in 31-bit mode. You mustalso link-edit the stage 2 security exit as re-entrant and place in an authorized library that the IBMConnect:Direct DTF can access.

8. Submit the startup jobstream to start IBM Connect:Direct.

Note: It is not necessary to restart IBM Connect:Direct when you modify the DGAXPRCT parametertable. The new settings are automatically in effect the next time a Process begins executing andinvokes the DGAXPRCT exit, which reads the new values in the table. See Reusing the DGAXPRCT Exitfor more information.

Enable the DGAXPRCXT ExitThe Stage 2 Security Exit executes the DGAXPRCT exit before it performs the necessary securitychecks for a IBM Connect:Direct Process about to be executed. To enable the Security Exit to invokethe DGAXPRCT exit, you must change the PROCEXIT parameter in the DGASECUR macro from NO toDGAXPRCT, and reassemble the exit. See DGASECUR Parameters for more information on this and allparameters in the DGASECUR macro.

Include Required DD StatementsMake sure your startup JCL includes the following DD statements:

//NDMPXTBL DD DSN=$CDPREF..PRCXTLIB(&NDMPXMEM),DISP=SHR//USRINFO DD SYSOUT=*

The first DD statement allocates the parameter table PDS member while the second DD statementallocates a SYSOUT data set to which user-defined information from User Exits, such as error messagesfor parameter records incorrectly formatted and matching entries for Processes which run, is logged.

The CONNECTX JCL startup member contains these DD statements. For more information on the startupJCL members, see DD Statements in Startup JCL.

Edit the DGAXPRXCT Parameter TableYou can use the ISPF text editor to create the DGAXPRXCT Parameter Table which defines which IBMConnect:Direct Processes can and cannot run. This table is stored as a Partitioned Dataset (PDS) member.

You must preallocate the data set with the following attributes:

DSORG=POLRECL=80RECFM=FBBLKSIZE=multiple of 80

Each table entry or record consists of a single-character command code in column one. Most commandcodes have a parameter which begins in column two and varies according to the command code function.

Chapter 4. Administration Guide 359

Note: The order of the entries in the table is important; the first match stops the table scan and the actionrequested is taken (allow the process to execute, flush the process, etc.).

CommandCode

Description Subparameters/Examples

* Comment line. * Only run the following processes.

E Enables DGAXPRCT. This command code must bethe first non-comment entry in the table.

The second column in this entry mustcontain one of the following values whichindicates the disposition of a process if it isnot allowed to run.

H – Places the Process in the Hold queuewith a status of HE (Held in Error)

R – Places the Process in the Timer queuein session retry until number of retries isexceeded. Once this number is exceeded,the Process is placed in the Hold queue witha status of RH (Restart Hold).

F – Flushes the process from the queue

D Disallows DGAXPRCT execution and fails Processexecution with a non-zero (error) return code andmessage NPRX003E.

You can also leave the disposition code incolumn two to make it easier to change from"E" to "D" and vice versa without having tochange column two to a blank for commandcode “D.”

P Matches Processes based on a full or partialProcess name. Supports the wild card trailingasterisk (*). Can be used to enable or disableProcess execution for a particular applicationby using naming conventions to match anapplication.

In addition, remote node and/orsubmitter@submitter-node can be specified tofurther qualify the match.

The combined format is:

Pprocnam[,remote-node[,submitter@submitter-node]]

PCOPY – Matches a single Process

PEOM* – Matches all Processes beginningwith “EOM” for the End of Month Processingapplication

P* – Matches all Processes\

PCOPY,RNODE,SUE@NODE1 – MatchesProcess COPY that was submitted by SUE onNODE1 and whose remote node is RNODE.

PCOPY,,SUE@NODE1 – Matches ProcessCOPY that was submitted by SUE on NODE1.

PCOPY,RNODE – Matches Process COPYwhose remote node is RNODE.

P*,*,SUE@NODE1 – Matches all Processessubmitted by SUE on NODE1.

R Reverses the action to be taken on a match.

If the match is found in an include list, theProcess is excluded.

If the match is found in an exclude list, theProcess is included.

The combined format is:

Rprocnam[,remote-node[,submitter@submitter-node]]

The syntax is the same as for the "P"command code.

In this example, all Processes whose remotenode begins with RNODE are excluded fromexecution except those whose remote nodeis RNODE3.

XR*,RNODE3NRNODE*L

360 IBM Connect:Direct for z/OS: Documentation

CommandCode

Description Subparameters/Examples

N Matches Processes based on a full or partialremote node name. Supports the wild card trailingasterisk (*).

NCD.NODE1 – Matches a single remote nodename

NCD.NODEA* – Matches all remote nodenames beginning with "CD.NODEA"

N* – Matches all remote node names

Note: P*,CDNODE1 is equivalent toNCDNODE1 and can be specified asR*,CDNODE1 to reverse the action.

S Matches Processes based on a full or wild cardIBM Connect:Direct submitter ID and a full orpartial submitter node combination. The format is<id>@<node>.

SACTQ0ACD@TPM002 – Matches a specificsubmitter ID and node combination.

S*@TPM002 – Matches all submitter IDsfrom node TPM002

SACTQ0ACD@* – Matches submitter IDACTQ0ACD from all nodes

SACTQ0ACD@TPM* - Matches submitter IDACTQ0ACD from all nodes beginning with"TPM"

S*@* – Matches all submitter IDs fromany node. This is another way to match allProcesses.

Note: P*,*,SUE@NODE1 is equivalent toSSUE@NODE and can be specified asR*,*,SUE@NODE1 to reverse the action.

I Includes Processes for execution that match thepatterns in the table which follow this commandcode. Either “I” or “X” must be the second non-comment entry in the table. Processes which donot match a pattern in the table are not executed.

Note: To choose which command code to useto select Processes, determine which group issmaller and use the corresponding commandCode. For example, if the number of Processesto be executed is smaller than the number ofProcesses to exclude from execution, specify “I”as the command code and add patterns to matchthat group of Processes.

ERINCD.BOSTON

Includes for execution only those Processeswhose remote node is CD.BOSTON.Excluded Processes are placed in the Timerqueue in session retry

X Excludes from execution those Processes thatmatch the patterns in the table which followthis command code. Either “X” or “I” must bethe second non-comment entry in the table.Processes which do not match a pattern in thetable are executed.

EHXSDALLASOPS@*

Excludes Processes for execution submittedby DALLASOPS from any node

L Last entry in table.

Chapter 4. Administration Guide 361

Sample Test ScenariosThe following examples show different applications of the DGAXPRCT exit using DGAXPRCT ParameterTables to define which IBM Connect:Direct Processes to run and not run.

Specify Which Processes RunIn this example, IBM Connect:Direct executes all Processes that start with ACH or are named DITEST01or DITEST02. All other Processes are placed in the Hold queue.

* Enable processing. Only permit processes matching one of the patterns* to execute. Hold processes that don't execute.EHIPACH*PDITEST01PDITEST02L

Specify Which Processes to ExcludeIn this example, IBM Connect:Direct does not execute any Process that starts with ACH or is namedDITEST01 or DITEST02. All other Processes are executed.

* Exclude matching processes. Permit all others to execute.EHXPACH*PDITEST01PDITEST02L

Permit Process Execution by Remote Node and Submitter User ID/NodeIn this example, IBM Connect:Direct executes all Processes that match one of the following criteria:

• The remote node name is DI.NODE1• A remote node whose name starts with DI0017• Any IBM Connect:Direct submitter ID from node DI0049• The specific IBM Connect:Direct submitter ID ACHAPP from any node

All Processes not matching one of the above criteria are flushed from the queue.

* Only permit matching processes to execute. Flush those that do not.EFINDI.NODE1NDI0017*S*@DI0049SACHAPP@*L

Combine Matching Criteria for a More Specific MatchIn this example, IBM Connect:Direct executes all Processes that match one or more of the followingcriteria:

• Processes that begin with XYZ• Processes that begin with ABC whose remote node is NODE1

All Processes not matching one of the above criteria are flushed from the queue.

362 IBM Connect:Direct for z/OS: Documentation

* Only permit matching processes to execute. Flush those that do not.EFIPXYZ*PABC*,NODE1L

Use the "R" (Reverse) Matching CriteriaIn this example, IBM Connect:Direct performs the following actions:

• Executes all Processes that begin with XYZ• Executes all Processes that begin with ABC whose remote node is NODE1• Excludes all Processes that begin with ABC and whose remote node is NODE1 when submitted by

JOE@NODE2 from execution

All other Processes are flushed from the queue.

* Only permit matching processes to execute. Flush those that do not.EFIPXYZ*RABC*,NODE1,JOE@NODE2PABC*,NODE1L

Note: When using the "R" (Reverse) matching criteria, always specify the most specific matching criterionfirst and the most generic matching criterion last.

Stop the DGAXPRCT ExitIn this example, the DGAXPRCT Exit will exclude Processes from being executed, and display a non-zeroreturn code signifying an error along with message ID NPRX003E . The remainder of the table is ignored(including the “F” code to flush Processes from the queue) and all Processes are placed in the Holdqueue.

To resume testing and use the DGAXPRCT exit again, change the "D" command code to an "E."

* Execute no processes at all. Put them in the hold queue and return.DFIPACH*PDITEST01PDITEST02L

Reusing the DGAXPRCT ExitTo facilitate the use of different testing scenarios, you can maintain multiple members in the DGAXPRCTParameter Table PDS. To reuse the basic DGAXPRCT Parameter table but modify it to change theProcesses which run and do not run, follow this procedure. It is not necessary to restart IBMConnect:Direct; the next time a Process begins executing, the new settings will be in effect when theDGAXPRCT exit reads the table.

CAUTION: To control the execution of the DGAXPRCT exit, make sure that only authorizedoperators can modify the DGAXPRCT Parameter Table PDS member using your security system.

1. Open the DGAXPRCT Parameter Table using the ISPF text editor.2. Delete the current contents of the table member.3. Copy another member for the next testing scenario you want to use and modify it as needed.

Chapter 4. Administration Guide 363

4. Save the DGAXPRCT Parameter Table PDS member.

The next time the DGAXPRCT exit is invoked when a Process begins executing, the DGAXPRCT exituses this updated table.

DGAXPRCT OutputThis topic contains example JOBLOG and USRINFO data set output resulting from the execution of theDGAXPRCT exit.

Example JOBLOG OutputThis example shows JOBLOG output when the DGAXPRCT exit is executing.

SVTM055I SESSION (001) ESTABLISHED WITH SNODE=WWW_TCPNPRX000I ### Permitted: TSTRUN (00000007) SNODE=WWW_TCPSVTM036I PROCESS STARTED TSTRUN ( 7) SNODE=WWW_TCPIGD103I SMS ALLOCATED TO DDNAME NDM00027SVTM052I CO01 COPY TSTRUN ( 7) SNODE=WWW_TCPSVTM052I COMPLETED 00000000/SCPA000ISVTM052I FROM /u/output/testfile7SVTM052I TO DALLAS.O.TESTFILE.BENCH.M50SVTM052I COMPLETED 00000000/SCPA000ISVTM037I PROCESS ENDED TSTRUN ( 7) SNODE=WWW_TCPSVTM056I SESSION (001) TERMINATED WITH SNODE=WWW_TCPSVTM055I SESSION (001) ESTABLISHED WITH SNODE=WWW_TCPNPRX109E ### Not executed: XSTRUN (00000009) SNODE=WWW_TCPSVTM056I SESSION (000) TERMINATED WITH PNODE=WWW_TCP

Example USRINFO OutputThese examples show USRINFO output that is written to the USRINFO dataset while the DGAXPRCTexit is executing. Each line of output has a timestamp and the hexadecimal address of the IBMConnect:Direct Task Control Area (TCA) under which the DGAXPRCT exit is executing. The TCA addresspermits correlating output lines when Processes execute concurrently.

The following example shows DGAXPRCT output based on matching the specific Process name, TSTRUN.

965630E0 DGAXPRCT V1.14 ENTERED: SQCB@=16987688965630E0 ############ APPLID TABLE ############965630E0 EF965630E0 I965630E0 PTSTRUN965630E0 L965630E0 ############ END APPLID TABLE ############965630E0 SETTING DISPOSITION TO FLUSH.965630E0 TABLE MATCH: PNAME,PNUM=TSTRUN ,00000007965630E0 ENTRY=PTSTRUN NPRX000I ### Permitted: TSTRUN (00000007) SNODE=WWW_TCP965630E0 DGAXPRCT EXITED: SQCB@/RC/MSGID 16987688 /00000000 /NPRX000I96561D60 DGAXPRCT V1.14 ENTERED: SQCB@=1699068896561D60 ############ APPLID TABLE ############96561D60 EF96561D60 I96561D60 PTSTRUN96561D60 L96561D60 ############ END APPLID TABLE ############96561D60 SETTING DISPOSITION TO FLUSH.96561D60 NO TABLE MATCH: PNAME,PNUM=XSTRUN ,00000009 NPRX101E ### No entry: XSTRUN (00000009) SNODE=WWW_TCP96561D60 DGAXPRCT EXITED: SQCB@/RC/MSGID 16990688 /00000004 /NPRX101E

The following example shows DGAXPRCT output based on matching the names of all Processes that beginwith TSTRUN using the wildcard *.

364 IBM Connect:Direct for z/OS: Documentation

96562720 DGAXPRCT V1.14 ENTERED: SQCB@=1699068896562720 ############ APPLID TABLE ############96562720 EF96562720 I96562720 PTSTRUN*96562720 L96562720 ############ END APPLID TABLE ############96562720 SETTING DISPOSITION TO FLUSH.96562720 TABLE MATCH: PNAME,PNUM=TSTRUN ,0000001096562720 ENTRY=PTSTRUN* NPRX000I ### Permitted: TSTRUN (00000010) SNODE=WWW_TCP96562720 DGAXPRCT EXITED: SQCB@/RC/MSGID 16990688 /00000000 /NPRX000I96561D60 DGAXPRCT V1.14 ENTERED: SQCB@=1699068896561D60 ############ APPLID TABLE ############96561D60 EF96561D60 I96561D60 PTSTRUN*96561D60 L96561D60 ############ END APPLID TABLE ############96561D60 SETTING DISPOSITION TO FLUSH.96561D60 TABLE MATCH: PNAME,PNUM=TSTRUN2 ,0000001196561D60 ENTRY=PTSTRUN* NPRX000I ### Permitted: TSTRUN2 (00000011) SNODE=WWW_TCP96561D60 DGAXPRCT EXITED: SQCB@/RC/MSGID 16990688 /00000000 /NPRX000I

The following example shows invalid entries in the DGAXPRCT Parameter Table.

96562720 DGAXPRCT V1.14 ENTERED: SQCB@=1699068896562720 ### INVALID TABLE ENTRY:XTSTRUN* NPRX005E ### Table format error encountered.96562720 DGAXPRCT EXITED: SQCB@/RC/MSGID 16990688 /00000008 /NPRX005E

Custom Messages in the Message LibraryYou can load special user-defined messages into the IBM Connect:Direct message library. The sampleformat for the IBM Connect:Direct message source in the following figure is in the DGAXMSGC member ofthe IBM Connect:Direct sample library, $CD.SDGASAMP.

Note: Use the exact format as follows. You cannot use comments.

DELETE =MSG00001INSERT =MSG00001MODULE =MSGSOURCSTEXT= This is an example of the short text message (one).L01 = This is an example of the long text message (one). AsL02 = many as 12 lines may be used for the long text message.L03 =L04 =L05 =L06 =L07 =L08 =L09 =L10 =L11 =L12 =

Observe the following rules for variables and message IDs:

• The DELETE and INSERT variables are 1–8 characters.• The MODULE variable is 1–64 characters.• The STEXT and L01 through L12 variables are 1–63 characters.• To insert a message ID, the INSERT, MODULE, STEXT, and L01 through L12 variables are required.• To delete a message ID, the DELETE variable is required.

Chapter 4. Administration Guide 365

• To replace a message ID, the DELETE, INSERT, MODULE, STEXT, and L01 through L12 variables arerequired.

The job stream in the following figure is in the DGAJMSGL member of the IBM Connect:Direct$CD.SDGAJCL library. After copying the message source into your message source library and makingchanges as needed, run this job stream to add your messages to the IBM Connect:Direct message library.

//JOBNAME JOB (ACCT),’NAME’,CLASS=A,NOTIFY=TSOID,MSGCLASS=X//MSGBUILD EXEC PGM=DMMSGLOD,PARM=’$CDHLQ.MSGFILE’//STEPLIB DD DSN=$CDHLQ.SDGALINK,DISP=SHR//SYSOUT DD SYSOUT=*//INPUT DD DSN=$HLQ.SDGAMSGS,DISP=SHR

Note: For SMP/E installations, add the message source to the NMSGSRC target library as an SMP/EUSERMOD. MSGLOAD JCL can then process it.

Make the following changes to the job:

• Change the PARM statement to reference the file name of the IBM Connect:Direct VSAM message file.This value is the same value specified in the MSGDSN initialization parameter.

• Change the STEPLIB DD card to reference the SDGALINK.• Change the INPUT DD card to reference the message source text. A sample format is in the member

DGAXMSGC in the IBM Connect:Direct sample library, $CD.SDGASAMP.

Message IDsIn a IBM Connect:Direct/Plex environment, messages can originate from any IBM Connect:Direct/Serveror from the IBM Connect:Direct/Manager so you should define a 2-character message ID that identifieswhich IBM Connect:Direct/Plex member originated the message. This message ID is displayed after themessage number.

Define the message ID using the CDPLEX.MSGID initialization parameter.

The following example shows a message if the CDPLEX.MSGID value is set to S1. The message ID ishighlighted in bold.

SVTM055I S1 SESSION (001) ESTABLISHED WITH SNODE=SC.DUB.TPYLA2 SVTM055I S1 SESSION (001) ESTABLISHED WITH PNODE=SC.DUB.TPYLA2 SVTM036I S1 PROCESS STARTED MVSMVST3( 1) PNODE=SC.DUB.TPYLA2 SVTM036I S1 PROCESS STARTED MVSMVST3( 1) SNODE=SC.DUB.TPYLA2

Customizing Submit ScreensWhen you type variables into a submit screen, the IUI builds a SUBMIT command, and the commandgoes to a dialog for handling. As delivered on the installation tape, the primary IUI panel, DGA@PRIM,directly invokes the IUI submit panel, DGA@UBMT, when the SB option is selected. You can construct acustomized submit screen to contain customized submit options. All menus can contain as many choicesas screen space permits. To customize the submit function, modify DGA@PRIM to invoke DGA@SM03instead of DGA@UBMT, when the SB option is selected, and perform the following procedure.

The following general steps are illustrated in an example which describes how to create a custom SUBMITscreen that copies a file to the existing file at another site at noon every day. You are notified when theProcess is complete.

1. DGA@SM03 is a submit menu panel which contains only one menu option that invokes DGA@UBMT.You can modify DGA@SM03 to include new menu selections to invoke the new customized submitpanels. This step is explained in Step 1 - Modify the Existing Menu DGA@SM03.

2. Define at least one general purpose Process to be invoked by the new custom submit screen. This stepis explained in Step 2 - Define General Purpose Process.

3. Provide custom submit screens. These screens:

366 IBM Connect:Direct for z/OS: Documentation

• Process variables that are resolved as SUBMITS occurs.• Build a command on each screen that communicates with the IUI dialog routines.

This step is explained in Step 3 - Provide a New Submit Screen.

Step 1 - Modify the Existing Menu DGA@SM03To modify the IBM Connect:Direct Submit Menu, add the following in Submit Menu (DGA@SM03):

• A line in the BODY section to specify the new option (+ 2 = => COPY TO EXISTING FILE AT ANOTHERSITE EVERYDAY AT NOON)

• A line in the PROC section to specify what to do when that option is selected (2,’PANEL(CUSTSUBM)’)

The following figure shows the menu displayed after you add information. Only the elements necessaryto modify an existing menu are displayed. If the user selects Option 2 on the command line, IBMConnect:Direct gives control to the screen with the name CUSTSUBM and displays that screen.

)ATTR ")BODY#UNODE + SUBMIT MENU +&ZDATE+CMD%= = > _ZCMD +&ZTIME#STEXT+%PROCESSES:++ 1 = = > SUBMIT A PROCESS+ 2 = = > COPY TO EXISTING FILE AT ANOTHER SITE EVERYDAY AT NOON+)INIT ")PROC " &SEL = TRANS(TRUNC(&ZCMD,’.’) " " 1,’PANEL(DMISUBMT)’ 2,’PANEL(CUSTSUBM)’ *,’?’ ")END

Note: For SMP/E installation, implement all ISPF panel changes as SMP/E USERMODs to the NISPPLIBtarget library.

Step 2 - Define General Purpose ProcessThe second step in creating a customized submit screen is to define a Process that the custom Submitscreen invokes. The following Process is named APROC.

APROC PROCESS SNODE=&SNODE NOTIFY=%USERSTEP1 COPY FROM (PNODE DSN=&DSN1 DISP=SHR) - TO (DSN=&DSN2 DISP=(SHR,KEEP))

The SNODE, source file name, and the destination file name specified in the BODY section of the customsubmit screen are substituted into the symbolic fields currently in the PROCESS (SNODE, DSN1, andDSN2).

Chapter 4. Administration Guide 367

Step 3 - Provide a New Submit ScreenA new submit screen processes variables resolved during submission and builds a command tocommunicate with the dialog routines. Although the customized submit screen can have any appearance,use the following information to help you design your screens.

1. Use the generic submit screen (DGAXCUST) found in the sample library, $CD.SDGASAMP, as a base forcreating the custom screen.

2. Use the least number of input fields necessary when creating the screen to accomplish Processsubmission.

3. Use existing variables from DGAXCUST, if possible. You can use any variable name, but fewer changesare necessary when you use the existing code. The following ISPF variables are used in the IBMConnect:Direct submit processing.

Variable Explanation

&PNAME1 Name of Process to be submitted

&DSN File name containing Process to be submitted

&SNODE Secondary node name

&H HOLD specification

&R RETAIN specification

&PR Priority of the Process

&NEWNAME New name for the Process being submitted

&CLS Process class

&NOTIFY Notify IBM Connect:Direct user ID

&PNODEID Security user ID at PNODE

&PNODEPW Current security password at PNODE

&PNODENPW New security password at PNODE

&SNODEID Security user ID at SNODE

&SNODEPW Current security password at SNODE

&SNODENPW New security password at SNODE

&DSYMBPARM Symbolic variable specification

&STIME Start time value

&SDATE Start day/date value

&CMD1 Used in constructing command string

&CMD2 Used in constructing command string

&CMD3 Used in constructing command string

&CMD4 Used in constructing command string

Note: Do not change the &CMD1, &CMD2, &CMD3, and &CMD4 ISPF variables. The SUBMIT commandstring is built into these four variables.

The following figure shows the ATTR and BODY sections of the customized submit screen CUSTSUBM.The ATTR section is the same as in the sample base screen, DGAXCUST. As seen in the BODY section,FROMDSN and TODSN are variables that are symbolically substituted when the general purposeProcess APROC is submitted.

368 IBM Connect:Direct for z/OS: Documentation

)ATTR + TYPE(TEXT) INTENS(LOW) SKIP(ON) : TYPE(INPUT) INTENS(NON) # TYPE(OUTPUT) INTENS(HIGH) JUST(ASIS) CAPS(OFF) @ TYPE(OUTPUT) INTENS(LOW) JUST(ASIS) ¢ PAD(_) )BODY #UNODE + CUSTOMIZED SCREEN +CMD%= = > _ZCMD #STEXT + TIME-&ZTIME % COPY TO EXISTING FILE AT ANOTHER SITE + DATE-&ZDATE % EVERY DAY AT NOON + JULIAN-&ZJDATE + FILE TO BE SENT FROM HERE % = = > ¢FROMDSN + + + NODE TO RECEIVE THE FILE % = = > ¢SNODE + + + RECEIVING FILE ON ABOVE NODE + = = > ¢TODSN +

4. Make the necessary changes in the INIT section after deciding how you want to set up the screen.Initialize all INIT section variables to the appropriate default value. For CUSTSUBM, the INIT section isin the following figure.

)INIT .ZVARS = '(V@SEC)' &NXTHELP = DMJSBMT1 .CURSOR = &FROMDSN /*CHANGED */ &UNODE1 = &UNODE1 &SPC = ''..&V@SEC = 'N'..IF (&PROC ~= 'Y') &STEXT = ''/* &PNAME1 = '' DELETED *//* &DSN = '' DELETED */ &SNODE = ''/* &Q = '' DELETED *//* &H = '' DELETED */ &R = 'Y' /*CHANGED *//* &PR = '' DELETED *//* &NEWNAME = '' DELETED *//* &CLS = '' DELETED */ &STIME = '12:00' /*CHANGED *//* &SDATE = '' DELETED *//* &SYMBPARM = '' DELETED */ &FROMDSN = '' /* ADDED */ &TODSN = '' /* ADDED *//* IF (&UNODE = &LNODE) DELETED * &NOTIFY = '%USER'/* IF (&UNODE ~= &LNODE) DELETED *//* &NOTIFY = '' DELETED */ IF (&PROC = 'Y') IF (&PROC# ~= 'NONE') .MSG = IUSB000I IF (&STEXT = '') .HELP = &NXTHELP IF (&STEXT ~= '') .HELP = DMI@MSG

The following changes are made in the INIT section:

• The cursor field is changed to FROMDSN.• &R is changed to Y to indicate RETAIN=YES.• &STIME is changed to 12:00 to indicate STARTT=(,12:00).• &FROMDSN and &TODSN are added and initialized to blanks.• Lines which carry a DELETED comment are removed because they are no longer necessary.

Chapter 4. Administration Guide 369

5. Make the necessary changes in the PROC section after deciding how you want to set up the screen.Verify PROC section field values and build the command string to submit the Process. For CUSTSUBM,the PROC section is in the following figures.

)INIT)PROC &PROC# = 'NONE' &CMD = &ZCMD &SEL = TRANS( TRUNC (&ZCMD,'.') SPF,'PANEL(ISR@PRIM) NEWAPPL(ISR)' WHO,'PANEL(DMI@WHO)' SW,'PGM(DMICMD) PARM(&CB@)' M,'PANEL(DMI@MSG)' AUTH,'PANEL(DMI@AUTH)' ' ','PGM(DMICMD) PARM(&CB@)' *,'?' ) &ZTRAIL = .TRAIL IF (&ZCMD = 'SW') &SPC = 'SLN' IF (&CMD = ' ') VER(&FROMDSN,NONBLANK) /* ADDED */ VER(&SNODE,NONBLANK) /* ADDED */ IF (&TODSN= '') /* ADDED */ &TODSN=&FROMDSN /* ADDED *//* VER(&PNAME1,NAME,MSG=IUSB001I) DELETED *//* IF (&PNAME1 ~= ' ') DELETED *//* IF (&DSN ~= ' ') DELETED *//* .MSG = IUSB002I DELETED *//* .CURSOR = PNAME1 DELETED *//* IF (&DSN = ' ') DELETED *//* VER(&PNAME1,NONBLANK,MSG=IUSB003I) DELETED *//* VER(&Q,LIST,Y,N,MSG=IUSB022I) DELETED *//* VER(&H,LIST,Y,N,C,MSG=IUSB005I) DELETED */ VER(&R,LIST,Y,N,I,MSG=IUSB006I)/* VER(&V@SEC,LIST,Y,N,I,MSG=IUSB006I) DELETED *//* VER(&PR,RANGE,0,15,MSG=IUSB007I) DELETED *//* VER(&NEWNAME,NAME,MSG=IUSB008I) DELETED *//* VER(&CLS,RANGE,1,255,MSG=IUSB009I) DELETED */ &USER = TRUNC(&NOTIFY,1) IF (&USER ~= %) VER(&NOTIFY,NAME,MSG=IUSB010I)&PROC = 'Y'

370 IBM Connect:Direct for z/OS: Documentation

&CMD1 = ' SUB PROC=APROC' /*CHANGED */ &CMD2 = '' &CMD3 = '' &CMD4 = &SYMBPARM IF (&PNAME1 ~= ' ') /*CHANGED */ &CMD1 = '&CMD1 PROC=&PNAME1' /*CHANGED */ IF (&DSN ~= ' ') /*CHANGED */ &CMD1 = '&CMD1 DSN=&DSN' /*CHANGED */ IF (&SNODE ~= ' ') &CMD1 = '&CMD1 SNODE=&SNODE'/* IF (&Q ~= ' ') DELETED *//* &CMD1 = '&CMD1 REQUEUE=&Q' DELETED *//* IF (&H ~= ' ') DELETED *//* &CMD1 = '&CMD1 HOLD=&H' DELETED */ IF (&R ~= ' ') &CMD1 = '&CMD1 RETAIN=&R'/* IF (&PR ~= ' ') DELETED *//* &CMD1 = '&CMD1 PRTY=&PR' DELETED *//* IF (&NEWNAME ~= ' ') DELETED *//* &CMD1 = '&CMD1 NEWNAME=&NEWNAME' DELETED */ IF (&NOTIFY ~= ' ') &CMD2 = ' NOTIFY=&NOTIFY' &PARMX = '' &PARMX2 = ''/* IF (&SDATE ~= ' ') DELETED *//* &PARMX = 'Y' DELETED *//* &CMD2 = '&CMD2 STARTT=(&SDATE,' DELETED */ IF (&STIME ~= ' ') IF (&PARMX ~= 'Y') &PARMX = 'Y' &PARMX2 = 'Y' &CMD2 = '&CMD2 STARTT=(,&STIME' IF (&PARMX2 ~= 'Y') &CMD2 = '&CMD2 &STIME' IF (&PARMX = 'Y') &CMD2 = '&CMD2'/* IF (&CLS ~= '') DELETED *//* &CMD2 = '&CMD2 CLASS=&CLS' DELETED *//* IF (&V@SEC = 'Y') DELETED *//* &ZSEL = 'PANEL(DMIUSRID)' DELETED */ &CMD3= '&&DSN1=&FROMDSN' /*ADDED */ &CMD3= '&CMD3 &&DSN2=&TODSN' /* ADDED */)END

The following changes are made in the PROC section:

• A verify is added for the &FROMDSN variable. It must be non-blank.• A verify is added for the &SNODE variable. It must be non-blank.• A test for blanks in &TODSN is added. If &TODSN is blank, it is set to &FROMDSN.• &CMD1 is changed to contain the string SUB PROC=APROC, the command default.• &CMD3 is added to contain the string &&DSN1=&FROMDSN. Symbolic substitution is accomplished

with this addition. When APROC is submitted, &DSN1 is translated to whatever value is in the&FROMDSN file.

• The next-to-last line is added to concatenate the string &&DSN2=&TODSN to the contents of&CMD3. When APROC is submitted, &DSN2 is translated to the value in &TODSN.

• Lines which carry a DELETED comment are removed because they are no longer necessary.

If Y12.FROMHERE is the file to be sent, CD.THERE is the node to receive the file, Z12.TOHERE is thereceiving file, and the Process is APROC, then the command string is built as follows.

SUB PROC=APROC SNODE=CD.THERE RETAIN=Y NOTIFY=%USER - STARTT=(,12:00) &DSN1=Y12.FROMHERE &DSN2=Z12.TOHERE

When the Process APROC is submitted, it is resolved as follows.

Chapter 4. Administration Guide 371

APROC PROCESS SNODE=CD.THERE NOTIFY=%USERSTEP1 COPY FROM (SNODE DSN=Y12.FROMHERE DISP=SHR) - TO (DSN=Z12.TOHERE DISP=(SHR,KEEP))

Administering StatisticsThe Connect:Direct for z/OS statistics facility logs statistics to a series of VSAM file pairs. Each pairconsists of an entry-sequenced file and a key-sequenced file, both with the REUSE attribute.

File Pair Configuration

The minimum configuration is two file pairs, or four files, however you can configure more than two filepairs. Specify the file pairs in the initialization parameters, STAT.DSN.BASE and STAT.FILE.PAIRS, as dataset name high level qualifiers and the number of pairs. This specification determines the configuration ofthe statistics file pair list.

Within each file pair, IBM Connect:Direct writes the statistics records to the entry-sequenced file, whilethe key-sequenced file maintains index information about the records. On average, IBM Connect:Directwrites records to the key-sequenced file at the rate of about one for every two records written to theentry-sequenced file.

Retrieving Statistics with the SELECT STATISTICS Command

When you issue SELECT STATISTICS commands, the system locates the requested records by using thekey-sequenced file as an index to the entry-sequenced file. All the file pairs defined to the DTF areavailable to SELECT STATISTICS command processing. IBM Connect:Direct searches any file pair thatcontains records satisfying the SELECT STATISTICS command, not just the files currently being written.

How Records Are WrittenIBM Connect:Direct writes the statistics records to the entry-sequenced VSAM files in chronological order,starting at the beginning of the file and proceeding until the file or its paired key-sequenced file is full.The oldest record is always at the beginning of the file and the newest record is last. The system recordseach statistics record as a single VSAM record. The system does not compress the records or add controlinformation.

When a file pair is full, the system switches to the next in the sequence, and begins writing to it. When thelast file pair in the list is full, the system wraps back to the first pair in the sequence.

You can also specify the time of a file switch by using the STAT.SWITCH.TIME initialization parameter.For example, you can specify that statistics files switch at midnight every day, which limits a file pair torecords from a single day. IBM Connect:Direct also provides a statistics switch API command that directsthe DTF to perform a switch at any time.

When the system has written to all the pairs in the list, the system reuses the pairs. When a switch ismade, the system closes the active pair and makes the pair with the oldest data the new active pair. Whenthe system switches to a file, or a file becomes active, Connect:Direct for z/OS does a VSAM RESET. ThisVSAM RESET erases any records and index information in the active file. The system then writes newrecords starting at the beginning of the file.

Tools to Monitor the Statistics FacilityIBM Connect:Direct provides the following tools for monitoring the statistics facility:

• INQUIRE STATISTICS command• S2 statistics records

372 IBM Connect:Direct for z/OS: Documentation

• SS statistics records• DGASSTAT utility

INQUIRE STATISTICS CommandThe INQUIRE STATISTICS command gives a snapshot of the status of the facility. INQUIRE STATISTICSproduces a report that includes the following:

• List of any currently EXCLUDEed record types• File pair list configuration that includes which file pair is active• Date and time range covered by each file pair• Size of each file• Utilization percentage of the entry-sequenced files• Count of SELECT STATISTICS commands active against each file pair• Indication if logging is waiting for SELECT STATISTICS to finish so a file pair can be reset• Indication if logging is waiting for archive to finish so a file pair can be reset• Reason for the last switch from each file pair• Most recent file access return code and message ID for each file• Utilization percentage of the nonactive key-sequenced files• Indication of whether archive notification was received for the nonactive files

S2 Statistics RecordsThe S2 statistics records contain information about the statistics logging function. The system writes therecords about once per hour when activity exists in the DTF. Each S2 record contains statistics about theperiod of time since the prior S2 record. The S2 statistics records include the following information:

• Beginning time and length of the period covered• Count of records written in the period• Count of ESDS control intervals written in the period• Count of total bytes written to the ESDS• Average statistics record length• Average records per control interval• Average ESDS writes per second• Average KSDS writes per second• Average logging service time• Total waits for logging queue element• Each indexed field including max keys and average keys per control interval

Use the TYPE parameter of the SELECT STATISTICS command to view the S2 records. The system writesthe S2 records with the user ID specified in the STAT.USER initialization parameter. If you code a uniqueID for STAT.USER and you specify the USER parameter on the SELECT STATISTICS request, you greatlyreduce the search time because the user ID is an indexed field. See the IBM Connect:Direct for z/OS UserGuide for more information on how to use the SELECT STATISTICS command.

For example, if you code STAT.USER=statuser, a SELECT STATISTICS request to display all S2 recordslooks like the following figure.

SELECT STATISTICS WHERE (USER=statuser, TYPE=(S2)) TABLE

Chapter 4. Administration Guide 373

SS Statistics RecordsThe SS statistics records contain information about SELECT STATISTICS processing. One SS record iswritten for each SELECT STATISTICS command that executes. The SS record includes information such asthe index that IBM Connect:Direct uses to search the files and the number of requests issued to the keyedand entry-sequenced clusters. The record also includes the number of records examined and rejected.

Use the SELECT STATISTICS command with the TYPE parameter to view the SS record.

Using selection criteria with the SELECT STATISTICS request improves the performance by efficientlylocating the requested records. For example, you can include the ID of the user that issued the SELECTSTATISTICS command or the approximate time the request was issued, using the STARTT, STOPT, andUSER parameters. The following figure shows an example using this selection criteria.

SELECT STAT WHERE - (TYPE=(SS) USER=USER1 STARTT=(,NOON) STOPT=(,13:00)) TABLE

Using the DGASSTAT Utility to Determine File UsageUse the DGASSTAT utility to find out the rate at which the system generates statistics records. DGASSTATalso performs an analysis of the contents of the statistics file showing what percentage of the records areof each record type. This utility runs as a batch job step, and analyzes a single statistics entry-sequencedfile.

Use the DGASSTAT JCL to report on the statistics files. It calculates the average number of CIs used perday at one DTF.

The job stream example in the following figure, DGAJSTAT , is found in the $CD.SDGAJCL distributionlibrary.

//JOBNAME JOB (ACCT),CLASS=A //************************************************************ //* * //* Connect:Direct * //* * //* This JCL will invoke the utility to produce * //* a report for a Statistics File. * //* * //* Change "$CD" to the high-level qualifier(s) * //* appropriate for your installation. * //* * //* Change "$CDVSAM.STAT.ESDS01" to match the name * //* of the Statistics file to be analyzed. * //* * //************************************************************ //STEP1 EXEC PGM=DGASSTAT //STEPLIB DD DISP=SHR,DSN=$CD.SDGALINK //SYSOUT DD SYSOUT=* //ESDS DD DISP=SHR,DSN=$CDVSAM.STATS.ESDS01 (ESDS of file pair)

Optimizing Statistics FilesUse this information to determine the most efficient use of Statistics file space.

Note: IBM Connect:Direct does not support extended-format, extended-addressing ESDS Statistics datasets.

In this example, the IBM Connect:Direct software is installed using the default statistics installation oftwo file pairs with a total capacity of 13,500 records. After running IBM Connect:Direct for a time, youdetermine that the records log for about 2.5 days before the file pair list wraps. The administrator wantsto provide space for 7 days worth of records to be available at any given time. The administrator does thefollowing:

1. Use DGASSTAT to determine the number of records written daily.

374 IBM Connect:Direct for z/OS: Documentation

Run the DGASSTAT utility against the statistics entry-sequenced clusters to determine the rate atwhich the system generates the statistics records.

For example, DGASSTAT shows that records per day is approximately equal to 5,400.2. Determine the total capacity of the statistics file.

capacity = (records per day) * days

Determine the total capacity in this example by multiplying the 5,400 records per day by seven days.In this case, the total capacity of the statistics file is 37,800 records.

3. Determine the number of records per file pair.

In this example, the administrator decides to define four file pairs, so each are given a capacity of9,500 records, for a total capacity of 38,000 records.

4. Determine the RECORDS parameter value for the key-sequenced clusters.The number of KSDS records needed depends on both the number of records in the associatedESDS and a factor determined by the ESDS CISIZE. For more information, see Statistic FileRecommendation, IBM Connect:Direct for z/OS Configuration Guide. Assume the factor in this caseis 0.75 which corresponds to an ESDS CISIZE of 8K.

KSDS-records = 0.75 * (ESDS-records)

Determine the number of KSDS records by multiplying 75% by 9,500, the number of records per filepair. The RECORDS parameter value for the key-sequenced clusters is 7,125.

Based on these calculations, the administrator allocates four file pairs. The entry-sequenced cluster(ESDS) of each pair is defined with RECORDS(9500). The key-sequenced clusters (KSDS) are defined withRECORDS(7125).

Change the File Pair ConfigurationMake changes to the statistics files or to the configuration of the file pair list when the DTF is not running.During DTF execution, the files remain allocated by IBM Connect:Direct.

The restrictions that IBM Connect:Direct places on changes to the configuration maintain the integrity ofthe facility. At DTF initialization time, IBM Connect:Direct checks the usability, validity, and accessibility ofthe statistics files data.

File Pair VerificationIBM Connect:Direct performs a verification procedure at initialization, as follows:

• Within each file pair, IBM Connect:Direct verifies the appropriate sizing, relative to each other, of theentry-sequenced cluster and the key-sequenced cluster. If the file pair is not relatively sized, then IBMConnect:Direct issues a warning message and initialization continues.

• If either of the files of a pair has data, IBM Connect:Direct attempts to verify that the two files areactually a statistics file pair. IBM Connect:Direct verifies that the key-sequenced file really does containindex information for the associated entry-sequenced file.

IBM Connect:Direct uses control information maintained in the key-sequenced file to perform theverification. The software keeps a control record in the KSDS which contains the data set name andthe control interval size of the paired entry-sequenced file. If this information does not match, statisticsinitialization fails.

Changing the File PairFollowing are the implications of changing the file pair.

Chapter 4. Administration Guide 375

• Changing the control interval size of the ESDS or renaming the clusters causes initialization to failbecause the control record in the KSDS no longer matches the files. The two ways to resolve thisstatistics initialization failure are:

– First, you can use the DGADBKEY utility to rebuild the key-sequenced cluster. This utility recreatesthe KSDS control record so that it matches the new names or control interval size. The records in thefile pair remain accessible when the DTF is available again.

– The second solution is to empty the files. The file pair is available for logging new records. However,the old records are no longer available. You may want to archive the files before emptying them.

• Changing the size of a file pair is not a problem. The sizes of both files of a pair change together so thatthe relative sizes do not change.

– If the files are made larger and the names remain the same, then copy the records from the oldsmaller entry and key-sequenced clusters to the new larger ones.

– Use the same procedure to make a file pair smaller if all the existing records from both files will fitinto the smaller space of the new files. If the existing records do not fit, then the new smaller file pairmust be left empty initially, and the old records become unavailable.

File Pair List VerificationIBM Connect:Direct generates the statistics file pair list from the initialization parameters STAT.DSN.BASEand STAT.FILE.PAIRS. See STAT.DSN.BASE = dsname base STAT.FILE.PAIRS = number for an example of afile pair list.

The IBM Connect:Direct statistics facility processes the statistics file pair list in a circular, or wrap-aroundfashion. The system maintains statistics records in strictly chronological order both within each file pair,and with regard to the file pairs in the list.

At DTF initialization, unless STAT.INIT=COLD is specified in the initialization parameters, IBMConnect:Direct verifies that the order of the file pairs is valid. This verification is done by examiningthe date and time range of each non-empty file pair in the list. These must be in strictly ascending orderthroughout the list, except across the wrap point. Empty file pairs may appear anywhere in the list.

Changing the Number of File PairsIt can be useful to periodically change the number of file pairs in the list. To change the number of filepairs, change the STAT.FILE.PAIRS initialization parameter which specifies the number of file pairs. Thisaction adds to or removes from the end of the list.

• Add empty file pairs to the end of the list unless you specify STAT.INIT=COLD.• Remove records from the end of the list by reducing the STAT.FILE.PAIRS value. When you remove these

records, they become unavailable and can in some cases leave gaps in the statistics data. You may wantto archive these records before removing them.

Archiving StatisticsArchiving refers to the process of copying the records from a statistics entry-sequenced cluster to anotherdata set for long-term storage. The output of this process is an archived statistics file. You can write thearchive file to a VSAM entry-sequenced cluster with the same characteristics as a statistics ESDS, or toa non-VSAM sequential file on DASD. The system does not store the statistics records in the ESDS in anyspecial format. The system records each statistics record as a VSAM record in an ordinary VSAM ESDS.You can also write the archive file to a magnetic tape or a database table.

Archiving Using a Predefined ProcessUsing the DTF initialization parameter STAT.SWITCH.SUBMIT, you can specify that when the DTF switchesfrom one statistics file pair to another, IBM Connect:Direct submits a predefined Process to archive therecords in the previously active ESDS. IBM Connect:Direct submits this archive Process with a symbolicparameter indicating the data set name of the ESDS of the pair.

376 IBM Connect:Direct for z/OS: Documentation

• The Process can then use IBM Connect:Direct to copy the data to another location. A sample archiveProcess, DGAPSTAT, is in the $CD.SDGAPROC distribution library.

• Alternatively, the Process can submit a batch job to archive the data using IDCAMS REPRO, or someother utility. Use the DGADTSUB utility to substitute the file data set name into the submitted jobstream. You can invoke DGADTSUB through the RUN TASK statement. A sample archive Process,DGAPSTRJ, that submits a batch job using DGADTSUB.

Timing the ArchiveThe archive must complete before IBM Connect:Direct needs to reuse the file being archived, that is, atthe time of wrap-around of the file pair list. The completion of the archiving Process is important becauseIBM Connect:Direct erases the contents of the statistics file when the system switches to that file. Inother words, archiving must complete within the time required for the file pair list to wrap. Normally, thiscondition does not present a problem.

Require Confirmation of ArchivalThe STAT.ARCH.CONFIRM initialization parameter specifies whether or not to ensure that data is archivedbefore the system erases the file. If you do not want archiving, IBM Connect:Direct simply resets the fileswhen the switching occurs, and begins writing. If you want archiving, IBM Connect:Direct verifies that thearchive is complete before proceeding. In this case, IBM Connect:Direct requires notification of archival.IBM Connect:Direct is notified in several ways:

• If the archive is done using the COPY statement in a IBM Connect:Direct Process, then the Process canalso invoke the DGADARRT utility when the COPY successfully completes. IBM Connect:Direct invokesDGADARRT through a RUN TASK statement, and notifies IBM Connect:Direct that the data is archived.

• If you use a batch job to archive, then the job can send the notification by including a step to executethe DGADARBT utility.

• Also, you can issue the API command STATISTICS ARCHIVED to inform IBM Connect:Direct to reuse afile pair.

If no indication regarding the completion of the archive exists when IBM Connect:Direct needs to reusethe files, the system issues a message, similar to the example shown below, to the operator console andwaits for a reply indicating permission to reuse the file.

10.00.01 JOB82592 SSTL013I Statistics file pair switch from 02 to 01, code:TIMER10.00.02 JOB82592 SSTL009I Arch notification required but not received for file pair 0110.00.02 JOB82592 *93 SSTL008I Reply "GO" when file available, or "DISABLE" logging.

In this situation, all activity in the DTF ceases until a response to the message from the operator existsindicating that the statistics file can now be overwritten. This safeguard occurs as a result of the requestthat the DTF not erase statistics data unless it is certain that archiving the statistics is complete.

If you have not been requiring archival notification and decide to begin requiring it, you can avoid gettingthese messages by using the IUI command STAT, CF option and forcing all pairs not in use to indicate theyhave been archived.

Not Requiring Confirmation of ArchivalIBM Connect:Direct does not require archive confirmation before reusing a statistics file pair whenyou specify or default to the DTF initialization parameter, STAT.ARCH.CONFIRM=NO. If you specify thisinitialization parameter, you are responsible for ensuring that the archive successfully completes beforeIBM Connect:Direct resets the file. If the file is reset before copying the records, the data is lost.

If the records are in the process of being copied when IBM Connect:Direct needs to reset the file, thenIBM Connect:Direct must wait for the copy to complete. This operation is because IBM Connect:Directmust have exclusive access to the file to do the VSAM reset. In this situation, IBM Connect:Direct alsoissues a message to the operator console and waits for a reply indicating that the file can be reset.

Chapter 4. Administration Guide 377

Using the SELECT STATISTICS Command with Archived StatisticsConnect:Direct for z/OS provides a means of issuing the SELECT STATISTICS command against archivedstatistics. To make archived statistics available to SELECT STATISTICS, you must put the archivedstatistics in the format of a statistics file pair. You must make available a VSAM entry-sequenced clusterwith a paired VSAM key-sequenced cluster containing the index information.

For example, if the records are archived to a magnetic tape file, you must first copy the archived recordsto a VSAM ESDS. Then you can run the DGADBKEY utility to build the required associated VSAM KSDS.Refer to Program Directory for IBM Connect:Direct for z/OS and Planning DASD Requirements in IBMConnect:Direct for z/OS Configuration Guide for information about the characteristics and relative sizes ofthe keyed and entry-sequenced clusters of a file pair. See “DGADBKEY” on page 381 for an explanationand example of the DGADBKEY utility.

Use the ARCHDSN parameter of the SELECT STATISTICS command to search archive files. The ARCHDSNparameter names only the key-sequenced clusters of the archive pairs; IBM Connect:Direct locates theassociated entry-sequenced clusters using control information in the key-sequenced clusters.

IBM Connect:Direct does not examine the statistics file pair list of the DTF when using the ARCHDSNparameter. IBM Connect:Direct only searches the archive files. SELECT STATISTICS processing does notlet you name files currently in the file pair list of the DTF in the ARCHDSN parameter or combine archivefiles with files in the file pair list. Refer to the IBM Connect:Direct for z/OS User Guide for a description ofthe SELECT STATISTICS command and the ARCHDSN parameter.

Maintaining an Archive File DirectoryIBM Connect:Direct also provides the capability of maintaining a directory of statistics archive files. Thedirectory is a VSAM key-sequenced file that contains a record for each archive file. Information in therecord includes the data set name of the archive file and the range of dates and times covered by thearchived records. Refer to VSAM Files DASD Requirement and Description in the IBM Connect:Direct forz/OS Configuration Guide for estimating space requirements when allocating the directory file.

To use the directory feature, you must allocate the directory file and specify its name in theSTAT.ARCH.DIR initialization parameter. IBM Connect:Direct provides a means of viewing the directorycontents using the INQUIRE STATDIR command.

The archive notification utilities, DGADARRT and DGADARBT, write the directory records. If you want touse the directory feature, you must execute one of these utilities from the Process or batch job thatarchives the records. This condition is true even if you do not specify STAT.ARCH.CONFIRM=YES in theDTF initialization parameters. You must also use these utilities to send archive notification when you arenot using the directory feature, but specify STAT.ARCH.CONFIRM=YES in the Initialization Parameters file.

Archive-Related UtilitiesThis section explains the archiving related utilities: DGADARRT, DGADARBT, and DGADBKEY.

DGADARRTThe DGADARRT utility (ARchive Run Task) has the following functions:

• Notifies IBM Connect:Direct of the availability of a statistics file pair for reuse due to the completion ofarchiving

• Optionally adds an entry to the directory of archive files• By default, removes the oldest record from a full archive directory to make room for the newest record.

You can invoke DGADARRT from within a Process through the RUN TASK statement. Use this utilitywhen submitting a Process at statistics file pair switch time that archives the statistical data using IBMConnect:Direct to copy the statistics to another file. When the copy operation successfully completes, thesystem can update the directory and send the archive notification.

The program accepts three parameters through the RUN TASK statement.

378 IBM Connect:Direct for z/OS: Documentation

• The first parameter is required and is the data set name of the statistics entry-sequenced cluster that isarchived.

• The second parameter is optional, and is the data set name of the archive file.• The third parameter is optional, and specifies whether to age the archive directory.

DGADARRT always sends archive notification to the DTF. If you specify STAT.ARCH.CONFIRM=NO and nonotification requirement exists, the notification has no effect.

The addition of the entry in the directory of archive files depends on the specification of the secondparameter string. If the second parameter is present, then the system updates the directory to contain anentry for the new archive file.

The following is an example of an archive Process. This Process copies a statistics file to a sequentialtape file and then invokes DGADARRT to send archive notification to the DTF and update the directory ofarchive files. IBM Connect:Direct passes the data set name of the statistics file to the Process in the formof the symbolic parameter &EDSN.

DGAPSTAT PROCESS PNODE=primary.node - SNODE=secondary.node - PRTY=10 - STARTT=(TODAY) - &EDSN=ARC COPY FROM (DSN=&EDSN) - TO (DSN=stat.archive.dsn(+1) - DISP=(NEW,CATLG,DELETE) - DCB=(DSORG=PS,RECFM=VB,LRECL=2048) - UNIT=CART - LABEL=(1,SL) ) IF (ARC EQ 0) THEN RUN TASK (PGM=DGADARRT,PARM=("&EDSN", - "stat.archive.dsn(+0)")) EIF

Whether the archive directory ages off the oldest record to make room for the newest depends on thethird parameter, ARCAGE.

ARCAGE=Y - Requests that if the archive directory is full, the oldest record is deleted to make room forthe newest. The user receives notification that the record is aged off the archive directory. The amount oftime it takes to add a record to the archive directory is insignificant. But the amount of time it takes to ageoff the oldest record is noticeable and increases with the size of the archive directory, because all of therecords in the ESDS must be rewritten. This is the default.

ARCAGE=N - Requests that if the archive directory is full, the utility stops without updating the archivedirectory.

The following example shows the ARCAGE parameter specified in the DGADARRT utility for use within aProcess through the Run Task statement:

DGAPSTAT PROCESS PNODE=primary.node - SNODE=secondary.node - PRTY=10 - STARTT=(TODAY) - &EDSN=ARC COPY FROM (DSN=&EDSN) - TO (DSN=stat.archive.dsn(+1) - DISP=(NEW,CATLG,DELETE) - DCB=(DSORG=PS,RECFM=VB,LRECL=2048) - UNIT=CART - LABEL=(1,SL) ) IF (ARC EQ 0) THEN RUN TASK (PGM=DGADARRT,PARM=("&EDSN", - "stat.archive.dsn(+0)", - "ARCAGE=Y")) EIF

To prevent aging, set ARCAGE=N. As a result, the newest record is discarded, rather than the oldest.

Chapter 4. Administration Guide 379

DGADARBTThe DGADARBT utility (ARchive BaTch) has the following two functions:

• Notifies IBM Connect:Direct that a statistics file pair is archived and is available for reuse• Optionally adds an entry to the directory of archive files• By default, removes the oldest record from a full archive directory to make room for the newest record.

Execute DGADARBT as a step within a batch job. Use DGADARBT when submitting a job that archives thestatistical data by executing IDCAMS or some other utility to COPY the data to another file at statisticsfile pair switch time. The system can update the directory and send archive notification upon successfulcompletion of the copy operation.

DGADARBT requires that the system allocate the archived statistics file with the data definition name(DDNAME) of STESDS.

DGADARBT always sends archive notification to the DTF. If you specify STAT.ARCH.CONFIRM=NO and nonotification requirement exists, then the notification has no effect.

If you want DGADARBT to update the directory of archive files, the system must allocate the followingDDNAMEs:

• STADIR, the directory file• STARCH, the archive file

In the following example, the archive Process submits a batch archive job using DGADTSUB to substitutethe statistics file data set name into the job stream. The system passes this data set name to the archiveProcess as the symbolic parameter &EDSN. Refer to the IBM Connect:Direct for z/OS User Guide forinformation about how to use DGADTSUB. The submitted job uses the IDCAMS utility to copy the statisticsrecords to an archive file. If the IDCAMS step is successful, IBM Connect:Direct invokes DGADARBT toboth send the archive notification and update the directory.

The following figure is a sample archive Process.

ARCHSTRJ PROCESS PNODE=primary.node - SNODE=secondry.node - PRTY=10 - STARTT=(TODAY) - &EDSN= RUN TASK (PGM=DGADTSUB, - PARM=("DSN=SYS3.CONNECT.INSTALL.JCL(ARCHJOB),DISP=SHR",- "DSNAME &EDSN"))

The following figure is a sample archive job stream.

380 IBM Connect:Direct for z/OS: Documentation

//ARCHJOB JOB (ACCT),CLASS=A//*//* ---------------------------------------------------------------- *//* IDCAMS step to archive the Statistics ESDS: *//* ---------------------------------------------------------------- *//*//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//INPUT DD DISP=SHR,DSN=&DSNAME//OUTPUT DD DISP=(NEW,CATLG,DELETE),// DSN=stat.archive.dsn(+1),// UNIT=CART,// LABEL=(1,SL)//SYSIN DD * REPRO INFILE(INPUT) OUTFILE(OUTPUT)/*//*//* ---------------------------------------------------------------- *//* DGADARBT step to notify DTF that ESDS was archived: *//* ---------------------------------------------------------------- *//*//STEP2 EXEC PGM=DGADARBT,COND=(0,LT,STEP1)//STEPLIB DD DSN=prod.ndmlib,DISP=SHR//SYSOUT DD SYSOUT=*//STESDS DD DISP=SHR,DSN=*.STEP1.INPUT//STARCH DD DISP=SHR,DSN=*.STEP1.OUTPUT//STADIR DD DSN=stat.archdir.dsn,DISP=SHR//

The DGADARBT utility accepts the same ARCAGE parameter as specified for DGADARRT. It is the first andonly OS parameter for this utility.

The following example shows the ARCAGE parameter specified in the DGADARRT utility to run as a step ina batch job:

//ARCHJOB JOB (ACCT),CLASS=A//*////* ---------------------------------------------------------------- *//* IDCAMS step to archive the Statistics ESDS: *//* ---------------------------------------------------------------- *//*//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//INPUT DD DISP=SHR,DSN=&DSNAME//OUTPUT DD DISP=(NEW,CATLG,DELETE),// DSN=stat.archive.dsn(+1),// UNIT=CART,// LABEL=(1,SL)//SYSIN DD *REPRO INFILE(INPUT) OUTFILE(OUTPUT)/*//*//* ---------------------------------------------------------------- *//* DGADARBT step to notify DTF that ESDS was archived: *//* ---------------------------------------------------------------- *//*//STEP2 EXEC PGM=DGADARBT,COND=(0,LT,STEP1),PARM='ARCAGE=Y'//STEPLIB DD DSN=prod.ndmlib,DISP=SHR//SYSOUT DD SYSOUT=*//STESDS DD DISP=SHR,DSN=*.STEP1.INPUT//STARCH DD DISP=SHR,DSN=*.STEP1.OUTPUT//STADIR DD DSN=stat.archdir.dsn,DISP=SHR//

To prevent aging, set ARCAGE=N. As a result, the newest record is discarded, rather than the oldest.

DGADBKEYThe DGADBKEY utility (Build KEYs) loads a statistics key-sequenced cluster with index information for anassociated statistics entry-sequenced cluster. DGADBKEY must execute as a batch job step.

Chapter 4. Administration Guide 381

DGADBKEY enables the recreation of index information for archived statistics data so that you can issuea SELECT STATISTICS command. You can also use this utility to rebuild index information for statisticsfiles in the DTF file pair list in certain cases. Refer to Change the File Pair Configuration for additionalinformation.

DGADBKEY requires the allocation of DDNAMEs, ESDSnn and KSDSnn, with the entry-sequenced andkey-sequenced clusters respectively. IBM Connect:Direct loads the entry-sequenced cluster with thestatistics records for building the index information. The key-sequenced cluster must either be empty,or be defined with the REUSE attribute. DGADBKEY erases any records in the KSDS before writing thenew information. The size of the KSDS is about 25% of the size of the associated ESDS. The KSDS musthave the characteristics of a statistics key-sequenced cluster. Refer to VSAM Files DASD Requirement andDescription in the IBM Connect:Direct for z/OS Configuration Guide for details about allocating statisticsclusters.

The following is an example of a job stream to execute DGADBKEY.

//DGADBKEY JOB (ACCT),CLASS=A//STEP1 EXEC PGM=DGADBKEY//STEPLIB DD DISP=SHR,DSN=prod.SDGALINK//ESDS01 DD DISP=SHR,DSN=stat.esds01//KSDS01 DD DISP=SHR,DSN=stat.ksds01//SYSOUT DD SYSOUT=*//

PARM=CONSOLIDATE allows DGADBKEY to build a KSDS for an ESDS that contains multiple archivedstatistics datasets. To use this parameter, create a large flat file of archived statistics, loading them in dateorder from the oldest to the newest. Next, load this file to an ESDS that will hold all the records and createa KSDS for this ESDS. Then execute DGADBKEY using PARM=CONSOLIDATE to build the KSDS file. Thisfile pair is available as an Archived Statistics Dataset.

Sample Archiving SetupAssume that you have the following requirements for archiving:

• Statistics records must remain available for seven days in the file pair list before being overwritten bynew records. After seven days, they must be available in archive files.

• Each archive file can contain no more than one day of statistics records.• Batch jobs executing the IDCAMS utility to copy the records to sequential files on magnetic tape must

perform the archiving. The archive files must be available for 365 days.• Maintain a directory of archive files.• Ensure that statistics data is not overwritten before being archived.• Establish a procedure for making archived statistics available to the SELECT STATISTICS command.

Sample Statistics ConfigurationThis section describes how to configure the statistics facility to satisfy these requirements.

You must determine how to configure the statistics file pair list. The rate at which you log statisticsrecords, availability of the statistics records for seven days before being overwritten, and each archive filecontaining no more than one day of statistics records determine the size and number of file pairs required.

For the statistics records to remain available for seven days after being generated, the total recordcapacity of all the entry-sequenced statistics files is seven times the average number of recordsgenerated daily. Run the DGASSTAT utility to determine how many records, on average, the system writesdaily.

According to the sample requirements, a single archive file contains up to the same number of recordsas a single statistics entry-sequenced cluster, and an archive file contains no more than a day of records.Each ESDS also holds about a day of records, implying that seven statistics file pairs exist. Use theSTAT.SWITCH.TIME initialization parameter to initiate a file pair switch every day at midnight rather than

382 IBM Connect:Direct for z/OS: Documentation

depend on a file pair switch occurring regularly as a result of file pairs filling. To ensure that the switchesdo not occur before midnight as a result of a file pair becoming full, make each ESDS slightly larger thanthe daily requirement.

If you determine, using DGASSTAT, that the system writes statistics records at the rate of about 11,000daily, define seven file pairs each with a capacity of about 12,000 records (RECORDS(12000)). This figureimplies that the associated key-sequenced clusters are defined with RECORDS(9000).

RECORDS(365) defines the directory of archive files because the system generates the archive files at therate of one daily and retains the files for one year.

SYSTEMS.CD.STATS is the data set name prefix for the statistics clusters. The data set name of the archivedirectory is SYSTEMS.CD.STATS.DIRECTRY. Member ARCHPROC in the data set SYSTEMS.CD.ADMINLIBcontains the archive Process that is submitted at file pair switch time.

The following initialization parameters are necessary for the sample archive requirements.

STAT.DSNBASE = SYSTEMS.CD.STATS /* data set name base */STAT.FILE.PAIRS = 7 /* number of file pairs */STAT.SWITCH.TIME = ( 00:00 ) /* switch at midnight */STAT.SWITCH.SUBMIT = SYSTEMS.CD.ADMINLIB(ARCHPROC) /* archive proc */STAT.ARCH.DIR = SYSTEMS.CD.STATS.DIRECTRY /* use directory */STAT.ARCH.CONFIRM = YES /* be sure archive completes */

The archive Process in the member ARCHPROC follows.

ARCHIVE PROCESS &EDSN=, - /* passed stats dsname */ SNODE=CD.PROD, - /* PNODE=SNODE */ PNODE=CD.PROD, - /* */ CLASS=1, - /* lowest class */ PRTY=15, - /* highest priority */ REQUEUE=YES /* re-queue on error */ /* */ /* invoke DGADTSUB to submit the archive job... */ /* */ RUN TASK (PGM=DGADTSUB, - /* execute DGADTSUB, */ PARM=("DSN=SYSTEMS.CD.JCL(ARCHJOB),DISP=SHR", - /*job */ /* stream to sub*/ "DSNAME &EDSN")) /* pass stat dsname */

The archive job stream in SYSTEMS.CD.JCL(ARCHJOB) follows.

//ARCHJOB JOB (ACCT),ARCHIVE,CLASS=A,MSGCLASS=Z,MSGLEVEL=(1,1)//******* archive the statistical data ****************************//ARCHIVE EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//INPUT DD DISP=SHR,CD=&DSNAME /* from DGADTSUB *///OUTPUT DD DSN=SYS.NDM.ARCH.STATS(+1),DISP=(NEW,CATLG,DELETE),// UNIT=TAPE,DCB=(BUFNO=6)//SYSIN DD * REPRO INFILE(INPUT) OUTFILE(OUTPUT)/*//******* notify Connect:Direct that the file pair can be reused, ****//******* and update the directory of archive files *************//NOTIFY EXEC PGM=DGADARBT,COND=(0,LT) /* if no errors *///STEPLIB DD DISP=SHR,DSN=SYS.CD.SDGALINK//STESDS DD DISP=SHR,DSN=*.ARCHIVE.INPUT /* stat file *///STDIR DD DISP=SHR,DSN=SYSTEMS.CD.STATS.DIRECTRY /* archive directory *///STARCH DD DISP=SHR,DSN=*.ARCHIVE.OUTPUT /* archive file *///SYSOUT DD SYSOUT=*//

The previous archive job stream indicates that the IBM Connect:Direct administrator manages requestsfor access to archived statistics records. The submitted requests specify a range of dates and times forthe necessary records.

Chapter 4. Administration Guide 383

The administrator issues the INQUIRE STATDIR command to determine which archive files containrecords for the specified period. The administrator runs the following job stream to create a usablearchived statistics file pair for each archive file that it finds. The first step creates the archive file andcopies the record to it. The second step builds the index information.

//RESTORE JOB (ACCT),RESTORE,CLASS=A,MSGCLASS=Z,MSGLEVEL=(1,1)//ARCHIVE EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//INPUT DD DISP=SHR,DSN=SYS.CD.ARCH.STATS.GnnnnVnn /* arch seq *///SYSIN DD * DEFINE CLUSTER - /* define archive KSDS */ (NAME(SYS.CDARCH.Dyymmdd.KSDS) - /* supply archive date yymmdd */ VOLUMES(USRVOL) - INDEXED NOIMBED - FREESPACE(0 0) - KEYS(27 0) - RECORDSIZE(32 78) - REUSE NOREPLICATE - SHAREOPTIONS(2)) - DATA - (CONTROLINTERVALSIZE(4096) - RECORDS(9000) - NAME(SYS.CDARCH.Dyymmdd.KSDS.DATA)) - INDEX - (CONTROLINTERVALSIZE(512) - NAME(SYS.CDARCH.Dyymmdd.KSDS.INDEX)) DEFINE CLUSTER - /* define archive ESDS */ (NAME(SYS.CDARCH.Dyymmdd.ESDS) - VOLUMES(USRVOL) - REUSE NONINDEXED NOIMBED - RECORDS(12000) - /* same size as stats files */ RECORDSIZE(275 2048) - SHAREOPTIONS(2)) - DATA - (CONTROLINTERVALSIZE(4096) -NAME(SYS.CDARCH.Dyymmdd.ESDS.DATA)) IF MAXCC = 0 - /* if clusters allocated OK */ THEN REPRO INFILE(INPUT) - /* then load with stats */ OUTDATASET(SYS.CDARCH.Dyymmdd.ESDS)/*//*******//******* rebuild statistics index information//*******//BLDKEY EXEC PGM=DGADBKEY,COND=(0,LT)//STEPLIB DD DISP=SHR,DSN=SYS.CD.NDMLIB//SYSOUT DD SYSOUT=*//ESDSnn DD DISP=SHR,DSN=SYS.CDARCH.Dyymmdd.ESDS /* ESDS cluster *///KSDSnn DD DISP=SHR,DSN=SYS.CDARCH.Dyymmdd /* KSDS cluster *///

The archived statistics are now available and you can issue SELECT STATISTICS against the statistics bycoding the name of the key-sequenced file with the ARCHDSN parameter, as follows.

SELECT STATISTICS WHERE - (PNAME=USERPROC, ARCHDSN=(SYS.CDARCH.Dyymmdd))

Displaying the Status of the Statistics Logging FacilityThe INQUIRE STATISTICS command displays the current status of the IBM Connect:Direct statisticslogging facility.

The INQUIRE STATISTICS command has the following format.

Label Command Parameters

(optional) INQuire STATistics

No parameters are required for the INQUIRE STATISTICS command.

384 IBM Connect:Direct for z/OS: Documentation

Statistics Inquiry through the Batch InterfaceTo use the INQUIRE STATISTICS command from the batch interface, perform the following steps.

1. Place your command in a batch job stream as described in the IBM Connect:Direct for z/OS User Guide.2. Submit the job while IBM Connect:Direct is running.

Note: You must set the fifth character of the DGADBATC output parameter specification to Y to printthe result of the command that is in the temporary data set.

3. Verify your results.

Statistics Inquiry through the IUI InterfaceTo use the INQUIRE STATISTICS command from the IBM Connect:Direct IUI, perform the following steps.

1. Access the statistics facility by selecting option INQ from the Connect:Direct Administrative OptionsMenu. The Inquire DTF Internal Status screen is displayed.

2. Type ISTA and press ENTER to display the status of the statistics logging facility.3. Verify your results from the statistics logging facility display that is displayed. The report includes

information such as the configuration of the statistics file pair list, the active file pair, file percentageutilizations, date and time ranges in the files, and additional information about the statistics facility.

The following figure shows a partial sample report.

=============================================================CD.ART *INQ STATS* DATE: 08.31.2018 TIME: 14:35:29=============================================================

Status => Enabled Sec. Name =>Return Code => 0 Message ID => SSTL000ILast "S2" => 00:00:00 Que Wait => NoDsn Base => EPETE1.CD.ART.STATS Q threshld => 375Rst KSDS Vers=> 2 Q low-watr => 1453Excluded =>****************** F I L E P A I R #01 ******************Status => Active KSDS Vers => 2Start Date => 08.31.2018 End Date => 08.31.2018Start Time => 14:32:21 End Time => 14:35:29KSDS Size => 18432000 ESDS CIS => 24576ESDS Size => 73728000 ESDS Loc. => 26180419Reset Pend. => No Arch. Wait => NoLast Switch => Sel. Count => 0KSDS Status => Alloc, Open ESDS Stat. => Alloc, Open L-cmd => ENDREQ L-cmd => ENDREQ L-msg => SVS0000I L-msg => SVS0000I L-rc => 0 L-rc => 0 L-fdb => 0 L-fdb => 0****************** F I L E P A I R #02 ******************Status => Empty

Displaying the Statistics Archive File DirectoryThe INQUIRE STATDIR command displays the IBM Connect:Direct statistics archive file directory.

The INQUIRE STATDIR command has the following format and associated parameters.

Label Command Parameters

(optional) INQuire STATDIR STARTT = ([date | day][,hh:mm:ssXM])

No parameters are required for the INQUIRE STATDIR command.

The following table describes the optional parameters used with the INQUIRE STATDIR command:

Chapter 4. Administration Guide 385

Parameter Description

STARTT = ([date | day][,hh:mm:ssXM])

This parameter specifies that the directory display is to begin with the first archivefile created after the designated starting date and time. The date or day and time arepositional parameters. If you do not specify the date or day, a comma must precedethe time. If you omit this parameter, the display begins with the first directory entry.

date

This parameter specifies that the directory display is to start with this specific date.You can specify the day (dd), month (mm), and year (yy).

You can specify the day (dd), month (mm), and year (yy for 2-digit year and yyyy for4-digit year). You can use periods or back slashes (/) to separate the components of adate value.

You can omit the separators only for transfers between mainframe nodes. However,you must use separators for transfers between mainframes and all other platforms.

After you designate the date order in your initialization parameters, you can use thefollowing date formats:

DATEFORM=MDY specifies the date format as:

• mm/dd/yy or mm/dd/yyyy• mm.dd.yy or mm.dd.yyyy

DATEFORM=DMY specifies the date format as:

• dd/mm/yy or dd/mm/yyyy• dd.mm.yy or dd.mm.yyyy

DATEFORM=YMD specifies the date format as:

• yy/mm/dd or yyyy/mm/dd• yy.mm.dd or yyyy.mm.dd

DATEFORM=YDM specifies the date format as:

• yy/dd/mm or yyyy/dd/mm• yy.dd.mm or yyyy.dd.mm

The following Julian date formats are valid:

• yyddd or yyyyddd• yy/ddd or yyyy/ddd• yy.ddd or yyyy.ddd

If only date is specified, the time defaults to 00:00.

386 IBM Connect:Direct for z/OS: Documentation

Parameter Description

STARTT = ([date |day] [,hh:mm:ssXM])(continued)

day

This parameter specifies to display the first archive file created after this day ofthe week. Valid names include MOnday, TUesday, WEdnesday, THursday, FRiday,SAturday, and SUnday. You can also specify YESTER to search for archive filescreated after yesterday or TODAY to search for the archive files created after today.

hh:mm:ssXM

Requests the first archive file created after this time of day, specified in hours (hh),minutes (mm), and seconds (ss). XM can be AM or PM. You can express the time ofday using the 24-hour clock or the 12-hour clock. If you use the 24-hour clock, validtimes are 00:00–24:00. If you use the 12-hour clock, you can express 1:00 hours as1:00AM, and you can express 13:00 hours as 1PM.

If you do not use either AM or PM, IBM Connect:Direct assumes the 24-hour clock.You do not need to specify minutes and seconds. You can also specify NOON, whichdisplays files created after noon, or MIDNIGHT, which displays archive files createdafter midnight. The default for the time is 00:00:00, the beginning of the day.

If you specify time of day but not date, the output shows the first available entry inthe archive directory for files created after that time of day. Archive files from all latertimes and dates display up to and including the stop time.

Viewing the Statistics Archive Directory through the Batch InterfaceTo use the INQUIRE STATDIR command from the batch interface, perform the following steps.

1. Place your command in a batch job stream as described in the IBM Connect:Direct for z/OS User Guide.2. Submit the job while IBM Connect:Direct is running.

Note: Set the fifth character of the DGADBATC output parameter specification to Y to print the result ofthe command that is in the temporary data set.

3. Verify your results.

Viewing the Statistics Archive Directory through the IUI InterfaceTo issue the INQUIRE STATDIR command in the IBM Connect:Direct IUI, perform the following steps.

1. Select option INQ from the Connect:Direct Administrative Options Menu to display the statisticsfacility. The Inquire DTF Internal Status screen is displayed.

2. Type IDIR and press ENTER to display the directory. A sample of the screen follows.

node.name INQUIRE STATISTICS ARCHIVE DIRECTORYCMD ==> hh.mm mm/dd/yy yyyy.ddd

START DATE ==> ________ (Gregorian or Julian) START TIME ==> __________ (HH:MM:SSXM)

3. Supply the beginning date and time to limit the display for the INQUIRE STATDIR command. A reportshowing the results of the inquiry is displayed. The following figure shows a partial sample report.

Chapter 4. Administration Guide 387

======================================================================node.name *INQUIRE STATDIR* DATE: mm/dd/yyyy TIME: hh:mm:ss======================================================================Archival DSN: USER01.STT.DGAPSTAT.G0008V00Archival Notification: 03/02/1998 98.061 00:01:28Oldest Record: 03/01/1998 98.060 00:00:06Newest Record: 03/01/1998 98.060 23:59:54

Archival DSN: USER01.STT.DGAPSTAT.G0009V00Archival Notification: 03/03/1998 98.062 00:01:35Oldest Record: 03/02/1998 98.061 00:00:11Newest Record: 03/02/1998 98.061 23:59:45 . . .

Switching the Statistics File PairThe STATISTICS SWITCH command initiates a statistics file pair switch. The currently active file paircloses, and logging continues on the next file pair in sequence. This command provides a means ofinitiating a file pair switch at any given time. Otherwise, switching occurs when the active file pair fills, orwhen a time of day specified in the STAT.SWITCH.TIME initialization parameter occurs.

The STATISTICS SWITCH command has the following format.

Label Command Parameters

(optional) STATistics SWITCH

No parameters are required for the STATISTICS SWITCH command.

Initiating a Statistics File Pair Switch through the Batch InterfaceTo use the STATISTICS SWITCH command from the batch interface, perform the following steps.

1. Place your command in a batch job stream as described in the IBM Connect:Direct for z/OS User Guide.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

Initiating a Statistics File Pair Switch through the IUI InterfaceThe IUI provides a formatted panel that facilitates the issuing of the STATISTICS SWITCH command.To issue the STATISTICS SWITCH command through the IBM Connect:Direct IUI, perform the followingsteps.

1. Select the STAT option of the Administrative Options Menu to access the Statistics Command panel.2. Select option FS on the panel to initiate the file pair switch.

Recording Statistics for Specific Record TypesThe STATISTICS ON/OFF command enables and disables recording of specific statistics record types.When you initialize the DTF, IBM Connect:Direct enables the recording of all record types unless youspecify the STAT.EXCLUDE initialization parameter. You can use the INQUIRE STATISTICS command tofind out which types are currently disabled.

Use the STATISTICS ON/OFF command prudently when excluding Statistics records logging becausesome types of records are critical for problem diagnosis. Do not exclude the following record types:

• CT – Copy Termination• PS – Process Submit• PT – Process Termination• RJ – Run Job

388 IBM Connect:Direct for z/OS: Documentation

• RT – Run Task• SW – Submit within Process• WO – WTO

Other record types are less critical and you can exclude them.

CAUTION: Excluding record types can make problem analysis and resolution more difficult.

The STATISTICS ON/OFF command has the following format and associated parameters.

Label Command Parameters

(optional) STATistics ON | OFF TYPE = (record type list)

The following parameter is required for the STATISTICS ON/OFF command:

Parameter Description

TYPE This parameter specifies the list of statistics record types whose recording isenabled or disabled. Use the 2-character identifier to specify record types. Theseidentifiers are in the table beginning on “Statistics Records” on page 325.

Excluding Statistics Logging through the Batch InterfaceTo use the STATISTICS ON/OFF command from the batch interface, perform the following steps.

1. Place your command in a batch job stream as described in IBM Connect:Direct for z/OS User Guide.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

Refer to “Recording Statistics for Specific Record Types” on page 388 for more information on whatnot to exclude.

Excluding Statistics Logging through the IUI InterfaceTo use the STATISTICS ON/OFF command from the IUI, perform the following steps.

1. Select the STAT option from the Connect:Direct Administrative Options Menu. The Statistics Commandscreen is displayed.

2. Select option EN to enable logging or option DI to disable logging. Supply the list of affected recordidentifiers in the area provided, and press ENTER.Refer to “Recording Statistics for Specific Record Types” on page 388 for more information on whatnot to exclude.

Notifying IBM Connect:Direct of Statistics File ArchivalThe STATISTICS ARCHIVED command notifies IBM Connect:Direct that the statistics file is archived. Itenables the system to erase and overwrite the file with new records.

When you specify STAT.ARCH.CONFIRM=YES in the DTF initialization parameters, IBM Connect:Directcannot reuse a statistics file pair until it receives confirmation that the archive is complete. TheSTATISTICS ARCHIVED command provides an additional means of sending this notification. Ordinarilyit is sent by the DGADARRT utility after the archive is done by a IBM Connect:Direct COPY Process, or bythe DGADARBT utility after the archive is done by a batch step.

The STATISTICS ARCHIVED command has the following format and associated parameters.

Label Command Parameters

(optional) STATistics ARCHived file pair number

Chapter 4. Administration Guide 389

The following parameter is required for the STATISTICS ARCHIVED command:

Parameter Description

file pair number This parameter specifies a number from 1–20 that identifies the statistics file forwhich archive notification is sent. This number is given as the relative number of thefile pair in the file pair list. The first pair in the list is file pair number 1.

Issuing Archive Notification through the Batch InterfaceTo use the STATISTICS ARCHIVED command from the batch interface, perform the following steps.

1. Place your command in a batch job stream as described in IBM Connect:Direct for z/OS User Guide.2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

Issuing Archive Notification through the IUI InterfaceTo use the STATISTICS ARCHIVED command from the IUI, perform the following steps.

1. Select the STAT option from the Connect:Direct Administrative Options Menu. The Statistics Commandscreen is displayed.

2. Select option CF, supply the number of the file pair for notification of archival, and press ENTER.

Managing the Transmission Control QueueIBM Connect:Direct stores submitted Processes in the Transmission Control Queue (TCQ). The TCQcontrols Process execution. The IBM Connect:Direct for z/OS User Guide contains information about howto submit Processes, how to control those Processes once they are in the TCQ, the logical queues thatmake up the TCQ, and the status values of Processes in the TCQ. The TCQ consists of two interdependentVSAM data sets:

• The Transmission Control Queue, or TCQ, is a Relative Record Dataset (RRDS) which contains an internalform of the Process language of each Process and status flags.

• The Transmission Control Index, or TCX, is an RRDS containing a single record. It contains bitmaps, thatindicate the availability of TCQ space.

The default size of the TCQ, as determined by the sample installation JCL, is 1000 records, but it can beas large as 4016 records if the sample TCX is used. The size of a Process can range from 1 to 43 records,depending upon the how many steps it contains. The average Process size varies by installation. If theaverage Process size is 5 records, the sample TCQ can contain approximately 200 Processes.

In order to use a TCQ with a capacity that exceeds 4016 records, the TCX must be defined with a recordsize and control interval (CI) size larger than those specified by default in the installation JCL. The IBMConnect:Direct for z/OS Configuration Guide and Program Directory for IBM Connect:Direct for z/OS containmore information about planning your space requirements.

Note: Both the TCQ and TCX can be defined with a CISIZE (Control Interval size) of up to 30,720 bytes.The maximum number of TCQ records that can be mapped by the maximum-sized TCX is 122,804.

To hold the maximum size Process (1 MB), the CISIZE of the TCQ must be at least 24 KB bytes.

Configure the TCQIBM Connect:Direct provides initialization parameters that allow you to configure the TCQ. Theseparameters fall into the following categories:

• Controlling startup—two parameters determine what the TCQ does with existing Processes:

– TCQ = WARM | COLD, whose default value of WARM specifies that all existing Processes in the TCQare retained. COLD requests that the TCQ be cleared of all processes.

390 IBM Connect:Direct for z/OS: Documentation

– CONFIRM.COLD.START = YES | NO, whose default value you must change to force the operator toconfirm the request for a COLD start before executing it.

• Controlling efficiency of the TCQ—the following parameters provide several flexible configurationoptions in this area.

– MAX.AGE lets you specify the number of days to wait before purging a Process. With this parameteryou can also manage the Wait and Hold queues by specifying which type of Process to purge (that is,those with a specific status) or the number of days to wait to purge for each status type.

– MAX.AGE.TOD used to change the system default of automatically purging the TCQ at midnight andwhenever IBM Connect:Direct is initialized. Optional.

– TCQ.THRESHOLD specifies when a warning is issued to indicate the TCQ is reaching capacity andProcesses may be deleted. It is also the auto-deletion threshold for the PR queue.

• Holding Processes—two parameters determine if submitted Processes are held.

– QUIESCE specifies whether or not IBM Connect:Direct holds Processes from execution.

Note: The QUIESCE parameter helps you in your efforts to clean up a TCQ, that has become corrupt.See Using the TCQ/TCX Repair Utility (DGADTQFX) for details.

– REQUEUE specifies whether to requeue a Process, that ABENDS or results in a return code greaterthan 4.

• Retaining Processes after Execution—set the PROCESS.RETENTION parameter to save a Process in thePR queue after it has executed. Then view or select completed Processes.

How to Troubleshoot the TCQIBM Connect:Direct provides several ways to recover from a system malfunction associated with a TCQproblem.

The TCQ/TCX Repair Utility, DGADTQFX allows you to solve corruption problems related to the TCQ/TCXdata sets without having to cold start the DTF and reinitialize the TCQ. The DGADTQFX batch programretains the original TCQ/TCX data sets used in production, and creates a new validated copy of the TCQby removing all invalid Processes. The DGADTQFX utility can also be used to create a TCQ and TCX forpre-version 4.6 IBM Connect:Direct. Processes that are larger than 64 KB (the pre-version 4.6 Processlimit) are removed from the new TCQ and TCX when the BACKLEVEL parameter is used.

Note: The DGADTQFX utility builds a new TCX/TCQ pair with increased CISIZEs to hold larger Processes.

Using the TCQ/TCX Repair Utility (DGADTQFX)The TCQ/TCX Repair Utility (DGADTQFX) can be used to help solve corruption problems related to theTCQ/TCX data sets.

Run the DGADTQFX utility in one of the following ways:

• Rebuild TCX mode, which creates a new TCX by using the current TCQ to indicate the existence ofProcesses.

• Use TCX mode, which creates a new TCQ using the current TCX to indicate the existence of Processes.When upgrading from Connect:Direct releases prior to 4.4, using TCX mode is recommended.

Note: Use different names to distinguish the original and new TCQ/TCX data sets in case you need to goback and reuse the original data sets.

The Rebuild TCX mode is the preferred mode for rebuilding the TCQ/TCX after encountering TCQcorruption problems, which cause U3083 abends.

CAUTION: The DGADTQFX utility is rebuilding the TCX based on Processes that remain in the TCQ.The utility will determine the highest Process number in the TCQ and will set the next availableProcess number to the next number. It is possible for this utility to reuse Process numbers.

Chapter 4. Administration Guide 391

The Use TCX mode is recommended for TCQs associated with systems running versions of IBMConnect:Direct prior to Version 4.4. Prior to Version 4.4, completed Processes were retained in the TCQand were not deleted.

The DGADTQFX program, located in $CD.SDGALINK, has one execution parameter for specifying thereport type.

Parameter Description

PARM= SUMMARY |DETAIL | BACKLEVEL |REMOVEPR

Specify SUMMARY to produce a report at the Process level.

Specify DETAIL to produce a report, which shows steps within each Process,such as RUN TASK, RUN JOB, SUBMIT, and COPY.

Specify BACKLEVEL to create a TCQ and TCX for pre-version 4.6 IBMConnect:Direct systems.

Specify REMOVEPR to remove all Processes on the PR queue.

Normally, you run DGADTQFX with IBM Connect:Direct shut down but you could run it in production. Thedata sets and reports created will be correct as long as no update activity to the input TCQ takes placewhile the utility executes. The program issues a warning message if the VSAM timestamp for the inputTCQ is changed during execution.

The return codes associated with the DGADTQFX utility are described in the following table.

Return Code Meaning

0 No errors were found in the input TCQ

4 At least one error was found and removed or a warning message was issued

8 A severe error occurred during execution and the utility was terminated

Initializing the DTF After DGADTQFX Has Found ErrorsIf errors were found and corrected when you ran the DGADTQFX utility, replace the original corrupteddata sets in use with the new data sets created by DGADTQFX. To allocate the new data sets to IBMConnect:Direct, use IDCAMS ALTER or regenerate the network map.

Using IDCAMS ALTER1. Shut down the DTF, if necessary.2. Rename the old TCQ and TCX to save the original data sets.3. Using ALTER, rename the new TCQ and TCX data sets using the original data set names.4. Initialize the DTF and specify the QUIESCE=YES initialization parameter.5. Use SELECT PROCESS to display the TCQ contents, and delete any unwanted Processes.6. Issue the MODIFY Sessions command to resume DTF operation.7. After you are confident that IBM Connect:Direct is operating normally with the new TCQ and TCX data

sets, delete the original TCQ and TCX datasets.

Regenerating the Netmap1. Shut down the DTF, if necessary.2. Execute the Unload Netmap utility, DGADNTLD.3. Change the names of the TCQ and TCX data sets in the unloaded member. The names are defined

within the LOCAL.NODE definition.4. REPRO the old network map data to preserve a copy of it for fallback purposes.5. Delete, define, and reload the netmap.6. Initialize the DTF and specify the QUIESCE=YES initialization parameter.

392 IBM Connect:Direct for z/OS: Documentation

7. Use SELECT PROCESS to display the TCQ contents, and delete any unwanted processes.8. Issue the MODIFY Sessions command to resume DTF operation.9. After you are confident that IBM Connect:Direct is operating normally with the new TCQ and TCX data

sets, delete the original network map, TCQ and TCX data sets.

DGADTQFX ExamplesThe following JCL samples are provided in $CD.SDGASAMP:

• DGAXTQF1, which runs DGADTQFX in Rebuild TCX mode. DGADTQFX will create new TCQ and TCX datasets and print a detailed report.

• DGAXTQF2, which runs DGADTQFX in Use TCX mode. DGADTQFX will use the current TCX data set toindicate the existence of TCQ Processes. The program will print a summary report.

• DGAXTQF3, which runs DGADTQFX in BACKLEVEL mode. DGADTQFX will create new TCQ and TCXdatasets and print a summary report. Processes larger than 64 KB are removed.

The following sample shows part of the JCL within $CD.SDGASAMP library member DGAXTQF1.

//*************************************************************//* *//* Run the TCQ FIX utility in "Rebuild TCX" mode. Create *//* new TCQ and TCX with any invalid contents of input *//* TCQ removed. Request detail-level reporting for *//* input and output TCQ: *//* *//*************************************************************//STEP2 EXEC PGM=DGADTQFX,PARM=DETAIL//STEPLIB DD DISP=SHR,DSN=CD.LOADLIB//SYSOUT DD SYSOUT=*//TCQIN DD DISP=SHR,DSN=CD.OLD.TCQ//TCQOUT DD DISP=SHR,DSN=CD.NEW.TCQ//TCXIN DD DISP=SHR,DSN=CD.OLD.TCX (not needed in this mode)//TCXOUT DD DISP=SHR,DSN=CD.NEW.TCX//TCQINRPT DD SYSOUT=*

You can accomplish tasks depending upon which DD statements are present in the batch JCL:

• If TCXOUT is present, Rebuild TCX mode is requested; otherwise, Use TCX mode is requested.• If TCQINRPT is present, an input TCQ report is generated; otherwise, it is not.• If TCQOUT is present, a new TCQ is created; otherwise, it is not. You can therefore analyze and report on

the input TCQ without creating any data sets.

Note: TCQOUT and TCXOUT must both be pre-allocated empty VSAM data sets.

DGADTQFX OutputThe sample reports shown in this section are a result of running DGADTQFX in Use TCX mode. The firstreport shows two invalid TCQ Processes, which were detected and skipped during the copy of the input

Chapter 4. Administration Guide 393

TCQ to the output TCQ. The second report lists all Processes in the input TCQ in sequential Processnumber order.

DGADTQFX Output TCQ Report (Summary)

Connect:Direct for z/OSDGADTQFX execution on 18 Mar 2003 14:58:16Mode: Use TCXOutput TCQ SummaryPName PNum Cur Step Submitter Node Other Node Stat UserID Submitted-------- ------- -------- ---------------- ---------------- ----- ------ ----------D3103UPR 4 STEP0108 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:08D3104UPR 5 STEP0103 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:14D3105UPR 6 STEP0103 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:17D3106UPR 7 STEP01 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:21D3107UPR 8 STEP01 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:24Processes Skipped SummaryPName PNum Cur Step Submitter Node Other Node Stat UserID Submitted-------- ------- -------- ---------------- ---------------- ------------- ---------D3101UPR 2 PLEX.JOE PLEX.TOM.TCP HO HI CBENN1 19 DEC 2002 11:08:45D3102UPR 3 PLEX.JOE PLEX.TOM.TCP HO HI CBENN1 19 DEC 2002 11:08:59Totals:Processes found in Input TCQ: 7Processes written to Output TCQ: 5Processes not copied to Output TCQ (skipped): 2STQF001E DGADTQFX ended; RC=04

DGADTQFX Input TCQ Report (Summary)

Input TCQ SummaryPName PNum Cur Step Submitter Node Other Node Stat UserID Submitted-------- ------- -------- ---------------- ---------------- ----- -------- ------------------D3101UPR 2 PLEX.JOE PLEX.TOM.TCP HO HI CBENN1 19 DEC 2002 11:08:45D3102UPR 3 PLEX.JOE PLEX.TOM.TCP HO HI CBENN1 19 DEC 2002 11:08:59D3103UPR 4 STEP0108 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:08D3104UPR 5 STEP0103 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:14D3105UPR 6 STEP0103 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:17D3106UPR 7 STEP01 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:21D3107UPR 8 STEP01 PLEX.JOE PLEX.TOM.TCP EX EX CBENN1 19 DEC 2002 11:09:24

Supporting DBCS and MBCS

Overview of DBCSSome languages have too many symbols for all characters to be represented using single byte codes. Forexample, the English language can be defined within a single byte range from 1-256, or x'00' throughx'FF'. The Korean and other ideographic languages contain several thousand characters. To create thesecoded character sets, two bytes are needed for each character.

The IBM Connect:Direct Double-byte Character Set (DBCS) support provides a mechanism for translatingASCII and EBCDIC DBCS data. DBCS support translates Single-byte Character Set (SBCS) and DBCS datain the form that is supported on the requested platform.

DBCS character representation differs between operating systems. Specifically, a mainframe representsdata in 8-bit EBCDIC code and a PC represents data in 7-bit ASCII code. For the mainframe environment,DBCS can be used exclusively within a file or be mixed with SBCS characters. Special character indicatorsexist to tell the difference between SBCS and DBCS characters. The special character indicators are shift-out (SO) and shift-in (SI), or x'0E' and x'0F' respectively for IBM mainframes. Shift-out denotes shiftingfrom SBCS to DBCS mode and shift-in denotes shifting from DBCS to SBCS mode. SO/SI combinations arenot required if DBCS is exclusive within a file. For the PC, the SO/SI characters are not recognized. In thisenvironment, DBCS is represented by setting the high order bit of the ASCII code. See the table in RULESfor correct mapping of DBCS characters by language.

394 IBM Connect:Direct for z/OS: Documentation

Note: A DBCS table can be extremely large and complex. Use the sample tables in this documentation asa reference only. They do not successfully translate all characters.

Translation TablesIBM Connect:Direct provides the following translation tables in both load module and source form. Theexecutable tables are located in $CD.SDGALINK and the source tables are in $CD.SDGASAMP. You cancopy and customize the source code format for your processing environment.

For more information on how to use these tables with the SYSOPTS parameter in the COPY statement, seethe Connect:Direct Process Language help.

Table Name Description

DGATXKSC host EBCDIC to ASCII KS5601

DGATKSCX ASCII KS5601 to host EBCDIC

DGATXKPC host EBCDIC to DBCS-PC Korean

DGATKPCX DBCS-PC Korean to host EBCDIC

DGATXJIS host EBCDIC to Japanese International Standard

DGATJISX Japanese International Standard to host EBCDIC

DGATXBG5 Chinese new host code to Chinese Big5

DGATBG5X Chinese Big5 to Chinese new host code

DGATXC55 Chinese new host code to Chinese 5550

DGATC55X Chinese 5550 to Chinese new host code

DGATJEFX Japanese host EBCDIC Katakana to ASCII

DGATXJEF ACSII to Japanese host EBCDIC Katakana

DGATGBKX GBK to Chinese new host code

DGATXGBK Chinese new host code to GBK

Customize Translation TablesYou can create and update the translation tables through a preprocessor that takes simple batch inputin a predefined format and creates output compatible with the assembler. You can then assemble andlink-edit the output to produce a translation table you can load.

Input to the batch preprocessor consists of six main parameters and the END parameter. All input beginsin column one. The following table defines the batch preprocessor parameters.

Parameter Required Default Format Definition

NAME No XLATE 8 characters Table name information

TITLE No DBCSTRANSLATIONTABLE

60 characters Table title information

DEFAULT No 0000 2 byte hexrepresentation

Default translation character

RULES No 80-FF 2 byte hexrepresentation

Language rules

SBCS No Standard 2 byte hexrepresentation

Single-byte character set translation table

Chapter 4. Administration Guide 395

Parameter Required Default Format Definition

DBCS Yes None 4 byte hexrepresentation

Double-byte character set translation table

END Yes None Terminates DBCS, SBCS, and RULESparameters

DBCScreates the double-byte character set translation table. This table translates all double-byte data duringa file transfer. This parameter has no default and is required. The DBCS parameter data begins in columnone and is terminated with the END statement.

The following example shows the syntax for the DBCS parameter.

DBCSf1f2,t1t2END

f1 denotes the first byte of the FROM DBCS character.

f2 is the second byte of the FROM DBCS character.

t1 is the first byte of the TO DBCS character.

t2 is the second byte of the TO DBCS character.

DBCS ExampleThe following example translates x'89A1' to x'B0ED', x'89A2' to x'B0EE', x'89A5' to x'B0EF', and so on tox'D37B' to x'C8F0'.

DBCS89A1,B0ED89A2,B0EE89A5,B0EF89A8,B0F089A9,B0F189AA,B0F289AB,B0F3D375,C8EED377,C8EFD37B,C8F0END

ENDis mandatory to terminate each of the following parameters:

• DBCS• RULES• SBCS

NAME=[tablename | XLATE]is an 8-character parameter for displaying table information in batch format. NAME is optional and is forinformational use only. If you use NAME, it must be the first parameter defined. If you use NAME withTITLE, NAME and TITLE must be the first two parameters defined. The default for NAME is XLATE.

The following example shows the syntax for the NAME parameter.

396 IBM Connect:Direct for z/OS: Documentation

NAME=DGATXKSC

The DGATXKSC table is provided in $CD.SDGASAMP.

TITLE=[title name | DBCS TRANSLATION TABLE]is a 60-character parameter for displaying table information in batch format. TITLE is optional and isfor informational use only. If you use TITLE, it must be the first parameter defined. If you use TITLEwith NAME, NAME and TITLE must be the first two parameters defined. The default for TITLE is DBCSTRANSLATION TABLE.

The following example shows the syntax for the TITLE parameter.

TITLE=HOST EBCDIC TO ASCII KS5601 TRANSLATION

The DGATXKSC table is provided in $CD.SDGASAMP.

DEFAULT=nnnncontains the hexadecimal representation you define as the replacement for invalid DBCS code points.This default character is displayed wherever a nontranslatable character is displayed in the data beingreceived. The default is 0000.

nnnn denotes the hexadecimal character defined to replace an invalid DBCS code point.

The following example shows the syntax for the DEFAULT parameter.

DEFAULT=FFFF

RULESdefines what constitutes a double-byte character for the defined language. RULES is only used whenreceiving a file from a platform other than z/OS or MVS, because the host cannot determine valid DBCScharacters without language rules. The default is any character within the range of x'80' through x'FF',meaning IBM Connect:Direct interprets any character within this range as the first byte of a DBCS pair.Both characters in the pair are translated to host DBCS. If specified, use the END statement to terminatethe RULES parameter.

Language Options TableThe following table identifies valid language options for the RULES parameter.

Language Option Range

KS5601 (Korean Standard) x'A1'-x'AC'

x'B0'-x'FD'

KOREAN (Old Style) x'81'-x'BF'

JAPANESE x'81-x'9F'

x'E0'-x'FC'

CHINESE (Traditional/Simplified and 5550) x'81'-x'FC'

BIG5 (Chinese) x'A4'-x'C6'

x'C9'-x'F9'

Chapter 4. Administration Guide 397

Language Option Range

x'01'-x'FF' user selectable

The following example shows the syntax for the RULES parameter.

RULESKS5601END

The KS5601 language option is in the DGATXKSC table, which is provided in $CD.SDGASAMP.

The following graphic represents the IBM Connect:Direct hexadecimal DBCS code points.

The following graphic represents the Korean Standard (KS5601) hexadecimal DBCS code points. The firstcharacter of each code point coincides with the range values in the Language Options Table.

398 IBM Connect:Direct for z/OS: Documentation

The following graphic represents the Korean hexadecimal DBCS code points. The first character of eachcode point coincides with the range values in the Language Options Table.

The following figure is a graphic representation of the Japanese hexadecimal DBCS code points. The firstcharacter of each code point coincides with the range values in the Language Options Table.

Chapter 4. Administration Guide 399

The following graphic represents the Traditional Chinese hexadecimal DBCS code points. The firstcharacter of each code point coincides with the range values in the Language Options Table.

The following graphic represents the Chinese (BIG5) hexadecimal DBCS code points. The first characterof each code point coincides with the range values in the Language Options Table.

400 IBM Connect:Direct for z/OS: Documentation

The following graphic represents the default hexadecimal DBCS code points.

RULES ExamplesThe following example translates all characters as DBCS that adhere to the KS5601 standard, or allcharacters that start with an x'A1' through x'AC' or x'B0' through x'FD'. Treat these characters as double-byte characters.

Chapter 4. Administration Guide 401

RULESKS5601END

The following example translates all characters as DBCS that adhere to the customized table. Treat allcharacters that start with x'90' through x'94' or x'B0' through x'B4' as double-byte characters.

RULES9091929394B0B1B2B3B4END

SBCScreates the single-byte character set translation table. This table translates all single-byte data duringa file transfer. The default translation table provided when the parameter is not specified, translates allEBCDIC characters in the range of x'00' through' x'FF' to its ASCII equivalent, within the range of x'00'through x'7F'. When receiving the file from a PC, the data is translated from ASCII to EBCDIC. Terminatethe SBCS parameter with the END statement.

If you define SBCS, you must begin all data in column one and only one hexadecimal character pair isallowed per line.

The following example shows the syntax for the SBCS parameter.

SBCSff,ttEND

ff denotes the FROM translation.

tt denotes the TO translation.

SBCS ExampleThe following example translates x'C1' to x'41', x'C2' to x'42', x'C3' to x'43', and so on.

SBCSC1,41C2,42C3,43C4,44C5,45C6,46END

CommentsComments allow you to include additional information in a batch preprocessor. Comments are availableas a convenience and do not affect IBM Connect:Direct. The format for a comment is an asterisk (*) incolumn 1, followed by the comment. The following figure is a sample comment with an asterisk in column1.

402 IBM Connect:Direct for z/OS: Documentation

* DEFAULT=FFFF instead of 0000.

Sample Preprocessor Input Data StreamThe following sample is the syntax for a preprocessor input data stream. The SBCS and DBCS tables areincomplete and would require many pages to produce a valid table.

NAME=MYTABLETITLE=SAMPLE TRANSLATION TABLERULES8081828384ENDSBCSC1,41C2,42C3,43C4,44C5,45C6,46ENDDBCS89A1,B0ED89A2,B0EE89A5,B0EF89A8,B0F089A9,B0F189AA,B0F289AB,B0F3D375,C8EED377,C8EFD37B,C8F0END

Sample JCL to EXECUTE the PreprocessorThe following sample JCL executes the preprocessor against the input source. The output produced bythe preprocessor is in assembler CSECT form and is input to the assembler. The assembled object is thenlink-edited to produce a load module.

The following JCL is contained in the member DGAJDBCS in the $CD.SDGAJCL library.

Chapter 4. Administration Guide 403

//JOBNAME JOB (ACCTN),’ADMINISTRATOR’,CLASS=A,// REGION=4098K,MSGLEVEL=(1,1),MSGCLASS=X//****************************************************************//*//* JCL TO CREATE DBCS TRANSLATE TABLE//*//* REPLACE THE FOLLOWING ENTRIES IN THE PROCEDURE STATEMENT//* BELOW WITH SITE DEPENDENT INFORMATION//*//* TABLE= NAME OF THE SOURCE TRANSLATE TABLE//*//****************************************************************//BLDDBCS PROC TABLE=XXXXXXXX,CDPREF='$CD',TEST=NOTEST,RENT=RENT//****************************************************************//* STEP1 CREATE ASSEMBLER OUTPUT FROM PRE-PROCESSOR INPUT//****************************************************************//STEP1 EXEC PGM=DMDBCSPR//STEPLIB DD DSN=&CDPREF..SDGALINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSTERM DD SYSOUT=*//SYSOUT DD SYSOUT=*//SYSABEND DD SYSOUT=*//CDTABIN DD DSN=&CDPREF..SDGASAMP(&TABLE),DISP=SHR//CDTABOUT DD DSN=&&SRC,DISP=(,PASS),SPACE=(CYL,(1,1)),// DCB=(BLKSIZE=1600,LRECL=80,RECFM=FB,DSORG=PS),// UNIT=SYSDA//****************************************************************//* STEP2 ASSEMBLE OUTPUT CREATE BY PRE-PROCESSOR//****************************************************************//STEP2 EXEC PGM=ASMA90,// PARM='OBJECT,NODECK,XREF(SHORT),&RENT,&TEST,USING(WARN(0X// ),NOMAP),FLAG(NOCONT)'//SYSLIB DD DSN=&CDPREF..SDGASAMP,DISP=SHR// DD DSN=SYS1.MACLIB,DISP=SHR// DD DSN=SYS1.MODGEN,DISP=SHR//SYSTERM DD SYSOUT=*//SYSPRINT DD SYSOUT=*//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(10,5))//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(10,5))//SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(10,5))//SYSLIN DD DSN=&&OBJ,UNIT=SYSDA,DISP=(,PASS),SPACE=(TRK,(5,5)),// DCB=(DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=3120)//SYSIN DD DSN=&&SRC,DISP=(OLD,DELETE)//****************************************************************//*

Information on IBM Connect:Direct Processes, including how to use the table created from the previousJCL sample using the COPY statement, is available at the Connect:Direct Process Language help.

Alternate Logic Applied to DBCS and SBCS Translation (LOGIC =B | (B,RC) )An alternate form of translation for data that contains both double byte and single byte data is provided. Itsupports the translation of mixed mode files using selectable translation tables.

The normal way that data is described, when a file contains both double and single bytes characters, isthrough the use of the shift-in (SI) and shift-out (SO) sequences. By default shift-out is normally 0x0Eand shift-in 0x0F, but these values can be configured. The support within the Connect:Direct productsallows for the shift-out and shift-in values to be specified if they are different than 0x0E and 0x0F. Recordboundaries are honored. SI or SO strings do not span record boundaries.

For more information on how to implement this alternate form of translation using the LOGIC=B|(B,RC)subparameter in the SYSOPTS parameter in the COPY statement, see the Connect:Direct ProcessLanguage help.

It is expected that data which contains DBCS and SBCS strings will use alternating SO, SI sequences todefine the start and end of each string. So a typical file record might look like:

SI single bytestring

SO double bytestring

SI single bytestring

404 IBM Connect:Direct for z/OS: Documentation

Any exception to this, such as two SI sequences without an intervening SO sequence, is consideredinvalid. When an invalid sequence is encountered, certain data strings are ignored and all translation isstopped, depending on the sequence of SI and SO markers.

Alternate Translation allows for the file to be completely transferred and an error (message SCPA074Iwith return code 8) noted at the completion of the transmission. You also have the option of usingLOGIC=B|(B,RC) to specify a different return code within the range of 1-254 for this specific message.If you specify LOGIC=B without specifying a return code, the default return code of 8 is used.Connect:Direct will use the specified return code when issuing the SCPA074I message. The followingcoding examples show how to specify a return code for SCPA074I and the expected results for each:

SYSOPTS="DBCS=(EBCXKSC,0E,0F,LOGIC=(B,4))"

In the example above, if the DBCS transfer produces the SCPA074I message, the return code generatedwill be 4.

SYSOPTS="DBCS=(EBCXKSC,0E,0F,LOGIC=(B,254))"

In the example above, if the DBCS transfer produces the SCPA074I message, the return code generatedwill be 254 or X'FE'.

See the Connect:Direct Process Language help for more information about specifying a return code for theSCPA074I message.

RulesThese rules take into account any combination of SI and SO sequences, even ones with no interveningbyte string. Since these rules are dependent on future sequences of SO or SI characters within the file.

The rules follow this truth table:

Note: SI still means Shift In to single byte mode and SO means Shift Out to double byte mode. However,no translation will be done if the SI, SO sequences are invalid.

PRIOR NEXT

SI SO

SI Do not translate the remainder ofthe record

SBCS translation until SO occurs

SO DBCS translation until SI occurs Do not translate the remainder ofthe record

For PAD specification, if EBCDIC to ASCII translation or ASCII to EBCDIC translation, PAD characterwill replace SI and SO characters for the entire file unless an invalid shift sequence is found. When aninvalid shift sequence is found in a record, the shift characters are left as is and the PAD character is notsubstituted from that point to the end of the record.

1. Each record is evaluated independently. All translation decisions are made on each individual record.SI/SO byte strings are not evaluated across record boundaries.

2. A record may or may not start with a shift character. If a shift character is not found in the first byteof the record, the byte string is considered SBCS data until the next shift character in that record isdiscovered.

3. If an invalid shift sequence is discovered, stop translation and send the record in a mixed format withthe first part translated and the last part in the original, untranslated form.

4. If a PAD character is specified, use it for those portions of the record that are translated. Untranslatedportions of the record will be left with any SI or SO characters as is.

Chapter 4. Administration Guide 405

5. End of record that occurs without a SI or SO sequence means data that precedes the end of file istreated as normal DBCS or SBCS data for translation depending on the previous shift state.

MBCS ConversionsMultibyte Character Set (MBCS) support enables you to convert between Unicode and other code setssupported on the z/OS platform. To perform an MBCS conversion, use the CODEPAGE parameter of theCOPY statement FROM and/or TO SYSOPTS clauses.

You can perform MBCS conversions in the following ways:

• Perform a conversion on the FROM node only and then send the Unicode file to the TO node.• Send a file to the TO node and let that node perform the conversion.• Perform a conversion from one z/OS compatible code set to a Unicode code set supported on the local

node (specified in the FROM clause CODEPAGE parameter). Then send the encoded Unicode file to theremote node to be converted to another z/OS compatible code set.

Instead of requiring that each IBM Connect:Direct node provide the capability to convert from anysupported character set to any other supported character set, the recommended approach is to convertthe original character set to a common intermediate form (UTF-8 or UCS-2) on the local node, transmitthe intermediate form to the remote node, and then perform the conversion to the final desired characterset on the remote node. This way, each node is responsible only for conversion between the Unicodeencoding and the character sets relevant to and supported by the node.

Note: To convert between Unicode (ISO 10646) and other code sets, IBM Connect:Direct makes callsto system routines which are part of the optional z/OS Language Environment component - NationalLanguage Support. Verify that your z/OS installation supports the code set conversions specified in theProcess language.

When you output an MBCS file, it should allow for a flexible output record length, thus z/OS files shouldbe specified as Variable Format (RECFM=VB). Also, to allow for a possible increase in data length dueto conversion, the LRECL of the receiving file must be larger than the LRECL of the sending file. In theexample shown below, the LRECL of the sending file is 80.

STEP01 COPY FROM (PNODE DISP=SHR - DSN=TEST3.MBCS0001.IBM930 - SYSOPTS="CODEPAGE=(IBM-930,UTF-8)" ) - TO (SNODE DISP=(,CATLG) - UNIT=SYSDA SPACE=(CYL,(3,3)) - VOL=SER=USER01 - DCB=(RECFM=VB,LRECL=90,BLKSIZE=24000) - DSN=CHICAGO.MBCS0001.IBM1047 - SYSOPTS="CODEPAGE=(UTF-8,IBM-1047)" )

For this particular MBCS conversion, the receiving file was successfully created by specifying LRECL as 90.Other conversions may require a larger value to avoid an SVSJ032I error during the Copy. If RECFM=VB,BLKSIZE for the output file must be at least as large as LRECL+4.

To display the CODEPAGE specification for a COPY step in a Process after step completion, use the SelectStatistics command for an SY Statistics record. Each node involved in a COPY generates an SY recordcontaining the SYSOPTS relevant to that node.

Except for syntax, the CODEPAGE parameter is not validated when the Process is submitted. However,when the Process is executed, an MBCS001E error will result on the node attempting the conversion if aninvalid code set is specified.

For additional Process examples, search on MBCS Conversion in the Connect:Direct Process Languagehelp.

406 IBM Connect:Direct for z/OS: Documentation

Performance Tuning

Analyzing TCP/IP PerformancePerformance problems occur when a system and its network are not operating as effectively as theyshould as indicated by slow response times and a decrease in users’ productivity. These problems can beintermittent or can indicate a growing strain pointing to capacity issues. Causes can be multifaceted andinclude both hardware and software origins or can be quickly solved with proper configuration settings.

Because of the multi-faceted nature of TCP/IP issues, this section serves as an analysis tool by providinga checklist of possible factors. By properly analyzing and defining the problem in terms of a set ofsymptoms and potential causes, you can either solve the performance problem yourself or can providesupport with documentation.

When you analyze performance, you must also consider your organization’s priorities, such as thefollowing goals:

• To maximize throughput in order to achieve the maximum data transfer rate• To “fill the pipe” and run at full capacity

As you test and fine-tune settings to address specific factors in a problem area, record the results andnote any unusual interactions or behavior. You may want to change company standards and create achecklist to accommodate new procedures or settings.

General TCP/IP ProblemsThere are many causes of general TCP/IP problems.

This table lists TCP/IP problems and factors to consider:

Problem Factors to Consider

Host Issues • Inadequate memory• Slow disk speed/contention• Slow channel speed/contention• Excessive workload• Inadequate processors/slow processor speed• Inefficient performance groups and dispatch priorities• Resource competition among applications on same system• Resource competition among LPARs

Chapter 4. Administration Guide 407

Problem Factors to Consider

Network issues At the link level, look for:

• Link errors• Hardware or interface errors• Latency problems• Collisions

At the IP layer, look for:

• Discarded packets• Reassembly failures• Whether the DoNotFragment Bit is set• TOS (TCP/IP Type of Service) such as Telnet with low delay (interactive

priorities overriding batch transmissions)• Small MTU/MSS (Maximum Transmission Unit/Maximum Segment Size)

Note: If the MTU is too small, inefficiency results whereas if it is too large,datagram fragmentation may result.

Network issues(cont'd)

At the TCP layer, look for:

• Segments retransmitted• Connections reset• Frequency of ACKs• Window size too small

In the TCP/IP stack, look for:

• The maintenance level of the two TCP stacks involved• The use of PORT and 1364 TCP CDSTC NODELAYACKS which may delay ACKS• The values of TCPSENDBFRSIZE and TCPRCVBFRSIZE in the TCP/IP PROFILE

data set

Note: These values affect all applications using the TCP/IP protocol whereasthe V2.BUFSIZE initialization parameter (see below) affects the operation ofthe IBM Connect:Direct application only.

• Whether the value set for PATHMTUDISCOVERY is an MTU size of 8992 (thedefault)

In the IBM Connect:Direct global initialization parameters file, look at:

• “V2.BUFSIZE = (maximum transmission buffer size, TCP/IP send/receivebuffer size)” on page 507–The default is V2.BUFSIZE=(32K,128K). Adjust ifneeded based on the bandwidth and speed of your communications lines.

• DEBUG–Make sure this setting is 00000000 so that internal traces are turnedoff.

• “TCP.API.TIMER = 00:00:00 | hh:mm:ss” on page 501–To reduce the numberof hung sessions, specify this keyword. Set this value to at least 20 minutesand specify TIMEOUT=YES on IUI signon panels for individual users. Sessionwaits before timing out and exiting.

408 IBM Connect:Direct for z/OS: Documentation

Problems Involving Executing IBM Connect:Direct ProcessesThis table lists factors to consider if a IBM Connect:Direct Process is executing inefficiently.

Note: Because FTP is a utility program integrated into the TCP stack (thus running at the dispatch priorityof the TCP stack), FTP may transfer data at a faster rate than an external application when sendinga single file from the same source to the same destination. The only time an external data transferapplication exceeds the transfer rate of FTP is when parallel data transfers take place between the samesource and destination. Using parallel data transfers between the same source and destination is howmost large production environments operate.

Factors to Consider Suggestions

Are you using compression? If so, what type? • Compression is generally unnecessary unless youuse a slow line. Send data in its original state.

• If you use extended compression and wantto see the effects of changing the defaultvalues for the parameters related to extendedcompression, see Increasing Throughput andDecreasing CPU Utilization.

Are you using checkpoints? If so, what is theinterval?

On a fast link make this interval large, for example,100M.

Are you sending text or binary files? When comparing IBM Connect:Direct with FTP,send files only in Binary mode with both IBMConnect:Direct and FTP. Binary mode must be usedwith Text files because FTP strips trailing blanksand sends only a partial file.

Note: IBM Connect:Direct only sends completefiles unless sending HFS files, where trailing blankscan be stripped.

What does the file structure look like? To speed up the transfer, use a larger blocksize.

Are you using striped extended-format data setsfor files that have large amounts of data or in whichtime is of the essence?

Depending on the number of stripes, you could seea dramatic increase in the I/O rate.

Can you break down the Process so as to sendmultiple files at once using IBM Connect:Direct'sparallel session capabilities?

For testing purposes, set the PARSESS parameterin the network map to at least 10 then submit 10file transfers in IBM Connect:Direct and 10 in FTP.After verification, change the PARSESS value to fityour environment.

Are you changing DCB attributes? Avoid giving the sending and receiving data setsdifferent DCB attributes since that forces thetransfer to "record mode," which increases CPUutilization and TCP or SNA I/O.

How to Improve BSAM Data Transfer RatesTo optimize BSAM sequential data set transfer rates, take one or more of the following approaches:

• If MAXSTGIO is currently defined in the initialization parameter file, review the setting and considersetting it to the 1 MB default or greater. To fine-tune and set the Number of Channel Programs (NCP) inthe DCB parameter of the COPY statement, include the second positional parameter as well.

• Increase the block size when it is advantageous to do so. Make the block size of a disk data set closeto (but not more than) half-track blocking (27998 for non-extended 3390 disk data sets or 27966 forextended 3390 data sets). This improves performance by increasing the number of bytes transferred

Chapter 4. Administration Guide 409

per I/O. For example, when transferring a data set with an LRECL of 80, it takes much longer to transfer27920 bytes in 349 blocks (BLKSIZE=80) than in 1 block (BLKSIZE=27920).

Note: Exceeding half-track blocking on disk wastes a significant amount of storage capacity withoutimproving the transfer rate.

For tape-to-tape transfers, a larger block size improves both performance and capacity. For disk-to-tapetransfers, the I/O performance benefit of reblocking to an LBI block size (> 32760) may be outweighed bythe CPU performance hit of transferring the data set in "record mode."

Troubleshooting BSAM Data TransfersData transfer rates using BSAM vary significantly from run to run even on the same system. For example,even with a high NCP, the transfer rate deteriorates when the I/O subsystem is moderately busy. Ifproblems should occur, review these factors:

• The REGION specified on the job card. With the higher number of I/O buffers comes the risk that if toomany Processes run simultaneously, the above-the-line storage can be exhausted. To prevent out ofstorage abends, review both the MAXSTGIO initialization parameter and the job's region.

• The number of concurrent transfers occurring on one DTF, even when all system components (CPU,DASD, CU, CHPID or network) run below capacity. For example, where a single transfer attains a transferrate of 76 MB per second, two concurrent transfers potentially reduce it to 66 MB per second for eachtransfer, three transfers to 58 MB per second, and 4 transfers to 52 MB per second.

• Hardware caching. When you run the same test case multiple times, usually the first runs slower thansubsequent runs. For example, the initial transfer rate might be 38 MB/second, which increases to 75MB/second for the second and subsequent runs.

• Network. The transfer rate varies widely according both to the speed of the network and the volume oftraffic on it.

• Data set's device, CU, and CHPID configuration, speed, and how busy they are.• CPU speed, and how busy it is (sometimes a limiting factor).• Compression. Compression sometimes slows down the transfer due to extra CPU use.

Problems Involving CheckpointsIf the value specified for the checkpoint interval either as an initialization parameter or in the TO clauseof a COPY statement is too small, it can significantly reduce transmission speed. Since the purpose ofcheckpointing is to save time in a restart, it is usually unnecessary to have a checkpoint interval thattranslates to less than a second of transmission time. A checkpoint interval that translates to 5 seconds oftransmission time between checkpoints is normally more than adequate. For example, if the transmissionrate to the other node is typically 10 MB/second, and you desire to lose no more than 5 seconds oftransmission time in a restart, then you would set CKPT=50M.

Increasing Throughput and Decreasing CPU UtilizationDepending on your company's computing environment, IBM Connect:Direct for z/OS provides a variety ofmethods to improve how efficiently your system is running, including the following:

• The Compression Control Feature, which allows you to control the type of compression used betweennodes

• Extended compression for environments using slow lines and high CPU capacity• The zIIP exploitation feature, which takes advantage of System z Integrated Information Processor

(zIIP) hardware to free up the general purpose processor resulting in potentially greater performanceand cost-competitiveness when compared with less efficient and more complex distributed networksolutions

In addition, if you are using Connect:Direct Secure Plus, there are other factors you should take underconsideration to fine-tune performance in this area.

410 IBM Connect:Direct for z/OS: Documentation

Compression Control FeatureThe Compression Control Feature (CCF) allows you to control the type of compression used betweennodes, that is, standard versus extended, and how compression is used on a node, that is, whether theselected compression type is required, may be used, or is not allowed at all. This control may be forcedglobally by the PNODE or negotiated by the SNODE. Global compression control settings are specified inthe initialization parameters, whereas settings for specific nodes are specified in the adjacent node entryfor those nodes.

Because this feature overrides compression settings specified in a Process, its default settings allow bothtypes of compression so that the Process determines the type of compression that will be used (standard“COMPRESS” or extended “COMP EXT”).

When control of compression is being exercised, the PNODE always applies its rules to the Process andthen attempts negotiation. Negotiation is not performed if the other node does not have the CCF codeinstalled. (The node having Process control is in charge in this case.)

Where a partner node also has CCF installed, then the two nodes will negotiate the type of compressionthat will be used. If one node says that compression must be used and the other says that it is notallowed, then the step will fail, causing an IMPASSE situation (SCPA994I). Also, if one node says FORCEEXT and the other replies FORCE STD, this is also an IMPASSE situation.

The parameters that govern compression control come from either or both the following initializationparameters and network map parameters:

• Initialization parameters

– COMPRESS.EXT– COMPRESS.STD– COMPRESS.NETMAP.OVERRIDE– COMPRESS.NEGO.FAIL

• Network Map parameters

– COMPRESS.EXT– COMPRESS.ST– COMPRESS.STD.PRIMECHA

The CCF initialization parameters are refreshable, so they may be changed at any time withoutrequiring the DTF to be recycled. When you do make changes to these initialization parameters, yourchanges will cause global overrides to Processes on your system(s). For example, where standardcompression is being used in Processes, if the initialization parameters are changed to specifyCOMPRESS.STD=DISALLOW, none of your Processes will use standard compression (as long as netmapoverrides are disallowed or the node definition does not contain compression control keywords).

If you want to put the netmap compression control keywords into effect, you have to specify values forthose keywords in the ADJACENT.NODE definitions because they do not have default values.

For example, if the netmap is changed for a node (or nodes) to specify COMPRESS.EXT=FORCE, then allProcesses that run on that node will behave as if COMP EXT was specified in each COPY step.

Because of situations such as these, it is important for you to contact your partners to discuss howcompression will be handled between the two IBM Connect:Direct systems to avoid IMPASSE copyfailures.

CPU Usage ExamplesYou have several options for controlling compression on nodes that give you flexibility in determiningwhether to spend CPU cycles on compression on a global or node-by-node basis.

Stop Using CompressionTo completely stop using compression, specify the following in the initialization parameters file:

Chapter 4. Administration Guide 411

COMPRESS.EXT=DISALLOWCOMPRESS.STD=DISALLOWCOMPRESS.NETMAP.OVERRIDE=DISALLOW

These values will prevent compression from being performed, and will not allow any netmap entries tooverride the compression controls with regards to Processes under this node's control.

If the partner node(s) have CCF, then they will respond to these negotiation specifications by eitherterminating compression, or by sending an SCPA994I, RC=8 message to show that their system specifiedFORCE as one of the compression types.

If the partner node does not have CCF, compression will be stopped only when this node is the PNODE(with the exception of PRECOMP files, which are precompressed files). If this system is the SNODE, thena message will be written to the RPLERRCK trace file when it is forced to do compression because thePNODE does not have CCF.

Prevent Standard CompressionTo prevent only standard compression, specify the following:

COMPRESS.STD=DISALLOW

COMPRESS.NETMAP.OVERRIDE=DISALLOW

In this case, only Processes specifying COMPRESS will be affected on this node. If the partner node hasCCF, then all Process steps that specify COMPRESS will be forced to no compression. However, if thepartner has specified COMPRESS=FORCE, then the step will fail with an SCPA994I, RC=8 message.

When a partner node is the PNODE and does not have CCF, then the compression specified in theirProcess will be performed. If the compression that is being done is disallowed on this node, then the nodewill write a message to the RPLERRCK trace file to note the situation.

Control Compression on a Node-by-Node BasisTo control compression on a node-by-node basis, you can specify the following initialization parameter (orsimply allow the parameter to default):

COMPRESS.NETMAP.OVERRIDE=ALLOW

You can then set the netmap compression parameters for each node as needed to allow extended and/orstandard compression.

You can also set up the reverse situation on a node-by-node basis, where only certain nodes areprevented from using compression. In this case, specify COMPRESS.NETMAP.OVERRIDE=ALLOW in theinitialization parameters file and specify the following netmap parameters for the nodes that will not usecompression:

COMPRESS.EXT=DISALLOWCOMPRESS.STD=DISALLOW

Using Extended CompressionTCP/IP connections accommodate greater bandwidth to transfer large files than older technologieseliminating the need to compress data. Data can be sent in its original state saving both time and theneed to decompress data once it has been transferred. However, if you have a slow line and high CPUcapacity, compression may be warranted. Under other conditions, compression consumes a lot of CPUand slows transfer rates considerably while giving little if any return given the cost of CPU time.

412 IBM Connect:Direct for z/OS: Documentation

Different Methods of Using Extended CompressionYou can compress and store files in ZLIB-compressed format using one of the following methods:

• On a global basis using the Extended Compression (ECZ) initialization parameters. If you alwaystransfer the same type of data, you may benefit by changing the global default values of the extendedcompression initialization parameters.

• On a Process basis using the EXT parameters in the COPY statement. If you send a variety of data types,it is probably more efficient to retain the default values of the initialization parameters and overridethem on a Process-by-Process basis using the COPY statement. For information on overriding theextended compression parameters in the COPY statement, see the Connect:Direct Process Languagehelp.

• Through the DGASACMP batch utility. This option allows the CPU consumption, or overhead ofextended compression, to be offloaded from IBM Connect:Direct to the standalone utility. The CPUtime consumed by this utility can be much greater than that consumed by IBM Connect:Direct becausethe DGASACMP utility must use record mode compression whereas IBM Connect:Direct can use blockmode compression. You can also use the DGASACMP batch utility to decompress the data and store itin its original format on the remote node where compressed data has been sent. The DGASACMP utilityproduces a report, which shows how much the data was read, written, compressed, and how long ittook to compress so you can determine the benefits of changing the default values of the extendedcompression parameters.

Changing the Values of ECZ ParametersThe effects of changing the default values for the ECZ.COMPRESSION.LEVEL, ECZ.MEMORY.LEVEL, andECZ.WINDOWSIZE extended compression parameters are not always predictable and can significantlyincrease CPU utilization. The default values for the three parameters produce very good results for awide variety of data types. Typically, it is only beneficial to change these default values if line speeds arelimited, data is repetitive, and CPU is available.

zIIP Exploitation FeatureThe zIIP Exploitation Feature (ZEF) is designed to offload CPU time to the System z IntegratedInformation Processor (zIIP), a special-purpose processor integrated into the System z server platforminfrastructure. By freeing up the general purpose processor (CP), the efficiency of environments whereCPU-intensive activities are being performed, such as ZLIB compression and SSL/TLS encryption, can besignificantly enhanced.

zIIPs execute programs that are structured to operate under control of z/OS-preemptable enclave servicerequest blocks (SRB). An enclave is a z/OS construct that allows a unit of work or transaction to beassigned a goal by the z/OS Workload Manager (WLM). If a program can operate under control of anenclave SRB, then it can be made eligible to run on a zIIP processor. The COPY operation, which is thecore operation of IBM Connect:Direct for z/OS, uses multiple phases in a pipeline to copy data fromsource to destination. Because some of these phases are CPU-intensive, they are good candidates forzIIP-eligible work.

Requirements to Use the zIIP Exploitation FeatureThe ZEF feature requires the following:

• Your System z must have one or more online zIIP processors.• You must be running z/OS 1/10 or later.• You must activate ZEF by performing one of the following actions:

– Add the ZIIP parameter to your global or local initialization parameter file. See “ZIIP = NONE |EXTCOMP | SSLTLS | ALL | PROJECT” on page 509 for a complete description of all settings. Becausethis parameter is not refreshable, you must restart IBM Connect:Direct to activate the ZEF feature.

Chapter 4. Administration Guide 413

– Use the MODIFY command and specify the ZIIP setting you want to use. See “IBM Connect:DirectMODIFY Command” on page 449 for more information.

Choosing the Appropriate ZEF SettingThe default value for the ZIIP parameter is NONE meaning that no enclave SRBs will be created and so noCPU time will be offloaded to a zIIP.

To offload all eligible activities to zIIP, you can select the ALL setting. These activities include allSSL/TLS encryption and decryption and extended compression and decompression performed duringCOPY steps. To check the results of using the ZEF feature, you can check the Copy Termination andProcess Termination (PT) records in SELECT STATISTICS.

In the following example, no zIIP processor was online, so all work was done under a CP and is shown inthe Time on CP field and no time (0) is shown in the Time on zIIP field. The zIIP Qualify time indicates theamount of time that could have been processed on the zIIP, had one been available 100% of the time itwas needed. If work executes on a zIIP processor in a fraction of the time it takes on a CP, then the walltime for the entire process can be estimated as (Time on CP – zIIP Qualify) + (zIIP Qualify * fraction). Thefraction is needed because the zIIP Qualify time is normalized to standard processor speed (that is, thefraction is the normalization factor). For more information on how these new IBM Connect:Direct statisticsare calculated, see “Additional Information on How Time is Calculated for Statistics” on page 414.

================================================================================CD.ART SELECT STATISTICS 06.21.2011 ================================================================================ ________________________________________________________________________________Function => Process Term Start Time => 16:17:03 Process Name => ZIIP1 Stop Time => 16:17:06 Process Num => 1.. Comp Code => 00000000 Comp Msg => SVTM100I Userid => EPETE1 Job Name => EPETE1 Job ID => TSU58526 Secondary Node => CD.BOB Time on CP => 00:00:13.449 Time on zIIP => 00:00:00.000zIIP Qualify => 00:00:10.598 ___________________________________________________________

You can project how much time could be offloaded to a zIIP without actually using the zIIP. If a zIIPprocessor is online, you can specify the PROJECT setting for the zIIP initialization parameter. All activitieswill continue being dispatched to the CP. If there is no zIIP processor online, there is no differencebetween the PROJECT and ALL settings.

To segregate extended compression and encryption activities, you can use the EXTCOMP setting tooffload only extended compression and decompression CPU time to a zIIP or the SSLTLS setting to offloadonly SSL and TLS data encryption and decryption CPU time.

Potential Issue When Using ZEFBecause the ZEF feature does not constrain which SRBs are offloaded to zIIPs when ALL is specified, allavailable zIIPS could easily be dominated by IBM Connect:Direct when multiple concurrent COPY stepswith extended compression are executing. To allow zIIP-eligible work to be executed on a CP if all zIIPsare in use, make sure to set the IEAOPTxx parameter, IIPHONORPRIORITY, to YES. For more information,see IEAOPTxx (OPT parameters) in MVS Initialization and Tuning Reference (SA22-7592) or IEAOPTxx(OPT parameters) for the online information center.

Additional Information on How Time is Calculated for StatisticsNote: IWMEQTME is a Workload Management (WLM) service documented in z/OS MVS Programming:Workload Management Services. For more information, refer to document number, SA22-7619.

The three new time-related statistics are derived as follows:

414 IBM Connect:Direct for z/OS: Documentation

• Time on CP = (IWMEQTME CPUTIME) – (IWMEQTME ZIIPTIME)• Time on zIIP = (IWMEQTME ZIIPTIME)• zIIP Qualify = (IWMEQTME ZIIPQUALTIME)

If the installation has no zIIP processors:

Time on zIIP (IWMEQTME ZIIPTIME) = 0

Therefore, Time on CP = (IWMEQTME CPUTIME) – 0

However, regardless of whether the installation has a zIIP processor:

Time on CP (IWMEQTME CPUTIME) – (IWMEQTME ZIIPTIME) + Time on zIIP (IWMEQTME ZIIPTIME) =(IWMEQTME CPUTIME)

The (IWMEQTME ZIIPTIME) and (IWMEQTME CPUTIME) times in the Process Termination record exampleabove will be the same (except for rounding errors) as reported by SMF and RMF for the enclave. But forstep statistics reported in COPY and RUN TASK records, times are "slices" of the enclave times and willadd up to slightly less than the corresponding Process Termination record times. These differences shouldbe negligible. This occurs because there is a small amount of between-step processing charged to theenclave that is not charged to any particular step. All of the between-step time is CP time; none is zIIPqualified.

Because SSL and TLS handshakes occur before an enclave is created, their CPU time is not reported inany enclave time.

Because IBM Connect:Direct reports zIIP-qualified time, not zIIP-eligible time, the IEAOPTxx parametersetting for PROJECTCPU has no effect on the times in IBM Connect:Direct statistics. However, ifPROJECTCPU=NO, there may be nothing in SMF or RMF to compare IBM Connect:Direct statistics to.

Considerations When Using Connect:Direct Secure PlusWhen using Connect:Direct Secure Plus, be aware of the following :

• CPU utilization increases dramatically with every increase in the length of the encryption key. Use thelowest level of encryption allowed by your security policy.

• Whenever possible, use an encryption key that is supported in the z/ hardware (3DES or AES128).• Even though extended compression is not recommended for high speed networks, using extended

compression with files that compress well (80-90%) can reduce total CPU utilization, especially if theencryption key is not implemented in the hardware.

• If Connect:Direct Secure Plus is being used between two Connect:Direct for z/OS nodes (from Version5.0 to Version 6.1 ), but not all files must be encrypted, consider using one of the following options:

– Specify OVERRIDE=YES on the remote node record in the Connect:Direct Secure Plus parameter fileand SECURE=OFF in the PROCESS statement.

– Specify OVERRIDE=YES on the remote node record in the Connect:Direct Secure Plus parameterfile and SECURE = (ENCRYPT.DATA=N) in your PROCESS or COPY statement. ENCRYPT.DATA=N tellsIBM Connect:Direct to not encrypt the actual file data being copied but rather just the control blockinformation, such as userid or password, used to establish a session.

Note: Both trading partners must support this capability.• If Connect:Direct Secure Plus is being used between two Connect: Direct for z/OS nodes (Version 6.2 or

later), all files will be encrypted:

– Encrypt.Data will be ignored as it has been deprecated from release 6.2 and it will always be treatedas Encrypt.Data=Y for all nodes (local and Adjacent) so it will always encrypt the data.

– Process/Step override (Secure = (Encrypt.Data=Y|N)) will not have any impact on process. It will beignored. No error message will be issued. Informational messages (CSPA051I and CSPA052I) will beissued in JESMSGLG.

– With cross version nodes, encryption honors the prior release settings. In other words, from version6.2, with cross version (lower version) it will work as lower node has requested for Encrypt.Data.

Chapter 4. Administration Guide 415

Using zFBA for File TransferLarge file transfers can cause performance issues. You can improve large file transfer performance byusing the zFBA feature to transfer large files between Connect:Direct zOS and Connect:Direct UNIX.

Utilizing the zFBA feature you can improve performance for large file transfers between Connect:DirectzOS and UNIX because there is minimal TCPIP stack usage in the transfer. This can significantly decreasethe CPU utilization in both the Connect:Direct zOS and TCPIP address spaces, as well as decrease thetransfer duration.

You must ensure that a wide data bandwidth is in place to allow zFBA devices to maximize benefit fromthe interface. Smaller files will not benefit from this interface as performance will likely not improve;therefore, it is recommended that you not use the zFBA feature to process smaller files.

For additional information, see z/OS MVS Programming: Authorized Assembler Services Guide,SA23-1371-00 zOS FBA Services

How zFBA works with IBM Connect:DirectIBM Connect:Direct utilizes a TCP/IP connection with its remote partner for its normal application (FMH)communication path, and two zFBA devices on the DS8K for data transfer.

Connect:Direct for z/OS uses an IOS API to allocate, read, write, unallocate and erase the zFBA devices.Connect:Direct for z/OS defines and manages the zFBA devices within its configuration in its NETMAP fileand the remote IBM Connect:Direct partner is not required to define the zFBA configuration in its NETMAPfile. IBM Connect:DirectUNIX only need to request that Connect:Direct for z/OS allocate two zFBA devicesfor the COPY.

In a non-zFBA COPY, the data and all FMHs are sent using TCPIP in units where the maximum size isdetermined through the negotiation between two nodes.

In a zFBA COPY step, the data (and any checkpoint FMHs) are transferred with a pair of zFBA devices, inunits of 32MB (the last one is usually smaller). The zFBA devices must be defined to be at least 32MBand any amount in excess of 32MB is unused by the IBM Connect:Direct zFBA feature. During the bulk ofthe transfer, the sending node is writing to one zFBA device in a pair; the receiving node is simultaneouslyreading the other zFBA device and writing the data to the destination data set. When the sender is donewriting to a zFBA device, it communicates to the receiver over the TCPIP connection directing it to thenew data. When the receiver has finished reading the data, it communicates back to the sender thatthe device is available and allows IBM Connect:Direct to reuse the zFBA device. The switching of zFBAdevices occurs many times in a COPY step.

Special Considerations when using zFBA with IBM Connect:DirectYou can use zFBA devices for COPY between two Connect:Direct for z/OS nodes with the followingrequirements:

• Both Connect:Direct for z/OS nodes MUST run in separate LPARS• Connect:Direct for z/OS nodes require the same zFBA configuration defined in both NETMAP files

The only protocols that supports zFBA transfers is TCPIP. Any other protocol used will generate messageSCZF002I and the COPY step will continue without using zFBA.

Once the data path is determined to be zFBA, if an allocation error occurs on z/OS or UNIX, theconnection terminates and message SCZF003E or SCZF006E is generated. SCZF006E is a special caseindicating that the PNODE and SNODE are on the same LPAR. SCZF003E errors are repeatable.

IBM Connect:Direct uses a fixed size of 32MB regardless of the actual zFBA device size; therefore, theminimum device size is 32MB. Each RU is rounded up to the next zFBA block size multiple (for the currentgeneration DS8K, there are 512 bytes per block). As many whole RUs are packed in a 32MB chunk as willfit.

CDPLEX supports zFBA transfers.

416 IBM Connect:Direct for z/OS: Documentation

You can not modify the zFBA setting using the INITPARM refresh. You must utilize the new globalinitialization parameter of zFBA so the WLM can direct the process to the correct server that supportszFBA.

The following is not supported when using zFBA: Secure+, CTCA, and any SNA protocol.

zFBA Error HandingThere are several possible errors that could indicate additional user action is required.

The following errors are possible when using zFBA:

Error SCZF0021

If a COPY statement has ZFBA=2, but the zFBA is not allowed for that process, an SCZF0021 occurs. Thefollowing list shows the Reason Text for Error Message SCZF002I.

1 = The INITPARM ZFBA=NO was specified or allowed o default2 = ZFBA is not supported with SNA or CTCA3 = ZFBA is not supported with Secure Plus4 = The Remote node does not support or is not configured for ZFBA5 = The Netmap has no entry for the node6 = There are no ZFBA device range for the node in netmap

If generated, the third line of the message explains why it is not allowed.

18.19.24 JOB02828 SCZF002I ZPUSH1 COPY ZFBA30S ( 1) SNODE=CD.BOB.NOZFBA 535535 SCZF002I Not using zFBA for COPY data transport. Reason:535 SCZF002I No ZFBA device range for node in netmap.

Error SCZF003E

An error occurred in IOSFBA ALLOCATE. The IOSFBA RC and RSN are included in the error message.

Example (message compacted):

13.59.48 JOB09406 SCZF003E ZPUSH1 COPY ZFBA01 (1) SNODE=CD.BOB 020 020 SCZF003E Cannot Allocate zFBA devices,RC=0C,RSN=01

The RC and RSN codes can be found in SYS1.MACLIB(IOSFBA).

Error SCZF005E

The FMH 76 is missing or invalid. A reason is included in the error message.

The following list shows the Reason Text for Error Message SCZF005E:

1. RECV error,or not FM76-L2. Device Count ^= 2-103. RCVFM764 Error4. RCVFM765 Error5. SNDFM764 Error6. SNDFM765 Error7. Curr Dev^0;FM76-4 RECV not needed8. Curr Dev^0;FM76-5 RECV not needed

Error SCZF006E

An error occurred in IOSFBA ALLOCATE in the SNODE in a CD z/OS to CD z/OS transfer. Since the PNODEran first and was able to allocate the same ZFBA devices, this error is usually caused by the PNODE andSNODE running on the same LPAR (RC=0000000C & RSN=00000001). This error requires that you movea CD z/OS node to a different LPAR.

Example (message compacted):

14.22.14 JOB09417 SCZF006E ZPUSH1 COPY ZFBA01 (1) PNODE=CD.ART 600 600 SCZF006E Cannot Allocate zFBA devices,RC=0C,RSN=01

Chapter 4. Administration Guide 417

Using zEDC with IBM Connect:DirectzEnterprise Data Compression (zEDC) is a compression acceleration capability that allows you to performhardware-based data compression that streamlines data exchanges, saves on storage, and reduces CPUconsumption. IBM now provides a new zlib version that supports the zEDC Express Accelerator forcompression and decompression activities to improve throughput and CPU usage.

You can use zEDC with IBM Connect:Direct by implementing the new initialization parameter, ZEDC. Ifthe zEDC Express Accelerator is available, the compression is perform by the hardware; otherwise, anew software version of zlib, 1.2.7, will be used. During product initialization, a new message appearsindicating that this version of zlib is available and if the zEDC hardware is available.

With zEDC hardware compression, the object being compressed or decompressed is performed using thehardware or the software. This is determined based on the size of the first data block from the objectpassed to the IBM ZLIB code.

This threshold is controlled by a system wide global parameter specified in SYS1.PARMLIB memberIQPPRMxx using global parameters DEFMINREQSIZE and INFMINREQSIZE.

Note: On IBM zEnterprise z15 and above processors IQPPRMxx is no longer valid. The z15 has no PCIEzEDC cards anymore and IQPPRMxx is solely used for PCIE. However, documentation for IQPPRMxxdoes provide the default values on z15 for the old global parameters. On a z15, those thresholds canbe specified using environment variables _HZC_DEFLATE_THRESHOLD and _HZC_INFLATE_THRESHOLD.That allows the threshold to be tailored by application using ENVIRON DD input of the new variables. Thevalid values are in the range 1-9999999, where each number is a multiple of 1024.

When this feature is used, it is utilized by the extended compression feature of IBM Connect:Directand is subject to the negotiated Compression Control Facility (CCF). When the PROCESS is executed,extended compression is negotiated if the ZIIP for extended compression is not enabled. The appropriateenvironment variable uses the zEDC accelerator and uses the buffer length restrictions defined by theoperating system and zEDC. IBM Connect:Direct statistics data indicates the version of zlib being usedand if the hardware zEDC Express accelerator was used.

During product initialization, when zEDC is specified as ON or by default, IBM Connect:Direct will inquirethe availability of the zEDC hardware and provide the appropriate initialization message, SITA374I, onthe status of the zEDC hardware. If the hardware is unavailable, IBM Connect:Direct will continue butsoftware compression is forced.

For a detail overview, requirements and planning for zEDC, please reference, z/OS MVS Programming:Callable Services for High-Level Languages, SA23-1377-00 zEnterprise Data Compression (zEDC).

Using PDSE Version 2 with IBM Connect:Directv6.1 includes support to directly control creation of a PDSE Version 2 (PDSE V2) with a userspecified maximum number of generations. This is implemented via the new DSNTYPE parametersyntax DSNTYPE=(LIBRARY,2) along with the new parameter MAXGENS=n, in the COPY statement. Bothspecifications are the same as allowed by z/OS JCL.

CD COPY DSNTYPE propagation has also been enhanced to include propagating the DSNTYPE Versionand MAXGENS when the propagated DSNTYPE is LIBRARY and the TO side INITPARMs specifyDSNTYPE=YES. For more details on propagating PDSE V2 attributes, see “Propagation” on page 419.Also see “DSNTYPE = YES | NO” on page 467. New support for specifying DSNTYPE=(LIBRARY,2) andMAXGENS=n in the COPY TO SYSOPTS is also added, thereby allowing earlier releases of Connect:Directfor z/OS as well as other Connect:Direct products running on other platforms such as Unix and Windowsto control creation of a PDSE V2 dataset on a IBM Connect:Direct v6.1 TO SNODE.

In addition to the COPY statement, IBM Connect:Direct for z/OS v6.1 Run Task program DGADTDYN(DMRTDYN) supports creating a PDSE V2 using the same syntax as the COPY statement and z/OS JCL.

IBM Connect:Direct for z/OS v6.1 PDSE V2 support also includes new fields for the DSNTYPE Version andMAXGENS in the TYPE record and the IUI CF RECEIVING FILE panel.

418 IBM Connect:Direct for z/OS: Documentation

PropagationIn an all IBM Connect:Direct for z/OS COPY step, the source data set’s DSNTYPE is propagated tothe destination dataset if DSNTYPE=YES is specified in the destination node’s INITPARMs, and theDSNTYPE is not specified for the destination dataset (in the COPY TO section). If either side is not IBMConnect:Direct for z/OS v6.1, then COPY will only support the propagation of the DSNTYPE, and not theDSNTYPE Version or MAXGENS.

If both sides are IBM Connect:Direct for z/OS v6.1, then DSNTYPE propagation will include the DSNTYPE,the DSNTYPE version, and the MAXGENS. More specifically, if DSNTYPE propagation is in effect, and aPDSE is to be created from another PDSE, then the source data set’s DSNTYPE, DSNTYPE version, andMAXGENS will be propagated, provided they are not specified in the COPY TO section.

1. DSNTYPE is only propagated if the INITPARM DSNTYPE=YES on the destination node and theDSNTYPE is not in the TO section of the COPY step.

2. DSNTYPE Version and MAXGENS are only propagated if the DSNTYPE is propagated.3. MAXGENS is only propagated for a PDSEV2.

The results also depend on the combination of JCL parameters and SMS parameters. In a COPY step,the JCL parameters can come from COPY TO parameters (including direct specification, DATACLAS, LIKEand TYPE), and propagation of the source dataset attributes. If those aren’t enough to determine allattributes, the SMS parameters from the Destination system come into play.

LimitationsIBM Connect:Direct for z/OS releases prior to v6.1 are indirectly capable of creating a PDSE V2 - ifthe TO dataset DSNTYPE is LIBRARY and the receiving system’s SYS1.PARMLIB (IGDSMSxx) specifiesPDSE_VERSION(2). However, IBM Connect:Direct for z/OS releases prior to v6.1 have no direct controlover the PDSE Version, nor do they propagate the version, nor do they have any way of specifying theMAXGENS value. A PDSE V2 created without a MAXGENS specification will take the default of 0.

When a PDSE version 2 is copied to a new PDSE version 2 using IBM Connect:Direct for z/OS v6.1 COPYstatement, only the base generation of each member is transferred to the new dataset. Thus, no matterhow many generations each member has in the FROM dataset, only one generation which is the basegeneration of each member will exist in the newly created TO PDSE V2 dataset. Subsequent CD COPYsteps to the same PDSE V2 TO dataset replace bases of existing members, and the generations for eachreplaced member will be rippled by DF/SMS, rolling off any generation which exceeds the MAXGENS valuefor the TO PDSE V2. In other words, IBM Connect:Direct for z/OS v6.1 has the same limitation as mostprograms that write a PDSE V2 member, including IEBCOPY and ISPF 3.3.

Copy all member generationsAny CDZ release can transmit an exact copy of a PDSE V2 (including all generations of all members)by using DFDSS (ADRDSSU) to backup and restore the PDSE, with CDZ’s role limited to transmitting theDFDSS backup dataset. This is possible because DFDSS copies and restores all data in the PDSE V2 andso makes an exact and complete copy of it, including the MAXGENS value. Any CDZ release can invokeDFDSS via COPY I/O exit program DGADSIOX (DMDSSIOX), and create an exact copy of a PDSE V2 in asingle COPY step.

Using PS-E Version 2 with IBM Connect:DirectA sequential extended format data set can be either Version 1 or 2. If it is Version 2, it can be used byFlashCopy, can be encrypted, and can be compressed via zEDC, in addition to the Version 1 capabilities(striping, other types of compression/compaction).

IBM Connect:Direct for z/OS v6.2 or later includes support to directly control creation of a PS-E Version2 (PS-E V2). This is implemented via the new DSNTYPE parameter syntax DSNTYPE=(EXTREQ,2) orDSNTYPE=(EXTPREF,2) in the COPY statement. Both specifications are same as allowed by z/OS JCL.

Chapter 4. Administration Guide 419

IBM Connect:Direct for z/OS v6.2 does not support DSNTYPE Version propagation when the propagatedDSNTYPE is EXTREQ or EXTPREF. For more details on propagating PS-E V2 attributes, refer “Propagation”on page 420.

PropagationWhen DSNTYPE is either EXTREQ or EXTPREF, IBM Connect:Direct for z/OS will only support thepropagation of the DSNTYPE, and not the DSNTYPE Version. This is because DYNALLOC (SVC 99) doesnot return the DSNTYPE Version information unless the “Return DSNTYPE Version information” key(DINRDSNV) is part of an SVC 99 request to create the data set.

Version of Created PS-E Data SetBecause there is no propagation of the PS-E DSNTYPE Version, when IBM Connect:Direct for z/OS createsa PS-E dataset, the results depend only on the combination of JCL parameters and SMS parameters. In aCOPY step, the JCL parameters come from COPY TO parameters (including direct specification, DATACLASand TYPE). If those are not enough to determine all attributes, the SMS parameters from the Destinationsystem come into play.

Select Stats DisplayThe DSNTYPE Version is displayed by IBM Connect:Direct for z/OS v6.2 or later Select Stats only when allthe following are true:

• The TO data set is created (not replaced).• It is created by IBM Connect:Direct for z/OS v6.2 or later.• The DSNTYPE and VERSION are specified in the COPY TO section (either directly or via SYSOPTS or the

TYPE parameter).

LimitationsIBM Connect:Direct for z/OS releases prior to v6.2 can create a PS-E V2 data set if the TO datasetDSNTYPE is EXTREQ or EXTPREF and the receiving system’s SYS1.PARMLIB (IGDSMSxx) specifiesPS_EXT_VERSION(2). However, IBM Connect:Direct for z/OS releases prior to v6.2 have no direct controlover the PS-E Version.

Simultaneous Session Reporting and Asset Tracking ReportingIBM Connect:Direct utilizes Simultaneous Session Reporting and Asset Tracking to continually monitorserver sessions, track metrics such as the high-water mark, generate SMF records to document thevalues, and generate audit reports with this data.

This feature is enabled by default and enables Connect:Direct administrators manage their serverlicensing requirements to:

• Help determine if the current usage of Connect:Direct servers is within the license entitlement levelsand can prevent potential license violations

• Track usage of IBM Connect:Direct server and its neighbors and assist administrators decommissiondevices that are no longer accessing IBM Connect:Direct servers.

IBM Connect:Direct sets several important Global initializ ation parameters that supply values to processits various functions. For example, SESSION.HIGHWATER.SMF parameter is set to define a sessionexpiration time. When this time period elapses, the Connect:Direct server records high-session limits,the time/date it occurred, and other additional information about the server itself such as, License type.This information is recorded as a SMF record into a zO/S standard facility, SMF and into its Statisticsfacility, Connect:Direct Server's Statistics to be utilized by IBM Control Center and other AIJ applications.

420 IBM Connect:Direct for z/OS: Documentation

With release v6.1, Highwater Session Record (HW) is enhanced to provide additional information andgenerate a HW record once every 24-hours period based on Mid-night UTC. The Connect:Direct Servertracks the highwater session mark and records the environment related information such as zOS SystemName, OS type, OS version, CD version etc. The Connect:Direct server will record the HW record to thestatistic file based on mid-night UTC. For example, if the Connect:Direct server in US CDT the record iswritten at 19:00:00 versus if it is written in US EDT, at 18:00:00. Each Connect:Direct server will adjustthis time based on its offset from UTC. The SELECT STAT command to format a report for this record type.

Note: Global initialization parameter SESSION.HIGHWATER.SMF is by default set to 60. To modifythis and other related parameters such as, SERVER.TYPE and SERVER.MSU see, Global InitializationParameters.

For example, Connect:Direct records and maintains the current session count internally and record thisexternally by writing the information to SMF record type 133. The SMF record type and the recordinginterval will be established at initialization time as specified with a new initialization parameter. EachConnect:Direct Server will record this information separately.

If the SMF record type of 133 is being used by another application, then you will need to specify a newSMF record type using the SESSION.HIGHWATER.SMF initialization parameter.

Post-processing of the SMF records will be done by a batch job, for which sample JCL and control cardsare distributed in SDGAJCL that will produce audit reports from the data.

Additionally, this data is also recorded as a H2 and HW record type in Server Statistics. Use SELECT STATcommand to format a report for this record type. For more information see, SELECT STATSTICS Commandin IBM Connect:Direct for z/OS User Guide.

SMF Record LayoutThe new SMF record layout is in the table below. It specifies the SMF TYPE or is defaulted to by thenew INITPARM (CDHWRTY=XL1’85’=133). It contains a subtype of 2 (CDHWSTY=XL2’0002’), and asubsystem identification of CDHW (CDHWSSI=CL4’CDHW ’) to aid in identification. The first 24 bytes arethe standard SMF record header for records with subtypes. The remaining bytes are the High Water markinformation.

Note: For programs, such as DFSort, that reference field position rather than field offset, add 1 to theoffset for control card usage. For programs, such as REXX, EXECIO and ISPF BROWSE/EDIT, which do nothandle the RDW field, subtract 4 from the offset to calculate field position.

For a sample layout, see the table below.

Table 1. Mapping of the CDzOS High Water Mark SMF Record

Offsets Name Length Format Description

00 00 CDHWLEN 2 binary Record length. This field and thenext field (total of four bytes)form the RDW (record descriptorword).

02 02 CDHWSEG 2 binary Segment descriptor

04 04 CDHSFLG 1 binary System indicator:

05 05 CDHWRTY 1 binary Record type, from parameter 1 ofthe SESSION.HIGHWATER.SMFINITPARM.

06 06 CDHWTME 8 binary Time since midnight, inhundredths of a second, whenthe record was moved into theSMF buffer.

Chapter 4. Administration Guide 421

Table 1. Mapping of the CDzOS High Water Mark SMF Record (continued)

Offsets Name Length Format Description

10 0A CDHWDTE 4 packed Date in the form 0cyydddF whenthe record was moved into theSMF buffer. See Standard SMFrecord header for a detaileddescription.

14 E CDHWSID 4 EBCDIC System ID (from SMCASID).

18 12 CDHWSSI 4 EBCDIC Subsystem ID c’CDHW’.

22 16 CDHWSTY 2 binary Record subtype x’0002’ =Session High Water Mark

24 18 CDHWSNAM 8 EBCDIC System name from CVTSNAME.

32 20 CDHWJOB 8 EBCDIC Job name of CDzOS server.

40 28 CDHWITME 4 binary Time, in the form HHMMSSTH,when the CDzOS server wasinitialized.

44 2C CDHWIDTE 4 packed Date in the form yyyydddC whenthe CDzOS server was initialized.

48 30 CDHWJID 8 EBCDIC 8-character job identifier

56 38 CDHWPLX 8 EBCDIC CDPlex name or blanks

64 40 CDHWSRV 8 EBCDIC CDPlex server name or blanks

72 48 CDHWNOD 16 EBCDIC CD local node name

88 58 CDHWUNU1 1 Unused

89 59 CDHWRCR 1 EBCDIC Record Creation Reason:‘I’=lnterval (CDHWRINT) reached‘T’=Termination

90 5A CDHWRINT 2 binary Recording Interval, in minutes,from parameter 2 ofthe SESSION.HIGHWATER.SMFINITPARM.

92 5C CDHWMAXP 2 binary Maximum Allowed ConcurrentProcesses, from MAXPROCESSINITPARM.

94 5E CDHWSHWM 2 binary Session High Water Mark for thisinterval.

96 60 CDHWHTME 4 binary Time in the form HHMMSSTH,when the Session High WaterMark was first reached in thisinterval.

100 64 CDHWHDTE 4 packed Date in the form yyyydddd whenthe Session High Water Mark wasfirst reached in this interval.

104 68 CDHWPRCT 2 Binary MAXPRIMARY Sessions

106 6A CDHWSECT 2 Binary MAXSECONDARY Sessions

422 IBM Connect:Direct for z/OS: Documentation

Table 1. Mapping of the CDzOS High Water Mark SMF Record (continued)

Offsets Name Length Format Description

108 6C CDWHOS 4 EBCDIC OS Type

112 70 CDHWOSVR 4 EBCDIC OS Version

116 74 CDHWCDVR 4 Binary CD Server Version

120 78 CDHWLIC 8 EBCDIC License Edition

128 80 CDHWTYP 4 EBCDIC License Sub-Type PROD/TEST

132 84 CDHWMSU 4 Binary MSU Value

136 88 CDHWGMT 4 Binary GMT Offset

140 8C CDHWNNUM 4 Binary Number of Nodes

144 90 2 Reserved

146 92 CDHWHSTL 2 Binary Length of Hostname

148 94 CDHWHOST 255 EBCDIC Hostname

403 193 5 Reserved

408 198 CDHWCNT 8 Binary Number of times HW Countreached

416 1A0 96 Reserved

H2 and HW Statistic Record layoutThe H2 and HW statistics record is generated and written to the Connect:Direct Statistics file at the sameinterval the SMF record is generated. This H2 and HW statistics record can be formatted as a report withthe Select Statistics command or the SS or S2 selection from the Connect:Direct IUI.

Table 2. Mapping of the CDzOS High Water Mark Statistics Record

OffsetDecimal

OffsetHexadecimal

Name Length Format Description

00 00 H2RECLN 2 Binary H2 Record length

02 02 H2RTYPE 2 EBCDIC H2 Record Id

04 04 H2TIME 4 Binary Time when STAT record iswritten

08 08 H2DATE 4 Binary Julian Date when STAT recordwritten

12 0C H2HSNAM 8 EBCDIC zOS System Name

20 14 H2HJOB 8 EBCDIC Server JOB Name

28 1C H2HITME 4 Binary Server Initialization Time

32 20 H2HIDTE 4 Packed Server Initialization Date

36 24 H2HJID 8 EBCDIC Server JOB Number

44 2C H2HPLX 8 EBCDIC CD Plex XCF Group Name

Chapter 4. Administration Guide 423

Table 2. Mapping of the CDzOS High Water Mark Statistics Record (continued)

OffsetDecimal

OffsetHexadecimal

Name Length Format Description

52 34 H2HSRV 8 EBCDIC CD Plex Member Name

60 3C H2SNOD 16 EBCDIC Server Nodename (LNODE)

78 4E H2HRINT 2 Binary HW Recording Interval

80 50 H2HMAXP 2 Binary Maximum Process(MAXPROCESS)

82 52 H2HSHWM 2 Binary High Session value

84 54 H2HHTME 4 Binary Time Reached in this Interval

88 58 H2HHDTE 4 Packed Date Reached in this Interval

92 5C H2HPRCT 2 Binary Primary Session Count

94 5E H2HSECT 2 Binary Secondary Session Count

96 60 H2HOS 4 EBCDIC OS Type

100 64 H2HOSVR 4 EBCDIC OS Version

104 68 H2HCDVR 4 Binary CD Server Version

108 6C H2HLIC 8 EBCDIC License Edition

116 74 H2HTYP 4 EBCDIC License Sub-Type PROD/TEST

120 78 H2HMSU 4 Binary MSU Value

124 7C H2HGMT 4 Binary GMT Offset

128 80 H2HNUMN 4 Binary Number of Nodes

134 86 H2HHSTL 2 Binary Length of Hostname

136 88 H2HHOST 255 EBCDIC Hostname

391 187 1 Reserved

392 188 H2SEQ 2 Binary Sequence number of Date/Time

394 18A 6 Reserved

400 190 H2TOTP 8 Binary Total number of ProcessExecuted

408 198 H2HWCNT 8 Binary Number of times HW Countreached

ReportingSeveral audit reports can be generated using the SMF data.

• Detail Report• Summary Report• CSV output file for importing into an Excel Spreadsheet

The SDGAJCL contain the following samples:

• DGAJDET – Collect SMF data using IFASMFDP and create report using DFSORT

424 IBM Connect:Direct for z/OS: Documentation

• DGAJSUM – Collect SMF data using IFASMFDP and create report using DGA#SUM• DGAJCSV – Collect SMF data using IFASMFDP and create report using DGA#CSV

Examples

Example 1 – SMF Record Detail Report. Sorted by SMFID, Date and Time of Write.

107/30/18 02:51:10 Simultaneous Session Interval Detail by: SMFID, Date and Time107/30/18 02:51:10 Simultaneous Session Interval Detail for SMFID: IRVK 0---SMF Record Written---- --------Interval High Water Mark-------- ------------------ SID Date Time Date Time Value Pri Sec R Jobname Job ID Name ---- -------- ----------- -------- ----------- ----- ----- ----- - -------- -------- ------- IRVK 2018.201 06:39:14.29 2018.201 06:38:12.90 0 0 0 I EPETE1A1 JOB02927 CD.ART IRVK 2018.201 06:40:13.34 2018.201 06:39:14.29 0 0 0 T TIC CP DIAGNOS CD.ART IRVK 2018.206 15:43:39.76 2018.206 15:43:21.06 0 0 0 T EPETE1A1 JOB03081 CD.ART IRVK 2018.206 15:45:03.25 2018.206 15:44:02.24 0 0 0 I EPETE1A1 JOB03083 CD.ART IRVK 2018.206 15:45:03.28 2018.206 15:44:02.24 0 0 0 I EPETE1B1 JOB03084 CD.BOB IRVK 2018.206 15:46:00.07 2018.206 15:45:03.28 0 0 0 T EPETE1B1 JOB03084 CD.BOB IRVK 2018.206 15:46:00.16 2018.206 15:45:03.25 0 0 0 T EPETE1A1 JOB03083 CD.ART IRVK 2018.206 15:47:26.10 2018.206 15:46:23.98 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:47:26.14 2018.206 15:46:24.01 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:48:26.86 2018.206 15:47:26.10 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:48:26.88 2018.206 15:47:26.14 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:49:27.90 2018.206 15:48:26.86 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:49:27.93 2018.206 15:48:26.88 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:50:27.90 2018.206 15:49:27.90 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:50:27.93 2018.206 15:49:27.93 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:51:28.95 2018.206 15:50:27.90 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:51:28.98 2018.206 15:50:27.93 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:52:29.40 2018.206 15:51:28.95 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:52:29.43 2018.206 15:51:28.98 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:53:29.40 2018.206 15:52:29.40 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:53:29.43 2018.206 15:52:29.43 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:54:29.40 2018.206 15:53:29.40 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:54:29.43 2018.206 15:53:29.43 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:55:29.60 2018.206 15:54:29.40 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:55:29.63 2018.206 15:54:29.43 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:56:30.65 2018.206 15:55:29.60 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:56:30.68 2018.206 15:55:29.63 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:57:30.65 2018.206 15:56:30.65 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:57:30.68 2018.206 15:56:30.68 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:58:30.65 2018.206 15:57:30.65 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:58:30.68 2018.206 15:57:30.68 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 15:59:31.70 2018.206 15:58:30.65 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 15:59:31.72 2018.206 15:58:30.68 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 16:00:31.70 2018.206 15:59:31.70 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 16:00:31.72 2018.206 15:59:31.72 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 16:01:32.75 2018.206 16:00:31.70 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 16:01:32.77 2018.206 16:00:31.72 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 16:02:32.75 2018.206 16:01:32.75 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 16:02:32.77 2018.206 16:01:32.77 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 16:03:32.75 2018.206 16:02:32.75 0 0 0 I EPETE1A1 JOB03085 CD.ART IRVK 2018.206 16:03:32.77 2018.206 16:02:32.77 0 0 0 I EPETE1B1 JOB03086 CD.BOB IRVK 2018.206 16:04:33.80 2018.206 16:03:32.75 0 0 0 I EPETE1A1 JOB03085 CD.ART

Isolating ProblemsTo expedite the diagnostics process, prepare the following information for the IBM Supportrepresentative:

• Version, release, maintenance level, and operating system for the IBM Connect:Direct products beingused on both nodes, for example, Connect:Direct for z/OS 6.0 with Connect:Direct for HP NonStop3.4.00.

• Release levels of the operating system, VTAM, and other software involved• Details describing the complete scenario, including:

– Commands that are issued, with exact syntax and order– Files or devices that are involved. Note the file contents and the type of file (such as DCB file

attributes, GDG, Tape, SMS, striped, compressed)– Interface that you used, such as batch interface, IUI, or operator interface– Error messages for both nodes– System logs for both nodes, including any messages generated while the problem occurred. Check

the SYSLOG for Connect:Direct for z/OS nodes– Which side is PNODE/SNODE– The direction of the data transfer

Chapter 4. Administration Guide 425

– What connection protocol you are using (LU0, LU6.2, IBM TCP/IP, TCPAccess)– If the node is a IBM Connect:Direct/Plex or stand alone server– IBM Connect:Direct Process including the FILE attributes for the FROM and TO files for both nodes– I/O device types– Network map information– Statistics information for both nodes including ALLOC information

Note: Be prepared to recreate the problem. Problem recreation is your responsibility.

Supporting DocumentationProblem determination can be involved and can require extensive research. We ask you to gather someof the following supporting documentation to help analyze the problem. Not all of this information isapplicable to all problems or all operating environments.

• SYSLOGs• IBM Connect:Direct statistics for both nodes• RPLERRCK output• ESTAE output• VTAM definitions• APPLID definitions• Logmode table entry• Class of Service (COS) entry• D NET VTAM display• IBM Connect:Direct traces• Network map information

You can use your network management software or VTAM commands to isolate any session-relatedproblems.

Diagnostic Rexx Exec for IUI EnvironmentsIf you are experiencing problems with the IBM Connect:Direct IUI, you can use the DGA#CAP Rexx execavailable in the SDGAISPC target library to facilitate diagnosis of IUI problems.

To invoke the DGA#CAP Rexx exec, type the following TSO command:

TSO %DGA#CAP

The exec issues an ISPF long message containing the dataset name where the output is written. ContactIBM Support and give the Support representative the output generated by the DGA#CAP Rexx exec.

Providing Dumps to Customer SupportA IBM Connect:Direct ABEND can occur when a system failure or system error exists or when the FORCEparameter is used with the STOP CD command.

When an ABEND is reported, Support searches the problem tracking database for any similar problems.Often the ABEND is a known bug or a common error, and a solution is readily available. Otherwise, providea full SVC dump for diagnosing ABENDs.

If support cannot locate a reference to the ABEND, you may be required to provide the followinginformation:

• Send a complete SVC dump, not a snap dump.

426 IBM Connect:Direct for z/OS: Documentation

• A copy of the Process and the statistics for that Process. If the Process has symbolics, include thesymbolic substitution data. Also, ensure that the statistics records include WTO records.

Note: Include statistics from both IBM Connect:Direct nodes.

If the ABEND occurred while executing a Process that has executed successfully, determine what changeswere made, either in the operating system or within IBM Connect:Direct, and do the following:

• Send console logs for both IBM Connect:Direct nodes.• Note whether the ABEND caused either IBM Connect:Direct node to terminate.• If the ABEND can be recreated, provide details.• Send a copy of the system log and network error log for both operating systems, which can indicate any

unusual situations occurring with the operating system or network at the time of the ABEND.

Note: A system log is required when analyzing an ABEND. It is preferable to review the log for bothsystems; however, it is essential for the system reporting the ABEND. When one of the nodes is not in az/OS environment, check the output files for IBM Connect:Direct.

• Send RPLERRCK DD output to review I/O errors and other information. See DD Statements in StartupJCL for more information.

• Send ESTAE DD output to review ABEND conditions and some special I/O errors. See DD Statements inStartup JCL for more information.

If several ABENDs occur simultaneously, send the dump from the first ABEND only. Subsequent ABENDsare usually a result of the original ABEND.

When sending a dump on tape, send the JCL that created the tape. DSN, VOLSER, LABEL, and DCBattributes are needed to facilitate tape unloading. If available, send a printout of the tape managementproduct display of the VOLSER.

Note: If you are sending a tape with more than one file, ensure that the JCL that created the tapereferences the correct file in the LABEL= parameter. This reference ensures that a previous file is notinadvertently overlaid.

Types of DumpsTo determine and resolve problems, Customer Support may request any of the following types of dumps:

• IBM Connect:Direct Data Transmission Facility (DTF) Dumps, which include SYSMDUMP and CDSVCDMPdumps

• IBM Connect:Direct IUI ABEND Dumps, which include z/OS Time Sharing Option (TSO) address spacedumps

• DGADBATC Batch Dumps• VSAM File Dumps

IBM Connect:Direct Data Transmission Facility (DTF) DumpsThis dump is generated when an ABEND occurs. It contains the contents of the IBM Connect:Directaddress space, which is copied into one or more of the data sets that you specify by ddname in the DTFJCL (CDSVCDMP, SYSABEND, or SYSMDUMP).

When an ABEND occurs, IBM Connect:Direct produces an SVC dump with all of the information for theaddress space, regardless of whether the ABEND occurred in the main task or a User Exit subtask. Unlessotherwise specified in the JCL, the dump is written to the standard SVC dump data set, SYS1.DUMPxx.You can specify an alternate data set by using the CDSVCDMP DD statement in the JCL.

Note: If the system attempts an SVC dump and fails with: *ERROR* Unable to take an SVC dump; reason:0B, the Dump Analysis and Elimination (DAE) component of the operating system found an earlier dumpof this problem already exists.

Turn off the SVC dump by modifying your JCL. For more information, see Turning Off the SVC Dump.

Chapter 4. Administration Guide 427

Multiple DTF SVC Dumps Capture Using CDSVCDMP

You can use CDSVCDMP to capture multiple DTF SVC dumps. A dump is created for each ABEND andwritten to a separate data set. You can specify whether the dumps are written to the SYS1.DUMPxx datasets or to unique user-specified data sets.

To write dumps to user-specified data sets, you must create a data set name for each dump that canoccur. The first data set name must end with .SYSMDP00. Each additional data set name must endwith .SYSMDPnn, where nn is a consecutive number up to a value of 99. For example, if you want to createenough data sets to write five dumps, create five data set names beginning with xxxx.yyyy.SYSMDP00 andending with xxxx.yyyy.SYSMDP04.

You must define the data sets with the same attributes as your SYS1.DUMPxx data sets. The data setsmust be preallocated and on the same disk volume.

To record multiple SVC dumps, set the JCL statement for CDSVCDMP as follows.

//CDSVCDMP DD DSN=XXXX.YYYY.SYSMDP00,DISP=SHR

The first dump is written to the .SYSMDP00 data set. When an additional ABEND occurs, a dump is writtento the next data set, .SYSMDP01. Each additional ABEND creates a dump to the next .SYSMDPnn data setas long as ABENDs occur and enough .SYSMDPnn data sets are available. If an ABEND occurs and all datasets are full, the dump is not created and a message is issued stating that all .SYSMDPnn data sets arefull.

You do not have to empty or reset these dump data sets. When the DTF is initialized, and you are usingthe .SYSMDPnn data sets, IBM Connect:Direct writes over the existing data in the data sets. If you wantto save the existing data, save the data sets using a different data set name before you restart IBMConnect:Direct.

Turning Off the SVC DumpIf you want to turn off the SVC dump, place the following statement in your DTF JCL.

//CDSVCDMP DD DUMMY

Changing Dump OptionsFor the SDATA parameter specify SDATA=(ALLSDATA). If SDATA=(ALLSDATA) is not an acceptable defaultfor your system, ensure that the SYS1.PARMLIB member corresponding to the ddname in the JCL for theDTF specifies, at a minimum, the following.

SDATA=(NOSUM,PSA,RGN,SQA,SWA,TRT,LPA,GRSQ,CSA,NUC)

For the PDATA parameter for IEADMPxx and IEAABDxx, specify PDATA=(ALLPDATA).

Note: PDATA is not an option for member IEADMRxx.

If you cannot specify ALLPDATA, at a minimum, include PSW, REGS, SA, JPA, SPLS, and SUBTASKS. Referto the IBM manual MVS Initialization and Tuning Reference for the release of z/OS being used.

If you are unable to change the SYS1.PARMLIB member, issue an operator command to change the dumpoptions.

The following steps guide you in issuing operator commands to change dump options:

1. Issue the command DISPLAY DUMP,OPTIONS to list the dump options currently in effect.2. Issue the command CHNGDUMP SET to change the options.

428 IBM Connect:Direct for z/OS: Documentation

3. Issue the CHNGDUMP DEL or CHNGDUMP RESET command to reset the options after recreating thedump.

If the correct dump options are specified in one of the SYS1.PARMLIB members, change the ddname inthe JCL for the DTF to reference the ddname corresponding to that member.

For further information on changing dump options, refer to the MVS System Commands IBM manual forthe z/OS being used.

IBM Connect:Direct IUI ABEND DumpsWhen the IBM Connect:Direct abends, a system dump might be required for problem resolution. To obtaina dump of the TSO address space, allocate a SYSMDUMP DD to an appropriately defined data set, andrun the ISPF with the TEST option. To send a dump of the IUI to a data set, allocate SYSMDUMP withDISP=MOD to account for the two dumps that IBM Connect:Direct produces.

To recreate an ABEND of the IUI to produce a dump, perform the following steps:

1. Ensure that the SYSMDUMP DD is allocated.2. Reinvoke ISPF with the ISPF TEST command.3. To allocate a SYSMDUMP DD, type the following TSO command where filename is a valid DSN name

that has LRECL=4160, BLKSIZE=0, and RECFM=FBS.

TSO ALLOC F(SYSMDUMP) DA(filename) MOD

The system will determine blocksize, and will prevent short blocks. Generally, 110 cylinders on a 3390device is enough space for an IUI dump.

4. When the ABEND message is displayed, press ENTER to produce a dump. Two dump messages (anddumps) are produced. Press PF3/END to bypass the dump.

DGADBATC Batch DumpsFor DGADBATC batch dumps, ensure the JCL that executes DGADBATC contains a SYSMDUMP DDstatement. Refer to “IBM Connect:Direct Data Transmission Facility (DTF) Dumps” on page 427 to ensurethat the appropriate dump options are specified for the corresponding ddname in the JCL for DGADBATC.

VSAM File DumpsIf a problem occurs when using a IBM Connect:Direct VSAM file, you might need a dump of the VSAMfile for problem resolution. To dump a Connect:Direct for z/OS VSAM file, use the IBM Access MethodServices (IDCAMS) PRINT command. If you send an IDCAMS PRINT of the TCQ, include the TCX file.

Refer to the sample job stream in the following example for creating a Connect:Direct for z/OS VSAMdump.

//XXXXXX JOB (1111),PROGRAMMER,NOTIFY=TSOID,CLASS=D,MSGCLASS=X,// MSGLEVEL=(1,1)//PRINT EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//SYSIN DD * PRINT INDATASET(DUMP1.ZOS.VSAM1) - DUMP

To copy a VSAM file to tape, use the IDCAMS REPRO command. You must include the DCB parameters,RECFM=VB, DSORG=PS for the data set created on the tape. In the LRECL and BLKSIZE parameters forthe dataset created, you must reflect the size specified for the RECORDSIZE parameter used when youdefined the file.

Chapter 4. Administration Guide 429

For example, if the IBM Connect:Direct statistics file was initially defined with RECORDSIZE (4089 4089),copy the IBM Connect:Direct statistics file by typing the following DCB parameters in the DD statement inthe JCL.

//OUTDD DD DSN=TAPE.STAT.FILE,// DCB=(LRECL=4089,BLKSIZE=4089,RECFM=F,DSORG=PS)

Suppressing Dumps for Specific ABEND CodesUse the following procedure if you want to suppress the dump for specific ABEND codes.

1. Add the ABEND code for which you want to suppress dumps to the ABEND codes list defined in theABEND.CODES.NODUMP parameter.

2. Set the ABEND.RUNTASK parameter to ABEND.CODES.NODUMP. Following is an example:

ABEND.CODES.NODUMP => (SX37 SX13 U0728 SXD9 S9FC)ABEND.RUNTASK => ABEND.CODES.NODUMP

Resolving the ProblemIf Support cannot resolve the problem during, it is documented as a case and is assigned a referencenumber. Refer to this number when forwarding documentation or calling support.

Severity Level Definition

Severity 1 Production system is down; requires immediate attention. For example, excessiveabnormal termination.

Severity 2 A major problem or question; the product operates but is severely restricted. Forexample, an incorrect response from a frequently used command.

Severity 3 A non-critical issue is encountered with the product, but the majority of functionsare still usable. For example, an incorrect response from an infrequently usedcommand.

Severity 4 A minor problem or question that does not affect product function. For example,the text of a message is misspelled.

All cases are prioritized based on severity.

Escalating a Problem ResolutionIf our normal support cycle does not produce the results you require or your issue has changed inseverity, you can escalate the case. To escalate a case, contact the technician responsible for yourproblem.

Reviewing IBM Connect:Direct Messages and Sense CodesAs you research a problem, note any messages issued by IBM Connect:Direct. Look specifically formessages displayed by the API through the IUI or batch interface. If an error occurred in a file transfer,look at messages for any Processes executing at that time for both nodes.

Also, check for messages in the JES log for z/OS.

IBM Connect:Direct messages contain short and long text to explain the error. Connect:Direct for z/OSdisplays the short text when an event occurs. The following information is displayed for each message ifyou request the long text:

• Module issuing the message• Short and long message texts

430 IBM Connect:Direct for z/OS: Documentation

• System action as a result of the message situation• User response to correct the situation

Note: For z/OS, press PF1 to display the longer explanation if the message is issued in an ISPF panel.

IBM Connect:Direct sense codes address connection errors involving the netmap and the DGADETLU(alias of DMGNETLU) module. The following is an example of a sense code display containing both thelong and short text. For additional information, see Messages in IBM Connect:Direct for z/OS User Guide.

Connect:Direct MESSAGE DISPLAY DATE => 2010.07.22 TIME => 09:53 MESSAGE ID==> SENS4022 MODULE ==> DMGNETLU ==============================================================================

SHORT TEXT==> LUNAME does not match name of node in NETMAP LONG TEXT: LINE 1 ==> The LUNAME or the remote node does not match the LUNAME LINE 2 ==> that is associated with the symbolic node name in the LINE 3 ==> C:D Network Map file. See messages SVTR014I and SVTR021I. LINE 4 ==> LINE 5 ==> LINE 6 ==> SYSTEM ACTION: The session is terminated unless NETMAP.CHECK LINE 7 ==> is specified in the INIT parms with the WARN parameter. LINE 8 ==> LINE 9 ==> LINE 10==> RESPONSE: The Adjacent.Node entry in the Network Map must be LINE 11==> updated to reflect the proper LUNAME, OR the remote LINE 12==> node should call in with correct LUNAME.

COMMAND ===> ________ ENTER 'DIR' TO DISPLAY THE DIRECTORY

Interactive Use of the IBM Connect:Direct Message FacilityDisplay the long text message through the IUI by either of the following methods:

• Use the SELECT MESSAGE command in the command line interface.• Type M at the CMD prompt and press Enter.• Access the PRIMARY OPTIONS MENU and type the MSG option at the CMD prompt.• Type =M from any IBM Connect:Direct screen at the CMD prompt in the ISPF Interface and press Enter.

The long text for the current message is displayed.

Displaying an ABEND MessageSome user ABEND messages are stored in the IBM Connect:Direct message file. To access them, insertthe ABEND message ID in place of a IBM Connect:Direct message ID.

Note: System ABEND messages appear in the JES log for z/OS. They do not appear in the IBMConnect:Direct message file. Refer to the appropriate operating system manuals if you require furtherdetails.

For example, to display the description of user ABEND U0075, perform the following:

1. Access the PRIMARY OPTIONS MENU in the IUI.2. Select the MSG option.3. Select option 1.4. Type U0075 on the message ID line and press Enter.

Chapter 4. Administration Guide 431

Connect:Direct MESSAGE DISPLAY DATE => mm.dd.yyyy TIME => hh:mm MESSAGE ID==> U0075 MODULE ==> DMINIT ==============================================================================

SHORT TEXT==> Connection services initialization failure. LONG TEXT: LINE 1 ==> An error has occured while initializing VTAM connection LINE 2 ==> services. ESTAE output should give a return code and error LINE 3 ==> flag. LINE 4 ==> LINE 5 ==> Verify the applid does not have a password associated with it LINE 6 ==> in the LOCAL.NODE definition of the Network Map. LINE 7 ==> LINE 8 ==> SYSTEM ACTION: ABEND the intialization of the DTF. LINE 9 ==> LINE 10==> RESPONSE: Verify that the APPLID is varied active and there is LINE 11==> not a VTAM password specified in the Network Map. LINE 12==>

COMMAND ===> ________ ENTER 'DIR' TO DISPLAY THE DIRECTORY

Examine Output from Select CommandsProblem determination and resolution is often as simple as gathering output from the IBM Connect:DirectSELECT commands and examining the output for obvious errors. For additional information, see the IBMConnect:Direct for z/OS User Guide. A description of the commands follows:

Command Description

SELECT NETMAP Displays or prints the definitions of nodes with which IBM Connect:Direct cancommunicate.

SELECT PROCESS Displays or prints information about IBM Connect:Direct Processes in the TCQ. Youcan use this command before or during IBM Connect:Direct Process execution.

SELECTSTATISTICS

Displays or prints statistics from the statistics log. Use this command only afterexecuting a IBM Connect:Direct Process.

SELECT TASK Selects, displays, or prints the list of all active users, Processes, and tasks withinIBM Connect:Direct.

SELECT TYPE Displays or prints type records from the Type file.

SELECT STATISTICS CommandThe SELECT STATISTICS command is one of the most useful commands for problem determination. Thissection provides a brief overview of the SELECT STATISTICS command. For more detailed information,refer to the IBM Connect:Direct for z/OS User Guide.

If an error occurred during a file transfer, issue the SELECT STATISTICS command on both the PNODEand SNODE to review the statistics for the Process. Process statistics are stored in the IBM Connect:Directstatistics log. You can request them by either using the IUI Select Statistics (SS) screen, if applicable, orissuing the IBM Connect:Direct SELECT STATISTICS command.

The statistics log records the following types of information for IBM Connect:Direct Processes:

• Function requested (COPY, RUN TASK, RUN JOB, SUBMIT)• Process name and number• Start and stop times, and date of the function• Completion code• Messages associated with the Process

432 IBM Connect:Direct for z/OS: Documentation

• Location and ID of the user requesting IBM Connect:Direct services• Sending and receiving file names• Amount of data sent and received• Security violations• All IBM Connect:Direct WTO messages, allocation information, and mount requests

Note: WTO messages are created during IBM Connect:Direct Process execution to document theexecution steps and are stored in the IBM Connect:Direct statistics file. This type of message is anexcellent debugging tool for determining a IBM Connect:Direct Process execution failure.

The optional parameters associated with the SELECT STATISTICS command enable you to define thesearch criteria and the form in which the report is presented.

IBM Connect:Direct IUI Select Statistics ScreenThe Select Statistics screen provides a convenient, easy method for issuing the SELECT STATISTICScommand. Use the fields to specify statistics selection criteria. The selection criteria enable you todetermine what records to select from the statistics log, limit the statistics to a certain period of time, orlimit the statistics to a certain Process. The selection criteria also allow IBM Connect:Direct to select therequested statistics from the file more efficiently.

The SELECT STATISTICS screen displays general IBM Connect:Direct Process information.

• To display the requested information in a formatted report, type a D in the CMD field and press Enter.• To print the formatted report, type a P in the CMD field and press Enter. The output is sent to your TSO

sysout.• For a summary report display, type an S in the CMD field and press Enter.• To view your statistics file in an unformatted display, type FIL or F in the CMD field and press Enter.• The SELECT STATISTICS screen also enables you to exclude certain types of information from being

displayed. Type a Y in any of the following fields and press Enter.

– MEMBERS - Statistics generated for each partitioned data set (PDS) member– WTO - WTO (Write to Operator) messages– WTO - All statistics other than WTO messages

When statistics are requested by Support, do not exclude any information. Set all the fields listed toN. Support must receive all information to solve the problem.

Verify File AttributesIf a problem occurs during a file transfer, verifying the accuracy of the file attributes can often resolvethe problem. Review the following file attribute parameters for the file being transmitted when the erroroccurred. Check both the input and output files specified in your IBM Connect:Direct Processes:

• Logical record length (LRECL)• Block size (BLKSIZE)• Record format (RECFM)• File organization (DSORG)• File disposition (DISP)• Unit containing the file (UNIT)• Volume serial number (VOLSER)• Storage for allocating new files (SPACE)• Optional processing code (OPTCD)• Length of keys used in file (KEYLEN)

Chapter 4. Administration Guide 433

• Number of blocks or tracks to search for available space (LIMCT)• SMS options and ACS rules

These parameters are described in detail at the Connect:Direct Process Language help.

Common ErrorsThis section describes the following types of common errors:

• Signon and IUI/API errors• Connect:Direct DTF session establishment errors• Connect:Direct DTF out-of-storage ABENDS• Allocation and open errors• Transmission errors• Operator interface errors

For each type of error, information on probable causes, actions to take, and data to collect is provided.

Note: For information on initialization and license key errors, see Initialization Errors in the IBMConnect:Direct for z/OS Configuration Guide that deals with errors that can occur when you start up.For errors related to security, see Troubleshooting Security Errors .

Signon and IUI/API ErrorsSignon errors keep you from accessing IBM Connect:Direct. IUI/API problems prevent you fromsuccessfully submitting a Process or executing a command.

This section describes the following types of signon and IUI/API errors:

• ISPF signon failures can be caused by a variety of problems. Errors signing onto the IUI through theISPF interface can include problems related to VTAM, TCP/IP, ISPF, or security. Refer to TroubleshootingSecurity Errors for a description of common security errors.

• IUI/API IBM Connect:Direct session failures occur when the IUI/API cannot establish a session with theDTF. A session failure usually means you will be unable to sign on to IBM Connect:Direct.

• SELECT command errors occur while issuing SELECT STATISTICS, SELECT PROCESS, SELECT NETMAP,SELECT USER, SELECT TYPE, and SELECT TASK commands from the IUI, batch, or operator interface.

Note: You can diagnose most IUI/API problems by running an API-to-DTF session trace. See informationon the NDMCMDS trace in IBM Connect:Direct Automatic Traces.

To avoid insufficient space being allocated for the temporary data set upon signon as well as SB37ABENDs, the administrator can define global signon defaults so that users do not have to individually altertheir signon default values to increase their allocation. For more information, see “Global Signon Defaults”on page 183.

Condition: Signon to IUI DeniedYour signon to IUI is denied with the message Error during ACB open.

434 IBM Connect:Direct for z/OS: Documentation

Error Cause Action Collect

SVTB002I The interactive applidthat is used for signonis not active, is in anunacceptable state, or isnot correctly defined toVTAM.

Review both the short text andlong text messages. AllocateNDMCMDS to display errormessages to your terminal.NDMCMDS shows all actualcommands issued to the DTF,including resolution of symbolics. Itcan be particularly helpful to debugIBM Connect:Direct commandsthrough the IUI or through thebatch interface if you are havingsignon problems, syntax errors,and so forth.

• For Connect:Direct for z/OS, typethe following on your commandline:

TSO ALLOC FI(NDMCMDS) DA(*)

• NDMCMDS output• Applid status display• Applid definitions• Network map

Condition: Signon to IUI DeniedYour signon to IUI is denied with the message USER attempted SIGNON with TIMEOUT=NO. Only anadministrator can change the TIMEOUT value and only on their own signon panel. Non-ADMIN userscannot sign on with the inactivity timer disabled.

Note: The inactivity timer indicates the number of minutes a user can remain inactive withoutcommunicating with the DTF. This timer is active if an administrator has specified a value in theTCP.API.TIMER global initialization parameter.

Error Cause Action Collect

SAFA020I The user, who doesnot have administrativeauthority, attempted tochange the TIMEOUTparameter value to NOfrom an IUI signon panel.

Log off and log on again. Changethe TIMEOUT parameter to YES tocomplete the signon process.

• Statistics file

Condition: Signon to IUI Denied - No Error MessageYour attempt to sign on to the IUI is denied, but no error message is displayed.

Error Cause Action Collect

None Your TSO or TSS profilespecifies the NOWTPMSGoption, which inhibitssome error output frombeing displayed to theterminal.

Review both the short text and longtext messages. For z/OS, changeto the WTPMSG option by typingTSO PROF WTPMSG. With theWTPMSG option, error messagesare displayed at the terminal. Retrythe operation (sign on).

• None

Condition: Signon Denied - IBM Connect:Direct not ActiveYour signon is denied.

Chapter 4. Administration Guide 435

Error Cause Action Collect

SVTB004I

SCIA011I

The IBM Connect:Directyou are signing on to isnot active.

Review both the short textand long text messages. Ensurethat IBM Connect:Direct hascompleted initialization beforeattempting a signon. AllocateNDMCMDS to display additionalinformation about the sessionfailure. NDMCMDS shows all actualIBM Connect:Direct commandsissued to the DTF, includingresolution of symbolics. It can beparticularly helpful to debug IBMConnect:Direct commands throughthe IUI or through batch interfaceif you are having signon problems,syntax errors, and so forth.

For z/OS, check to see that thenetwork map is specified correctlyon the ISPF menu and that thenetwork map is correctly loaded.

Try to sign on through the batchinterface to isolate the problem.

• NDMCMDS output• Network map• IBM Connect:Direct

initialization parameters• For z/OS the ISR@PRIM panel

Condition: Signon Denied - Users Exceeds LimitSignon is denied.

Error Cause Action Collect

STAA004I The number ofinteractive users onIBM Connect:Direct hasreached the limit setin the MAXUSERSparameter.

Review both the short text and longtext IBM Connect:Direct messages.Check the MAXUSERS parameterin the IBM Connect:Directinitialization parameters data set.If it is commented out, thedefault is six users. Report thiserror to your IBM Connect:Directadministrator, and determinewhether you need to increasethe value of this parameter.If the TCP.API.TIMER is notbeing used, consider using thisglobal initialization parameterto terminate orphaned sessions(some JAI users do not sign off,they just drop the connection).

• IBM Connect:Directinitialization parameters

Condition: TCP/IP API session terminatedUsers who are logged on to the DTF via TCP/IP may have their sessions dropped and see the messageTCP/IP SEND error; Connection Lost. If the user presses F1 to see the help for this message, the followingtext is displayed for message SVTC006I:

436 IBM Connect:Direct for z/OS: Documentation

MSGID ==> SVTC006I MODULE ==> DMTSTSND

TCP/IP SEND error; Connection Lost

An error has been detected while sending a command via TCP/IP.The TCP/IP connection has been lost. A possible cause isConnect:Direct has been shutdown and all TCP/IP connectionshave been closed.

System Action: Normal processing can not continue.

Response: Logoff and attempt to signon again.

In addition, SAFA019 signoff errors are recorded in statistics along with matching user IDs and themessage, TCP API session LOGOFF has been forced. To reduce the number of active sessions andstay below the limit set in the MAXUSERS global initialization parameter, the administrator can usethe TCP.API.TIMER global initialization parameter to specify the maximum time of session inactivity aTCP/IP-connected IUI or API session waits before timing out and exiting. When a user has not doneanything with the IUI to cause it to communicate with the DTF and the timer period expires, the DTF dropsthe session, and can then detect and recover lost sessions without having to be recycled.

Error Cause Action Collect

SVTC006I

SAFA019

The TCP.API sessionhas been inactive forthe period specified bythe TCP.API.TIMER globalinitialization parameter.

• A TSO/ISPF/IUI user shouldlog on to the DTF they lostconnection with.

• A program or system that wasusing the API should sign onagain.

• Statistics file–check theuser and completion code(comp code) associated withthe SAFA019I completionmessage (comp msg). On theSELECT STATISTICS screen,type Y in the CHANGEEXTENDED OPTS field andon the next screen, type SO(signoff) as a Record Type.

Condition: SELECT Command Issued Successfully - No Output ProducedThe SELECT command is issued successfully and completes with a successful return code and message,but no output is produced.

Error Messages

SAFF000I SAFF014I SAFK000I SAFL000I SAFL010I SCBB000I

SCBL000I SCBO000I SCBP000I SCBQ000I SCBX000I SOPA000I

SOPA011I SOPE000I SOPS001I

Cause Action Collect

It is likely that IBMConnect:Direct is having troubleallocating the temporary dataset that contains the outputfrom the SELECT command.

Review both the short text and longtext messages. For Connect:Direct forz/OS, specify a UNIT and VOLSER forthe temporary data set, and SPACEinformation. You can specify UNIT andVOLSER on the SIGNON DEFAULTS panelof the IUI or use the TEMPDSN parameteron your signon command for batch. Notethat a UNIT type of VIO is not acceptable.

• List of the SELECT commandsthat produce output and thosenot producing output

• Any error messages

Chapter 4. Administration Guide 437

Condition: SELECT Commands - No Output AvailableSELECT commands return with no output and a message indicating no output was available from thecommand.

Error Cause Action Collect

SOPA010I

SOPB012I

For the SELECT PROCESSand SELECT STATISTICScommands, it is likelythat the userid issuingthe command is definedas a general user bythe stage 2 security exit,indicating that the useris only allowed to seethe command output forProcesses submitted bythat same userid.

Review both the short text andlong text messages. Check to seethat the userid is defined with theability to select Process/statisticsfor Processes not submitted by thatuserid.

• Authorization for the userid• Statistics file

IBM Connect:Direct DTF Session-Establishment ErrorsIBM Connect:Direct DTF session-establishment errors prevent a successful connection between two IBMConnect:Direct systems. This section explains the most common causes of DTF session-establishmenterrors, actions to take, and the types of data you need to collect to troubleshoot the error.

Condition: Cannot Establish a Session with Another IBM Connect:Direct SessionThe table describes the four possible causes and the courses of action to take.

Error Cause Action Collect

SVTM026I

SVTM045I

SVTM053I

SVTM104I

The links that connect the two IBMConnect:Direct systems are not active,or an error has occurred on the links.

Review both the short text and longtext messages. If you are unable todetermine the problem, check theRPLERRCK DD for possible clues. Useyour network management software todetermine the status of the links usedfor system-to-system communication.Reactivate the links.

• None

SVTM026I The cross-domain resource definitionfor the remote IBM Connect:Directsystem is not active.

Review both the short text and longtext messages. If you are unable todetermine the problem, check theRPLERRCK DD for possible clues. Useyour network management softwareto determine the status of the IBMConnect:Direct cross-domain managerand cross-domain resource definitionsused in communicating with other IBMConnect:Direct locations. Reactivate thecross-domain resource manager orcross-domain resources

• None

438 IBM Connect:Direct for z/OS: Documentation

Error Cause Action Collect

SNAS0801

SVTM026I

The VTAM applid for the remote IBMConnect:Direct system is not active.

Review both the short text and longtext IBM Connect:Direct messages.If you are unable to determine theproblem, check the RPLERRCK DDfor possible clues. Use your networkmanagement software to determinethe status of the applid for theremote IBM Connect:Direct system.Ensure the remote IBM Connect:Directhas initialized. Reactivate the VTAMapplid, or initialize the remote IBMConnect:Direct. system.

• None

SCCS028I

STAA005I

The maximum number of secondarysessions is reached on the secondaryIBM Connect:Direct system.

Review both the short text and longtext messages. If you are unable todetermine the problem, check theRPLERRCK DD for possible clues.Determine the number of active VTAMsessions for the secondary location.Use your network management softwareto issue D NET,ID=applid,E (VTAMapplid) at the secondary location site.Ensure that the maximum number ofsecondary sessions is sufficient for yourrequirements.

To avoid the situation thatcauses the STAA05I error, setthe global initialization parameter,“TCP.CONNECT.TIMEOUT= 30 | numberof seconds” on page 501.

• None

IBM Connect:Direct DTF Out-of-Storage ABENDSDTF out-of-storage ABENDS may occur during heavy IBM Connect:Direct activity or during phases whenthe DTF has run for a long period of time. This chapter explains the most common causes of DTFout-of-storage ABENDs, actions to take, and the types of data to collect.

Condition: Out-of-Storage ABEND Occurs in the DTFThe following table describes two possible causes and associated actions to take.

Chapter 4. Administration Guide 439

Error Cause Action Collect

user ABENDU0500

user ABENDU0501

If this conditionoccurs onlyduring heavyIBM Connect:Directactivity, you mayneed to modifythe initializationparameters orthe DTF REGIONparameter.

Review both the shorttext and long textmessages. Limit thenumber of Processes thatcan run at one timeusing the MAXPRIMARY,MAXSECONDARY, andMAXPROCESS initializationparameters. Also, examinethe MAXSTGIO initializationparameter to determine ifit can be decreased. TheREGION size in the DTF JCLmay need to be increasedto allow more concurrentProcesses.

• TSubpool that is growing• Dump taken after controlled tests

when all DTF activity has ended• The IBM Connect:Direct log• IBM Connect:Direct initialization

parameters• IBM Connect:Direct STC (started

task) JCL• Source for any user exits

SystemABENDSx0A

SystemABENDSx78

If this conditionappears to be"storage creep" andoccurs after theDTF is active fora long time (notnecessarily runningmany Processesimmediately), youcan take severalactions.

• See Possible Actions totroubleshoot this problem.

• Dump taken after controlled testsafter all DTF activity ended

• The IBM Connect:Direct log• IBM Connect:Direct initialization

parameters• IBM Connect:Direct STC JCL• Source for any user exits

Possible ActionsUse the following list to help you troubleshoot DTF out-of-storage ABENDs:

• Examine all RUNTASK programs; ensure that for every file opened, a CLOSE and a FREEPOOL is alsodone.

• Examine any user exits for GETMAIN (or STORAGE OBTAIN) macros ; verify that FREEMAIN (orSTORAGE RELEASE) macros are issued for each of those areas.

• Examine any RUNTASK programs for GETMAIN (or STORAGE OBTAIN) macros; ensure FREEMAIN (orSTORAGE RELEASE) macros are issued for each area.

• Try to pinpoint the type of Processes or other DTF activity that causes the problem:• Does this occur only during a COPY?• Does this occur when a specific Process is run? What does the Process do?• Does this occur when a certain command is issued? What is the command?

Note: For the next two suggestions, you can issue an MVS DUMP command for the Connect:Directfor z/OS address space to help in your investigation. Make sure that the SDATA includes the followingparameters:

RGN,LSQA,SUM,PSA,GRSQ,SQA,SWA,TRT

See the IBM MVS System Commands manual for the release of z/OS in use.

• If you cannot determine which Process, command, or other activity is causing the storage creep, run atypical batch of Processes or commands that runs when the ABEND occurs. Before the out-of-storageABEND occurs, go to the ADMIN MD panel and QUIESCE Connect:Direct for z/OS. For example, if theABEND usually occurs after 10 hours of activity, quiesce after about 8 hours.

440 IBM Connect:Direct for z/OS: Documentation

• If you did determine that a certain Process or command causes the problem, submit that Process orissue the command several times (the number of times depends on how long it takes before you get tothe ABEND). For example, if it occurs after the Process runs 100 times, run it 90 times in your tests. Geta dump of the DTF address space after all DTF activity is finished.

Allocation and Open ErrorsAllocation and open errors involve the source or destination files. This chapter describes errors in whichthe allocation or opening of a file fails, and the action to take and types of data you need to collect totroubleshoot the error.

Condition: Allocating a User File FailsUse the following table to troubleshoot this error.

Note: IBM Connect:Direct initialization parameters (ALLOC.CODES and ALLOC.RETRIES) determine whichallocation errors, if any, cause a Process that fails on an allocation error to be retried.

.

Error Cause Action Collect

SDAA001I

SDAA004I

SDAA005I

SDAA048I

IBM Connect:Directreceived an error whileallocating a file or dataset.

Review both the short text and longtext messages. Check the SYSLOG,console, or IBM Connect:Directstatistics for the text ofthe SDAA004I and SDAB005Imessages. The SDAA004I messagecontains the allocation parametersused by IBM Connect:Direct. Ifan error exists, the ERR=nnnnfield of the SDAB005I messagecontains non-zeroes, and errortext follows. Use the IBMConnect:Direct message facility tolook up the error, which has aformat of SDEnnnnI, where nnnnis the number in the ERR field.The operating system dynamicallocation routine returns the ERRvalue.

Note: IBM Connect:Directinitialization parameters(ALLOC.CODES andALLOC.RETRIES) determine whichallocation errors, if any, cause aProcess that fails on an allocationerror to be retried.

• IBM Connect:Directallocation string (found inthe WTO records in thestatistics file)

• IBM Connect:Direct Processinvolved

• SDAA004I message output• SDAB005I message output

Condition: TCQ File Below Defined Threshold ValueUse the following table to troubleshoot this problem.

Chapter 4. Administration Guide 441

Error Cause Action Collect

SPQL003I

TCQ file isnow belowthe definedthreshold of&VAR.

The number of VSAM fileCIs used has reached thedefined threshold.

Reduce the number of Processes inthe TCQ, or increase the size of theTCQ. Refer to “Configure the TCQ”on page 390 for more information.

• None

Transmission ErrorsTransmission errors include consistency problems within communication components that can occurduring Process execution. The errors can occur within communication components such as VTAM, IBMNetwork Control Program (NCP), or links.

This section lists possible transmission errors, error messages, probable causes, actions to take, and datato collect to troubleshoot an error.

Condition: Error During Process Execution InitiationError Cause Action Collect

SVTM041I(SNASYNC1:Sessionabnormallyterminated)

The session or link was lostbefore Process execution began.

Review both the short text and longtext messages. Use your networkmanagement software to determinethe status of the link, cross-domaindefinitions, and applids used inthe system-to-system communication.Activate the link, cross-domaindefinitions, or applids as required, andrestart the Process

• None

SVTM053I(Sessionacquirefailure)

A protocol error occurred withinthe IBM Connect:Direct system.

Review both the short text and longtext messages. Also, request a sessionmanager trace and an RPL trace.

• Output fromsession manager

• Output from RPLtraces

Condition: Unrecoverable Error Occurs while a Process ExecutesWhen an unrecoverable send or receive error occurs within the system-to-system session while a Processexecutes, the three likely causes of the problem are detailed in the following table. You may need abackup copy of the file if a file I/O error caused a send or receive error. If the error is temporary, retryingthe Process might clear up the difficulty.

442 IBM Connect:Direct for z/OS: Documentation

Error Cause Action Collect

SVTM045I An I/O error within theprimary or secondarynode causes IBMConnect:Direct to send anegative response to theother location.

Review both the short text andlong text messages. Accompanyingmessages indicate the type of errorthat caused the send or receivesession to fail. Check your networkmanagement software for VTAMsense codes, then find the reasonthe sense code was issued. Correctthe problem if possible and retrythe Process.

In some cases, you need a VTAMbuffer or an I/O trace of the error.You may need a backup copy ofthe file if a file I/O error causedsend or receive error. If the erroris temporary, retrying the Processmight clear up the difficulty.

• Output from the VTAM bufferor I/O trace

SVTB020I,followed by aU4095ABEND

A IBM Connect:Directsystem shuts down witheither the IMMEDIATEor FORCE parameterspecified on the STOP CDcommand.

Review both the short text andlong text messages. Restart IBMConnect:Direct.

• None

SVTM042ISVTM043ISVTM044ISVTM045ISVTM046ISVTM047ISVTM048ISVTM049I

VTAM sensecode 0870

VTAM sensecode 800A

An error occurswithin one ofthe communicationcomponents (VTAM, NCP,or link)

Review both the short textand long text messages.The communication componentcontaining the error issues errormessages. Various VTAM and NCPdefinitions are incompatible withIBM Connect:Direct operations.Refer to Selecting RU Sizes inthe IBM Connect:Direct for z/OSConfiguration Guide for moreinformation.

• VTAM definitions• NCP definitions

Operator Interface ErrorsOperator interface errors occur while you are using the operator interface to issue commands to IBMConnect:Direct. You can find more information on the operator interface in the IBM Connect:Direct for z/OSFacilities Guide.

This section lists possible operator interface errors, error messages, possible causes, actions to take, anddata to collect to troubleshoot an error.

Task Busy MessageUse the following table to troubleshoot the problem when you receive a Task Busy message after issuingan Operator Interface command.

Chapter 4. Administration Guide 443

Error Cause Action Collect

IEE342IModifyrejected -task busy

An error in theMCS.SIGNON parameterin the IBM Connect:Directinitialization parameters.

Ensure that the MCS.SIGNONparameter reflects a valid userid-password combination withIBM Connect:Direct operatorauthority. Remove commentsfrom this parameter.

• IBM Connect:Directinitialization parameters

• SYSLOG output

User Not Authorized MessagesUse the following table to troubleshoot authorization errors you receive when you issue operator interfacecommands.

Error Messages

SCBB001I SCBC030I SCBD001I SCBE001I SCBF001I SCBF063I

SCBF064I SCBG001I SCBH001I SCBI001I SCBJ001I SCBK005I

SCBL001I SCBN001I SCBO001I SCBP001I SCBR002I SCBS001I

SCBT005I SCBU003I SCBV001I SCBW001I SCBX001I SCBY001I

SCPA008I SFIA002I SFIA003I SRJA014I SRTA008I SSUB100I

Cause Action Collect

The userid attempting toissue the operator interfacecommands is not authorizedto issue them.

Review both the short text and long textmessages. Check the userid specified inthe MCS.SIGNON parameter of the IBMConnect:Direct initialization parameters file.Determine whether that userid has theauthority to issue the command. If youbelieve it does, run a security trace todetermine why the user cannot issue thecommand.

See Security Traces for information on howto run the trace.

• IBM Connect:Directinitialization parameters

• Security trace

Diagnostic ToolsYou can perform some problem isolation and diagnostics by running traces. A trace is a sequentialrecording of program events during execution. Trace output is useful only as a diagnostic tool for theSupport.

When running traces for Support, consider the following information:

• Limit IBM Connect:Direct activity while running traces.• Trace the simplest case possible.• Disable traces upon completion. They generate considerable overhead.• Use traces judiciously. They are for diagnostic purposes only and there is potential security exposure.

Security TracesSupport uses a security trace to debug security problems. The trace shows:

• Fields from the security control block• Messages

444 IBM Connect:Direct for z/OS: Documentation

• Return codes from the security system itself such as IBM RACF, CA-TOP SECRET, and ACF2• Data set names, if verifying data sets• Userids (passwords will not displayed as encrypted or plain text)

Note: To prevent a remote node's security from discovering and then using Signon dummy passwords togain access to a primary node, you can use the initialization parameter, “REMOTE.DUMMY.PASSWORD =[ YES | INTERNAL ]” on page 486. REMOTE.DUMMY.PASSWORD only works when using the STAGE1 andSTAGE 2 SECURITY exits.

Starting a Security Trace for the First Time in the DTFNote: Once you have completed this procedure, go to Turning a Security Trace On and Off in the DTF AfterInitial Setup when you need to start a security trace. You do not have to reinitialize IBM Connect:Direct.

1. Specify TRACE=DEBUG as a parameter in your security exit source and reassemble and link-edit theexit.

2. For Connect:Direct for z/OS in the IBM Connect:Direct startup JCL, allocate a DD for SECURITY, eitherto SYSOUT or to a data set on DASD with attributes of RECFM=VBA, LRECL=121, and BLKSIZE=125 orgreater.

To be able to turn security tracing on and off using DEBUG settings, add the DEBUG= parameter to theglobal initialization parameter data set, and specify 00100000 (or xx1xxxxx where x is any hex value0-F).

Note: If you specify Separate trace per task tracing to be done for security traces, all output for thesecurity trace will be routed to the task DD, for example, Rnnnnnnn.

To turn security tracing off, you can then specify xx0xxxxx using the IBM Connect:Direct MODIFYcommand to specify the debug setting.

3. If IBM Connect:Direct is active, stop IBM Connect:Direct. Restart it with the modified JCL startup job,and recreate the problem.

Turning a Security Trace On and Off in the DTF After Initial SetupUse the MODIFY command to turn tracing on and off by specifying DEBUG settings (see Debug Settings).

Starting a Security Trace in the IUI (ISPF)You can start a security trace to debug security problems in the IUI.

1. To allocate a security trace for the IUI, enter the following command:

TSO ALLOC FI(APISECUR) DA(*) /* FOR ZOS */

Note: As an alternative, to send the information to a preallocated data set with attributes ofRECFM=VBA, LRECL=121, and BLKSIZE=125, you can enter the follow command:

TSO ALLOC FI(APISECUR) DA('$hlq.APISECUR.TRACE')OLD2. Log on to the DTF and carry out any commands you want traced. Trace information is written to the

screen immediately upon signon. Sign off when finished.3. To stop the security trace, issue the following command:

TSO FREE FI(APISECUR) /* FOR ZOS */

IBM Connect:Direct Function TracesIBM Connect:Direct contains various internal traces for diagnosing problems and recording events. Basedon the trace specified, the IBM Connect:Direct trace output is directed to various ddnames. You canenable these traces using one of the following methods:

• Modify the IBM Connect:Direct startup job stream to include the trace files and ddnames for traceoutput and add the DEBUG=nnnnnnnn parameter to the initialization parameter data set. The traces areturned on during IBM Connect:Direct initialization and continue running until turned off by the MODIFYcommand or until IBM Connect:Direct is terminated.

Chapter 4. Administration Guide 445

• Issue the IBM Connect:Direct MODIFY command to set DEBUG bits. The trace starts when you issue theMODIFY command. See IBM Connect:Direct MODIFY Command.

• Reduce the amount of trace information by restricting a trace to a Process (MODIFY Debug = parameter)or a specific node (NODE.TRACE.ON parameter). See IBM Connect:Direct MODIFY Command for moreinformation about these parameters.

Debug SettingsUse the following debug settings with the:

• DEBUG=nnnnnnnn initialization parameter• BITS.ON=X'nnnnnnnn'• BITS.OFF=X'nnnnnnnn'• MODIFY command parameters• NODE.TRACE.BITSON=(node name,X'nnnnnnnn')• NODE.TRACE.BITSOFF=(node name,X'nnnnnnnn')

For each debug bit turned on for a trace, you must allocate the equivalent DD names in the Output DDcolumn to the IBM Connect:Direct started task. If you do not specify these DD names in the started taskJCL of IBM Connect:Direct, you must allocate them using either the DYN (batch) or DYN (IUI) optiondescribed in this section. The one exception is separate trace per task (Rnnnnnnn), which is dynamicallyallocated by IBM Connect:Direct as required. This trace output is directed to SYSOUT.

For each debug bit turned on for trace using any of the above mentioned methods a new databasestatistic record type is generated and recorded to diagnose problems and record events. The audittrail can be viewed using the INQUIRE DEBUG command as described the procedures in the followingsections.

Example Database Statistic Record Output

This following record displays old and new DEBUG Bits. Note that the mode using which the DEBUG bitswere modified that generated this record.

================================================================================CDZOSA.SDEV1 SELECT STATISTICS DATE : 04.06.2020================================================================================

________________________________________________________________________________Function => Debug RecordDate => 04.06.2020 Time => 23:46:18Node Name => CDZOSA.SDEV1Process Name => SDEV1 Process Num => 3Set By => Process This Node => POld Bits => FFFFFEFF New Bits => 12345678

The following table shows the available function traces for Connect:Direct for z/OS, with their respectiveDEBUG settings, and the DD names (or filenames) used for output. Specify these bits using hexadecimalnotation, for example, X'80' plus X'10' would result in X'90' while X'08' plus X'04' would result in X'0C'.

DEBUG Setting Trace Type Output DD

80000000 COPY Routine and RUN TASK trace RADBDD01

10000000 Full TPCB/SYMBOLICS from DMCBSUBM DMCBSUBM

08000000 Session manager trace RADBDD05

04000000 Separate trace per task

(Example: “R0000005” to trace TASK 5)

Rnnnnnnn

02000000 API session trace RADBDD07

01000000 DMGCBSUB trace RADBDD08

446 IBM Connect:Direct for z/OS: Documentation

DEBUG Setting Trace Type Output DD

00400000 TCQSH from DMCOPYRT DMCOPYRT

00200000 Make each SVC dump unique N/A

00100000 SECURITY trace control SECURITY

00040000 GETMAIN/FREEMAIN trace RADBDD16

00008000 I/O buffer trace RADBDD21

00004000 WTO all dynamic allocation parameters RADBDD22

00002000 IBM Connect:Direct/Plex traces

ACTION queue manager trace CDPLXACT

CKPT queue manager trace CDPLXCKP

TCQ queue manager trace CDPLXTCQ

STATS queue manager trace CDPLXSTA

First REQUEST queue manager trace CDPLXREQ

Second and subsequent REQUEST queue manager trace. Forexample, “CDPLXR03” traces the third queue manager.

CDPLXRnn

JOIN queue manager trace CDPLXJOI

00001000 Workload Balancing trace CDPLXWLB

00000800 zIIP-related trace CDZIIP

00000100 In-storage tracing only

Note: The size of this in-storage table is controlled by theTRACE.BUFFER initialization parameter.

N/A

00000080 RPL trace - long

Note: To avoid generating excessive output when you use this tracewith a large value for the V2.BUFSIZE initialization parameter, usethe short RPL trace.

RPLOUT

00000040 RPL trace - short RPLOUT

00000020 Version 2 session trace RADBDD33

00000008 Logon exit trace RADBDD35

00000004 Logon Processor trace RADBDD36

00000002 SCIP exit trace RADBDD37

00000001 SNMP trap trace SCTRAPDD

Displaying DEBUG SettingsUse the INQUIRE DEBUG command to display the current DEBUG settings for each adjacent node in theNetmap.

The INQUIRE DEBUG command has the following format and parameter.

Label Command Parameter

(optional) INQuire DEBUG WHERE (SERVER=server name)

Chapter 4. Administration Guide 447

The parameter for the INQUIRE DEBUG command is:

Parameter Description

WHERE(SERVER=servername)

This parameter is optional. This parameter specifies the IBM Connect:Direct/Server whose DEBUG settings you want to view. The server name parameteris the 1–8 character name assigned to a IBM Connect:Direct/Server bythe CDPLEX.SERVER initialization parameter. If you omit this parameter ina IBM Connect:Direct/Plex environment, the DEBUG settings for the IBMConnect:Direct/Manager are displayed. You cannot use this parameter in a IBMConnect:Direct/Stand-alone Server. See Debug Settings for a descriptions ofthese settings.

Using the INQUIRE DEBUG Command from the Batch InterfaceTo use the INQUIRE DEBUG command from the batch interface:

1. Place your command in a batch job stream.2. Submit the job while IBM Connect:Direct is running.

Note: You must set the fifth character of the DGADBATC output parameter specification to Y to printthe result of the command that is in the temporary data set.

3. Verify the results.

The following figure shows a partial sample report:

======================================================================CD.CHI *INQ DEBUG/QUIESCE* DATE: mm.dd.yyyy TIME: hh:mm:ssSYSTEM INITIALIZED --------(0000)-------- mm.dd.yyyy hh:mm:ss======================================================================

DEBUG => '00200000'QUIESCE => NoTCQ DSN => PROD1.CD.CHI.TCQTCX DSN => PROD1.CD.CHI.TCXTCQ Threshold => NoTCQ File 0% Full. Max.# CI: 1000 # Used CI: 0

NODE TABLE => NODE NAME QUIESCE DEBUGNODE ENTRY 1 => CD.DAL Yes B0BB0BB0NODE ENTRY 2 => CD.DAL.CSGA YesNODE ENTRY 3 => CD.DAL.CSGB YesNODE ENTRY 4 => CD.DAL.LU0 YesNODE ENTRY 5 => CD.DAL.LU62 Yes

Issuing the INQUIRE DEBUG Command through the IUITo display the DEBUG settings from the IUI:

1. Select option INQ from the Connect:Direct Administrative Options Menu.

The Inquire DTF Internal Status screen is displayed.2. If you want to view the DEBUG settings for a specific IBM Connect:Direct/Plex member, type the server

name in the Server field. If you want to view the DEBUG settings for a IBM Connect:Direct/Manager,leave the Server field blank.

Leave the Server field blank in a IBM Connect:Direct/Stand-alone Server.3. Select the IDBG option.4. Press ENTER.

The current DEBUG settings are displayed.

448 IBM Connect:Direct for z/OS: Documentation

DEBUG Initialization ParameterVarious settings on the DEBUG=nnnnnnnn initialization parameter turn on a specific trace option or anycombination of options. In the syntax for the DEBUG initialization parameter, nnnnnnnn represents theDEBUG setting in hexadecimal.

You can place trace DD statements in the system without slowing down IBM Connect:Direct performanceif you do not turn on the trace by specifying the DEBUG parameter.

For problems with SNA connections, use the following four function traces merged into a single outputfile:

• Session manager trace• Separate trace per task trace• Long RPL trace• COPY routine trace

Note: If the problem occurs during file transfer or session establishment of node connections, run thetrace on both the sending and receiving nodes.

IBM Connect:Direct MODIFY CommandThe IBM Connect:Direct MODIFY command yields the same types of traces as the DEBUG initializationparameter. Unlike the initialization parameter, however, the MODIFY command does not require you tobring down and restart the DTF. The trace starts when you issue the MODIFY command to turn on thetrace bits, provided the DD is allocated.

Note: When JES data sets are dynamically allocated, specify FREE=CLOSE to ensure that the DD isdeallocated and tracing stopped when you close the trace DD using the MODIFY command.

You can issue the MODIFY command through the batch interface or interactively through the IUI. SeeIssuing the MODIFY Command Through the Batch Interface or Issuing the MODIFY Command through theIUI. To see the current DEBUG setting, see Displaying DEBUG Settings.

The MODIFY command has the following format and parameters. None of these parameters are required.

Label Command Parameters

(optional) MODIFY BITS.OFF = X'nnnnnnnn'

BITS.ON = X'nnnnnnnn'

CLOSE = ddname

DDNAME = (ddname, nn)

DEBUG = nnnnnnnn

DYN (batch) = 'dynamic allocation string'

Note: Use an equal sign before and quotes around the dynamic allocationstring.

DYN (IUI) dynamic allocation string

Note: Do not use an equal sign before or quotes around the dynamicallocation string in the IUI screen unless you are entering it on theCommand Line Interface..

INITPARMS = YES

MODDIR.TRACE = YES

NODE.TRACE.BITSOFF=(node name, X'nnnnnnnn')

NODE.TRACE.BITSON=(node name, X'nnnnnnnn')

Chapter 4. Administration Guide 449

Label Command Parameters

NODE.TRACE.ON = (node name, debug bits)

NODE.TRACE.OFF = node name

WHERE(SERVER = server name)

ZIIP = NONE | EXTCOMP | SSLTLS | ALL | PROJECT

The following table describes the parameters of the MODIFY command.

Parameter Description

BITS.OFF = X'nnnnnnnn' Turns individual trace bits off. Refer to Debug Settings for the'nnnnnnnn' value.

BITS.ON = X'nnnnnnnn' Turns individual trace bits on. Refer to Debug Settings for the'nnnnnnnn' value.

CLOSE = ddname This parameter specifies the DD name that is closed in the IBMConnect:Direct DTF.

DDNAME = (ddname, nn) This parameter specifies a DD name related to a requested trace.All trace information generated as a result of the BITS.ON setting isdirected to the DDNAME indicated in the parameter list, based onthe IBM Connect:Direct TASKID number nn. This DDNAME providesa consolidated trace of all activity associated with the task. TheDDNAME format is R00000nn, where nn is the TASKID.

DEBUG = nnnnnnnn Replaces the system-wide debugging bits with the specified debugbits. Refer to Debug Settings to see all possible debug bit values.

DYN = 'dynamic allocationstring' (batch)

This parameter specifies that dynamic allocation is invoked in the DTFusing a specified allocation string. Use an equal sign before and quotesaround the dynamic allocation string in the batch DYN parameter.

You must use an equal sign before and quotes around the dynamicallocation string in the Command Line Interface for the IUI.

DYN dynamic allocation string(IUI)

This parameter specifies that dynamic allocation is invoked in the DTFusing a specified allocation string. Do not use an equal sign before orquotes around the dynamic allocation string in the MODIFY DYN fieldon the MODIFY COMMAND screen.

Note: If you issue the MODIFY command in the Command LineInterface (CLI), you must use an equal sign before and quotes aroundthe dynamic allocation string.

INITPARMS Refreshes initialization parameters qualified to be modifieddynamically while IBM Connect:Direct is running.

MODDIR.TRACE=YES Requests a module trace.

NODE.TRACE.BITSOFF = (nodename, X'nnnnnnnn')

Turns individual trace bits off for a specified node. The node name isthe 1–16 character name of the node on which the trace runs. The* and ? wildcard characters are supported when specifying the nodename. Refer to Debug Settings for the 'nnnnnnnn' value.

NODE.TRACE.BITSON = (nodename, X'nnnnnnnn')

Turns individual trace bits on for a specified node. The node name isthe 1–16 character name of the node on which the trace runs. The* and ? wildcard characters are supported when specifying the nodename. Refer to Debug Settings for the 'nnnnnnnn' value.

450 IBM Connect:Direct for z/OS: Documentation

Parameter Description

NODE.TRACE.ON = (node name,debug bits)

Requests a trace run on one or more specified nodes. The node nameis the 1–16 character name of the node on which the trace runs. The* and ? wildcard characters are supported when specifying the nodename. The debug bits are the 8-character DEBUG bits setting. See theBITS.OFF = X'nnnnnnnn' parameter for a listing of debug bits.

The trace runs until turned off by the NODE.TRACE.OFF= parameter.

NODE.TRACE.OFF = (nodename)

Turns off a trace set by the NODE.TRACE.ON parameter.

The node name is the 1–16 character name of the node on which thetrace is running. The * and ? wildcard characters are supported whenspecifying the node name.

WHERE(SERVER=server name) This parameter specifies which IBM Connect:Direct/Plex member theMODIFY command applies to. The server name parameter is the 1–8 character name assigned to a IBM Connect:Direct/Server by theCDPLEX.SERVER initialization parameter.

If this parameter is omitted, the MODIFY command applies to the IBMConnect:Direct/Manager.

ZIIP = NONE | EXTCOMP |SSLTLS | ALL | PROJECT

This parameter specifies the setting for the zIIP exploitation feature(ZEF). Refer to “zIIP Exploitation Feature” on page 413 and “ZIIP =NONE | EXTCOMP | SSLTLS | ALL | PROJECT” on page 509.

Issuing the MODIFY Command Through the Batch InterfaceTo use the MODIFY command from the batch interface:

1. Place the command in the batch job stream.2. Submit the job while IBM Connect:Direct is running.3. Verify the results.

Examples of MODIFY Command through the Batch InterfaceThe following example turns on the short RPLOUT trace:

MODIFY BITS.ON = X'00000040'

The following example turns off the short RPLOUT trace:

MODIFY BITS.OFF = X'00000040'

The following example invokes dynamic allocation in the DTF to the allocated DDNAME RPLERRCK:

MODIFY DYN = 'DD=RPLERRCK'

The following job turns on the merged COPY routine and DMGCBSUB traces.

Chapter 4. Administration Guide 451

//TRACEON JOB (1111),‘TRACES',NOTIFY=JSMITH,CLASS=O,// REGION=1024K,MSGCLASS=X//STEP01 EXEC PGM=DGADBATC,PARM=‘YYSLYYY'//STEPLIB DD DSN=$CD.SDGALINK,DISP=SHR //DMPUBLIB DD DISP=SHR,DSN=JSMITH.CNTL// DD DISP=SHR,DSN=JSMITH.PROCESS.LIB//DMMSGFIL DD DISP=SHR,DSN=JSMITH.CD1.MSG//DMNETMAP DD DISP=SHR,DSN=JSMITH.CD1.NETMAP//DMPRINT DD SYSOUT=*//SYSPRINT DD SYSOUT=*//NDMLOG DD SYSOUT=* //SYSIN DD * SIGNON NETMAP=JSMITH.CD1.NETMAP USERID=(JSMITH) MODIFY BITS.ON=X‘81000000'SUBMIT PROC=ACCTSEPT SIGNOFF

The following job turns off the trace.

//NOTRACE JOB (1111),‘TRACES',NOTIFY=JSMITH,CLASS=O,// REGION=1024K,MSGCLASS=X//STEP01 EXEC PGM=DGADBATC,PARM=‘YYSLYYY'//STEPLIB DD DSN=$CD.SDGALINK,DISP=SHR //DMPUBLIB DD DISP=SHR,DSN=JSMITH.CNTL// DD DISP=SHR,DSN=JSMITH.PROCESS.LIB//DMMSGFIL DD DISP=SHR,DSN=JSMITH.CD1.MSG//DMNETMAP DD DISP=SHR,DSN=JSMITH.CD1.NETMAP//DMPRINT DD SYSOUT=*//SYSPRINT DD SYSOUT=*//NDMLOG DD SYSOUT=*//SYSIN DD * SIGNON NETMAP=JSMITH.CD1.NETMAP USERID=(JSMITH)MODIFY BITS.OFF=X‘81000000' SIGNOFF

See IBM Connect:Direct for z/OS User Guide for a description of the batch interface, and the installationand administration guide for a description of the MODIFY command.

Issuing the MODIFY Command through the IUITo use the MODIFY command features through the IUI:

1. Request option MD from the Connect:Direct Administrative Options Menu to access the MODIFYCOMMAND screen.

node.name MODIFY COMMAND 14:34 CMD ==>

Server ==> ________ 00000000 (Current DEBUG Settings) MODIFY DEBUG ==> ________ (nnnnnnnn) MODIFY BITS.ON ==> ________ (nnnnnnnn) MODIFY BITS.OFF ==> ________ (nnnnnnnn) MODIFY DDNAME ==> ___________ (ddname,nn) MODIFY CLOSE ==> ________ (ddname) MODIFY MODDIR.TRACE ==> ___ (YES) MODIFY DYN ==> ____________________________________________________________ MODIFY SESSIONS ==> _ (Quiesce or Resume) NODE ==> ________________ MODIFY NODE.TRACE.ON ==> ( ________________ ________ ) MODIFY NODE.TRACE.OFF ==> ________________ MODIFY NODES ==> ___ (YES) MODIFY INITPARMS ==> ___ (YES) MODIFY ZIIP ==> _________ (ALL NONE EXTCOMP SSLTLS PROJECT)

2. Type values in the appropriate fields. See the MODIFY command parameter descriptions in IBMConnect:Direct MODIFY Command.

Note: Do not type an equal sign or quotes in the MODIFY DYN field. However, if you issue theMODIFY command on the CLI, you must type an equal sign before and quotation marks around thedynamic allocation string.

452 IBM Connect:Direct for z/OS: Documentation

3. When you have completed your entries, press ENTER.

Note: If you need to modify trace settings for more than one node, you can use the MODIFY NODESscreen which displays the Trace and Debug settings for all of the Netmap adjacent nodes. See ModifyTrace and Debug Settings Through the Modify Nodes Screen for more information.

Examples of MODIFY Commands through the IUIThis section shows examples of MODIFY commands for Connect:Direct for z/OS.

The following MODIFY commands set the bits to turn on a short send/receive trace and to dynamicallyallocate the ddname RPLOUT.

MODIFY DYN=‘DD=RPLOUT,DSN=A985467.PRINT,DISP=SHR,FREE=CLOSE’MODIFY BITS.ON=X‘00000040’

After running the trace, the following MODIFY commands close the ddname RPLOUT and turn off theshort send/receive trace.

MODIFY BITS.OFF=X‘00000040’MODIFY CLOSE=RPLOUT

Modify Trace and Debug Settings Through the Modify Nodes ScreenPerform the following procedure to modify trace and debug settings through the Modify Nodes screen.

1. Request option MD from the Connect:Direct Administrative Options Menu to access the ModifyCommand screen.

2. Type YES in the MODIFY NODES field.3. Press ENTER.

The Modify Nodes screen is displayed.

CD.PRD MODIFY NODES (Unsaved Changes) Row 1 of 1054 CMD ==> SCROLL ===> PAGE(CMD commands: CLEAR DEBUG/TRACE QUIESCE RESUME; CANCEL END REFRESH SAVE)(SEL commands: C=Clear Q=Quiesce R=Resume. Overtype Debug setting.) SEL Node Name Quiesce Debug Chg --- ---------------- ------- -------- --- CD.PRD.CSGA OFF 11111111 CD.PRD.CSGB OFF 11111111 CD.PRD.CSGD OFF 11111111 CD.PRD.CSGE OFF 11111111 CD.PRD.CSGF ON 11111111 Y CD.PRD.CSGG OFF 11111111 CD.PRD.VIPA OFF 11111111 CD.TST OFF FFFFFEFF CD.TST.%%%%% OFF FFFFFEFF CD.TST.CSGA ON Y CD.TST.CSGB OFF FFFFFEFF CD.TST.CSGD OFF FFFFFEFF CD.TST.CSGG OFF FFFFFEFF CD.TST.CTCA1 OFF FFFFFEFF CD.TST.CTCA2 OFF FFFFFEFF CD.TST.CTCA3 OFF FFFFFEFF

4. Use one or both of the following methods:

• Issue a Debug or Trace command on the CMD line.• Issue SEL commands or overtype the Debug field for specific nodes.

For more information, see “Modify Nodes Screen” on page 181.5. Type SAVE in the CMD field and press ENTER to save your changes.

Chapter 4. Administration Guide 453

IBM Connect:Direct Automatic TracesYou can activate some internal IBM Connect:Direct traces without using the DEBUG bits. Activatethese traces during normal IBM Connect:Direct operation. Others traces are useful mostly for problemdiagnosis. You can activate each of these automatic IBM Connect:Direct traces by having a DD statementin the IBM Connect:Direct startup JCL or allocated in a TSO session, except for NDMCMDS, which isallocated in the JCL for DGADBATC or through the IUI. For more information, see DD Statements inStartup JCL.

Note: To avoid generating excessive output, review Security Traces.

Some of the most useful automatic traces are:

• DMVSOPEN contains information related to the allocation of the target data set.• ESTAE captures information on I/O errors; VTAM connection errors; ABEND control blocks; open and

close errors; TCQ/TCX errors on add, update, and so forth; and statistics file write errors. Provided in thebasic DGAJCONN JCL member.

• CDESTAE contains various I/O errors from the statistics facility.• RPLERRCK captures VTAM send and receive errors. Provided in the basic DGAJCONN JCL member.• NDMCMDS shows all actual IBM Connect:Direct commands issued to the DTF, including resolution of

symbolics. It can be particularly helpful to debug IBM Connect:Direct commands through the IUI orthrough batch interface if you are having signon problems, syntax errors, and so forth.

• NDMLOG lists all initialization parameters read from the INITPARM data set including obsoleteparameters, which are indicated by SITA995I messages, and all modules, along with the last dateon which they were modified, and related fix numbers. Provided in the basic DGAJCONN JCL member.

• CDLOG is a chronological log of IBM Connect:Direct events listing all master, console, programmer, andoperator messages, and information on failed tests.

DD Statements in Startup JCLIBM Connect:Direct provides two members in the JCL file:

• DGAJCONN—Contains the minimum set of DDs to run IBM Connect:Direct. You may want to use this setof DD statements as the base and add specific DD statements from the DGAJCONX member to fit yourtracing needs.

• DGAJCONX—Contains all possible DDs to cover stand-alone servers, IBM Connect:Direct/Plex systems,automatic traces, and various DEBUG output. Most of the DD statements in this JCL startup jobstreamhave been discussed earlier in this chapter.

The DD statements in the DGAJCONX JCL can be broken down into the following types:

• Minimal DD statements included in the DGAJCONN JCL• DD statements for general operations• DD statements for running automatic traces.• DD statements for running detailed function traces in conjunction with the DEBUG initialization

parameter in a stand-alone IBM Connect:Direct system• DD statements for running detailed function traces in conjunction with the DEBUG initialization

parameter in a IBM Connect:Direct/Plex system

CAUTION: The diagnostic DD statements associated with the DEBUG bits cause much more I/Oand allocating them can consume significant CPU resources. To avoid degrading performance inyour production environment, be sure to follow the guidelines in Diagnostic Tools.

The following DD statements are included in both the DGAJCONN and DGAJCONX JCL:

DDNAME Function

STEPLIB IBM Connect:Direct SDGALINK.

454 IBM Connect:Direct for z/OS: Documentation

DDNAME Function

DMPUBLIB IBM Connect:Direct Process library

USRINFO Standard display from User exits

NDMLOG Automatic trace to list all initialization parameters read from the INITPARM dataset including obsolete parameters, which are indicated by SITA995I messages,and all modules, along with the last date on which they were modified, and relatedfix numbers.

ESTAE Automatic trace to capture I/O errors, VTAM connection errors, ABEND controlblocks, open and close errors, TCQ/TCX errors on adds and updates, and statisticsfile write errors.

RPLERRCK Automatic trace to capture VTAM/TCP send and receive errors.

The following DD statements run general functions in all systems:

DDNAME Function

SYSTERM Standard MVS

NSXOUT SNA NSXEXIT

CDDUMPR1 IBM Connect:Direct DUMP command output

ADRIOXLG Sysprint for DSS exit

SECURITY1 Security trace if Stage 2 exit has TRACE=DEBUG specified

CDSECURI Stage1 Security Trace

DMPRINT1 Submit command Output

APITRACE1 Stage2 API Trace, which consists primarily of IUI and batch interface activity

AXUNIQ Error Recovery1Can generate excessive output. Use judiciously.

The following DD statements are used to run automatic traces and perform related functions.

Note: To handle B37 (out of space) conditions when tracing to disk, code the DD statement withFREE=CLOSE, which will close and deallocate the dataset. The DD statement will not be reallocatedand tracing will stop. If the DD statement does not include FREE=CLOSE and a B37 condition occurs,the dataset is closed and reopened. Tracing continues and all old trace data to this DD is lost. WhenFREE=CLOSE is coded for JES datasets, closing the DD makes the JES entry available immediatelyfor printing or purging without affecting the other JES datasets. You could specify FREE=CLOSE inthe DD statement and then, using the ISPF MD dialog, periodically close the DD and reallocate itwith FREE=CLOSE. This would enable you to purge old JES entries without having to reinitialize IBMConnect:Direct.

DDNAME Function

DEVTRACE1 Traces UCB open and close activity.

DMGEVENT Traces Event Services activity.

DMVSOPEN Formats the allocation block.

CDESTAE Diagnostics on various I/O errors from the statistics facility. Allocate this name byincluding in the IBM Connect:Direct startup JCL.

IGWTRACE1 Traces PDSE program objects load to unload activity.

Chapter 4. Administration Guide 455

DDNAME Function

LOSTOUT Lost term exit trace.

NDMAPI Used for diagnostics on session errors with the API.

NDMCMDS IUI/Application Program Interface (IUI/API) commands passed to IBMConnect:Direct. Also use it for diagnostics on session errors with the API.

CDCMDS IUI/Application Program Interface (IUI/API) commands passed to IBMConnect:Direct. Also use it for diagnostics on session errors with the API.

CDLOG1 A chronological log of IBM Connect:Direct events listing all master, console,programmer, and operator messages, and information on failed tests.

1Can generate excessive output. Use judiciously.

The following output DD statements are used to run detailed function traces and perform relatedfunctions in a stand-alone system.

Output DD Trace Type DEBUG Setting

RADBDD01 COPY Routine and RUN TASK trace 80000000

DMCBSUBM Full TPCB/SYMBOLICS from DMCBSUBM 10000000

RADBDD05 Session manager trace 08000000

Rnnnnnnn Separate trace per task

(Example: “R0000005” to trace TASK 5)

Note: DDs are dynamically allocated by IBMConnect:Direct as required.

04000000

RADBDD07 API session trace 02000000

RADBDD08 DGADCBSU trace 01000000

DMCOPYRT TCQSH from DMCOPYRT 00400000

N/A Make each SVC dump unique 00200000

SECURITY SECURITY trace control 00100000

RADBDD16 GETMAIN/FREEMAIN trace 00040000

RADBDD21 I/O buffer trace 00008000

RADBDD22 WTO all dynamic allocation parameters 00004000

CDZIIP System z Integrated Information Processor (zIIP)-relatedtrace

00000800

RPLOUT RPL trace - long

Note: To avoid generating excessive output when youuse this trace with a large value for the V2.BUFSIZEinitialization parameter, use the short RPL trace.

00000080

RPLOUT RPL trace - short 00000040

RADBDD33 Version 2 session trace 00000020

RADBDD35 Logon exit trace 00000008

RADBDD36 Logon Process or trace 00000004

456 IBM Connect:Direct for z/OS: Documentation

Output DD Trace Type DEBUG Setting

RADBDD37 SCIP exit trace 00000002

SCTRAPDD SNMP trace 00000001

The following output DD statements are used to run detailed function traces and perform relatedfunctions in a IBM Connect:Direct/Plex environment:

Output DD Trace Type DEBUG Setting

CDPLXACT ACTION queue manager trace 00002000

CDPLXCKP CKPT queue manager trace

CDPLXTCQ TCQ queue manager trace

CDPLXSTA STATS queue manager trace

CDPLXREQ First REQUEST queue manager trace

CDPLXRnn Second and subsequent REQUEST queue managertrace. For example, “CDPLXR03” traces the thirdqueue manager.

CDPLXJOI JOIN queue manager trace

CDPLXWLB Workload Balancing trace 00001000

Global Initialization ParametersInitialization parameters supply values for various IBM Connect:Direct functions. IBM Connect:Directprocesses these parameters during initialization.

Global initialization parameters apply to a IBM Connect:Direct/Stand-alone Server or each member of aIBM Connect:Direct/Plex environment.

In a IBM Connect:Direct/Plex environment, the local initialization parameters of a member can overridesome global initialization parameters. See Local Initialization Parameters for more information about localinitialization parameters.

In all cases, initialization parameters are kept in a PDS (Partitioned Data Set) and may not come from asequential file.

Note: In a IBM Connect:Direct/Plex environment, you can only override initialization parameters allowedin the local initialization parameters file using the PARM= keyword in the EXEC statement at systemstartup. In a IBM Connect:Direct/Stand-alone Server environment, however, you can override globalinitialization parameters with the PARM= keyword in the EXEC statement.

Handling Return CodesIf you receive a return code of 4 when you stop IBM Connect:Direct, review the NDMLOG for informationregarding obsolete and soon-to-be obsolete parameters. Once you remove these parameters, you avoidthese warning messages at start-up. These messages are numbered: SITA995I, SITA988I, and SITA989I.

ABEND.CODES.NODUMP=(ABEND code list)The ABEND code list parameter specifies up to 16 system or user ABENDs. This parameter does not applyto RUN TASK ABENDS unless you specify ABEND.CODES.NODUMP for the ABEND.RUNTASK initializationparameter.

Chapter 4. Administration Guide 457

When a task ABENDs, IBM Connect:Direct searches this list. If the ABEND is found, the dump issuppressed. Use this parameter to prevent dumps on ABEND codes for which you do not need dumpinformation.

Specify system ABEND codes in the list using an S followed by three characters such as SB37.

Specify user ABEND codes in the list using a U followed by four numeric digits such as U4030.

Specify a wildcard masking character in the code using X. Place the X in any position following either the Sor U, such as SX37 or U40XX.

Note: It is not necessary to include the following ABEND codes in the ABEND.CODES.NODUMP listbecause they are suppressed by default: S00C (reason code 4 only), S047, S13E, S222, S422, SA03,U1024, U1025, U1028, SX13, SX37.

Modifiable through MODIFY INITPARMS command: YES.

ABEND.RUNTASK = (DUMP | ABEND.CODES.NODUMP)This parameter specifies whether to refer to ABEND.CODES.NODUMP for ABEND codes when suppressingdumps.

Value Description

DUMP System dumps when a RUNTASK ABENDs. This value is the default.

ABEND.CODES.NODUMP An ABEND dump is generated instead of a system dump. Searchesthe ABEND.CODES.NODUMP list for a match. If the ABEND code isfound, the dump is suppressed. If the ABEND code is not found, thesystem dump continues.

Modifiable through MODIFY INITPARMS command: YES

ALLOC.CODES = (allocation errors)This parameter specifies allocation errors for which IBM Connect:Direct retries the Process step asspecified in the ALLOC.RETRIES and ALLOC.WAIT initialization parameters. These allocation errors are theDynamic Allocation Interface Routine (DAIR) codes generated by the dynamic allocation function (SVC99)of the operating system, such as z/OS. The following is an example of an IBM error reason code (0210)shown in the IBM Connect:Direct SDAB005I message.

SDAB005I - ERR=0210,INFO=0000,REQUESTED DATA SET NOT AVAILABLE. ALLOCATED TO ANOTHERJOB.

You can find common dynamic allocation error codes in the IBM Connect:Direct MSG file by enclosingthe code in the message SDExxxxI skeleton, where xxxx is the error reason code. The variable SDAB005Imessage short text and description come from the MVS Programming Authorized Assembler ServicesGuide (general publication number SA22-7608-nn), which is accessible on IBM's website. For ERR codesnot found in the IBM Connect:Direct MSG file, see the MVS Programming Authorized Assembler ServicesGuide.

IBM Connect:Direct defined the following error codes to enable retries for specific failures.

Value Description

PDSR This is an internally generated IBM Connect:Direct code, that unlike the othersdescribed in this section, is not an allocation code. When two or more Processesattempt to write to the same PDS at the same time, only one can write successfully tothe PDS. The remaining Processes have error messages with this PDSR code and areretried in the same way as the other codes discussed in this section.

458 IBM Connect:Direct for z/OS: Documentation

Value Description

DSNR This option is similar to the PDSR allocation code but works on non-PDS data sets.When you attempt to send or receive a non-PDS data set, but cannot because the dataset is in use, IBM Connect:Direct retries the Process (specified by the retry option) forthe number of times specified, if you have coded the DSNR option.

GDGR This option indicates that if the ENQ fails (as described for the GDGENQ parameter) forGDG data sets, the Process is retried.

TAPR This option indicates that a tape Process is retried if the number of tape Processesspecified by MAX.TAPE is reached.

ARCH This option indicates that the data set is archived, and IBM Connect:Direct retriesbased upon the value specified for the ALLOC.RETRIES initialization parameter. Youmust use the DGAXARCL allocation exit for this option to work.

Note: It is not necessary to use the IBM Connect:Direct DMGALRCL exit to avoid acommon allocation error that ties up the IBM task input/output table (TIOT) via theenqueue on SYSZIOT. See the discussion on the sample allocation exit, DGAXARCL(alias of DMGALRCL), in Sample Allocation Exits, for more detailed information onrecall processing of migrated and archived data sets.

Allocation retries are controlled by the PNODE and supported for z/OS and VM/ESA platforms only. Thefollowing table lists the default allocation error codes and their meanings.

Code Definition

020C Exclusive use of shared file

0210 Allocated to another job

0218 Volume not mounted

0220 Volume not available

0234 One device required

0068 VM minidisk already linked read-only, if transferring with VM

0069 VM minidisk already linked read-write, if transferring with VM

006A VM minidisk already linked read-write and read-only, if transferring with VM

Modifiable through MODIFY INITPARMS command: YES

ALLOC.MSG.LEVEL = INFO | WARN | SEVEREThis parameter specifies the severity of dynamic allocation messages to display. By setting the level, youcan suppress unwanted messages. ALLOC.MSG.LEVEL values correspond to levels defined by DynamicAllocation and are described in the IBM Authorized Assembler Services Guide (GC28-1467).

Value Description

INFO This value indicates that all informational messages are displayed.

WARN This value indicates that only warning messages are displayed.

SEVERE This value indicates that only severe messages are displayed.

Modifiable through MODIFY INITPARMS command: NO

Chapter 4. Administration Guide 459

ALLOC.RETRIES = number of retriesThis parameter specifies the number of IBM Connect:Direct retries of an allocation failure. The default is20.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

ALLOC.WAIT = hh:mm:ssThis parameter specifies the amount of time that IBM Connect:Direct waits between retries of anallocation failure. The default is 00:03:00.

Modifiable through MODIFY INITPARMS command: YES

ALLOCATION.EXIT = modnameThis parameter specifies the name of the user-written interface that communicates with Connect:Directfor z/OS. You can invoke the allocation exit prior to any allocation activity by IBM Connect:Direct, therebyallowing the exit program to examine and modify information that IBM Connect:Direct uses during theallocation Process, such as the data set name (DSN) and destination name. In addition, you can setparameters to terminate a copy step before allocation takes place.

For sample exits, see the $CD.SDGASAMP library. The default is no allocation exit.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX = NO | YESThis parameter indicates whether or not IBM Connect:Direct initializes as a IBM Connect:Direct/Plexoperation.

Value Description

NO IBM Connect:Direct does not initialize as a IBM Connect:Direct/Plex operation.

YES IBM Connect:Direct initializes as a IBM Connect:Direct/Plex operation.

Modified through MODIFY INITPARMS command: NO

CDPLEX.MAXSERVER = maximum number of servers | 4This parameter specifies the maximum number of servers the IBM Connect:Direct/Plex Manager willmanage. The acceptable range is 1–32. The default value is 4.

For more information, see Storage Requirements in a IBM Connect:Direct Plex Environment in theIBMConnect:Direct for z/OS Configuration Guide.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.TIMER = 5 | number of minutesThis parameter specifies the time-out value for XCF communications in minutes. The valid range is 0,5–99. Zero (0) indicates that no time-out is set for XCF communications.

Modified through MODIFY INITPARMS command: NO

CDPLEX.WLM.GOAL = (NO | YES, exitname)This parameter specifies whether the IBM Workload Manager (WLM) Goal Mode queries are used forbalancing IBM Connect:Direct/Plex Process workload in a sysplex.

460 IBM Connect:Direct for z/OS: Documentation

Value Description

NO No Goal Mode queries are made. Process workload is balanced withoutdetermining system capacity information. This is the default value.

YES Goal mode queries are made. A warning message is issued when a WLM query ismade that shows a server is running on a system that is NOT in Goal Mode.

exitname If you want to implement your own method for using WLM query information, youcan create a WLM user exit and specify the name of the exit. You can find a sampleuser exit in $CD.SDGASAMP library called DGAXWLMX .

Modifiable through MODIFY INITPARMS command: yes

CHECK.CERT.EXPIRE = NO | YESThis parameter indicates whether or not IBM Connect:Direct will check the validity of certificates.

This parameter is only effective if Connect:Direct Secure Plus has been enabled by specifyingSECURE.DSN = Connect:Direct Secure Plus parameter filename. For more information, see CertificateValidity Check Used by Connect:Direct Secure Plus.

Value Description

NO IBM Connect:Direct does not check the validity of certificates.

YES IBM Connect:Direct checks the validity of certificates whenever IBM Connect:Direct isstarted. This is the default value.

Modifiable through MODIFY INITPARMS command: YES

CHECK.CERT.EXPIRE.TIME = 00:00:00 | HH:MM:SSThis parameter specifies the time of day that IBM Connect:Direct will check the validity of certificates. Thedefault, 00:00:00, indicates that IBM Connect:Direct will perform its validity check at midnight. You canenter any value between 00:00:00 and 23:59:59. This parameter is only effective if CHECK.CERT.EXPIRE= YES and Connect:Direct Secure Plus has been enabled by specifying SECURE.DSN = Connect:DirectSecure Plus parameter filename.

Modifiable through MODIFY INITPARMS command: YES

CHECK.CERT.EXPIRE.WARN.DAYS = 30 | nnnThis parameter specifies the number of days prior to the certificate expiration date that a warningmessage will be issued. IBM Connect:Direct. The default is 30 days. You can enter any value between 1and 365. his parameter is only effective if CHECK.CERT.EXPIRE = YES and Connect:Direct Secure Plus hasbeen enabled by specifying SECURE.DSN = Connect:Direct Secure Plus parameter filename.

Modifiable through MODIFY INITPARMS command: YES

CKPT = nK | nMThis parameter enables automatic checkpointing of eligible files if no CKPT keyword is specified on theIBM Connect:Direct COPY statement.

See the CKPT.MODE initialization parameter for further details of automatic checkpointing. K meansthousands of bytes; M means millions of bytes.

Valid values of n are:

• 0–2147483K• 0–2147M

Chapter 4. Administration Guide 461

Setting a value of 0 means no automatic checkpointing.

The default is 10M.

IBM Connect:Direct uses the value specified, rounded to the nearest block boundary, to determine when acheckpoint is taken. The CKPT specification on the IBM Connect:Direct Copy statement always overridesthe CKPT initialization parameter value.

Modifiable through MODIFY INITPARMS command: YES

CAUTION: Any error during update cancels all the changes for that particular request.

Note: For sequential files, do not specify a CKPT value less than:

BLKSIZE * NCP * 10 * # stripes

where NCP is the number of buffers for reading data from or writing data to a sequential data set usingBSAM and # stripes refers to striped extended-format data sets. For more information, see ProblemsInvolving Checkpoints .

CKPT.DAYS = number of daysThis parameter specifies the number of days that checkpoint records stay in the Checkpoint file beforeautomatic deletion during IBM Connect:Direct initialization. The records can be left in the Checkpoint fileif transmission is interrupted and the Process is deleted without being restarted. The default is 4.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

CKPT.MODE = (RECORD | BLOCK BLOCK | RECORD PDS | NOPDS NOPDS |PDS VSAM | NOVSAM VSAM | NOVSAM)

This parameter enables you to control checkpointing in both record and block level transfers.

Note: This parameter does not apply to TCP/IP or LU6.2 connections. See Process Queuing and Recoveryfor an explanation of when checkpointing occurs.

Subparameter Description

RECORD | BLOCK Refers to transferring physical sequential (PS) files. It determines whethercheckpointing is allowed when the CKPT parameter is specified on the COPYstatement. If a record level transfer is taking place, BLOCK does not allow recordlevel checkpointing, even if you have coded the request on the COPY statement. Ifyou are performing a block level transfer, BLOCK enables checkpointing requestscoded on the COPY statement. RECORD enables record level checkpointing.

BLOCK | RECORD Refers to transferring PS files. It determines what type of checkpointing occurswhen automatic checkpointing is in effect. You enable automatic checkpointing byspecifying a value in the CKPT parameter in the initialization parameters. If youuse the CKPT parameter, you do not have to request checkpointing on each COPYstatement. If you specify RECORD for this parameter, both record level and blocklevel automatic checkpointing occur, depending on the mode of transfer for eachcopy. Use BLOCK to prevent automatic checkpointing on a record level transfer.

PDS | NOPDS Refers to transferring partition data sets (PDS). Because checkpointing informationis sent with each member of a PDS, this subparameter specifies whethercheckpointing is allowed with PDS transmission if a request is coded on the COPYstatement. NOPDS prevents checkpointing on the PDS, even if you requested it onthe Copy statement. PDS enables PDS transmissions to be checkpointed.

462 IBM Connect:Direct for z/OS: Documentation

Subparameter Description

NOPDS | PDS Refers to transferring PDS. It determines what type of checkpointing occurs whenautomatic checkpointing is in effect. To enable automatic checkpointing, specify avalue in the CKPT parameter in the initialization parameters. If you use the CKPTparameter, you do not have to request checkpointing on each COPY statement.If you specify PDS, all PDS transmissions are automatically checkpointed. NOPDSprevents automatic checkpointing of PDS transmission.

VSAM | NOVSAM Specifies whether checkpointing takes place for VSAM files when the checkpointparameter is specified in the COPY statement.

VSAM | NOVSAM Specifies whether automatic checkpointing takes place for VSAM files.

Modifiable through MODIFY INITPARMS command: YES

COMPRESS.EXT = ALLOW | DISALLOWThis parameter specifies whether extended compression will be allowed on a global basis.

Note: If COMPRESS.NETMAP.OVERRIDE=ALLOW is specified, the COMPRESS.EXT value specified inthe netmap ADJACENT.NODE entry will override the value specified for this parameter in the globalinitialization parameters.

Value Description

ALLOW Extended compression is allowed. This value is the default.

DISALLOW Extended compression is not allowed.

Modifiable through MODIFY INITPARMS command: Yes.

COMPRESS.NEGO.FAIL = STEP | PROCESSThis parameter specifies how a Process is handled when negotiations fail (for the system that has controlof the Process).

Value Description

STEP When negotiations fail, the STEP fails with RC=8, and modal logic may be used todetermine how to proceed. This value is the default.

PROCESS When negotiations fail, the Process fails and is placed in HO HE (Held in Error).

Modifiable through MODIFY INITPARMS command: Yes.

COMPRESS.NETMAP.OVERRIDE = ALLOW | DISALLOWThis parameter specifies whether netmap entries for compression control (on a node-by-node basis) willoverride the global compression control settings in the initialization parameters.

Value Description

ALLOW The netmap compression control settings are allowed to override the initializationparameters. This value is the default.

DISALLOW The netmap compression control settings are not allowed to override theinitialization parameters.

Modifiable through MODIFY INITPARMS command: Yes.

Chapter 4. Administration Guide 463

COMPRESS.STD = ALLOW | DISALLOWThis parameter specifies whether standard compression will be allowed on a global basis.

Note: If COMPRESS.NETMAP.OVERRIDE=ALLOW is specified, the COMPRESS.STD value specified inthe netmap ADJACENT.NODE entry will override the value specified for this parameter in the globalinitialization parameters.

Value Description

ALLOW Standard compression is allowed. This value is the default.

DISALLOW Standard compression is not allowed.

Modifiable through MODIFY INITPARMS command: Yes.

CONFIRM.COLD.START = YES | NOThis parameter indicates whether an operator has to confirm a COLD start of the Transmission ControlQueue (TCQ) and Statistics files.

Value Description

YES Issues a Write to Operator with Reply (WTOR) prompt to force the operator toconfirm the request for a COLD start before executing the COLD start.

NO Performs a COLD start without requiring operator confirmation.

Modifiable through MODIFY INITPARMS command: NO

CRC = (OFF | ON, YES, No)This parameter specifies whether cyclic redundancy checking (CRC) is performed for TCP/IP connections.The CRC parameter is a 32 bit checksum used by IBM Connect:Direct to detect network data corruptionwhich occasionally occurs in IP data networks. If network data corruption is detected, IBM Connect:Directwill stop the Process execution and restart the Process from the last checkpoint record. This provides anextra layer of data integrity when transmitting data over an IP network. You cannot enable CRC checkingwhen running Connect:Direct Secure Plus.

Parameter Description

OFF | ON This parameter specifies whether CRC is ON or OFF for the node. This firstpositional parameter establishes the default for the node.

YES | No This parameter specifies whether overrides are allowed. You can perform overridesin a Process statement or with a network map parameter.

Modifiable through MODIFY INITPARMS command: YES

CTCA = NO | YESThis parameter specifies whether the channel-to-channel adapter (CTCA) driver is loaded at IBMConnect:Direct initialization.

Value Description

NO The CTCA driver is not loaded at initialization. This value is the default.

YES The CTCA driver is loaded at IBM Connect:Direct initialization.

Modifiable through MODIFY INITPARMS command: NO

464 IBM Connect:Direct for z/OS: Documentation

CTCA.TIMER = number of secondsThis parameter specifies the number of seconds for a SEND/RECEIVE to wait before a timeout on theconnection occurs. The valid range is from 60–300. The default is 180 seconds.

Modifiable through MODIFY INITPARMS command: NO

DATEFORM = (MDY | DMY | YMD | YDM)This parameter specifies how dates are displayed and input. Dates are displayed with a 4-digit yearformat unless a 2-digit year format is specified. You can use periods or back slashes (/) to separate themonth, day, and year values.

This parameter applies only to Gregorian dates.

Value Description

MDY This value indicates that dates are displayed or input in one of the followingformats:

• MMDDYYYY• MM/DD/YYYY• MM.DD.YYYY• MMDDYY• MM/DD/YY• MM.DD.YY

DMY This value indicates that dates are displayed or input in one of the followingformats.

• DDMMYYYY• DD/MM/YYYY• DD.MM.YYYY• DDMMYY• DD/MM/YY• DD.MM.YY

YMD This value indicates that dates are displayed or input in one of the followingformats.

• YYYYMMDD• YYYY/MM/DD• YYYY.MM.DD• YYMMDD• YY/MM/DD• YY.MM.DD

Chapter 4. Administration Guide 465

Value Description

YDM This value indicates that dates are displayed or input in one of the followingformats.

• YYYYDDMM• YYYY/DD/MM• YYYY.DD.MM• YYDDMM• YY/DD/MM• YY.DD.MM

Modifiable through MODIFY INITPARMS command: NO

DEBUG = nnnnnnnnTurns on a specific trace option or any combination of options, where nnnnnnnn represents a debugsetting in hexadecimal.

By default, this initialization parameter is set to 00200000 to make each SVC dump unique. You canmodify DEBUG= settings using the MODIFY command. See IBM Connect:Direct MODIFY Command.

See Debug Settings for a complete listing of the DEBUG settings, the trace types produced, and theddnames used for output.

Modifiable through MODIFY INITPARMS command: NO

DEFAULT.PERMISS = (text_permissions | 644, binary_permissions | 755)This parameter specifies the default file permissions for HFS files that are created by Connect:Direct. Ifnot specified, Connect:Direct defaults to 644 for text files and 755 for binary files.

To enable the permission setting for HFS files that use DEFAULT.PERMISS, set the UNIX SystemServices UMASK to 000 by using the runtime environment variable, _EDC_UMASK_DFLT. Otherwise,Connect:Direct uses a default UMASK of 022 that changes the write permissions for GROUP and OTHER.

To set the environment variable, define the _EDC_UMASK_DFLT=000 variable in a RECFM=VB type fileand allocate the ENVIRON DD in the Connect:Direct startup JCL. For example: //ENVIRON DD DISP=SHR,DSN=$CD.ENVIRON(TZ).

Value Description

text_permissions Default file permissions for text files.

binary_permissions Default file permissions for binary files.

Permission values contain 3 digits. The first digit indicates the owner’s file permissions, the second digitindicates the owner’s group’s file permissions, and the third digit indicates the file permissions for allothers. The following are permission values:

• 0 - No file access is allowed• 1 - Execute access is allowed• 2 - Write access is allowed• 3 - Write and Execute access is allowed• 4 - Read access is allowed• 5 - Read and Execute access is allowed• 6 - Read and Write access is allowed• 7 - Read, Write, and Execute Access is allowed

466 IBM Connect:Direct for z/OS: Documentation

Modifiable through MODIFY INITPARMS command: NO

DESC.CRIT = (descriptor code)This parameter specifies the descriptor code used for critical write-to-operator (WTO) messages.Messages that go to the critical route code are, for example, disastrous session errors or critical ABENDs.You can specify as many as 16 codes. The default of DESC.CRIT = (2) specifies immediate action isrequired.

Modifiable through MODIFY INITPARMS command: YES

DESC.NORM = (n,n,...)This parameter specifies the descriptor code used for normal (WTO) messages. You can specify as manyas 16 codes.

DESC.NORM = ( ) specifies that no descriptor code is assigned. The default is no descriptor code.

Modifiable through MODIFY INITPARMS command: YES

DESC.TAPE = (n,n,...)This parameter specifies the descriptor code for the tape pre-mount message used by Connect:Direct forz/OS. (For more information, see the IBM Connect:Direct for z/OS Facilities Guide.) You can specify asmany as 16 codes. The default is 2.

Modifiable through MODIFY INITPARMS command: YES

DSNTYPE = YES | NOThis parameter indicates whether the DSNTYPE, DSNTYPE Version, and MAXGENS is propagated from thesource file (to be used as the default destination file DSNTYPE) or whether it must be coded within theProcess.

DSNTYPE=YES must be specified in the receiving node's initialization parameters for the receiver toperform propagation from the source file.

Value Description

Yes Indicates that the DSNTYPE, and if applicable the DSNTYPE Version andMAXGENS, of the source file (FROM DSN) will be used to create the new outputfile (TO DSN) if it cannot be obtained from any other COPY statement parameter.

The DSNTYPE will be propagated only when the output data is allocated asDISP=NEW or does not exist. A COPY statement parameter that influencesDSNTYPE is required when copying to a different DSNTYPE, for example, PDSEto PDS or PDS to PDSE. DSNTYPE Version can only be propagated when the FROMDSN DSN-TYPE is LIBRARY and is propagated. MAXGENS can only be propagatedwhen the FROM DSN DSNTYPE=(LIBRARY,2) and is propagated. MAXGENS canbe specified in the TO DSN without affecting the DSNTYPE or DSNTYPE Version(specified or propagated), and incorrectly doing so results in an error (e.g.IGD17320I) in DYNAMIC ALLOCATION on the TO side.

No Indicates that the DSNTYPE of the source file (FROM DSN) will not be propagatedto the new output file (TO DSN).

The DSNTYPE must be supplied by a COPY statement parameter, or else it will takethe system default (BASIC for sequential organization; for partitioned organizationthe default is specified in SYS1.PARMLIB(IGDSMSxx).

The DSNTYPE Version default is also specified in SYS1.PARMLIB(IGDSMSxx).

Chapter 4. Administration Guide 467

Modifiable through MODIFY INITPARMS command: NO

This will propagate the class name but not the definition. To propagate SMS attribute like DATACLAS,MGMTCLAS and STORCLAS, code these keyword parameters in the FROM parameter on the sending sidewith value of $$$$$$$$. This can be done in the Process definition, on the IUI COPYCF screen or in theTYPE File record definition.

ECZ.COMPRESSION.LEVEL = 1 | nThis parameter determines the level of compression. The valid value range is 1–9. The default is 1, whichusually provides sufficient compression. The data goes through the compression code the number oftimes indicated by the value specified for the parameter.

CAUTION: Compression consumes significant CPU resources. To avoid degrading performancein your production environment by changing the global, default settings for the extendedcompression parameters, you should: (1) Review “Using Extended Compression” on page 412to view test results that describe how changing the global, default values affects performance,and (2) Review Testing the Effects of Changing Values for Extended Compression Parameters inIBM Connect:Direct for z/OS User Guide for information on using the DGASACMP offline utility toperform tests to determine whether changing the default values of the extended compressionparameters at the global level or by overriding them at the Process level will significantly improveyour system performance.

Modifiable through MODIFY INITPARMS command: YES

ECZ.MEMORY.LEVEL = 4 | nThis parameter identifies how much virtual memory is allocated to maintain the internal compressionstate. This memory is above the 16 megabyte line. The valid value range is 1–9. The default is 4. Level 1requires the least memory (1 KB); level 9 requires the most memory (256 KB).

Compression consumes significant CPU resources. For more information, see the caution for theparameter, “ECZ.COMPRESSION.LEVEL = 1 | n” on page 468.

Modifiable through MODIFY INITPARMS command: YES

ECZ.WINDOWSIZE = 13 | nnThis parameter determines the size of the compression window or history buffer. This memory is abovethe 16 megabyte line. The valid values are 8–15. The default is 13. Size 8 uses 1 KB of memory, whereasSize 15 requires 128 KB of memory.

Compression consumes significant CPU resources. For more information, see the caution for theparameter, “ECZ.COMPRESSION.LEVEL = 1 | n” on page 468.

Modifiable through MODIFY INITPARMS command: YES

ESF.WAIT = hh:mm:ssThis parameter specifies the maximum amount of time that IBM Connect:Direct waits before checking forESF-submitted Processes. When that time expires, IBM Connect:Direct retrieves any Processes submittedthrough the ESF.

The default is 00:03:00.

Modifiable through MODIFY INITPARMS command: YES

468 IBM Connect:Direct for z/OS: Documentation

EXPDT = (TT,DD,TD,DT) (if multiple values EXPDT = TT | DD | TD | DT | ALL |NONE (if only one value)

This parameter specifies IBM Connect:Direct system defaults for propagating the expiration date from theFROM data set to a NEW data set. The following table lists the valid keywords for the EXPDT parameterand coding conventions.

Value Meaning Result

TT tape-to-tape Propagate the expiration date if the data set on the sending side and thedata set on the receiving side are both on tape.

DD DASD-to-DASD Propagate the expiration date if the data set on the sending side is on DASDand the data set on the receiving side is also on DASD.

TD tape-to-DASD Propagate the expiration date if the data set on the sending side is on tapeand the data set on the receiving side is on DASD.

DT DASD-to-tape Propagate the expiration date if the data set on the sending side is on DASDand the data set on the receiving side is on tape.

ALL Always propagate the EXPDT from data sets on all device types to data setson all device types (works only for DASD and tape).

NONE Never propagate the expiration date of the sending data set to the receivingdata set. This value is the default.

If you specify multiple values, enclose them in parentheses and separate them by a comma. If you code asingle value, you do not need to enclose them in parentheses. If you code ALL or NONE, you cannot codeany other keyword.

The receiving side determines whether or not IBM Connect:Direct propagates the expiration date. Ifthe sending side specifies ALL in its initialization parameter, but the receiving side specifies NONE,the EXPDT is not propagated. Therefore, if the copy is from SNODE to PNODE, the PNODE side makesthe determination; if the copy is from PNODE to SNODE, the SNODE side determines if the EXPDT ispropagated.

IBM Connect:Direct overrides the EXPDT initialization parameter in a Process when the followingconditions occur:

• If you code an EXPDT or RETPD parameter for the receiving side (TO side) in the Process, IBMConnect:Direct uses that EXPDT or RETPD and ignore the initialization parameter EXPDT.

• If you code an EXPDT or RETPD for the sending side (FROM side) in a Process and not for thereceiving side, IBM Connect:Direct uses the EXPDT in the Process, according to the EXPDT initializationparameter setting on the receiving side.

• If you do not specify the EXPDT in the Process and the input (FROM) data set is on DASD, IBMConnect:Direct obtains the EXPDT from the DSCB. If the input data set is on tape and the tape is SL orAL (Standard or ASCII), IBM Connect:Direct uses the tape label. When IBM Connect:Direct dynamicallyallocates the data set on the receiving side, EXPDT is used, according to the initialization parameterEXPDT setting on the receiving side.

When you transfer a data set with no associated EXPDT, the following occurs:

If an input data set does not have an EXPDT, and the EXPDT is to be propagated, then the dynamicallocation string for the output data set specifies LABEL = EXPDT = 00000. DASD data sets are consideredto not have an EXPDT if the DSCB EXPDT is 00000. Tape data sets are considered to not have an EXPDT ifthe HDR1 label contains 00000 for the EXPDT. When a data set is allocated with LABEL = EXPDT = 00000,the tape header label or the DASD DSCB contains zeroes for the EXPDT on the output data set. If you havea tape management system or DASD management system, their databases can reflect a different EXPDTthan the tape label or DASD DSCB, depending upon the defaults on the receiving side.

Modifiable through MODIFY INITPARMS command: YES

Chapter 4. Administration Guide 469

EXTENDED.RECOVERY = NO | YESThis parameter specifies whether IBM Connect:Direct Extended Recovery is used.

Value Description

NO IBM Connect:Direct Extended Recovery is not used. This is the default value.

YES IBM Connect:Direct Extended Recovery is used.

Extended recovery is supported in the IBM Connect:Direct/Stand-alone Server and IBM Connect:Direct/Plex environments.

Modifiable through MODIFY INITPARMS command: NO

EXTERNAL.STATS.ALLOWED = NONE|ALL|(rec_type,app_descr)|listThis parameter controls which external statistics records can be written to Connect:Direct Node viacommand WRITE EXSTATS.

Component or Functionality Description

NONE External Statistics Logging is disabled, and statistics recordcannot be written via WRITE EXSTATS command. This will bedefault value.

All External Statistics Logging is enabled and all statistics recordscan be written via WRITE EXSTATS command.

(rec_type,app_descr) External Statistics Logging is enabled.

Only statistics records where WRITE EXSTATS command’sparameter TYPE = rec_type and parameterAPPLICATION.NAME = app_descr, are allowed via WRITEEXSTATS command.

rec_type must be valid value as applicable for TYPEparameter in WRITE EXSTATS command.

app_descr must be valid value as applicable forAPPLICATION.NAME parameter in WRITE EXSTATS. Valuemust be enclosed within quotes. If value must be extended tomultiple lines, then value in each line must be enclosed withinquotes and continuation character ‘-‘ must be specified at theend of each line except last line.

For example,

EXTERNAL.STATS.ALLOWED = (YA,’6.02.00_DMBATCH UI’)

Same can be written in multiple lines as follows,

EXTERNAL.STATS.ALLOWED = (YA,’6.02.00_’ – ‘DMBATCH UI’)

470 IBM Connect:Direct for z/OS: Documentation

Component or Functionality Description

list External Statistics Logging is enabled.

List of (rec_type,app_descr) are allowed via WRITEEXTSTATS

For example,

EXTERNAL.STATS.ALLOWED = ((YA,’6.02.00_DMBATCH UI’), - (YB,’CONTROL_CENTER’))

Modifiable through MODIFY INITPARMS command: NO

FASP = ( NO | SSP , NO | SSP)The first positional parameter is used for when this IBM Connect:Direct Server is the PNODE and thesecond is for when this IBM Connect:Direct Server is the SNODE. The default of NO indicates that theFASP via SSP support is globally set to FASP=NO. IBM Connect:Direct Processes should not attemptto use the FASP transport unless overriden by the NETMAP or Process. SSP indicates that the IBMConnect:Direct Processes should request the FASP transport when in session with SSP unless override bythe NETMAP or Process.

Modifiable through MODIFY INITPARMS command: No

FASP.FILESIZE.THRESHOLD = nnn | nK | nM | nGThe default of 1G defines the threshold to limit the use of the FASP transport to specific file sizes.If the estimated file size is less than this threshold, IBM Connect:Direct will proceed as FASP=NO forthat file transfer. This value is represented as number of bytes and 1K equals 1024. The sending IBMConnect:Direct Server will apply the threshold using the PNODE's setting.

Modifiable through MODIFY INITPARMS command: Yes

FASP.BANDWIDTH = nnn | nK | nM | nGThis is an optional FASP configuration parameter that specifies how much bandwidth each transfer canuse. The default is taken from the license and is negotiated with the remote to the smaller of the values.The value cannot exceed the value defined in the license and SSP will ensure the smaller is used. Thisvalue is represented as number of bits and 1K equals 1000.

Modifiable through MODIFY INITPARMS command: Yes

FASP.POLICY = FAIR | FIXED | HIGH | LOWThis is an optional FASP configuration parameter that specifies the 'fairness' of each transfer. The defaultis FAIR.

Modifiable through MODIFY INITPARMS command: Yes

FIPS = NO | YESThis parameter specifies whether Connect:Direct FTP+ will place System SSL in to FIPS mode. It isa global, non-refreshable initialization parameter that applies to the TLS protocol. If FIPS=YES, thisparameter is effective only if the following have been met:

• System SSL requirements to enable and run in FIPS mode have been met. For more information onmeeting the System SSL requirements for FIPS mode, see the System SSL Programming Guide.

• Connect:Direct Secure Plus has been enabled by specifying the SECURE.DSN initialization parameter.

Chapter 4. Administration Guide 471

Once FIPS mode is requested and successfully set, Connect:Direct FTP+ will not attempt to switch tonon-FIPS mode. To switch to non-FIPS mode, update the FIPS initialization parameter to FIPS=NO andrestart Connect:Direct FTP+. If Connect:Direct FTP+ is in FIPS mode, any attempt to use the SSL protocolwill result in a failure.

Modifiable through MODIFY INITPARMS command: NO

FILE.AGENT.PATH = file agent absolute directory pathThis parameter specifies the location of the File Agent USS directory absolute path. If this parameter isspecified then, File Agent can be configured via Connect:Direct Web Services.

The valid value range is 1 to 1023 characters excluding enclosing quotes. Value must be an existingabsolute USS directory path, enclosed within quotes. For example,

FILE.AGENT.PATH = ‘/u/FileAgent’

If the value has to extended to multiple lines, then the value on each line should be enclosed withinquotes and there must be continuation character ‘-‘ specified at the end of each line except the last line.For example,

FILE.AGENT.PATH = ‘/u/’ – ‘FileAgent’

is same as

FILE.AGENT.PATH = ‘/u/FileAgent’

Note: This parameter is only compatible with the File Agent variant which comes with Connect:Directpackage.

Modifiable through MODIFY INITPARMS command: NO

GDGALLOC = GENERATION | DSNAMEThis parameter specifies whether IBM Connect:Direct allocates GDG data set by generation or data set.

Note:

Do not specify both GDGALLOC=GENERATION and GDGENQ=NO. IBM Connect:Direct will changeGDGENQ=NO to GDGENQ=YES.

472 IBM Connect:Direct for z/OS: Documentation

Value Description

GENERATION IBM Connect:Direct allocates by generation, so the allocation isDATA.SET.NAME(xx), where (xx) is the relative generation such as (+1), (-3),(0), and so on. Use for SMS GDG files so that duplicate GDG generationsare not created. GDGALLOC=GENERATION logic supports sites that use bothSMS and non-SMS GDG data sets. The GDGENQ parameter is ignored andIBM Connect:Direct handles the ENQ logic. IBM Connect:Direct performs anexclusive SYSTEMS ENQ on QNAME NDMGDG and uses the base GDG nameas the RNAME.

This exclusive ENQ causes a serialization within any IBM Connect:Direct onthe system. First, IBM Connect:Direct issues a LOCATE to find the currentabsolute generation number. Next, IBM Connect:Direct performs an exclusiveSYSTEM ENQ on QNAME SYSDSN and uses the data set name returned fromLOCATE as the RNAME. If successful, IBM Connect:Direct then performs ashared SYSTEM ENQ on QNAME SYSDSN and uses the base GDG name as theRNAME. Dynamic allocation (SVC 99) is performed.

If the data set name allocated is not the same as what the LOCATE returned,the process ends with an SDEGDGRI error and the file is deleted. The twoSYSDSN ENQs are not released until the end of the COPY step. The NDMGDGENQ on the base is released (DEQueued) after the allocation is performed.

GENERATION is the default value.

DSNAME IBM Connect:Direct allocates by data set name (i.e.,DATA.SET.NAME.G0000V00). If GDGENQ=YES parameter is coded, IBMConnect:Direct handles the ENQ logic. IBM Connect:Direct performs anexclusive SYSTEMS ENQ on QNAME NDMGDG and uses the base GDG nameas the RNAME.

This exclusive ENQ causes a serialization within any IBM Connect:Direct onthe system. First, IBM Connect:Direct issues a LOCATE to find the currentabsolute generation number. Next, IBM Connect:Direct performs an exclusiveSYSTEM ENQ on QNAME SYSDSN and uses the data set name returned fromLOCATE as the RNAME. If successful, IBM Connect:Direct then performsdynamic allocation (SVC 99) on the data set name that LOCATE returned.

If the ENQ is not successful, the process ends with an SDEGDGRI error andallocation does not occur. The SYSDSN ENQ is not released until the end ofthe COPY step. The NDMGDG ENQ on the base is released (DEQueued) afterthe allocation is performed.

If you code GDGALLOC = GENERATION, then for new non-SMS managed files, you must use one of theIBM-approved methods of supplying DCB attributes. For example, you could use one of these methods:

• Code a model DSCB in the Process DCB=(model DSCB data set name).• Use an existing data set with the attributes desired for the new GDS data set DCB=(cataloged data set

name) in the Process.• Have a model DSCB defined for the generation data group (GDG).• Use the LIKE=(cataloged data set name) parameter in the Process.

If you fail to use an approved method when creating new GDG data sets by generation, you will receive anallocation error of 048C.

Modifiable through MODIFY INITPARMS command: YES

Chapter 4. Administration Guide 473

GDGENQ = YES|NOThis parameter specifies whether or not IBM Connect:Direct uses ENQ on the data set and on the baseGDG before allocation to see if another address space or task has this data set or base GDG allocated.This condition applies to output GDG data sets only.

Note:

Do not specify both GDGALLOC=GENERATION and GDGENQ=NO. IBM Connect:Direct will changeGDGENQ=NO to GDGENQ=YES.

Value Description

YES IBM Connect:Direct performs an ENQ on the entire data set (with the G0000V00appended to the base GDG name) if the Process is copying to an output GDG dataset. The ENQ fails if any job in the system has this data set allocated (including IBMConnect:Direct). Another ENQ is done for the GDG base. This ENQ fails if a differentjob (excluding IBM Connect:Direct) has any generation of this GDG allocated. If eitherENQ fails, the Process is retried according to the ALLOC.CODES, ALLOC.RETRIES, andALLOC.WAIT initialization parameters. If GDGR is not specified in the ALLOC.CODES, thenthe Process is not queued for retry.

The ENQs are not done for data set names coded in the Process as data.set.GnnnnVnn,only for data sets that specify a relative generation, such as (+1) (0) or (-1).

NO The GDGENQ parameter is disabled and no ENQ is done for GDG copies. NO=default.

Modifiable through MODIFY INITPARMS command: YES

IMMEDIATE.SHUTDOWN = I | R | (I, nnn | 60) | (R, nnn | 60)This parameter determines how an immediate shutdown issued through the STOP CD command isexecuted.

Value Description

I The immediate shutdown waits for all Run Task programs to complete before shuttingdown IBM Connect:Direct. This value is the default

nnn | 60

This value specifies the number of seconds that IBM Connect:Direct waits after startingthe SHUTDOWN before it forces the DTF to terminate. If the wait time expires and IBMConnect:Direct forces a shutdown, the following message is displayed to the operator:

SITB999I SHUTDOWN IMMEDIATE timed out.

nnn=0 indicates that IBM Connect:Direct does not have a time limit within which it mustshut down the DTF.

R The immediate shutdown commands functions as a runtaskimm shutdown. It terminatesall executing Run Task Processes and shuts down IBM Connect:Direct.

nnn | 60

This value specifies how many seconds IBM Connect:Direct waits after starting theSHUTDOWN before it forces the DTF to terminate. If the wait time expires and IBMConnect:Direct forces a shutdown, the following message is displayed to the operator:

SITB999I SHUTDOWN IMMEDIATE timed out.

nnn=0 indicates that IBM Connect:Direct does not have a time limit within which it mustshut down the DTF.

474 IBM Connect:Direct for z/OS: Documentation

Modifiable through MODIFY INITPARMS command: NO

INITPARM.BACKUP = memberSpecifies the name of the partitioned data set member that contains the backup of the global initializationparameter file. It is created when IBM Connect:Direct successfully initializes. In case IBM Connect:Directcannot start up successfully after initparm updates have been applied, you can restore the initparmsusing this member and then restart IBM Connect:Direct.

Note: The PDS that is used for the INITPARMS in the PARM= of the JCL is the data set used to hold thebackup. Ensure that the PDS is large enough to hold both the directory entry (with ISPF type stats) andthis backup member.

Modifiable through MODIFY INITPARMS command: NO

INVOKE.ALLOC.EXIT = SEND|RECV|BOTHDetermines whether to invoke the allocation exit upon sending a file, receiving a file, or both sending andreceiving a file.

Value Description

SEND Invokes the allocation exit upon sending a file.

RECV Invokes the allocation exit upon receiving a file.

BOTH Invokes the allocation exit upon both sending and receiving a file. This is thedefault value.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

INVOKE.ALLOC.EXIT.ON.RESTART = YES|NOIndicates whether to invoke the allocation exit on restart of a previously failed Process.

Value Description

NO This value indicates whether to invoke the allocation exit on restart of a previously failedProcess.

YES This value indicates whether to invoke the allocation exit on restart of a previously failedProcess. This is the default value.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

INVOKE.SPOE.ON.SNODEID = NO|YESThis parameter indicates whether to invoke Secure Point-of-Entry when a user codes SNODEID =parameter on the PROCESS.

Value Description

NO IBM Connect:Direct does not invoke Secure Point-of-Entry when a user codesSNODEID = parameter on the PROCESS.

YES IBM Connect:Direct invokes Secure Point-of-Entry when a user codes SNODEID =parameter on the PROCESS.

Modifiable through MODIFY INITPARMS command: NO

Chapter 4. Administration Guide 475

MAX.AGE = (nnn , * | *(nnn) | ALL | ALL(nnn) | status_type | status_type(nnn) , list)

This parameter specifies how many calendar days to wait before purging a Process. You can also use thisparameter to purge only Processes with a specific status or define a different time to wait for each statustype.

Note: IBM Connect:Direct software does not automatically delete Processes when you specify 0.

The following table explains the values.

Value Description

nnn The number of days to wait before purging a Process. The maximum value is 32767. Afterthe specified number of days as passed, the Process is deleted. If nnn=0, no MAX.AGEprocessing is performed.

* (asterisk) Purge all Processes.

ALL Purge all Processes with Hold queue error status types (HE, HO, HP, HS, RA, and RH).

status_type Purge only specified status types (HE, HO, HP, HS, PR, RA, RH, HC, HI, HR, WC, WT, or WX).

list Specify a list by separating entries with a comma.

Following are the queue status values you can select for automatic removal from the TCQ.

Parameter Description

ALL This value indicates a request for all of the queue types for the MAX.AGE parameter. Ifyou specify ALL and another queue type, ALL is ignored.

HE This value indicates to automatically remove held for error (HE) status values. Thisparameter is the default.

HO This value indicates to automatically remove held for operator (HO) status values.

HP This value indicates to automatically remove held due to Process error (HP) statusvalues.

HS This value indicates to automatically remove held for suspension (HS) status values.

RA This value indicates to automatically remove held for restart due to allocation error(RA) status values.

RH This value indicates to automatically remove restart held (RH) status values.

The order of precedence for MAX.AGE subparameters is:

1. Any specified status types take precedence over the ALL subparameter and the wildcard (*)subparameter.

2. The ALL subparameter (purge types HE, HO, HP, HS, RA, and RH) takes precedence over the wildcard(*) subparameter.

3. The wildcard (*) subparameter (purge all valid status types) takes the last precedence.

An example of the MAX.AGE parameter follows.

MAX.AGE=(10,*,ALL(4),HO(20),HI(0))

The following table explains the values in the example.

476 IBM Connect:Direct for z/OS: Documentation

Value Description

10 The default number of days before a Process is removed from the Process queue.

* All Process types are removed. Because no waiting period is specified for *, the default of 10days is used.

ALL(4) Processes with Hold queue error status types (HE, HO, HP, HS, RA, and RH) are removedafter 4 days in the Hold queue. Note that the 4-day waiting period for Processes with thesestatus types overrides the 10-day default waiting period.

HO(20) Processes with an HO status type are purged after 20 days. As a result, they are not purgedwhen ALL or wildcard (*) Processes are purged.

HI(0) Processes with an HI status type are not eligible for purge because zero is specified as thewaiting period. They are never automatically purged from the Hold queue.

In the following example, Processes in the PR queue are aged after one day. Processes in any other queueor status are not aged:

MAX.AGE = (0,PR(1),*(0))

Modifiable through MODIFY INITPARMS command: YES

MAX.AGE.TOD = timeThis parameter specifies when to automatically purge a Process queue. If omitted, the queue is purged atmidnight and at IBM Connect:Direct initialization. You can use any valid IBM Connect:Direct time formatfor the TIME parameter.

In the following example, the Process queue purge runs at 2:30 p.m.

MAX.AGE.TOD=14:30

Modifiable through MODIFY INITPARMS command: YES

MAXPRIMARY = number of PNODE sessionsA PNODE session is started when initiating a Process to one or more SNODEs. This parameter specifiesthe maximum number of PNODE sessions that can be active concurrently. The range is from 2 to 512. Thedefault is 6.

Note: We recommend you code a MAXPROCESS value of 150 or less for performance reasons. Ifyou code MAXPROCESS, the value of this parameter can be up to the MAXPROCESS. There is noadvantage to setting it higher than MAXPROCESS. If you do not code a MAXPROCESS, MAXPRIMARY+ MAXSECONDARY becomes the default for MAXPROCESS. In that case, the combined values ofMAXPRIMARY and MAXSECONDARY should equal 150 or less.

Modifiable through MODIFY INITPARMS command: NO

MAXPROCESS = number of executing PNODE and SNODE ProcessesThis parameter specifies the maximum number of executing PNODE and SNODE Processes allowed at onetime. The value allowed is between 2 and 1024, inclusive. The default is the value of MAXPRIMARY +MAXSECONDARY.

Modifiable through MODIFY INITPARMS command: NO

Note: Although 1024 is the maximum valid value for this parameter, MAXPROCESS should be set to 150or less.

Chapter 4. Administration Guide 477

Note: If you are using IBM Connect:Direct for z/OS based on a license for the Simultaneous Sessionmetric, you should set the MAXPROCESS value to be equal to or less than the number of SimultaneousSession entitlements included with your license. You must obtain entitlements sufficient to cover thehighest number of sessions that are or have been simultaneously in existence across all instances orcopies of the software you have installed. Using the MAXPROCESS parameter allows you to control andlimit the number of Simultaneous Sessions used with each copy of IBM Connect:Direct for z/OS.

MAXRETRIES = number of retriesThis parameter specifies the maximum number of retries that is made to start a node-to-node session. IfIBM Connect:Direct cannot start the session, any Processes destined for the secondary node are placedin the timer queue for retries (TI RE). After all retries are exhausted, they go into the HO WC (hold queue,waiting connection). The range for MAXRETRIES is from 0–512. The default is 7. For related information,see the WTRETRIES initialization parameter.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

MAXSECONDARY = number of SNODE sessionsA SNODE session is started when receiving a Process from a PNODE. This parameter specifies themaximum number of SNODE sessions that can be active concurrently. The range is from 2 to 512. Thedefault is 6.

Note: We recommend you code a MAXPROCESS value of 150 or less for performance reasons. Ifyou code MAXPROCESS, the value of this parameter can be up to the MAXPROCESS. There is noadvantage to setting it higher than MAXPROCESS. If you do not code a MAXPROCESS, MAXPRIMARY+ MAXSECONDARY becomes the default for MAXPROCESS. In that case, the combined values ofMAXPRIMARY and MAXSECONDARY should equal 150 or less.

Modifiable through MODIFY INITPARMS command: NO

MAXSTGIO = maximum storage used for sequential data set transfers forsystem-determined NCP, maximum I/O storage for user-specified NCP)

This parameter specifies the maximum amount of storage used for BSAM sequential data set transfers.MAXSTGIO has two positional parameters that limit the total I/O buffer size in different circumstances.The first is used to limit it when the system determines the number of channel programs (NCP). Thesecond is used to limit it when you specify the NCP in the COPY statement. (The larger the value, thebetter the I/O performance for sequential file transfers. However, the larger the value, the larger theREGION size that may be required for the DTF.) The valid value range for both parameters is 60000–8,388,608 (60K–8M). The default value is 1048576 (1M).

• IBM Connect:Direct uses these parameters to limit the number of buffers/channel programs used forsequential I/O and calculates the NCP by dividing the MAXSTGIO value by the block size of the dataset being transferred. The number of channel programs specified can range from 0 (to have the systemdetermine the value) to 255. For more information on how IBM Connect:Direct processes sequentialdata sets using BSAM, see How to Improve BSAM Data Transfer Rates.

For example, if you specify the default of 1 MB for MAXSTGIO, the following number of channel programs/buffers are allocated for data sets with the block sizes listed in the following table. Also listed is theamount of storage required for buffers for this transfer, which is a product of the block size and NCP.

BLKSIZE Number of ChannelPrograms/Buffers

Storage Used forTransfer

80 255 20,400

4,080 192 783,360

478 IBM Connect:Direct for z/OS: Documentation

BLKSIZE Number of ChannelPrograms/Buffers

Storage Used forTransfer

6,400 128 819,000

27,998 32 895,936

• The data sets in the above table did not take advantage of striping or Large Block Interface (LBI)support, which affect BSAM sequential data set transfer rates. In addition, the method for determiningNCP did not vary—the NCP values listed above were all system-determined. You can also specify theNCP by using the second positional parameter of the MAXSTGIO initialization parameter.

• If you specify a large value for MAXSTGIO, be sure to review the REGION size specified for the DTF. Theregion size must be large enough to accommodate the maximum number of sequential transfers thatcould take place at any one time, multiplied by the value coded for MAXSTGIO, plus the normal amountof region that the DTF requires.

Modifiable through MODIFY INITPARMS command: YES

MAX.TAPE = number of tape Processes | NONEThis parameter specifies the maximum number of tape Processes that are allowed to start in a node.

Value Description

number of tapeProcesses

The numeric range is 0–32767. The default is 10.

When this limit is reached, one of two events can occur to any Processes that try toallocate a tape unit:

• The Processes end with a return code of 8 and a SDETAPRI message• If the ALLOC.CODES initialization parameter includes the code TAPR, the Processes

are placed on the timer retry queue. They are then retried the number oftimes specified in the ALLOC.RETRIES parameter, at the interval specified in theALLOC.WAIT parameter.

NONE This value indicates that the node does not perform tape Processing.

If you specify NONE, any Process that tries to copy from or to a tape on this node ends with a return codeof 8 and a SDETAPRI message. You can still copy from or to tapes on the SNODE.

Modifiable through MODIFY INITPARMS command: NO

MAXUSERS = number of usersThis parameter specifies the maximum number of interactive users and batch users that can sign on toIBM Connect:Direct at any one time. When this limit is reached, no other users are allowed to sign on. Therange for MAXUSERS is from 2–512. The default is 6.

Modifiable through MODIFY INITPARMS command: NO

MCS.CLIST = console operator CLIST library file nameThis parameter specifies the file name of the CLIST library of the z/OS console operator. This parameter isrequired for use of the console operator interface. No default exists.

Note: Multiple Operate CLIST data sets can be concatenated using the SDAGOPLS DD statement in theIBM Connect:Direct JCL. For more information, see the IBM Connect:Direct Facilities Guide.

Modifiable through MODIFY INITPARMS command: NO

Chapter 4. Administration Guide 479

Note: Multiple Operate CLIST data sets can be concatenated using the SDAGOPLS DD statement in theConnect:Direct JCL. For more information, see the IBM Connect:Direct Facilities Guide.

MCS.SIGNON = (SIGNON USERID = (user ID,password))This parameter specifies the console Signon command of the operator for the Operator interface.

Keyword Subparameter Description

USERID user ID The user ID of the console operator.

Password associated with the user ID of the console operator.

optionalparameters

Optional parameters associated with the SIGNON command. Theseparameters are described in Managing Sessions in the IBMConnect:Direct for z/OS User Guide.

You must specify the SIGNON USERID.

This parameter is required for installations that use the console operator interface. You can specify all theparameters allowed on the SIGNON command here. There is no default value.

If a signon without a password occurs in a stage1 exit, the authority is inherited from the TSO user IDused for the signon. If a signon with a password occurs in a stage1 exit, the authority of the user ID in thesignon command is used.

Modifiable through MODIFY INITPARMS command: NO

MULTI.COPY.STAT.RCD=not set | CT | MC | M2This parameter creates statistics records for files copied using the DGADSIOX I/O exit and is particularlyuseful with the wildcard feature, which can produce large numbers of files. When this parameter is set, amessage is sent to the Console each time the DGADSIOX I/O exit copies a file, regardless of what othertypes of statistics records are being generated. For more information on the DGADSIOX I/O exit, seeUtility Programs in IBM Connect:Direct for z/OS User Guide.

By default, this initialization parameter is not set. Use the following table to determine the conditionsunder which to use each setting.

Value Conditions for Use Description

Not set • DGADSIOX I/O exit is not used.• Information for individual files is

needed.

No file completion statistics records are createdand no console messages are produced.

CT • DGADSIOX I/O exit is used.• Pre-existing customer exits detectfiles using CT records.

Produces a Copy Termination type of statisticsrecord.

MC • DGADSIOX I/O exit is used.• Control Center is installed and

monitoring the IBM Connect:Directserver.

Produces a PDS Member Copy type of statisticsrecord, which replaces the member name with thefile name provided by the ADRDSSU utility.

M2 • DGADSIOX I/O exit is used.• None of the other conditions apply.

Produces a “multiple copy” type of statisticsrecord, which shows the file name, current returncode, bytes processed as reported by the IBMADRDSSU utility, and normal Step information.

Modifiable through MODIFY INITPARMS command: YES

480 IBM Connect:Direct for z/OS: Documentation

NETMAP.CHECK = NO | (ALL | TCP, ALL | BOTH | NODENAME, FAIL | WARN |PASS)

This parameter defines the communication types that perform NETMAP checking, the verification toperform, and the action to take if the node does not exist. This parameter is ignored for CTCA connections.

Value Description

NO This value indicates that the IBM Connect:Direct node attempting toestablish a session with this IBM Connect:Direct node need not bedefined in the network map at this node. This feature is convenient whenanother IBM Connect:Direct node initiates contact the majority of thetime.

ALL | TCP ALL enables NETMAP checking for all communication types except forTCP/IP.

TCP enables NETMAP checking for TCP/IP communication.

Note: If you code NETMAP.CHECK = TCP, you must provide a networkmap entry for each TCP/IP node. The adjacent node entry must specifythe logical node name, port number, TCP/IP address, and a session typeof TCP. For example:

ADJACENT.NODE=((UNIX.DALLAS,5555,199.5.5.5,TCP) ENVIRONMENT =UNIX)

ALL | BOTH | NODENAME ALL or BOTH (for SNA) enables verification on both the logical node nameand APPLID/LUNAME.

ALL or BOTH (for TCP) enables verification on both the logical node nameand IP address.

NODENAME enables verification on the logical node name or TCP Aliasnames.

FAIL | WARN | PASS FAIL indicates that access to the system is denied.

WARN indicates that access is allowed, but a warning message is issued.

PASS indicates that access is allowed without any warning message beingissued.

You must define all three parameters to require that the IBM Connect:Direct node establishing a sessionwith this IBM Connect:Direct node be defined in the network map of this node under certain conditions.

To enable NETMAP checking for all communication types, you must code the NETMAP.CHECK parameterfor each. Following is an example.

NETMAP.CHECK=(ALL,ALL,FAIL)

NETMAP.CHECK=(TCP,NODENAME,WARN)

• The first entry for NETMAP.CHECK causes IBM Connect:Direct to check all communication types, exceptfor TCP, for both NODENAME and APPLID/LUNAME.

• The second NETMAP.CHECK entry checks TCP nodes for NODENAME only. If the node does not exist,IBM Connect:Direct issues a warning message but permits access.

Modifiable through MODIFY INITPARMS command: NO

Chapter 4. Administration Guide 481

NETMAP.CHECK.ON.CALL= YES | NOIndicates how IBM Connect:Direct handles a HOLD=CALL Process at submit time.

Value Description

NO This value specifies that the PNODE permits a submit of a Process with HOLD=CALL, evenif the SNODE entry is not in the network map of the PNODE. However, the TCP.IP.DEFAULTentry must be in the network map of the PNODE. This value is the default.

YES This value specifies that the PNODE does not allow a submit of a Process with HOLD=CALL,if the SNODE entry is not in the network map of the PNODE (even if a TCP.IP.DEFAULT entryexists in the network map). If you specify Yes, you must define the SNODE in the PNODEnetwork map.

If you specify Yes, you must define the SNODE in the PNODE network map.

Modifiable through MODIFY INITPARMS command: YES

NODE.QUIESCE.OFF = NODENAMEThis parameter indicates that all processing in the specified node is not suspended until a Quiesce isissued with the MODIFY command. You can specify this node-level parameter for as many nodes asrequired. Node-level initparms are processed in the order specified.

The node name parameter is the 1–16 character local node name specified in the network map of theaffected node. You can also specify a partial node name with the * and ? wildcard characters. If youspecify * anywhere in the node name other than the very end, you must enclose the node name insingle quotes. For example, the following parameter sets Quiesce to OFF on all node names that containDETROIT.

NODE.QUIESCE.OFF = ‘*DETROIT*’

Refer to Suspending and Resuming Quiesce and Trace Settings for how to suspend normal operations bysetting SESSIONS to Q (Quiesce) with the MODIFY command.

Modifiable through MODIFY INITPARMS command: NO

NODE.QUIESCE.ON = NODENAMEThis parameter indicates that all processing in the specified node is suspended and no new processing ispermitted until a Resume is issued with the MODIFY command. You can specify this node-level parameterto suspend processing for as many nodes as required. Node-level initparms are processed in the orderspecified.

The node name parameter is the 1–16 character local node name specified in the network map of theaffected node. You can also specify a partial node name with the * and ? wildcard characters. If youspecify * anywhere in the node name other than the very end, you must enclose the node name insingle quotes. For example, the following parameter suspends processing on all node names that containMIAMI.

NODE.QUIESCE.ON = ‘*MIAMI*’

If the parameter is issued on an SNODE to quiesce processing with a PNODE, the session with the PNODEis established. However, as soon as the PNODE node name is determined, the session is terminated. Noprocessing of data occurs.

Use this parameter if you want to suspend processing on a node because of problems, but want othernodes to continue processing. You can also use it if you know that a node will be down for some time.

482 IBM Connect:Direct for z/OS: Documentation

Refer to Suspending and Resuming Quiesce and Trace Settings for how to resume normal operations bysetting SESSIONS to R (Resume) with the MODIFY command.

Modifiable through MODIFY INITPARMS command: NO

NODE.TRACE.OFF = NODENAMETurns off tracing for a specified node. You can specify this node-level parameter for as many nodes asrequired. Node-level initparms are processed in the order specified.

The node name parameter is the 1–16 character local node name specified in the network map of theaffected node. Use the * and ? wildcard characters to specify the node name. If you specify * anywherein the node name other than the very end, enclose the node name in single quotes. For example, thefollowing parameter disables tracing on all node names that contain DALLAS.

NODE.NODE.OFF = ‘*DALLAS*’

You can modify NODE.TRACE.OFF= settings using the MODIFY command. See IBM Connect:DirectMODIFY Command.

Modifiable through MODIFY INITPARMS command: NO

NODE.TRACE.ON = (NODENAME,nnnnnnnn)Turns on a specific trace option or any combination of options for a specified node, where nnnnnnnnrepresents a debug setting in hexadecimal. You can specify this node-level parameter for as many nodesas required. Node-level initparms are processed in the order specified.

The node name parameter is the 1–16 character local node name specified in the network map of theaffected node. You can use the * and ? wildcard characters to specify the node name. If you specify *anywhere in the node name other than the very end, you must enclose the node name in single quotes.For example, the following parameter enables tracing on all node names that contain DENVER and setsthe debug bits to 80000000.

NODE.TRACE.ON = (‘*DENVER*’,80000000)

You can modify NODE.TRACE.ON= settings using the MODIFY command. See IBM Connect:Direct MODIFYCommand.

See Debug Settings for a complete listing of the DEBUG settings, the trace types produced, and theddnames used for output.

Modifiable through MODIFY INITPARMS command: NO

NON.SWAPABLE = YES | NOThis parameter specifies whether IBM Connect:Direct is marked as non-swappable.

When NON.SWAPABLE = YES, IBM Connect:Direct is not swapped out during periods of no activity. Thedefault value is YES.

Note: When IBM Connect:Direct is running as a IBM Connect:Direct/PLEX or when CTCA has beeninitialized, NON.SWAPABLE is forced to YES. Otherwise, this keyword controls the setting.

Modifiable through MODIFY INITPARMS command: NO

PDSE.SHARING = YES | NOThis parameter indicates if the zOS PDSE sharing feature is supported by IBM Connect:Direct. Thekeyword, PDSESHARING in the IGDSMSxx member in SYS1.PARMLIB , which defines the level of PDSEsharing across subsystems of a sysplex, has two possible values:

Chapter 4. Administration Guide 483

• NORMAL sharing allows users to share a PDSE only at a data set level.• EXTENDED sharing allows users to share a PDSE at both a data set level and member level.

For more information on PDSE sharing, including requirements, and test scenarios and results for boththe normal and extended mode, refer to the , which you can find at IBM Redbook Partitioned Data SetExtended (PDSE) Usage Guide.

CAUTION: Because PDSE sharing allows multiple users to open the same PDSE member foroutput, some operations may destroy directories and create data integrity problems. The last userto issue the STOW macro, which replaces an entry on the directory, gets their update permanentlyapplied to the member. To ensure that updates are not lost, keep this consideration in mind so thatusers can take the appropriate steps.

When you initialize IBM Connect:Direct, the IGWLSHR callable service is used to verify that the operatingsystem can support PDSE sharing. If the operating system cannot support this PDSE sharing level, theSITA641W error message

Level of PDSE.SHARING is not supported

will display and initialization will continue as if the PDSE.SHARING parameter had been specified as NO.

Value Description

YES IBM Connect:Direct will support PDSESHARING as defined by the operating system.

Note: You must specify SHR as the disposition (DISP) keyword so that you can share aparticular data set with other jobs. All other dispositions – OLD, NEW, RPL, and MOD –will continue to serialize the PDSE to ensure that multiple IBM Connect:Direct processescannot share the same PDSE.

NO IBM Connect:Direct will not support PDSE sharing. If multiple processes attempt to openthe same PDSE for output at the same time, the processes terminate with one of thefollowing error messages:

• SDEPDSRI – PDS already open for output by IBM Connect:Direct.• SDE0210I – Requested data set not available. Allocated to another job.

In addition, the processes are placed in the appropriate queue and retried according to anyinitialization parameters specified.

Modifiable through MODIFY INITPARMS command: YES

PDSENQ = YES | NOThis parameter specifies whether or not IBM Connect:Direct serializes access of output PDSes forsimultaneous directory updates from IBM Connect:Direct and ISPF EDIT or the IBM linkage editor.

484 IBM Connect:Direct for z/OS: Documentation

Value Description

YES An ISPF/IEWL ENQUEUE (or RESERVE if the device is shared) is issued to serializeaccess for output PDS data sets opened with DISP = SHR. Use of PDSENQ doesnot prevent simultaneous directory updates from batch jobs or other sources thatdo not issue the same enqueues. If the ENQ or RESERVE fails, DATA SET INUSE allocation error is issued. The Process retries later if 0210 is specified inthe ALLOC.CODES initialization parameter. Because the ISPF editor only enqueuesa member of a PDS when an ISPF SAVE of the member is issued, a user canbe in edit on the member from a PDS to which IBM Connect:Direct is trying tocopy. If you attempt to save a member being edited at the same time that IBMConnect:Direct is copying to that PDS, the TSO/ISPF session hangs until the IBMConnect:Direct COPY operation is complete. When the IBM Connect:Direct COPYoperation completes, the ISPF SAVE command executes, thereby overlaying themember that are recently copied by IBM Connect:Direct.

NO An ISPF/IEWL ENQUEUE is not issued.

Modifiable through MODIFY INITPARMS command: YES

PROCESS.RETENTION = YES | NOThis parameter saves a PNODE Process to the PR queue and retains the completed Process for a period oftime. Retaining a Process allows you to troubleshoot problems with a completed Process or with the useof symbolics.

Because a Process will be stored on the TCQ longer, increase the TCQ space before activatingthis parameter. (For more information on enlarging the TCQ, see Planning the Installation in IBMConnect:Direct for z/OS Configuration Guide.) A Process remains in the PR queue until you delete it usingthe DELETE command or it is removed when space is needed or based on the values defined in theMAX.AGE and MAX.AGE.TOD parameters. Use the TCQ.THRESHOLD parameter to identify when to deleteProcesses in the PR queue, to make space available for newly submitted Processes.

Changing the parameter to NO will not delete Processes from the PR queue. It will prevent moreProcesses from being added to the PR queue.

Value Description

YES After a PNODE Process is complete, it is moved to the PR queue to allow you totroubleshoot a problem with a Process or to view PNODE Processes that have executed.

NO Completed PNODE Processes will not be added to the PR queue. This is the default.

SNODE Processes cannot be moved to the PR queue.

The TCQ.THRESHOLD parameter is the auto-deletion threshold for the PR queue.

Modifiable through MODIFY INITPARMS command: NO

PRTYDEF = Process priorityThis parameter specifies the default priority for Processes submitted to IBM Connect:Direct. If you do notspecify priority on the Process statement, IBM Connect:Direct uses the default priority when placing theProcess on the TCQ. The priorities range from zero to 15, with 15 the highest priority. The default is 10.This parameter is not valid for LU6.2 and TCP/IP flows.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

Chapter 4. Administration Guide 485

QUIESCE = YES | NOThis parameter specifies whether or not IBM Connect:Direct holds Processes from execution.

Value Description

YES No DTF-to-DTF sessions are started, but you can establish interactive sessions.Any Process to be executed is placed in the WAIT queue. Refer to Suspending andResuming Quiesce and Trace Settings for information on how to resume normaloperations by setting SESSIONS to R (Resume) with the MODIFY command.

NO IBM Connect:Direct does not hold Processes from execution.

In a IBM Connect:Direct/Plex environment, this parameter applies to all IBM Connect:Direct/Servers.

Note: When you initialize IBM Connect:Direct for the first time with allocation to a TCQ created byDGADTQFX it is recommended that you specify YES for the QUIESCE parameter. After you delete anyunwanted Processes from the TCQ, DTF activity can be resumed using the Modify command.

Modifiable through MODIFY INITPARMS command: NO

QUIESCE.NODE = node nameIf you are using the QUIESCE.NODE parameter, you are encouraged to use the NODE.QUIESCE.ONparameter as it provides equivalent functionality with enhanced capabilities. The QUIESCE.NODEparameter is still supported.

This parameter indicates that all processing in the specified node is suspended and no new processing ispermitted until a Resume is issued with the MODIFY command.

The node name parameter is the 1–16 character local node name specified in the network map of theaffected node. You can also specify a partial node name followed by an asterisk (*). For example, thefollowing parameter suspends processing on all node names that begin with NODE.CHICAGO.

QUIESCE.NODE = NODE.CHICAGO*

If the parameter is issued on an SNODE to quiesce processing with a PNODE, the session with the PNODEis established. However, as soon as the PNODE node name is determined, the session is terminated. Noprocessing of data occurs.

Use this parameter if you want to suspend processing on a node because of problems, but want othernodes to continue processing. You can also use it if you know that a node will be down for some time.

Refer to Suspending and Resuming Quiesce and Trace Settings for how to resume normal operations bysetting SESSIONS to R (Resume) with the MODIFY command.

Modifiable through MODIFY INITPARMS command: NO

REMOTE.DUMMY.PASSWORD = [ YES | INTERNAL ]For this parameter to take effect, you must use the Stage 2 Security exit to recognize Signon DummyPasswords.

This parameter controls whether Signon and Process Start is authorized for remote nodes if a dummypassword was specified during Signon.

Value Description

YES Any remote can specify a dummy password to obtain Signon and Process Startauthorization on the local node.

INTERNAL Requires the remote node to have the Adjacent Node attribute of INTERNAL (seeTrusted Node Security) for the authorization to occur.

486 IBM Connect:Direct for z/OS: Documentation

Modifiable through MODIFY INITPARMS command: NO

REQUEUE = YES | NOThis parameter specifies whether to requeue Processes which ABEND, such as an x37, or with a returncode greater than 4, or to allow any subsequent steps to run, or go to Process termination.

Value Description

YES Places the Process in the hold queue if it did not end with any of the errors listed abovebut ABENDed with a return code greater than 4 and one of the following is true:

• The Process or SUBMIT command has REQUEUE = YES• Neither the Process nor the SUBMIT command has REQUEUE specified, but REQUEUE

= YES is specified in the initialization parameters• The data set on the PNODE side is a tape data set

YES is the default value.

NO Executes the remaining steps in a Process following a failed COPY STEP, but the failedCOPY STEP is not requeued. If REQUEUE is specified on a PROCESS or SUB statement, itoverrides the initialization REQUEUE specification.

This parameter is only effective if checkpointing is in use. REQUEUE only applies to the PNODE, orsubmitting side that has Process control.

REQUEUE is not effective under any of the following conditions:

• SHUTDOWN IMMEDIATE is requested• Session error caused the Process to terminate

YES places the Process in the hold queue if it did not end with any of the errors listed above but ABENDedwith a return code greater than 4 and one of the following is true:

• The PROCESS or SUBMIT command has REQUEUE = YES• Neither the PROCESS nor the SUBMIT command has REQUEUE specified, but REQUEUE = YES isspecified in the initialization parameters

• The data set on the PNODE side is a tape data set

If a dynamic allocation error occurs, the Process goes to ALLOCATION RETRY. When the specified numberof allocation retries is exhausted and if REQUEUE = YES is specified, the Process is placed in the holdqueue with a status of HO RA (HO = Held by Operator; RA = Held for Restart Due to Allocation Error).

If the Process is ABENDed, the status on the hold queue is HE (hold/error). If the Process received areturn code greater than 4, the status is RH (restart/held).

Modifiable through MODIFY INITPARMS command: YES

RESET.ORIGIN.ON.SUBMIT = YES | NOThis parameter resets the originating node.

Parameter Description

YES The originating node is set to the node where the submit is issued. This action applies toall connection types.

NO The originating node is not set to the node where the submit is issued.

This parameter only affects Processes submitted to the SNODE that use SNODEID or SUBMIT. If youuse this parameter, both the sending and receiving nodes must use this parameter. Also test its impact,

Chapter 4. Administration Guide 487

especially if you or your trading partner use Secure Point-of-Entry (SPOE). If you use SPOE and apply thisparameter, you may need to update AUTHFILE entries for user ID/node combinations used by SPOE.

Modifiable through MODIFY INITPARMS command: YES

REUSE.SESSIONS = YES | NOEnables you to control the use of the sessions initiated by the local node. When you select a Process forexecution between two nodes, control of the session is negotiated. If only one DTF has work destinedfor the other DTF, then the DTF with work to process controls the session. If they both have work toprocess, then the one with the higher priority work controls the session. This negotiation takes place atthe completion of each Process. It is possible for the local DTF to initiate a session and be significantlydelayed in utilizing that session based on the workload of the partner DTF.

Value Description

YES The previously allowed negotiation takes place as described.

NO The remote DTF is not allowed to utilize the sessions established by the localDTF. (IBM Connect:Direct does not allow Processes that are waiting for an eligiblesession to run when an SNODE session becomes available.)

Modifiable through MODIFY INITPARMS command: YES

ROUTCDE.CRIT = (route code)This parameter specifies the route code used for critical WTO messages. You can specify as many as 16codes. Suppress these messages by typing 0 for the route code.

ROUTCDE.CRIT = (2,8) specifies master console information and teleprocessing control.

ROUTCDE.CRIT = (8,11) specifies teleprocessing control and programmer information. This value is thedefault.

Modifiable through MODIFY INITPARMS command: YES

ROUTCDE.NORM = (route code)This parameter specifies the route code used for normal WTO messages. You can specify up to 16 codes.You can suppress these messages by typing 0 for the value.

ROUTCDE.NORM = (2,11) specifies master console information and programmer information.

ROUTCDE.NORM = (11) specifies programmer information. This value is the default.

Modifiable through MODIFY INITPARMS command: YES

ROUTCDE.TAPE = (route code)This parameter specifies the route code used for the tape mount message issued by Connect:Direct forz/OS. You can specify as many as 16 codes. A specification of 0 suppresses the tape mount message.

ROUTCDE.TAPE = (3,5,11) specifies tape pool, tape library, and programmer information.

ROUTCDE.TAPE = (5,11) specifies tape library and programmer information. This value is the default.

Note: If ROUTCDE.TAPE = 0 is coded and TAPE.PREMOUNT = NO, then the z/OS system mount processingat allocation time holds an ENQ on SYSZTIOT until mount is satisfied.

Modifiable through MODIFY INITPARMS command: YES

488 IBM Connect:Direct for z/OS: Documentation

RUN.JOB.EXIT = modnameThis parameter specifies the name of the IBM Connect:Direct module responsible for user read/writecontrol of job streams. The module name can be from 1–8 characters long. The first character must bealphabetic. No default exists for this parameter.

Specify one of the following interface programs to use with Connect:Direct for z/OS:

• RUN.JOB.EXIT = DGAXACRJ (CA-ACF2)• RUN.JOB.EXIT = DGAXRACJ (IBM RACF and CA-TOP SECRET)

Sample programs are provided as part of the Connect:Direct for z/OS sample library. They may not meetthe normal security requirements of an installation. Modify them accordingly.

You must define a user on all nodes involved in Process execution.

Modifiable through MODIFY INITPARMS command: NO

RUNJOBID = USER | CDThis parameter specifies security environment in force for IBM Connect:Direct RUNJOB Processes.

Value Description

USER This value specifies that the Process runs under the ID of the user. This value is the default.

CD This value specifies that the Process runs under the IBM Connect:Direct DTF ID.

Modifiable through MODIFY INITPARMS command: NO

RUN.TASK.EXIT = modnameThis parameter specifies the name of the module responsible for verifying that a user is authorized torun a specified program in the DTF address space. The modname can be from 1–8 characters; the firstcharacter must be alphabetic. No default exists for this parameter.

Specify one of the following interface programs to use with Connect:Direct for z/OS:

• RUN.TASK.EXIT = DGAXACFT (CA-ACF2)• RUN.TASK.EXIT = DGAXRACT (for IBM RACF and CA-TOP SECRET)• RUN.TASK.EXIT = DGAXSAFT (CA-ACF2 with SAF enabled)

Sample programs are part of the Connect:Direct for z/OS sample library. They may not meet the normalsecurity requirements of an installation. Modify them accordingly.

You must define a user on all nodes involved in Process execution.

Modifiable through MODIFY INITPARMS command: NO

RUNTASK.RESTART = YES | NOThis parameter determines whether a RUN TASK program executes at restart if IBM Connect:Direct isunable to determine whether the program has run.

Value Description

YES RUN TASK program executes at restart if IBM Connect:Direct is unable to determinewhether the program has run

NO RUN TASK program does not executes at restart if IBM Connect:Direct is unable todetermine whether the program has run

Chapter 4. Administration Guide 489

This parameter corresponds to the node where the RUN TASK step executes. For example, if the RUNTASK step is running on the SNODE, the coding of the RUNTASK.RESTART parameter on the SNODEdetermines whether the RUN TASK program executes at restart.

Modifiable through MODIFY INITPARMS command: YES

S+CMD.ENFORCE.SECURE.CONNECTION = YES | NOThis parameter specifies whether Connect:Direct Secure Plus commands are accepted from the IBMConnect:Direct client API on nonsecure connections.

Value Description

YES IBM Connect:Direct will enforce a secure connection, that is, it will not acceptConnect:Direct Secure Plus commands from a client API on a nonsecure connection.

NO IBM Connect:Direct accepts Connect:Direct Secure Plus commands from a client API on anonsecure connection.

Modifiable through MODIFY INITPARMS command: NO

SECURE.DSN = filenameThis parameter specifies the Connect:Direct Secure Plus parameters file.

Note: To enable FIPS mode, you must specify a filename for this parameter.

Modifiable through MODIFY INITPARMS command: NO

SECURE.SSL.PATH.PREFIX = prefixThis parameter specifies the prefix location of the key database that contains the certificates for the SSLprotocol. Use this parameter if you are using SSL security with the IBM Connect:Direct Connect:DirectSecure Plus and you are operating in a CD/Plex environment.

Modifiable through MODIFY INITPARMS command: NO

SECURITY.EXIT | SECURITYThis parameter specifies the name of the IBM Connect:Direct exit which performs security checking. Asample security exit, DGAMGSAF, is provided in the $CD.SDGASAMP library. You can modify this exit if itdoes not meet your security requirements.

Value Description

module name A name 1–8 alphanumeric characters long, with the first character alphabetic.

DATASET Specifies that the exit is invoked only for file security; the IBM Connect:DirectAuthorization Facility is used for access (signon) security.

ALL Specifies that the exit is invoked for file and access security.

PSTKT Indicates that the local DTF IBM RACF security is defined to accept IBMRACF PassTicket passwords. For more information, see Generating IBM RACFPassTickets .

OFF Specifies that no security exists; all requests are valid.

If you do not specify the SECURITY.EXIT parameter or it is commented out of the initialization parametersfile, customized security is not performed and the IBM Connect:Direct Authorization Facility (AUTH file) isused.

490 IBM Connect:Direct for z/OS: Documentation

For the first installation of Connect:Direct for z/OS, specify SECURITY.EXIT = OFF until a security exit isinstalled.

A user must be defined on all nodes involved in Process execution.

The default is the IBM Connect:Direct Authorization Facility.

Note: You can also code this parameter as SECURITY=

Modifiable through MODIFY INITPARMS command: NO

SECURITY.NOTIFY = YES | NO | HOLDThis parameter specifies whether IBM Connect:Direct sends a message to users informing them ofsecurity failures on Processes they have submitted.

Value Description

YES Specifies that IBM Connect:Direct sends a message to users informing them of securityfailures on Processes they have submitted. If you set the SECURITY.NOTIFY initializationparameter to YES and you specify NOTIFY = %USER or NOTIFY = user ID on the Processstatement, a security failure sends a TSO notification to the user specified in the NOTIFYparameter of a SUBMIT or PROCESS statement.

NO Specifies that IBM Connect:Direct does not send a message to users informing them ofsecurity failures on Processes they have submitted.

HOLD Specifies that IBM Connect:Direct places Processes in the Hold queue with a status of HEif the other node returns an error during performance of security checking.

The following scenarios could occur with this parameter:

• SECURITY.NOTIFY = NO and a Process has NOTIFY = user ID specified. If a stage 2 security erroroccurs on the SNODE, the user ID is not notified. The user ID is notified of all other errors or normalcompletion. All messages and return codes are in the Statistics File.

• SECURITY.NOTIFY = YES and a Process does not specify NOTIFY. The user is not notified of any errorsor normal completion. All messages and return codes are in the Statistics File.

• SECURITY.NOTIFY = YES and a Process has NOTIFY = user ID specified. If a stage 2 security erroroccurs on the SNODE, the user ID is notified. The user ID is also notified of all other errors or normalcompletion. All messages and return codes are in the Statistics File.

Modifiable through MODIFY INITPARMS command: NO

SERVER.MSU = number|2147483647For IBM Connect:Direct Premium edition 5655-X01, this parameter specifies Million Service Units (MSU)value of license. The MSU value is used to compute a Value Unit (VU) which is a unit of measure by whichthe program can be licensed. This value defined by the product license and is obtained from your license.

The acceptable range is 0–2147483647.

Default: 0

Modifiable through MODIFY INITPARMS command: No.

Note: Server must be recycled to update the value.

Note: If you do not specify a value for this parameter, it defaults to 0.

SERVER.TYPE = [PROD | TEST]This parameter specifies IBM Connect:Direct server type.

Acceptable values are:

Chapter 4. Administration Guide 491

Value Description

PROD This value indicates that the Server and its licence is intended to be a productioncopy of the C:D server.

This value is default.

TEST This value indicates that the Server is intended for testing and migration activities.

License restriction do not apply to this Server.

Modifiable through MODIFY INITPARMS command: No.

Note: Server must be recycled to update the value.

Note: Your product license defines the server environment support, Production or Test, and itsrestrictions.

SESSION.HIGHWATER.SMF = (133 | 128-255, 1-60) | NOThis parameter determines the SMF record type number and the recording interval for High Water Markrecords. For License permitting the acceptable range is (133 | 128-255, 1-60). The default value is (133 ,60) where the second value is in minutes.

Note:

• If the SMF record id of 133 is being used by other applications, you must specify a suitable record idwith this initialization parameter. The value of NO is only valid for license versions X01 and X12. X09and X11 licenses require the SESSION.HIGHWATER.SMF parameter.

• If message SITA386E or SITA386W appears, it means the default or specified record type is beingsuppressed by SMF. Refer to D SMF, O display and look for NOTYPE sub parameter of the SYS parameterto see which records are being suppressed.

SNA = YES | NOThis parameter specifies if IBM Connect:Direct initializes with SNA support. You must also specify a validVTAM APPLID in the local node record of the NETMAP.

Value Description

YES IBM Connect:Direct tries to open the VTAM ACB. If it cannot open the ACB, IBMConnect:Direct prompts the operator for the next action.

NO Only Processes running under TCP/IP or CTCA run or connect to the DTF.

If you change this parameter to SNA = NO after IBM Connect:Direct initializes, you must restart IBMConnect:Direct.

Modifiable through MODIFY INITPARMS command: NO

SNMP = YES | NOInitializes the SNMP trap agent environment.

Value Description

YES Enables the SNMP trap agent environment.

NO Disables the SNMP trap agent environment.

Modifiable through MODIFY INITPARMS command: YES

492 IBM Connect:Direct for z/OS: Documentation

SNMP.DSN = data set name | data set name (member)This parameter identifies the data set used by the SNMP task to initialize the default trap variables anduser defined trap triggers. The data set contains the trap events that you want to disable and any traptriggers you define. All traps are enabled by default. A sample data set is installed in the $CD.SDGASAMPlibrary called DGAXSNMP .

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

SNMP.MANAGER.ADDR = hostname | IP addressThis parameter determines the TCP/IP address or hostname of the host where the SNMP networkmanager is initialized. By default, this address is the same as the IBM Connect:Direct TCP/IP address,or the local hostname. In a IBM Connect:Direct/Plex environment, the default is the TCP/IP address forthe IBM Connect:Direct Manager. You may specify the IP address as an IPV4 or IPV6 address.

This parameter is required if the SNMP network manager resides on a different host or is required to use adifferent TCP/IP address.

Modifiable through MODIFY INITPARMS command: YES

SNMP.MANAGER.PORTNUM = port-numberThis parameter is the TCP/IP port that is defined for UDP traffic to the SNMP network manager. Thedefault is port number 162. If the defined UDP port number is something other than 162, this parameteris required.

Modifiable through MODIFY INITPARMS command: YES

SNODE.ARCH.RECALL.WAIT = NO | YESThere is no default value for this parameter however the default behavior is as follows.

A Process that allocates a migrated dataset will either:

• WAIT for the dataset to be recalled• Terminate with an SDEARCHI RC=08

The action taken depends if ARCH is coded in ALLOC.CODES initialization parameter. If ARCH is notincluded in the ALLOC.CODES then the Process will WAIT for the RECALL to complete. If ARCH is includedthen the Process will terminate with the SDEARCHI RC=08. The behavior is the same regardless if thisIBM Connect:Direct is the PNODE or SNODE.

With SNODE.ARCH.RECALL.WAIT the RECALL behavior will be controlled based on the setting of thisparameter when this Connect:Direct is the SNODE.

SNODE.ARCH.RECALL.WAIT=YES (Process waits for the RECALL to be completed)SNODE.ARCH.RECALL.WAIT=NO (Process terminates with SDEARCHI RC=08)

Modifiable through MODIFY INITPARMS command: YES

STAT.ARCH.CONFIRM = YES | NOThis parameter indicates whether or not IBM Connect:Direct is to have confirmation that the contents of astatistics file pair are archived before erasing them and reusing the file pair to record new information.

Chapter 4. Administration Guide 493

Value Description

YES Specifies that IBM Connect:Direct requires confirmation before reusing the file.The Connect:Direct for z/OS utilities DGADARRT and DGADARBT provide archiveconfirmation. You can invoke these utilities from an archive Process or an archivebatch job, respectively.

If archive confirmation has not occurred at the time a file is to be switched toand therefore erased, IBM Connect:Direct issues a WTOR requesting operatorpermission to overwrite the file. DTF activity halts until you type a response to theWTOR. An affirmative response causes an immediate file pair switch. A negativeresponse disables the statistics logging function, but the DTF remains active.

NO Specifies that IBM Connect:Direct erases the file contents at the time of a pairswitch regardless of whether indication that the file was archived is received.

Note: If you code the STAT.ARCH.CONFIRM parameter as YES, then also specifythe STAT.SWITCH.SUBMIT parameter.

Modifiable through MODIFY INITPARMS command: NO

STAT.BUFFER.ESDSDATA | STAT.BUFFER.KSDSINDX |STAT.BUFFER.KSDSDATA

This parameter specifies the number of buffers VSAM allocates for the statistics clusters. IBMConnect:Direct uses the values when generating VSAM access method control blocks (ACBs) for thestatistics files. Generating these blocks provides a means of tuning VSAM performance for statistics fileaccess in the DTF. IBM Connect:Direct specifies separate buffers for the index and data components forthe key sequenced clusters. Each buffer is the size of the control interval of the specified component.

Note: These buffers are allocated above the 16 megabyte line.

The syntax for this parameter is as follows:

STAT.BUFFER.ESDSDATA = number of ESDS data buffersSTAT.BUFFER.KSDSINDX = number of KSDS index buffersSTAT.BUFFER.KSDSDATA = number of KSDS data buffers

The defaults are:

• STAT.BUFFER.ESDSDATA = 6• STAT.BUFFER.KSDSINDX = 6• STAT.BUFFER.KSDSDATA = 6

Modifiable through MODIFY INITPARMS command: NO

STAT.ERROR = ABEND | DISABLEThis parameter specifies the action of the DTF for certain types of errors which can occur in the StatisticsFacility, such as VSAM errors or repeated ABENDs.

Value Description

ABEND Specifies that the DTF ABENDs with U3400. This value is the default.

DISABLE Specifies that the Statistics Facility is disabled but the DTF remains active. The DTFoperates normally. However, no statistics records are written.

494 IBM Connect:Direct for z/OS: Documentation

When an ABEND occurs within the Statistics Facility, an SVC dump is written to a SYS1.DUMPxx data setand recovery is attempted. After five recovery attempts, the DTF ABENDs with U3400 or the StatisticsFacility is disabled, depending on the value specified for the STAT.ERROR parameter.

Modifiable through MODIFY INITPARMS command: NO

STAT.EXCLUDE = (record type list)This parameter specifies what record types to exclude from the statistics log. The system does not passexcluded records to the statistics exit. The 2-character identifiers specify the record types in the list.Refer to “Statistics Records” on page 325 for a complete list of record type identifiers.

You can also selectively exclude using the Statistics exit. See “Recording Statistics for Specific RecordTypes” on page 388 for more information. You can also turn recording of specific record types on and offduring DTF execution using the STATISTICS ON/OFF API command.

The following example excludes PDS member records from the statistics log.

STAT.EXCLUDE = (MC)

Statistics records are often useful or indispensable in debugging problems. Excluding records from thestatistics log makes problem determination difficult. Do not exclude the following record types:

Record Type Description

CT Copy Termination

PS Process Submit

PT Process Termination

RJ Run Job

RT Run Task

SW Submit within Process

WO Write to Operator (WTO)

No default exists for this parameter.

Modifiable through MODIFY INITPARMS command: YES

STAT.INIT = WARM | COLDThis parameter specifies whether to erase the contents of the statistics files for the DTF at initialization.

Value Description

WARM Specifies that the system does not erase the contents at DTF initialization. In this case,statistics from prior DTF executions are available in the new execution. This value is thedefault.

COLD Specifies that the system erases all preexisting records. Only records generated during thecurrent execution are available.

Modifiable through MODIFY INITPARMS command: NO

Chapter 4. Administration Guide 495

STAT.QUEUE.ELEMENTS = statistics record queue sizeThis parameter specifies the size of the queue that holds statistic records to be written.

The range of the STAT.QUEUE.ELEMENTS initialization parameter is 1-9999 elements, with a default valueof 1500. A queue that is too small can degrade system performance, whereas a queue that is too largecan cause wasteful storage allocation above the 16 megabyte line. In a Connect:Direct Plex environment,the queue element number is calculated by taking the CDPLEX.MAXSERVER value, adding 1 (for themanager) and then multiplying it by the STAT.QUEUE.ELEMENTS value. If this is less than 5000, then5000 is used. If greater than 10000, then 10000 is used.

When a IBM Connect:Direct task writes a statistic record, it queues the record to be written to thestatistics facility asynchronously. The statistics facility then processes the queue and writes the statisticsrecord. This parameter controls the size of this queue. When the queue becomes full, tasks that write astatistics record are held until a slot in the queue becomes available.

You should choose the size of the queue based on how busy IBM Connect:Direct is expected to be duringpeak-use periods. A lightly loaded system (up to 5 Processes executing concurrently) can run with a smallqueue, so a queue size of 100 elements may be adequate. However, busier systems require a largerqueue (200-1500 elements) to avoid performance degradation caused by queue contention.

There are two size considerations for the statistics queue, the total size and the threshold size. Thetotal size is initially specified by the value of the STAT.QUEUE.ELEMENTS initialization parameter, and canbe adjusted if necessary. Each stat queue element takes up 2 KB of space and is allocated above the16 megabyte line. The threshold size is a value smaller than the total size, and represents a portion ofthe queue that is reserved for peak-use periods. This helps to improve queue availability under a highworkload. The threshold size is calculated automatically, and is usually one-fourth the total size. If thethreshold size is inadequate, the total queue size should be increased.

Note: To ensure that an adequate amount of virtual storage above the line is allocated for the queueholding the statistics records in a IBM Connect:Direct/Plex environment, specify REGION=0M on the jobcard that starts IBM Connect:Direct. For more information about storage requirements, see Planning theInstallation in IBM Connect:Direct for z/OS Configuration Guide.

Modifiable through MODIFY INITPARMS command: NO

STAT.SNODEID = (NO | YES,NO | YES)This parameter specifies whether the submitter’s ID should be placed in the statistics record. The firstsubparameter applies to version 1 flows (SNA-LU0) and the second subparameter applies to version 2flows (SNA-LU6.2/TCP).

Note: STAT.SNODEID affects the user ID (original submitter ID or SNODEID) which is used to execute aSUBMIT within a Process, instead of affecting just the submitter’s ID in the statistics record.

A value of YES causes the SNODEID, if present, to be placed in the statistics record.

A value of NO causes the submitter's ID to be placed in the statistics record.

Modifiable through MODIFY INITPARMS command: NO

STAT.SWITCH.SUBMIT = dsn [member]This parameter enables a site to name a sequential data set or a member of a PDS that contains a Processto be submitted at statistics file pair switch time. Use this feature to submit a Process that archives thestatistics file pair that has just filled. Alternatively, the Process can submit a batch job which in turnarchives the statistics records.

Note: The STAT.SWITCH.SUBMIT parameter is identical in format to the DSN parameter of the IBMConnect:Direct SUBMIT statement. See the Connect:Direct Process Language help for information on theSUBMIT statement.

If you code the STAT.ARCH.CONFIRM parameter as YES, then also specify the STAT.SWITCH.SUBMITparameter.

496 IBM Connect:Direct for z/OS: Documentation

IBM Connect:Direct internally generates a SUBMIT command to submit the Process, and specifies a singlesymbolic parameter, &EDSN. The symbolic parameter &EDSN specifies the data set name of the entrysequenced cluster just filled. Therefore, the DTF supplies to the archive Process the name of the ESDScluster to archive.

You can make archived statistics records available to the SELECT STATISTICS command by copying themto a VSAM entry sequenced cluster, and then use the DGADBKEY utility to recreate the associated indexinformation in a VSAM key sequenced cluster.

No default exists for this parameter.

Modifiable through MODIFY INITPARMS command: NO

STAT.SWITCH.TIME = (hh:mm:ss , ...)This parameter specifies times of day to perform a statistics file switch. The STAT.SWITCH.TIME is in24-hour clock format. You can specify up to four times in this parameter. The system initiates a switchwhenever one of the named times occurs, regardless of whether the currently active files are full. If youdo not specify the STAT.SWITCH.TIME parameter, switching occurs whenever a file pair becomes full or inresponse to the API command STATISTICS SWITCH.

Modifiable through MODIFY INITPARMS command: NO

STAT.TPREC = (start_time, end_time, snaps_per_hour)This parameter instructs IBM Connect:Direct to create a statistics record that contains the number ofProcesses and the amount of data sent and received for a node. You can use the statistics record for loadbalancing and tracking trends.

Value Description

start_time This value indicates the start time for the statistics records creation. The validformat is hh:mm:ss.

Valid values are 00:00:00 through 23:59:59.

end_time This value indicates the time when the statistics record generation ends. The validformat is hh:mm:ss.

Valid values are 00:00:00 through 23:59:59.

snaps_per_hour Valid values are 1–60. If you specify a value of 1, IBM Connect:Direct takes onesnapshot per hour. If you specify a value of 60, IBM Connect:Direct takes onesnapshot per minute, or 60 per hour. No default exists for this parameter.

Modifiable through MODIFY INITPARMS command: NO

STAT.USER = (user ID, [password])This parameter specifies the security ID under which the statistics log is written and any archive Processor batch job runs. Use this parameter when implementing a stage 2 security exit.

A system task (a separate TCB) does the writing of the statistics files to minimize the impact of statisticslogging on the throughput of the DTF. File pair switching and archive Process submission is also done bythis task. Such processing is done in the background within the DTF, and therefore, has less impact onother activity. Connect:Direct for z/OS creates this task using the security user ID from the STAT.USERparameter. The system also propagates the user ID to the archive Process and to any batch jobs thearchive Process submits.

If your site is running with full stage 1/stage 2 security implemented, it is not necessary to supply thepassword with this parameter.

Chapter 4. Administration Guide 497

Value Description

user ID Specifies the security ID that IBM Connect:Direct passes to a security exit. It contains 1–8characters.

Note: Certain IBM Connect:Direct statistics records are written with the STAT.USER IDin their user ID field. For example, the S2 records that contain information about thestatistics logging Process are written with this ID. Because user ID is one of the indexedstatistics record fields, specifying a unique ID facilitates the rapid retrieval of theserecords through the SELECT STATISTICS command when the TYPE and USER selectioncriteria are specified.

password Specifies the current security password. The security exit uses this parameter to validatethe current security password.

If you do not specify this parameter, or if you do not implement the stage 2 security exit, the statisticslogging task runs with the security ID of the DTF job, and with the user ID of NDM. In this case, the TP andS2 records are written with NDM in their user ID fields.

Modifiable through MODIFY INITPARMS command: NO

STATISTICS.EXIT = modname | (modname[,MANAGER | SERVER | BOTH])This parameter specifies the name of the IBM Connect:Direct statistics exit module you can invoketo complement the IBM Connect:Direct statistics gathering functions. Use this program to log IBMConnect:Direct information, perform IBM system management facilities (SMF) functions, and log custominformation. To use this feature, you must explicitly code this initialization parameter and supply a modulename—the default is no security exit.

For more information on the IBM Connect:Direct sample statistics exits, which are located in the$CD.SDGASAMP library, see Sample Statistics Exits.

In a IBM Connect:Direct /Plex environment, you can specify whether the Manager, the server(s) or bothlaunch the statistics exit. By specifying the MANAGER keyword, only the Manager region launches thestatistics exit. By specifying SERVER, all servers launch the statistics exit. Specifying BOTH causes allregions—servers and the Manager—to launch the statistics exit and for the same records to be processedtwice.

In a IBM Connect:Direct /Plex environment, MANAGER is the default entity to launch the exit, but youmust still specify the module name.

Modifiable through MODIFY INITPARMS command: NO

STRNO.MSG = number | 10This parameter specifies the number of strings allowed to message file processing.

The acceptable range is 5–100. The default value is 10.

Modifiable through MODIFY INITPARMS command: NO

SUBMIT.EXIT = modnameThis parameter specifies the name of the module responsible for controlling changes to IBMConnect:Direct parameters, such as Process name, priority, class, and secondary node. The module namecan be from 1–8 alphanumeric characters long, with the first character alphabetic. No default exists forthis parameter.

For more information on the IBM Connect:Direct sample exits, which are located in the $CD.SDGASAMPlibrary, see Sample Submit Exits.

Modifiable through MODIFY INITPARMS command: NO

498 IBM Connect:Direct for z/OS: Documentation

SYSOUT = classThis parameter specifies the JES output class for spool output generated during DTF execution. The classmust be one character in length. No default exists for this parameter.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

TAPE.PREMOUNT = YES | NO | LISTThis parameter specifies whether the Connect:Direct for z/OS tape premount message is displayed.

Value Description

YES Tape premount message is displayed.

NO Tape premount message is not displayed.

LIST LIST instructs IBM Connect:Direct to list up to 10 tape volume serial number onthe SVST000I tape premount message.

Note: If ROUTCDE.TAPE = 0 is coded and TAPE.PREMOUNT = NO, then the z/OS system mount processingat allocation time holds an ENQ on SYSZTIOT until mount is satisfied.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

TAPEIO = BSAM | EXCPThis parameter identifies what the TAPEIO setting was prior to Version 5.0.

The default value is BSAM.

This parameter does one thing prior to Version 5.0 and something different afterwards.

Prior to Version 5.0, this parameter controlled what access method was used by the COPY function toread and write to tape, either BSAM or EXCP. When BSAM was specified, BSAM was used to read and writethe tape, NOTE TYPE=REL was used to generate tape checkpoint records, and POINT TYPE=REL was usedto set the tape restart point. When EXCP was specified, EXCP was used to read and write the tape, achannel command equivalent to NOTE TYPE=ABS was used to generate tape checkpoint records, and achannel command equivalent to POINT TYPE=ABS was used to set the restart point.

After Version 5.0, BSAM is always used to read and write to tape, NOTE TYPE=ABS is always used togenerate new tape checkpoint records, and POINT TYPE=ABS is always used to set the tape restartpoint from new checkpoint records. The TAPEIO parameter is re-purposed and tells IBM Connect:Directwhat the TAPEIO setting was prior to Version 5.0 so that it can switch to using POINT TYPE=RELwhen restarting using pre-Version 5.0 checkpoint records. This information is critical to the successfulfunctioning of checkpoint restart if a tape is created by a IBM Connect:Direct prior to Version 5.0 andthe restart attempted on or after Version 5.0. This includes checkpoint records stored in the local node'scheckpoint dataset, as well as checkpoint records stored in a remote node's checkpoint dataset.

Thus, the TAPEIO parameter setting becomes irrelevant and can be removed once there is no possibilityof restarting a tape COPY function using IBM Connect:Direct prior to Version 5.0.

Modifiable through MODIFY INITPARMS command: NO

TAPEMOUNT.EXIT = modnameThis parameter specifies the name of interface to StorageTek Tape Silo software, which provides statusinformation on the volumes to satisfy a tapemount request. You can invoke the exit prior to a tape VOLSERmount request to automatically cancel the request should any volume not be available for the Silo toprocess. For more information, see Tapemount Exit.

Chapter 4. Administration Guide 499

The module name can be from 1–8 alphanumeric characters long, with the first character alphabetic. Nodefault exists for this parameter.

The IBM Connect:Direct sample exit is named DGAXTAPX and located in the $CD.SDGASAMP library.

Modifiable through MODIFY INITPARMS command: NO

TCP = OES | NOThis parameter specifies whether the TCP/IP connection modules are loaded during initialization and ifso, the type of modules.

Value Description

OES Specifies the TCP/IP OpenEdition Sockets Interface support.

Note: You must install and run the IBM BPX facility, the series of IBM programs thatcomprise the OES functionality, before you can transfer files using the TCP = OES supportof the IBM Connect:Direct. In addition, IBM RACF sites must install the OMVS securitysegment before using the OES interface to transfer files.

NO Causes no modules for the TCP/IP connection to load during initialization.

Modifiable through MODIFY INITPARMS command: NO

TCP.API.LISTEN = ((addr , port) , (addrn , portn))Use this parameter to define up to eight different address and port combinations for each server forincoming connection requests.

The TCP.API.LISTEN parameter allows for a list of IP address and port number combinations to supportmultiple addresses, including IPv6.

For each server in a IBM Connect:Direct Plex environment, override the global initialization parameter byspecifying the TCP.API.LISTEN parameter in that server's local initialization parameters. The first addressdefined in the parameter becomes the local or default address.

There is no default for TCP.API.LISTEN if the parameter is not specified. If the parameter is specified withan address only, the port can default. The default port for TCP.API.LISTEN is 1363.

The syntax for the TCP.API LISTEN parameter is similar to the following example:

TCP.API.LISTEN = ( (addr1 , port1) , (addrn , portn) )

In the example, addr1 through addrn is specified as either the word ANYADDR or ANYADDR6, a TCPhostname or a specific IP address. Also, port1 through portn is specified as a single port number. Thefollowing example demonstrates this specification:

TCP.API.LISTEN =(MVSA , 1363) /* establish single API listen

Value Description

ANYADDR6 When you specify ANYADDR6, 0::0 or (::), both IPv4 and IPv6 connection requestsare accepted through this listen. To define a single listen task to accept IPv4 andIPv6 requests, specify the TCP.API.LISTEN parameter as follows.

TCP.API.LISTEN=(ANYADDR6,1363)

Modifiable through MODIFY INITPARMS command: NO

500 IBM Connect:Direct for z/OS: Documentation

TCP.API.DISCONNECT.ERROR.MESSAGE = Yes | NoThis parameter controls whether STCO999E error messages are generate to RPLERRCK DD when an APItask disconnects unexpectedly.

Value Description

YES To generate the error message.

NO To suppress the message generation.

Default is YES.

Modifiable through MODIFY INITPARMS command: YES

TCP.API.TIMER = 00:00:00 | hh:mm:ssThis parameter specifies the maximum time of session inactivity a TCP/IP connected IUI or API sessionwaits before timing out and exiting. The default value of 00:00:00 indicates that no timer is used. Theeffective range is 00:20:00–02:00:00 (20 minutes–2 hours).

If you are using Control Center to monitor your Connect:Direct for z/OS server, set this value to at leasttwice the value of the Monitor Rest Time setting in Control Center.

Note: It is recommended that you set the value for the TCP.API.TIMER parameter to at least oneminute greater than the wait timeout value set for IBM system management facilities (SMF) to avoidproblems when restoring migrated data sets. For information on the TIMEOUT parameter, see Signing Onto Connect:Direct for z/OS in IBM Connect:Direct for z/OS User Guide.

Modifiable through MODIFY INITPARMS command: YES

TCP.CONNECT.TIMEOUT= 30 | number of secondsThis parameter defines the length of time in seconds that a non-DTF interface (IBM Control Center,Connect:Direct Browser User Interface, TELNET, port scanners etc) will be allowed to linger when anattempt is made to connect to the TCP.LISTEN port rather than the TCP.API.LISTEN port. Value can befrom 5 seconds to 300 seconds.

The default value is 30.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

TCP.FMH.TIMER=hh:mm:ssThis parameter defines the length of time in hours, minutes, and seconds that the TCP session can beinactive waiting on a IBM Connect:Direct FMH to be received from the remote node before the TCPsession is terminated.

The default value is 00:10:00. For a IBM Connect:Direct Run Task step, the timer value does not apply.

The IBM Connect:Direct Process is placed in the Timer Retry queue and retried after the amount of timespecified by the WTRETRIES initialization parameter has elapsed. However, if the session times out asecond time, the Process is placed in Held in Error status and remains in the Hold queue to give you anopportunity to analyze the problem to prevent this Process from retaining TCP resources. This Held inError status requires a manual intervention to have the Process execute again.

Care should be taken in specifying these timer values in that IBM Connect:Direct Processes could performdifferently than expected due to the session being prematurely terminated.

Use this parameter only when necessary, and when you do, set it to an extremely high value. It is difficultto estimate how much time it takes, for example, for a file to be allocated by means of a manual tapemount. Through trial and error, you should be able to select an appropriate value for this parameter.

Chapter 4. Administration Guide 501

Modifiable through MODIFY INITPARMS command: NO

TCP.FMH.TIMER.RETRIES=nThe TCP.FMH.TIMER.RETRIES parameter defines the number of times a process can be retried once in TIQueue, due to the TCP.FMH.TIMER initialization parameter. After all the RETRIES exhausted, the Processis placed in Held in Error status and remains in the Hold queue.

The range of this parameter is 1-100. If this parameter is not specified in INITPARM, the default value isset to 1.

If an INVALID value (less than 1 OR greater than 100) is specified, the parameter is set to DEFAULT valueand a warning is issued in Connect:Direct Server Logs as specified below:

SITA767I TCP.FMH.TIMER.RETRIES outside 1-100 range

Modifiable through MODIFY INITPARMS command: NO

TCP.LISTEN = ((addr , port) , (addrn , portn))Use this parameter to define up to 64 different address and port combinations for each server forincoming connection requests.

The TCP.LISTEN parameter allows for a list of IP address and port number combinations to supportmultiple addresses, including IPv6.

For each server in a IBM Connect:Direct Plex environment, override the global initialization parameterby specifying the TCP.LISTEN parameter in that server's local initialization parameters. The first addressdefined in the parameter becomes the local or default address.

There is no default for TCP.LISTEN if the parameter is not specified. If the parameter is specified with anaddress only, the port can default. The default port for TCP.LISTEN is 1364.

The syntax for the TCP.LISTEN parameter is similar to the following example:

TCP.LISTEN = ( (addr1 , port1) , (addrn , portn) )

In the example, addr1 through addrn is specified as either the word ANYADDR or ANYADDR6, a TCPhostname or a specific IP address. Also, port1 through portn is specified as a single port number. Thefollowing example demonstrates this specification:

TCP.LISTEN = ((MVSA , 1364), - /* using DNS for address & Default (10.20.129.3 , 4100), - /* specific address, specific port (10.20.129.3 , 4101))

Value Description

ANYADDR6 When you specify ANYADDR6, 0::0 or (::), both IPv4 and IPv6 connection requestsare accepted through this listen. To define a single listen task to accept IPv4 andIPv6 requests, specify the TCP.LISTEN parameter as follows.

TCP.LISTEN=(ANYADDR6,1364)

Modifiable through MODIFY INITPARMS command: NO

TCP.RUNTASK.TIMER = hh:mm:ssThe TCP.RUNTASK.TIMER initialization parameter defines the length of time in hours, minutes, andseconds that the PNODE will wait for the RUN TASK on the SNODE to complete before the TCP session is

502 IBM Connect:Direct for z/OS: Documentation

terminated. The default value of 00:00:00 indicates that no timer is used. This timer value only applies toa Run Task function when the RUNTASK is being performed on the SNODE.

Modifiable through MODIFY INITPARMS command: NO

TCP.SOURCEIP = (IPv4 address or DNS | IPv6 address or DNS)TCP.SOURCEIP defines the default source IPv4 address and IPv6 address for any outbound IBMConnect:Direct connection.

The first positional parameter assigns a global IPv4 address that Connect:Direct can bind to for outboundProcesses. The IPv4 default will be obtained from the Hostname assigned to the TCP/IP task.

The second positional parameter assigns a global IPv6 address that Connect:Direct can bind to foroutbound IPv6 Processes. The is no default value and the first IPv6 address defined with the TCP/LISTENinitialization parameter will be used as a default.

If TCP.SOURCEIP is not specified or if ANYADDR (0.0.0.0) is specified, the default HOST IP will be used.The IPV4 address can be specified as 1STLISTEN which will cause the first IP in the TCP.LISTEN list tobe used. This behavior mimics previous releases. If the first IP in TCP.LISTEN is ANYADDR or 0.0.0 and1STLISTEN is specified, Connect:Direct for z/OS will bind to 0.0.0.0 which will return and use the first IPin the TCP stack.

Modifiable through MODIFY INITPARMS command: NO

TCP.SRC.PORTSThis parameter specifies a destination IP address (or multiple addresses) and the source portsassociated with the destination addresses. The values in this parameter are loaded into a table thatIBM Connect:Direct uses to find a match when establishing a session. It is available only for z/OS nodesusing TCP=OES.

The syntax for this parameter is as follows:

TCP.SRC.PORTS = (ip.address,port-ranges),(ip.address2,port1,port2), - (ip.address3,port-ranges)TCP.SRC.PORTS = (ip.address/submask,port-ranges), …TCP.SRC.PORTS = (ip.address/0XFFFFFFFFFFFFFFFF,ports,ranges)

Use a wildcard character [* or 0 (zero)] to define a destination IP address pattern. The wildcards must bein the least significant positions.

You can add an optional subnet mask for the destination IP address, followed by the source port numberand/or range of port numbers for the destination IP address.

For IPv4, valid subnet mask values are:

• Dotted quad notation, such as 255.255.0.0• Hexadecimal notation, such as 0xffffff00

For IPv4 address specification, the ip.address can be fully qualified such as 199.1.1.1, or a genericaddress such as 199.1.*

You cannot use a subnet mask if you use wildcards in the destination IP address pattern.

Specify the range of source ports from lowest port number to highest port number order. For example,1025–2000 is valid, whereas 2000–1025 is invalid. The source port numbers must be between 1025–65535, inclusive.

Note: The number of source ports defined must be sufficient to handle the number of concurrent IBMConnect:Direct sessions. If not, performance can be severely affected.

Following is an example.

Chapter 4. Administration Guide 503

TCP.SRC.PORTS = (199.2.4.*, 5000-5050), - (199.2.4.7, 1376), - (200.200.4.4/255.255.2.4, 2000-2100, 3000-3100), - (138.16.*.*, 2000-2050, 3000-3050, 4001, 4005)

For IPv6 specification, the ip.address is specified in IPv6 format with colons. It can be fully qualifiedsuch as 1:2:3:4:5:6:7:8 or a generic address 1:2:3:4:*. Generic specification of the IPv6 ip.addresscannot use the shortcut specification. For example, 1111:0:0:0:0:6666:7777:8888 can be specified as1111::6666:7777:8888 as a fully qualified name. However, 1111::6666:* is not allowed because there isno way to know how many zeros have been eliminated.

For IPv6, valid subnet mask values are:

• Hexadecimal notation, such as 0XFFFFFFFFFFFFFFFFFFFFFFFF00000000

Note: If the specification of an IPv6 address, mask and ports takes more than one line, split at the slashdividing the ip.address from the submask.

The following example demonstrates how to specify an IPv6 address, mask and ports over more than oneline:

TCP.SOURCE.PORTS=(1111:2222:3333:4444:5555:6666:7777:8888/ - 0XFFFFFFFFFFFFFFFFFFFFFFFF00000000,02000-03000,03500), - (199.1.1.2/255.255.0.0,04000-05000,05500)

Modifiable through MODIFY INITPARMS command: NO

TCP.SRC.PORTS.LIST.ITERATIONS = number of scansThis parameter specifies the number of times that IBM Connect:Direct scans the available ports list toattempt a connection before going into a retry state. Use any value between 0 and 255.

Modifiable through MODIFY INITPARMS command: NO

TCP.TIMER = wait timeThis parameter specifies the number of seconds that a Process waits on a TCP data read before theProcess is cancelled and put in timer retry status.

The number can range from 0–32767. The default value is 300.

Use a value of 60 or greater to keep Processes from waiting indefinitely because of a lost connection.

This parameter can have the following impacts on Processes:

1. Setting the parameter to 0 causes a Process to become stranded and requires you to manuallyrequeue and restart the Process.

2. Setting this parameter to a high value (such as 1800 [a half-hour] or 3600 [an hour]) to allow longrunning tasks to complete prevents any shutdowns during that time. Also, long running tasks tie upcommunications links and associated resources for the time period. System resources are used moreefficiently by breaking a task into smaller units, with a RUN JOB submitting the long running Process.

Modifiable through MODIFY INITPARMS command: NO

TCQ = WARM | COLDThis parameter specifies how the TCQ is initialized.

Value Description

WARM IBM Connect:Direct uses the TCQ as it exists.

504 IBM Connect:Direct for z/OS: Documentation

Value Description

COLD IBM Connect:Direct reinitializes the TCQ and any Processes left on the TCQ arelost.

Modifiable through MODIFY INITPARMS command: NO

TCQ.THRESHOLD = NO | YES | nnThis parameter specifies how IBM Connect:Direct issues warning messages as the TCQ reaches a definedcapacity. Use the TCQ.THRESHOLD parameter to identify when to delete Processes in the PR queue, tomake space available for newly submitted Processes.

Value Description

No Indicates that a warning message is not produced when control intervals (CIs) reach acertain level on the TCQ file. A message is issued when the TCQ is completely full. Thisvalue is the default.

Yes Indicates that a warning message is issued when the TCQ becomes 90% full. Themessage is reissued when the percentage changes but remains above 90% full.

nn Allows you to specify a 2-digit percentage of the number of VSAM file control intervalsused on the TCQ file. When the TCQ reaches this percentage, IBM Connect:Direct issues amessage. The message is reissued when the percentage changes and remains above thepercentage specified here. The range for percentage value is 0 through 99.

Note: A value of 0 is the equivalent of the default NO value, that is, no SPQL002I warningmessage is produced; only when the TCQ is completely full is a message issued.

Processes on the PR queue are automatically deleted on a space-needed basis at non-ESF SUBMIT time,thus not affecting the TCQ.THRESHOLD.

Modifiable through MODIFY INITPARMS command: YES

THIRD.DISP.DELETE = YES | NOThe PNODE setting for the THIRD.DISP.DELETE= parameter controls how IBM Connect:Direct processesthe value of the third subparameter of the (TO)DISP= parameter during a COPY operation when an ABENDoccurs in the COPY step on the receiving node.

Value Description

YES Enables the third disposition delete feature.

NO Disables this feature.

The following table describes the conditions under which THIRD.DISP.DELETE=YES is enforced and theresult it produces.

This processing occurs When all of these conditions are present

The data set on the receiving node isdeleted.

ABEND occurs in the COPY step on the receiving node(SNODE).

THIRD.DISP.DELETE=YES.

Third subparameter of the TO(DISP) parameter is notdefined, or is defined as DELETE.

Third subparameter of the TO(DISP) parameter is notdefined as KEEP or CATLG.

Chapter 4. Administration Guide 505

This processing occurs When all of these conditions are present

The destination output file does not exist, that is, theCOPY statement creates a file, which means that if RPLis specified, there is no file to replace.

The DISP parameter of the TO side of the COPY statementis set to one of the following options:

• DISP=(NEW,CATLG)• DISP=(NEW,CATLG,DELETE)• DISP=(NEW,KEEP)• DISP=(NEW,KEEP,DELETE)• DISP=(RPL,CATLG)• DISP=(RPL,CATLG,DELETE)• DISP=(RPL,KEEP)• DISP=(RPL,KEEP,DELETE)

The Process is ineligible for REQUEUE because one of thefollowing is true:

• Checkpointing is turned OFF.• REQUEUE=NO is specified in the Process statement or

as an initialization parameter.

When THIRD.DISP.DELETE=NO is set, the following processing occurs:

• IBM Connect:Direct does not apply the third subparameter value, even if it is set to DELETE in theProcess itself.

• IBM Connect:Direct uses the value set for the second subparameter of the TO(DISP) parameter as thevalue for the third subparameter. For example, if the second subparameter is set to CATLG, the thirdsubparameter is treated as if CATLG were specified.

CAUTION: When you create GDG data sets using relative numbering, for example,DATA.SET.NAME(+1), you must specify CATLG as the third subparameter of the TO(DISP)parameter. If you fail to do so, a RETRY failure occurs. For example, you can specifyDISP=(NEW,CATLG,CATLG) or DISP=(,CATLG,CATLG).

Modifiable through MODIFY INITPARMS command: YES

THIRD.DISP.DELETE.X37Parameter THIRD.DISP.DELETE.X37 must be coded on the receiving NODE in conjunction with thedataset's DISP= values and the PNODE's THIRD.DISP.DELETE value. The PNODE must code, or default to,THIRD.DISP.DELETE=YES in its initialization parameters.

The format is:

THIRD.DISP.DELETE.X37=NO (the default) or YES.

It applies to output tapes only. The output tape's disposition must be coded asDISP=(NEW,CATLG,DELETE). Without using this new parameter, if an abend occurs while writing a tapethen, the dataset will only be deleted if no check pointing is being done. It will allow the data set to bedeleted and not cataloged if an x37, out of space, abend occurs even if check pointing is being performed.

Modifiable through MODIFY INITPARMS command: YES

506 IBM Connect:Direct for z/OS: Documentation

TRACE.BUFFER = nnn | 2This parameter specifies how much space in 64-bit storage is allocated for tracing. By default, twomegabytes are allocated for the in-storage wrap trace buffer. To turn off in-storage tracing, specifyTRACE.BUFFER=0.

Modifiable through MODIFY INITPARMS command: NO

TRANS.SUBPAS = YES|NOThis parameter specifies whether the submitter password is sent to the receiving node if the receivingnode submits within a Process back to the submitting node.

Value Description

YES The submitter password is sent to the receiving node

NO The submitter password is not sent to the receiving node

Modifiable through MODIFY INITPARMS command: YES

UPPER.CASE = YES|NOThis parameter specifies whether initialization messages sent to the console are displayed in uppercaseletters.

Value Description

YES Initialization messages sent to the console are displayed in uppercase letters

NO Initialization messages sent to the console are displayed in uppercase andlowercase letters

Note: You must define this parameter on the execution parameter overrides to ensure that all initializationmessages are displayed in uppercase letters.

Modifiable through MODIFY INITPARMS command: NO

V2.BUFSIZE = (maximum transmission buffer size, TCP/IP send/receivebuffer size)

The first positional parameter specifies the default maximum buffer size that IBM Connect:Direct uses forLU6.2 and TCP/IP data transmission. Valid values range from 3712–2M.

Note: When running with Secure Plus, the minimum V2.BUFSIZE should be 8K to accommodatecertificate information exchanged as part of COPY termination.

The second positional parameter is used to alter the TCP/IP send and receive buffer sizes within TCP/IP.The maximum value is 2M. The minimum value is set by TCPCONFIG in the TCP/IP PROFILE data set.If a value is specified that is lower than the TCPCONFIG value, the TCPCONFIG value is used. Thedefault of the second parameter is double the first parameter, unless this is lower than the value set byTCPCONFIG in the TCP/IP stacks PROFILE data set. For example, TCPCONFIG TCPSENDBFRSIZE 64KTCPRCVBFRSIZE 64K in the TCP/IP PROFILE would set the default to 64 KB. This default value of 64Kwould be used unless the first parameter is greater than 32 KB, or the second parameter is greater than64 KB.

The default is V2.BUFSIZE=(32K,128K)

In general terms, the second positional parameter should be at least the same and not less than the firstparameter and should be big enough to handle the largest V2.BUFSIZE override from the netmap. A goodcommon practice is to have the second parameter be a multiple of the first parameter and at least twiceor more than the first parameter.

Chapter 4. Administration Guide 507

Also, note that the first positional parameter can be overridden in the ADJACENT.NODE entry in thenetmap using the BUFFER.SIZE parameter. For details, see BUFFER.SIZE=V2.buffer override.

Modifiable through MODIFY INITPARMS command: NO

WTMESSAGE = NO | YES | (YES,nnn)This parameter specifies whether a WTO message is generated when a Process is placed on the timerretry queue.

Value Description

YES Specifies that message SVTM110I is written to the console each time a Process isplaced on the timer queue.

NO Specifies that message SVTM110I is not written to the console each time aProcess is placed on the timer queue.

(YES,nnn) Specifies the number of times the SVTM110I messages are written to the console.Valid value for nnn is 1–512. The default is 1, which specifies that the message iswritten every time. If you specify 2, every second message is displayed, and so on.

IBM Connect:Direct uses this parameter with the MAXRETRIES initialization parameter when attemptingto establish a lost session.

Modifiable through MODIFY INITPARMS command: YES

Note: Any error during update cancels all the changes for that particular request.

WTRETRIES = hh:mm:ss | 00:03:00This parameter specifies the amount of time between attempts to reestablish a node-to-node session.The default is 00:03:00. IBM Connect:Direct uses this parameter with the MAXRETRIES initializationparameter when trying to establish a lost session.

Modifiable through MODIFY INITPARMS command: YES

XCF.NAME = XCF group nameThis parameter specifies a unique name for a IBM Connect:Direct/Plex environment, or for a IBMConnect:Direct/Stand-alone Server (including the standby system) using extended recovery. Thisparameter is not needed in a IBM Connect:Direct/Stand-alone Server that does not use extendedrecovery.

XCF group names cannot begin with the letters “A” through “J” or with the letters “SYS” because theseare reserved by IBM. You cannot modify this parameter through the MODIFY INITPARMS command.

Modifiable through MODIFY INITPARMS command: NO

ZEDC = ON|OFF|PREFERREDThis parameter allows you to enable or disable the support for the zEDC feature.

Value Description

ZEDC = ON Enables the support within IBM Connect:Direct for the zEDC accelerator for allrecord formats.

Note: If ZEDC=ON and ZIIP is enabled then ZIIP is preferred.

ZEDC = OFF Disables the support within IBM Connect:Direct for the zEDC accelerator. Defaultvalue.

508 IBM Connect:Direct for z/OS: Documentation

Value Description

ZEDC =PREFERRED

Enables the support with Connect:Direct for the zEDC accelerator for all recordtype with setting zEDC as a preferred compression method.

ZFBA = YES|NOThis parameter allows you to enable or disable the support for the zFBA feature. For more information,see Using zFBA for File Transfer.

Value Description

YES Enables the zFBA feature within the Connect:Direct Server. Modifiable throughMODIFY INITPARMS command : YES

NO Disables the zFBA feature within the Connect:Direct Server. This is the defaultvalue.

ZIIP = NONE | EXTCOMP | SSLTLS | ALL | PROJECTThis parameter enables you to specify the setting for the zIIP Exploitation Feature. For more information,see “zIIP Exploitation Feature” on page 413.

Subparameter Description

NONE The default. No CPU time is offloaded to a zIIP and IBM Connect:Direct continuesto operate as it has for all versions.

EXTCOMP Schedules SRBs to offload COPY step extended (ZLIB) compression anddecompression CPU time to a zIIP.

SSLTLS Schedule SRBs to offload COPY step SSL and TLS data encryption and decryption(not the handshake) CPU time to a zIIP.

ALL Schedules SRBs to offload COPY step SSL and TLS data encryption and decryption(not the handshake) and extended (ZLIB) compression and decompression CPUtime to a zIIP.

PROJECT Same as ALL, except the SRBs are always dispatched to a general purpose (CP)processor, not a zIIP processor. This allows you to project C:D zIIP usage (ratherthan use the zIIP) when you have a zIIP processor online. If no zIIP processor isonline, there is no difference between PROJECT and ALL.

Note: The PROJECT setting requires that you set the IEAOPTxxparameter, PROJECTCPU to YES. For more information, see IEAOPTxx(OPT parameters) in MVS Initialization and Tuning Reference(SA22-7592-21 or http://publib.boulder.ibm.com/infocenter/zos/v1r12/index.jsp?topic=/com.ibm.zos.r12.ieae200/ieaopt.htm)

Modifiable through MODIFY INITPARMS command: NO

IBM Connect:Direct System File Initialization ParametersThe following section identifies the initialization parameters for IBM Connect:Direct system files.You must specify each initialization parameter. These initialization parameters are considered globalparameters in a IBM Connect:Direct/Plex environment.

AUTHDSN = dsnThis parameter specifies the file name of the IBM Connect:Direct VSAM Authorization file. No defaultexists for this parameter.

Chapter 4. Administration Guide 509

Modifiable through MODIFY INITPARMS command: NO

CKPTDSN = dsnThis parameter specifies the file name of the IBM Connect:Direct VSAM Checkpoint/restart file. No defaultexists for this parameter.

Modifiable through MODIFY INITPARMS command: NO

MSGDSN = dsnThis parameter specifies the file name of the IBM Connect:Direct VSAM Message file. No default exists forthis parameter.

Modifiable through MODIFY INITPARMS command: NO

NETDSN = dsnThis parameter specifies the file name of the IBM Connect:Direct VSAM network map file. No defaultexists for this parameter.

Modifiable through MODIFY INITPARMS command: NO

STAT.ARCH.DIR = archive directory file nameThis parameter specifies the data set name of the directory of statistics archive files. Use the directory tomaintain information about the files containing archived statistics records. This information includes thedate/time range covered by the records in each file, and is useful in locating the archive file containingrecords for a specific date/time. When you omit this parameter, the archive directory functions areunavailable. No default exists for this parameter.

Modifiable through MODIFY INITPARMS command: NO

STAT.DSN.BASE | STAT.FILE.PAIRSThe STAT.DSN.BASE parameter specifies the high-level qualifiers for the statistics files cluster names. Useany valid z/OS data set name qualifiers for this parameter. The high-level qualifier can range from 1–37characters. The syntax for this parameter is as follows:

STAT.DSN.BASE = dsname base

The STAT.FILE.PAIRS parameter indicates the number of file pairs to use. You must specify at least twofile pairs. The number of file pairs ranges from 2–20. The syntax for this parameter is as follows:

STAT.FILE.PAIRS = number

The two parameters specify the statistics file pair list. During DTF initialization, IBM Connect:Direct usesthese two values to develop the data set names for the statistics files. The low-level qualifier, ESDSnn, isadded to the base data set name to form the names of the ESDS clusters. In ESDSnn, nn is the numberthat identifies the position of the file pair in the list. IBM Connect:Direct uses KSDSnn as the qualifier toform the names of the KSDS clusters.

The following example uses both STAT.DSN.BASE and STAT.FILE.PAIRS to specify the statistics file pairlist.

STAT.DSN.BASE = CD.STATS /* STATISTICS DSNAME BASE */STAT.FILE.PAIRS = 3 /* NUMBER OF PAIRS */

The example in the previous figure generates the following file pair list.

510 IBM Connect:Direct for z/OS: Documentation

CD.STATS.ESDS01 /* FIRST FILE PAIR ... ESDS */CD.STATS.KSDS01 /* FIRST FILE PAIR ... KSDS */CD.STATS.ESDS02 /* SECOND FILE PAIR ... ESDS */CD.STATS.KSDS02 /* SECOND FILE PAIR ... KSDS */CD.STATS.ESDS03 /* THIRD FILE PAIR ... ESDS */CD.STATS.KSDS03 /* THIRD FILE PAIR ... KSDS */

Modifiable through MODIFY INITPARMS command: NO

TYPEDSN = dsnThis parameter specifies the file name of the IBM Connect:Direct VSAM Type file. No default exists for thisparameter.

Modifiable through MODIFY INITPARMS command: NO

Local Initialization ParametersLocal initialization parameters are only used in a IBM Connect:Direct/Plex environment. They only applyto a specific member of the IBM Connect:Direct/Plex. Each IBM Connect:Direct/Plex member must haveits own local initialization parameter member with the CDPLEX.MANAGER=YES|NO parameter as the firststatement in the member.

You can override any initialization parameter that is allowed in the local initialization parameters memberby using the PARM= keyword in the EXEC statement. Local parameters override any global parametersetting; however, the global setting is used if a local parameter is not specified. Some parameters do notapply to all members of the CDPLEX. For example, MAXPROCESS, MAXSECONDARY, and MAXPRIMARYset no process limit for the CDPLEX manager. Likewise, MAXUSER has no purpose for a CDPLEX server, asit does not support API sessions.

Local and Global Initialization ParametersThe following local initialization parameters are also global initialization parameters. See the descriptionfor the corresponding Global Initialization Parameter for a description of these parameters:

• “CTCA = NO | YES” on page 464• “CTCA.TIMER = number of seconds” on page 465• “DEBUG = nnnnnnnn” on page 466• “MAXPRIMARY = number of PNODE sessions” on page 477• “MAXSECONDARY = number of SNODE sessions” on page 478• “MAX.TAPE = number of tape Processes | NONE” on page 479• “QUIESCE = YES | NO” on page 486• “SECURITY.EXIT | SECURITY” on page 490• “SNA = YES | NO” on page 492• “STAT.INIT = WARM | COLD” on page 495• “STATISTICS.EXIT = modname | (modname[,MANAGER | SERVER | BOTH])” on page 498• “TCP = OES | NO” on page 500• “TCP.API.LISTEN = ((addr , port) , (addrn , portn))” on page 500• “TCP.LISTEN = ((addr , port) , (addrn , portn))” on page 502• “TCP.TIMER = wait time” on page 504• “TCQ = WARM | COLD” on page 504• “TRACE.BUFFER = nnn | 2” on page 507• “UPPER.CASE = YES|NO” on page 507

Chapter 4. Administration Guide 511

• “V2.BUFSIZE = (maximum transmission buffer size, TCP/IP send/receive buffer size)” on page 507• “ZFBA = YES|NO” on page 509• “ZIIP = NONE | EXTCOMP | SSLTLS | ALL | PROJECT” on page 509

CDPLEX.INITPARM.BACKUP = memberThis parameter specifies the name of the data set member to be used as a backup of the localinitialization parameter member if IBM Connect:Direct cannot start up successfully after initparm updateshave been applied. To ensure that this backup member contains valid initialization parameters, thismember is written to after initialization is completed successfully.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.MANAGER = NO | YESThis parameter indicates whether this IBM Connect:Direct/Plex member is a IBM Connect:Direct/Manageror a IBM Connect:Direct/Server and must be the first statement in all local initialization parametermembers. Only one IBM Connect:Direct/Manager is allowed in a IBM Connect:Direct/Plex.

Value Description

YES Indicates that this IBM Connect:Direct/Plex member is a IBM Connect:Direct/Manager or a IBM Connect:Direct/Server.

NO Indicates that this IBM Connect:Direct/Plex member is not a IBM Connect:Direct/Manager or a IBM Connect:Direct/Server. This is the default.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.MSGID = NONE | xxThis parameter specifies two characters that identify the IBM Connect:Direct/Plex member. Thesecharacters display after the message number in messages sent to a console operator. They enable theoperators to identify the message source.

Following is an example of the message display if the CDPLEX.MSGID value is set to S1. The two characteridentifier is highlighted in this example.

SVTM055I S1 SESSION (001) ESTABLISHED WITH SNODE=SC.DUB.TPYLA2 SVTM055I S1 SESSION (001) ESTABLISHED WITH PNODE=SC.DUB.TPYLA2 SVTM036I S1 PROCESS STARTED MVSMVST3( 1) PNODE=SC.DUB.TPYLA2 SVTM036I S1 PROCESS STARTED MVSMVST3( 1) SNODE=SC.DUB.TPYLA2

If your site uses automated operations monitoring and you use this parameter to identify IBMConnect:Direct/Plex members, you may need to revise your monitoring program because of the change inmessage format. In this case, you may want to leave this parameter at NONE.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.PLEXCLASSES = (*,plexclass,…,plexclass)This parameter specifies which PLEXCLASSes are supported by the IBM Connect:Direct/Server. You canrestrict a IBM Connect:Direct/Server to run only jobs in the specified PLEXCLASSes. An asterisk (*)indicates that the IBM Connect:Direct/Server supports any Process that does not specify a PLEXCLASS orspecifies a PLEXCLASS of ‘*’.

If you specify CDPLEX.PLEXCLASSES, you must explicitly specify ‘*’ as its value to run any Processes witha Plexclass of ‘*’ on that IBM Connect:Direct/Server.

The PLEXCLASS name is 1–8 characters long and up to 8 classes may be specified.

512 IBM Connect:Direct for z/OS: Documentation

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.REDIRECTThis parameter is used by the IBM Connect:Direct Plex Manager in the IBM Connect:Direct Plexenvironment to determine the redirection address that is presented to the remote node. It allows youto specify redirection addresses based on the security node type (internal or external) and session type(TCP) of the adjacent node in the network map for the IBM Connect:Direct Plex Servers within the localinitialization parameters.

The syntax for this parameter is as follows:

CDPLEX.REDIRECT = ((INT_IPv4,EXT_IPv4),(INT_IPv6,EXT_IPv6)

The CDPLEX.REDIRECT parameter is a local initialization parameter for servers only, and defaults to thefirst IPv4 or IPv6 address indicated for the server.

The following shows an example of the syntax for the CDPLEX.REDIRECT parameter followed by anexample with actual TCP/IP addresses and port numbers.

CDPLEX.REDIRECT=((INT TCP IPV4 , PORT),(EXT TCP IPV4 , PORT ) - (INT TCP IPV6 , PORT),(EXT TCP IPV6 , PORT ) -

CDPLEX.REDIRECT=((10.20.201.2,4199),(199.1.22.333,4199) - (FD00::22CE:0:0:0:82,4299),(FD00::22CE:1:2:3:99,4299)

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.REDIRECT.EXCEPTION = ((Mgr-IP, Ext_Svr-IP, Ext_Svr-port,Exception-IP, Exception-port),...)

This parameter specifies exception redirection IP addresses and ports in addition to those specified inthe CDPLEX.REDIRECT parameter and will be used based on how the remote server contacts the IBMConnect:Direct/Plex Manager. If the remote IBM Connect:Direct server contacts the IBM Connect:Direct/Plex Manager on the Mgr-IP listen address and the IBM Connect:Direct/Plex Workload manager selectsa IBM Connect:Direct/Plex server whose CDPLEX.REDIRECT IP and Port matches the Ext_Svr-IP andExt_Svr-port, the Exception-IP and Exception-port will be used instead of the IBM Connect:Direct/PlexServer's CDPLEX.REDIRECT IP address and port.

This parameter is only valid for the IBM Connect:Direct/Plex Manager.

You can use TCP/IP IPv4 and TCP/IP IPv6 addresses in the CDPLEX.REDIRECT.EXCEPTION parameter butall of the IP addresses in any given CDPLEX.REDIRECT.EXCEPTION string must be of the same type (IPv4or IPv6). In addition, the IBM Connect:Direct/Plex Manager must listen on specific IP addresses and notlisten on ANYADDR (0.0.0.0) or ANYADDR6, for example:

TCP.LISTEN=((10.20.201.3,3802),(10.20.129.165,3802), - (FD00:0:0:22CE::3802,3802))

Value Description

Mgr-IP IBM Connect:Direct/Plex Manager's Listen IP address

Chapter 4. Administration Guide 513

Value Description

Ext_Svr-IP, Ext_Svr-port IBM Connect:Direct/Plex Server's CDPLEX.REDIRECTEXTernal IP address and port for the IBMConnect:Direct/Plex server selected by WorkloadManager for this Process

Exception-IP, Exception-port Exception IP address and port.

The following shows an example of the syntax for the CDPLEX.REDIRECT.EXCEPTION parameter where:

• If the remote node contacts the IBM Connect:Direct/Plex Manager on 10.20.129.165 and the selectedIBM Connect:Direct/Plex Server redirects to 10.20.201.3 port 3811, then 10.20.129.162 port 3811 willbe used instead.

• If the remote node contacts the IBM Connect:Direct/Plex Manager on FD00:0:0:22CE::3802and the IBM Connect:Direct/Plex Server redirects to FD00:0:0:22CE::3803 port 4812, thenFD00:0:0:22CE::3805 port 3811 will be used instead.

• Otherwise, the address and port specified in the CDPLEX.REDIRECT parameter will be used.

CDPLEX.REDIRECT.EXCEPTION=( - ( 10.20.129.165, 10.20.201.3, 3811, 10.20.129.162, 3811) - ( FD00:0:0:22CE::3802, FD00:0:0:22CE::3803, 4812, - FD00:0:0:22CE::3805, 3811) )

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.SERVER = IBM Connect:Direct/Server nameThis parameter specifies the name of the IBM Connect:Direct/Server. Use only for IBM Connect:Direct/Plex members whose CDPLEX.MANAGER parameter value is NO. Each IBM Connect:Direct/Server in theIBM Connect:Direct/Plex must have a unique 1–8 character name. The IBM Connect:Direct/Server namecannot be the same as the XCF.NAME name. (The XCF.NAME name is used as the IBM Connect:Direct/Manager name).

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.SERVER.JOBDSN = data set nameThis parameter specifies the data set name that contains the various jobs or started tasks that aresubmitted at initialization. This parameter is only valid for the IBM Connect:Direct/Manager.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.SERVER.JOBMEM = ((member name,server name),…)This parameter specifies the CDPLEX.SERVER.JOBDSN member containing the JCL or start command thatstarts the specified IBM Connect:Direct/Server. The member name can be up to 8 characters long.

This parameter is only valid for the IBM Connect:Direct/Manager.

You can specify a maximum of 32 member/server name combinations.

If you want to start the IBM Connect:Direct/Server as a started task in a JES2 environment, use one of thefollowing to issue a start command:

• To issue a START command on the same z/OS image, include START= as the first statement in themember. The member is not submitted as JCL, but a START command is issued with the rest of the firststatement.

For example, if START=HOST4100,X is the first statement, then the command START HOST4100,X isissued to z/OS.

514 IBM Connect:Direct for z/OS: Documentation

• To issue a START command on a different z/OS image, include /*$VS,‘command’ as the first statementin the member. The member is submitted to JES, but JES identifies the /*$VS and issues the appropriatecommand to z/OS.

For example, if /*$VS,‘RO CSGB,S CDICOMB’, the member is submitted to JES and the

RO CSGB,S CDICOMB command is issued by JES to z/OS rather than placed in the job queue.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.SERVER.NODE = node nameThis parameter specifies a unique 1–16 character name for a IBM Connect:Direct/Server. This parameteris not used for a IBM Connect:Direct/Manager.

In a IBM Connect:Direct/Plex, all members appear to external IBM Connect:Direct systems as a singlelocal node. However, if you use network map checking and an external IBM Connect:Direct systemcommunicates with more than one IBM Connect:Direct/Server, you can specify a name to identify eachIBM Connect:Direct/Server.

The adjacent node's USE.SERVER.NODE network map parameter (see “Keyword Parameters for AdjacentNode Entries” on page 255) must specify that the IBM Connect:Direct/Server use this name in the initialcommunications.

Modifiable through MODIFY INITPARMS command: NO

CDPLEX.TIMER = 5 | number of minutesThis parameter specifies the time-out value for XCF communications in minutes. The valid range is 0,5–99. Zero (0) indicates that no time-out is set for XCF communications.

Modified through MODIFY INITPARMS command: NO

CDPLEX.VTAM = (VTAM-APPL,P/S-Node-APPL)This parameter specifies the VTAM APPLIDs for a IBM Connect:Direct/Server. This initialization parameteris required for a IBM Connect:Direct/Server if SNA=YES is specified in the global initialization parameters.

Modifiable through MODIFY INITPARMS command: NO

Chapter 4. Administration Guide 515

516 IBM Connect:Direct for z/OS: Documentation

Chapter 5. User Guide

Introduction to IBM Connect:Direct commandsUse IBM Connect:Direct commands to submit and manipulate Processes stored in the TransmissionControl Queue (TCQ). For example, you can select, delete, and suspend Processes by using IBMConnect:Direct commands.

You can use either of the following two methods to issue commands:

Method Description

Batch Interface Enables you to issue IBM Connect:Direct commands with the DGADBATC programin a batch environment. See Introduction to the Batch Interface for moreinformation about how to use the Batch Interface.

Interactive User Provides easy-to-use command entry through fill-in-the-blank screens. TheInteractive User Interface (IUI) is an ISPF Dialog online interface. See Introductionto the Interactive User Interface (IUI), for more information on how to use the IUI.

Some command options which you can select through the IUI do not have a batch equivalent. Thedocumentation notes these exceptions in option descriptions.

Supported commandsThe following table lists IBM Connect:Direct commands, which perform various administrative and userfunctions.

Command IUI Function

CHANGE PROCESS CP Modify a Process in the TCQ

DELETE PROCESS DP Remove a Process from the TCQ

DELETE TYPE DT Delete a record from the Type file (both a user andadministrative task)

DELETE USER DU Delete a user from the Authorization file (administrativetask)

FLUSH PROCESS FP Terminate an Executing Process (both a user andadministrative task)

FLUSH TASK TF Remove a task from the Execution queue (administrativetask)

INQUIRE INQ View information about IBM Connect:Direct DTF status

INQUIRE SNMP INQ SNMP Display SNMP Trap Table

INSERT TYPE IT Insert a record in the Type file (both a user andadministrative task)

INSERT USER IU Add a user to the Authorization file (administrative task)

MODIFY MD Run diagnostics and modify initialization parameters(administrative task)

SELECT MESSAGE SEL MSG Display message detail using message ID

SELECT NETMAP NM Display node from the network map file

© Copyright IBM Corp. 1993, 2021 517

Command IUI Function

SELECT PROCESS SP Examine a Process in the TCQ

SELECT STATISTICS SS, S2 Examine records in the Statistics Log

SELECT TASK TS Display IBM Connect:Direct system tasks status(administrative task)

SELECT TCPXLAT NM Translate TCP/IP host names - addresses

SELECT TYPE ST Examine the records in the Type file (both a user andadministrative task)

SELECT USER SU Examine user authorization (administrative task)

SIGNON Connect to IBM Connect:Direct DTF

SIGNOFF X Terminate a connection to the IBM Connect:Direct DTF

STATISTICS STAT Perform statistics functions (administrative task)

STOP CD SN Stop IBM Connect:Direct operation (administrative task)

SUBMIT SB Submit a Process for execution

SUSPEND PROCESS SUS Suspend Process execution

SWAP NODE SW Swap to another IBM Connect:Direct node

UPDATE NETMAP UNM Update the network map file (administrative task)

UPDATE TYPE IT Update a record in the Type file (both a user andadministrative task)

UPDATE USER IU Change user privileges (administrative task)

Writing IBM Connect:Direct commandsA IBM Connect:Direct command is a string of characters that conveys your requests to the IBMConnect:Direct Data Transmission Facility (DTF) for execution. You write these commands by using aunique syntax called the IBM Connect:Direct native format.

If you are using the batch interface, operator interface, or your own user-written application, you write thecommands in this native format. If you are using the IUI, IBM Connect:Direct builds the commands in theformat for you.

Native formatThe following table shows the structure of a IBM Connect:Direct command in its native format.

Label Command Parameters and Subparameters

The following table explains each command component:

Component Description

Label (optional) You can optionally identify your IBM Connect:Direct command through use of alabel. A label must begin in position 1 and consists of a 1-8 character alphanumericstring, with the first character alphabetic.

Note: The Connect:Direct commands are reserved words and should not be usedas labels. For example, SUBMIT, SELECT etc.

Note: Any value in column position 1 is considered a label and is processed assuch.

518 IBM Connect:Direct for z/OS: Documentation

Component Description

Command The command itself specifies the IBM Connect:Direct function requested and mustbegin after position 1.

Use one or more blanks to separate the command from the parameters whichfollow it.

Parameters orSubparameters

Parameters or subparameters specify further instructions for the command.Separate your parameters by one or more blanks. Parameters can be eitherkeyword or positional.

Keyword parameters are usually followed by an equal sign and can have a setof subparameters. An example of a keyword parameter is CASE in the followingcommand.

SIGNON NETMAP=network.map.name CASE=Yes|No

You must type positional parameters in a specific order, with commas replacingany parameter not typed. These parameters are always on the right of the equalsign. Enclose positional subparameters in parentheses, with the parenthesespreceded and followed by blanks or commas.

In the following command USERID is an example of a keyword parameter, andID,pswd,newpswd are examples of positional subparameters:

SIGNON USERID=(ID,pswd,newpswd)

A positional parameter or the variable information in a keyword parameter issometimes a list of subparameters. Such a list can include both positional andkeyword parameters.

Command exampleThe following CHANGE PROCESS command changes a preexisting Process named PAYROLL so that thenew destination node is DALLAS1 and the Process executes every Friday.

Note: In the following example the command CH should start in column position 2 or greater and wouldnot be appropriate as a label starting in column position 1.

CH PROC WHERE (PNAME=PAYROLL) - DEST=DALLAS1 - RETAIN=Y - STARTT=(FR)

Command syntaxThis section describes the syntax used to construct IBM Connect:Direct commands and Processes.

For a complete description of Process syntax and examples, see the IBM Connect:Direct Process LanguageReference Guide.

AsterisksUse asterisks to indicate generic specifications of parameters in the SELECT commands. With generics,you request information by specifying just a single asterisk (*) or a character string plus an asterisk.

To examine records for users whose user IDs begin with ST, specify the following parameter:

USERID=ST*

Chapter 5. User Guide 519

CommasCommas function to separate items within a list (except in the case of symbolic substitution. Refer toSymbolic Substitution), and to control the order of values specified as positional parameters. You mustuse a comma to indicate omission of a positional parameter. In the following example, the omission of thepswd subparameter is indicated by the extra comma.

SIGNON USERID=(ID,,newpswd)

Continuation MarksA command can continue across multiple lines. Use the hyphen (-), preceded and followed by a space, toindicate that the command continues on the following line. The hyphen can appear anywhere in positions3-79. The following command is continued on a second line.

CHANGE PROCESS WHERE (PNAME=PAYROLL) - DEST=DALLAS1

ParenthesesIn the following example, parentheses enclose lists and associate a group of values.

SIGNON USERID=(MYUID1,MYPSWD)

Symbolic SubstitutionUse symbolic substitution to substitute information in a IBM Connect:Direct Process. The substitution isrepresented by an ampersand (&) plus 1-8 alphanumeric characters. In the following example, the valuefor &DATA is resolved when you submit the Process.

DSN=&DATA

If you have multiple symbolics, separate them with one or more spaces.

Single and Double Quotation MarksThe rules for using single and double quotation marks are:

• Single-quote strings allow the parsing of parameters as typed.• Double-quote strings allow the resolution of symbolic substitution in a quoted string.

The following example shows the use of single quotation marks to enable you to embed specialcharacters or blanks within a parameter or subparameter value.

SIGNON PACCT='JOB FOR SYSMAINT,DEPT.27'

The following example shows the use of double quotation marks to allow for the resolution of symbolicsubstitution.

SIGNON PACCT="JOB FOR SYSMAINT,DEPT. &DEPND"

Single quotation marks are not valid for symbolic substitution in a IBM Connect:Direct command butcan be used with a keyword parameter in a Process statement (refer to the IBM Connect:DirectProcessLanguage Reference Guide

For example, the following SUBMIT Process command, which uses single quotation marks:

SUB PROC=DCB HOLD=YES - &DCB='DCB=(LRECL=80,BLKSIZE=3120,RECFM=FM)'

520 IBM Connect:Direct for z/OS: Documentation

results in the following invalid Process.

SUB PROC=DCB HOLD=YES &DCB='DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB)'

The following example which uses the same Process information as the example above but this time withdouble quotation marks:

SUB PROC=DCB HOLD=YES - &DCB=”DCB=(LRECL=80,BLKSIZE=3120,RECFM=FM)”

resolves to:

SUB PROC=DCB HOLD=YES &DCB=DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB)

CommentsComments allow you to include descriptive information within a command. Comments are available foryour convenience and do not affect IBM Connect:Direct. Use the following formats for comments:

• Preceded by a slash-asterisk (/*) and followed by an asterisk-slash (*/).• An asterisk (*) in position 1, followed by the comment.

Note: The /* must be paired with an */ even if it goes across multiple lines.

The following lines are valid comments, indicating that the SIGNON command labeled DSIGN signs on tothe DALLAS node.

/* SIGN ON TO DALLAS */*SIGN ON TO DALLASDSIGN SIGNON NODE=DALLAS /*DALLAS*/

/* Start of my comment SIGNON is then followed bySIGNOFF End of my comment */

ConcatenationUse the double bar ( || ) to concatenate, or link together, character strings. You must precede the doublebar and follow it with a blank. Use the double bar to join a long value that continues over multiple records.For example, you can type the following command.

PACCT=JOBACCTDATA || -WITHNOBLANKS

The vertical bar is x'4F'.

IBM Connect:Direct resolves your command to the following format:

PACCT=JOBACCTDATAWITHNOBLANKS

Special CharactersCertain characters cause IBM Connect:Direct to take special actions. These special characters are thehyphen (-), double bar (||), ampersand (&), and the IBM Connect:Direct delimiters. The following tablelists the delimiters recognized by IBM Connect:Direct.

Delimiters Description

blank

< less than sign

Chapter 5. User Guide 521

Delimiters Description

> greater than sign

* asterisk

( open parenthesis

) close parenthesis

¬ not sign

/ slash

\ backslash

, comma

. period

' single quotation mark

" double quotation mark

= equal sign

{ opening brace

} closing brace

[ opening bracket

] closing bracket

Special Purpose BracketingYou must often maintain special characters as part of a string. To maintain special characters, enclose thestring in bracketing characters. Bracketing characters are backslashes (\), single quotation marks ('), anddouble quotation marks (").

Bracketing backslashes are indicators of special processing of a character string. IBM Connect:Directdoes not maintain them as part of the string at its final resolution. Use bracketing backslashes to:

• Continue a string containing special characters across multiple lines• Ensure that quotation marks within the string are maintained

The following is an example of using bracketing backslashes in a command:

PACCT=\'DEPT\MIS\ || - \602'\

IBM Connect:Direct resolves the command as follows:

PACCT='DEPT\MIS602'

Indicating case sensitivityThe CASE parameter specifies whether parameters associated with accounting data, user ID, password,and data set name in the commands and Processes are case-sensitive. You can make this designation atthe signon level for all commands that are issued for the session that is established by the signon, and atthe command level.

The following table describes the levels at which you can set the CASE parameter.

522 IBM Connect:Direct for z/OS: Documentation

Level Description

Session The CASE parameter of the SIGNON command indicates if commandsentered during this session are case-sensitive. The default value is NO. Youcan override this setting at the command level.

Individual Command You can change the CASE parameter for an individual command and overridethe session case sensitivity as follows:

• In the Connect:Direct for z/OS IUI, the CASE parameter is usually indicatedon the IUI by the following words: DO YOU WANT VALUES FOR THISREQUEST TO BE CASE SENSITIVE? ==> Reply Y or N to this question. Thevalue for the CASE parameter stays in effect as long as you reuse the samepanel. When you change panels, the value reverts to the session default.

• In native command mode, such as used in the Batch Interface, you mustdesignate your override on each command record if you want to overridethe CASE parameter of the SIGNON command.

Process For commands that refer to Processes already in the TCQ, only the CASEparameter applies to the fields in the command. For commands that referto Processes that are not yet in the TCQ, the case sensitivity applies to theProcess statements.

Indicating selection criteriaUse the WHERE parameter to specify which records to select, change, or delete based on subparameters,such as Process name or Userid.

Selection subparameters are optional; however, you must specify at least one. These subparameters arespecial in that they identify which records are selected for the command activity defined by the otherparameters.

Use the WHERE parameter to indicate selection criteria for commands which affect Process, Task, Type,User, and Statistic records. For Statistics records, you may also specify WHERE2 which provides supportfor all *NODE selection criteria. The command function applies to all records which match the selectioncriteria.

For example, in the CHANGE PROCESS command, you can use the WHERE parameter with its PNUMBERsubparameter to select a list of Processes by number and release all of them through the RELEASEparameter.

In the IUI, the WHERE parameter is represented by the list of selection criteria which precedes thecommand parameters themselves. For example, you see the following on the CHANGE PROCESS screen:

PROCESS NUMBERS: ==> _____ ==> _____ ==> _____ ==> _____

Additionally, you see lists for Process name and submitter to indicate the selection criteria. The IBMConnect:Direct IUI builds the WHERE parameter for the command as it selects the fields from left to righton the screen.

Indicating output destinationThe FILE, PRINT, TABLE, and DISPLAY parameters specify the form in which information is presentedwhen the command produces output.

The following table describes each parameter.

Chapter 5. User Guide 523

Parameter Description

FILE Causes IBM Connect:Direct to return the output as unformatted records to thetemporary file. You indicate the name of your temporary file through the TMPDSNparameter of your SIGNON command. See “Using SIGNON through the BatchInterface” on page 558 , for a description of the TMPDSN parameter. Thestatistics record macros in the IBM Connect:Direct sample library provide theoutput record format.

When IBM Connect:Direct puts the unformatted records in a temporary file, otherprograms can process the records and customize reports for specific needs. Youcan use this functionality to process statistics records. You can archive a statisticsfile each day with a Generation Data Group (GDG). The IBM Connect:Direct productprovides sample job streams that extract statistics on a daily basis.

PRINT Routes output of the command to the destination specified in the PRINT keywordof the SIGNON command. See “Using SIGNON through the Batch Interface” onpage 558 , for a description of the PRINT parameter.

TABLE or DISPLAY Stores the output of the command in the IBM Connect:Direct temporary file or filespecified in the TMPDSN parameter and displays it upon successful completionof the command. (For more information on the TMPDSN parameter, see “UsingSIGNON through the Batch Interface” on page 558.) The output is usually intabular format. You can browse the output by using such commands as UP, RIGHT,or FIND. Press the PF1 key for Help on how to browse the file.

Some screens offer additional output format, such as summary tables. These options are listed along withthe display, file, and print options.

The batch interfaceYou request IBM Connect:Direct services in the batch environment through the batch interface program,DGADBATC.

When you submit a job stream that contains IBM Connect:Direct commands such as SYSIN input,DGADBATC reads the input data stream and processes the requested functions. DGADBATC supportsall IBM Connect:Direct commands.

Batch interface job requirementsBatch interface jobs must meet certain requirements.

• You cannot use Process statements in the job stream. Use the SUBMIT command with a preexistingProcess that contains Process statements. The batch job is notified of a successful SUBMIT, but notwhether the PROCESS itself is successful. Unless MAXDELAY is used, DGADBATC processing of theSUBMIT is asynchronous.

• For DGADBATC, specify a region size of 0 megabytes (REGION=0M), especially if you specifyMAXDELAY. If you specify a different region size, the DGADBATC job may ABEND with an 878 code.

• The Processes that you submit using the PROC parameter must be in the IBM Connect:Direct PublicProcess Library, allocated to the DMPUBLIB DD statement in the DGADBATC JCL. If the Process is notin the IBM Connect:Direct Public Process Library, use the DSN parameter of the SUBMIT command toindicate the location of the Process. See Building, Modifying, and Submitting Processes, for the DSNparameter description.

The IBM Connect:Direct commands that you use in the batch job stream must follow the syntax that isoutlined in Writing IBM Connect:Direct Commands.

• If you are not using the Extended Submit Facility (ESF), the DTFs that you sign on to must be activewhen you submit the DGADBATC job.

524 IBM Connect:Direct for z/OS: Documentation

• You can specify ESF as a SIGNON command parameter. You can only issue SIGNON, SIGNOFF, andSUBMIT commands by using ESF. ESF is only available for Processes you submit on the local node. Youcannot use ESF with MAXDELAY.

Processing rulesThe following rules apply to IBM Connect:Direct commands and options in the DGADBATC job stream.

• The first command in the job stream must be a SIGNON command.• The maximum command string length is 4,096 bytes. Each new IBM Connect:Direct command in the job

stream must start on a separate line. You can split a command across more than one line by using thecontinuation mark. However, the first word or string of the next command must start on a new line asshown in the following example.

SIGNON USERID=(LYNN) - NODE=CD.BOSTONSEL STAT WHERE (PNUM=24)SIGNOFF

• All IBM Connect:Direct commands must start in column 2. Any data in column 1 is considered a label.

Sample job stream to run the batch interfaceThe following example shows a sample job stream to run the DGADBATC program. The job stream islocated in $CD.SDGAJCL(DGADBATC).

//JOBNAME JOB (ACCNTNG),PROGRAMMER,TIME=2,CLASS=A,// MSGCLASS=A//DGADBATC EXEC PGM=DGADBATC,REGION=0M,PARM= 'YYSLYNNNNNN'//STEPLIB DD DISP=SHR,DSN=$CD.SDGALINK//DMNETMAP DD DISP=SHR,DSN=$CD.NETMAP//DMPUBLIB DD DISP=SHR,DSN=$CD.SDGAPROC//DMMSGFIL DD DISP=SHR,DSN=$CD.MSG//DMPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSIN DD * SIGNON USERID=(USERID,- PASSWORD) SUBMIT PROC=COPY SNODE=CD.NODE.B - HOLD=NO - &NODE=PNODE - &DSN1=DATASET1 - &DSN2=DATASET2 - &DISP1=RPL - &DISP2=CATLG - &COMPRESS=COMPRESS SEL PROC WHERE (QUEUE=A) TABLE SIGNOFF/*

The following example shows the COPY Process submitted in the previous example as it is displayed inthe IBM Connect:Direct Public Process Library, $CD.SDGAPROC:

COPY PROCESSSTEP1 COPY FROM(&NODE DSN=&DSN1 DISP=SHR) - TO (DSN=&DSN2 DISP=(&DISP1,&DISP2)) - &COMPRESS

DDNAMES for DGADBATCThe DGADBATC program has both required and optional ddnames.

The following table describes the required and optional ddnames for the DGADBATC program shown inthe sample job stream example.

Chapter 5. User Guide 525

DDNAME Description

STEPLIB Indicates the location of the library that contains the IBM Connect:Direct load modules.This DD statement is required, unless the data set is in linklist.

DMNETMAP Indicates the name of the network map for the node you are signing on to. You canalso specify this name through the SIGNON command NETMAP parameter. If you useboth methods, the network map file name specified on the SIGNON command takesprecedence. This DD statement is optional.

DMPUBLIB Indicates the library that contains the IBM Connect:Direct Processes. This DD statementis required.

DMMSGFIL Indicates the IBM Connect:Direct message file that contains IBM Connect:Directmessages. This DD statement is required.

DMPRINT Indicates the destination of the job output from DGADBATC that collects outputmessages such as error messages. This DD statement is required. Always checkDMPRINT output for verification of the processing that occurred.

SYSPRINT Indicates the destination of the job execution messages. This DD statement is optional.

NDMCMDS Use to test new job streams. If specified, it prints an image of each command sent toIBM Connect:Direct after processing all symbolic substitution and parameter overrides.This DD statement is optional.

APITRACE Used to provide an automatic trace of the API code. This DD statement is optional.

Note: Depending on the number of commands in SYSIN a large amount of trace datacan be generated.

APISECUR Used tp provide an automatic Security trace for the API code. This DD statement isoptional.

Note: Depending on the number of commands in SYSIN a large amount of trace datacan be generated.

SYSIN Indicates the location of the IBM Connect:Direct commands. You can represent it asa sequential file, PDS member, or instream data. If using a file, its DCB should beRECFM=FB,LRECL=80. This DD statement is required.

DGADBATC EXEC parametersThe DGADBATC EXEC parameters identify optional output formatting routines.

The characters in the PARM keyword in the DGADBATC EXEC statement are required parameters. Theoutput is displayed in the data set defined by DMPRINT. In the following table which lists the positionalDGADBATC EXEC parameters, Y stands for yes, N for no, S for short text, and L for long text.

Position Value Description

1 Y Display the command string that executed.

N Do not display the command string that executed.

2 Y Display the API return code and message ID.

N Do not display the API return code and message ID.

3 S Display short message text when the API sends a return code of zero.

L Display long message text when the API sends a return code of zero.

N Do not display message text when the API sends a return code of zero.

526 IBM Connect:Direct for z/OS: Documentation

Position Value Description

4 S Display short message text when the API sends a non-zero return code.

L Display long message text when the API sends a non-zero return code.

N Do not display message text when the API sends a return code greater thanzero.

5 Y Display the data that generated in the temporary file.

N Do not display the data that generated in the temporary file.

6 N Reserved

7 N Reserved

8 Y If parameter 9 is specified as N, this parameters prints output from a SELECTSTATS command to DMPRINT when a MAXDELAY Process fails with a returncode other than 52.

9 Y Enables monitoring of the MAXDELAY Restart Process. Produces informationalmessages about monitoring and about the submitted and monitored Processnumber. For more information about MAXDELAY restart, see Using theMAXDELAY keyword parameter to synchronize submitted Processes

N Allows the MAXDELAY Process to execute without restart. The DGADBATCstep is suspended until the Process completes execution.

10

Applies toMAXDELAYRestart only.

Y If parameter 9 is specified as Y, the MAXDELAY progress is processed on astatus report to the DMPRINT DD using the Select Process command.

Note: Using this parameter may result in a large amount of data for DMPRINTDD.

N Suppresses the progress report.

11

Applies toMAXDELAYandMAXDELAYRestart.

Y Forces the DGADBATC step to terminate on the first return code of 8 orgreater.

N Allows the DGADBATC step to continue to process the commands in SYSINeven after a non-zero return code.

DGADBATC return codes with DGADCHLADGADBATC communicates with the IBM Connect:Direct API through a high-level application interfaceprogram, DGADCHLA. The DGADCHLA program detects error situations while processing commands forDGADBATC, and issues special return codes based on these situations.

The return code from DGADBATC reflects the highest return code of all commands processed.

If you receive a return code of 4 or 8, check the DMPRINT DD output for the exact error that isencountered during command processing to DGADBATC.

A return code of 8 normally indicates an invalid parameter or keyword. A return code of 4 indicates thatDGADCHLA found nothing for the command. For example, you could receive a return code of 4 if youissued a SELECT STATISTICS command for a Process with no statistics.

If you receive a DGADBATC return code greater than 8, check return codes for error information.

Chapter 5. User Guide 527

Return Code –Hexadecimal

ReturnCode –Decimal

Description

0000000C 12 A session is lost in a multiple session environment.

00000010 16 The master session is lost.

00000014 20 The master session is signed off successfully.

0000001C 28 A non-master signon failed.

00000020 32 High-level interface program, DGADCHLA, received an invalidnumber of

input parameters.

00000024 36 The output specification included an invalid parameter.

00000028 40 Invalid pointer to the UICB is passed to DGADCHLA.

00000034 46 MAXDELAY=0 Process never executed and was removed from theProcess

queue.

Using the MAXDELAY keyword parameter to synchronize submittedProcesses

You can synchronize submitted Processes by coding the MAXDELAY keyword parameter in either theSUBMIT command or the PROCESS statement.

To suspend the execution of the DGADBATC job step until the submitted Process either completes or aspecified interval of time elapses, use the MAXDELAY keyword.

For a detailed description of the MAXDELAY parameter, see the Submit command in “SUBMIT Command”on page 572.

Important: Because of the following restrictions, you might want to code MAXDELAY in the SUBMITcommand instead of the PROCESS statement:

• If you code MAXDELAY in a PROCESS and submit it through the IUI, the submit will fail with themessage SCBI220I MAXDELAY not supported feature for IUI.

• If you use the MAXDELAY PROCESS statement keyword, the message SCBI221I MAXDELAY notsupported for ESF submits is displayed when the DTF is down and the Process does not submit.

The following example shows the MAXDELAY keyword that is coded in the SUBMIT command.

//SYSIN DD * SIGNON USERID=(USER01,PASSWRD)ESF=NO SUBMIT PROC=PROCAAA MAXDELAY=UNLIMITED SIGNOFF/*

You can also place the MAXDELAY keyword in the PROCESS statement for PROCAAA, as in the followingexample.

PROCAAA PROC SNODE=REMOTE.NODE.B MAXDELAY=UNLIMITEDSTEP01 COPY TO (DSN=USER01.TESTDATA.OUTPUT - DISP=RPL - SNODE) - FROM (DSN=USER01.TESTDATA.INPUT - DISP=SHR - PNODE)

528 IBM Connect:Direct for z/OS: Documentation

SIGNON Parm Options

When the DGADBATC parameter nine enables the MAXDELAY Restart, it also enables new SIGNONcommand parameters, MAXWAIT and MAXRETRY. These parameters control how often and how manytimes the API attempts to restart a failed API session while monitoring a MAXDELAY process when theninth DGADBATC EXEC is set to Y.

MAXRETRY defines the number of attempts to restart the API session if a session failure occurs after asuccessful SUBMIT using MAXDELAY. If the failure occurs before SUBMIT returns the Process name andProcess number, no restart will be attempted. If the MAXRETRY count is exhausted without successfullyrestarting the session, DGADBATC terminates with MSGID=SCIB024I. The value for nn has a range of 1 to20, with a default value of 3.

MAXWAIT defines the interval of delay between restart attempts after a failed API session. The value fornn specifies seconds to wait and has a range of 0 (no wait) to 60 (1 minute), with a default value of 10seconds.

Example:

SIGNON USERID=(joe,joepwd) - MAXRETRY=nn - MAXWAIT=nn

MAXDELAY Restart

MAXDELAY Restart allows the API to respond to API session failures while waiting for a MAXDELAYProcess to complete and is only valid for processes submitted with the MAXDELAY parameter andactivated using new DGADBATC PARM values. Without the new PARM values, there is no change inbehavior for MAXDELAY or the API.

When activated with the new DGADBATC PARM values, the C:D Server will return Process name andProcess number immediately for processes submitted with the MAXDELAY parameter. The API monitorsprocess execution using Select Process commands until the process is no longer active in the queues.When the process is no longer in the queues, the API issues a Select Statistics command to determineprocess disposition.

Depending on process disposition, the MAXDELAY parameter requested, and DGADBATC PARM options,the API will either proceed to the next command or issue commands to delete the process and terminatethe API session.

If a API session failure occurs while monitoring the MAXDELAY process, the API will attempt to restartthe session then continue monitoring the process. API session restarts are controlled by new parametersspecified or defaulted from the SIGNON command.

DGADBATC Parm Options

Three DGADBATC PARM options activate and control the MAXDELAY RESTART. These values arerepresented as Y or N values in positions nine, ten and eleven of the PARM string.

Parameter nine enables or disables the MAXDELAY RESTART. To enable MAXDELAY RESTART and shift theMAXDELAY processing to the API, set this parameter to Y. The default for this parameter is N, causing theMAXDELAY, as described above, to be used.

Parameter ten allows the API to display to DMPRINT, a process progress report from the Select Processcommands used to monitor the process. To enable this progress report, set this parameter to Y. Thedefault for this parameter is N.

Important: Setting the tenth parameter to Y may produce additional output to DMPRINT for long runningMAXDELAY processes. You may want to consider utilizing other facilities, such as the IUI or IBM ControlCenter to monitor the progress of the process.

Chapter 5. User Guide 529

Parameter eleven provides control over the remaining commands within SYSIN in the event that aSUBMIT with MAXDELAY terminates with a non-zero return code. When specified as Y, this parameterforces an EOF or EOJ of the API without attempting to execute the remaining commands in SYSIN. Thisvalue defaults to N.

For example, if the SYSIN has 100 SUBMIT commands using MAXDELAY and the second submit failswith a non-zero return, with parameter eleven specified as Y the remaining 98 submit commands will notexecute.

//STEP1 EXEC PGM=DGADBATC,PARM='yyllyyyyYNN'

"yyllyyyy" are the old 8 parameters and YNN represent the new parameters. For more information aboutparameter options, see “DGADBATC EXEC parameters” on page 526

MAXDELAY Limitations and Restrictions

There are many considerations to take into account when using PROCESS submission and MAXDELAY.These considerations include:

• ESF and MAXDELAY are mutually exclusive. During an ESF session, the only command possible isSUBMIT. ESF and SUBMIT with MAXDELAY are not possible and results in SCBI221I MAXDELAY, afailure of the SUBMIT. An ESF submit occurs when the API cannot establish the connection to theServer for any reason, such as when the Server is down or when there is not enough SNA APPLIDdefined in the NETMAP; in these cases, it is the responsibility of the API to construct and assign theprocess number, and write the process to the TCQ.

• When using a MAXDELAY parameter of UNLIMITED, processes submitted that are not immediatelyeligible for execution are subject to the intelligent retry logic when a PROCESS to the same SNODEcannot establish a session. These processes will be placed into the HOLD queue while the failingprocess retries. If this failing process exceeds its maximum retry, all processes for that same SNODEwith be placed into the HOLD and will require manual intervention to run. This will cause the API to hangwhile not producing your desired results.

• If the connection between the API and the C:D Server is lost due to a time out or other network issues,the API is terminated without any knowledge of the results of the submitted process. However, withthe DGADBATC EXEC ninth parameter as Y, the MAXRETRY and MAXWAIT will attempt to restart theconnection.

How MAXDELAY Affects PROCESS Submission

When the Server constructs and writes the PROCESS to the TCQ , the Server does not communicate theresults or process number back to the API; instead, it places the API in a WAIT status. The API waits untilthe PROCESS completes its execution; it does not know the process number assigned. The API remainsin WAIT status and is dependent on the positional parameter defined with the MAXDELAY, unlimited,queued, time value or 0 (zero).

If set as unlimited or MAXDELAY UNLIMITED, the API connection will be in WAIT status until thePROCESS completes execution and is removed from the TCQ. In the event of an error that causes thatPROCESS to be placed into the HOLD queue, the API connection will remain in WAIT until manual action istaken for that held PROCESS.

When queued, time value, or MAXDELAY QUEUED, the API connection will be in WAIT until the PROCESScompletes execution or is removed from the TCQ or the time interval expires. If the PROCESS executeslonger than that specified time, or is placed into the HOLD queue the API will not get the complete orexpected results. If 0 (zero) or MAXDELAY ZERO, the API connection will be in WAIT until the PROCESScompletes execution and is removed from the TCQ. However, if an error occurs that would normally placethe PROCESS into the HOLD queue, the MAXDELAY ZERO PROCESS is removed from the queue and theAPI is posted complete with an error. An API connection cannot be in WAIT forever with MAXDELAYUNLIMITED.

530 IBM Connect:Direct for z/OS: Documentation

MAXDELAY Parm Options

The API applies the MAXDELAY restrictions depending on the MAXDELAY option requested, for example:

MAXDELAY = hh:mm:ss or QUEUED

If the process has not completed execution in the interval defined, the DGADBATC is terminated with anappropriate message and a non-zero return code:

MAXDELAY = UNLIMITED or 0 (zero)

When the process completes, the results are reported to DMPRINT and the API proceeds to the nextcommand in the SYSIN input. If the execution causes the process to be placed in the HOLD queue,notification will be reported to DMPRINT and the process will be deleted from the queue and theDGADBATC terminated with an appropriate message and non-zero return code.

Please note this is a change in behavior for MAXDELAY=UNLIMITED and that the process will be deletedsimilar to MAXDELAY=0.

The Interactive User Interface (IUI)Issue IBM Connect:Direct commands using the IUI through two menus.

Menu Description

The PrimaryOptions Menu

Enables you to invoke screens where you can create and submit Processes, viewstatistics about your Processes, control your Processes in the Transmission ControlQueue (TCQ), view your IBM Connect:Direct environment, access the message file,sign on, swap nodes, and sign off IBM Connect:Direct. This option is available to allusers, and is described in this book.

The AdministrativeOptions Menu

Enables the IBM Connect:Direct product administrator to perform maintenance tothe Type file, the Authorization file, and the network map and to perform functionssuch as selecting and flushing tasks, initializing traces, typing native commands,displaying storage utilization, requesting traces, and stopping IBM Connect:Direct.

Note: You can also use the Sterling Connect:Direct Browser User Interface to perform some of theprocedures in this chapter.

Primary Options MenuThe Primary Options Menu contains the IBM Connect:Direct functions which are available to most users.

Chapter 5. User Guide 531

View Modify Control Create Execute Help------------------------------------------------------------------------------CD.ART IBM Connect:Direct for z/OS Primary Options MenuOption ===>

Select one of the following:

CF - Copy a file ********************* SB - Submit a predefined process * * DF - Define a process using ISPF Edit * Today: 08.30.2018 * SS - View statistics for a completed process * Time: 14:00 * S2 - Advanced view statistics * UID: EPETE1 * MB - Submit a batch to Connect:Enterprise for z/OS * * CP - Change characteristics of a process * OPT Enabled * DP - Delete a non-executing process * OPT Part-Enabled * FP - Flush an executing process * OPT Disabled * SP - View data about an executing process * * PS - Suspend an executing process ********************* MSG - View Connect:Direct message text SW - Swap among concurrent Connect:Direct sessions SD - View/Change your Connect:Direct signon information defaults NM - View information in the Connect:Direct network map WHO - View characteristics of your Connect:Direct IUI environment SPF - Enter ISPF/PDF AUTH - View your Connect:Direct function authorization MS - Sign on to multiple Connect:Direct nodes concurrently ADMIN - Perform Connect:Direct administrative functions

To request a function, type its option identifier on the command line (CMD==>) and press Enter.

Selection Panel Flower box legendThe Primary Option Menu, like other IUI selection menus, has a flower box with the date, time, UID, anda legend of color scheme indicating user's authority to functions on the menu. If an option navigates toanother selection menu, the color indicates the user's authority to the functions on that menu.

• If an option has the same color as the flower box string OPT Enabled (default=WHITE), then the user isfully authorized to use the function, or all the functions in the menu it navigates to.

• If the option is the same color as OPT Part-Enabled (default=GREEN), then the user is authorized forsome of the functions in the menu it navigates to.

• If the option is the same color as OPT Disabled (default=BLUE) then the user is not authorized for thefunction or any function in the menu it navigates to.

For example, if the Primary Option Menu ADMIN option is BLUE, the user is not authorized for any of thefunctions on the ADMIN selection menu, and cannot even navigate to it via the Primary Option Menu. Ifthe ADMIN option is GREEN, the user is authorized for at least one, but not all of the functions on theADMIN selection menu, and can navigate to it. If the ADMIN option is WHITE, the user is authorized for allthe functions on the ADMIN selection menu, and can navigate to it.

The color scheme enables users to see what they are authorized to use on the selection menus, withouthaving to navigate to the User Authorization screen and interpret its contents. The colors can be changedby your Connect:Direct System Administrator.

Create and Submit ProcessesThe following options enable you to create and submit Processes to the TCQ:

Option Description

CF Displays the main Copy File Menu where you can set up a COPY Process.

SB Displays the Submit Process screen where you can submit a predefined Process.

DF Displays the Process Definition Screen where you can define or update a Process using theISPF edit function and then submit the Process.

532 IBM Connect:Direct for z/OS: Documentation

See Building, Modifying, and Submitting Processes for more information.

The following option enables you to view statistics related to completed Processes:

Option Description

SS Displays the Select Statistics screen where you can examine the system statistics logrecords with search criteria applied and select the output to go to a file, table, or printer.See Process Results and Statistics for more information on the Select Statistics screen.

S2 Displays the Advanced Select Statistics screen where you can enter all selection criteria inone scrollable panel. It also allows you to use the new *NODE selection criteria.

The following options enable you to delete, flush, view, suspend, and change Processes in the TCQ:

Option Description

CP Accesses the Change Process screen where you can change the priority and class of aProcess and the status of the Process in the TCQ. See Modifying a Process in the TCQ withCHANGE PROCESS for more information on the Change Process screen.

DP Displays the Delete Process screen where you remove a nonexecuting Process from the TCQ.

FP Displays the Flush Process screen where you can remove an executing Process from theTCQ.

SP Displays the Select Process screen where you view the status of Processes submitted(placed in the TCQ) for execution. See Controlling Processes with Commands for information.

PS Displays the Suspend Process screen where you put an executing Process in the Hold TCQ.See Controlling Processes with Commands for information.

The following options enable you to view your IBM Connect:Direct environment:

Option Description

MSG Displays the Message Maintenance screen where you can display IBM Connect:Directmessages or print a summary or full report of the IBM Connect:Direct message file. SeeViewing and Printing Messages Using Different Criteria for more information on the MessageMaintenance screen.

SD Displays the Signon Defaults screen where you can examine and change your signon defaultvalues. See Signing On to Connect:Direct for z/OS for more information on the SignonDefaults screen.

NM Displays the Select network map screen, where you choose for display or print the definednodes from the network map file and translate TCP/IP host names and network addresses.

WHO Displays the User Information screen, which indicates your user ID, user node, version,release, maintenance level of IBM Connect:Direct and file information about your currentsession. See Signing On to Connect:Direct for z/OS for more information on viewing currentsign on parameters.

AUTH Displays the User Authorization screen. This screen displays commands you are authorizedto use. See Displaying Your User Authorization for more information.

The following options enable you to sign on and swap among multiple sessions:

Option Description

MS Displays the Multiple Session Signon screen where you sign on to another DTF session. Seepage 46 for information.

Chapter 5. User Guide 533

Option Description

SW Displays the Swap/Display User Sessions screen where you view all the multiple sessionsthat you are signed on to and swap sessions. See Signing On to Multiple Sessions for moreinformation on the Multiple Session Signon screen.

The following options display other menus:

Option Description

SPF Displays an ISPF/PDF session, one level beneath IBM Connect:Direct panels. SeeNavigating the Interactive User Interface for information on branching to an ISPF/PDFsession.

ADMIN Displays the Connect:Direct Administrative Options Menu with command options used foradministering the system.

Navigating the Interactive User InterfaceYou can move from screen to screen with branch commands and function keys.

Using Branch CommandsBranch commands enable you to navigate quickly to a specific screen without returning to the Menu. Youcan type the branch command on the command line at the top of the screen (CMD==>) or on any inputline preceded by ==>. To execute the branch, type = followed by the ID of the screen you want to branchto and press Enter.

For example, to go to the Select Process (SP) screen, type =SP on the command line and press Enter.

Note: The equal sign (=) is not required before an option on the command line of the Signon screen or thePrimary Options Menu.

The following table describes two additional branch commands that you can use.

Command Description

=ADMIN.xx

where xx is thescreen ID

Enables you to move to an administrative screen from a primary screen. Forexample, to branch from the WHO screen (which is an option of the PrimaryMenu) to the INQ screen (which is an option of the Administrative Menu), type=ADMIN.INQ at the command line of the WHO screen.

SPF.x

where x is theSPF option that youwant to display

The SPF option on the Primary Options Menu branches to the ISPF/PDF session,one level beneath the IBM Connect:Direct panels. If you want to bypass theISPF/PDF menu, type the SPF command with a period and the option. Forexample, to use the BROWSE function within ISPF/PDF, type SPF.1 on thecommand line. The SPF command is valid on each IBM Connect:Direct screencommand line.

Using the PF KeysThe PF keys listed in the following table are some of the programmed default definitions that you can usewith IBM Connect:Direct screens. The ISPF user-defined PF keys are supported.

Key Result

PF1 Displays online field Help or long error message

PF3 Returns to the previous screen

PF4 Returns to the Primary Options Menu

PF7 Scrolls up

534 IBM Connect:Direct for z/OS: Documentation

Key Result

PF8 Scrolls down

PF10 Scrolls right

PF11 Scrolls left

Browsing the IUI DisplayThe TABLE or DISPLAY parameters which are options at the bottom of most Selection screens specifythat the output of the selection command is stored in the IBM Connect:Direct temporary file and thendisplayed upon successful completion of the command. The output is usually in tabular format. Use thecommands, UP, RIGHT, or FIND, to browse the output. Press the PF1 key to see extensive Help on how tobrowse the file.

Displaying Your User AuthorizationUse the User Authorization screen to determine commands you are authorized to execute. To access thescreen, select the AUTH option from the Primary Options Menu.

CD.ART USER AUTHORIZATION 13:43CMD ==>

AUTH COMMAND AUTH COMMAND --------------------------- ---------------------------

1) YES - CHANGE PROCESS 15) YES - SELECT TASK 2) YES - DELETE PROCESS 16) YES - SELECT TYPE 3) YES - DELETE TYPE 17) YES - SELECT USER 4) YES - DELETE USER 18) YES - SUBMIT PROCESS 5) YES - FLUSH PROCESS 19) YES - SUBMIT WITHIN PROC 6) YES - FLUSH TASK 20) YES - SUSPEND PROCESS 7) Y/Y - INSERT/UPDATE TYPE 21) YES - STAT COMMAND 8) Y/Y - INSERT/UPDATE USER 22) YES - EVENT COMMAND 9) YES - MODIFY (TRACE) 23) YES - VIEW PROCESS 10) YES - STOP CONNECT:DIRECT 24) YES - PERFORM CRC OVERRIDES 11) YES - UPDATE NETWORK MAP 25) NO - CONFIRM DELETE 12) YES - SELECT NETWORK MAP 26) YES - CONFIRM DEL OFF 13) YES - SELECT PROCESS 27) Y/Y - SECURE+ ADMIN/CMDS 14) YES - SELECT STATISTICS 28) YES - UPDATE INITPARM

YES or Y means you are authorized, NO or N means you are not authorized, and SUB means you areauthorized only if you submitted the Process.

To branch to an authorized function, type the corresponding number on the command line or cursor-select an enabled AUTH field, a field under the AUTH column.

Getting HelpIBM Connect:Direct provides a Help facility which describes the parameters that you can type through theIUI.

• Access the Help information by typing HELP on the command line and press Enter or pressing the PF1key.

• Press Enter to continue viewing the Help screens.• When you have viewed the screens, you can either press PF1 to continue to the tutorial or press PF3 to

return to the screen you branched from.

Operator TablesThe Operator Table is available only under the IUI. This display enables you to monitor and controlProcesses. It is accessed through the SELECT PROCESS command and provides a summary of PNODEProcesses in the TCQ. See Viewing and Controlling a Process through the Operator Table for a descriptionand samples of the Operator Table.

Chapter 5. User Guide 535

node.name Row 1 to 6 of 6 -------------------------------OPERATOR TABLE------------------- ==> Q SCROLL ===> PAGE OPTION PNAME PNUMBER SUBMITTER.NODE-- OTHER.NODE------ QUEUE SERVER USERID ------------------------------------------------------------------------------- SEND100M 18 CD.NODE1 CD.STD45 EX EX USER01 SEND50K 20 CD.NODE2 10.20.129.151 ¬P EX USER01 COPYPAY 25 CD.NODE3 CD.STD44 ¬P EX USER01 BKUPDSK1 2 CD.NODE4 10.20.129.141 ¬P EX USER01 BENCH50 13,218 CD.NODE5 CD.STD45 ¬P EX USER01 COPYCF 21 CD.NODE6 CD.STD45 HO HI******************************* Bottom of data ******************************** USER01

You can press Enter to refresh the display and monitor the progress of the Processes displayed on thescreen. The following table describes the commands that you can issue from the Operator Table.

Command Description

H Hold

D Delete

R Release

P Suspend

F Flush

V View Processes

S Show Detail

Type the option you want in the OPTION column next to the name of the Process as shown in the previousscreen.

Note: The Executing Queue version of the Operator Table displays the executing Processes only;therefore, the options available to it are limited to the Suspend (P) and Show detail (S) only.

MessagesYou may encounter two types of messages: ISPF/PDF and IBM Connect:Direct messages.

Message Type Description

ISPF/PDFmessages

Display at the top of the screen when the value you typed for a field does not pass theeditor. You get this kind of message if, for example, you type an alphabetic character ina numeric field. Press PF1 to see a longer explanation of the error or type HELP on thecommand line and press Enter.

IBMConnect:Directmessages andsense codes

Contain a short and long text which explain an error you get when you submit yourcommand. This type of error is indicated by a message ID with the format xxxxnnnx,for example, SVSL003I. You get this error, if, for example, you type an invalid Processname on a SELECT PROCESS command.

IBM Connect:Direct generates a sense code to indicate a connection error involvinga netmap. The format for a sense code is SENSnnnn where nnnn is the four-digitnumber representing the sense code.

536 IBM Connect:Direct for z/OS: Documentation

Message ExampleIn the following example, the user typed ABC for Process Number, a numeric field, resulting in themessage PROCESS NUMBER in the upper right corner. Pressing PF1 produces the longer message "ABC"IS INVALID...

node.name SELECT PROCESS PROCESS NUMBER CMD ==> O hh:mm "ABC" IS INVALID; MUST BE IN THE RANGE 0 - 199,999. CMD: O ... OPERATOR TABLE S ... OPERATOR TABLE/EXEC QUEUE STATUS P ... PRINT REPORT D ... DISPLAY REPORT V ... VIEW PROCESS QUEUE: ==> _ (A-ALL,W-WAIT,E-EXECUTE,H-HOLD,T-TIMER) PROCESS NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______ PROCESS NAMES: ==> ________ ==> ________ ==> ________ ==> ________ SERVER NAMES: ==> ________ ==> ________ ==> ________ ==> ________ STATUS: (HO,HR,HI,HE,HC,HP,HS,RH,RA,WC,WX,WT,H,R,W) ==> __ ==> __ ==> __ ==> __ DESTINATION NODES: ==> ________________ ==> ________________ ==> ________________ ==> ________________ USER ID: NODE ID: ==> ________________________________________________________________ ==> ________________ ==> ________________________________________________________________ ==> ________________ DO YOU WANT VALUES FOR THIS REQUEST TO BE CASE SENSITIVE? ==> NO

The following is an of the short text message that is displayed at the top of the screen.

No process(es) found matching the search criteria.

The long text provides a more detailed explanation of the message and can also include the system actionand a suggested response. Press PF1 to see the long explanation of the error or type HELP or M on thecommand line and press Enter. The following figure shows a sample message.

node.name Connect:Direct MESSAGE DISPLAY hh:mm CMD ==> MSGID ==> SVSL003I MODULE ==> DMVSOPEN Copy requested DISP=(,CATLG) to already cataloged dataset. The PROCESS COPY step requested a DISP=(,CATLG) on the TO clause of the COPY statement. The requested dataset already exists as a cataloged dataset. System Action. The PROCESS COPY step is terminated with a completion code of 8. Response: Either correct the COPY dataset or uncatalog the existing dataset and re-submit the PROCESS.

The Statistics Summary screen, an option of the SELECT STATISTICS command, also gives you the optionof branching to the message screen associated with a failed Process. Type an M next to the Process namewhich failed (indicated by an *), and IBM Connect:Direct displays the extended message.

Messages in a IBM Connect:Direct/Plex EnvironmentIn a IBM Connect:Direct/Plex environment, messages can originate from any IBM Connect:Direct Serveror from the IBM Connect:Direct Manager. The system administrator can define a 2-character messageID that identifies which IBM Connect:Direct/Plex member originated the message. This message ID isdisplayed after the message number, as in the following example. The message ID is highlighted in bold inthis example.

SVTM055I S1 SESSION (001) ESTABLISHED WITH SNODE=SC.DUB.OS390SVTM055I S1 SESSION (001) ESTABLISHED WITH PNODE=SC.DUB.OS390SVTM036I S1 PROCESS STARTED MVS2MVST( 1) PNODE=SC.DUB.OS390SVTM036I S1 PROCESS STARTED MVSM2VST( 1) SNODE=SC.DUB.OS390

Chapter 5. User Guide 537

The system administrator defines the message ID using the CDPLEX.MSGID initialization parameter. Formore information, see Customizing IBM Connect:Direct in the IBM Connect:Direct for z/OS AdministrationGuide and search for .

Viewing and Printing Messages Using Different CriteriaYou can use the Message Maintenance screen to view or print IBM Connect:Direct Message Text. You candisplay messages by message ID if you need to look up an error message in your Process statistics, or ifyou have a batch job that failed.

1. Type DIR at the COMMAND prompt at the bottom of the screen to display the directory of the modulemessages.

2. From the Primary Options Menu, select option MSG.The MSG command is available only through the IUI. The following sample screen is a combination oftwo panels to show the prefixes used in IBM Connect:Direct messages:

Connect:Direct MESSAGE LOOKUP 2 Members processed DATE => yyyy/mm/mm ENTER OPTION ==> _ TIME => hh:mm ============================================================================== OPTIONS =========== 1 = DISPLAY MESSAGE TEXT BY MESSAGE ID 2 = DISPLAY LIST OF ENTRIES (OPTIONALLY BY MODULE) MODULE==> ________________________________________________________________ 3 = PRINT SUMMARY REPORT 4 = PRINT FULL REPORT The following is the general basis for C:D messages: MAINFRAME: z/OS, VM, VSE, Security (ACF2, RACF, TSS), etc. MESSAGE MESSAGE PREFIX Applies to: PREFIX Applies to: N xxx CICS API failures Q xxx CICS API failures RACF xxxx Security system MSGs S xxxxxxx C:D Mainframe msgs SENS nnnn NETMAP sense code U nnnn z/OS User ABEND code CSPx xxxx Secure Plus MBCS xxxx Multi-Byte Character Set NON-Mainframe MESSAGE MESSAGE PREFIX Applies to: PREFIX Applies to: A xxxxxxx i5/OS or OS/400 CCUP xxxx Control Center EMSL xxxx HP NonStop or Tandem FSLD xxxx HP NonStop or Tandem IOXT xxxx HP NonStop or Tandem J xxxxxxx C:D for the Web L xxxxxxx Windows, SI, or Select V xxxxxxx OpenVMS X xxxxxxx Linux, UNIX, or Stratus

3. Type 1 on the command line and press Enter.The Message Display Screen appears.

4. Type the message ID and press Enter. (To check a sense code, type SENSnnnn where nnnn is thefour-digit number representing the sense code and press Enter.) The full text of the message (or sensecode) is displayed. In the following example, the information associated with Message SCBI190I isshown.

538 IBM Connect:Direct for z/OS: Documentation

Connect:Direct MESSAGE DISPLAY DATE => yyyy.mm.dd TIME => hh:mm MESSAGE ID==> SCBI190I MODULE ==> DMCBSUBM ============================================================================== SHORT TEXT==> Process specified not in process library. LONG TEXT: LINE 1 ==> This message may be generated for the following reasons: LINE 2 ==> LINE 3 ==> 1) The member specified is not in the public process library LINE 4 ==> or in the PDS specified in the 'DSN=' keyword. LINE 5 ==> 2) The process library has not been properly concatenated. LINE 6 ==> LINE 7 ==> LINE 8 ==> LINE 9 ==> LINE 10==> SYSTEM ACTION: Return to invoker with RC=8. LINE 11==> LINE 12==> RESPONSE: Verify the above is correct and resubmit process. COMMAND ===> ________ ENTER 'DIR' TO DISPLAY THE DIRECTORY

Viewing a Message ListYou can display a list of all IBM Connect:Direct messages or a list of messages generated by a module.

1. From the Primary Options Menu, select option MSG.

Note: The MSG command is available only through the IUI.2. Type 2 on the command line, specify a Module (optional), and press Enter. The Message Summary

screen appears. (If you do not specify a module name, all messages are displayed.)In the sample below, the module, DMINIT2, was specified.

------------------Connect:Direct MESSAGE SUMMARY------------------ Row 1 of 31 CMD ==> SCROLL ===> PAGE MSG ID MODULE MESSAGE CSPN010E DMINIT2 SIGNATURE.DSN.BASE Initialization Parameter Invalid CSPN011E DMINIT2 SIGNATURE.FILE.PAIRS Initialization Parameter Invalid CSPN012E DMINIT2 SIGNATURE.DSN.BASE and/or SIGNATURE.FILE.PAIRS missing CSPN013E DMINIT2 SECURE+ Interface Module not found CSPN116E DMINIT2 PARM FILE VALIDATION FAILURE CSPN117E DMINIT2 SECURE.DSN IS NOT A VSAM KSDS CSPN118E DMINIT2 SECURE+ INTERFACE MODULE NOT FOUND SCFS006I DMINIT2 AUTOLOG OF CMS SERVER FAILED SITA137E DMINIT2 POSIX Init Parm conflict. SITA169I DMINIT2 SECURE.DSN Data set not found. SITA170I DMINIT2 TRACE.BUFFER outside 0-999 range, TRACE.BUFFER=2 assumed. SITA185I DMINIT2 SITA185I (VSE) TCP.NAME VALUE OVERRIDEN BY SYSPARM. SITA190I DMINIT2 Secure+ Initialization failed, Secure No Override No SITA278I DMINIT2 All nodes are quiesced, QUIESCE=YES specified SITA338I DMINIT2 Asset Protection Failure. SITA339I DMINIT2 Number of licensed copies has been exceeded. SITA604I DMINIT2 Invalid option specified for SNA paramater. SITA607I DMINIT2 SNA=YES but no VTAM APPLID is available. SITA609I DMINIT2 VTAM services disabled. SITA610I DMINIT2 Both SNA and TCP are NO, can not continue. SITA641W DMINIT2 Level of PDSE.SHARING is not supported.

Note: You must specify the “old” modules names used in versions prior to the 5.1 release ofConnect:Direct for z/OS. For information, go to IBM Connect:Direct for z/OS Release Notes and searchfor Upgrading to Connect:Direct for z/OS Version 5.1.

3. Type an S next to the message ID for the full Message Display screen.

Printing MessagesYou can print the IBM Connect:Direct messages file in summary form or in detail, including the long formof the message text.

1. From the Primary Options Menu, select option MSG.

Chapter 5. User Guide 539

Note: The MSG command is available only through the IUI.2. Do one of the following:

• Type 3 on the command line for a summary report, and press Enter.• Type 4 on the command line for a detail report, and press Enter.

Specify the sysout class for the message file print output and the ID for a remote printer. If you wantyour output to go to a preallocated data set instead, specify the name of the data set. You mustenclose the data set name in single quotes and give it the following DCB attributes.

DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=0

The Application Program InterfaceThe high-level application-program, DGADCHLA, handles communication between the Connect:Direct forz/OS API and any application program that provides IBM Connect:Direct with command strings for batchprocessing. You can write an application program following the rules described in the following sections.

You can also process IBM Connect:Direct command strings by using the DGADBATC batch interfaceprogram. For more information on using DGADBATC, refer to Sample Job Stream to Run the BatchInterface.

Both DGADCHLA and DGADBATC are in $CD.SDGALINK.

You can design user-written applications that have an interface to IBM Connect:Direct. You can write theapplications in any computer language, including PL/I, Assembler, and COBOL. The following samples arein the $CD.SDGASAMP library:

Application Name Description

DGAXSAMP Assembler language user-written application

DGAXPLIS PL/I language user-written program

DGAXCOBS COBOL language user-written program

Important: All API programs run in 31-bit mode and they must call DGADCHLA in 31-bit mode. You caneither link your program as AMODE 31, or establish 31-bit addressability before calling DGADCHLA. Seethe sample program DGAXSAMP for an example of establishing 31-bit addressability and returning to24-bit addressability after the call to DGADCHLA. Also execute DGADCHLA with a BASSM rather than aBALR. Macro GENCALL is provided in the sample library to perform a BASSM. See the sample programDGAXSAMP for an example.

Attention: When calling DGADCHLA from an application that uses multiple subtasks to invoke theAPI simultaneously, it is recommended that an APIINIT call be made from the application maintask or a permanent subtask prior to attaching the API subtasks. The APIINIT call will anchorand initialize DCB storage for standard print/trace DDs used by all API subtasks. This will preventpossible ABEND conditions caused by CLOSE or I/O requests from subtasks that did not initiallyOPEN those DCBs. APIINIT should only be issued once by the application and will cause SCIB025Imessages to be written to the DDs identified in SDGAMAC member DGA$SYAT, if they are present.APIINIT is specified as the ninth parameter and all other parameters will be ignored for that call.

DGADCHLA ProgramThe DGADCHLA program communicates with the API through a control block interface called the UserInterface Control Block (UICB).

DGADCHLA works in the following sequence:

1. Optional APIINIT call to anchor print/trace DCB storage when API can be called from multiplesubtasks in calling application. This is a one time call from the application main task or a permanent

540 IBM Connect:Direct for z/OS: Documentation

subtask prior to attaching other subtasks that perform API calls. APIINIT is passed in the ninthparameter position.

2. DGADCHLA accepts IBM Connect:Direct command strings from an application program and passes thestrings to the API.

3. The user-written application requests DGADCHLA to perform output formatting routines afterreturning from the API. These formatting routines display information about the IBM Connect:Directcommand that just completed processing.

4. After execution of each command, DGADCHLA issues a return code reflecting the status of APIcommunications.

Required Parameters for DGADCHLADGADCHLA requires IBM Connect:Direct to pass three parameters on every invocation from anapplication program.

The parameters, in order, are the following:

Parameter Description

CMDLEN (firstparameter)

Points to a variable-length character string (up to 4096 bytes) that contains the stringlength in the first halfword and the command text in the remainder of the string. Justas in DGADBATC, the first command string must be a SIGNON and the last commandmust be a SIGNOFF. The following figure shows the command string format.

UICB@ (secondparameter)

Points to a fullword pointer of zeroes, which is filled in with the UICB address byDGADCHLA when DGADCHLA receives the SIGNON command from the applicationprogram. Information in the UICB can now be interrogated by the application program,if necessary. The UICB@ field is cleared and filled again with zeroes when DGADCHLAreceives the SIGNOFF command.

OUTSPECS(thirdparameter)

Points to a 7-character string containing the output format specifications. The outputis written to the file name defined by DMPRINT. Each specification is one characterlong.

All output generated as a result of these specifications is routed to a DDNAME ofDMPRINT. No output is created if the DDNAME is not present.

The following table describes the OUTSPECS output format specifications:

Field Values Meaning

1 Y Displays the command string thatexecuted.

N Does not display the commandstring that executed.

2 Y Displays the API return code andmessage ID.

Chapter 5. User Guide 541

Field Values Meaning

N Does not display the API returncode and message ID.

3 S Displays the short message textwhen a return code of zerocomes from the API.

L Displays long message text whena return code of zero is receivedfrom the API.

N Does not display message textwhen a return code of zero isreceived from the API.

4 S Displays the short message textwhen a nonzero return codecomes from the API.

L Displays long message text whena nonzero return code comesfrom the API.

N Does not display message textwhen a return code greater thanzero comes from the API.

5 Y Displays the data generated inthe temporary file.

N Does not display the datagenerated in the temporary file.

6 Y Displays the string that identifiesUICB fields which the Extractfeature returns informationabout.

N Does not display the stringthat identifies UICB fields whichthe Extract feature returnsinformation about.

7 Y Displays a dump of the area thatreceived output from the Extractfeature.

N Does not display a dump of thearea that received output fromthe Extract feature.

8 Y If parameter 9 is specified asN, this parameters prints outputfrom a SELECT STATS commandto DMPRINT when a MAXDELAYProcess fails with a return codeother than 52.

542 IBM Connect:Direct for z/OS: Documentation

Field Values Meaning

9 Y Enables monitoring ofthe MAXDELAY RestartProcess. Produces informationalmessages about monitoringand about the submitted andmonitored Process number.For more information aboutMAXDELAY restart, see Using theMAXDELAY keyword parameter tosynchronize submitted Processes

N Allows the MAXDELAY Processto execute without restart. TheDGADBATC step is suspendeduntil the Process completesexecution.

APIINIT Optional parameter used on firstinvocation to anchor DCB storagefor print/trace output. All otherparameters are ignored.

10

Applies to MAXDELAY Restartonly.

Y If parameter 9 is specified asY, the MAXDELAY progress isprocessed on a status report tothe DMPRINT DD using the SelectProcess command.

Note: Using this parameter mayresult in a large amount of datafor DMPRINT DD.

N Suppresses the progress report.

11

Applies to MAXDELAY andMAXDELAY Restart.

Y Forces the DGADBATC step toterminate on the first return codeof 8 or greater.

N Allows the DGADBATC stepto continue to process thecommands in SYSIN even after anon-zero return code.

The following example shows the most common specifications for this parameter.

OUTSPECS DC C'YYSLYNNNNNN'

Positions 6 and 7 are not used by DGADCHLA unless the extract feature of DGADCHLA is used, asexplained in the next section.

Extracting Return CodesIf you want the Return Code from the processed IBM Connect:Direct command, you must use the extractfeature. This feature enables you to extract certain UICB fields after IBM Connect:Direct commandexecution.

To activate the optional extract feature, the program must pass the following additional parameters toDGADCHLA:

Note:

Chapter 5. User Guide 543

DGADCHLA specifies either the first three required parameters or all eight parameters which includethese parameters related to return codes. If an incorrect number of parameters is passed, DGADCHLAissues an error message and assigns a return code of 20. Processing cannot occur during this time.

Parameter Description

EXTSTRLN (fourthparameter)

The UICB extract string.The user-supplied application must set up an extract stringidentifying the UICB fields to extract. The string consists of a halfword length fieldcontaining the length of the extract string (excluding the itself halfword lengthfield), followed by the first UICB field to extract, a space, the second UICB field toextract, a space, and so on.

A sample extract string follows:

You can only specify the UICB fields listed in the extract string. If you encounter aninvalid keyword in the string, the extract routine terminates execution, and no moreinformation is extracted. The application is informed of the error by means of theEXTRC, EXTMSG, and INVALKEY parameters. If field 6 of the OUTSPECS parameteris set to Y, the extract string is written to the file defined by DMPRINT.

EXTAREA (fifthparameter)

Where the UICB extracted information is placed. The application is responsible forensuring that the area is large enough to accommodate the information requestedby the extract string. If field 7 of OUTSPECS is set to Y, the extract string is writtento the file defined by DMPRINT. The following shows how to calculate requiredstorage for the extract area necessary for the extract string in the figure shown forthe EXTSTRLN parameter.

EXTRC (sixthparameter)

A 4-byte binary field containing the extract feature return code.

EXTMSG (seventhparameter)

An 8-character field containing an 8-character message ID from the extractfeature.

INVALKEY (eighthparameter)

An 8-character field containing an invalid extract string keyword. DGADCHLA relaysthe location of the extract string error to the application in this parameter. This fieldcontains the invalid item in the extract string if EXTRC is nonzero.

The following table shows how to calculate required storage for the extract area necessary for the extractstring in the figure shown for the EXTSTRLN parameter:

UICB Field Data Definitions Storage

UITMPDDN Character length of 8 8 bytes

UIRTNCD Fullword 4 bytes

UIPROC# Fullword 4 bytes

UIMSGID Character length of 8 8 bytes

UICB FieldsThe following table shows the valid UICB fields. Specifying these fields in the EXTSTRLN parameterresults in feedback in the extract area, defined by the EXTAREA parameter. Exact definitions are in theDGA$UICB macro found in $CD.SDGAMAC. In the table, the Control Block Builder Syntax Error WorkAreas have a value only when appropriate. For the Boolean Flags, output is Y (bit is on) or N (bit is off).

544 IBM Connect:Direct for z/OS: Documentation

Name Type LN Description

UIRCBLNG halfword 2 The length of the control block

UIDESCR character 16 UICB identifier

UITCA address constant 4 Task Control Area

UIBRCB address constant 4 Batch Region Control Block

UIDYNCB address constant 4 Dynamic Allocation Control Block

UITPCB address constant 4 Text Parser Control Block

UILEVEL fullword 4 Modal level counter

UITMPDCB address constant 4 Temporary file DCB

UIMSGCB address constant 4 Message Control Block

UIUNODE character 16 User node ID

UIUID character 64 User ID

UIPSWD character 64 Signon password

UINPSWD character 64 New Signon password

UITMPVOL character 6 Volume serial number of temporary file if not specifiedby user

UNTMPDDN character 8 DDNAME used for temporary DSN

UIUSRTYP character 1 User Type (operator, administrator, user)

UIAPPLID character 8 VTAM logon ID

UIRTNCD fullword 4 API return code

UIMSGID character 8 API message ID

UILNODE character 16 Name of node that is "local" to DTF

UILPP halfword 2 Lines per page for printed output

UITMPLNG halfword 2 Length of TSO temporary file name

UITMPDSN character 44 TSO temporary file name

UIPUBLNG halfword 2 Length of Process Library name

UIPUBDSN character 44 Process Library name

UIMSGLNG halfword 2 Length of message library name

UIMSGDSN character 44 Message library name

UINETMAP character 64 Network map file name

UIPROC# fullword 4 Process number from submit

UIDSPLY address constant 4 Address of SCDSPLY

UISTRING address constant 4 Address of SCSTRING

****************

************ Start of control block builder syntax error work area

UILABL# halfword 2 Length of IBM Connect:Direct label

UILABL character 8 IBM Connect:Direct label

Chapter 5. User Guide 545

Name Type LN Description

UICMD1# halfword 2 Length of first word in IBM Connect:Direct command

UICMD1 character 8 First word in IBM Connect:Direct command

UICMD2# halfword 2 Length of second word in IBM Connect:Direct command

UICMD2 character 8 Second word in IBM Connect:Direct command

UIKLST# halfword 2 Length of keyword that starts a list

UIKLST character 8 Keyword that starts a list

UIKEYW# fullword 4 Length of keyword in list before error

UIKEYW character 8 Last keyword in list before an error

UIPARM# halfword 2 Length of parameter associated with UIKEYW

UIPARM character 8 Parameter in error associated with UIKEYW

UIERRM1# halfword 2 Length of UIERRM1 string

UIERRM1 character 64 All of the above work areas resolved into a string

UIERRM2 character 64 Msg ID and text for parsing error

****************

************ Start of boolean flags

UIERRON character 1 Indicates message in UIERRM1

UIERRLAB character 1 Indicates something in UILABL

UIERRCM1 character 1 Indicates something in UICMD1

UIERRCM2 character 1 Indicates something in UICMD2

UIERRSCP character 1 Indicates parsing error

UIERRC1O character 1 Indicates open delimiter after command keyword, forexample, "IF ("

UIERRC2O character 1 Indicates open delimiter after second commandkeyword

UIERRG character 1 Indicates VTAM error msg in UIERRM1

UIERRLST character 1 Indicates something in UIKLST

UIERRLOP character 1 Indicates open delimiter after UIKLST

UIERRLCL character 1 Indicates close delimiter after UIKLST

UIERRLEQ character 1 Indicates equal sign after UIKLST

UIERRLCM character 1 Indicates comma after UIKLST

UIERRLSP character 1 Indicates space after UIKLST

UIERRKEY character 1 Indicates something in UIKEYW

UIERRKOP character 1 Indicates open delimiter after UIKEYW

UIERRKCL character 1 Indicates close delimiter after UIKEYW

UIERRKEQ character 1 Indicates equal sign after UIKEYW

UIERRKCM character 1 Indicates comma after UIKEYW

546 IBM Connect:Direct for z/OS: Documentation

Name Type LN Description

UIERRKSP character 1 Indicates space after UIKEYW

UIERRBPC character 1 Indicates close delimiter before a parameter in a list

UIERRPRM character 1 Indicates something in UIPARM

UIERRPOP character 1 Indicates open delimiter after UIPARM

UIERRPCL character 1 Indicates close delimiter after UIPARM

UIERRPEQ character 1 Indicates equal sign after UIPARM

UIERRPCM character 1 Indicates comma after UIPARM

UIERRPSP character 1 Indicates space after UIPARM

UIF1SUBM character 1 Indicates a submitted Process

UIGOTDSN character 1 Indicates found temporary file name as Signoncommand parameter

UITFILE character 1 Indicates data is generated into temporary file

UIEOF character 1 Indicates reached EOF of Process file

UIMODAL character 1 Indicates modal statement processed

UITFILEX character 1 Reserved

UIMASTER character 1 Indicates this UICB is master

UIRECON character 1 Indicates a reconnect attempted

UIINACT character 1 Indicates VTAM session for this UICB failed

UILOCAL character 1 Indicates local node session

UIESF character 1 Indicates ESF=YES on Signon command

UIZOPSWD character 1 Indicates blank password on Signon

UIZNPSWD character 1 Indicates blank new password on Signon

****************

************ END OF BOOLEAN FLAGS

UIRAT@ address constant 4 PTR to resource address table

UIDRLSE# halfword 2 DTF release level

UIDPUF# halfword 2 DTF PUF level

UIDPUT# halfword 2 PUT tape number

UILINE# halfword 2 Line number within Process in error

UIRLSE# halfword 2 Current release, version and mod level

UIPUF# halfword 2 Current PUF level

UI@MASTR address constant 4 Master (user) UICB

UI@ACTIV address constant 4 Currently active UICB

UI@FPTR address constant 4 Next UICB

UI@BPTR address constant 4 Previous UICB

UIALOTYP character 8 Allocation type for temporary file

Chapter 5. User Guide 547

Name Type LN Description

UIALOPRI character 8 Allocation of prime space for temporary file

UIALOSEC character 8 Allocation of secondary space for temporary file

UIALOUNI character 8 Allocation unit for temporary file

UIALOVOL character 8 Allocation of volume serial number for temporary file

UIFOLD character 3 Fold to upper case if YES UIPRTALC

UIPRTALC character 80 User-defined IBM Connect:Direct print destination

UIPACCT# halfword 2 Length of PNODE accounting data

UIPACCT character 255 PNODE accounting data text

UISACCT# halfword 2 Length of SNODE accounting data

UISACCT character 255 SNODE accounting data text

UIGSCAPI (VM) character 8 GCS API virtual machine identifier

DGADCHLA Return CodesReturn codes reflect the status of the DGADCHLA communications with the API. These codes only reflectwhether DGADCHLA could process the request and pass the command to the DTF. They do not reflect thecompletion status of the command.

The following table defines each return code.

RC Description

00000000 The command executed normally.

00000004 Signon to the master session failed, but the ESF environment is established.

00000008 A non-ESF command attempted in an ESF environment.

0000000C A session is lost in a multiple session environment.

00000010 The master session is lost.

00000014 The master session signed off successfully.

00000018 The master session signon failed, and no ESF ability exists.

0000001C A non-master signon failed.

00000020 DGADCHLA received an invalid number of input parameters.

00000024 The output specifications included an invalid parameter.

00000028 An invalid pointer to the UICB is passed to DGADCHLA.

00000034 MAXDELAY=0 Process never executed and was removed from the Process queue.

For more information on master sessions and multiple session environments, refer to Signing On toConnect:Direct for z/OS.

Extract Fields for DGADCHLA Return CodesThe following extract fields apply to DGADCHLA return codes:

Field Description

UIRTNCD Lists return codes. UIRTNCD is set on completion of every command processed by theDTF.

548 IBM Connect:Direct for z/OS: Documentation

Field Description

UIMSGID Lists message IDs. UIMSGID is set on completion of every command processed by theDTF.

UIPROC# Identifies Process numbers. UIPROC# is set for every successful Submit command.

See UICB Fields for the complete list of UICB fields.

Important: When you are using DGACHLA within an application, ensure that for each SIGNON commanda SIGNOFF executes successfully (RC=x’14’) to avoid a storage creep within the application program.

DGADCHLA ExamplesThe following examples show how required and optional parameters appear in sample programs. There isalso a sample job stream for executing the program.

Required Parameters and Calling SequencesThe following example shows how the required parameters and calling sequences appear in a sampleAssembler program:

******************************************************************* THE DATA DEFINITIONS ARE AS FOLLOWS: *******************************************************************CMDLEN DS H LENGTH OF COMMAND STRINGCMD DS CL4096 COMMAND STRINGUICB@ DS A POINTER TO UICBOUTSPECS DC C'YYSLYNN' OUTPUT SPECIFICATIONS******************************************************************* ** THE DGADCHLA INVOCATION WOULD BE: ** *******************************************************************CALL DGADCHLA,(CMDLEN,UICB@,OUTSPECS),VL

The following example shows how the required parameters and calling sequences appear in a samplePL/I program:

******************************************************************* THE DATA DECLARATIONS ARE AS FOLLOWS: *******************************************************************DECLARECMD_PARM FIXED BINARY (31) BASED (R),UICB_PARM FIXED BINARY (31) INITI (0'B'),OUTSPEC_PARM CHAR (7) INIT ('YYSLYNN'),CMD CHAR (4096) VARYING,R POINTER;******************************************************************* ** THE DGADCHLA INVOCATION WOULD BE: ** *******************************************************************R=ADDR(CMD) ;CALL DGADCHLA(CMD_PARM, UICB_PARM, OUTSPEC_PARM);

Optional ParametersThe following example shows how the optional parameters look in a sample Assembler program:

Chapter 5. User Guide 549

*********************************************************************** THE PARAMETERS WOULD BE DEFINED AS FOLLOWS: ***********************************************************************CMDLEN DS HCMD DS CL4096UICB@ DS AOUTSPECS DC C'YYSLYYY'EXTSTRLN DC H'32'EXTSTR DC C‘UITMPDDN UIESF UIPROC# UIMSGID'EXTAREA DS OCL24 /*OUTPUT FROM THE UICB EXTRACT */EXTMPDDN DS CL8 /*VALUE OF UITMPDDN */EXESF DS F /*VALUE OF UIRTNCD */EXPROC# DS XL4 /*VALUE OF UIPROC# */EXMSGID DS CL8 /*VALUE OF UIMSGID */EXTRC DS FEXTMSG DS CL8INVALKEY DS CL8************************************************************************ NOTE THAT THE EXTRACT STRING ITSELF IS 30 BYTES LONG, *** BUT THE DUMP OF ITS EXTRACT WILL USE 31 BYTES. *** *** INSIDE THE MAIN BODY OF THE PROGRAM, THE CALL TO *** DGADCHLA WOULD LOOK LIKE: *** ***********************************************************************CALL DGADCHLA,(CMDLEN,UICB@,OUTSPECS,EXTSTRLN,EXTAREA, * EXTRC,EXTMSG,INVALKEY),VL

Sample Job Stream for Executing the ProgramThe following example shows a sample job stream that executes a IBM Connect:Direct program thatinvokes DGADCHLA.

//jobname JOB (ACCT),'PGMR NAME',// NOTIFY=TSOUER,TIME=(1),// MSGCLASS=X,CLASS=A,PRTY=9,REGION=1024K//JOBLIB DD DISP=SHR,DSN=$CD.SDGALINK//CD EXEC PGM=USERPROG//DMPRINT DD SYSOUT=*//DMNETMAP DD DISP=SHR,DSN=$CD.VSAM.NETMAP//DMPUBLIB DD DISP=SHR,DSN=$CD.SDGAPROC//DMMSGFIL DD DISP=SHR,DSN=$CD.VSAM.MESSAGE//SYSUDUMP DD SYSOUT=*//NDMCMDS DD SYSOUT=*

You must allocate several files using DD statements before executing a IBM Connect:Direct applicationprogram that calls DGADCHLA.

The following table defines the DD statements in the sample job stream:

Statement Definition

DMPRINT All output from SELECT PROCESS, SELECT STATISTICS, SELECT TYPE, and SELECTUSER commands is written to this DD. Also, output as a result of the OUTSPECSspecification is written to DMPRINT. DMPRINT is optional, but often required.

DMNETMAP This definition is the name of the network map file that contains the names of allthe nodes that IBM Connect:Direct communicates with. DMNETMAP is required if noNETMAP keyword is specified on the SIGNON command.

DMPUBLIB This definition is a library containing Processes. It is required.

DMMSGFIL This definition is the name of the Message file. It is required.

NDMCMDS If allocated, all command strings are written to the current file. It is optional.

550 IBM Connect:Direct for z/OS: Documentation

Managing Sessions

Signing On to Connect:Direct for z/OSThe SIGNON command establishes your session with the DTF so that you can issue commands.

You can control access to the IBM Connect:Direct system through the IBM Connect:Direct AuthorizationFacility and security exits. For information on security control, go to the IBM Connect:Direct for z/OSAdministration Guide and search for Implementing Security.

If you are using the Extended Submit Facility (ESF), you can submit the SIGNON command even thoughthe DTF is inactive.

Timeout ProblemsIf you are logged off involuntarily while using IBM Connect:Direct via TCP/IP, your problem may be relatedto the TCP/IP connection not being able to communicate with the DTF. If you see the message TCP/IPSEND error; Connection Lost, and press F1 to see the help for this message, the following text is displayedfor message SVTC006I:

MSGID ==> SVTC006I MODULE ==> DMTSTSND TCP/IP SEND error; Connection LostAn error has been detected while sending a command via TCP/IP.The TCP/IP connection has been lost. A possible cause isConnect:Direct has been shutdown and all TCP/IP connectionshave been closed.System Action: Normal processing can not continue.Response: Logoff and attempt to signon again.

Although the TCP/IP protocol does not have a mechanism to send you a console message indicating thatthe client has been dropped and your session has timed out, you can determine if this has happened toyou by looking in the statistics file for a signoff record with an SAFA019I error message that matches youruser ID (be sure to enter Y in the CHANGE EXTENDED OPTS field on the SELECT STATISTICS panel or usethe ADVANCED SELECT STATISTICS panel, and then enter SO as a record type on the next screen). Formore information, go to the IBM Connect:Direct for z/OS Administration Guide and search for Signon andIUI/API Errors.

IBM Connect:Direct provides an inactivity timer that is based on the number of minutes a user canremain inactive without communicating with the DTF. An administrator can specify this value using theTCP.API.TIMER global initialization parameter. IBM Connect:Direct will only recognize changes made tothe TIMEOUT parameter by an administrator. If you attempt to change this parameter and you are not anadministrator, you will not be able to sign on. You can determine if this has happened to you by looking inthe statistics file for a signon record with an SAFA020I error message that matches your user ID. For moreinformation, go to the IBM Connect:Direct for z/OS Administration Guide and search for Signon and IUI/APIErrors.

Note: The rationale behind the timeout feature is to do housekeeping to keep the number of hungsessions to a minimum and avoid the limit specifying the maximum number of users that can be signedon to IBM Connect:Direct. Without the timeout feature, an administrator would have to recycle the DTF toallow TCP/API logons to reconnect once the MAXUSER limit was reached.

Using SIGNON through the IUITo execute the SIGNON command through the IUI, perform the following steps:

1. Select IBM Connect:Direct from your ISPF/PDF Primary Option Menu. The Copyright and the Signonscreen are displayed, unless SIGNON defaults are previously set.

Chapter 5. User Guide 551

CMD ==> IBMConnect:Direct for z/OS VERSION : 06 RELEASE : 000 MODIFICATION : 000 LEVEL : 0000 TODAY IS : 2018/02/24 (2018.055 ) THE TIME IS: 09:01 More: + USER ID => USER01 PASSWORD => NEW PASS => NODE NAME => TRANSPORT => COMMUNICATION ADDRESS =>( , ) DESCRIPTION => TIMEOUT => Licensed Materials - Property of IBM 5655-X11 Copyright IBM Corp. 2013,2018 All Rights Reserved IBM is a Trademark of International Business Machines

The Signon screen indicates the version, release, modification, and Program Update Tape (PUT) levelsof IBM Connect:Direct.

2. Type your user ID and press Enter.

Depending upon your site configuration, you may also need to type in a password, a new password,node name, transport, communications address, and case sensitivity option before pressing Enter.These parameters are described in “SIGNON Command” on page 553, or press PF1 for Help.

If you are using the Extended Submit Facility (ESF), the DTF does not need to be active to execute theSIGNON, SIGNOFF, and SUBMIT commands.

Note: If the Error requesting session, IBM Connect:Direct may be inactive message is displayed, theIBM Connect:Direct DTF is not started.

If your signon is successful, the Primary Options Menu is displayed, unless you have updated yourSIGNON defaults to execute an initial command.

Viewing Your Current Signon ParametersYou can view your signon default parameter settings.

• To see how your signon parameters defaults are currently set, select the WHO option from the PrimaryOptions Menu.The following figure shows an example of the User Information display produced by the WHO option.

Connect:Direct IUI USER INFORMATION hh:mm CMD ==> USER ID==> USER01 USER NODE ==> node.name TRANSPORT PROTOCOL ==> NETMAP COMMUNICATION ADDRESS ==> APPLID TEMPORARY DSN DDNAME ==> TMPDD TEMPORARY DSN VOLSER ==> TMPVSER DATA SETS: TEMPORARY DSN ==> CD.TEMP.DSN MESSAGE DSN ==> CD.MSG.VER01 NETWORK MAP DSN ==> CD.NETMAP.VER01 PUBLIC PROCESS DSN ==> CD.PUBLIB IUI VERSION ==> VV IUI RELEASE ==> RRR IUI MODIFICATION ==> MMM IUI PUT LEVEL ==> PPPP DTF VERSION ==> V.RR.MM

552 IBM Connect:Direct for z/OS: Documentation

Setting Up Signon DefaultsUse the Signon Defaults screen to set up signon default information.

• Select SD from the Primary Options Menu to access the Signon Defaults screen.

node.name SIGNON DEFAULTS hh:mm CMD==> CURRENT DEFAULTS: USER ID ==> PASSWORD ==> TRANSPORT==> COMMUNICATION ADDRESS ==>( , ) DESCRIPTION ==> TIMEOUT ==> YES TEMPORARY DATA SET NAME ==> ALLOCATION TYPE ==> PRIMARY SPACE ==> UNIT TYPE ==> SECONDARY SPACE ==> VOL=SER ==> EXTENDED SUBMIT FEATURE ==> UPPER CASE FOR PRINT ==> PRINT FILE DESTINATION ==> PNODE ACCOUNTING DATA ==> SNODE ACCOUNTING DATA ==> DO YOU WANT ALL COMMANDS FOR THIS SESSION TO BE CASE SENSITIVE? ==> NO INITIAL COMMAND ==>

Note: Instead of users individually altering their signon defaults, the IBM Connect:Direct administratorcan define global signon defaults. With this method, users will not be responsible for increasing theirallocation and can also avoid SB37 ABENDs. For more information, refer to Global Signon Defaults inthe IBM Connect:Direct for z/OS Administration Guide.

The INITIAL COMMAND field enables you to bypass the Primary Options Menu and have a designatedcommand screen display automatically at signon. For example, to have the User Information screen(WHO) display automatically at signon, type WHO in the Initial Command field.

Command stacking is allowed. For example, type ADMIN.ST in the INITIAL COMMAND field to branchto the View Type Record (ST) option of the Administration Menu (ADMIN).

By typing your user ID and other information in the SIGNON Defaults panel, you can bypass theSIGNON panel.

SIGNON CommandThe SIGNON command has the following format and associated parameters. The required parametersand keywords are in bold print. Default values for parameters and subparameters are underlined.

Label Command Parameters

(optional) SIGNON NETMAP = network map data set name

CASE= Yes | No

COMADDR= (Port number, IP address | alias name)

ESF= Yes | No

FOLD= Yes | No

NODE= node name

PACCT= 'pnode accounting data'

PRINT= destination of printed output

RECONNECT

SACCT= 'snode accounting data'

SPACE= (CYL | TRK | blk,([prim],[sec]))

Chapter 5. User Guide 553

Label Command Parameters

TMPDD= preallocated data set ddname

TMPDSN= preallocated data set name

TRANSPORT= SNA | TCP | NETmap

UNIT= temporary dsn unit type

USERID= (ID, pswd, newpswd)

VOLSER= volume serial

DESCRIPTION= '30-character string'

TIMEOUT= Yes | No

Parameter Value Description

NETMAP = networkmap data set name

Specifies the network map data set name, which is a 1-44 alphanumericcharacter string with the first character alphabetic. This parameter is required.Ask your administrator for information about completing this value.

If you provide the DMNETMAP DD name in the job stream used with DMBATCH,you are not required to include this parameter with the SIGNON command. Ifyou specify the data set name in both places, the network map data set nameyou specify on the SIGNON command takes precedence.

For the IUI, the network map data set name is specified in the ISPF/PDFPrimary Option Menu as a parameter of the DMISTART program. This data setname is established by your IBM Connect:Direct administrator at installationand is not indicated through the IUI SIGNON command screens.

CASE= Yes | No The CASE parameter determines case sensitivity. It specifies whetherparameters associated with accounting data, user ID, password, and data setname in the commands which follow the signon must be case sensitive. Thedefault is No. This parameter is optional.

You can override this designation on a command-by-command basis byadjusting the case sensitivity parameter on the individual command.

554 IBM Connect:Direct for z/OS: Documentation

Parameter Value Description

COMADDR= (Portnumber, IP address |alias name)

Specifies the communications address used in TCP/IP connections to the DTF.This parameter is specified only if the TRANSPORT parameter is set to TCP.

The port number specifies the port number used for TCP/IP communications.This value is the value from the TCP.API.LISTEN initialization parameter of theDTF that you want to sign on to.

The IP address/alias name specifies the IP address or alias name used forTCP/IP communications.

If you use the COMADDR parameter, you must specify both the port numberand IP address/alias name.

If you use alias name or long domain name resolution, you do not need tosupply the IP address in the COMADDR parameter or in the COMMUNICATIONSADDRESS field during Connect:Direct SIGNON. The name resolution featureresolves a valid alias name or long domain name to the matching IP address.

The maximum length of the IP address|alias name variable is 16 characters. Ifyou want to use an LDNS (long domain name system) or an alias name greaterthan 16 characters, the name must be defined in the network map, and theTRANSPORT must be coded as NET.

Note: Allocate the SYSTCPD DD to the TCPDATA file in both the Connect:Directstartup JCL and API session startup JCL when you request domain nameresolution.

ESF= Yes | No Specifies whether the Extended Submit Facility (ESF) is available for the currentsignon. This parameter is optional. The default value is Yes.

The ESF enables you to submit Processes even if the DTF is not active. Whensigning on to a Connect:Direct DTF that is active, but with no VTAM APPLIDavailable, the ESF enables signon to the DTF. When you submit the Process it isenabled and placed in the TCQ as soon as the ESF.WAIT time expires.

ESF is available only for Processes submitted on the local node. You can onlyissue the Connect:Direct SIGNON, SUBMIT, and SIGNOFF commands using theESF; all other Connect:Direct commands are rejected.

CAUTION: If you use the MAXDELAY PROCESS statement keyword,the message SCBI221I MAXDELAY not supported for ESFsubmits, is displayed when the DTF is down and the Process will notsubmit.

FOLD= Yes | No Determines printing upper case control. It specifies whether printed output, anoption of the various SELECT commands, are all uppercase letters. The defaultvalue is No, specifying printed output of uppercase and lowercase letters. Thisparameter is optional.

NODE= node name Specifies the name of the node (DTF) you sign on to. It is the name assigned toa node defined in the network map definitions. This parameter is optional.

PACCT= 'pnodeaccounting data'

Specifies the accounting data for the primary node (PNODE). The maximumlength of the accounting data is 256 characters. If special characters, suchas a space, are part of the accounting data, you must enclose the string insingle quotation marks. Connect:Direct uses this data as a default for eachProcess unless you override it on the SUBMIT command, PROCESS statement,or SUBMIT statement. This parameter is optional.

Chapter 5. User Guide 555

Parameter Value Description

PRINT= destination ofprinted output

Specifies an allocation string that determines the destination of the printedoutput that you request on the various SELECT commands. This parameter isoptional. SYSOUT=A is the default value. An example follows.

'SYSOUT=C DEST=RMT1 FREE=CLOSE RETURN=(DD)'

You must include both FREE=CLOSE and RETURN=(DD) in the string forthis specification. When using the IUI, if you do not specify a destination,Connect:Direct routes the output to the SYSOUT class specified in theinitialization parameters (external to Connect:Direct) under the TSO user ID.If you modify the destination, you need to sign off Connect:Direct after updatingthe field in order for the new destination to be in effect.

RECONNECT Specifies that you can reestablish your VTAM session without having to sign offand sign on again. You can lose a VTAM session due to a link or line failure. Thisparameter is optional. The USERID parameter is the only other parameter thatyou specify with the RECONNECT option.

SACCT= 'snodeaccounting data'

Specifies the accounting data for the secondary node (SNODE). This parameteris optional. The maximum length of the accounting data is 256 characters. Ifspecial characters, such as a space, are part of the accounting data, you mustenclose the string in single quotation marks. Connect:Direct uses this data asa default for each Process unless you override it on the SUBMIT command,PROCESS statement, or SUBMIT statement.

SPACE= (CYL | TRK |blk,([prim],[sec]))

Specifies the temporary data set (TMPDSN) allocation type, primary spaceallocation, and secondary space allocation. This parameter is optional.

The first subparameter is the allocation type. An allocation type of CYL specifiesspace allocation by cylinder. CYL is the default value. An allocation type of TRKspecifies space allocation by track. An allocation type of blk specifies spaceallocation by the average block length of the data. Connect:Direct computes thenumber of tracks to allocate.

The second subparameter, prim, specifies the primary allocation of storage.The default value is 1.

The third subparameter, sec, specifies the secondary allocation of storage. Thedefault value is 1.

TMPDD= preallocateddata set ddname

Specifies the ddname of a user-supplied preallocated data set. The maximumlength is an 8-character alphanumeric string. This parameter is optional. Do notuse both the TMPDD and TMPDSN parameters at the same time in the SIGNONcommand.

556 IBM Connect:Direct for z/OS: Documentation

Parameter Value Description

TMPDSN=preallocated data setname

Specifies the name of a preallocated data set used to receive command resultsthat are printed or displayed. The data set name is a 1-44 alphanumericcharacter string that must conform to z/OS standards for data set names. Thisparameter is optional, and when not specified, Connect:Direct builds a systemtemporary data set. It normally derives the name for the data set based on yourTSO ID. In some cases, this derived data set name violates your facility namingconvention. Use the Signon Defaults screen to override the data set name asneeded.

If you name a data set at signon time, preallocate it with the followingattributes prior to signing on to Connect:Direct (4104 is the minimumBLKSIZE):

DSORG=PS LRECL=4100 RECFM=VBA BLKSIZE=4104

Do not use both the TMPDD and TMPDSN parameters at the same time in theSIGNON command.

TRANSPORT= SNA |TCP | NETmap

Defines the communications protocol to use for the session. This parameter isoptional.

The default value (NETmap) indicates that the protocol defined in the networkmap is used for the session.

A value of SNA tells Connect:Direct to establish the session using SNA. Youmust define the node you are signing on to as an SNA node, or the SIGNONProcess fails.

A value of TCP tells Connect:Direct to establish a TCP/IP session.Connect:Direct uses the communications address specified in the COMADDRparameter (see page 62 for a description of the COMADDR parameter), if thatparameter is specified as part of the SIGNON command. If the COMADDRparameter is not specified, Connect:Direct tries to establish the session usingthe communications address from the network map. If an invalid COMADDRparameter is supplied, Connect:Direct establishes an ESF API session.

UNIT= temporary dsnunit type

Specifies the temporary data set name (TMPDSN) unit type, which must be a1-8 alphanumeric character string defining the unit type for data set allocation.This parameter is optional. If omitted, the operating system defined default forDASD is used by dynamic allocation.

USERID= (ID, pswd,newpswd)

Specifies your signon security information. This parameter is optional.

ID specifies the security ID that Connect:Direct passes to a security exit. It cancontain 1-64 characters of any kind, and is case-sensitive.

pswd specifies the current security password. The security exit uses thisparameter to validate the current security password. It contains 1-64alphanumeric characters, and is case-sensitive.

newpswd specifies the new security password. The security exit uses thisparameter to change the current security password to the new securitypassword. It contains 1-64 alphanumeric characters, and is case-sensitive.

When you attempt a sign on to a remote node, the user ID and passwordinformation must correspond to security procedures at that remote node.

VOLSER= volumeserial

Specifies the temporary data set name (TMPDSN) volume serial number, whichmust be a 1-8 character alphanumeric string defining the volume serial numberfor data set allocation. This parameter is optional.

Chapter 5. User Guide 557

Parameter Value Description

DESCRIPTION= '30-character string'

Describes the API type that is logging on. It is displayed with the SelectTask command. If Connect:Direct cannot determine the API type, thecommunication address is used.

Defaults: DMCHLAPI, DMBATCH, ISPFIUI, CONSOLEUI, ICOUI, CICSUI, andJava Application Interface

TIMEOUT= Yes | No Specifies whether the value specified for the TCP.API.TIMER global initializationparameter applies to this specific user. This parameter is optional. The systemwill only accept changes to this field made by an administrator and onlyfor their own IUI session; all others will be governed by the initializationparameter. The default value is Yes. Do not use the TIMEOUT keyword inDMBATCH.

Using SIGNON through the Batch InterfaceTo use the SIGNON command from the batch interface, perform the following steps:

1. Place the command in the DGADBATC job stream as described in Sample Job Stream to Run the BatchInterface.

2. Submit the job while is running. If you are using the Extended Submit Facility (ESF), the DTF does notneed to be active for the SIGNON command to process.The following example shows a SIGNON command in which the user specifies a pre-allocatedtemporary data set named MYUID1.TEMP.DSN which resides on SYSDA. The accounting data isspecified for the PNODE and SNODE.

SIGNON NETMAP=DALLAS.NETMAP - USERID=(MYUID1,MYPSWD) - PACCT='JOB FOR SYSMAINT, DEPT.27, MARKETING' - SACCT='JOB FOR INVENTRY, DEPT.55, ACCOUNTING' - TMPDSN='MYUID1.TEMP.DSN' - UNIT=SYSDA

See Signing On to Connect:Direct for z/OS for additional examples of the SIGNON command in thebatch interface.

Signing On to the APIThe communication address used to establish a connection to IBM Connect:Direct is determined by theTRANSPORT parameter defined in the SIGNON command. The default for the TRANSPORT parameter isNET (NETMAP) which means that the protocol defined in the NETMAP Adjacent node entry is used. Formore information, see Adjacent Node Definition Examples.

Parameter Value Description

TRANSPORT = NET Default. When TRANSPORT is defined as NET, the sign on process retrieves theAdjacent node entry to determine if the TCPAPI parameter has been defined.If TCPAPI exists, then a TCP connection is attempted using the communicationaddress defined. The communication port number is obtained from the TCPAPIparameter, and if the IP address exists in the TCPAPI parameter, it is also used.If the IP address does not exist in the TCPAPI parameter, it must be obtainedfrom either the Adjacent node or the LDNS parameter. If the TCPAPI does notexist, the APPLID parameter is retrieved and SNA is used as the protocol.

TRANSPORT = SNA When TRANSPORT is defined as SNA, the sign on process retrieves theAdjacent node entry to determine the APPLID parameter, and SNA is used asthe protocol. If the APPLID parameter does not exist, then an ESF SIGNON isperformed.

558 IBM Connect:Direct for z/OS: Documentation

Parameter Value Description

TRANSPORT = TCP When the TRANSPORT is defined as TCP, the communication address mustbe specified on the SIGNON command. For more information, go to the IBMConnect:Direct for z/OS Administration Guide and search for Initializing IBMConnect:Direct without SNA Support.

Adjacent Node Definition ExamplesTo only allow SNA API signons:

/* PNODE=SNODE WITH SNA API SIGNON ONLY */ ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) - APPLIDS=(M1CDI701 M1CDI702 M1CDI703) - )

To only allow TCP API signons using an IPv4 address:

/* PNODE=SNODE WITH TCP API SIGNON ONLY USING IP ADDRESS */ ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,111.222.333.444) - )

To only allow TCP API signons using an IPv6 address:

/* PNODE=SNODE WITH TCP API SIGNON ONLY USING IP ADDRESS */ ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,1111:2222:3333:4444:5555:6666:7777:8888) - )

To only allow TCP API signons using the LDNS parameter:

/* PNODE=SNODE WITH TCP API SIGONON ONLY USING LDNS */ ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,) - LDNS=long.domain.name - )

To allow both SNA and TCP API signons:

/* PNODE=SNODE WITH BOTH SNA AND TCP API SIGNON */ ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,111.222.333.444) - APPLIDS=(M1CDI701 M1CDI702 M1CDI703) - )or/* PNODE=SNODE WITH BOTH SNA AND TCP API SIGNON */ ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) - TCPAPI=(4198,) - LDNS=long.domain.name - APPLIDS=(M1CDI701 M1CDI702 M1CDI703) - )

Signing On to Multiple SessionsUse the SIGNON command to sign on simultaneously to multiple sessions of the DTF. The SIGNONcommand parameters which are valid for the multiple session signon are a subset of the full SIGNONcommand parameters. For more information, see Using SIGNON through the Batch Interface.

Chapter 5. User Guide 559

Master SessionThe first successful SIGNON command establishes the master session. The master session is the activesession until another session is established. Each subsequent signon becomes the active session unlesssessions are swapped using the SWAP NODE command.

Signing on to the master session and signing on to another node under the master session requires twodifferent signons. The parameters specified for the master session signon dictate the environment for allsessions running under the master session.

Non-Master SessionFor a session other than master, you are limited to the following SIGNON command parameters.

Label Command Parameters

(optional) SIGNON NODE= node name

RECONNECT

USERID= (ID, pswd, newpswd)

See Using SIGNON through the Batch Interface for descriptions of these parameters.

SIGNOFF SequenceCarefully control your SIGNOFF command sequence because if you sign off the master session, IBMConnect:Direct signs off all other sessions. If you sign off a non-master session, IBM Connect:Direct onlysigns off that session, and the master session immediately becomes the active session again, regardlessof the order in which the sessions are established. See Sequencing the SIGNON, SWAP NODE, andSIGNOFF Commands for examples of the importance of the sequence of your SIGNOFF commands.

Switching NodesWhen you issue multiple signons, one node can perform one function and another node a differentfunction. The SWAP NODE command enables you to swap from node to node. See Using SWAP NODEthrough the Batch Interface for the SWAP NODE command description and examples.

Using the Batch Interface for Multiple Session SIGNONTo use the multiple session SIGNON command through the batch interface, place your commands in theDGADBATC job stream and submit the job while IBM Connect:Direct is running. If you have the ExtendedSubmit Facility (ESF) available, the DTF does not need to be running to submit the job.

See the examples in Sequencing the SIGNON, SWAP NODE, and SIGNOFF Commands for job streamsthat issue SIGNON, SWAP NODE, and SIGNOFF commands and an explanation of the significance of thecommand sequence in the job stream.

Using the IUI Multiple Session SIGNON CommandTo access the Multiple Session Signon screen, select MS from the Primary Options Menu.

560 IBM Connect:Direct for z/OS: Documentation

node.name hh:mm CMD ==> yyyy.mm.dd yyyy.ddd MULTIPLE SESSION SIGNON USER ID ==> USER01 PASSWORD ==> NEW PASS ==> NODE NAME ==> TRANSPORT ==> NET COMMUNICATION ADDRESS ==>( , ) DESCRIPTION ==> RECONNECT ==> N (Y OR N. TO THE *ACTIVE* NODE AFTER A SESSION FAILURE) PNODE ACCOUNTING DATA ==> SNODE ACCOUNTING DATA ==> DO YOU WANT ALL COMMANDS FOR THIS SESSION TO BE CASE SENSITIVE? ==> NO

The Multiple Session Signon screen enables you to sign on to more than one node during a singleISPF/PDF session. The APPLIDS value in the network map Adjacent Node definition determines themaximum number of sessions that IBM Connect:Direct is allowed on one DTF. Each signon uses anadditional VTAM APPLID.

See “SIGNON Command” on page 553 for field descriptions, or press the PF1 key for Help.

Swap Node CommandThe SWAP NODE command enables you to swap to another node when you are signed on to more thanone node at a time. Use the SWAP NODE command to specify which node a command is issued to.

The SWAP NODE command has the following format and associated parameter:

Label Command Parameters

(optional) SWAP NODE node name

The only parameter for the SWAP NODE command is node name, which specifies which node to swap to ina multiple session environment. The node name is the name assigned to the LOCAL.NODE field defined inthe network map definitions.

Using SWAP NODE through the IUIYou can use the Swap/Display User Sessions screen to swap to another node or delete (signoff) anothernode.

1. Select option SW from the Primary Options Menu to access the SWAP/DISPLAY User Sessions screen.The screen displays all user sessions for this ISPF/PDF session.

----------------------SWAP/DISPLAY USER SESSIONS------- Row 1 to 2 of 2 ==> SCROLL ===> PAGE NODE COMMUNICATION ID CURRENT STATUS USERID ---------------------------------------------------------------------- node.name1 applid0 *ACTIVE* *MASTER* **LOCAL* userid2 node.name3 applid1 userid1****************************** Bottom of data *************************

2. Do one of the following:

• To swap sessions, type S in the input field to the left of the node name and press Enter. ACTIVE isdisplayed next to the node name you just selected. To determine which node is currently signed onwhen this field is not displayed, look to the upper left corner of most panels for the display of thenode name.

Chapter 5. User Guide 561

• To delete or sign off a session, type D in the input field to the left of the node name and press Enter.

Note: If you sign off the master session, the first node you signed on, all sessions are lost.

Using SWAP NODE through the Batch InterfaceTo use the SWAP NODE command from the batch interface:

1. Place your commands in the DGADBATC job stream as described in Sample Job Stream to Run theBatch Interface.

2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

For example, the following command swaps you from your current active remote node with a user IDof JONES2 to the local node under the user ID of JONES1:

//SYSIN DD * SIGNON USERID = (JONES1) - NODE = CD.LOCAL SIGNON USERID = (JONES2) - NODE = CD.REMOTE SWAP NODE CD.LOCAL SELECT NETMAP WHERE(NODE=CD.LOCAL) SIGNOFF SIGNOFF/*

Sign Off CommandThe SIGNOFF command terminates a connection to the DTF. If you are using the Extended Submit Facility(ESF), you can submit the SIGNOFF command even though the DTF is inactive.

The SIGNOFF command has the following format. No associated parameters are available.

Label Command Parameters

(optional) SIGNOFF

Using SIGNOFF Through the IUIThe following table identifies how to SIGNOFF from various locations of the IUI. You must press Enterafter each SIGNOFF command.

SIGNOFF Command Location

SIGNOFF SIGNON screen or the Primary Options Menu

End SIGNON screen or the Primary Options Menu

X SIGNON screen or the Primary Options Menu

=SIGNOFF or =X Command Line

When you sign off IBM Connect:Direct, the system returns you to the ISPF menu.

Follow these rules when you sign off IBM Connect:Direct:

• You must type a SIGNOFF command twice from the command line.

Note: The first SIGNOFF command returns you to the Primary Options menu and the second SIGNOFFcommand returns you to the ISPF menu.

• You only need to sign off once from the SIGNON screen or the Primary Options Menu.

562 IBM Connect:Direct for z/OS: Documentation

Using SIGNOFF through the Batch InterfaceTo use the SIGNOFF command from the batch interface, perform the following steps:

1. Place your commands in the DGADBATC job stream as described in “Sample job stream to run thebatch interface” on page 525.

2. Submit the job while IBM Connect:Direct is running. If you have the Extended Submit Facility (ESF)available, the DTF does not need to be running in order for the SIGNOFF command to function.

3. Verify your results.

The following example shows a SIGNON command followed by a SIGNOFF command.

SIGNON USERID=(MYUID1,MYPSWD) NETMAP=NETMAP.NAMESIGNOFF

See the examples in Sequencing the SIGNON, SWAP NODE, and SIGNOFF Commands for moreexamples of the SIGNOFF command used with the Multiple Session Signon feature and the SWAPcommand.

Sequencing the SIGNON, SWAP NODE, and SIGNOFF CommandsWhen you issue SIGNON, SWAP NODE, and SIGNOFF commands, the sequence in which you issue thesecommands is important, as shown in the following examples.

Example 1: Terminating Two Sessions with One SIGNOFF CommandThe following example shows a DGADBATC SIGNON to two different nodes and the use of the SWAPNODE command. The SIGNOFF command in this example causes IBM Connect:Direct to terminate bothsessions, because the active session at signoff is the master session.

/* NETMAP = CD.NETMAP, BOSTON IS ACTIVE (MASTER) */ SIGNON USERID=(SAM) NODE=CD.BOSTON/* SIGN ON TO JERSEY */ SIGNON USERID=(SAM) NODE=CD.JERSEY/* SUBMIT COPY ON JERSEY */ SUB PROC=COPY1/* SWAP TO BOSTON */ SWAP NODE CD.BOSTON/* SUBMIT COPY ON BOSTON */ SUB PROC=COPY1/* SIGN OFF BOTH NODES (terminating master session)*/ SIGNOFF

Example 2: Terminating a Master Session with the SIGNOFF CommandIn the following example, the first SIGNOFF command terminates the CD.NEWYORK node because it isthe last SIGNON command issued. The second SIGNOFF command terminates both the CD.JERSEY andCD.BOSTON nodes because the first SIGNOFF command made the master session the active session andsigning off the master session signs off all other sessions.

/* NETMAP = CD.NETMAP, BOSTON IS ACTIVE (MASTER */ SIGNON USERID=(SAM) NODE=CD.BOSTON/* SIGN ON TO JERSEY */ SIGNON USERID=(SAM) NODE=CD.JERSEY/* SIGN ON TO NEWYORK */ SIGNON USERID=(SAM) NODE=CD.NEWYORK/* BOSTON IS ACTIVE AFTER SIGNOFF TO CD.NEWYORK */ SIGNOFF/* SIGN OFF ALL SESSIONS (terminating master session) */ SIGNOFF

Chapter 5. User Guide 563

Example 3: Terminating a Non-Master Session with the SIGNOFF CommandThe following example illustrates that whenever a SIGNOFF command is issued to a non-master session,the master session automatically becomes active again regardless of the order in which the nodes aresigned on.

If you try to swap to a node that is already active, the SWAP NODE command is ignored. The USERID (orany other user ID specified) must be a user record in the IBM Connect:Direct authorization file or a validID for the security subsystem in use, to sign on to the node.

/* NETMAP = CD.NETMAP, BOSTON IS ACTIVE (MASTER) */ SIGNON USERID=(SAM) NODE=CD.BOSTON/* SIGN ON TO JERSEY */ SIGNON USERID=(SAM) NODE=CD.JERSEY/* SIGN ON TO NEWYORK */ SIGNON USERID=(SAM) NODE=CD.NEWYORK/* NEWYORK ACTIVE */ SIGNOFF/* SIGN ON TO JERSEY */ SWAP NODE CD.JERSEY/* JERSEY ACTIVE */ SIGNOFF/* SIGN OFF ALL SESSIONS */ SIGNOFF

Building, Modifying, and Submitting ProcessesYou can construct and submit Processes for execution in several ways, depending upon the userinterfaces available on your operating environment. These IBM Connect:Direct user interfaces include:

• Interactive User Interface (IUI)• Connect:Direct Browser User Interface• Sterling Connect:Direct File Agent• Batch interface

User-written programs issued through the IBM Connect:Direct Application Program Interface (API)

For more information about monitoring and manipulating your submitted Processes, see ControllingProcesses with Commands.

Note: The maximum size allowed for a Process is 1 MB.

You can also use the Connect:Direct Browser User Interface to perform some Connect:Direct for z/OSprocedures.

The following steps describe how a Process executes:

1. You submit a Process.

You create and submit a new Process or submit a predefined Process from a IBM Connect:DirectProcess library.

2. The parser checks the syntax of the Process.3. The Process is queued for execution and the submit message is issued

If the Process passes syntax checking, it is placed in a work queue based on Process parameters, suchas priority, class, and start time.

IBM Connect:Direct work queues are referred to as the Transmission Control Queue (TCQ) or theProcess queue. A Process can have one of the following queue states in the TCQ:

State Description

EXECUTION Indicates that the Process is executing.

WAIT Indicates that the Process is waiting until a connection is established or available.

564 IBM Connect:Direct for z/OS: Documentation

State Description

HOLD Indicates that the Process is held on the queue until released by an operator or theSNODE connects with a request for held work.

TIMER Indicates that the Process is submitted to execute at the user-specified time or date.

PROCESSRETENTION

Indicates the process has completed and would have been deleted, butPROCESS.RETENTION=YES was specified in the INITPARMs. The process can onlybe viewed or deleted.

You can manipulate any Process in the TCQ with various IBM Connect:Direct commands that aredescribed in the next chapter.

A message indicating that the Process submitted successfully is returned when the Process is placedin the TCQ.

4. The Process is queued for execution and the submit message is issued.

You can manipulate any Process in the TCQ with various IBM Connect:Direct commands that aredescribed in the next chapter.

A message indicating that the Process submitted successfully is returned when the Process is placedin the TCQ.

5. IBM Connect:Direct finds an available connection and Process execution begins. The Process isselected for execution based on Process parameters and the availability of the remote node.

Process RoutingThe RETAIN, HOLD, and STARTT parameters route Processes as described in the following table:

Parameters Queue Comments

None Wait Process remains on the Wait queue until IBM Connect:Direct can starta session with the SNODE at which time it moves to the Executionqueue.

RETAIN=INITIAL Hold Process automatically executes each time IBM Connect:Direct isinitialized with TCQ=WARM.

RETAIN=YES Hold A copy of the Process is kept in the Hold queue after it has executed.The Process does not execute again until it is released by a CHANGEPROCESS command.

HOLD=YES Hold Process remains in the Hold queue until someone releases theProcess.

HOLD=CALL Hold Process is automatically moved from the Hold queue to the Wait queuewhen the SNODE contacts the node on which the Process resides.

STARTT Timer When the scheduled time and date arrive, the Process is put on thewait queue and is available for execution.

RETAIN=INITIAL is useful for Processes that contact other IBM Connect:Direct nodes each time IBMConnect:Direct completes initialization. This action causes any work queued on the remote node forthe local node to begin. The DGAPHTBT sample Process allows you to test if IBM Connect:Direct isrunning on a SNODE without actually running a Process on the node. For more information, go to the IBMConnect:Direct for z/OS Administration Guide, search for Maintaining the Network, and read the note onthe DGAPHTBT Process.

You can use RETAIN=YES combined with STARTT to run a Process at a periodic interval. For example,RETAIN=YES and STARTT=(Tuesday, 3pm) starts the Process every Tuesday at 3 pm; RETAIN=YES andSTARTT=(,12:00) starts the Process each day at noon.

Chapter 5. User Guide 565

Note: The RETAIN process parameter has no relationship to the PROCESS.RETENTION initializationparameter.

The Timer queue is also used for session retry and file allocation retry based on IBM Connect:Directinitialization parameters specified by a particular installation. When retry limits are exhausted, theProcess is moved to the Hold queue with a WC (hold queue, waiting connection) status for session retry.

Note: For allocation failures to be requeued, you must set the REQUEUE initialization parameter to YES sothat the Process is placed in the HO RA (HO = Held by Operator, RA = Held for Restart Due to AllocationError) queue.

Process QueuingWhen you submit a Process, IBM Connect:Direct puts the Process in a logical queue based on the Processstatement routing parameters on Process Routing.

IBM Connect:Direct selects Processes in a first-in first-out manner for execution within Process classand priority as sessions are available. The following section describes in detail how IBM Connect:Directselects Processes for execution.

Process SelectionIBM Connect:Direct uses the parallel sessions capability so that multiple Processes can executesimultaneously between any two IBM Connect:Direct nodes. Process selection for each parallel session isbased on a class that the user specifies on a Process.

Note: Parallel sessions support requires you to specify PARSESS=YES in the VTAM application definitionfor both nodes. If two nodes have differing values for parallel sessions, transfers are limited by themaximum number of sessions in the ADJACENT.NODE definition on the node where the Process issubmitted. For TCP/IP connections, IBM Connect:Direct manages the parallel sessions and providesmultiple connections between the two TCP/IP partners.

You define the maximum number of sessions between two nodes in the network map. Because eachsession has a corresponding class value, the maximum number of sessions and maximum number ofclasses are equal. Selection of a Process for execution in a given node is based on Process priority(the PRTY parameter of the Process statement) within session class. User-specified class values allow aProcess to execute on the session having the matching class value or on sessions with higher class values.The default class is the value specified in the IBM Connect:Direct network map.

When one Process completes, IBM Connect:Direct selects another Process (if any) to run on the availablesession. IBM Connect:Direct searches until it finds the first Process with a class eligible to execute on theavailable session.

A typical use for classes is to define critical Processes with low class values so that more sessions areavailable for their execution. You can specify higher class numbers for time-consuming Processes; thisenables sessions with corresponding lower class numbers to become available more frequently.

Intelligent Session RetryThe Intelligent Session Retry feature provides the ability to manage session retries when a connection toa specific node is down so that all Processes are not retried at the same time. This feature makes theexisting connection retry facility more efficient by reducing the extra processing overhead created wheneach IBM Connect:Direct Process retries the connection independently.

When multiple Processes are submitted for a specific node that is down, the Processes all initially attemptto connect. When this fails, the first Process submitted to this node continues to retry until MAXRETRIESis exceeded. The other Processes to this node are moved to the Hold (HO) queue with a RH (held for retry)status and are not retried. When MAXRETRIES is exceeded for the first Process, it is moved to the Hold(HO) queue with a WC (waiting connection) status for session retry.

After the first Process is moved to HO WC status, it can be restarted by one of the following ways:

566 IBM Connect:Direct for z/OS: Documentation

• You can manually release the Process causing it to be retried until a connection is made orMAXRETRIES is exceeded, when it will return to HO WC status

• Another Process is submitted to this same node, causing the Process in HO WC status to be retried untileither a connection is made or MAXRETRIES is exceeded, returning it to HO WC status

• The SNODE initiates communication with the PNODE, causing the Process in the HO WC status to bereleased

When the first Process in HO WC status connects and is released, this causes the other Processes beingheld in HO RH status to be released serially. Therefore, only one Process going to an inactive node willretry until the connection is made resulting in less overhead, since multiple Processes going to the samenode are not all attempting to retry at the same time. This also reduces the number of statistic recordswhich would be produced for multiple retries.

Note: The node name used by the Intelligent Retry feature is the specific name used for the SNODEparameter. This means that if the SNODE is known by more than one node name or TCPNAME value, onlythose in the queue waiting with that value will be recognized for release.

Process Execution ExampleIn the following example, IBM Connect:Direct is running. Seven Processes are submitted to the TCQon NODE.A to execute on NODE.B. All of the submitted Processes are ready to run. In addition, allProcesses have a user-specified class value and the same priority. (Class determines which session IBMConnect:Direct selects to run. Class values allow a Process to execute on a session with a matching classvalue or on sessions with higher class values.)

This site configuration enables up to four sessions to run between NODE.A and NODE.B. Each sessionbetween NODE.A and NODE.B has its own unique class number. IBM Connect:Direct executes in thefollowing order:

1. NODE.A simultaneously starts four sessions, as in the following figure. Processes are displayed in thesame order they appear in the queue. Because the user-specified class of PROCA and PROCB is 1, theycan run on the class 2, 3, or 4 sessions, if needed.

2. PROCB completes execution, making a session available. IBM Connect:Direct looks through the TCQfor the first eligible Process for that session. PROCG is the next Process available to run on the class 2session because all other Processes have a class value higher than 2.

Chapter 5. User Guide 567

3. PROCA, PROCG, and PROCD complete execution. PROCE begins executing in the class 3 session andPROCC begins executing in the class 4 session. The class 1 and class 2 sessions cannot be usedbecause the only Process remaining in the queue (PROCF) is class 4. PROCF must wait for an availableclass 4 session.

4. PROCH and PROCI are submitted. PROCF continues to wait, because it can only run in a class 4session.

568 IBM Connect:Direct for z/OS: Documentation

5. PROCE completes. PROCF is still waiting for PROCC to complete. If another Process is submitted forclass 1, 2, or 3, it can use the available class 3 session.

.

Chapter 5. User Guide 569

Process Management in a IBM Connect:Direct/PlexIn a IBM Connect:Direct/Plex, the IBM Connect:Direct Manager uses a set of Process management rulesto schedule Processes to IBM Connect:Direct Servers. These rules are applied in the following order:

1. The IBM Connect:Direct Manager first checks if the remote node is running a IBM Connect:Directrelease that supports multiple servers. If the remote node does not support multiple servers, theIBM Connect:Direct Manager schedules all Processes to the IBM Connect:Direct Server that is alreadyrunning a Process with this node, and Process management does not occur. If the node supportsmultiple servers, the IBM Connect:Direct Manager continues with the Process management rules thatfollow.

2. The IBM Connect:Direct Manager determines which IBM Connect:Direct Servers on the remote nodecan run the Process, based on the PLEXCLASS of the IBM Connect:Direct Server and the Process, andthe current transport support in the IBM Connect:Direct Server.

3. The IBM Connect:Direct Manager then determines which IBM Connect:Direct Server from step 2 hasthe lowest workload. The current Process workload of each IBM Connect:Direct Server is determinedby dividing the number of active Processes on the server by its MAXPROCESS initialization parametervalue.

4. If two or more IBM Connect:Direct Servers have the lowest workload, the Process is sent to theIBM Connect:Direct Server that has the earliest last scheduled time (the time of day that the IBMConnect:Direct Server Process is scheduled).

Note: If a IBM Connect:Direct/Plex communicates with an external IBM Connect:Direct system, theexternal system must send work to the IBM Connect:Direct Manager to balance Process workloads in theIBM Connect:Direct/Plex. If an external IBM Connect:Direct system communicates directly with a IBMConnect:Direct Server, work from the external system is not distributed using Process management; theIBM Connect:Direct Server simply does the requested work. However, the IBM Connect:Direct Server stillinforms the IBM Connect:Direct Manager that it is processing work, so the IBM Connect:Direct Managercan continue to correctly balance Process workload in the IBM Connect:Direct/Plex.

Also, to perform workload balancing with an external IBM Connect:Direct system when the IBMConnect:Direct/Plex is the SNODE, the external system must be a IBM Connect:Direct version thatsupports the IBM Connect:Direct/Plex environment. You do not have to configure the external systemas a IBM Connect:Direct/Plex. Configure it to communicate directly with the IBM Connect:Direct Manager.

Example: Process Management StepsFollowing is an example of the steps in Process management.

1. A IBM Connect:Direct/Plex consists of a IBM Connect:Direct Manager and two IBM Connect:DirectServers. Both IBM Connect:Direct Servers can process the same PLEXCLASS (CLASS1).

570 IBM Connect:Direct for z/OS: Documentation

2. The IBM Connect:Direct Manager receives a new Process. After determining that both IBMConnect:Direct Servers support the PLEXCLASS required to run the Process, the IBM Connect:DirectManager determines which IBM Connect:Direct Server has the lowest workload.

In this case, SERVER2 has the lowest workload; it has one active Process out of a maximum of four.The IBM Connect:Direct Manager routes the Process to SERVER2, and the last scheduled time ofSERVER2 is updated to the current time.

3. The IBM Connect:Direct Manager has another Process to schedule. SERVER1 and SERVER2 havethe same workload. However, the last Process is scheduled to SERVER2, so the IBM Connect:DirectManager routes the new Process to SERVER1.

Chapter 5. User Guide 571

SUBMIT CommandThe SUBMIT command enables you to submit a Process to the TCQ for execution. Parameters you specifyon the SUBMIT command override any corresponding parameters specified in the Process itself.

Note: If you are using the Extended Submit Facility (ESF), you can use the SUBMIT command to submitProcesses to the TCQ, even if the DTF is inactive.

The SUBMIT command has the following format. The Label is optional.

Label SUBmit Parameters and Subparameters

The SUBMIT command has the following parameters. The required parameters and keywords are in boldprint. Default values for parameters and subparameters are underlined.

572 IBM Connect:Direct for z/OS: Documentation

Label Command Parameters

(optional) SUBmit PROC= memberorDSN= dsn | dsn(member)

CASE= Yes | NoCLASS= nDEBUG= trace settings for this ProcessFASP= No | SSPFASP.BANDWIDTH=nnn | nM | nG FASP.FILESIZE.THRESHOLD=nnn | nM | nGFASP.POLICY=FAIR|HIGH|LOW|FIXEDHOLD= Yes | No | CallMAXDELAY= [unlimited | queued | 0 | hh:mm:ss]NEWNAME= newnameNOTIFY= %USER | userPACCT= 'pnode accounting data'PLEXCLASS= (pnode class, snode class)PNODE= primary node namePNODEID= (ID, pswd, newpswd)PRTY= nREQUEUE= Yes | NoRETAIN= Yes | No | InitialSACCT= 'snode accounting data'SNODE= secondary node name | TCPNAME=tcpvalue;portSNODEID= (ID, pswd, newpswd)&symbolic 1= variable string 1 &symbolic 2= variable string 2 ...=... &symbolic N= variable string N

The following tables describes SUBMIT command parameters:

Parameter Description

PROC = member Specifies the Process Library member name. This name is themember of the PUBLIB which contains the Process you aresubmitting. The member name is a 1-8 character alphanumericstring, with the first character alphabetic. This parameter isrequired if the Process resides in the IBM Connect:Direct PUBLIB.

The IBM Connect:Direct PUBLIB PDS is specified by theDMPUBLIB ddname allocated to the TSO session or specified inthe batch job stream.

DSN = dsn | dsn (member) Specifies the data set name or the name of the member of aPDS that contains the Process if the Process is not in the IBMConnect:Direct PUBLIB. This parameter is required if the Processdoes not reside in the IBM Connect:Direct PUBLIB.

dsn is the data set name of a sequential file that contains theProcess.

dsn(member) specifies the PDS name and member name (inparentheses) that contains the Process. Specify either PROC orDSN; do not specify both.

Chapter 5. User Guide 573

Parameter Description

CASE = Yes | No Specifies whether parameters associated with accounting data,user ID, password, and data set name in the command and in theProcess are to be case sensitive. This parameter is optional.

CLASS = n Determines the node-to-node session on which a Process canexecute. See your IBM Connect:Direct administrator for whichclass to specify. The range is 1-255. This parameter is optional.

DEBUG= trace Specifies the 8-position trace setting for this Process. Thisparameter enables you to specify a part trace for a particularProcess. For more information see Debug Settings in the IBMConnect:Direct for z/OS Administration Guide.

HOLD = No | Yes | Call Specifies whether or not the Processes are placed in the holdqueue. This parameter is optional.

No specifies that IBM Connect:Direct does not place the Processin the hold queue, but places it in the WAIT for execution queue(EX). HOLD=NO is the default.

Yes specifies that the Process remains in the hold queue untileither a CHANGE PROCESS command releases the Process or aDELETE PROCESS command deletes the Process.

When HOLD=YES and you specify a value for the STARTTparameter, IBM Connect:Direct places the Process submitted inthe hold queue.

Note: When RETAIN=Y, IBM Connect:Direct ignores the HOLDparameter.

Call specifies that IBM Connect:Direct is to place the Process inthe hold queue until a session is established with the specifiedSNODE. This session is established by either another Processstarting on the PNODE destined for the same SNODE or theSNODE contacting the PNODE. For example, a Process submittedwith HOLD=NO establishes a session and causes execution of anyProcesses residing on the SNODE destined for this node that aresubmitted with HOLD=CALL.

Note: To support dial-up connections from Connect:Direct forMicrosoft Windows platforms and release Processes serially,define the SNODE using a TCP/IP address of 0.0.0.0 (a null IPaddress). You may let the port number default since it will beresolved at connection time. Processes submitted to such nodeswill default to HOLD=CALL status and can only be released bya NULL or ENABLE process from Connect:Direct for MicrosoftWindows. Releasing Processes to such nodes will immediatelycause them to return to HOLD=CALL status without executingbecause the connection cannot be resolved. Processes initiatedby such nodes will execute normally, but will not release theHOLD=CALL Processes. Checkpoint restart is supported for suchnodes.

574 IBM Connect:Direct for z/OS: Documentation

Parameter Description

MAXDELAY = [unlimited | queued | 0 |hh:mm:ss]

Indicates that the submit command waits until the submittedProcess completes execution or the specified time intervalexpires. This parameter is optional. Do not use MAXDELAY fora submit within a Process—use only in SUBMIT commands.

Note: If the Process does not complete within the time intervalspecified by queued or hh:mm:ss, the API returns SSPA006I,RC=4 and DGADBATC terminates with RC=48 (x'30').

unlimited specifies that the submit command waits until theProcess completes execution. If MAXDELAY is coded and noparameters are specified then in this case MAXDELAY will defaultto unlimited.

queued specifies that the submit command waits until theProcess completes or 30 minutes, whichever occurs first.

0 specifies that the submit command attempts to start a sessionfor the submitted Process to execute on immediately. If IBMConnect:Direct cannot establish a session, after all retries areexhausted, the Process is flushed and the submit command failswith the error SVTM118I RC=52(x'34').

Note: If IBM Connect:Direct cannot establish a session afterall retries are exhausted due to all available sessions on theremote node being in use, that is, when session attempts failwith error SVTM080I SESSION (nnn) REJECTED pname (pnum)SNODE=remote.node, the Process is flushed and the submitcommand fails with the error SVTM118I RC=12(x'0C').

MAXDELAY=0 Processes will not use the intelligent retry feature.When a transfer to a remode node times out and retries,subsequent transfers to the same remote node will also time outand retry rather than being added to the wait queue.

hh:mm:ss specifies that the submit command waits for aninterval no longer than the specified hours, minutes, and secondsor until the Process completes, whichever occurs first.

NEWNAME = newname Specifies the new name of the Process. The default is the label onthe Process statement. This parameter is optional.

NOTIFY = %USER | user ID Specifies the user ID to receive Process completion messages.This parameter is optional.

%USER specifies that the user who submitted the Processreceives the completion messages, if the IBM Connect:Direct userID that the user is currently logged on with is the same as the TSOuser ID. If the IBM Connect:Direct user ID is different from theTSO user ID, the TSO user is not notified but the ID to which IBMConnect:Direct is logged on will be notified.

user ID specifies the TSO user ID that receives Processcompletion messages.

Note: The NOTIFY capability is not supported across z/OS imagesin the sysplex environment. IBM Connect:Direct cannot sendProcess completion messages across z/OS images in a sysplex.

Chapter 5. User Guide 575

Parameter Description

PACCT = 'pnode accounting data' Accounting data for the PNODE. The maximum length of theaccounting data is 256 characters. If special characters are partof the accounting data, you must enclose the string in singlequotation marks. This parameter is optional.

This data overrides any accounting data specified on the SIGNONcommand and any accounting data specified in the Processstatement of the submitted Process.

PLEXCLASS = (pnode class, snode class) Specifies the class that directs the Process to only certain serversin a IBM Connect:Direct/Plex. This parameter is only used in aIBM Connect:Direct/Plex and is optional.

You can designate each server in a IBM Connect:Direct/Plex to support only certain PLEXCLASSes through theCDPLEX.PLEXCLASSES initialization parameter. You can then limitProcesses to only those servers by specifying the PLEXCLASS inthe Process definition.

The pnode class controls which IBM Connect:Direct Serverruns the Process. The snode class controls what other nodeis used with the Process. The pnode class and snode classare each 1-8 characters long. An asterisk (*) indicates thatthe Process runs on any server with an asterisk designatedin the CDPLEX.PLEXCLASSES initialization parameter. If you donot specify a PLEXCLASS, the network map is checked for adefault PLEXCLASS. If the network map does not specify a defaultPLEXCLASS, then an asterisk is used as the default.

If a Process must run on a specific IBM Connect:Direct Server,specify the IBM Connect:Direct Server name in this field. TheProcess only runs on that server.

PNODE = primary node name Specifies the primary node of the Process. This parameter isoptional.

primary node name is a 1-16 alphanumeric character namedefined in the network map. You can express the name inalphanumerics or nationals (@#$) with embedded periods.

The node to which you submit the Process is always the PNODE.You do not need to specify this parameter. It defaults to the nameof the node submitting the Process. PNODE is for documentationpurposes only.

PNODEID = (ID, pswd, newpswd) Specifies security user IDs and security passwords at the PNODE.This parameter is optional. ID specifies the security ID that IBMConnect:Direct passes to a security exit for validations on thePNODE side of the Process. The range is 1-64 alphanumericcharacters.

pswd specifies the current security password. The security exituses this parameter to validate the current security password onthe PNODE side of the Process. It can contain 1-64 alphanumericcharacters.

newpswd specifies the new security password. The security exituses this parameter to change the current security passwordto the new security password. The range is 1-64 alphanumericcharacters.

576 IBM Connect:Direct for z/OS: Documentation

Parameter Description

PRTY = n Specifies the Process priority in the Transmission Control Queue.High numbers indicate high priorities; low numbers indicate lowpriorities. IBM Connect:Direct uses this priority only for Processselection; it does not affect the priority during transmission. Thedefault is defined during your installation. The range is from 0-15.This parameter is optional.

REQUEUE = Yes | No Specifies whether IBM Connect:Direct requeues a COPY step if anABEND occurs during processing. This parameter is optional.

Yes places the requeued Process in the HOLD queue with a statusof HELD IN ERROR (HE). You can then take corrective action andrestart the Process at the step that failed. Note that you mustexplicitly release the Process from the HOLD queue when thestatus is HELD IN ERROR (HE).

No specifies the failing copy step is not requeued if it fails withan ABEND (such as X37). The remaining steps in the Process areallowed to execute. The default is NO. The value REQUEUE=Nois forced in the case of a submit containing the MAXDELAYparameter.

RETAIN = Yes | No | Initial Specifies whether or not IBM Connect:Direct keeps a copy of theProcess in the HOLD queue after the Process has executed. Thisparameter is optional.

Yes keeps a copy of this Process in the HOLD queue after theProcess executes. The copy of the Process does not executeuntil you release it through a CHANGE Process command. Ifyou specify RETAIN=YES, IBM Connect:Direct automatically holdsthe Process until you release it, unless you include the STARTTparameter in your Process. Use RETAIN in conjunction withSTARTT to cause a Process to run repeatedly at a given time eachday.

No specifies that IBM Connect:Direct is to delete the Processafter execution. The default value for RETAIN is NO. The valueRETAIN=No is forced in the case of a submit containing theMAXDELAY parameter.

Initial specifies that IBM Connect:Direct is to execute the Processevery time IBM Connect:Direct is initialized.

Note: Do not code the STARTT parameter with the RETAIN=Iparameter.

SACCT = 'snode accounting data' Specifies the accounting data for the SNODE. The maximumlength of the accounting data is 256 characters. If you includespecial characters with the accounting data, you must enclose thestring in single quotation marks. This parameter is optional.

This data overrides any accounting data specified on the SIGNONcommand and any accounting data specified in the Processstatement.

Chapter 5. User Guide 577

Parameter Description

SNODE = secondary node | SNODE=TCPNAME = tcpvalue;port

Specifies the secondary node used in this Process. Thisparameter is optional.

secondary node name is a 1-16 alphanumeric name that isdefined in the network map.

The following characters are allowed:

A-Z, 0-9, !, @, #, $, %, &, {, }, +, -, ^

Connect:Direct for z/OS does not accept the following charactersfor the SNODE:

(, ) =, \, “, ‘, <, >, |, ||

Use SNODE=TCPNAME=tcpvalue to specify TCP/IP connectionsthat are not defined in the network map. tcpvalue can be aDNS name up to 255 characters or a 15-character IPv4 or 39-character IPv6 TCP/IP address.

port is the TCP/IP port number. It can be up to 5 characters long.

Note: If the TCPNAME keyword is used and the port is notspecified, the TCP.IP.DEFAULT entry is used if the NODE is notdefined in the Netmap.

SNODEID = (ID, pswd, newpswd) Specifies security user IDs and security passwords at the SNODE.

ID specifies the security ID that IBM Connect:Direct passes to asecurity exit for validation on the SNODE side of the Process. Itcan contain 1-64 alphanumeric characters.

pswd specifies the current security password. The securityexit uses this parameter to validate the current securitypassword on the SNODE side of the Process. It can contain1-64 alphanumeric characters. In the case where the SNODEcan Process a PassTicket password, the PNODE generates aPassTicket when only a SNODE user ID override is specified. Theactual generation is contingent upon the information shared in thePNODE Authorization File and the option that generates the stage2 security exit. The IBM Connect:Direct for z/OS AdministrationGuide contains details for the Authorization File and stage 2security exit characteristics.

newpswd specifies the new security password. The security exituses this parameter to change the current security passwordto the new security password. The range is 1-64 alphanumericcharacters.

578 IBM Connect:Direct for z/OS: Documentation

Parameter Description

STARTT = ([date | day] [,hh:mm:ssXM]) Specifies that IBM Connect:Direct not execute the Process untila specified date or time. The date, day, and time are positionalparameters. If you do not specify the date or day, place a commabefore the time. This parameter is optional.

Note: Do not code STARTT with RETAIN=INITIAL.

date specifies the date to execute the Process. You can specifythe day (dd), month (mm), and year (yy for 2-digit year andyyyy for 4-digit year). You can use periods or backslashes (/)to separate the components of a date value. You can omit theseparators only for transfers between mainframe nodes. Useseparators to guarantee transfers between all platforms.

You can use the following date formats, according to which dateorder is specified in the DATEFORM initialization parameter:

• DATEFORM=MDY specifies the date format as mm/dd/yy,mm/dd/yyyy, mm.dd.yy, or mm.dd.yyyy

• DATEFORM=DMY specifies the date format as dd/mm/yy,dd/mm/yyyy, dd.mm.yy, or dd.mm.yyyy

• DATEFORM=YMD specifies the date format as yy/mm/dd,yyyy/mm/dd, yy.mm.dd, or yyyy.mm.dd

• DATEFORM=YDM specifies the date format as yy/dd/mm,yyyy/dd/mm, yy.dd.mm, or yyyy.dd.mm

Valid Julian dates formats are yyddd, yyyyddd, yy/ddd, yyyy/ddd,yy.ddd, or yyyy.ddd

If you specify a date without a time, the time defaults to 00:00.

If RETAIN=YES, you cannot specify a date in the STARTTparameter.

Chapter 5. User Guide 579

Parameter Description

STARTT = ([date | day] [,hh:mm:ssXM])(continued)

day specifies the day of the week that IBM Connect:Direct isto release the Process for execution. Valid names are MOnday,TUesday, WEdnesday, THursday, FRiday, SAturday, and SUnday.You can also specify TODAY, which releases the Process forexecution today, or TOMORROW, which releases the Process forexecution the next day.

If you specify the day of the week with RETAIN=YES, the Processexecutes the same day every week.

If you specify a day without a time, the time defaults to 00:00. Atime of 00:00 means that if you submit a Process on Monday, withMonday as the only STARTT parameter, the Process does not rununtil the following Monday.

hh:mm:ssXM indicates the time of day in hours (hh), minutes(mm), and seconds (ss) that IBM Connect:Direct is to release theProcess. You can set XM to AM or PM, or you can omit it if you areusing a 24-hour clock. You need not specify minutes and seconds.

You can express the time of day using the 24-hour clock or the12-hour clock. If you do not use AM and PM, IBM Connect:Directassumes the 24-hour clock. If you use the 12-hour clock, you canexpress 01:00:00 hours as 1:00A, and 13:00 hours as 1PM. If youuse the 24-hour clock, valid times are 00:00-24:00.

You can also specify NOON, which releases the Process forexecution at noon, or MIDNIGHT, which releases the Process forexecution at midnight.

If you code hh:mm:ssXM with RETAIN=YES, IBM Connect:Directschedules the Process for execution the same time every day.

Note: When you specify both HOLD=YES and a STARTT value, theHOLD specification takes precedence. IBM Connect:Direct placesa Process submitted with HOLD=YES on the hold queue even ifyou specify a start time.

&symbolic 1 = variable string 1 &symbolic 2 = variable string 2...&symbolic N = variable string N

Specifies the default value substituted for the symbolic parameterin the Process. If you use a symbolic in the SUBMIT command, itoverrides any default values you specify in the Process statement.

Specify a null value by immediately following the equal sign witha comma. You must enclose a symbolic parameter containingspecial characters in single quotation marks.

You can set an ampersand (&) symbolic parameter to anothersingle ampersand symbolic parameter that is resolved during thefirst Process submission. Do not use identical symbolic names.The maximum variable string length is 256 characters.

SUBMIT Command ExamplesUse these examples to help you gain a basic understanding of how you can use the SUBMIT command.

Process ExampleThe following example shows the syntax for a Process named PAYROLL.

580 IBM Connect:Direct for z/OS: Documentation

SUBMIT PROC=PAYROLL - HOLD=Y RETAIN=Y - PACCT='1959, DEPT 27' - SACCT='1962, DEPT 24' - CASE=YES

In this example, the SUBMIT command was used to:

• Place the Process (named PAYROLL) in the HOLD queue.• Retain a copy after it is released for execution.• Create case sensitivity for fields associated with accounting data, user ID, password, and data set name

in the SUBMIT command and in the PAYROLL Process.

Symbolic Substitution ExampleIn the following example, IBM Connect:Direct resolves the symbolic &DSN in the Process COPYSEQ uponsubmission:

SUBMIT PROC=COPYSEQ - SNODE=CHICAGO, &DSN=MYFILE

Submitting Processes through the Batch InterfaceTo submit a Process through the batch interface, perform these steps:

1. Place your SUBMIT command in the DGADBATC job stream as described in Introduction to the BatchInterface.

2. Submit the job while IBM Connect:Direct is running.

Note: If the Extended Submit Facility (ESF) is available, the DTF does not need to be running toexecute your command.

3. Verify your results.

Submitting Processes through the IUIThe Interactive User Interface (IUI) enables you to create, edit, and submit Processes using the SB, DF,and CF options available on the PRIMARY OPTIONS MENU.

IUI Submit OptionsThe SB, DF, and CF options available from the IUI enable you to perform the following submit options forProcesses:

Option Description

SB Enables you to submit Processes from the IBM Connect:Direct PUBLIB or a library you specifyon the screen. You can also override certain parameters in the existing Process.

DF Enables you to edit, create, and submit Processes residing in the IBM Connect:Direct PUBLIBor a library you specify on the screen. You edit or create a Process using the ISPF editor.

CF Enables you to dynamically build a COPY Process through fill-in-the-blank panels and submitit.

Validating Processes from the SB, DF, and CF IUI OptionsFrom any of the IUI SUBMIT screens available through the SB, DF, and CF options, you can validate theProcess syntax without submitting the Process, or you can submit the Process, which includes verifyingthe syntax, as explained in the following table:

Chapter 5. User Guide 581

Operation Related Parameter or Command Result

Validate Processsyntax

• Enable VALIDATE ONLY parameter• Issue SUBV command

• The Process is displayed in the VIEWPROCESS screen.

• If the Process is valid, the messageSubmit Process for validation commandwas successful is displayed.

• If the Process is invalid, a messageidentifies the problems in the Process.You can press PF1 for information totroubleshoot the problem.

• You can press PF3 to return to theprimary SB, DF, or CF screen.

Submit Process andvalidate syntax

• Issue SUBMIT or SUB command • If the Process is valid, it is executedand a Process number is displayed forreference.

• If the Process is invalid, a messagedescribes the problem. You can pressPF1 for information to troubleshoot thesyntax errors.

Using the SB IUI Option to Submit a Predefined ProcessThe Interactive User Interface (IUI) enables you to submit predefined Processes using the SB option,which is available from the PRIMARY OPTIONS MENU (see Primary Options Menu). You can submit aProcess from the IBM Connect:Direct PUBLIB or a library you specify and override certain parameters inthe existing Process.

To submit a predefined Process from the IBM Connect:Direct IUI:

1. Select option SB from the Primary Options Menu to display the SUBMIT PROCESS screen.

If you enable the SECURITY OVERRIDE parameter, type the security override information in the IBM Conect:Direct SECURITY OVERRIDE screen. node.name Connect:Direct SECURITY OVERRIDE TIME: hh:mm CMD==> PRIMARY NODE: SECURITY ID: ________________________________________________ PASSWORD : SECONDARY NODE: SECURITY ID: ________________________________________________ PASSWORD :

2. Type the name of the Process to submit.3. Take one of the following actions:

• To submit the Process, press Enter.• To define additional parameters, continue with step 4.

4. Type any additional parameters of your SUBMIT command and press Enter.

For SUBMIT parameter descriptions not included in the following table, press PF1 or see SUBMITCommand.

582 IBM Connect:Direct for z/OS: Documentation

Field Description

TRANSPORT Specifies the method of transport to use for the file transfer.

NETMAP—Causes IBM Connect:Direct to search in the network map for thesending and receiving nodes. If you type a Transport of NETMAP, the SNODEkeyword remains SNODE=secondary node.

TCP—Indicates that the NODE NAME field contains an alias name or an IPaddress. IBM Connect:Direct does not look in the network map for nodeinformation. If you type TCP in the Transport field, the SNODE keywordbecomes SNODE=TCPNAME=tcpvalue.

DNS—Enables you to enter a domain name up to 255 bytes.

SECURITYOVERRIDE

Enables you to override security information such as password and user ID forthe primary and secondary node.

Yes = Enable security overrride.

No = Do not override security information.

VALIDATE ONLY Enables you to validate the Process syntax without submitting the Process.

Yes = Validate without submitting the Process.

No = Do not validate without submitting the Process.

CASE SENSITIVITY Specifies whether parameters associated with accounting data, user ID,password, and data set name in the Submit Process are to be case sensitive.The default is NO, which does not allow mixed case.

5. If you enable the SECURITY OVERRIDE parameter, type the security override information in the IBMConnect:Direct SECURITY OVERRIDE screen.

If you enable the SECURITY OVERRIDE parameter, type the security override information in the IBM Connect:Direct SECURITY OVERRIDE screen. node.name Connect:Direct SECURITY OVERRIDE TIME: hh:mm CMD==> PRIMARY NODE: SECURITY ID: ________________________________________________ PASSWORD : SECONDARY NODE: SECURITY ID: ________________________________________________ PASSWORD :

6. Press Enter to perform one of the following actions:

• Submit the Process. See the table in Operation for the possible results.• View the results of the validate-only operation in the VIEW PROCESS panel, if you enabled the

VALIDATE ONLY parameter. See the table in Operation for the possible results.

CAUTION: Press PF3 to exit the screen from which you submitted the Process. Each time youpress Enter, the Process is submitted.

7. If you performed the validate-only operation, press PF3 to return to the SUBMIT PROCESS screen.

Using the DF IUI Option to Create, Edit, and Submit ProcessesThe Interactive User Interface (IUI) enables you to modify, create, and submit Processes using the DFoption, which is available on the PRIMARY OPTIONS MENU. Using the DF option, you can:

• Modify a Process• Create a new Process• Submit a Process

Chapter 5. User Guide 583

• Copy statement models to create a Process

The IBM Connect:Direct Public Process Library (PUBLIB) contains Process statement models that you canuse as templates for creating IBM Connect:Direct Processes. The DF option enables you to copy Processstatement models, edit them for your environment using the ISPF editor, and. submit Processes residingin the IBM Connect:Direct PUBLIB or in a library you specify.

CAUTION: Do not edit a sample member directly. Keep the source as is, edit a new name, and thencopy the member into the new one. Save as a new name. The SDGAPROC Process library containsalias names that if edited and saved will break the aliases.

The PUBLIB contains commented files and uncommented files. File names of commented files arepreceded by the at sign (@); file names with the pound sign (#) prefix do not include comments.

See Validating Processes from the SB, DF, and CF IUI Options for details about how to validate the syntaxof a Process with and without submitting it.

Modifying and Submitting a Process Using the DF IUI OptionTo modify a Process using the ISPF editor and submit the Process to the DTF:

1. Choose option DF from the Primary Options Menu to display the Connect:Direct PROCESS DEFINITIONscreen.

2. Type the member name of the Process.3. Verify the library location and press Enter.

The PROCESS LIBRARY NAME field is required. If the member is located in the IBM Connect:DirectPUBLIB, type the library name that is displayed in the PUBLIC PROCESS LIB field in the PROCESSLIBRARY NAME field.

4. After IBM Connect:Direct displays the Process in ISPF edit mode, make the desired changes.5. Press PF3 to return to the PROCESS DEFINITION screen.6. Specify case sensitivity. Case sensitivity applies to the SUBMIT command and the Process.7. Take one of the following actions:

• To validate the Process without submitting it, type SUBV and refer to the table in “ValidatingProcesses from the SB, DF, and CF IUI Options” on page 581 for information on the results.

• To submit the Process, type SUBMIT (or SUB) on the command line and press Enter.

Creating and Submitting a New Process Using the DF IUI Option

To create and submit a new Process:

1. Choose option DF from the Primary Options Menu to display the Connect:Direct PROCESS DEFINITIONscreen.

2. Type the member name of the new Process.3. Specify the name of the library where you want to save the new Process and press Enter.

The member location can be your private Process library (PROCESS LIBRARY NAME) or the IBMConnect:Direct PUBLIC PROCESS LIBRARY.

4. After IBM Connect:Direct displays an ISPF editor screen, type your new Process.5. Press PF3 to save the Process in the PROCESS LIBRARY you specified and return to the PROCESS

DEFINITION SCREEN.6. To validate the Process without submitting it, type SUBV on the command line and press Enter. See

the table in “Validating Processes from the SB, DF, and CF IUI Options” on page 581 for informationabout the results.

7. Specify case sensitivity. Case sensitivity applies to the SUBMIT command and the Process.8. To submit the Process, type SUBMIT (or SUB) in the command line and press Enter.

584 IBM Connect:Direct for z/OS: Documentation

Submitting a Process Using the DF IUI Option

To submit a Process to the DTF:

1. Choose option DF from the Primary Options Menu to display the Connect:Direct PROCESSDEFINITION screen.

2. Type SUBMIT (or SUB) on the command line.3. Type the member name of the Process.4. Verify that the library name that contains the member you want to submit is displayed in the PROCESS

LIBRARY NAME field. If the member is located in the IBM Connect:Direct PUBLIB, type the libraryname that is displayed in the PUBLIC PROCESS LIB field in the PROCESS LIBRARY NAME field.

5. Specify case sensitivity. Case sensitivity applies to the SUBMIT command and the Process.6. Press Enter. See the table in “Validating Processes from the SB, DF, and CF IUI Options” on page 581

for information about the results.

Using Statement Models to Create a ProcessTo copy a Process statement model to a new PDS member:

1. Choose option DF from the Primary Options Menu to view the IBM Connect:Direct PROCESSDEFINITION screen.

2. Type the name of the new PDS member.

Note: The PUBLIC PROCESS LIB displays the partitioned data set (PDS) allocated by the signon CLISTor the TSO logon procedure.

3. Type the PROCESS LIBRARY NAME and press Enter.4. Type COPY on the command line at the top of the blank member and press Enter.5. When the ISPF Edit/View-Copy screen is displayed, type the member name of the PROCESS

statement model you want to copy in the DATA SET NAME field and press Enter.

For example, to create your Process, first copy the PROCESS statement. Specify @PROCESS to usecommented models from the PUBLIB, or #PROCESS to use uncommented models in your Process.

6. To add a statement model, type a in the first column of the last line of the new member and pressEnter.

7. Repeat steps 4 through 6 to copy additional statement models into the member following thePROCESS statement.

8. Edit the statement model or models for your environment according to the following guidelines:

• Replace underscores with the appropriate parameter values.• Provide an appropriate Process name in the PROCESS statement.• Delete all lines that are not applicable.• Continuation marks are necessary on all but the last line of each statement model.• You can delete comment lines. They are optional.

9. Press PF3 to save the changes and return to the IBM Connect:Direct PROCESS DEFINITION screen.10. Take one of the following actions:

• To validate the Process without submitting it, type SUBV and press Enter. See the table inOperation for information about the results.

• To submit the Process, type SUBMIT on the command line and press Enter. See the table inOperation for information about the results

Using the CF IUI Option to Generate a COPY ProcessThe CF option of the Interactive User Interface (IUI) enables you to dynamically generate a COPY Processthrough fill-in-the-blank panels and submit it.

Chapter 5. User Guide 585

CAUTION: The Process generated through this option is a one-time only Process and and there areno facilities to save the Process.

The COPY FILE Menu of the CF option displays a series of screens that collect information to generatea SUBMIT PROCESS command. IBM Connect:Direct submits the predefined Process, COPYCF, with theappropriate command parameters and variable substitutions based on your input. You can use fourscreens to create the COPYCF Process:

Screen Name Description

COPY FILE Menu Collects information for the SUBMIT COMMAND parameters, PNODE/SNODEinformation, data compression, and checkpoint information.

Security OverrideMenu

Collects information about user ID, password, and accounting data. This optionalpanel is displayed only if you request it on the first panel.

SENDING FILEMenu

Collects information for the Process variables for the sending file.

RECEIVING FILEMenu

Collects the information for the Process variables for the receiving file.

The following diagram illustrates the relationship of these four screens.

See Validating Processes from the SB, DF, and CF IUI Options for details about how to validate the syntaxof a Process with and without submitting it.

Generating a COPY Process

To generate a COPY Process:

1. Select the CF option from the Primary Options Menu to display the COPY FILE Menu.

586 IBM Connect:Direct for z/OS: Documentation

node.name Connect:Direct Copy File Menu TIME: hh:mmCMD ==>

SENDING ENVIRONMENT: ZOS______ TRANSPORT: NETMAPNODE NAME: CD.NODE1________________________________________________________RECEIVING ENVIRONMENT: ZOS______NODE NAME: CD.NODE2________________________________________________________PROCESS NAME: COPYCF__ SUBMIT MULTI MODE: N (Y, N) CLASS: ___ (NUMERIC) VALIDATE ONLY: NHOLD: Y (Y, N, OR C-CALL) ZFBA: _NOTIFY USER: %USER___________________________________________________________PRIORITY: __ (RANGE: 0 TO 15) FASP: ___REQUEUE: N (Y OR N) FASP Policy: _____RETAIN ON TCQ: N (Y, N, OR I-INITIAL) FASP Bandwidth: ________START DATE: __________ TIME: __________ FASP Filesize: ________CHECKPOINT: ________ (BYTE INTERVAL - NK|NM)DEBUG: ________ (HEXADECIMAL)PLEXCLASS: ________ ________ (PNODE SNODE)COMPRESS: N____ (Y, N, X-EXTENDED, X'XX', OR C'C')EXT COMPRESSION LEVEL: _ WINDOW: __ MEMORY: _OVERRIDE SECURITY: N (Y OR N)

DO YOU WANT VALUES FOR THIS COPY TO BE CASE SENSITIVE?: NO___

2. If necessary, rename the COPYCF Process by typing a name in the PROCESS NAME field.3. For descriptions of SUBMIT parameters not included in the following table, press PF1 or see SUBMIT

Command.

Parameter Name Description

SENDINGENVIRONMENT

Specifies the operating system or platform from which the file is transmitted.The values you place in the Sending Environment and Node Name fieldsdetermine which Sending File screen is displayed.

NODE NAME Specifies the name of the IBM Connect:Direct node from which the file istransmitted.

TRANSPORT Specifies the method of TRANSPORT IBM Connect:Direct uses for the filetransfer.

NETMAP—Causes IBM Connect:Direct to look in the network map for thesending and receiving nodes. If you type a Transport of NETMAP, the SNODEkeyword remains SNODE=secondary node.

TCP—Indicates that the NODE NAME field contains an alias name or an IPaddress. IBM Connect:Direct does not look in the network map for nodeinformation.

DNS—Enables you to enter a domain name up to 255 bytes

Note: If you type TCP or DNS in the Transport field, the SNODE keywordbecomes SNODE=TCPNAME=tcpvalue.

RECEIVINGENVIRONMENT

Specifies the operating system or platform to which the file is transmitted. Thevalues you place in the Receiving Environment and Node Name fields determinewhich Receiving File screen is displayed.

NODE NAME Specifies the name of the node to which the file is transmitted.

PROCESS NAME (optional) Specifies the name to be used under which the Process will besubmitted. If you do not type a Process name, IBM Connect:Direct providesthe default name COPYCF.

Chapter 5. User Guide 587

Parameter Name Description

SUBMIT MULTIMODE

Specifies if multiple process re-submission to TCQ for execution are allowed.

YES = Allows process re-submissions

This enables process re-submission with same attributes.

NO = Limits process re-submissions

This prevents process re-submissions so that submitters are only able to makeonly one submission per COPY process.

Any process re-submissions from users will be declined and the followingmessage displays:

Process NOT Re-submitted.

You have already submitted a process with the same information! If you havenot seen the completion message yet, then you can check on the progress ofthe copy using option SP from the main Connect:Direct menu. However, if youwant to resubmit the process change the SUBMIT MULTI MODE TO Y.

VALIDATE ONLY Enables you to validate the Process without submitting it.

YES = Validate the Process, but do not submit it.

NO = Do not validate before the Process is submitted.

FASP Optional: Specifies whether Connect:Direct should request SSP to use the FASPprotocol to the SNODE. Valid only when there is a FASP capable SSP and theSNODE is also FASP capable otherwise it is FASP=NO. Valid values are NO orSSP.

FASP POLICY Optional: Specifies the FASP Policy that SSP is to attempt for the FASP session.Valid values are FIXED or FAIR HIGH or LOW.

FASP BANDWIDTH Optional: Specifies the FASP Bandwidth that SSP is to attempt for the FASPsession. Valid values are specified as nnn or nM or nG

FASP FILESIZE Optional: Specifies the FASP Filesize Threshold to limit the size of file thatcan use the FASP protocol. File sizes that are less than the threshold will beprocessed as FASP=NO.

ZFBA Specifies the number of zFBA devices to allocate to the Process. Theonly acceptable value is 2 and this ZFBA feature requires additionalconfiguration settings in the NETMAP and initialization parameters. Consult theConnect:Direct Administration Guide for Using zFBA for File Transfer.

CHECKPOINT (optional) Specifies the byte interval for checkpoint support, which enablesrestart of interrupted transmissions at the last valid transmission point,avoiding the need to restart transmission from the beginning.

K denotes thousands; M denotes millions. A checkpoint value of zero stopsautomatic checkpointing.

588 IBM Connect:Direct for z/OS: Documentation

Parameter Name Description

COMPRESS (optional) Specifies whether and how the data being transmitted should becompressed.

Y – Uses compression with X'40' (blank) as the PRIMEchar.

N – Does not use compression.

X – Uses Extended compression.

X'xx' – Uses compression with the specified ‘xx' hex vale.

C'c' – Uses compression with the specified ‘cc' character value.

Note: Compression is CPU-intensive, and its effectiveness is data dependent. Itshould only be used if its benefits are known.

EXTCOMPRESSIONLEVEL

Note: The effects of changing the default values for the extended compressionparameters (level, window, and memory) are not always predictable and cansignificantly increase CPU utilization. Before changing the default values, seeImproving Performance in the IBM Connect:Direct for z/OS AdministrationGuide.

(optional) Specifies the value from 1–9 indicating the degree of compression touse. The default is 1, which usually provides sufficient compression.

WINDOW (optional) Specifies the value from 8–15 indicating the size of the compressionbuffer to use. The default of 13 equals 32 KB.

MEMORY (optional) Specifies the value from 1–9 indicating the amount of memory usedto maintain the compression state. The default of 4 equals 8 KB.

OVERRIDESECURITY

Enables you to change security information for the sending and receivingnodes.

YES = Enable

NO = Disable

CASE SENSITIVITY (optional) Specifies the case sensitivity not only to the SUBMIT command, butto the COPY Process itself. IBM Connect:Direct provides for mixed case userinput because some platforms allow it. The default is NO, which does not allowmixed case.

4. To override security information, type Y in the OVERRIDE SECURITY field.

node.name Connect:Direct SECURITY OVERRIDE TIME: hh:mm CMD ==> SENDING ENVIRONMENT: ZOS TRANSPORT: TCP NODE NAME: CD.NODE1 SECURITY ID: ________________________________________________________________ PASSWORD : ACCOUNTING DATA: ____________________________________________________ RECEIVING ENVIRONMENT: ZOS NODE NAME: CD.NODE2 SECURITY ID: ________________________________________________________________ PASSWORD : ACCOUNTING DATA: ____________________________________________________

5. In the SECURITY OVERRIDE screen:a) Specify the security information for the node whose security you want to override and press Enter.

This procedure assumes that you modify security information for both nodes.b) Press PF1 for a description of each field.

Chapter 5. User Guide 589

Note: For a complete description of the valid parameters of a COPY Statement and examplesto help you fill in both the SENDING FILE and RECEIVING FILE screens, see the Connect:DirectProcess Language help.

6. When the SENDING FILE screen for the environment and node name you specified is displayed, typeappropriate values and press Enter.

Note: If the data set name does not follow z/OS naming conventions, enclose the data set in singlequotation marks. An HFS file must begin with a slash (/) and can contain up to 251 bytes.

node.name COPYFILE - SENDING FILE (z/OS or OS/390) TIME: hh:mm CMD ==> NODE NAME: CD.NODE2 SENDING DSNAME: __________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________ UNIT PARAMETER: ( ________________________________ ) LABEL PARAMETER: ( ________________________________ ) VOLUME SERIAL(S):( _______________________________________________________ ) RETAIN: _ (Y OR N) DCB PARAMETER: ( ________________________________________________________ ) TYPE KEY: ________ MSVGP NAME: ________ SYSOPTS: _____________________________________________________________________ (PDS ONLY:) REPLACE: Y (Y OR N) ALIAS: Y (Y OR N) SELECTION CRITERIA: ( __________________________________________ ) ( __________________________________________ ) EXCLUSION CRITERIA: ( __________________________________________ ) ( __________________________________________ )

7. When the RECEIVING FILE screen for the environment and node name you specified is displayed, typeappropriate values and press Enter.

Note: If the data set name does not follow z/OS naming conventions, enclose the data set in singlequotation marks. An HFS file must begin with a slash (/) and can contain up to 251 bytes.

node.name COPYFILE - RECEIVING FILE (z/OS or OS/390) TIME: hh:mm CMD ==>

NODE NAME: Q1A.ZOS.V6100 RECEIVING DSNAME: ____________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ______________________________ DISPOSITION: ( NEW , CATLG_ , ______ ) UNIT PARAMETER: ( ________________________________ ) VOLUME SERIAL(S):( _______________________________________________________ ) ) RETAIN: _ (Y OR N) COUNT: ___ (1-255) DCB PARAMETER: ( __________________________________________________________ ) LABEL PARAMETER: ( ____________________________________________ ) SPACE: ( ________________________________ ) TYPE KEY: ________ MSVGP NAME: ________ SYSOPTS: _____________________________________________________________________ SMS: DATA CLASS: ________ STORAGE CLASS: ________ MGMT CLASS: _________ AVERAGE RECS: _ DSNTYPE: _______ VERSION: _ MAXGENS: __________ EATTR: ___ VSAM ORGANIZATION: ____ KEY LENGTH: ___ KEY OFFSET: _____ LIKE DSNAME: ____________________________________________ SECURITY MODEL: ____________________________________________ GENERIC MODEL: ___ (YES OR NO)

8. Press Enter.

• If you enabled the Validate Only parameter, a VIEW PROCESS screen with your Process is displayed.See the table in Operation for information on the results.

• If you did not select the Validate Only option, the Process is executed. See the table in “ValidatingProcesses from the SB, DF, and CF IUI Options” on page 581 for information on the results.

590 IBM Connect:Direct for z/OS: Documentation

CAUTION: Press PF3 to back out of each screen until the Primary Options Menu is displayed.Since SUBMIT MULTI MODE is disabled, the following message displays when the userattempts re-submitting a process with the same information.

Process not re-submittedYou have already submitted a process with the same information!If you have not seen the completion message yet, then you can check on the progress of the copy using option SP from the mainConnect:Direct menu. However, if you want to resubmit the process change the SUBMIT MULTI MODE TO Y.

To resubmit the process, modify a attribute and try submitting the process again. Alternatively,go back to the Copy File Menu and change the SUBMIT MULTI MODE to Y.

Controlling Processes in the TCQ

Controlling Processes with CommandsIBM Connect:Direct Processes consist of statements with parameters that provide instructions forcopying files, running jobs and programs, and altering the sequence of Process step execution. Use theProcess Control commands to manipulate these Processes while they are in the TCQ.

Note: You can also use the Connect:Direct Browser User Interface to perform some Connect:Direct forz/OS procedures.

Setting Selection CriteriaThe Process control commands have common parameters and IUI screen layouts. All Process controlcommands allow you to select Processes by Process name, number, and submitter. (Some allowadditional criteria.) The WHERE parameter groups the selection arguments, enabling you to makecommon changes or selections. The command applies to all Processes which match the criteria. Forexample, if you indicate a Process name PROCA with no further qualification, all Processes named PROCAare affected by the command.

When you specify two or more WHERE subparameters, you further qualify the selection so that allconditions must be satisfied. In this way, you can adequately qualify your selection if you have non-unique Process names or numbers. For example, if you specify in your selection criteria a Process name ofPROCA and Process number of 16, the Process number of PROCA must be 16 for the command to apply.

If you specify multiple Processes by using the list option on the subparameter, the position of thearguments in the list is significant. Elements in each list must correspond by position. For example,PNAME=(PROCA, PROCB), PNUM=(16,17) requires that PROCA be Process number 16 and PROCB beProcess number 17 for the command to apply.

On the screens, you can type a list of Process names, numbers, and submitters (user ID and node ID) toobtain the same results that the WHERE parameter list provides in batch. IBM Connect:Direct builds theappropriate command from the screen. IBM Connect:Direct accesses the corresponding Process namesand numbers and submitters (user ID and node) from left to right to construct the list form of thiscommand.

Modifying a Process in the TCQ with CHANGE PROCESSUse the CHANGE PROCESS command to modify the parameters of a Process when the Process is in theTCQ in a nonexecuting state. Release a held Process or restart a failed Process with this command. (Youcan also release a held Process through the Operator Table and Selected Process screens by typing an Rnext to the Process Name.)

Chapter 5. User Guide 591

CHANGE PROCESS Command FormatThe CHANGE PROCESS command has the following format and associated parameters. Requiredparameters and keywords are in bold print.

Label Command Parameters

(optional) CHange PROCESS WHERE ( NODE= node name | (list)PNAME= name | (list)PNUMber= number | (list)SUBmitter= (node name, user ID)|(list) )CASE= Yes | NoCLASS= nDEBUG= trace bitsDEST= destination nodeHOLD= Yes | No | CallNETMAP.REFRESHPLEXCLASS=(pnode class, snode class)PRTY= nRELEASERESTART= [NO | FIRST = volume sequence number | FIRST = SER = volume serial number | LAST = volume sequence number | LAST = SER = volume serial number | VOLCNT = n]RETAIN= Yes | No | InitialSTARTT= ([date|day] [,hh:mm:ssXM])

The following table describes the parameters for the CHANGE PROCESS command:

Parameter Description

WHERE (NODE = node name | (list) PNAME= name | (list)

PNUMber = number | (list)

SUBmitter = (node name, user ID) | (list))

Specifies which Process(es) to change. Name multiple Processesin the command using the selection criteria method describedon “Setting Selection Criteria” on page 591 if you have to makesimilar changes to many Processes. This parameter is required.

The selection subparameters are optional; however, you mustspecify at least one of NODE, PNAME, PNUMBER, or SUBMITTER.These subparameters are special in that they identify whichProcesses are selected for the change activity defined by theother parameters.

NODE = node name | (list) Specifies the snode or a list of snodes where the Processes to bechanged are running. If you specify a list of snodes, enclose themin parentheses separate each snode with a comma.

You can use this subparameter with the HOLD parameter to putall Processes on a node on hold if the node is unavailable, or ifproblems exist with the node. You can restart all Processes laterusing the RESTART parameter with the NODE= subparameter.

PNAME = name | (list) Specifies the name of the Process to be changed or a listof Process names enclosed in parentheses and separated bycommas. This parameter is optional.

592 IBM Connect:Direct for z/OS: Documentation

Parameter Description

PNUMber = number | (list) Specifies the number of the Process to be changed or a listof Process numbers enclosed in parentheses and separated bycommas. The range is 1-99999.

SUBmitter = (node name, user ID) | (list) Specifies the node name and user ID of the user that submittedthe Process to be changed. Specify a list of SUBmitter IDsby enclosing the IDs in parentheses and separating them bycommas.

CASE = Yes | No Specifies whether parameters associated with accounting data,user ID, password, and data set name are case sensitive. Thedesignation refers only to the command, not to the Process itself.See Indicating Case Sensitivity for a general overview of casesensitivity. This parameter is optional.

CLASS = n Determines the node-to-node session on which a Processexecutes. Consult your IBM Connect:Direct administrator forinstructions concerning which class to specify. The range is1-255. This parameter is optional.

DEBUG= trace settings for this Process Specifies the 8-position trace setting for this Process. Thisparameter enables you to specify a trace for only this Process.The table on Building, Modifying, and Submitting Processes listsacceptable trace values. This parameter is optional.

Note: This option can generate a large amount of output andshould be used with caution.

DEST = destination node Specifies a new destination node. This parameter changes thenode that this Process communicates with. This parameter isoptional.

HOLD = Yes | No | Call Specifies whether or not the Process is placed in the hold queue.This parameter is optional.

Yes specifies that the Process remains in the hold queue untilone of the following events occurs:

• CHANGE PROCESS releases the Process• DELETE PROCESS deletes the Process

When you specify both HOLD=YES and a STARTT value, the HOLDspecification takes precedence. Therefore, IBM Connect:Directplaces a Process submitted with HOLD=YES on the hold queueeven if you specified a start time.

No specifies that IBM Connect:Direct does not place the Processin the hold queue, but places it in the WAIT for execution queue(EX). HOLD=NO is the default.

Call specifies that IBM Connect:Direct is to place the Process inthe hold queue until a session is established with the specifiedSNODE. This session could be established by either anotherProcess starting on the PNODE destined for the same SNODEor the SNODE contacting the PNODE. For example, a Processsubmitted HOLD=NO establishes a session and causes executionof any Processes residing on the SNODE destined for this nodethat are submitted with HOLD=CALL.

Note: IBM Connect:Direct ignores the HOLD parameter ifRETAIN=Y.

Chapter 5. User Guide 593

Parameter Description

NETMAP.REFRESH Refreshes the network map for Processes waiting execution inthe Wait queue, after an UPDATE NETMAP command is issued forthis node. (For a description of the UPDATE NETMAP command,see the IBM Connect:Direct for z/OS Administration Guide andsearch on Maintaining the Network Map. This parameter isoptional.

Do not use the NETMAP.REFRESH parameter if the network mapprotocol is changed (for example, changing a node from LU0 toLU6.2). If you change the protocol for a particular node, you mustdelete and resubmit all waiting Processes for that node.

PLEXCLASS = (pnode class, snode class) Specifies the class that directs the Process to only certain serversin a IBM Connect:Direct/Plex. This parameter does not applyto a IBM Connect:Direct Stand-alone Server. This parameter isoptional.

You can designate each server in a IBM Connect:Direct/Plex to support only certain PLEXCLASSes through theCDPLEX.PLEXCLASSES initialization parameter. You can then limitProcesses to only those servers by specifying the PLEXCLASS inthe Process definition.

The pnode class controls which IBM Connect:Direct Server runsthe Process. The snode class controls what other node is usedwith the Process.

The pnode class and snode class are each 1-8 characters long.An asterisk (*) indicates that the Process runs on any server withan asterisk designated in the CDPLEX.PLEXCLASSES initializationparameter. If you do not specify a PLEXCLASS, the network mapis checked for a default PLEXCLASS. If the network map doesnot specify a default PLEXCLASS, then an asterisk is used as thedefault.

If a Process must run on a specific IBM Connect:Direct Server,specify the IBM Connect:Direct Server name in this field. TheProcess only runs on that server.

PRTY = n Specifies the Process priority in the Transmission Control Queue.High numbers indicate high priorities; low numbers indicate lowpriorities. IBM Connect:Direct uses this priority only for Processselection; it does not affect the priority during transmission. Thedefault is set by the PRTYDEF global initialization parameter. Therange is from 0-15. This parameter is valid for LU0 only. Thisparameter is optional.

RELEASE Releases the Process for execution from the queue where it iscurrently residing. Either specify RELEASE or omit it. Releases orRELEASE=no is not valid. This parameter is optional.

594 IBM Connect:Direct for z/OS: Documentation

Parameter Description

RESTART = [NO | FIRST = volumesequence number | FIRST=SER=volumeserial number |

LAST = volume sequence number |

LAST = SER = volume serial number |

VOLCNT = n]

Specifies the conditions for restarting an interrupted Process.

Use the CHANGE PROCESS command to cause IBMConnect:Direct to restart a data transmission at the lastcheckpoint position taken before the interruption or at a previouscheckpoint position. IBM Connect:Direct restarts the copy step atthe position you specify. This parameter is optional.

NO specifies that the copy step restarts at the beginning of thetransmission.

FIRST=volume sequence number specifies that the copy steprestarts at the beginning of the volume designated by the volumesequence number.

FIRST=SER=volume serial number specifies that the copy steprestarts at the beginning of the volume serial given.

LAST=volume sequence number specifies that the copy steprestarts at the end of the volume designated by the volumesequence number. LAST specifies that the copy step restarts atthe last block on the volume if the output is disk or the lastcheckpoint on the volume if the output is tape.

LAST=SER=volume serial number specifies that the copy steprestarts at the end of the volume serial given. LAST specifiesthat the copy step restarts at the last block on the volume if theoutput is disk or the last checkpoint on the volume if the output istape.

VOLCNT=n specifies that the volume count on the interruptedcopy step is changed to the value specified. You can use thisparameter to increase the number of output volumes if the copystep is interrupted because the volume count of that step is toosmall.

RETAIN = Yes | No | Initial Specifies whether or not IBM Connect:Direct keeps a copy of theProcess in the HOLD queue after the Process has executed. Thisparameter is optional.

Yes keeps a copy of this Process in the HOLD queue after theProcess executes. The copy of the Process does not executeuntil you release it through a CHANGE Process command.If RETAIN=YES is specified, IBM Connect:Direct automaticallyholds the Process until you release it, unless you include theSTARTT parameter in your Process. Use RETAIN in conjunctionwith STARTT to cause a Process to run repeatedly at a giveninterval.

No specifies that IBM Connect:Direct is to delete the Processafter execution. The default value for RETAIN is NO.

Initial specifies that IBM Connect:Direct is to execute theProcess every time IBM Connect:Direct is initialized. Do not codethe STARTT parameter with the RETAIN=I parameter.

Chapter 5. User Guide 595

Parameter Description

STARTT =

( [ date | day] [,hh:mm:ssXM ])

Specifies that the Process not execute until a specified dateor time. See “SUBMIT Command” on page 572 for a completeexplanation of the STARTT parameter. This parameter is optional.When changing the date, day, or hh:mm:ssXM, you mustrespecify even the values that do not change. You cannot specifyTODAY or TOMORROW for the day subparameter.

Note: Processes with a QUEUE or STATUS of PR cannot be changed with the CHANGE PROCESScommand.

CHANGE PROCESS Command ExamplesThe following CHANGE PROCESS command places the Processes named PAYROLL and BILLING in thehold queue:

CH PROC WHERE ( - PNAME=(PAYROLL, BILLING)) - HOLD=Y

In the following example, the Process named PAYROLL is changed so that the new destination node isDALLAS1 and the Process executes every Friday:

CH PROC WHERE (PNAME=PAYROLL) - DEST=DALLAS1 - RETAIN=Y - STARTT=(FR)

In the following example, the Process called PAYROLL with the Process number of 60584 has the RETAINstatus changed so that the Process is deleted after execution:

CH PROC WHERE (PNUM=60584, PNAME=PAYROLL) - RELEASE - RETAIN=N

Issuing CHANGE PROCESS through the Batch InterfaceTo use the CHANGE PROCESS command from the Batch Interface:

1. Place commands in the DGADBATC job stream as described in Sample Job Stream to Run the BatchInterface.

2. Submit the job while IBM Connect:Direct is running.

A report similar to the following is displayed:

=================================================================== CHANGE PROCESS===================================================================PROCNAME PROCNUM_ SUBMITTER_NODE__ SNODE.NAME______ MESSAGE________USERID___________-------------------------------------------------------------------DMNOTEST 271 node.name node.name DEST CHANGEDUSER01-------------------------------------------------------------------

3. Check this report to verify your results.

596 IBM Connect:Direct for z/OS: Documentation

Issuing CHANGE PROCESS through the IUIUse the CHANGE PROCESS screen to change a Process and its parameters. To issue the CHANGEPROCESS command from the IBM Connect:Direct IUI, perform the following steps:

1. Select option CP from the Primary Options Menu to display the CHANGE PROCESS screen.

node.name CHANGE PROCESS hh:mmCMD ==>PROCESS NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______PROCESS NAMES: ==> ________ ==> ________ ==> ________ ==> ________NODES ==> _______________ ==> _______________ ==> _______________USER IDS: USER NODES: ==> _________________________________________________________________ ==> ____________________________ ==> _________________________________________________________________ ==> ___________________________ ==> _________________________________________________________________ ==> ____________________________PLEXCLASS ==> ________ ________ (PNODE SNODE)DESTINATION NODE ==> ________________ DEBUG ==> ________PRIORITY ==> __ (0 TO 15)CLASS ==> ___HOLD PROCESS ==> _ ('Y'-YES, 'N'-NO, 'C'-CALL)RELEASE PROCESS ==> _ ('Y'-YES, 'N'-NO')RETAIN PROCESS ==> _ ('Y'-YES, 'N'-NO, 'I'-INIT)REFRESH FROM NETMAP ==> _ ('Y'-YES, 'N'-NO')SCHED. START DATE ==> ________ TIME ==>______RESTART ALTERATIONS ==> _________________________________________________DO YOU WANT THE VALUES OF THIS REQUEST TO BE CASE SENSITIVE? ==> NO

IBM Connect:Direct selects the corresponding Process names and numbers and submitters (user IDand node) from left to right to construct the list form of this command. This list fully qualifies yoursearch criteria.

2. Type at least one of the parameters or a combination of parameters as described in the CHANGEPROCESS command syntax section on Modifying a Process in the TCQ with CHANGE PROCESS or pressthe PF1 key for Help.

IBM Connect:Direct changes the parameters for the Processes that match the search criteria. The casesensitivity designation refers only to the command parameters on the screen, not to the parameters ofthe Process itself.

Suspending, Flushing, and Deleting ProcessesThe SUSPEND PROCESS, FLUSH PROCESS, and DELETE PROCESS commands have similar formats andparameters. The following table describes each command:

Process Description

SUSPENDPROCESS

Terminates execution and puts an executing Process in the Hold queue. IBMConnect:Direct places the Process in HOLD status. You can restart the Processthrough the RELEASE parameter of the CHANGE PROCESS command, or by usingthe R option on the Operator Table screen or the Selected Process screen.

FLUSH PROCESS Terminates an executing Process. Note that if you specify RETAIN=YES, the flushedProcess remains in the TCQ for execution at the next scheduled time. If you specifyRETAIN=NO, IBM Connect:Direct removes the Process from the TCQ, and you mustresubmit it if you want it to execute.

DELETE PROCESS Enables you to specify a nonexecuting Process and remove it from the TCQ.

Note: FLUSH PROCESS stops an executing Process.

If you do not specify FORCE for the FLUSH or SUSPEND command, an indicator notifies the programexecuting on behalf of the Process that a FLUSH or SUSPEND command was issued for the Process. Ifthat program is not in control (for example, if it is waiting on a request outside of IBM Connect:Direct code

Chapter 5. User Guide 597

to complete), then it does not see the FLUSH or SUSPEND indicator and the Process is not flushed orsuspended; otherwise, the program looks for the FLUSH or SUSPEND indicator and takes the appropriateaction.

When you specify FORCE, the action taken depends on the STATE and SUBSTATE of the Process for whichyou issued the FORCE FLUSH or FORCE SUSPEND. Determine the STATE and SUBSTATE of the Process bydoing a SELECT PROCESS or SELECT TASK command.

Note: For a Process in a VTAM I/O STATE and a SUBSTATE of SEND or RECEIVE, the FLUSH or SUSPENDcommand is implemented whether you specify FORCE or not. That is not true for the other states.

SUSPEND, FLUSH, or DELETE PROCESS Command FormatThe SUSPEND PROCESS, FLUSH PROCESS, and DELETE PROCESS commands have the following formatand associated parameters. Required parameters and keywords are in bold print.

Label Command Parameters

(optional) FLUSH PROCess |DELETE PROCess | SUSPEND PROCess

WHERE (PNAME= name | (list)PNUMber= number | (list) SUBmitter= (node name, user ID)|(list) FORCE )

Note: The FORCE parameter is not valid forDELETE PROCESS.

CASE = Yes | No

The following table describes the parameters:

Parameter Description

WHERE (

PNAME = name | (list)

PNUMber = number |(list)

SUBmitter = (nodeid,user ID) | (list)

FORCE )

Specifies which Process to suspend, delete, or flush. Name multiple Processes in thecommand using the search criteria method described on “Setting Selection Criteria”on page 591 .

WHERE is the only required parameter for the SUSPEND PROCESS, DELETE PROCESS,and FLUSH PROCESS commands. Its subparameters are optional. However you mustspecify at least one of the PNAME, PNUMBER, and SUBMITTER subparameters.

PNAME = name | (list) specifies the name of the Process or a list of Process namesenclosed in parentheses and separated by commas.

PNUMber = number | (list) specifies the number of the Process selected or a list ofProcess numbers enclosed in parentheses and separated by commas. The range is1-99999.

SUBmitter = (nodeid, user ID) | (list) specifies the nodeid and user ID of the userthat submitted the Process. Specify a list of SUBmitter IDs by enclosing the IDs inparentheses and separating them by commas.

FORCE enables you to suspend or flush a Process waiting for unavailable resources. Ifthe initial suspend or flush fails, retry the command with FORCE.

Note: FORCE parameter is not valid for DELETE PROCESS. If FORCE is specified for aProcess executing on an LU6.2 session, it can terminate the session immediately, andIBM Connect:Direct does not exchange the Process statistics between nodes.

CASE = Yes | No Specifies whether parameters associated with accounting data, user ID, password,and data set name are case sensitive. The designation refers only to the command, notthe Process itself. This parameter is optional.

598 IBM Connect:Direct for z/OS: Documentation

Note: Processes with a QUEUE or STATUS of PR cannot be flushed or suspended with the FLUSH orSUSPEND PROCESS command.

SUSPEND, FLUSH, and DELETE Command ExamplesExamples of the SUSPEND, DELETE, and FLUSH commands are shown in the following:

SUSPEND ProcessThe following command suspends any executing Process with a submitter node ID of DALLAS and asubmitter user ID of SMITH:

SUSPEND PROC WHERE (SUB=(DALLAS, SMITH))

The following command suspends the Process named PAYROLL, which is Process number 514 and theProcess named COPY100, which is Process number 575.

SUS PROC WHERE ( - PNAME=(PAYROLL,COPY100), - PNUM=(514,575))

FLUSH ProcessThe following command flushes executing Processes submitted by SMITH at the node DALLAS:

FLUSH PROC WHERE (SUB=(DALLAS, SMITH))

The following command flushes the Process named PAYROLL which has Process number of 514 and theProcess named COPY100 which has the Process number of 575:

FLUSH PROC WHERE ( - PNAME=(PAYROLL,COPY100), - PNUM=(514,575))

DELETE ProcessThe following command deletes Processes with the number 60584:

DEL PROC WHERE (PNUM=60584)

The following command deletes all Processes submitted by CHUCK at the node DALLAS.MVS:

DEL PROC WHERE (SUB=(DALLAS.MVS, CHUCK))

The following command deletes all Processes in the PR queue. When specifying QUEUE= PR, no otherselection criteria are allowed.

DELETE PROCESS WHERE (QUEUE=PR)

Chapter 5. User Guide 599

Issuing the SUSPEND PROCESS, DELETE PROCESS, or FLUSH PROCESSCommands through the Batch InterfaceTo use the SUSPEND PROCESS, DELETE PROCESS, or FLUSH PROCESS commands from the BatchInterface, perform the following steps:

1. Place commands in the DGADBATC job stream as described in “Sample job stream to run the batchinterface” on page 525.

2. Submit the job while IBM Connect:Direct is running.3. Verify the results.

Issuing the SUSPEND PROCESS, DELETE PROCESS, or FLUSH PROCESSCommands through the IUITo issue commands through the IUI:

1. Access the function that you want as described in the following table.

Function Access Method

Suspend anexecuting Process

Select option PS from the Primary Options Menu.

Type SUS at the Primary Options Menu command prompt

Type a P next to the Process Name on the Operator Table, the Operator Table -Executing Queue, or the Selected Process screens.

Delete anonexecutingProcess

Select option DP from the Primary Options Menu.

Type a D next to the Process Name on the Operator Table or the SelectedProcess screens.

Flush a Process Select option FP from the Primary Options Menu.

• Type an F next to the Process Name on the Selected Process screen.

The following screen shows an example of the Suspend an Executing Process screen. The Delete ANonexecuting Process screen and the Flush Process screen are similar except that the FORCE option isnot on the Delete A Nonexecuting Process screen.

node.name SUSPEND AN EXECUTING PROCESS hh:mm CMD ==> PROCESS NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______ ==> ______ ==> ______ ==> ______ ==> ______ PROCESS NAMES: ==> ________ ==> ________ ==> ________ ==> ________ ==> ________ ==> ________ ==> ________ ==> ________ FORCE: ('Y'-YES, 'N'-NO) FORCE SUSPENDING A PROCESS ON AN LU 6.2 SESSION ==> _ MAY TERMINATE THE SESSION IMMEDIATELY WITHOUT STATISTICS OF THE PROCESS BEING EXCHANGED USER IDS: USER NODES: ==> _______________________________________________________________ ==> ___________________________ ==> _______________________________________________________________ ==> ___________________________ ==> _______________________________________________________________ ==> ___________________________DO YOU WANT THE VALUES OF THIS REQUEST TO BE CASE SENSITIVE? ==> NO

IBM Connect:Direct builds the SUSPEND PROCESS command from this screen, and selects thecorresponding Process names and numbers and submitters (user ID and node) from left to right toconstruct the list form of this command. This list fully qualifies your search criteria.

600 IBM Connect:Direct for z/OS: Documentation

2. Type at least one of the parameters or a combination of parameters as described in the SUSPENDPROCESS command syntax section in Suspending, Flushing, and Deleting Processes, or press the PF1key for Help. IBM Connect:Direct suspends the Processes which match your search criteria.

Note: Case sensitivity designation refers only to the command parameters on screen, not to theparameters of the Process.

3. To minimize the risk of deleting, suspending, or flushing a Process accidentally, you may be requiredto confirm a Process request before it is executed. If you are required to confirm delete, flush, andsuspend commands, a panel similar to the following screen is displayed. Do one of the following:

• To confirm the operation, type Y on the command line. IBM Connect:Direct performs the functionand returns to the previous screen.

• To return to the previous screen without performing the function, press PF3. To change the Processnumbers, select this option before executing the command.

DMDELCN2 DATE: YYYY/MM/DD Connect:Direct Confirm Delete Command TIME: HH:MMCMD ==>You have requested the following process(es) be deleted, are you sure this is what you want to do? Reply Yes, No or CANCEL or Press PF3 to Cancel the Request Process Numbers ==> 123 ==> ==> ==> ==> ==> Process Names ==> ==> ==> ==> ==> ==> USER IDS: USER NODES: ==> ==> ==> ==> ==> ==> == ==> __ Do not display this Confirm Delete prompt again.

Note: If you see the option, Do not display this Confirm Delete prompt again, you can type an X next tothis option to turn off the Confirm prompt so that it will not display again during the current session.

Examining Processes in the TCQUse SELECT PROCESS to look over Processes in the TCQ. You can specify the search criteria and the formin which the information is presented (file, printout, table, or screen display).

Note: Use the SELECT STATISTICS command to determine the outcome of a completed Process.

SELECT PROCESS Command FormatThe SELECT PROCESS command has the following format and parameters. The required parameters andkeywords are in bold print. Default values are underlined.

Note: The syntax and parameters for the VIEW PROCESS command are identical.

Chapter 5. User Guide 601

Label Command Parameters

(optional) SELect PROCess

or

View PROCess

WHERE ( DEST= node | (list) PNAME= name | (list) PNUMber= number | (list) QUEUE= All | queue name SERVER= server name STATUS= Process status | (list) SUBmitter= (node name, user ID)|(list) )CASE= Yes | NoFILE | PRint | TABle

The following table describes the parameters.

Parameter Description

WHERE (DEST = node | (list) PNAME = name | (list) PNUMber = number | (list) QUEUE = All | Exec | Hold | PR |Timer |Wait STATUS = Process status | (list) SERVER = server name | (list) SUBmitter = (node name, user ID) | (list) )

Note: PR (Process Retention) requiresadditional setup, see IBM Connect:Direct forz/OS Administration Guide.

Specifies which Processes to select. Name multiple Processesin the command using the search criteria method described on“Setting Selection Criteria” on page 591 . The subparametersPNAME, PNUMber, and SUBmitter are optional, but you mustspecify at least one.

WHERE is the only required parameter for the SELECT PROCESScommand. Not all its subparameters are required.

DEST = node | (list) specifies the destination node name of theProcess you are selecting or a list of destinations enclosed inparentheses and separated by commas.

PNAME = name | (list) specifies the name of the Process or alist of Process names enclosed in parentheses and separating bycommas.

602 IBM Connect:Direct for z/OS: Documentation

Parameter Description

PNUMber = number | (list) specifies the number of the Processyou are selecting or a list of Process numbers enclosed inparentheses and separated by commas. The range is 1-99999.

QUEUE = All | queue name specifies Process selection based onthe TCQ. Values are: All specifies selection of a Process from allqueues. This value is the default. queue name can be one of thefollowing:

E = Executing queueH = Hold queueT = Timer queueW = Wait queue

SERVER = server name | (list) selects Processes on thespecified IBM Connect:Direct Servers. The server name isa 1-8 character name assigned to each server in a IBMConnect:Direct/Plex through the CDPLEX.SERVER initializationparameter.

STATUS = Process status | (list) specifies Process selection bystatus value or a list of status values in parentheses separatedby commas. Values include:

H = All Held ProcessesHC = Held for CallHE = Held for ErrorHI = Held InitiallyHO = Held by OperatorHP = Held due to Process errorHR = Held RetainHS = Held for SuspensionPR = Retained after ExecutionR = All Restart ProcessesRA = Held for Restart due to Allocation errorRH = Restart Held (may be due to the Intelligent Retry feature)W = All Waiting Processes (including Retry)WC = Wait for ConnectionWT = Waiting for TransportWX = Waiting for IBM Connect:Direct Server

SUBmitter = (node name, user ID) | (list) specifies the nodeidand user ID of the user that submitted the Process. Specify alist of SUBmitter IDs by enclosing the IDs in parentheses andseparating them by commas.

CASE = Yes | No Specifies whether parameters associated with accounting data,user ID, password, and data set name are case sensitive. Thedesignation refers only to the command, not the Process itself.See Indicating Case Sensitivity for a general overview of casesensitivity. This parameter is optional.

FILE | PRint | TABle Specifies the form in which the information is presented. TABLEis the default. See Indicating Output Destination for detailedinformation about the output format produced by each of thethese parameters. This parameter is optional.

Chapter 5. User Guide 603

SELECT PROCESS Command ExampleThe following command searches for all Processes submitted by SMITH at the node CD.DALLAS.

SEL PROC WHERE (SUB=(CD.DALLAS, SMITH))

Issuing SELECT PROCESS through the Batch Interface

To use the SELECT PROCESS command from the Batch Interface, perform the following steps:

1. Place commands in the DGADBATC job stream as described in “Sample job stream to run the batchinterface” on page 525.

2. Submit the job while IBM Connect:Direct is running.3. Verify your results.

Issuing SELECT PROCESS through the IUIUse the Select Process screen to specify the Processes that you want to display and how you want themdisplayed. To issue the SELECT PROCESS command in the IBM Connect:Direct IUI, perform the followingsteps:

1. Select option SP from the Primary Options Menu to display the Select Process screen.

node.name SELECT PROCESS CMD ==> O hh:mm CMD: O ... OPERATOR TABLE S ... OPERATOR TABLE/EXEC QUEUE STATUS P ... PRINT REPORT D ... DISPLAY REPORT V ... VIEW PROCESS QUEUE: ==> _ (A-ALL,W-WAIT,E-EXECUTE,H-HOLD,T-TIMER,P-PR) PROCESS NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______ PROCESS NAMES: ==> ________ ==> ________ ==> ________ ==> ________ SERVER NAMES: ==> ________ ==> ________ ==> ________ ==> ________ STATUS: (HO,HR,HI,HE,HC,HP,HS,PR,RH,RA,WC,WX,WT,H,R,W) ==> __ ==> __ ==> __ ==> __ DESTINATION NODES: ==> ________________ ==> ________________ ==> ________________ ==> ________________ USER ID: NODE ID: ==> ________________________________________________________________ ==> ________________ ==> ________________________________________________________________ ==> ________________ DO YOU WANT VALUES FOR THIS REQUEST TO BE CASE SENSITIVE? ==> NO

2. To select the Processes, specify the parameters to use as search criteria. These parameters aredescribed in SELECT PROCESS Command Format.

Note: The case sensitivity designation refers only to the command parameters on the screen, not tothe parameters of the Process itself.

3. To select the destination for your output, type the letter representing one of the following outputoptions on the command line:

• O accesses the Operator Table and creates a one line summary of each selected PNODE Process. Formore information, see Viewing and Controlling a Process through the Operator Table.

• S builds an Operator Table consisting only of Processes that are currently executing. The table showshow much data is transmitted for a COPY step. For more information, see Accessing ExecutionQueue Status on the Operator Table.

• V displays the content of the matching Processes within the TCQ. For more information, see Viewingthe Content of Processes Matching Your Search Criteria.

• P prints a report of the selected Processes.• D displays a report, similar to the following figure.

604 IBM Connect:Direct for z/OS: Documentation

BROWSE -- temporary file name ----- LINE 00000000 COL 001 080 COMMAND ===> SCROLL ===> PAGE********************************* TOP OF DATA *******************************=========================================================== SELECT PROCESS===========================================================

Prc Name => PROCESSA Queue => EXEC Prc Num => 3 Status => EX Prc Debug => 00000200 SMFID => SYSA Subnode => CD.NODE1 Time => Other Node => CD.NODE2 Date => Jobname => Job Num => Day => Userid => USER01 Prty => 10 Retain => N Ret proc => NONE Class => 1 State => Step Name => Xmit St => Max Class => 100 Ses id => PNODE Message Id => Rtncde => 0 Direction => Sending Side Applid => 05610 Ses Rstrt => 0 Dyn Rstrt=> 0 Snding DSN => SMSTEST.DSN1 Rcving DSN => SMSTEST.DSN2 Volseq No => 001 Ttrn => 00012434 Volser => ARTS09 Function => COPY Member => V2 Buffer Size => 2,097,152 Negotiated V2 Buffer Size => 2,097,152 TCP Buffer Size Used => 2,097,152 Estimated File Size => 10,000,050,560 Sent: Blks => 74,671 Recs => 0 RU's => 233 Bytes Read => 2,081,966,480 Bytes Sent => 464,633,653 Compression Factor => 77.7

Viewing and Controlling a Process through the Operator TableThe Operator Table displays the PNODE Processes which satisfied your selection criteria; it does notdisplay information about Processes submitted from another node.

1. After you type O on the command line of the Select Process screen, the Operator Table/ExecutingQueue screen is displayed.

The first two characters of the QUEUE indicate the queue, the second two characters indicate thestatus value. The OTHER.NODE is the name of the nonsubmitting node in the session.

2. Type an option in the OPTION column next to the Process name (PNAME) and press Enter. Thefollowing table describes each option.

Option Description

H Place a nonexecuting Process on the Hold queue.

D Delete a nonexecuting Process from the queue. For more information, see Issuing theSUSPEND PROCESS, DELETE PROCESS, or FLUSH PROCESS Commands through the IUI .

R Release a held Process.

P Suspend a Process from the executing queue. For more information, see Issuing CHANGEPROCESS through the IUI .

S Select a Process for detailed display. For more information, see Viewing and Controlling aProcess through the Selected Process Screen .

V View a Process in the executing queue. For more information, see Viewing the Content ofProcesses Matching Your Search Criteria .

Note: When you release a Process which contains RETAIN=YES, it is copied and assigned a newProcess number.

Chapter 5. User Guide 605

3. If you are required to confirm a delete or suspend Process request before it is executed, respond tothe Confirm Command prompt.

Note: If message ID SOPA006I is displayed on the Operator Table screen next to the Process nameunder the OPTION column, it indicates that the Process can no longer be found. The Process wasprobably in execute status when another function was selected, and the screen was not refreshed.Screens are not automatically refreshed. Press Enter to refresh the screen.

4. To view any message text, type END to leave the Operator Table and return to the Select Processscreen. Then type M on the command line, and press Enter.

Accessing Execution Queue Status on the Operator Table1. After you type S at the command line of the Select Process screen, the Operator Table/Executing

Queue displays Processes that are currently executing. The Operator Table/ Executing Queue screenshows how much data is transmitted by the COPY step, including:

• Blocks for block-mode transmissions• Records for record-mode transmissions• RUs (request/response units)• I/O bytes• VTAM bytes• The compression factor

The following figure is a sample of the screen and shows that two Processes are executing.

node.name Row 1 to 2 of 2 -----------------------OPERATOR TABLE/EXECUTING QUEUE----------- ==> Q SCROLL ===> PAGE OPTION PNAME PNUMBER SUBMITTER.NODE-- OTHER.NODE------ QUEUE SERVER USERID ------------------------------------------------------------------------------- BENCHRC 272 Q1A.ZOS.V4600 Q1A.ZOS.V4600 ¬P EX S3 USER01 Blks => 6 Recs => 0 RUs => 173 I/O bytes => 177,138 Compression VTAM bytes => 177,152 Factor => 0.0% BENCHRC 272 Q1A.ZOS.V4600 Q1A.ZOS.V4600 EX EX S3 USER01 Blks => 7 Recs => 0 RUs => 174 I/O bytes => 195,440 Compression VTAM bytes => 178,176 Factor => 8.8% ******************************* Bottom of data ********************************

2. Type an option in the OPTION column next to the Process name (PNAME) and press Enter. Thefollowing table describes each option.

Option Description

P Suspend a Process in the executing queue.

S Select a Process for detailed display. For more information, see Viewing andControlling a Process through the Selected Process Screen .

Viewing and Controlling a Process through the Selected Process ScreenTo view and control a Process through the Selected Process Screen:

1. From the Operator Table, type S in the OPTION column next to the name of the Process to display theSelected Process screen. This screen displays details about the Process that you selected from theOperator Table.The following figure is a sample of the screen which displays all available information about theparticular Process you selected from the Operator Table.

606 IBM Connect:Direct for z/OS: Documentation

CD.NODE SELECTED PROCESS 01:36CMD==> Process Name => PROCESS1 Number => 1 Step => COPY1 Other Node => CD.NODE DEBUG=> FFFFFEFF Status => EX Commid => 32782;10.120.130.42 Queue => EXEC Function => COPY Sub State => TCP State => ST RUNNG Server => PLEXCLASS => ( ) Submitter => CD.NODE SENDING SIDE SMFID => IRVO Userid => USER01 Scheduled Time => Date => Day => Queueing Prty => 10 Class => 1 Retain => NO Submitted Class=> 1 Max Class => 20 Sess.ID=> PNODE Session restrt => 0 Dyn rstrt => 0 RouteID=> Last Msgid => Last RC => 00000000 RetProc=> Secure=> AUTH - TLS V1.2 Signature => N Cipher#=> 009D Sending File => SMSTEST.DSN1 Receiving File => SMSTEXT.DSN2 Volume seq no. => 1 Volser => ARTS0H TTRN => 0000018B zFBA => ( ) Current zFBA => Blks => 392 Recs => 0 RUs => 335 Bytes Read => 10 916 720 MEMBER => Bytes Sent => 10 920 330 Compression Factor => 0.0% Encrypt.Data => Y Cipher Suite => TLS_RSA_WITH_AES_256_GCM_SHA384

2. Type any of the following Process control commands at the command line, and press Enter. Thefollowing table describes each option:

Command Description

P Suspend the currently executing Process

D Delete a nonexecuting Process

H Place a nonexecuting Process in the HOLD queue

R Release a nonexecuting Process

Enter Monitor the currently executing Process execution

C Change Other Node, Queueing Priority, Scheduled Time, Scheduled Day, andRetain Status in a nonexecuting Process

3. To change parameters, move the cursor to the appropriate field on the screen, make the changes thatyou want, and press Enter.

4. If you are required to confirm a Process request, respond to the Confirm Delete/Suspend Commandprompt.

5. If the Process completes execution while the Selected Process screen is displayed, press Enter toreturn to the Operator Table screen.

Viewing the Content of Processes Matching Your Search CriteriaTo view the content of Processes matching your search criteria:

• To view output on the VIEW PROCESS screen, do one of the following:

– Type a V on the command line on the Select Process screen after specifying the parameters to useas search criteria. These parameters are described in SELECT PROCESS Command Format. Also, formore information, see Issuing SELECT PROCESS through the IUI.

– Type V in the OPTION column next to the Process name on the Operator Table/Executing Queuescreen. (The PNODE Processes which satisfied your selection criteria on the Select Process screenare displayed on the Operator Table/Executing Queue screen.) See Viewing and Controlling aProcess through the Selected Process Screen.

The following shows the sample output of the VIEW PROCESS command:

Chapter 5. User Guide 607

Note: In case of Secure=(Encrypt.Data=Y|N) in process statement or Copy step, view process willdisplay “/*(Ignored; Deprecated*/” as below.

=========================================================== VIEW PROCESS

PROCESS NAME: SECOPY PROCESS NUMBER: 0===========================================================

SECOPY PROCESS SNODE=CDZOSB.SSARA1 - PNODE=CDZOSA.SSARA1 - SECURE=ENCRYPT.DATA=Y /*(Ignored; Deprecated)*/ - NOTIFY=SSARA1 - RETAIN=NO - CLASS= -

SECOP1 COPY FROM - (PNODE - DSN='SSARA1.PROCESS.XX8' - DISP=(SHR) - ) - TO - (SNODE - DSN='SSARA1.PROCESS.A1' - DISP=(RPL) - ) - SECURE=(ENCRYPT.DATA=Y /*(Ignored; Deprecated)*/)

SECOP2 COPY FROM - (PNODE - DSN='SSARA1.TESTFILE.O' - SELECT=( - TESTFILE - ) - DISP=(SHR) - ) - TO - (SNODE - DSN='SSARA1.PROCESS.A1' - DISP=(RPL) - ) - SECURE=(ENCRYPT.DATA=Y /*(Ignored; Deprecated)*/)

SECOP3 COPY FROM - (PNODE - DSN='SSARA1.TESTFILE.O' - SELECT=( - TESTFILE - ) - DISP=(SHR) - ) - TO - (SNODE - DSN='SSARA1.PROCESS.A1' - DISP=(RPL) - )

Process Queuing and RecoveryIBM Connect:Direct stores submitted Processes in the Transmission Control Queue (TCQ). The TCQcontrols Process execution. It consists of two inter-dependent VSAM Relative Record Data Sets (RRDS),and an in-memory queue which controls access. The two data sets are the TCQ and the TCX, which is aspace map for the TCQ.

Logical QueuesThe TCQ has the following logical queues:

• Wait• Execution• Hold

608 IBM Connect:Direct for z/OS: Documentation

• Timer• Process Retention

Access the queues and manipulate Processes using the following IBM Connect:Direct commands:

• CHANGE PROCESS• DELETE PROCESS• FLUSH PROCESS• SELECT PROCESS• SUSPEND PROCESS

Refer to Controlling Processes with Commands, for more information the on each of these IBMConnect:Direct commands.

Queuing ParametersThe RETAIN, HOLD, and STARTT parameters queue Processes as described in following table.

Parameters Queue Comments

None Wait Process remains on the Wait queue until IBMConnect:Direct can start a session with the SNODE.The Process then moves to the Execution queue.

RETAIN=INITIAL Hold Process automatically executes each time IBMConnect:Direct is initialized with TCQ=WARM. Thissetting is useful for Processes that contact other IBMConnect:Direct nodes each time IBM Connect:Directcompletes initialization. This action causes any workqueued on the remote node for the local node tobegin.

RETAIN=YES Hold A copy of the Process is kept in the Hold queue afterit has executed. The Process does not execute againuntil it is released by a CHANGE PROCESS command.

You can use RETAIN=YES, combined with STARTT,to run a Process at a periodic interval. For example,RETAIN=YES and STARTT=(Tuesday, 3pm) starts theProcess every Tuesday at 3 pm; RETAIN=YES andSTARTT=(,12:00) starts the Process each day at noon.

HOLD=YES Hold Process remains in the Hold queue until someonereleases the Process.

HOLD=CALL Hold Process is automatically moved from the Hold queueto the Wait queue when the SNODE contacts the nodeon which the Process resides.

Chapter 5. User Guide 609

Parameters Queue Comments

STARTT Timer When the scheduled time and date arrive, the Processis put on the wait queue and is available for execution.

You can use RETAIN=YES, combined with STARTT,to run a Process at a periodic interval. For example,RETAIN=YES and STARTT=(Tuesday, 3pm) starts theProcess every Tuesday at 3 pm; RETAIN=YES andSTARTT=(,12:00) starts the Process each day at noon.

You can also use the Timer queue for session retryand file allocation retry based on IBM Connect:Directinitialization parameters specified by a particularinstallation. When you exhaust retry limits, theProcess is moved to the Hold queue with an HE status.

When you submit a Process, IBM Connect:Direct puts it in the appropriate logical queue based onProcess statement routing parameters listed in the preceding table. See Process Execution Example foran illustration of how IBM Connect:Direct executes a Process.

TCQ Status and State ValuesThe SELECT PROCESS command displays IBM Connect:Direct status values, task state values, andtransport state values. These are defined in the following table:

Value Definition

IBMConnect:DirectStatus Value

Each Process on the TCQ has an associated IBM Connect:Direct status value. Thisstatus value has a unique meaning determined by which queue the Process is in. TheSELECT PROCESS command displays IBM Connect:Direct status values.

IBMConnect:DirectTask State Values

When a Process is in the Execution queue, the SELECT PROCESS command alsodisplays a IBM Connect:Direct task state value. The state values are provided forinformation purposes. You cannot modify or control them using IBM Connect:Directcommands. The task state value shows the current state of the Process. Usually,IBM Connect:Direct tasks are waiting for completion of a service such as File I/O,IBM Connect:Direct locked resource, or VTAM I/O.

Transport StateValues

When a Process is on the Execution queue, the SELECT PROCESS command canalso display a transport state value, depending on timing. The state values areprovided for informational purposes. You cannot modify or control them using IBMConnect:Direct commands. For example, if the Process is currently in a VTAM I/Ostate, the SELECT PROCESS output can show a further state value such as send orreceive.

While a Process is executing, the SELECT PROCESS command displays the numberof file blocks or records and VTAM request/response units (RUs) sent or received.This display gives you an indication of the status of COPY statements on the Process.

610 IBM Connect:Direct for z/OS: Documentation

Wait QueueThe following table shows the IBM Connect:Direct status value for the Wait Queue:

Status Value Explanation

WC Waiting for Connection. This status is the initial queue status when a Process issubmitted without HOLD or RETAIN specified. This status means the Process is readyto execute as soon as possible. This Process runs as soon as an eligible session isavailable. If you find a Process in this state, it is most likely for this reason. Processesare also in this state when IBM Connect:Direct is quiesced.

WP Waiting for Parsess. This status means the Process is ready to run but other Processesare executing with the same SNODE, and no other sessions are available. This Processruns as soon as an eligible session is available.

WT Waiting for transport. This status is the status of a Process when the transport protocolis not available. This Process runs as soon as the transport protocol is available.

WX Waiting for server. This status is the status of a Process waiting for a IBM Connect:DirectServer to become available. This Process runs as soon as an eligible IBM Connect:DirectServer is available. An eligible IBM Connect:Direct Server is an active server thatsupports the Process PLEXCLASS and the transport protocol (SNA, TCP, or CTCA). Thetransport protocol must also be available on the server for it to be eligible.

The following table shows the applicable commands for the Wait Queue:

Command Description

Change Process Modifies Process attributes

Delete Process Removes the Process from the queue

Select Process Displays Process status and state

Execution QueueThe following table shows the IBM Connect:Direct status values for the Execution Queue:

Status Value Explanation

EX Node is in Process control and executing the displayed Process.

WC (Waiting forConnection)

Process control is in negotiation while the two nodes determine which Processexecutes next, based on priority.

PR.CNTL This node is not in Process control. This status occurs: (1) during Process negotiationwhere highest priority on either node runs next, or (2) when the current node is theSNODE during Process execution.

SS Session with other node is being started.

The following table shows IBM Connect:Direct task state values for Processes in the Execution Queue:

Task State Explanation

DISPATCH Task is waiting to dispatch

INACTIVE Task can be dispatched but inactive

VTAM I/O Task is waiting on VTAM request

P=SNODE PNODE equals SNODE task

VSAM I/O Waiting on VSAM I/O request

Chapter 5. User Guide 611

Task State Explanation

MISC Miscellaneous I/O, such as a WTO

FILE I/O Non-VSAM I/O

LOCK Waiting for IBM Connect:Direct locked resource

SUBTASK Waiting on a subtask, such as open or close, allocation, security, or RUN TASK

RUNNING Executing instructions

TCA SCAN TCA scan

TIMER Waiting for timer event

ATTACH Waiting for attached tape drive

ALLOCATE Waiting for allocation to complete

MOUNT Waiting for tape mount

OPEN Waiting for OPEN to complete

The following table shows the Subtask state values for the Execution Queue. The first characters of thesubtask request state indicate the session protocol such as TCP or LU6.2.

Subtask State Explanation

ADOPT V2 Performing Adopt

CALL V2 Performing Call

INIT V2 Performing Initialization

CLEANUP Performing Cleanup

HANGUP Performing Hangup

SEND V2 Performing Send

SEND RSP Performing Send Response

SEND SIG Performing Send Signal

RECV V2 Performing Receive

ANSWER V2 Performing Answer

IOCTL V2 Performing I/O Control

GET BUF Performing I/O Control Get Buffer

RDY RCV Performing I/O Control Ready Receive

The following table shows the transport state values for the Execution Queue:

Transport State Explanation

NO SESSION No VTAM session

SESSION EST Session with another node being established

NO REQUEST No VTAM request outstanding

RECEIVE Waiting on VTAM RECEIVE request

OPEN Waiting on VTAM OPEN request

CLOSE Waiting on VTAM CLOSE request

612 IBM Connect:Direct for z/OS: Documentation

Transport State Explanation

SETLOGON Waiting on VTAM SETLOGON request

REQSESS Waiting on a request session request

OPNDST Waiting on an open destination request

CLSDST Waiting on a close destination request

GENCB EXTLST Waiting on a GENCB EXLIST

GENCB ACB Waiting on a GENCB ACB

GENCB NIB Waiting on a GENCB NIB

GENCB RPL Waiting on a GENCB RPL

REJSESS Waiting on a reject session request

SESSIONC Waiting on a session cancel request

INQUIRE Waiting on an inquire request

OPNSEC Waiting on an open secondary request

RSHUTD Waiting on a request shutdown request

SIMLOGON Waiting on a simulate logon request

SND RESPONSE Waiting on a send response request

WAIT FOR +DR Waiting on a definite response request

VTAM I/O Waiting on VTAM request

SEND Waiting on VTAM send request

DACTSESS waiting on LU6.2 deactivate session request

RCVFMH5 Waiting on LU6.2 receive FMH-5 request

REJECT Waiting on LU6.2 reject conversation request

ACTSESS Waiting on LU6.2 activate session request

ALLOC ALLOCD Waiting on LU6.2 allocate conversation until available request

PRERECV Waiting on LU6.2 prepare to receive request

Note: In a IBM Connect:Direct/Plex environment, the LU6.2 connection protocoldoes not enable the IBM Connect:Direct Manager to redirect work to one of itsservers. The remote node must address the server on which you want to runan LU6.2 Process. To do this, specify the node name and VTAM address of theIBM Connect:Direct Server on which the Process is to run in the remote server'snetwork map. Use the same CDPLEX.SERVER.NODE and CDPLEX.VTAM specifiedfor the local initialization parameters for the IBM Connect:Direct Server you aretrying to address.

CNOS Waiting on LU6.2 change number of session request

DELLOC Waiting on LU6.2 deallocate conversation request

SEND CONFRMD Waiting on LU6.2 send confirmation request

6.2 RECEIVE Waiting on LU6.2 receive request

6.2 SEND Waiting on LU6.2 send request

SEND ERROR Waiting on LU6.2 send error request

Chapter 5. User Guide 613

Transport State Explanation

DISPLAY Waiting on LU6.2 display session limit request

DEFINE Waiting on LU6.2 define session limits request

ALLOC IMMED Waiting on LU6.2 allocate conversation immediately request

The following table shows the allocate state values for the Execution Queue:

Allocate State Value Explanation

SVC99 Performing SVC99

CAT SEARCH1 CAMLST locate

READ VTOC CAMLST search

The following shows the applicable command descriptions for the Execution Queue:

Applicable Command Description

Flush Process Terminates and deletes an executing Process

Select Process Displays Process status and state

Suspend Process Terminates and moves an executing Process on the hold queue

Hold QueueThe following table shows the IBM Connect:Direct Status values for the Hold Queue:

Status Value Explanation

HC (Held for Call) Process is submitted with HOLD=CALL specified.

A session started from either node causes IBM Connect:Direct to place thisProcess on the wait queue in WC status, and eventually in the executionqueue (EX) when the first Process finishes.

Note: If the SNODE is defined with a null IP address, the Processes willbe released serially. Refer to the HOLD parameter in SUBMIT Command formore information.

HE (Held in Error) The Process was submitted and received an error unrelated to allocationor session errors. The Process is being checkpointed and REQUEUE=YESis specified. A common error that causes IBM Connect:Direct to place theProcess in HE status is an out of space condition (Sx37 ABEND).

HI (Held Initially) Process is submitted with HOLD=YES specified.

HO (Held by Operator) An exception response is sent from the other node during FMH exchangesat Process negotiation or step termination. It also occurs if an FMH isinvalid or is sent out of sync, or if the remote node is not defined in thenetwork map.

HP (Held due to ProcessError)

An exception response is sent from the other node during EXIT exchangesat Process negotiation or step termination. HP also occurs if an EXIT isinvalid, sent out of sync, or if the remote node is not defined in the Networkmap.

HR (Held Retain) Process is submitted with RETAIN=YES specified or being held for Processretry (intelligent retry).

614 IBM Connect:Direct for z/OS: Documentation

Status Value Explanation

HS (Held for Suspension) The operator issued a SUSPEND PROCess command. You can releasethe Process later. The Process will run (Held for Suspension) when IBMConnect:Direct is recycled.

RA (Held for Restart Dueto Allocation Error)

During Process execution, an allocation error occurred that matched thosespecified in the initialization parameters. This status enables the Process torestart after the allocation problem is resolved.

RH (Restart Held) Either the Process is being held awaiting a connection to an inactive nodeby the Intelligent Session Retry feature (see Intelligent Session Retry ) ora checkpointed Process is executing when an error such as a lost sessionor an I/O error occurred. This status enables the copy to restart when thesession is reestablished.

WC (Wait For Connection) Session establishment is attempted, including retries if specified, andfailed. The current Process is put on the wait queue (and later EX Q) if asession with that node is established later. It also can be released.

The following table shows the applicable commands for the Hold Queue:

Applicable Command Description

Change Process Modifies Process attributes

Delete Process Removes the Process from the queue

Select Process Displays Process status and state

Timer QueueThe following table shows the IBM Connect:Direct Status values for the Timer Queue:

Status Value Explanation

RE (Retry) The session with the SNODE is in the retry state. The number of and intervalbetween retries is specified in the initialization parameters. The Process can bein retry status for session establishment or for an allocation error.

WC (Wait ForConnection)

The Process is submitted with a start time or date (STARTT) that has notexpired. When the STARTT is reached, the Process is put on the wait queue forscheduling to the EX Q.

The following table shows the applicable commands for the Timer Queue:

Applicable Command Description

Change Process Modifies Process attributes

Delete Process Removes the Process from the queue

Select Process Displays Process status and state

Process RecoveryIBM Connect:Direct provides facilities to recover from most errors that occur during Process execution.Recovery from the point of failure is usually accomplished quickly. The following types of errors can occurduring normal operation:

• Link failure terminates a session between IBM Connect:Direct systems• File I/O error occurs during Process execution• IBM Connect:Direct abends because of a hardware or other error

Chapter 5. User Guide 615

• TCQ Corruption

IBM Connect:Direct provides the following facilities to address errors:

Facility Description

Sessionestablishmentretry

When one or more Processes run with a node, IBM Connect:Direct establishes asession with that node and begins execution. If IBM Connect:Direct cannot startthe session, IBM Connect:Direct retries the session establishment. The initializationparameters, MAXRETRIES and WTRETRIES, determine the number of retries and theinterval between retries.

If IBM Connect:Direct cannot establish a session after all retries are exhausted,the Process is placed in the Hold queue in the TCQ with a status of Waiting forConnection (WC). When a session is established with the other node, all otherProcesses are scanned and the highest priority Process is executed after theprevious Process is finished.

VTAM automaticsession retry

If Process execution is interrupted because of a VTAM session failure, IBMConnect:Direct automatically attempts to restart the session. This recovery facilityuses the same parameter values as the session establishment retry facility.

If IBM Connect:Direct cannot establish the session, the Process that is executing andany other Processes that are ready to run with the other node are placed in the Holdqueue with a status of Waiting for Connection (WC).

TCQ/TCX RepairUtility

When the TCQ becomes corrupt because of an outage or other circumstance, IBMConnect:Direct may abend in production or during the next DTF initialization. TheIBM Connect:Direct administrator can use the TCQ/TCX repair utility to removeambiguous or corrupt data and avoid having to cold start the DTF and reinitializethe TCQ, thus losing any Processes left in the TCQ.

Process stepcheckpoint

As a Process executes, IBM Connect:Direct records which step is executing in theTCQ. If Process execution is interrupted for any reason, the Process is held inthe TCQ. When the Process is available for execution again, IBM Connect:Directautomatically begins execution at that step.

COPY statementcheckpoint/restart

For physical sequential files and partitioned data sets, IBM Connect:Direct collectspositioning checkpoint information at specified intervals as a COPY statementexecutes. Checkpoints are taken for each member that is transferred within a PDS,regardless of the checkpoint interval. If the copying procedure is interrupted for anyreason, you can restart it at the last checkpoint position.

Note: Whenever a Process step is interrupted and restarted, some data will beretransmitted. Statistics records for the Process step will reflect the actual bytestransferred, and not the size of the file.

The COPY statement checkpoint/restart works in conjunction with step restart.The restart is automatic if IBM Connect:Direct can reestablish a session based onthe initialization parameter values for MAXRETRIES and WTRETRIES. See COPYStatement Checkpoint/Restart Facility for more information.

The CHANGE PROCESS command can also invoke the checkpoint/restart facility. SeeControlling Processes with Commands for instructions on how to use the CHANGEPROCESS command.

Note: Checkpoint/restart is not supported for I/O exits at this time.

COPY Statement Checkpoint/Restart FacilityThe checkpoint/restart facility includes the following elements:

• Initialization parameters

616 IBM Connect:Direct for z/OS: Documentation

• Checkpoint/restart file• Copy statement checkpoint parameters

Initialization ParametersIBM Connect:Direct uses the following initialization parameters with the COPY statement checkpoint/restart facility:

Parameter Description

CKPT.MODE Specifies whether the checkpoint function is performed when IBM Connect:Directis transferring a file in record mode or block mode. (Record mode transfer isused when reblocking of the output file is specified.) It also specifies whether thecheckpoint function is performed for partitioned data sets and if so, what type.Automatic checkpointing of VSAM files is supported.

This parameter does not apply to TCP/IP and LU6.2 connections. With TCP/IP andLU6.2 connections, checkpointing is based on the checkpoint interval requested(regardless of the data set type or whether it is in block or record format) and onboth nodes' ability to perform the checkpoint function. When both nodes agree todo checkpointing, the checkpoint interval is controlled by the sending node whilecheckpoint record filing is done on the receiving node.

CKPT Specifies the default interval for checkpointing when it is not specified on the COPYstatement.

You should specify the CKPT value as a multiple of the value specified for theV2.BUFSIZE initialization parameter. If you do not, performance can seriouslydeteriorate.

Note: Be aware of additional overhead associated with specifying too small acheckpoint interval, particularly when transferring large files.

Note: For sequential files, try to avoid using a CKPT value less than:

BLKSIZE * NCP * 10

where NCP is the number of buffers for reading data from or writing data toa sequential data set using BSAM

For more information, search on Improving Performance in the IBM Connect:Directfor z/OS Administration Guide.

CKPT.DAYS Specifies the amount of time that checkpoint records are kept if they are notdeleted. IBM Connect:Direct automatically deletes checkpoint records when aProcess is restarted and runs to a successful completion.

CKPTDSN Specifies the name of the checkpoint/restart file that holds checkpoint recordsduring execution of the COPY statement.

For detailed information about these parameters, search on Global Initialization Parameters in the IBMConnect:Direct for z/OS Administration Guide.

Checkpoint/Restart FileThe IBM Connect:Direct checkpoint/restart file contains positioning information for both files involvedin executing a COPY statement. IBM Connect:Direct maintains the checkpoint records throughout datatransmission and deletes them when a transmission completes successfully.

Note: Checkpoints take place on the receiving end of a transfer. During restart, this information isexchanged with the sender so that appropriate positioning can take place.

Chapter 5. User Guide 617

A checkpoint record can be left in the Checkpoint file if an interrupted Process is deleted by the operator.IBM Connect:Direct scans the checkpoint records during initialization and deletes records older than thevalue specified in the CKPT.DAYS initialization parameter.

COPY Statement ParametersThe CKPT and REQUEUE parameters of the COPY statement also control aspects of the Checkpoint/Restart facility. The following table describes these parameters.

COPY statement parameters

Parameter Description

CKPT Specifies the interval IBM Connect:Direct uses to record checkpoint information.IBM Connect:Direct uses this CKPT value, rounded to the nearest block, indetermining how many bytes to transfer before taking a checkpoint.

If you do not specify the Copy statement CKPT parameter, IBM Connect:Directuses the value specified in the CKPT initialization parameter. Specifying a valueof CKPT=0K, or not specifying CKPT in the initialization parameters, disablescheckpointing. Be aware of additional overhead associated with specifying toosmall a checkpoint interval, particularly when transferring large files.

REQUEUE Indicates whether IBM Connect:Direct requeues Processes that end due to anABEND, such as an Sx37, or enables any subsequent steps to run to Processtermination. This parameter is only effective if checkpointing is in use. See theConnect:Direct Process Language help for more information.

Checkpoint/Restart Examples for TCP/IP or LU6.2 TransfersThe following examples describe how checkpoint/restart works for different transfer types.

TCP/IP or LU6.2 TransfersIn the case of transfers using TCP/IP IBM Connect:Direct sends approximately 30 bytes of overhead aftersending an amount of data equal to the checkpoint interval in effect. Therefore, if the file size is 3 millionbytes and the checkpoint interval is 10k, then 30 bytes of overhead is sent 300 times, resulting in a totaloverhead of 9000 bytes.

Other TransfersFor other transfers (LU0 or transfers to MS-DOS), IBM Connect:Direct sends an additional seven bytesper block or ten bytes per record of overhead during data transfer. Data is sent in record mode whenreblocking is taking place during transfer (source and destination block sizes differ). When no reblockingis taking place, IBM Connect:Direct sends in block mode.

When you enable checkpointing, IBM Connect:Direct transfers positioning information in addition to thefile. The positioning information enables IBM Connect:Direct to reposition the file in the event of aninterruption. The following examples show how to determine this overhead in number of bytes whenusing Checkpoint/Restart for non-TCP/IP transfers.

In the following table, IBM Connect:Direct checkpoints the file in block mode and adds seven bytes toeach block transmitted. This functionality adds only 2,100 bytes to the transmission of almost 6 millionbytes.

File Attributes Sending File Receiving File

BLKSIZE 19,069 19,069

LRECL 0 0

DSORG PS PS

618 IBM Connect:Direct for z/OS: Documentation

File Attributes Sending File Receiving File

RECFM U U

FILE SIZE 300 blocks 300 blocks

In the following table, IBM Connect:Direct checkpoints the file in record mode because the data is beingreblocked. IBM Connect:Direct adds 10 bytes to each record being transmitted. This functionality adds150,000 bytes to the transmission, or 5 percent overall.

File Attributes Sending File Receiving File

BLKSIZE 5,000 2,000

LRECL 200 200

DSORG PS PS

RECFM FB FB

FILE SIZE 600 blocks 1,500 blocks

RUN TASK Checkpoint/RestartConnect:Direct for z/OS also offers a checkpoint/restart feature with the RUN TASK Process statement.

If a RUN TASK program is executing on the SNODE and a session failure occurs, the PNODE recognizesthe session failure and puts the Process in the Timer queue for retry. The SNODE, however, is still runningthe RUN TASK program and is not aware of the session failure until the program finishes. The checkpoint/restart feature for RUN TASK ensures that when the Process restarts on the PNODE, the RUN TASKprogram does not execute a second time on the SNODE.

RUN TASK Checkpoint RecordsIBM Connect:Direct always writes a checkpoint record on the node where the RUN TASK programexecutes. The initial checkpoint record is written upon entry to DGADRNT$, the module that handlesthe RUN TASK Process statement. IBM Connect:Direct updates the checkpoint record before attachingthe program that is to execute. When the RUN TASK program finishes, IBM Connect:Direct updates thecheckpoint record again.

RUN TASK RestartIf a RUN TASK Process step restarts, the node where the program executes attempts to find thecheckpoint record in the checkpoint file. If the RUN TASK step is still executing, the Process that isrunning for the restart of the step waits for the RUN TASK program to finish the first task and then proceedto the next step of the Process.

At Process restart for a RUN TASK step, if the program is still executing, you see two Processes in theEX queue for the same Process step. The first Process is executing the program. The second Process iswaiting for the first Process to complete. When the first Process completes, it determines that the sessionit was running under is lost and posts the second Process. The second Process records how the RUN TASKstep that is still executing ended, and proceeds to the next step in the Process.

Re-execution of the RUN TASKThe RUN TASK step does not execute again if it is determined at restart that the RUN TASK step endedbecause it finished before the PNODE restarted the Process. However, if the RUN TASK program didnot complete and is not currently running, then the RESTART parameter determines the restart of theProcess.

Also, if at restart, IBM Connect:Direct cannot find the checkpoint record and the RUN TASK programis not executing, IBM Connect:Direct is unable to determine what action to take for the restart. If IBMConnect:Direct cannot determine what action to take for the restart, it uses the RESTART parameter. Youcan code the RESTART parameter on the RUN TASK step or in the initialization parameters.

Chapter 5. User Guide 619

Note: If you code the RESTART parameter on the RUN TASK step, it overrides the initialization parameter.When you code RESTART=YES, IBM Connect:Direct executes the program again. When you codeRESTART=NO, the Process skips the RUN TASK step.

Search on Global Initialization Parameters in the IBM Connect:Direct for z/OS Administration Guide fordetailed information about the RUNTASK.RESTART initialization parameter.

Process Results and StatisticsThe SELECT STATISTICS command is used to retrieve statistics records. Use this command to see theresults of a Process that has finished executing.

Note: The IBM Connect:Direct Activity Reporting System (ARS) produces detailed statistics reports.

You can also use the Connect:Direct Browser User Interface to perform some Connect:Direct for z/OSprocedures.

Statistics Log RecordsIBM Connect:Direct keeps a record of operations and activity in a Statistics Log file. This file contains thefollowing record types:

Record Type Provides Statistics About

Process Submit The submitted Process

Member Copy Transmission of a PDS member

Copy How the COPY statement completed

Process Duration How the Process completed

Run Job A job submitted to the z/OS internal reader (JES)

Run Task A program attached to the Process as a subtask

Submit within Process A Process that is submitted within another Process

InterConnect OptionResults

Processes created by the InterConnect Option

External Record Logged from External Source via WRITE EXSTATS command

For a table of statistics record types, refer to “IBM Connect:Direct Exits” on page 322.

Statistics Records ContentThe statistics records include the following information:

• In all records:

– Record type or function– Date and Time of record logging– Process name and number, if specified– SMFID, if specified– User ID– Other node (secondary or primary) involved in the Process– Start and stop time of the function– Highest or final completion code and message– Step label name, if one is specified

• In the Member Copy record, the input and output member names

620 IBM Connect:Direct for z/OS: Documentation

• In the Process Submit and Submit Within records, the submitted PDS DSN and member name• In the Copy record:

– The number of records or blocks read from or written to the file, and whether the transfer wasperformed in block or record mode

– The number of I/O bytes that were read or written from disk or tape– The number of VTAM bytes sent or received during the session, including IBM Connect:Direct and

VTAM control information– The RUSIZE

The size displayed is not the actual RUSIZE used by the transfer but rather the RUSIZE indicated bythe LOGMODE. VTAM can negotiate for a smaller RUSIZE.

– The compression percentage

This percentage is calculated by evaluating the number of VTAM bytes and the number of I/O bytes.If the number of VTAM bytes is less than or equal to the number of I/O bytes, a positive compressionpercentage is calculated as:

Compression Percentage = (1 – {VTAM Bytes ³ I/O Bytes} ) x 100

If the number of VTAM bytes is greater than the number of I/O bytes, a negative compression iscalculated as:

Compression Percentage = – (1 – {I/O Bytes ÷ VTAM Bytes} )x 100

The compression percentage values displayed in the Copy Termination record differ depending on thefile attributes specified. A negative compression percentage means that more bytes are sent than areread from the file. This includes IBM Connect:Direct control information.

Elapsed Time SignificanceUse the following table to interpret the elapsed time between the start and stop times for the differentrecord types:

Record Type Interpretation

For Copy Termination The elapsed time includes file allocation on both nodes and the time required tomount a tape, when required.

For Run Task or RunJob

The elapsed time indicates the time it took to run the task or job before controlreturned to IBM Connect:Direct.

For Submit withinProcess

The elapsed time indicates the time it took to submit the Process to the TCQ.

For an ESF ProcessSubmit

The start time is when the submit was performed (the Process was added to theTCQ). The stop time is when the Process was first added to the Process queue.

InterConnect Option RecordsThe InterConnect Option (ICO) routes files from a IBM Connect:Direct node to an IBMConnect:Enterprise® Secure Client node for distribution, distributes batches to a Connect:Direct node,and provides notification of success or failure of the Process. The InterConnect software copies the entirecontent of the SYSPRINT file of the IBM Connect:Enterprise Secure Client batch utility, STOUTL, into theIBM Connect:Direct Statistics file.

This report from STOUTL is displayed as a block by IBM Connect:Direct. The InterConnect Optionsoftware imposes a limit of 500 lines for the report. These reports are retrievable only through theSELECT STATISTICS command FILE option for batch, and the DISPLAY option for the IUI. Search on

Chapter 5. User Guide 621

Offline Utilities in the IBM Connect:Enterprise for z/OS User’s Guide for samples of the output reportsfrom the ADD and EXTRACT functions.

Additional statistics records related to the InterConnect Option are written to the statistics facility. For alist of those statistics records, search on Using IBM Connect:Direct Exits in the IBM Connect:Direct forz/OS Administration Guide.

Note: If you specify a statistics exit in the initialization parameters, the LF and RO records are passed tothe exit.

External record

From version 6.2 onwards, Connect:Direct supports logging of statistics records from external sources.User can write statistics records from external sources via command WRITE EXSTATS. Following 40statistics record identifiers (say Y-series) are reserved for external statistics.

YA YB YC YD YE YF(reservedforFileAgent)

YG YH YI YJ

YK YL YM YN YO YP YQ YR YS YT

YU YV YW YX YY YZ Y0 Y1 Y2 Y3

Y4 Y5 Y6 Y7 Y8 Y9 Y@ Y# Y$ Y%

External records are retrievable through the SELECT STATISTICS command option for batch, and theDISPLAY option for the IUI.

SELECT STATISTICS CommandUse the SELECT STATISTICS command to retrieve and examine statistic log records. You can selectrecords based on certain conditions and indicate if you want the output displayed, printed, or saved in afile for later processing. See information about the FILE subparameter in Indicating Output Destination forhow to save your output in a file for processing later.

SELECT STATISTICS Command FormatSELECT STATISTICS has the following format and parameters. The required parameters and keywords arein bold print. Default values for parameters and subparameters are underlined.

622 IBM Connect:Direct for z/OS: Documentation

Label Command Parameters subparameters

(optional)

SELectSTATistics

WHERE(subparameters)

ARCHDSN = dsname | (list)CASE = YES | NOCCODE = (condition,completion code)EXCLUDE = (MEMber | MCR) | (WTO) | (NOTWTO) | (list)FNAME = dsname | (list) | *MSGID = ID | (list)PNAME = name | (list)PNUMber = number | (list)SERVER = server name | (list)SNODE = name | (list)STARTT = ([date|day][,hh:mm:ssXM])STOPT = ([date | day][,hh:mm:ssXM])TYPE = ID | (list) | *USER = name | (list)

FILE | PRint |TABle |SUMmary

Note: These parameters are mutually exclusive - only one of themmust be specified.

(optional)

SELectSTATistics

WHERE2(subparameters)

ANODE = name | (list)ARCHDSN = dsname | (list)CASE=YES | NOCCODE = (condition , completion code)EXCLUDE = (MEMBer) | (MCR) | (WTO) | (NOTWTO) | (list)FNAME = dsname | (list)FNODE = name | (list)LNODE = name | (list)MSGID = ID | (list)PNAME = name | (list)PNODE = name | (list)PNUMber = number | (list)RNODE = name | (list)SERVER = server name | (list)SNODE = name | (list)STARTT = ([date | day][,hh:mm:ssXM])STOPT = ([date | day][,hh:mm:ssXM])TNODE = name | (list)TYPE = ID | (list)UNODE = name | (list)USER = name | (list)

FILE | PRint |TABle |SUMmary

Note: These parameters are mutually exclusive - only one of themmust be specified.

The following table describes the SELECT STATISTICS command parameters:

Parameter Description

WHERESpecifies which statistics records to examine. This parameter or WHERE2 isrequired. The subparameters, such as PNAME, PNUMBER, and STARTT, areoptional, but you must include at least one subparameter. WHERE namesubparameters only support the generic character asterisk (*) and it is limited tothe end of the name.

Chapter 5. User Guide 623

Parameter Description

WHERE2 Specifies which statistics records to examine. This parameter or WHERE isrequired. WHERE2 supports the same subparameters as WHERE, in addition tothe following sub-parameters: ANODE, FNODE, LNODE, PNODE, RNODE, TNODEand UNODE. When these subparameters are specified, they can use extendedgenerics support. Also, when specified as a WHERE2 subparameter, SNODE canuse extended generics support. Ex-tended generics support allows one or moreasterisks (*) and/or percent signs (%) anywhere in the name. An asterisk standsfor any number of characters. A percent sign stands for one character. The defaultrecord types selected by WHERE2 are the same as those for WHERE.

FILE | PRint | TABle |SUMmary

Specifies the output format. Indicate only one. TABLE is the default. Thisparameter is optional.

See Indicating Output Destination for an explanation of the output produced by theselection of the FILE, PRINT, and TABLE parameters. The SUMMARY parameterproduces a 3-line summary per statistics record, similar to the example onStatistics Log Records.

The reports from Connect:Enterprise are retrievable only through the FILE optionfor batch and the DISPLAY option for the IUI.

The following table describes the SELECT STATISTICS command sub-parameters:

Parameter Description

ANODE=name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name is any of the following: PNODE, SNODE or UNODE. You can specifya list of names by enclosing them in parentheses. ANODE names can contain lowercasecharacters and supports extended generics.

ANODE supports extended generics. For example, if you specify ANODE=CD.TEST%.NODE,then records with CD.TEST1.NODE in the PNODE, SNODE or UNODE field are selected. Toselect CD.TEST12.NODE, specify ANODE=CD.TEST%%.NODE or ANODE=CD.TEST*.NODE orCD.TEST* or any of other extended generic specification.

Note: ANODE is only allowed as a WHERE2 subparameter.

ARCHDSN=dsname | (list)

Specifies that IBM Connect:Direct is to search the archived statistics files named, instead ofthe statistics log currently in use by the DTF. Archived statistics files store old statisticsdata that is no longer active in the statistics log. See your system administrator forinformation about the availability of archived statistics at your site, and for the data setnames you can specify with the ARCHDSN subparameter.

CASE=YES | NO Specifies whether lowercase or mixed-case data is permitted for the USER, ANODE,FNODE, LNODE, PNODE, RNODE, SNODE, TNODE, UNODE, and FNAME subparameters.The CASE subparameter overrides the global CASE option defined at signon for the purposeof the SELECT STATISTICS command.

YES folds the data in USER, ANODE, FNODE, LNODE, PNODE, RNODE, SNODE, TNODE,UNODE, and FNAME to uppercase regardless of the actual data specified.

NO preserves the actual case typed for the USER, ANODE, FNODE, LNODE, PNODE, RNODE,SNODE, TNODE, UNODE, and FNAME subparameters. The CASE defaults to the settingdefined within the session defaults if nothing is specified.

624 IBM Connect:Direct for z/OS: Documentation

Parameter Description

CCODE =(condition,completion code)

Specifies selection by completion code.

condition specifies a relationship to the completion code given in the subsequentpositional parameter.

The options for specifying condition include:

GT for greater thanLT for less thanEQ for equal toNE for not equal toGE for greater than or equal toLE for less than or equal to

completion specifies a decimal value 1 to 2,147,483,647 to allow for all completion codesthat the RUN TASK statement can pass. This last value represents a maximum 31-bit binarynumber.

For example, if CCODE = (EQ,12) is specified, records that have a Comp Code of 0000000Care selected.

For another example, if CCODE = (GT,0) is specified, you see statistics records in which thestep completion code is greater than zero, as long as the records also meet other specifiedcriteria.

EXCLUDE =(MEMBer | MCR)| (WTO) |(NOTWTO) | (list)

Specifies to exclude certain statistics from selection. Specify a list of excluded options byenclosing them in parentheses and separating them by a space or a comma. To select allstatistics, omit the EXCLUDE parameter from the SELECT STATISTICS command. The TYPEparameter overrides the EXCLUDE specifications.

MEMBer | MCR specifies whether or not to exclude the PDS member copy record for PDScopies on the statistics report.

WTO specifies that Connect:Direct write-to-operator (WTO) messages are excluded fromthe SELECT STATISTICS command. Dynamic allocation messages are represented as WTOsin the statistics file.

NOTWTO specifies that only WTO records are displayed that is, exclude everything that isNOT a WTO record.

FNAME=dsname |(list)

Limits the selected statistics records to those that contain the specified file name. TheFNAME subparameter is meaningful for the following record types:

CT Copy TerminationRJ Run JobSD Start IBM Connect:DirectSW Submit within Process

The meaning of the file name within these records is unique for each record type. Forexample, the Run Job record contains the file name of the submitted JCL. Filenames can beup to 254 characters in length and can contain lowercase characters.

FNAME supports use of limited generic specification using an asterisk (*) at the end of thedsname. For example, if you specify TEST.F1*, then all dsnames with first seven charactersas TEST.F1 are selected.

Chapter 5. User Guide 625

Parameter Description

FNODE =name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name was the FROM (sending) node (CI, CT, FA, MC records), or wasthe execution node (RJ, RT records). You can specify a list of names by enclosing themin parentheses. FNODE names can contain lowercase characters and supports extendedgenerics.

Note: FNODE is only allowed as a WHERE2 subparameter.

LNODE=name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name was the LOCAL (or this) node. You can specify a list of namesby enclosing them in parentheses. LNODE names can contain lowercase characters andsupports extended generics.

Note: LNODE is only allowed as a WHERE2 subparameter.

MSGID = ID |(list)

Specifies selection by message ID. You can specify a list of message IDs by enclosingthem in parentheses. You can use a generic specification in the MSGID parameter using anasterisk (*) at the end of the ID. For example, if you specify SCPA*, then MSGIDs with SCPAin the first four characters of the message ID are selected.

PNAME=name |(list)

Specifies selection by Process name. You can specify a list of Processes by enclosing themin parentheses. You can use a generic specification in the PNAME parameter by using anasterisk (*) at the end of the name. For example, if you specify PNAME=TEST*,then recordswith TEST in the first four characters of the Process name field are selected regardless ofthe contents of the remaining characters. Records having TEST, TEST123, and TESTX allsatisfy this selection criterion.

PNODE=name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name was PNODE. You can specify a list of names by enclosing themin parentheses. PNODE names can contain lowercase characters and supports extendedgenerics.

Note: PNODE is only allowed as a WHERE2 subparameter

PNUMber =number | (list)

Specifies selection by Process number. You can specify a list of Processes by enclosingthem in parentheses. The range is 1–199999.

RNODE=name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name was a REMOTE (or the other) node. You can specify a list of namesby enclosing them in parentheses. RNODE names can contain lowercase characters andsupport extended generics.

Note: RNODE is only allowed as a WHERE2 subparameter.

SERVER = servername

Specifies the name of the IBM Connect:Direct member where the statistics are generated.The server name is a 1–8 character name assigned to each IBM Connect:Direct Serverthrough the CDPLEX.SERVER initialization parameter. This parameter is required in a IBMConnect:Direct/Plex.

626 IBM Connect:Direct for z/OS: Documentation

Parameter Description

SNODE = name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name was the SNODE. You can specify a list of names by enclosing themin parentheses. SNODE names can contain lowercase characters and supports extendedgenerics when specified as a WHERE2 subparameter.

SNODE supports limited generics when specified as a WHERE subparameter. Use limitedgeneric specifications by placing an asterisk (*) at the end of the name. For example, if youspecify SNODE=DALLAS*, then records with DALLAS in the first six characters of the SNODEfield are selected regardless of the contents of the remaining characters. Records havingDALLAS.PROD, DALLAS.TEST, and DALLAS all satisfy this selection criterion.

STARTT =([date | day][,hh:mm:ssXM])

Specifies selection by designated starting date and time. The date or day and time arepositional parameters. If you do not specify the date or day, precede the time with acomma.

date specifies the date to execute the Process. You can specify the day (dd), month (mm),and year (yy for 2-digit year and yyyy for 4-digit year). You can use periods or backslashes(/) to separate the components of a date value. You can omit the separators only fortransfers between mainframe nodes. Use separators to guarantee transfers betweenall platforms.You can use the following date formats, according to which date order isspecified in the DATEFORM initialization parameter:

• DATEFORM=MDY specifies the date format as mm/dd/yy, mm/dd/yyyy, mm.dd.yy, ormm.dd.yyyy

• DATEFORM=DMY specifies the date format as dd/mm/yy, dd/mm/yyyy, dd.mm.yy, ordd.mm.yyyy

• DATEFORM=YMD specifies the date format as yy/mm/dd, yyyy/mm/dd, yy.mm.dd, oryyyy.mm.dd

• DATEFORM=YDM specifies the date format as yy/dd/mm, yyyy/dd/mm, yy.dd.mm, oryyyy.dd.mm

Valid Julian dates formats are yyddd, yyyyddd, yy/ddd, yyyy/ddd, yy.ddd, or yyyy.ddd.

If you do not specify the DATEFORM parameter, Connect:Direct for z/OS defaults to MDYdate format.

day specifies the day of the week to select. Valid names include MOnday, TUesday,WEdnesday, THursday, FRiday, SAturday, and SUnday. You can also specify YESTER tosearch for statistics records created yesterday or TODAY to start the search at recordscreated today.

hh:mm:ssXM indicates the time of day in hours (hh), minutes (mm), and seconds (ss) toselect. Set XM to AM or PM. You can use the 24-hour clock or the 12-hour clock. If you usethe 24-hour clock, valid times are 00:00-24:00. If you use the 12-hour clock, 1:00 hoursare expressed as 1:00AM, and 13:00 hours are expressed as 1PM. If you use neither AMor PM, IBM Connect:Direct assumes the 24-hour clock. You do not have to specify minutesand seconds.

You can also specify NOON, which searches for the statistics records at noon, orMIDNIGHT, which searches for the statistics records at midnight.

If you do not specify a start date, the start date will be Jan 0, 0000. If you do not specifya start time, the start time will be 00:00:00. If you specify neither, the start date and timewill be Jan 0, 0000 00:00:00. If the start date and time is after the current system date andtime, searching will be bypassed, and so nothing will be selected. If you specify a day of theweek, it is always resolved to the current date or a prior date, never a future date.

Chapter 5. User Guide 627

Parameter Description

STOPT =([date | day][,hh:mm:ssXM])

Specifies a search for statistics records up to and including the designated date, day, andtime positional parameters. If you do not specify the date or day, place a comma before thetime.

The date and time formats are the same as the STARTT parameter. The time default is24:00:00, the end of the day.

If you do not specify a stop time, it will be 23:59:59.99. Otherwise, it will be the timespecified. Either way, this time is only provisional.

If you do not specify a stop date, it will be the current system date. Otherwise it will be thedate specified. Either way, this date is only provisional.

If the provisional stop date and time is after the current system date and time, latter isused. Otherwise, the provisional date and time are used.

If you specify a day of the week, it is always resolved to the current date or a prior date,never a future date.

TNODE =name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name was the TO (receiving) node (CI, CT, FA, MC records), or was thenon-execution node (RJ, RT records). You can specify a list of names by enclosing themin parentheses. TNODE names can contain lowercase characters and supports extendedgenerics.

Note: TNODE is only allowed as a WHERE2 subparameter.

TYPE = ID | (list) |*

Specifies the statistics record types to select. Every statistics record IBM Connect:Directgenerates has an associated record-type identifier. Each identifier is two characterslong and indicates the event or function that generated the record. The identifier alsoindicates the record format and contents. Use TYPE= * to view all record types. TheTYPE subparameter specifies which record types to select, and overrides the EXCLUDEparameter. When you do not specify a TYPE, the record types selected are determinedby the output option chosen, and can be affected by the EXCLUDE subparameter. Whenyou specify the PRINT or TABLE output option, the types in the following table areselected. Specify FILE for the output option to select all available types. Use the EXCLUDEsubparameter to exclude certain types that the output option included.

For a list of statistics record type identifiers, search on Statistics Records in the IBMConnect:Direct for z/OS Administration Guide.

UNODE = name |(list)

Limits the selected statistics records to those that are written for processes where thespecified node name was the UNODE. You can specify a list of names by enclosing themin parentheses. UNODE names can contain lowercase characters and supports extendedgenerics.

Note: UNODE is only allowed as a WHERE2 subparameter.

Note: For Process oriented records, UNODE is the Submitter’s node and for commandoriented records, UNODE is the node where the command was issued.

USER = name |(list)

Limits the selected statistics records to those that are written for users with the specifiedname. You can specify a list of names by enclosing them in parentheses. Use genericspecifications by placing an asterisk (*) at the end of the name. For example, if you specifyUSER = SYS$*, then records with SYS$in the first four characters of the USER field areselected regardless of the contents of the remaining characters. Records having SYS$BOB,SYS$ADM, and SYS$0001 all satisfy this selection criterion. USER names can be up to 64characters in length and can contain lowercase characters.

628 IBM Connect:Direct for z/OS: Documentation

Using SELECT STATISTICS through the Batch InterfaceTo use the SELECT STATISTICS command from the Batch Interface, perform the following steps:

1. Place commands in the DGADBATC job stream as described in “Sample job stream to run the batchinterface” on page 525.

2. Submit the job while IBM Connect:Direct is running.

SELECT STATISTICS Command ExamplesThe following command searches for statistics records based on start and stop date and time, andexcludes write-to-operator statistics messages.

SEL STAT WHERE ( - EXCLUDE=(WTO) - STARTT=(11/24/2003,06:45:00) - STOPT=(11/25/2003,8AM) - )

The following command searches for statistics records based on start and stop date and time, andexcludes write-to-operator and PDS member copy statistics records.

SEL STAT WHERE (- EXCLUDE=(WTO,MEMB) - STARTT=(11/21/2003,15:25:00) - STOPT=(11/25/2003,15:30:00) - )

The following command searches for statistics records based on Process name, and start and stop dateand time. It excludes write-to-operator statistics messages.

SEL STAT WHERE ( - EXCLUDE=(WTO) - PNAME=BILLING - STARTT=(12/28/2003,06:00) - STOPT=(12/28/2003,23:00) - )

The following command searches for signon records for the user Mary.

SEL STAT WHERE (USER=MARY, TYPE=SI) TABLE

The following command searches are identical and both select only WTO records.

SEL STAT WHERE (TYPE=WO) TABLESEL STAT WHERE (EXCLUDE=(NOTWTO)) TABLE

The following command searches for statistics records based on Process start/stop date and time that ranon a IBM Connect:Direct Server named SERVER1.

SEL STAT WHERE ( - SERVER=SERVER1 - STARTT=(12/28/2003,06:00) - STOPT=(12/28/2003,23:00) - )

The following command searches for Process submission records for Processes in which the SNODEis any node in Dallas, and prints the output. Assume that the site administrator indicates that the

Chapter 5. User Guide 629

November statistics records are contained in a file pair whose key sequenced data set is namedSYS.ARCH.STATS.M9611. For an explanation of statistics file pairs, search on Administering Statisticsin the IBM Connect:Direct for z/OS Administration Guide.

SEL STAT WHERE ( - TYPE=(PS,SW) - SNODE=DALLAS* - ARCHDSN=SYS.ARCH.STATS.M9611 - ) PRINT

The following command searches for signon and signoff records that match today’s date and the User IDSEAN.

SEL STAT WHERE ( - TYPE=(SI,SO) - USER=SEAN - STARTT=(TODAY) - STOPT=(TODAY,24:00:00) - ) TABLE

The following command searches for the message ID SCMG010I and all message IDs that begin withSCPA.

SEL STAT WHERE ( - MSGID=(SCMG010I, SCPA*) - )

The following figure illustrates the commands for archiving statistics for a single day using the BatchInterface. These commands archive the statistics from the previous day into the preallocated data set ofthe API referenced by the DD DMTMPDSN.

SIGNON USERID=(USERID,PASSWORD) TMPDD=DMTMPDSN - NETMAP=HLQ.CD.NETMAPSELECT STAT WHERE (STARTT=(YESTERDAY,00:00:00) - STOPT=(YESTERDAY,24:00:00)) FILESIGNOFF

SELECT STATISTICS Sample OutputThe following shows sample output from a SELECT STATISTICS command.

================================================================================CDA.NODE1 SELECT STATISTICS DATE : 06.07.2021================================================================================Function (PS)=> Process Submit Start Time=> 01:36:04 06.07.2021Process Name => COPY1 Stop Time=> 01:36:04 06.07.2021Process Num => 1Comp Cod+Msg => 00000000 SSPA001ISubmit Job+ID=> USER1 TSU04779UserID => USER1SnodeID => NoPNode => CDA.NODE1 This Node => PSNode => CDB.SSARA1Submit Node => CDA.SSARA1Submitted DSN=> USER1.PROCESS================================================================================CDA.NODE1 SELECT STATISTICS DATE : 06.07.2021================================================================================Function,(CT)=> COPY Start Time=> 01:37:12 06.07.2021Process Name => COPY1 Stop Time=> 01:37:12 06.07.2021Process Num => 1Comp Cod+Msg => 00000000 SCPA000ISubmit Job+ID=> USER1 TSU04779SMFID => IRVOStep Name => PROCESS1UserID => USER1

630 IBM Connect:Direct for z/OS: Documentation

Pnode Version=> 6.02.00 Snode Version=> 6.01.00PNode => CDA.NODE1 This Node => PSNode => CDB.NODE1 From Node => PSubmit Node => CDA.NODE1Session Class=> 001Other addr => 10.120.130.42Other port => 32782

Session Protocol => TCPFASP => No Session is not with SSPV2 Buffer Size => 1,048,576Negotiated V2 Buffer Size => 32,768TCP Buffer Size Used => 2,097,152Compression Control Feature: ONNegotiated: NO Compression

TLS V1.2 Enabled => Yes Encrypt.Data=YTLS Ciphersuite => TLS_RSA_WITH_AES_256_GCM_SHA384Subject => (SN=60:9b:aa:4d:00:04:ce:9f/C=IN/ST=haryana/L=gurugram/O=capegemini/OU=aricent/CN=CDB_CERT/)Issuer => (C=IN/ST=haryana/L=gurugram/O=capegemini/OU=aricent/CN=CDB_CERT/)

From ( Pnode Dsn=>SMSTEST.DSN1) DCB => LRECL => 00080 BLKSIZE => 14960 RECFM => FB DSORG => PS Mgd => YES DSNTYPE => BASIC DISP=> (S, , ) recs => 39 blks => 1 Bytes Read => 3,120 Bytes Sent => 3,305 Cmpr Perc => - 5.6% VOL=SER => ARTS09 Time on CP => 00:00:00.149 Time on zIIP => 00:00:00.000 zIIP Qualify => 00:00:00.000To ( Snode Dsn=>SMSTEST.DSN2) DCB => LRECL => 00080 BLKSIZE => 27920 RECFM => FB DSORG => PS Mgd => YES DSNTYPE => BASIC DISP=> (R, , ) recs => 39 blks => 1Bytes Written => 3,120Bytes Received=> 3,305 Cmpr Perc => - 5.6% VOL=SER => ARTS0M Time on CP => 00:00:00.191 Time on zIIP => 00:00:00.000 zIIP Qualify => 00:00:00.000================================================================================CDA.NODE SELECT STATISTICS DATE : 06.07.2021================================================================================Function (PT)=> Process Termination Start Time=> 01:36:04 06.07.2021Process Name => COPY Stop Time=> 01:37:13 06.07.2021Process Num => 1 Submit Time=> 01:36:03 06.07.2021Comp Cod+Msg => 80B37000 SVTM100I Schedule Time=> (none)Submit Job+ID=> USER1 TSU04779SMFID => IRVOUserID => USER1PNode => CDA.USER1 This Node => PSNode => CDB.USER1Submit Node => CDA.USER1Session Class=> 001 Time on CP => 00:00:05.734Time on zIIP => 00:00:00.000zIIP Qualify => 00:00:00.000

Using SELECT STATISTICS through the IUIYou can use the Select Statistics screen to select, display, and print statistics information from IBMConnect:Direct activities.

To select, display, or print statistics information using the IUI:

1. Select option SS from the Primary Options Menu to display the Select Statistics screen.

Chapter 5. User Guide 631

node.name SELECT STATISTICS CMD ==> P hh:mm CMD: S ... SUMMARY TABLE D ... DISPLAY REPORT yyyy.mm.dd P ... PRINT REPORT yyyy.ddd PROCESS NUMBERS: ==> ______ ==> ______ ==> ______ ==> ______ PROCESS NAMES: ==> ________ ==> ________ ==> ________ ==> ________ START DATE ==> TODAY_____ ( YYYY.MM.DD ) START TIME ==> __________ (HH:MM:SSXM) STOP DATE ==> TODAY_____ ( YYYY.MM.DD ) STOP TIME ==> __________ (HH:MM:SSXM) CONDITION CODE: ==> __ ________ EXCLUDE ( MEMBER RECS ==> Y WTO RECS ==> Y ^WTO RECS ==> N ) CHANGE EXTENDED OPTS: ==> N

2. To access the Select Statistics Extended Options screen, type Y in the CHANGE EXTENDED OPTS field.On the command line, type the command for the output format that you want. The following tabledescribes each option:

Command Description

D Display the output on the screen.

P Send the output to the printer.

F View unformatted statistic records.

S Display a two-line summary per statistics record on the screen. See theStatistics Summary figure on Statistics Summary.

Note: The records from the InterConnect Option are only retrievable through the DISPLAY option.

The following table lists the statistics record types, their corresponding record type identifiers, andwhether they display through the Display Report command, or the Change Extended Opts field of theSelect Statistics screen.

Record ID Description DisplayReport

Change ExtendedOptions

CE Copy I/O Start Y

CH Change Process D Y

CI Copy Step Start Y

CS Statistics Command Y

CT Copy Termination D Y

CX Check Certificate Validity Y

DC Directory Commands Y

DP Delete Process D Y

DT Select Task Y

DU Delete User Y

EI Event Services Start Command Y

ET Event Services Stop Command Y

EV Event Services Command Y

FA IGWFAMS Message Y

FI Long File Name Record D Y

632 IBM Connect:Direct for z/OS: Documentation

Record ID Description DisplayReport

Change ExtendedOptions

FP Flush Process D Y

FS Suspend Process D Y

FT Flush Task D Y

GO Process Modal - GOTO, ELSE, or EXIT Statement Y

HW High Concurrent Session Count Y

IA Inquire Statistics Y

IB Inquire Debug Y

ID Inquire STATDIR Y

IF Process Modal - IF Statement Y

IP Inquire Initialization parameters Y

IT Inquire SNMP Trap Table Y

IU Insert User Y

IX Inquire IBM Connect:Direct/Plex Y

JI Run Job Start Y

LF ICO Log File Record Y

MC PDS Member Copy D Y

M2 Multiple Copy Record D Y

NL Process modal - EIF or PEND statement Y

NM NETMAP Updated Y

PE IBM Connect:Direct/Plex Error Record Y

PI PNODE Process Start Y

PR Performance Measurement Record Y

PS Process Submit D Y

PT PNODE Process Termination D Y

PX IBM Connect:Direct/Plex Activity (Leave or JoinIBM Connect:Direct/Plex)

Y

QE Queue Change to EXEC Queue Y

QH Queue Change to HOLD Queue Y

QP Queue Change to Process Retention Queue Y

QT Queue Change to TIMER Queue Y

QW Queue Change to WAIT Queue Y

RE ICO Report Record Y

RF Refresh/Update initialization parameters Y

RJ Run Job D Y

RO ICO Event Record Y

Chapter 5. User Guide 633

Record ID Description DisplayReport

Change ExtendedOptions

RT Run Task D Y

SB Session Begin Y

SC Statistics Control Record Y

SD Start IBM Connect:Direct Y

SE Session End Y

SF Statistics Format Y

SI Signon Y

SN Select Netmap Y

SO Signoff Y

SP Select Process Y

SS Select Statistics Y

ST Stop IBM Connect:Direct Y

SU Select User Y

SW Submit within a Process D Y

SY • SYSOPT PNODE• SYSOPT SNODE

D Y

S2 Statistics Logging Statistics Y

TF TCQ Threshold Full Y

TI Run Task Start Y

TL TCQ Threshold Low Y

TP Throughput Record Statistics D Y

TR Trap Event Record

TS Suspend Task Y

TW TCQ Threshold Warning Y

UM Update Network map Y

UU Update User Y

VP View Process Y

WO WTO D Y

WS Select Stat Command Y

XO Trace On/Off Y

ZI SNODE Process Start D Y

ZT SNODE Process Terminated D Y

The following screen is displayed if you selected Y in the CHANGE EXTENDED OPTS field.

634 IBM Connect:Direct for z/OS: Documentation

node.name SELECT STATISTICS EXTENDED OPTIONS CMD===> ________________________________________________________________ hh:mm yyyy.mm.dd yyyy.ddd RECORD ==> __ ==> __ ==> __ TYPES: ==> __ ==> __ ==> __ SNODE NAME: ==> ________________ MESSAGE ID: ==> ________ USER ID: ==> ________________________________________________________________ FILENAME: ==> ________________________________________________________________ SEARCH ==> ______________________________________________ ARCHIVED ==> ______________________________________________ DATASETS: ==> ______________________________________________ SERVER: ==> ________ DO YOU WANT THE VALUES OF THIS REQUEST TO BE CASE SENSITIVE? ==> N

See the SELECT STATISTICS parameters description on SELECT STATISTICS Command for informationon how to complete the fields, or press PF1 for Help.

Statistics SummaryIf you selected S to display a statistics summary, the following Statistics Summary screen is displayed:

----------------------STATISTICS SUMMARY--------------- ROW 1 TO 3 OF 3==> SCROLL ===> PAGE FUNCTION PNAME PNUMBER ----SUBMITTER NODE----OTHER.NODE----- USERID MSGID RTNCD END DATE/TIME P|SNODE SERVER------------------------------------------------------------------------------------ * RUN-TASK TESTMBR2 5 SC.MVS.QA5A AS400.CDQA62 RBELL1 SERVER1 ARTT003I 000000008 MM/DD/YY HH:MM:SS PNODE S COPY TESTMBR2 5 SC.MVS.QA5A AS400.CDQA62 RBELL1 SERVER2 SCPA001I 000000000 MM/DD/YY HH:MM:SS PNODE SUB-CMD TESTMBR2 5 SC.MVS.QA5A AS400.CDQA62 RBELL1 SERVER2 SSPA001I 000000000 MM/DD/YY HH:MM:SS PNODE

The first and second lines of each entry identify a Process by function, Process name and number,submitter node, other node, and user ID. The third line is the message ID, return code, ending date andtime of that Process, P|SNODE, and IBM Connect:Direct Server that the Process ran on. The P|SNODE fieldwill have either SNODE or PNODE depending on the record type as follows:

• Copy Term (CT) ------------- Node type of this record.• Process Submit (PS) -------- Node it was submitted on (always PNODE).• Process Term (PT) ---------- Node type of this record (always PNODE).• Process Term (ZT) ---------- Node type of this record (always SNODE).• Run Job (RJ) --------------- Node the job was submitted on.• Run Task (RT) -------------- Node the task was run on.• Submit within Process (SW) - Node the process was submitted on.

An asterisk (*) before the Process name indicates a nonzero return-code. You can type M next to theProcess name to display a description of the message ID associated with the Process as in the followingfigure.

Chapter 5. User Guide 635

node.name Connect:Direct (TM) MESSAGE DISPLAY hh:mm CMD ==> MSGID ==> SVSL003I MODULE ==> DMVSOPEN Copy requested DISP=(,CATLG) to already cataloged dataset. The PROCESS COPY step requested a DISP=(,CATLG) on the TO clause of the COPY statement. The requested dataset already exists as a cataloged dataset. System Action. The PROCESS COPY step is terminated with a completion code of 8. Response: Either correct the COPY dataset or uncatalog the existing dataset and re-submit the PROCESS.

Display StatisticsIf you typed D to display the output on screen and specified only the CT record type, it is formatted asshown in the following example.

Note: The statistics display function supports 133 character records and horizontal scrolling using thestandard ISPF scrolling function keys.

================================================================================ CD.NODEA SELECT STATISTICS DATE : 03.30.2020 ================================================================================ Function => COPY Step Start Time => 16:14:06 Process Name => STATS60A Step End Time => 16:14:48 Process Num => 5 SMFID => SYSK Comp Code => 00000000 Userid => USER11 Comp Msg => SCPA000I Job Name => USER11 Job ID => TSU04406 Secondary Node => CD.NODEB Step Name => STEP1 Pnode Version=> 6.01.00 Snode Version=> 6.01.00 Other addr => 11.12.13.14 Other port => 05620 Session Class=> 001

Session Protocol => TCP FASP => No Session is not with SSP V2 Buffer Size => 131,072 Negotiated V2 Buffer Size => 131,072 TCP Buffer Size Used => 262,144 Compression Control Feature: ON Negotiated: NO Compression

From ( Snode Dsn=>USER11.SMSTEST.DSN1) DCB => LRECL => 00080 BLKSIZE => 27920 RECFM => FB DSORG => PS-E Mgd => YES DSNTYPE => EXTENDED STRIPED DISP=> (S, , ) recs => 0 blks => 358,167 Bytes Read => 10,000,000,000 Bytes Sent => 10,001,432,668 Cmpr Perc => 0.0% VOL=SER => ARTS0M ARTS0F ARTS0D ARTS08 ARTS06 ARTS0B Time on CP => 00:00:06.264 Time on zIIP => 00:00:00.000 zIIP Qualify => 00:00:00.000 To ( Pnode Dsn=>USER11.SMSTEST.DSN2) DCB => LRECL => 00080 BLKSIZE => 27920 RECFM => FB DSORG => PS-E Mgd => YES DSNTYPE => EXTENDED STRIPED DISP=> (R, , ) recs => 0 blks => 358,167 Bytes Written => 10,000,000,000 Bytes Received=> 10,001,433,436 Cmpr Perc => 0.0% VOL=SER => ARTS0M ARTS06 ARTS0E ARTS0D ARTS08 ARTS09 Time on CP => 00:00:08.274 Time on zIIP => 00:00:00.000 zIIP Qualify => 00:00:00.000

636 IBM Connect:Direct for z/OS: Documentation

The following figure illustrates how output to the system console and messages in response to consolecommands are formatted.

=============================================================================CD.NODEA SELECT STATISTICS DATE : 08.28.2018=============================================================================

14:45:16 SVTM055I SESSION (001) ESTABLISHED WITH SNODE=CD.NODEB14:45:16 SVTM036I PROCESS STARTED STATS60A( 7) SNODE=CD.NODEB14:45:16 SDAA004I - OBTAIN TSODSN=NO DSN=USER11.SMSTEST.DSN114:45:16 SDAC006I (LOCATE) - R15=0000, R0=0000, Function completed successfully.14:45:16 SDAC006I (LOCATE) - R15=0000, R0=0000, Function completed successfully.14:45:16 SDAA004I - ALLOC DD=NDM00016 TSODSN=NO RETURN=(DSORG,DEVTYPE,14:45:16 SDAA004I - VOL,STORCLAS,DATACLAS,MGMTCLAS) DSN=USER11.SMSTEST.DSN114:45:16 SDAA004I - DISP=(SHR ) DCB=(BLKSIZE=0000027920,DSORG=PS ,14:45:16 SDAA004I - LRECL=00080,RECFM=FB ) UNIT=(3390 ,,DEFER) VOL=(,,14:45:16 SDAA004I - 001,,)14:45:16 SDAB005I - ERR=0000, INFO=0000, DYNAMIC ALLOCATION COMPLETED SUCCESSFULLY.14:45:22 SOPD049I Connect:Direct Process,(STATS60A , 7 ) suspended by USER1114:45:22 SOPD023I SUSPEND Process command by USER11 completed.14:45:22 SDAA004I - UNALLOC DISP=(,KEEP) DD=NDM0001614:45:22 SDAB005I - ERR=0000, INFO=0000, DYNAMIC ALLOCATION COMPLETED SUCCESSFULLY.14:45:22 SVTM052I STEP1 COPY STATS60A( 7) SNODE=CD.NODEB14:45:22 SVTM052I FROM USER11.SMSTEST.DSN114:45:22 SVTM052I TO USER11.SMSTEST.DSN214:45:22 SVTM052I #### COMPLETED 0000000C/SCPA046I14:45:22 SVTM105I PNAME=STATS60A, PNUM= 7 MOVED TO Q=HOLD , QSTATUS=HS14:45:22 SVTM037I PROCESS SUSPENDED STATS60A( 7) SNODE=CD.NODEB14:45:22 SVTM056I SESSION (001) TERMINATED WITH SNODE=CD.NODEB14:45:24 SOPD049I Connect:Direct Process,(STATS60A , 00000007) changed by USER1114:45:24 SOPB017I CHANGE Process command by USER11 completed.14:45:24 SVTM055I SESSION (001) ESTABLISHED WITH SNODE=CD.NODEB14:45:24 SVTM036I PROCESS STARTED STATS60A( 7) SNODE=CD.NODEB14:45:24 SDAA004I - OBTAIN TSODSN=NO DSN=USER11.SMSTEST.DSN114:45:24 SDAC006I (LOCATE) - R15=0000, R0=0000, Function completed successfully.14:45:24 SDAC006I (LOCATE) - R15=0000, R0=0000, Function completed successfully.14:45:24 SDAA004I - ALLOC DD=NDM00017 TSODSN=NO RETURN=(DSORG,DEVTYPE,14:45:24 SDAA004I - VOL,STORCLAS,DATACLAS,MGMTCLAS) DSN=USER11.SMSTEST.DSN114:45:24 SDAA004I - DISP=(SHR ) DCB=(BLKSIZE=0000027920,DSORG=PS ,14:45:24 SDAA004I - LRECL=00080,RECFM=FB ) UNIT=(3390 ,,DEFER) VOL=(,,14:45:24 SDAA004I - 001,,)14:45:24 SDAB005I - ERR=0000, INFO=0000, DYNAMIC ALLOCATION COMPLETED SUCCESSFULLY.

Note: In a IBM Connect:Direct/Plex, all write-to-operator (WTO) records display the IBM Connect:DirectServer name (or XCF.NAME for a IBM Connect:Direct Manager) before the time.

Using ADVANCED SELECT STATISTICS through the IUIYou can use the Advanced Select Statistics (S2) screen to select, display, and print statistics informationfrom IBM Connect:Direct activities. The Advanced Select Statistics panel incorporates all fields from boththe Select Statistics and the Select Statistics Extended Options panels into one scrollable panel. Thismakes it easier for those using larger dimension screen sizes to use the dialog. The S2 panel also includesnew fields supported by SELECT STATISTICS command specifying the WHERE2 parameter. For moreinformation see, “SELECT STATISTICS Command Format” on page 622. Since Advanced Select Statistics(S2) screen uses The WHERE2 parameter, the S2 Detail report will differ from the SS report by thoserecord types reported differently by WHERE2. Note that there is more information in the help panel for S2.

To select, display, or print statistics information using the IUI:

Select option S2 from the Primary Options Menu to display the Advanced Select Statistics screen.

Chapter 5. User Guide 637

CD.ART Advanced Select Statistics 08.30.2018 2018.242 14:13:05CMD ==> D AutoSave==> YES

Cmds: S ... Summary Table D ... Display Report P ... Print Report SAVE Save Variables REST Restore Variables CLR Clear Variables

Start Stop ---------- ----------Date: __________ __________ (MM.DD.YYYY SU MO TU WE TH FR SA TO YE)Time: __________ __________ (HH:MM:SSXM)

Process Numbers==> 1 2Process Names ==> ____________________________________________________________Record Types ==> CT SB /PNODE ==> ____________________________________________________________ / SNODE ==> ____________________________________________________________ / From ==> CD.ARTNode/ To ==> ____________________________________________________________Names Local ==> ____________________________________________________________ \ Remote ==> ____________________________________________________________ \ Submit ==> ____________________________________________________________ \Any ==> ____________________________________________________________Server Names ==> ____________________________________________________________Message IDs ==> ____________________________________________________________User IDs ==> ____________________________________________________________File Names ==> ____________________________________________________________

Condition Code ==> __ ________

Search ==> ______________________________________________Archived ==> ______________________________________________Datasets ==> ______________________________________________

Excl Memb Recs ==> NExcl WTO Recs ==> YExcl ^WTO Recs ==> N

Case Sensitive ==> Y

DTF Level: 6.00.00

Advanced SELECT STATISTICS Display ReportThe IUI Advanced Select Statistics (S2) panel uses the WHERE2 parameter with SELECT STATISTICScommand. The WHERE2 formatted statistics records have a common header that makes it easier to findfrequently sought report values such as Time and Date, on Local and Remote nodes. The Display Reportfor record types supported by the WHERE2 parameter is different from Display Report for record typessupported by the WHERE parameter.

Note: Record types not supported by WHERE2 parameter continue to display using the same format asthe WHERE parameter.

The following table lists the statistics record types and their corresponding record type identifiers thatdisplay through the Display Report command of the Advanced Select Statistics screen for WHERE2parameter.

Record ID Description

CT Copy Termination

FI Long File Name Record

MC PDS Member Copy

RJ Run Job

RT Run Task

PI PNODE Process Start

PS Process Submit

638 IBM Connect:Direct for z/OS: Documentation

Record ID Description

PT PNODE Process Termination

To use S2 panel, follow the same procedure as the SS panel, except there are more node field types thatyou can specify. There is no second panel you must go to if you want to specify any of the less frequentlyused fields. If no record types are specified, the default types are the same as for Select Statistics (SS).

The following table describes Default records types that display through the Display Report command forSelect Statistics (SS) and Advanced Select Statistics (S2) screens:

Record ID Description

CH Change Process

CT Copy Termination

DP Delete Process

FI Long File Name Record

FP Flush Process

FS Suspend Process

MC PDS Member Copy

M2 Multiple Copy Record

PS Process Submit

PT PNODE Process Termination

RJ Run Job

RT Run Task

SW Submit within a Process

SY SYSOPT (PNODE & SNODE)

TP Throughput Record Statistics

ZI SNODE Process Start

ZT SNODE Process Terminated

All other record types must be requested specifically. An asterisk (*) requests all types in both SS and S2.

Advanced SELECT STATISTICS sample outputThe following figure illustrates an example SELECT STATISTICS WHERE2 report for PS, CT and PT records.

================================================================================CDA.NODE1 SELECT STATISTICS DATE : 06.07.2021================================================================================Function (PS)=> Process Submit Start Time=> 01:36:04 06.07.2021Process Name => COPY1 Stop Time=> 01:36:04 06.07.2021Process Num => 1Comp Cod+Msg => 00000000 SSPA001ISubmit Job+ID=> USER1 TSU04779UserID => USER1SnodeID => NoPNode => CDA.NODE1 This Node => PSNode => CDB.SSARA1Submit Node => CDA.SSARA1Submitted DSN=> USER1.PROCESS================================================================================CDA.NODE1 SELECT STATISTICS DATE : 06.07.2021================================================================================Function,(CT)=> COPY Start Time=> 01:37:12 06.07.2021

Chapter 5. User Guide 639

Process Name => COPY1 Stop Time=> 01:37:12 06.07.2021Process Num => 1Comp Cod+Msg => 00000000 SCPA000ISubmit Job+ID=> USER1 TSU04779SMFID => IRVOStep Name => PROCESS1UserID => USER1Pnode Version=> 6.02.00 Snode Version=> 6.01.00PNode => CDA.NODE1 This Node => PSNode => CDB.NODE1 From Node => PSubmit Node => CDA.NODE1Session Class=> 001Other addr => 10.120.130.42Other port => 32782

Session Protocol => TCPFASP => No Session is not with SSPV2 Buffer Size => 1,048,576Negotiated V2 Buffer Size => 32,768TCP Buffer Size Used => 2,097,152Compression Control Feature: ONNegotiated: NO Compression

TLS V1.2 Enabled => Yes Encrypt.Data=YTLS Ciphersuite => TLS_RSA_WITH_AES_256_GCM_SHA384Subject => (SN=60:9b:aa:4d:00:04:ce:9f/C=IN/ST=haryana/L=gurugram/O=capegemini/OU=aricent/CN=CDB_CERT/)Issuer => (C=IN/ST=haryana/L=gurugram/O=capegemini/OU=aricent/CN=CDB_CERT/)

From ( Pnode Dsn=>SMSTEST.DSN1) DCB => LRECL => 00080 BLKSIZE => 14960 RECFM => FB DSORG => PS Mgd => YES DSNTYPE => BASIC DISP=> (S, , ) recs => 39 blks => 1 Bytes Read => 3,120 Bytes Sent => 3,305 Cmpr Perc => - 5.6% VOL=SER => ARTS09 Time on CP => 00:00:00.149 Time on zIIP => 00:00:00.000 zIIP Qualify => 00:00:00.000To ( Snode Dsn=>SMSTEST.DSN2) DCB => LRECL => 00080 BLKSIZE => 27920 RECFM => FB DSORG => PS Mgd => YES DSNTYPE => BASIC DISP=> (R, , ) recs => 39 blks => 1Bytes Written => 3,120Bytes Received=> 3,305 Cmpr Perc => - 5.6% VOL=SER => ARTS0M Time on CP => 00:00:00.191 Time on zIIP => 00:00:00.000 zIIP Qualify => 00:00:00.000================================================================================CDA.NODE SELECT STATISTICS DATE : 06.07.2021================================================================================Function (PT)=> Process Termination Start Time=> 01:36:04 06.07.2021Process Name => COPY Stop Time=> 01:37:13 06.07.2021Process Num => 1 Submit Time=> 01:36:03 06.07.2021Comp Cod+Msg => 80B37000 SVTM100I Schedule Time=> (none)Submit Job+ID=> USER1 TSU04779SMFID => IRVOUserID => USER1PNode => CDA.USER1 This Node => PSNode => CDB.USER1Submit Node => CDA.USER1Session Class=> 001 Time on CP => 00:00:05.734Time on zIIP => 00:00:00.000zIIP Qualify => 00:00:00.000

WRITE EXSTATS CommandUse the WRITE EXSTATS command to write statistics record from external sources.

640 IBM Connect:Direct for z/OS: Documentation

WRITE EXSTATS Command FormatWRITE EXSTATS has the following format and parameters. The required parameters and keywords arebold.

Label

Command Parameters

(Optional)

WRITE EXSTATS TYPE = ID

MSGID = ID

STARTT = ([date][,hh:mm:ssXM])

STOPT = ([date][,hh:mm:ssXM])

CCODE = completion code

MSG.SHORTTEXT or MSST = text

USER = name

LNODE = name

APPLICATION.NAME or APP.NAME = text

FCODE = feedback code

PNAME = name

PNUMBER or PNUM = number

SUBMITTER = name

DSN = name

MSG.LONGTEXT or MSGT = text

SYMBOLIC.PARAMETERS or SYMBOLS = text

UDF1= text

UDF2= text

UDF3= text

UDF4= text

The following table describes the WRITE EXSTATS command parameters:

Chapter 5. User Guide 641

Parameter Description

TYPE = ID Specifies the statistics record types to write. Every statisticsrecord IBM Connect:Direct writes from external source hasan associated record-type identifier. Each identifier is twocharacters long and indicates the event or function thatgenerated the record.

Identifier must be one of following reserved record types forexternal statistics:

YA, YB, YC, YD, YE, YF, YG, YH, YI, YJ, YK, YL, YM, YN, YO, YP, YQ, YR, YS, YT, YU, YV, YW, YX, YY, YZ, Y0, Y1, Y2, Y3, Y4, Y5, Y6, Y7, Y8, Y9, Y@, Y#, Y$, Y%

Note: This is required parameter.

MSGID = ID Specifies 8 character message ID.

Note: This is required parameter.

642 IBM Connect:Direct for z/OS: Documentation

Parameter Description

STARTT = ([date][,hh:mm:ssXM]) Specifies starting date and time of operation or function whichgenerated this record. The date or day and time are positionalparameters. If you do not specify the date or day, precede thetime with a comma.

Date specifies the date of Process execution. You can specifythe day (dd), month (mm), and year (yy for 2-digit year andyyyy for 4-digit year). You can use periods or backslashes (/)to separate the components of a date value. You can omit theseparators only for transfers between mainframe nodes. Useseparators to guarantee transfers between all platforms. Youcan use the following date formats, according to which dateorder is specified in the DATEFORM initialization parameter:

• DATEFORM=MDY specifies the date format as mm/dd/yy,mm/dd/yyyy, mm.dd.yy, or mm.dd.yyyy

• DATEFORM=DMY specifies the date format as dd/mm/yy,dd/mm/yyyy, dd.mm.yy, or dd.mm.yyyy

• DATEFORM=YMD specifies the date format as yy/mm/dd,yyyy/mm/dd, yy.mm.dd, or yyyy.mm.dd

• DATEFORM=YDM specifies the date format as yy/dd/mm,yyyy/dd/mm, yy.dd.mm, or yyyy.dd.mm

Valid Julian dates formats are yyddd, yyyyddd, yy/ddd, yyyy/ddd, yy.ddd, or yyyy.ddd. If you do not specify the DATEFORMparameter, Connect:Direct for z/OS defaults to MDY dateformat.

hh:mm:ssXM indicates the time of day in hours (hh), minutes(mm), and seconds (ss) to select. Set XM to AM or PM. Youcan use the 24-hour clock or the 12-hour clock. If you usethe 24-hour clock, valid times are 00:00-24:00. If you usethe 12-hour clock, 1:00 hours are expressed as 1:00AM, and13:00 hours are expressed as 1PM. If you use neither AM orPM, IBM Connect:Direct assumes the 24-hour clock. You donot have to specify minutes and seconds.

If you do not specify a start date, the start date will be Jan 0,0000. If you do not specify a start time, the start time will be00:00:00. If you specify neither, the start date and time will beJan 0, 0000 00:00:00. If the start date and time is after thecurrent system date and time, searching will be bypassed, andso nothing will be selected. If you specify a day of the week, itis always resolved to the current date or a prior date, never afuture date.

Note: This is required parameter.

Chapter 5. User Guide 643

Parameter Description

STOPT = ([date][,hh:mm:ssXM]) Specifies stopping date and time of operation or functionwhich generated this record. The date, day, and time arepositional parameters. If you do not specify the date or day,place a comma before the time.

The date and time formats are the same as the STARTTparameter. The time default is 24:00:00, the end of the day.

If you do not specify a stop time, it will be 23:59:59.99.Otherwise, it will be the time specified. Either way, this timeis only provisional.

Note: This is required parameter.

CCODE = completion code Specifies a decimal value 1 to 2,147,483,647

Note: This is required parameter.

MSG.SHORTTEXT

or MSST = text

Specifies 1 to 72 characters in length short message text. Textmust be enclosed within quotes For example,

MSG.SHORTTEXT = ‘Process Executed Successfully’

Same text can be specified on multiple lines as follows,

MSST = \’Process \ || - Executed Successful\’\

Note: This is required parameter.

USER = name Specifies user name, who performed operation or functioncausing generation of this statistics record.

USER name can be up to 64 characters in length and cancontain lowercase characters. If not specified, USER namedefault to current signed-on user.

LNODE = name Specifies Local Node name on which process or command issubmitted, causing generation of this statistics record.

If not specified, LNODE name default to current signed-onNode.

APPLICATION.NAME

or APP.NAME = text

Specifies 1 to 32 characters text description of applicationwhich is generating this statistics record. Text must beenclosed within quotes.

If not specified, it is defaulted to current signed-on applicationdescription. For example,

APPLICATION.NAME = ‘CD File Agent’

Same text can be specified on multiple lines as follows,

APP.NAME = \’CD \ || - File Agent\’\

644 IBM Connect:Direct for z/OS: Documentation

Parameter Description

FCODE = feedback code Specifies a decimal value 1 to 2,147,483,647

This is optional parameter and can be specified if message hasfeedback code in addition to completion code

PNAME = name Specifies 1 to 8 characters Process name.

This is optional parameter and can be specified whenstatistics record is related to Connect:Direct process.

PNUMBER

Or PNUM = number

Specifies Process number. The range is 1-199999

This is an optional parameter and can be specified whenstatistics record is related to Connect:Direct process.

SUBMITTER = name Specifies user name, who submitted the Connect:Directprocess.

SUBMITTER name can be up to 64 characters in lengthand can contain lowercase characters. This is an optionalparameter and can be specified when statistics record isrelated to Connect:Direct process

DSN = name Specifies data set name or USS file path.

DSN can be up to 255 characters in length and can containlowercase characters. Name must be enclosed within quotes.

This is optional parameter and can be specified whenstatistics record is related to data set or file. For example,

Data set name

DSN = ‘HLQ.LLQ’

USS absolute file name

DSN = ‘/u/Library/Book 001’

Same name can be specified on multiple lines as follows,

DSN = \'/u/Library/\ || -Book 001\'\

MSG.LONGTEXT

or MSGT = text

Specifies 1 to 960 characters in length long message text. Textmust be enclosed within quotes. This is optional parameter.

For example,

MSG.LONGTEXT = ‘Process Executed Successfully’

Same text can be specified on multiple lines as follows,

MSGT = \’Process \ || -Executed Successful\’\

Chapter 5. User Guide 645

Parameter Description

SYMBOLIC.PARAMETERS

or SYMBOLS = text

Specifies substitution parameters.

Text can be up to 127 characters in length and can containlowercase characters. Text must be enclosed within quotes.

This is optional parameter and can be specified whenstatistics record is related to Connect:Direct process andprocess contains substitution parameters. For example,

SYMBOLIC.PARAMETERS = ':&DATE=TODAY:&GDG=+1:'

Same text can be specified on multiple lines as follows,

SYMBOLS = \':&DATE=TODAY\ || -:&GDG=+1:\'\

UDF1 = text Specifies additional text information.

Text can be up to 127 characters in length and can containlowercase characters. Text must be enclosed within quotes.This is an optional parameter

For example,

UDF1 = ‘User Defined Field 1’

Same text can be specified on multiple lines as follows,

UDF1 = \'User Defined \ || -Field 1\'\

UDF2 = text Specifies additional text information.

Text can be up to 127 characters in length and can containlowercase characters. Text must be enclosed within quotes.This is an optional parameter

For example,

UDF2 = ‘User Defined Field 2’

Same text can be specified on multiple lines as follows,

UDF2 = \'User Defined \ || - Field 2\'\

UDF3 = text Specifies additional text information.

Text can be up to 127 characters in length and can containlowercase characters. Text must be enclosed within quotes.This is an optional parameter

For example,

UDF2 = ‘User Defined Field 3’

Same text can be specified on multiple lines as follows,

UDF3 = \'User Defined \ || - Field 3\'\

646 IBM Connect:Direct for z/OS: Documentation

Parameter Description

UDF4 = text Specifies additional text information.

Text can be up to 127 characters in length and can containlowercase characters. Text must be enclosed within quotes.This is an optional parameter

For example,

UDF4 = ‘User Defined Field 4’

Same text can be specified on multiple lines as follows,

UDF4 = \'User Defined \ || - Field 4\'\

Connect:Direct provides permission, External Statistics Logging via authorization bit mask (ABM) torestrict user from performing WRITE EXSTATS command.

Connect:Direct also provides initialization parameter, EXTERNAL.STATS.ALLOWED to control whichexternal statistics record identifiers are allowed from which application.

SELECT MESSAGE CommandThe SELECT MESSAGE command enables you to display message details using the message ID.The SELECT MESSAGE command has the following format and associated parameters. The requiredparameters and keywords are in bold print. Default values for parameters and sub parameters areunderlined

Label Command Parameter

(optional) SELect MeSsaGe WHERE (ID|MSGID= message ID) [Short | Long]

The following table describes the SELECT MESSAGE command parameters

Parameter Description

WHERE

ID | MSGID = message ID

Specifies the 8-character message identification. You can specify a genericmessage ID.

[Short | Long] Specifies to display the message text in short or long format. The shortformat is the default.

The following screens show examples of the SELECT MESSAGE command.

To use SELECT MESSAGE with a specific ID:

SELECT MSG WHERE (MSGID=SCPA0001) LONG

To use SELECT MESSAGE with a generic ID:

SELECT MESSAGE WHERE (MSGID=SCPA*)

Chapter 5. User Guide 647

The Network Map

Retrieving Records from the Network Map FileUse the SELECT NETMAP command to retrieve records from the network map file for display or furtherprocessing. The network map file is maintained by your system administrator.

Issuing the SELECT NETMAP Command from the IUIUse the Select network map screen to select a Network map record.

1. Select option NM from the Primary Options Menu to display the Select Netmap or TCP Informationscreen.

node.name SELECT NETMAP OR TCP INFORMATION hh:mm CMD ==> NETMAP INFORMATION NODE KEY(S): ==> ________________ ==> ________________ ==> ________________ ==> ________________ ==> ________________ ==> ________________ ==> ________________ ==> ________________ TCP INFORMATION ADDRESS:__________________________________________ NAME: ________________________________________________________________ OUTPUT DESTINATION ==> DIS (DIS-DISPLAY,PR-PRINT)

2. Type the selection criteria for the nodes you want to examine and press Enter. To select all nodes, youcan simply press Enter.

The following is an example of a network map showing two nodes: CD.PLX44 and CDSELECT.SCO.

BROWSE SYS20095.T141831.RA000.EPETE1.NDMAPI.H0F Line 0000000000 Col 001 080 Command ===> Scroll ===> CSR********************************* Top of Data **********************************=========================================================== SELECT NETWORK MAP===========================================================Node Name : CD.PLX44 VTAM Applid : M1CDD97GMax Parsess : 10 Def Ses Class : 1Session Type: SNA Environment :Logmode : NDML256K Library Name :Node Status : INTERNAL, SEND, RECEIVECreated : 01/01/2020 , 21:21:21Updated : 02/02/2020 , 22:22:22Used as PNOD: 03/03/2020 , 23:23:23Used as SNOD: 04/04/2020 , 23:24:22ALT.COMM : (ALT.DIR=BALANCE - (ALT.ADDR=10.20.129.101,ALT.PORT=13641, ALT.TYPE=TCP , ALT.USE.OUT=YES ))CRC : DEFAULT Session Snode Max : 255PlexClass : ( , ) Use.Server.Node: No___________________________________________________________Node Name : CDSELECT.SCO TCP PORT : 13640TCP Address : 10.20.246.244Max Parsess : 20 Def Ses Class : 2Session Type: TCP Environment : UNIXSource IP : 10.20.201.2Node Status : INTERNAL, SEND, RECEIVECreated : 01/01/2020 , 21:21:21Updated : Used as PNOD: Used as SNOD: ALT.COMM : (ALT.DIR=TOP - (ALT.ADDR=MVSLPARA.ARICENT.COM, ALT.PORT=01364,ALT.TYPE=TCP , SOURCEIP=10.20.202.22 , ALT.USE.OUT=YES ))CRC : DEFAULT Session Snode Max : 255Contact : Joe DowePhone : (xxx) xxx-xxxxxDescription : Connect:Direct for z/OS XXXX Node

648 IBM Connect:Direct for z/OS: Documentation

You can make generic requests by using an asterisk. For example, type an asterisk (*) in the first nodekey field to select all nodes and D* to select only those nodes that begin with D. See SELECT NETMAPCommand Format or press PF1 for Help.

Note: The TCP information fields are for creating the SELECT TCPXLAT command described in the nextsection. Do not fill them in for the SELECT NETMAP command.

Issuing the SELECT NETMAP Command from the Batch Interface

• To use the SELECT NETMAP command from the Batch Interface, place your commands in theDGADBATC job stream and submit the job while IBM Connect:Direct is running. The followingcommand displays all network map entries for node names that begin with SAN.

SIGNON SEL NET WHERE (NODE=(SAN*)) SIGNOFF

In the following example, the only node name in the network map which begins with SAN is theSANFRAN node. This report contains a long DNS record, which you can define in the Adjacent NodeDefinition in the network map. For more information on the Adjacent Node Definition, search onMaintaining the Network Map in the IBM Connect:Direct for z/OS Administration Guide.

============================================================================ SELECT NETWORK MAP ============================================================================ NODE NAME : SANFRAN VTAM APPLID : M1A66789 MAX PARSESS : 10 DEF SES CLASS : 1 SESSION TYPE: SNA ENVIRONMENT : OS390 NODE STATUS : INTERNAL, SEND, RECEIVE LONG DNS : REGIONAL.MANAGER.OFFICE.IN.THE.SAN.FRANCIS CO.BAY.AREA.CALIFORNIA.USA Created : 01/01/2020 , 10:10:10 Updated : Used as PNOD: 02/02/2020 , 20:20:20 Used as SNOD: ALT.COMM : (ALT.DIR=BALANCE - (ALT.ADDR=M1A66790,ALT.TYPE=SNA , ALT.USE.OUT=YES )) CRC : DEFAULT SESSION SNODE MAX : 255 CONTACT : JOE SMITH PHONE : 345-999-6999 DESCRIPTION : SANFRAN TO TOKYO NODES PATH, SECONDARY P ATH TO OSAKA.

SELECT NETMAP Command FormatThe SELECT NETMAP command uses the following format and parameters. The required parameters arein bold print. Default values for parameters and subparameters are underlined.

Label Command Parameters

(optional) SELect NETMAP WHERE (NODE = (node| generic |(list)))

PRint | DISplay

The following table describes SELECT NETMAP parameters:

Chapter 5. User Guide 649

Parameter Description

WHERE (NODE =(node | generic | (list))

Specifies which network map node definitions you want to examine. WHERE isthe only required parameter for the SELECT NETMAP command.

NODE=(node |generic | (list)) specifies the network map node names that areselected. Specify a list of node names by enclosing them in parentheses andseparating each by a comma or a blank.

node specifies a node name. The node is a 1–16 character alphanumeric string,with the first character alphabetic.

generic specifies a generic selection of node names. To specify node namesgenerically, type a 1–7 character alphanumeric string, with the first characteralphabetic, plus an asterisk (*). For instance, if your network includes nodenames PHOENIX, SANDIEGO, SANFRAN, and TUCSON, a specification of SAN*provides information about the SANDIEGO and SANFRAN nodes. If you typeonly an asterisk (*), IBM Connect:Direct displays (or prints) all nodes that youare authorized to use.

PRint | DISplay Indicates the output format. Indicate only one.

Translating TCP/IP Host Names to Network AddressesUse the SELECT TCPXLAT command to translate TCP/IP host names to network addresses and TCP/IPaddresses to host names.

Issuing the SELECT TCPXLAT Command from the IUIThe Select NETMAP or TCP Information screen issues the SELECT TCPXLAT command or the SELECTNETMAP command depending on your request.

1. Select option NM from the Primary Options Menu to display the Select Netmap or TCP Informationscreen. (See Issuing the SELECT NETMAP Command from the IUI to see a screen sample.)

2. Press Tab until you reach the TCP INFORMATION portion of the screen. See the parameterdescriptions in SELECT TCPXLAT Command Format or press PF1 for Help.

3. Do one of the following:

• To translate a host address to a fully qualified host name, type the address in dot notation form in theADDRESS field.

• To translate a host name to a real TCP/IP address, type the host name in the NAME field. You canalso type an alias name in this field if the host name is too long for the space provided.

The following output is displayed:

xx.abc.node111 RESOLVED TCP NAME/ADDRESS 14:56 CMD ==> TCP name/address translation successful. TCP ADDRESS : 111.222.333.444 FULLY QUALIFIED TCP HOST NAME: qaoptsol.csg.stercomm.com____________________________ $$$$ ________________________________

Issuing the SELECT TCPXLAT Command with the Batch InterfaceTo use the SELECT TCPXLAT command from the Batch Interface, place your commands in the DGADBATCjob stream and submit the job while IBM Connect:Direct is running. Use the batch version of the SELECTTCPXLAT command to make multiple requests for resolution. The maximum number of requests is 10.

• To use the SELECT TCPXLAT command from the Batch Interface, place your commands in theDGADBATC job stream and submit the job while IBM Connect:Direct is running. Use the batch version

650 IBM Connect:Direct for z/OS: Documentation

of the SELECT TCPXLAT command to make multiple requests for resolution. The maximum number ofrequests is 10.

The following command produces the TCP Name/Address Translation Report. The first two nameslisted in the TRTCPNAM parameter are aliases, the third is an actual host name.

SIGNON SEL TCPXLAT WHERE (TRTCPNAM=(NAME1, NAME2, tcpip.host.name3)) SEL TCPXLAT WHERE (TRTCPADR=(123.456.78.999, 123.456.789.012))SIGNOFF

The following report shows the resolution of name to address or address to name. REQUEST is what istyped in the command.

============================================================================= TCP Name/Address Translation Report=============================================================================REQUEST : NAME1Host Address : NNN.NNN.NN.NNN..HOST NAME : tcpip.host.name1REQUEST : NAME2*** TCP Name/Address could not be resolved ***REQUEST : tcpip.host.name3Host Address : NNN.NNN.NN.NNN..HOST NAME : tcpip.host.name3============================================================================= TCP Name/Address Translation Report=============================================================================REQUEST : 123.456.78.999Host Address : 123.456.78.999,HOST NAME : tcpip.host.name4REQUEST : 123.456.789.012Host Address : 123.456.789.012,HOST NAME : tcpip.host.name5

SELECT TCPXLAT Command FormatThe SELECT TCPXLAT command uses the following format and parameters. The required parameter is inbold print. Default values for parameters and subparameters are underlined.

Label Command Parameters

(optional) SELect TCPXLAT WHERE (TRTCPNAM = (tcpip.host.name | (list)) TRTCPADR = (tcp.net.adr | (list)))PRint | DISplay

The following table describes the SELECT TCPXLAT command parameters:

Chapter 5. User Guide 651

Parameter Description

WHERE (TRTCPNAM = (tcpip.host.name | (list)) TRTCPADR = (tcp.net.adr | (list)) )

Specifies which TCP host name or network address resolution youwant to examine. This parameter is required. Provide one of thefollowing subparameters:

TRTCPNAM = (tcpip.host.name | (list)) specifies a translationfrom host name or alias to a real address. Type this name inthe standard format with each of the qualifiers being from 1to 64 alphanumeric characters, with a maximum name lengthof 64 characters. Specify a list of names by enclosing them inparentheses and separating each by a comma or a blank.

TRTCPADR = (tcp.net.adr | (list)) specifies a translation from anIP address to the host name for that network. Type this addressin the dotted format (nnn.nnn.nnn.nnn) with a maximum lengthof 15 characters including periods. Specify a list of addresses byenclosing them in parentheses and separating each by a commaor a blank.

PRint | DISplay Specifies where output is directed. Indicate only one. Whenyou submit this command through DGADBATC, use the PRINTparameter only.

Utility ProgramsIBM Connect:Direct provides several utility programs and one I/O exit that facilitate your use of thesoftware. You can perform the following functions using these programs and the exit:

• Notify the user of Process success or failure using DGADTIFY and DGADTFY2• Dynamically allocate data sets using DGADTDYN• Place job stream in a wait status for a specified period of time and set return codes indicating whether

the batch step or RUN TASK completed successfully or failed by using the DGADWAIT program.• Dynamically invoke AMS (Access Method Services) to perform VSAM utility functions using DGADTAMS• Resolve symbolic references using DGADTSUB and DGADGSUB• Compress and decompress files stored in a ZLIB compressed format (DGASACMP)• Determine how many concurrent sessions are running during a specific time period (DGADVITL)• Interface with the IBM utility ADRDSSU, by using the IBM Connect:Direct I/O exit, DGADSIOX. The

ADRDSSU program enables you to copy SMS-compressed data without having to decompress the dataand also provides support for copying wildcard-named files.

• Replace existing FTP sessions within z/OS job streams with Connect:Direct for z/OS Processes usingIBM Sterling Connect:Direct FTP+ for z/OS (CDFTP).

User Notification ProgramsIBM Connect:Direct provides sample programs that notify the console operator or IUI users about thesuccess or failure of any Process step. The sample programs are supplied in source statement form in theIBM Connect:Direct SDGASAMP library and in load module form in IBM Connect:Direct SDGALINK. UseRUN TASK and MODAL statements with the sample programs to notify users.

The messages sent are standard TRANSFER SUCCESSFUL or TRANSFER FAILED status messages.

Operator Console Notify Program (DGADTIFY)The operator console program, DGADTIFY, works with the RUN TASK statement to notify the consoleoperator of the success or failure of Processes by means of Write to Operator (WTO) messages.

The program must have the following parameters passed to it:

652 IBM Connect:Direct for z/OS: Documentation

Parameter Description

CL4‘GOOD' |CL4‘FAIL'

The first positional parameter tells the program the correct message to output. Codethe parameter as illustrated in the following example, including the single quotes.

file name The second positional parameter is the name of the file that is being copied.

The following example shows a Connect:Direct for z/OS Process using the DGADTIFY program.

COPY1 PROCESS PNODE=CDA SNODE=CDBSTEP01 COPY - FROM ( - PNODE - DSN=FILE1 - DISP=SHR - ) - TO ( - SNODE - DSN=FILE2 - DISP=SHR - )STEP02 IF (STEP01=0) THENNOTIFYG RUN TASK (PGM=DGADTIFY, - PARM=(CL4'GOOD',FILE1)) PNODE ELSENOTIFYF RUN TASK (PGM=DGADTIFY, - PARM=(CL4'FAIL',FILE1)) PNODE EIF

The DGADTIFY program is attached on the PNODE. A parameter list containing the GOOD or FAILmessage criteria and the FILE1 file name is passed to DGADTIFY. If the COPY statement is successful, thefirst RUN TASK step executes and you see the following message:

SNTB001I ** CONNECT:DIRECT SUCCESSFUL STEP COMPLETION **FILE XFER BETWEEN - PLEX.JOE AND - PLEX.TOM SUCCESSFULREQUESTOR=CTENN1DSN=CD.OUTPUT.data set

If the COPY statement is unsuccessful, the second RUN TASK step executes and you see the followingmessages:

SNTB002I ** Connect:Direct FAILED STEP COMPLETION ********** Connect:Direct FILE TRANSFER FAILED ***************** Connect:Direct FILE TRANSFER FAILED *********FILE XFER BETWEEN - PLEX.JOE AND - PLEX.TOM FAILEDREQUESTOR=CTENN1DSN=CD.OUTPUT.data set******** Connect:Direct FILE TRANSFER FAILED ***************** Connect:Direct FILE TRANSFER FAILED *********

User Notify Program (DGADTFY2)Use the sample program, DGADTFY2, in conjunction with the RUN TASK statement to notify TSO usersof various conditions. The program accepts a variable length parameter list to broadcast notificationmessages to users.

Note: The TSO user ID must be in the same z/OS image as the DTF where the DGADTFY2 RUN TASK isrunning.

The following table describes the parameters:

Chapter 5. User Guide 653

Parameter Description

CL4‘GOOD' |CL4‘FAIL'

This first positional parameter indicates the success or failure of the Process step.Code the parameter as illustrated in the following example, including the singlequotes.

file name This second positional parameter is the name of the file that is being copied.

user ID | user ID list The last parameter or list of parameters contains the TSO user IDs to notify.Separate the user IDs with a comma.

The following example demonstrates a Process using the DGADTFY2 program.

COPY PROCESS PNODE=CDA SNODE=CDBSTEP01COPY - FROM (PNODE - DSN=FILE1 - DISP=SHR) - TO (SNODE - DSN=FILE2 - DISP=RPL )STEP02 IF (STEP01=0) THENNOTIFY1 RUN TASK - (PGM=DGADTFY2,PARM=(CL4'GOOD',FILE1,CDID1,CDID2))SNODE ELSENOTIFY2 RUN TASK - (PGM=DGADTFY2,PARM=(CL4'FAIL',FILE1,CDID1,CDID2))PNODEEIF

A GOOD value is relayed to the TSO users CDID1 and CDID2 on CDB in the following message:

SNTA001I **Connect:Direct FILE TRANSFER SUCCESSFUL** TRANSFER BETWEEN - CDA AND - CDB DSN=FILE1

A FAIL value is relayed to the TSO users CDID1 and CDID2 on CDA in the following message.

SNTA002I ****Connect:Direct FILE TRANSFER FAILED**** TRANSFER BETWEEN - CDA AND - CDB DSN=FILE1

Dynamic Allocation Program (DGADTDYN)The dynamic allocation program, DGADTDYN, performs several useful status checking and housekeepingfunctions in a Process. It is located in the IBM Connect:Direct SDGALINK.

When multiple actions are contained in the parameters, the completion code returned is the highestcompletion code encountered.

DGADTDYN ParametersThe RUN TASK command invokes DGADTDYN with parameters that define allocation actions to execute.The following rules apply to the syntax of the parameters:

• Perform each allocation action with as many parameters as required.• Separate each unique allocation action by a parameter containing a fullword of minus one (F'-1').• A leading blank on the first parameter is not required; however, you must include a leading blank on

all subsequent parameters. If you do not include a leading blank, the program issues an RC=30 and anSRTA005I message for the Process.

• Parameters must not extend past column 72, or they are not read.

The following table shows the available dynamic allocation functions:

654 IBM Connect:Direct for z/OS: Documentation

Function Description

ALLOC Use the ALLOC function to allocate a file. The allocation request can contain mostjob stream DD statement options, including DCB options applicable to allocation. Thisfunction is the default.

UNALLOC Use the UNALLOC function to unallocate a file.

CONCAT Use the CONCAT function to concatenate two files.

DECONCAT Use the DECONCAT function to perform dynamic deconcatenation.

LOCATE Use the LOCATE function to locate cataloged data sets.

Note: You cannot access HFS files using DGADTDYN.

DGADTDYN Sample Program UsesThe following examples demonstrate how you can use the functions of the DGADTDYN program.

Example 1: Locate and Allocate a Data SetThe following example calls the program DGADTDYN using the LOCATE parameter to determine if acataloged file exists.

If the file does not exist, the program issues a nonzero return code and makes a call to allocate the filethrough the ALLOC parameter.

PROC1 PROCESS SNODE=BOSTONLOCATE RUN TASK(PGM=DGADTDYN - PARM=(C'LOCATE DSN=XYZ.CUSTOMER.FILE'))SNODE IF (LOCATE NE 0) THENALLOC RUN TASK (PGM=DGADTDYN - PARM=(C'ALLOC', - C' DSN=XYZ.CUSTOMER.FILE', - C' DISP=(NEW,CATLG)', - C' VOL=SER=DCM009', - C' SPACE=(CYL,(1,1))', - C' DSNTYPE=EXTPREF', - C' DCB=(RECFM=FB,DSORG=PS,LRECL=80,BLKSIZE=3120)', - C' UNIT=3380'))SNODE EIF

Example 2: Delete and Uncatalog a Data SetThe following example deletes and uncatalogs a data set.

The first function, ALLOC, allocates the data set specifying a current status of OLD and a secondary (ornormal step completion) disposition of DELETE, which deletes the data set.

The second function, UNALLOC, unallocates the data set. Because of the disposition (the data set isoriginally allocated with disposition DELETE), the data set is uncataloged.

Use the F'-1' as a separator between allocation functions.

PROC2 PROCESS SNODE=BOSTONDELETE RUN TASK(PGM = DGADTDYN - PARM = (C'ALLOC DSN=XYZ.TEMP DISP=(OLD,DELETE)' - F'-1' - C'UNALLOC DSN=XYZ.TEMP'))

Chapter 5. User Guide 655

Example 3: Allocate and Concatenate Data SetsThe following example calls the program to allocate each data set through the ALLOC parameter. Thenit calls DGADTDYN again to do the concatenation through the CONCAT parameter. The data set isconcatenated under the first DDNAME in the CONCAT list.

RTDYNCON PROCESS SNODE=BOSTONALLOC1 RUN TASK (PGM=DGADTDYN - PARM=(C'ALLOC DSN=XYZ.TEMP DISP=SHR DD=OLD1')) PNODEALLOC2 RUN TASK (PGM=DGADTDYN - PARM=(C'ALLOC DSN=XYZ.TEMP2 DISP=SHR DD=OLD2')) PNODECONCAT RUN TASK (PGM=DGADTDYN - PARM=(C'CONCAT DD=(OLD1,OLD2)')) PNODE

Example 4: Deconcatenate and Unallocate Data SetsThe following example calls the program to deconcatenate by DDNAME using the DECONCAT parameter.Then it calls DGADTDYN again to unallocate each data set in the concatenation with the UNALLOCcommand.

RTDYNCON PROCESS SNODE=BOSTONDECONCAT RUN TASK (PGM=DGADTDYN - PARM=(C'DECONCAT DD=(OLD1)')) PNODEUNALLO1 RUN TASK (PGM=DGADTDYN - PARM=(C'UNALLOC DD=OLD1')) PNODEUNALLO2 RUN TASK (PGM=DGADTDYN - PARM=(C'UNALLOC DD=OLD2')) PNODE

Run Task Wait Program (DGADWAIT)Use the DGADWAIT program as a batch step or a RUN TASK to place a job stream in a wait status for aspecified period of time and set return codes indicating when the step or task completes. To synchronizeProcesses submitted through the batch interface, use DGADWAIT with the MAXDELAY parameter in aSUBMIT command or PROCESS statement. For more information, see Using the MAXDELAY KeywordParameter to Synchronize Submitted Processes. This program is distributed via SDGASAMP and must beassembled and link-edited to the IBM Connect:Direct load library.

The following table describes the positional parameters. If you execute DGADWAIT as a RUN TASK,enclose the parameters in quotes because of the embedded commas, for example, PARM=('1,2').

Parameter Description

VALUE1 The first positional parameter indicates the time to wait. The default is 0 or you canuse a comma to omit.

For seconds, specify (S)xxxx. The maximum is 9999 seconds or about 2.7 hours.

For minutes, specify Mxxx. The maximum is 999 minutes or about 16.6 hours.

For hours, specify Hxx. The maximum is H99 or about 4.1 days.

You can also specify ‘ABEND' and then use the actual user ABEND code for thesecond positional parameter.

VALUE2 The second positional parameter specifies the return code to set. The default is 0.The maximum is 4095.

'-' causes a -1 value (if executed as a batch step, IBM displays the return codevalue as 4095).

VALUE3 The third positional parameter is only used to display diagnostics as WTO (write-to-operator) messages. Specify 'DIAG' or leave blank. Any other value is ignored.

656 IBM Connect:Direct for z/OS: Documentation

The following examples show how to use DGADWAIT in a RUN TASK. In the first example, the programwaits for one second, and then sets the return code to 2.

DGADWAIT PROCESS SNODE=NODE.NAME &PRM='1,2'STEP01 RUN TASK (PGM=DGADWAIT PARM=(&PRM))

In this example, the program does not wait, but sets the return code to 8.

DGADWAIT PROCESS SNODE=NODE.NAME &PRM='0,8'STEP01 RUN TASK (PGM=DGADWAIT PARM=(&PRM))

VSAM AMS Interface Program (DGADTAMS)The VSAM AMS interface program, DGADTAMS, dynamically invokes AMS to perform VSAM utilityfunctions. The program is located in the IBM Connect:Direct SDGALINK.

The highest completion code encountered in any AMS action is returned.

DGADTAMS ParametersDGADTAMS is invoked by the RUN TASK Process statement with the following parameters that defineallocation and AMS actions to execute.

Parameter Description

sysprint outputparameters

The first positional parameter is special because it defines dynamic allocationparameters for the AMS SYSPRINT output. This parameter can allocate a spool fileor a user file. The FREE and RETURN subparameters are required.

Note: You must specify all of the sysprint output parameters on the same line. Theycannot be on separate lines.

The following example defines a CLASS A SYSOUT spool file.

C'FREE=CLOSE, RETURN=(DD) SYSOUT=A'

controlstatementparameters

You can use any valid input to the VSAM AMS program as input to DGADTAMS, evenmultiple input parameters defining one or more AMS actions. You must begin all VSAMcontrol statement parameters with a blank.

DGADTAMS Sample ProgramThe following figure shows a sample of DGADTAMS using the Define Cluster AMS function. The ASMSYSPRINT output is routed to the existing user file XYZ.OUTPUT.

VADC1 PROCESS SNODE=BOSTONDEFINE RUN TASK (PGM=DGADTAMS, - PARM=(C'FREE=CLOSE,RETURN=(DD),DISP=OLD,DSN=XYZ.OUTPUT', - C' DELETE(VSAM.PAY.CHECKS) CLUSTER', - C' DEFINE CLUSTER -',- C' (NAME(VSAM.PAY.CHECKS) -',- C' RECORDS(1) -',- C' VOLUMES(DCM009) -',- C' OWNER(NDM) -',- C' NONINDEXED -',- C' RECORDSIZE(4089 4089) -',- C' SHAREOPTIONS (2)) -',- C' DATA -',- C' (CONTROLINTERVALSIZE(4096) -',- C' NAME(VSAM.PAY.CHECKS.DATA)) -',- C' CATALOG(USER.UCAT)')) SNODE

Chapter 5. User Guide 657

Symbolic Resolution Utilities (DGADTSUB and DGADGSUB)The IBM Connect:Direct utility programs, DGADTSUB and DGADGSUB, enable you to submit jobs to theinternal reader, much like RUN JOB. DGADTSUB has the added capability of symbolic resolution into thejob. The RUN TASK statement invokes DGADTSUB or DGADGSUB, which allows you to substitute variablesin the parameter list.

The following table lists DGADTSUB and DGADGSUB parameters, and DGADGSUB variables:

Parameter Description

JCL source The first parameter is an allocation string to point to the job to submit. Code itwithout a ddname because DGADTSUB acquires one. IBM Connect:Direct uses thisvalue, along with the DISP parameter, to allocate the data set that contains theJCL.

SubsequentParameters

Subsequent parameters define resolutions for symbols used in the JCL itself. Foreach parameter, the first position is the name of the symbol found in the JCL andthe second position is the value used. Separate the first and second positions byan equal sign (=), one or more spaces, or a comma. The value is terminated bythe end of the parameter string, or a comma or space not within a quoted string.A parameter can also contain only a symbol name, in which case the value tosubstitute into the job stream is a null string.

Note: To pass lowercase data to the DGADTSUB program, use SYSOPTS in the RUNTASK statement.

Variables (for usewith DGADGSUB)

%SRCDSN The resolved ‘FROM' data set name from the last COPY stepexecuted in this Process

%DSTDSN The resolved ‘TO' data set name from the last COPY step executedin this Process

%PROCNAME The name of this Process

%PROCNUM The number of this Process

Note: To use %SRCDSN or %DSTDSN, the RUN TASK must be run on the PNODE.The values for the %SRCDSN and %DSTDSN variables are not available when theRUN TASK is run on the SNODE.

The following figure is an example of RUN TASK using the DGADTSUB program.

RUN TASK (PGM=DGADTSUB - PARM=('DSN=dsname,DISP=SHR', - 'JOB X21JOB', - 'RPTNAME REPORT01', - 'CLASS A', - 'FILE X21.FILE' - )) PNODE

The job stream source that corresponds to this RUN TASK statement is displayed in the following figure.The values requiring substitution are presented in bold type.

//&JOB JOB (79502),&RPTNAME,PRTY=12,TIME=(1),CLASS=&CLASS, // REGION=512K,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=BSMITH1//PRINT EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY,DCB=BLKSIZE=80//SYSUT1 DD DISP=SHR,// DSN=&FILE //SYSUT2 DD SYSOUT=&CLASS,DCB=(&FILE)

658 IBM Connect:Direct for z/OS: Documentation

The following figure shows the resulting job stream after substitution has taken place. IBM Connect:Directreplaces the variables that began with & with the assigned values in the DGADTSUB parameter list.

//X21JOB JOB (79502),REPORT01,PRTY=12,TIME=(1),CLASS=A,// REGION=512K,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=BSMITH1//PRINT EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY,DCB=BLKSIZE=80//SYSUT1 DD DISP=SHR,// DSN=X21.FILE//SYSUT2 DD SYSOUT=A,DCB=(X21.FILE)//*

Passing Variables Using DGADGSUBYou can use the DGADGSUB program, which substitutes variables in the parameter list and then calls theDGADTSUB program to process the parameter list further.

Note: DGADGSUB is not intended to concatenate variables, only to substitute them. Variableconcatenation is handled by the parser at PROCESS submit time. DGADGSUB is intended to pass variablesto JCL to be substituted into the job.

To do this, modify an existing RUN TASK statement that calls DGADTSUB to call DGADGSUB, and add thevariables you want to use in the parameter list.

The following figure is an example of RUN TASK using the DGADGSUB program.

STEP01 RUN TASK(PGM=DGADGSUB - PARM=('DSN=DALLAS1.ZOS.SRCLIB(JCLTEST1),DISP=SHR', - 'JOB &JOBNAME', - 'SRC %SRCDSN', - 'DST %DSTDSN ', - 'PROCNAME %PROCNAME', - 'PROCNUM %PROCNUM ', - 'DSN DSNNAME')) PNODE

In this example, the following circumstances are in effect:

• The ‘FROM' data set in the last COPY step before this RUN TASK is DALLAS1.FILE• The ‘TO' data set in the last COPY step before this RUN TASK is DALLAS1.TEST.GDG.G0006V00• The name of the Process is 'TESTPR'• The Process number is 29• The &JOBNAME is XYZ

The DGADGSUB program makes the variable substitutions and calls the DGADTSUB program with thefollowing parameters:

PARM=('DSN=DALLAS1.ZOS.SRCLIB(JCLTEST1),DISP=SHR', - 'JOB XYZ', - 'SRC DALLAS1.FILE', - 'DST DALLAS1.TEST.GDG.G0006V00 ', - 'PROCNAME TESTPR', - 'PROCNUM 00029 ', - 'DSN DSNNAME'))

Wherever &JOB, &SRC, &DST, &PROCNAME, &PROCNUM, and &DSN are found inDALLAS1.ZOS.SRCLIB(JCLTEST1), the corresponding values are substituted. Once all the substitutionshave been made, the resultant JCL is submitted to JES.

Chapter 5. User Guide 659

Using Symbolic VariablesIt can also be useful to specify the values to substitute as symbols rather than their actual value. You canthen use a single Process for multiple purposes.

The following figure is an example of DGADTSUB that symbolically substitutes values into a z/OS job beingsubmitted to the internal reader. IBM Connect:Direct supports any symbols that begin with an ampersand.

In the example, the second and subsequent parameters name the symbol, without the &, and value thatthe symbol becomes in the submitted job stream. IBM Connect:Direct substitutes the value itself whenthe Process is submitted.

DGADTSUB PROC SNODE=CD.OS39040.N1 NOTIFY=USER01 - &CLASS=A &DEST=LOCAL &JOB=JOB1SB - &RPTNAME=’’’RPT NAME’’’ - &FILE=X21.FILE - &JCL=X21.CNTL(SUBSUB)** RUN TASK (PGM=DGADTSUB - PARM=(“DSN=dsname,DISP=SHR”, - “FILE &FILE”, - “JOB &JOB”, - “CLASS &CLASS”, - “DEST &DEST”, - “RPTNAME &RPTNAME”, - )) PNODE

IBM Connect:Direct Exits and DGADTSUBIf your IBM Connect:Direct system uses any of the standard exits (Security, RUN JOB, or RUN TASK),DGADTSUB functions with any or all of them without further modification. Both a RUN TASK and a RUNJOB exit are invoked by DGADTSUB, and any processing that takes place is done when using DGADTSUB.

Error OutputDGADTSUB writes any internal error information to the data set specified on the CDESTAE DD statement.Always include this DD statement in the IBM Connect:Direct startup job stream.

Return CodesThe following table describes the DGADTSUB return codes:

Return Code Meanings

04 A job stream record is truncated after substitution. Symbolic substitution is performedon columns 1–71 of the JCL record. Truncation is indicated when substitution causesthe data in columns 1–71 to expand beyond column 71.

For non-JCL records, substitution is performed on columns 1–80. The most commoncause of this error is sequence numbers in data statements.

08 An error occurred parsing the parameters or the job stream source.

A symbol length is greater than 19.

A symbol name is absent in the parameter string.

660 IBM Connect:Direct for z/OS: Documentation

12 No parameters are passed.

An I/O error occurred.

An input data set allocation parameter is not found.

The symbol table overflowed.

A file open error occurred.

An input record length is greater than 256.

A member locate error occurred.

Batch Compression Utility (DGASACMP)DGASACMP is a batch utility that compresses and stores files in ZLIB-compressed format. You cantransfer these compressed files using a IBM Connect:Direct Process and store them on the remote nodeas compressed data. A user can execute DGASACMP on the remote node to decompress the data andstore it in the original format. These files cannot be decompressed using any other utility.

Note: You can also decompress files using a IBM Connect:Direct Process. Refer to AutomaticDecompression for more information.

DGASACMP supports physical sequential files (PS), KSDS, ESDS, and RRDS VSAM files. DGASACMPcannot allocate VSAM files as DISP=(NEW,CATLG), so you must pre-define the VSAM output file whendecompressing a file that was originally VSAM.

DGASACMP does not support PDS (or PDSE) files as PDS, but you can use IEBCOPY to unload the PDS,then compress or decompress using DGASACMP.

DGASACMP ParametersYou can pass the following parameters to DGASACMP:

Parameter Description

MODE= COMP | DECOMP Specify COMP to compress an input file. Specify DECOMP todecompress a compressed file.

REPORT=NORMAL | DEBUG Specify NORMAL to instruct DGASACMP to produce a summarystatistics report. This value is the default. Specify DEBUG to instructDGASACMP to produce a detailed statistics report.

ZLIB=(CMP=1 | n, WIN=13 | nn,MEM=4 | n)

These three parameters change the settings of the extendedcompression utility. CMP indicates the compression level. Validvalues are 1–9. The default value is 1. WIN indicates the windowsize. Valid values are 9–15. The default value is 13. MEM indicatesthe memory. Valid values are 1–9. The default value is 4.

Note: Changing these values can significantly impact performanceand CPU overhead. Before you change the default values, seeTesting the Effects of Changing Values for Extended CompressionParameters .

Chapter 5. User Guide 661

DGASACMP ExamplesThe following sample JCL, found as member DGAXCMP in $CD.SDGASAMP, compresses a physicalsequential (PS) file and stores it as compressed data.

//CDCMP JOB (1004),'BATCH COMPRESS',CLASS=N,MSGCLASS=X,// COND=(1,LT),REGION=0M//*//* ZLIB COMPRESS A FILE IN BATCH//*//COMP EXEC PGM=DGASACMP,PARM='MODE=COMP'//STEPLIB DD DISP=SHR,DSN=$CD.SDGALINK//INPUT DD DISP=SHR,DSN=$CD.FILE1//OUTPUT DD DSN=$CD.FILE1.COMP,DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(TRK,(1500,300),RLSE),// DCB=(BLKSIZE=27920,RECFM=U,DSORG=PS)//SYSOUT DD SYSOUT=*,DCB=(BLKSIZE=133)//*

The following sample JCL, found as member DGAXDCMP in $CD.SDGASAMP, decompresses acompressed file and stores it in the original format.

//CDDECMP JOB (1004),'BATCH COMPRESS',CLASS=N,MSGCLASS=X,// COND=(1,LT),REGION=0M//*//* ZLIB DE-COMPRESS A FILE IN BATCH//*//DECOMP EXEC PGM=DGASACMP,PARM='MODE=DECOMP'//STEPLIB DD DISP=SHR,DSN=$CD.SDGALINK//INPUT DD DSN=$CD.FILE1.COMP,DISP=SHR//OUTPUT DD DSN=$CD.FILE1.NEW,DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(TRK,(1500,300),RLSE),// DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)//SYSOUT DD SYSOUT=*//*

DGASACMP OutputThe following screen shows sample output from DGASACMP.

SACO000I DGASACMP started, GMT =2001.275 19:39:25.00SACO001I OS Parm: MODE=COMP,SACO002I Options in effect: MODE=COMP CMP= 1 WIN= 13 MEM= 4 REPORT=NORMALSACO003I ZLIB Version=1.2.3SACO011I INPUT DSORG=PS RECFM=FB RECSZ= 80 DSN=CD.TESTFILE.M1SACO012I OUTPUT DSORG=PS RECFM=U RECSZ= 27,920 DSN=CD.TESTFILE.M1.COMPSACO021I Total Records Read = 12,500SACO022I Total Records Written = 5SACO023I Total Bytes Read = 1,000,000SACO024I Total Bytes Written = 124,584SACO031I Compression Percent = 88%SACO032I Compression Ratio = 8.0:1SACO033I TCB CPU Seconds = 2.627SACO034I Elapsed Seconds = 4.103SACO999I DGASACMP utility completed successfully

You can also invoke DGASACMP with the OUTPUT DD as DUMMY, indicating that the summary reportis produced, but the output data is not stored. You must still provide the DCB attributes. The followingscreen shows an example.

//OUTPUT DD DUMMY,// DCB=(BLKSIZE=27920,RECFM=U,DSORG=PS)

662 IBM Connect:Direct for z/OS: Documentation

Testing the Effects of Changing Values for Extended Compression ParametersBefore you change the default values of the extended compression parameters when using theDGASACMP utility, search on Improving Performance in the IBM Connect:Direct for z/OS AdministrationGuide and review the benchmark figures showing different test results. You can also use this utility offlineto determine the benefits of changing the default values in a test environment before actually usingcompression on live data in your production environment.

Although extended compression using ZLIB is available on a global basis using the ECZ initializationparameters and on a Process basis using the EXT parameters in the COPY statement, performingcompression online consumes significant CPU resources. The DGASACMP utility produces a report(see the sample report in DGASACMP Output), which shows how much the data was read, written,compressed, and how long it took to compress. Another report is produced when you use DGASACMP todecompress data and restore it to its original format.

To use DGASACMP to test compression, follow this procedure:

1. Prepare a file containing the typical type of data you transfer and the average amount of data involvedin a transfer.

2. Transfer the file without using compression and record the time it takes for the transfer to complete.3. To test the results of compressing and decompressing the file, run DGASACMP three times on the test

file using the following settings. After each compression run, run DGASACMP to decompress the file.Keep the output reports for each test to compare results.

• CMP=1,WIN=13,MEM=4 (the default settings)• CMP=1,WIN=1,MEM=14)• CMP=8,WIN=1,MEM=14)

4. To determine if it is worthwhile to use compression and what extended compression parameter valuesare most beneficial for your environment, examine the test results taking the following factors intoconsideration:

• Amount of CPU and elapsed time it takes to compress and decompress the data• Amount of time it takes to send the data• Virtual memory space used to maintain the ZLIB internal control blocks• Virtual memory space used to allocate the compression window or history buffer• Type of data being sent, including its compressibility

Automatic DecompressionAs an alternative to storing the data as compressed data on the remote node, you can decompress afile during Process execution. This functionality is available between z/OS and any other platform thatsupports ZLIB compression.

To perform automatic decompression, specify PRECOMP=YES in the SYSOPTS parameter in the FROMclause of the COPY statement. PRECOMP=YES indicates that the FROM data set is precompressed andinstructs IBM Connect:Direct to decompress the file as part of the Process. If you do not code SYSOPTSor set PRECOMP to NO, the file is sent in compressed format and the receiver must run DGASACMP withMODE=DECOMP.

Note: If you are decompressing a file using DGASACMP, you cannot allocate VSAM files asDISP=(NEW,CATLG). You must predefine the VSAM output file.

The following sample Process, found as member DGAPMPPS in $CD.SDGAPROC, instructs IBMConnect:Direct to decompress a file that is compressed using DGASACMP.

Note: Refer to the $CD.SDGASAMP data set for more sample Processes.

Chapter 5. User Guide 663

CDCOMPPS PROCESS SNODE=CD.OS390STEP1 COPY FROM (DSN=$CD.FILE1.COMP - DISP=(SHR) - SYSOPTS='PRECOMP=YES' - PNODE) - TO (DSN=$CD.FILE1.NEW - DISP=(RPL) - SNODE)

Determine “High-Water Mark” for a Period (DGADVITL)The program called DGADVITL reports how many concurrent sessions (Processes) are running during thetime period specified. Below is a sample RUN TASK that executes as a PNODE=SNODE Process whensubmitted. This Process must be force flushed to discontinue. The MCS console displays the number ofsessions that ran during the specified period, and the time and date the high water mark was reached.These messages appear in the JESMSGLG segment of the IBM Connect:Direct SYSOUT.

/****************************************************************//* RUN TASK FOR HIGH WATER PROCESS NUMBER; PNODE=SNODE */ /***************************************************************/RTBB PROCESS SNODE=your.local.node STEP1 RUN TASK (PGM=DGADVITL,PARM=(C'60')) PNODE

The parameter, C, is the number of minutes desired in a measurement interval. The interval, 60, is anappropriate value to use. Since the Process that does the measuring runs as a PNODE=SNODE Process,the system adds a count of 2 to whatever the highest number of Processes that were running concurrentlyduring a particular sample window. For example, if 6 other Processes were running simultaneously at agiven time during the sample window, the value in the SVIT001I message will be '0008'. If no Processeswere running during that sample time, the measuring Process is not counted, so the value in the SVIT001Imessage is '0000'.

The following example shows the output of the DGADVITL program:

SVIT001I SESSION HIGH WATER MARK OF: 0003 REACHED AT: 10:15:46 ON: 02000173

Note: Using the DGADVITL utility may not be required and Simultaneous Session Reporting (SSR) is thepreferred application in most instances. Connect:Direct utilizes Simultaneous Session Reporting (SSR)to continually monitor sessions over the life of Connect:Direct and tracks the session high-water mark,generates an SMF133 record to document this value, and provides reports from the data. For CDPLEX,a DGADVITL Run Task must be running on each server in the CDPLEX to report that server's activity onthe number of concurrent sessions reached during the specified period. For additional information aboutSimultaneous Session Reporting (SSR), see Simultaneous Session Reporting in the System AdministrationGuide.

ADRDSSU Interface Program (DGADSIOX I/O Exit)The DGADSIOX I/O exit dynamically invokes the IBM ADRDSSU utility to enable you to copy:

• SMS-COMPRESSED data without first uncompressing the data• Wildcard-named files

Running Traces for the DMDSSIOX I/O ExitThe DGADSIOX I/O exit automatically logs information to //ADRIOXLG each time the ADRDSSU programis invoked regardless of the DEBUG bit settings. However, to log additional tracing information, use thesetting, DEBUG=00008000 or DEBUG=04008000 in the DEBUG DDNames in the IBM Connect:Directstartup JCL to generate an I/O Buffer Trace or an I/O Buffer Trace combined with a separate trace pertask. DGADSIOX I/O exit information logs to Rnnnnnnn while DSS exit information logs to Xnnnnnnn.

664 IBM Connect:Direct for z/OS: Documentation

DGADSIOX I/O Exit Sample ProcessesThree sample Processes are provided in the $CD.SDGAPROC library distributed with IBM Connect:Directthat you can use to prepare a Process to execute the DGADSIOX I/O exit:

• DGAPIOX1, which copies the SMS-COMPRESSED data set, KSTIC1.SMSTEST.DMDSSU.COMP.OUTLIST,from the PNODE to a data set of the same name on the SNODE but renames the SNODE data set toMWATL1.SMSTEST.DMDSSU3.** as part of the execution of the ADRDSSU utility on the SNODE.

• DGAPIOX2, which is similar to the DGAPIOX1 process but uses symbolic substitution to name the inputdata set.

• DGAPWILD, which is set up to copy wildcard-named files

DGADSIOX I/O exit limitations and security considerationsCheckpoint/restart is not supported when using DGADSIOX I/O exit for the following reasons:

• I/O exits in general including do not support Checkpoint/restart• The IBM ADRDSSU utility does not support Checkpoint/restart• Control cards are allow for wild-carded input

In addition, the ADRDSSU utility does not support DUMP/RESTORE of z/OS UNIX System Services userfiles such as PATH='/u/kstic1/abc.txt'. However, ADRDSSU does support HFS files.

The DGADSIOX I/O Exit utility program invokes DFSMSdss to perform requested functions by callingthe ADRDSSU utility via the cross-memory application interface, documented in DFSMSdss StorageAdministration. This cross-memory interface causes a DFSMSdss server address space to start underthe ASPACE name of DGADSIOX.

For HFS and ZFS type files, there are restrictions related to UNIX System Services that may result infailures or hangs without proper security. Please refer to DFSMSdss Storage Administration (Applicationprogramming interface, Cross-memory application interface restrictions) for a description of therestrictions and set up requirements related to HFS and ZFS files.

When using DUMP/RESTORE to copy a ZFS File System, a separate IDCAMS VERIFY must be donefollowing the COPY. This can be done with the DGADTSUB Run Task utility or with IDCAMS outside ofIBM Connect:Direct. Without the VERIFY, any access to the restored ZFS File System will receive an OPENerror (RC=116 orx’74’) and the data will not appear usable. VERIFY must be performed prior to mountingthe ZFS File System. This requirement does not apply to HFS File Systems nor to individual ZFS filescopied using DGADSIOX

DGASCONV – Secure Parameter File Conversion UtilityWhen upgrading from a release of IBM Connect:Direct prior to 5.2 and using Secure Plus, the SecureParameter and Secure Access files must be converted to the new file format. The SPAdmin tool cannotopen a secure parameter file created in a release prior to 5.2.

The DGASCONV utility performs the conversion by allocating a new secure parameter file and using theold secure parameter file as input. Due to the possibility of secure passwords with Strong PasswordEncryption (SPE) being enabled in the previous release, this utility also uses the DGADTQFX and IDCAMSto convert the TCQ/TCX, copy the NETMAP and copy the AUTH file.

Sample JCL, DGAJCONV, in the SDGAJCL data set should be tailored to your environment and executed toperform this conversion. Use the instructions within the DGAJCONV JCL to assist with this JCL tailoring.

The execution of DGAJCONV with produce a report in the output DD called REPORT. Use this report todetermine the scope of the changes made by the utility and to make recommended manual updates toany action produced in the report.

You must also specify the new secure parameter file as SECURE.DSN within your initialization parameters.This utility produces a diagnostic trace to the DD called TRACEO, which is a comment in the sample JCL. Ifyou do not want to execute the diagnostic trace, leave the DD as a comment.

Chapter 5. User Guide 665

Using the TCQ/TCX Repair Utility (DGADTQFX)The TCQ/TCX Repair Utility (DGADTQFX) can be used to help solve corruption problems related to theTCQ/TCX data sets.

Run the DGADTQFX utility in one of the following ways:

• Rebuild TCX mode, which creates a new TCX by using the current TCQ to indicate the existence ofProcesses.

• Use TCX mode, which creates a new TCQ using the current TCX to indicate the existence of Processes.When upgrading from Connect:Direct releases prior to 4.4, using TCX mode is recommended.

Note: Use different names to distinguish the original and new TCQ/TCX data sets in case you need to goback and reuse the original data sets.

The Rebuild TCX mode is the preferred mode for rebuilding the TCQ/TCX after encountering TCQcorruption problems, which cause U3083 abends.

CAUTION:

The DGADTQFX utility is rebuilding the TCX based on Processes that remain in the TCQ. The utilitywill determine the highest Process number in the TCQ and will set the next available Processnumber to the next number. It is possible for this utility to reuse Process numbers.

The Use TCX mode is recommended for TCQs associated with systems running versions of IBMConnect:Direct prior to Version 4.4. Prior to Version 4.4, completed Processes were retained in the TCQand were not deleted.

The DGADTQFX program, located in $CD.SDGALINK, has one execution parameter for specifying thereport type.

Parameter Description

PARM= SUMMARY| DETAIL |BACKLEVEL | REMOVEPR

Specify SUMMARY to produce a report at the Process level.

Specify DETAIL to produce a report, which shows steps within eachProcess, such as RUN TASK, RUN JOB, SUBMIT, and COPY.

Specify BACKLEVEL to create a TCQ and TCX for pre-version 4.6Connect:Direct systems.

Specify REMOVEPR to remove all Processes on the PR queue.

Normally, you run DGADTQFX with IBM Connect:Direct shut down but you could run it in production. Thedata sets and reports created will be correct as long as no update activity to the input TCQ takes placewhile the utility executes. The program issues a warning message if the VSAM timestamp for the inputTCQ is changed during execution.

The return codes associated with the DGADTQFX utility are described in the following table.

Return Code Meaning

0 No errors were found in the input TCQ

4 At least one error was found and removed or a warning message wasissued

8 A severe error occurred during execution and the utility wasterminated

Initializing the DTF After DGADTQFX Has Found Errors

666 IBM Connect:Direct for z/OS: Documentation

If errors were found and corrected when you ran the DGADTQFX utility, replace the original corrupteddata sets in use with the new data sets created by DGADTQFX. To allocate the new data sets to IBMConnect:Direct, use IDCAMS ALTER or regenerate the network map

IBM Sterling Connect:Direct FTP+ for z/OS (CDFTP)IBM Sterling Connect:Direct FTP+ for z/OS is a component of Connect:Direct for z/OS that provides asimple and dynamic migration path from unmanaged FTP sessions within z/OS job streams to a managedenvironment using Connect:Direct for z/OS with minimal change to the JCL.

IBM Sterling Connect:Direct FTP+ for z/OS provides a simple, reliable, and secure way to transferfiles between a Connect:Direct for z/OS installation at a central processing center and remote IBMConnect:Direct sites. IBM Sterling Connect:Direct FTP+ for z/OS runs as the client and supportsConnect:Direct for z/OS, Connect:Direct for Microsoft Windows, and Connect:Direct for UNIX as theremote system.

Components of IBM Sterling Connect:Direct FTP+The major components of IBM Sterling Connect:Direct FTP+ are:

• IBM Sterling Connect:Direct FTP+ Manager—Starts as a job stream or started task just like a IBMConnect:Direct/Plex Manager. It handles IBM Sterling Connect:Direct FTP+ Clients and is only a PNODE.It cannot be contacted by a remote IBM Connect:Direct to start a process, and it cannot be contacted bya non- IBM Sterling Connect:Direct FTP+ Client. (The sample JCL, DGAXFTPJ, is in $CD.SDGASAMP.)

The IBM Sterling Connect:Direct FTP+ Manager enables the TCP API and can be contacted by the ISPFIUI, Control Center, the Connect:Direct Browser User Interface, and the IBM Connect:Direct JAI.

• IBM Sterling Connect:Direct FTP+ Client—Starts a special case of a IBM Connect:Direct Server. It buildsand submits a Process which is scheduled by the IBM Sterling Connect:Direct FTP+ Manager back tothe IBM Sterling Connect:Direct FTP+ Client using the server name for the PLEXCLASS. It is only aPNODE and cannot be contacted by a remote IBM Connect:Direct to start a Process. (The sample JCL,DGAXFCLI, is in $CD.SDGASAMP.)

• IBM Sterling Connect:Direct FTP+ Plug-in—Provides support for FTP commands that IBMConnect:Direct does not support, such as CWD (change working directory), MKDIR (make a directory),RMDIR (remove directory), DIR (obtain a directory listing of files), and DELETE and MDELETE (deletingfiles).

When the JCL is changed to use IBM Sterling Connect:Direct FTP+ for z/OS instead of FTP, all of thesupported FTP commands are interpreted into appropriate COPY or RUNTASK and COPY steps andexecuted within the IBM Sterling Connect:Direct FTP+ Client started in the user's address space.

Security Considerations for IBM Sterling Connect:Direct FTP+The IBM Connect:Direct files, Connect:Direct Secure Plus parameter file and Netmap, are accessedthrough the IBM Sterling Connect:Direct FTP+ Manager under its authority. The only IBM Connect:Directfile that is accessed through the IBM Sterling Connect:Direct FTP+ Client is the IBM Connect:DirectMessage File. All file accesses on the local system will be performed under the authority of the job userid(normal MVS operation). All file accesses on the remote system will be performed under the authority ofthe userid/password used for the SNODEID in the IBM Sterling Connect:Direct FTP+ for z/OS Process.

To use the IBM Sterling Connect:Direct FTP+ Client to connect to a remote Connect:Direct for z/OSsystem, the remote userid must have HFS file access on the remote Connect:Direct for z/OS system if thetemporary file written by the plug-in on Connect:Direct for z/OS is an HFS file or if HFS files or directoriesare to be accessed.

Configure IBM Sterling Connect:Direct FTP+ for z/OSBefore you can use IBM Sterling Connect:Direct FTP+, certain installation and configuration tasks must beperformed.

Complete the following tasks:

Chapter 5. User Guide 667

• “Install IBM Sterling Connect:Direct FTP+ Plug-in” on page 668• “Create CDFTP Procedure” on page 668• “Create JCL to Start the IBM Sterling Connect:Direct FTP+ Manager” on page 670• “Update Netmap for Remote Nodes” on page 671• “Start IBM Sterling Connect:Direct FTP+ Manager” on page 671

Install IBM Sterling Connect:Direct FTP+ Plug-inThe IBM Sterling Connect:Direct FTP+ Plug-in must be installed on the IBM Connect:Direct nodesthat IBM Sterling Connect:Direct FTP+ for z/OS communicates with. The IBM Sterling Connect:DirectFTP+ Plug-in is already included in the Connect:Direct for z/OS installation. If the remote node is aConnect:Direct for UNIX or Connect:Direct for Microsoft Windows server, the IBM Sterling Connect:DirectFTP+ Plug-in must be deployed on the remote system. For IBM Sterling Connect:Direct FTP+ Plug-ininstallation instructions for Connect:Direct for Microsoft Windows and Connect:Direct for UNIX, refer tothe latest IBM Sterling Connect:Direct FTP+ 1.2 Release Notes.

Note: Make a note of the fully-qualified installation directory of the plug-in (unless the remote node isConnect:Direct for z/OS) and the fully qualified name of the plug-in temporary file on the remote IBMConnect:Direct server. You need this information when you update the Netmap.

Create CDFTP ProcedureBuild the CDFTP procedure and save it in your system's PROCLIB. The CDFTP procedure is executed inyour modified FTP JCL. The sample JCL, DGAXFTPP, is in $CD.SDGASAMP.

The following is an example of a CDFTP procedure:

//CDFTP PROC//CDFTP EXEC PGM=DMINIT,REGION=0M,// PARM='USER1.INIT.PARMLIB(GLOBINIT),CDFTP' //STDENV DD DUMMY//SYSTCPT DD DISP=(,DELETE),DSN=&&RES,// SPACE=(CYL,(1,1)),DCB=(DSORG=PS,RECFM=FB,// LRECL=80,BLKSIZE=24000),UNIT=SYSDA//NETRC DD DISP=SHR,DSN=USER1.OS390.SRCLIB(NETRC)//SYSTCPD DD DISP=SHR,DSN=SYS2.TCPIP.PARMS(TCPDATA2)//STEPLIB DD DISP=SHR,DSN=USER1.CD5000.LOADLIB//CDPLEX DD DISP=SHR,DSN=USER1.INIT.PARMLIB(SERVER)//CDESTAE DD SYSOUT=*//ESTAE DD SYSOUT=*//NDMLOG DD SYSOUT=*

In this example, the Global initialization parameters file, GLOBINIT, and local initial initializationparameters file, SERVER, contain normal initialization parameters for starting a IBM Connect:Direct/PlexServer. If CDPLEX.SERVER= is specified in the local initialization parameters, it is ignored and the JESjobname is used as the server name. The specification of CDFTP as the first override parm after thespecification of the location of the initialization parameters file identifies this DTF as a IBM SterlingConnect:Direct FTP+ Client.

The SYSTCPT DD is required so that the Resolver will write its trace information into this file when arequest to the Resolver, such as GETHOSTNAME, is issued. IBM Sterling Connect:Direct FTP+ reads thistrace information to get the resolved DATASETPREFIX from the Resolver to determine which FTP.DATA fileto open and process.

A z/OS FTP client gets its configuration data from the FTP.DATA file and uses the following search order tofind this file:

• DD card - //SYSFTPD• Tsoprefix.FTP.DATA• Tsoid.FTP.DATA• /etc/ftp.data• SYS1.TCPPARMS(FTPDATA)

668 IBM Connect:Direct for z/OS: Documentation

• tcpip_hlq.FTP.DATA

IBM Sterling Connect:Direct FTP+ Client will attempt to find the correct FTP.DATA file using the followingsearch order:

• DD card - //SYSFTPD• JobUserid.FTP.DATA• /etc/ftp.data• SYS1.TCPPARMS(FTPDATA)• tcpip_hlq.FTP.DATA

Note: /etc/ftp.data must not be File Format NA or it will be ignored.

Note: tcpip_hlq is determined from DATASETPREFIX in the RESOLVER trace information written in theSYSTCPT DD. If DATASETPREFIX is not found, the default is “TCPIP".

If the FTP.DATA file is found, the following configuration parameters are honored by IBM SterlingConnect:Direct FTP+:

• PRIMARY—used for CDFTP.TEMPFILE allocation• SECONDARY—used for CDFTP.TEMPFILE allocation• SPACETYPE—used for CDFTP.TEMPFILE allocation• KEYRING—used to override Connect:Direct Secure Plus keyring

Note: The FTP.DATA file is used by both z/OS FTP and IBM Sterling Connect:Direct FTP+.Use ;CDFTPKEYRING if IBM Sterling Connect:Direct FTP+ should use a different keyring than z/OS FTP.

• ;CDFTPKEYRING ;—used for a IBM Sterling Connect:Direct FTP+ specific override of Connect:DirectSecure Plus Keyring

Note: Do not forget to put a semi-colon (;) in front of CDFTPKEYRING and a space followed by asemi-colon ( ;) at the end of CDFTPKEYRING, which makes this statement a comment to z/OS FTP, butwill still be recognized by IBM Sterling Connect:Direct FTP+ and processed.

CDFTPKEYRING ;(or KEYRING if ;CDFTPKEYRING ; is not specified) will override the Connect:DirectSecure Plus specification of the keyring only if the Connect:Direct Secure Plus Parmfile was defined witha keyring. If the Connect:Direct Secure Plus Parmfile is defined to use a key database, the FTP.DATAspecification is ignored with a message to OUTPUT. To explicitly specify to use the Connect:DirectSecure Plus Parmfile definitions (keyring or key database, and to avoid the message to OUTPUT),code: ;CDFTPKEYRING ;.

• SECURE_DATACONN—used as default for Connect:Direct Secure Plus transfers

The IBM Sterling Connect:Direct FTP+ Client is a special case of a IBM Connect:Direct/Plex Server in aIBM Connect:Direct/Plex environment. The local initialization parameters file, SERVER, should specify:

CDPLEX.MANAGER=NO

For more information about global and local initialization parameters, see Initialization Parameters in theIBM Connect:Direct for z/OS Administration Guide.

Chapter 5. User Guide 669

Create JCL to Start the IBM Sterling Connect:Direct FTP+ ManagerCreate JCL to start the IBM Sterling Connect:Direct FTP+ Manager. Refer to the following JCL as anexample:

//CD$MGR JOB (CDHOSTD),'FTPUSER',PRTY=12,TIME=1440,CLASS=Q,// REGION=0M,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=&SYSUID/*JOBPARM LINES=999999//************************************************************//* *//* CONNECT:DIRECT (Connect:Direct for z/OS MANAGER) *//* *//************************************************************// SET PGM=DMINIT,P=,// E='STAT.INIT=COLD,TCQ=COLD'//NDMITST EXEC PGM=&PGM,REGION=0M,// PARM='&P.USER1.INIT.PARMLIB(GLOBINIT),CDFTP,&E '//CDPLEX DD DISP=SHR,DSN=USER1.INIT.PARMLIB(CDFTPMGR)//CDSVCDMP DD DUMMY//STEPLIB DD DSN=USER1.CD5000.LOADLIB,DISP=SHR//DMPUBLIB DD DSN=USER1.PROCESS.LIB,DISP=SHR//ESTAE DD SYSOUT=*//CDESTAE DD SYSOUT=*//NDMLOG DD SYSOUT=*

In this example, the JCL that starts the IBM Connect:Direct Manager is similar to JCL that starts the IBMConnect:Direct/Plex Manager. The initparm override PARM CDFTP as the first override parm after thelocation of the global initialization parameters makes this a IBM Sterling Connect:Direct FTP+ Manager.

The following local and global initialization parameters are forced with no message:

• TCP=OES• SNA=NO• CTCA=NO• SECURITY=OFF (IBM Sterling Connect:Direct FTP+ Client only. The Security parameter is allowed for

the IBM Sterling Connect:Direct FTP+ Manager)• TCQ=COLD• CONFIRM.COLD.START=NO• TCP.FMH.TIMER=00:00:00• TCP.RUNTASK.TIMER=00:00:00• PROCESS.RETENTION=NO

If you specify any of the following Global Initialization Parameters, they are ignored:

• TCP.LISTEN• MAXPROCESS• MAXPRIMARY• MAXSECONDARY

The local initialization parameters file for the IBM Sterling Connect:Direct FTP+ Manager, CDFTPMGR,should specify:

CDPLEX.MANAGER=YES

For more information about global and local initialization parameters, see Initialization Parameters in theIBM Connect:Direct for z/OS Administration Guide.

670 IBM Connect:Direct for z/OS: Documentation

Update Netmap for Remote NodesIBM Sterling Connect:Direct FTP+ for z/OS gets its configuration information about remote systems itconnects to from the IBM Connect:Direct Netmap.

Configure the following parameters in your Connect:Direct for z/OS Netmap for each remote system thatIBM Sterling Connect:Direct FTP+ for z/OS connects to:

• CDFTP.PLUGIN=<fully qualified installation directory of the IBM Sterling Connect:Direct FTP+ Plug-in>

This parameter is not required when the Netmap entry defines a z/OS system.• CDFTP.TEMPFILE=<fully qualified name of the IBM Sterling Connect:Direct FTP+ temporary file>

The IBM Sterling Connect:Direct FTP+ Plug-in creates a temporary file to store the results of a directorycommand RUNTASK operation.

Note: If no variables are used in the CDFTP.TEMPFILE, IBM Sterling Connect:Direct FTP+ for z/OSappends the job userid and the ASID and CPUID to the CDFTP.TEMPFILE parameter as a furtherspecification of uniqueness.

Several variables are available for substitution in the CDFTP.TEMPFILE specification. The followingvariables allow you to build an appropriate unique temporary file as a z/OS file:

• &userid;—The remote userid (lower case)• &USERID;—The remote userid (upper case)• &lusrid;—The local userid padded to eight characters with '$'• &lcpuid;—The first eight bytes of the local CPUID with "C" overlaying the first byte• &asid;—The four character Address Space ID prefixed with "AS"

For example, you can specify CDFTP.TEMPFILE= with a variable ("&userid;"). IBM SterlingConnect:Direct FTP+ for z/OS inserts the remote userid in place of the &userid;. In the followingexample, the userid specified in the script or NETRC file is user1.

CDFTP.TEMPFILE=/u/&userid;/cdftp/temp.file

CDFTP.TEMPFILE resolves to:

CDFTP.TEMPFILE=/u/user1/cdftp/temp.file

In the script or NETRC file, specify the userid in the case expected for the substitution.

Start IBM Sterling Connect:Direct FTP+ ManagerStart the IBM Sterling Connect:Direct FTP+ Manager as a job stream or started task the same way youstart IBM Connect:Direct/Plex Manager using the JCL created in the previous step.

The IBM Sterling Connect:Direct FTP+ Manager must be running before the IBM Connect:Direct FTP+Client can successfully contact the IBM Sterling Connect:Direct FTP+ Manager to perform its work.

For more information, see the IBM Connect:Direct for z/OS Administration Guide.

Modify FTP JCLUse the following procedure to modify your FTP JCL to use IBM Sterling Connect:Direct FTP+ :

1. Change EXEC PGM=FTP to EXEC PROC=CDFTP.2. Change the INPUT and OUTPUT DD statements and other step statements to specify the

procedure step name. For example, change //INPUT to //CDFTP.INPUT and change //OUTPUT to //CDFTP.OUTPUT.

3. Change the first statement in the INPUT data stream to specify the remote IBM Connect:Direct nodename instead of the machine name for the FTP server.

The following is an example of JCL that executes the CDFTP procedure:

Chapter 5. User Guide 671

//CD$FTPJC JOB (CDHOSTD),'-CDFTP+-',TIME=(1440),CLASS=Q,// REGION=0M,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=&SYSUID/*JOBPARM LINES=999999//LIBS JCLLIB ORDER=(USER1.OS390.SRCLIB)//CDFTP EXEC PROC=CDFTP//CDFTP.NETRC DD DISP=SHR,DSN=USER1.OS390.SRCLIB(NETRC)//CDFTP.FTPTRACE DD SYSOUT=*//CDFTP.OUTPUT DD SYSOUT=*//CDFTP.INPUT DD *MVSB (exitebcdiccd /u/user3delimitmkdir cdftptestlibcd cdftptestliblcd 'USER1.CDFTP.TESTLIB'delimitbinsite sbdataconn=(IBM-037,ISO8859-1)locsite sbdataconn=(IBM-037,ISO8859-1)put CDFTPJC1ebcdicput CDFTPJC1 CDFTPJC2dirlsmdelete CDFTPJC*cduprmdir cdftptestlibclosequit//

You must provide the following information in the JCL:

• Remote host—In this example, the hostname of the FTP server is changed to specify the IBMConnect:Direct node name, MVSB, that is in the Netmap. If the DNS name or IP address used byFTP is the nodename in the Netmap, no change is required. However, duplicating the entry in theNetmap and giving it the IP address or the DNS name as the node name may cause Netmap checkingproblems. In this case, the script should be changed to use the Netmap entry node name.

The remote host statement can also specify (exit, as shown in this example, or (exit=nn to specifythat any error exits the script with a reason code (default is RC=8).

The remote host statement can also specify (secure=off|ssl|tls to specify security options.

If both exit and secure= are specified; only one open parenthesis can be used. For example, MVSB(exit 16 secure=off.

• Remote userid and password—In this example, they are obtained from the NETRC file. If the remoteuserid and password are not specified in the NETRC file, they must be included in the FTP script afterthe remote host.

In the following sample excerpt of JCL that executes the CDFTP procedure, the remote host isPROD.ZOS1, the remote userid is user1 and the password is S1VX$25B:

...//CDFTP.INPUT DD *PROD.ZOS1user1 S1VX$25Bcd /u/daily...

You do not specify the use of Connect:Direct Secure Plus in the JCL. It is determined by theinitialization parameters and the Connect:Direct Secure Plus parameter file definitions for the nodenamed in the script.

To simplify matching up statistics in the remote node with IBM Sterling Connect:Direct FTP+ forz/OS, the PROCESS name is the jobname and the process number is the jobid. The jobname is also

672 IBM Connect:Direct for z/OS: Documentation

used for the IBM Sterling Connect:Direct FTP+ Client server name when contacting the IBM SterlingConnect:Direct FTP+ Manager.

Note: Only the JCL interface is implemented. The ISPF interface (option 6;FTP) is not supported.

New $CD.SDGAPARM and $CD.SDGASAMP MembersThe IBM Connect:Direct $CD.SDGAPARM and $CD.SDGASAMP contain Initialization Parameters, JCL, andother samples that you can use and modify in your IBM Sterling Connect:Direct FTP+ environment.

Member Description Location

DGAIPGBL Global Initialization Parameters $CD.SDGAPARM

DGAIPMGR Manager Local Parameters $CD.SDGAPARM

DGAIPSVR Server (FTP+ Client) Local Parameters $CD.SDGAPARM

DGAXFTPJ CD FTP+ Manager Startup JCL $CD.SDGASAMP

DGAXFCLI CD FTP+ Client JCL $CD.SDGASAMP

DGAXFTPP CDFTP PROC $CD.SDGASAMP

DGAXNETC Sample NETRC $CD.SDGASAMP

DGAXFTPM Sample NETMAP Entry $CD.SDGASAMP

Supported FTP CommandsIBM Sterling Connect:Direct FTP+ for z/OS separates the z/OS FTP commands into three categories:

• Commands completely supported• Commands partially supported• Commands accepted, but ignored.

All commands are case insensitive and can be abbreviated as specified in the z/OS FTP documentation.

Fully Supported FTP CommandsThe following FTP commands are fully supported by IBM Connect:Direct FTP+ for z/OS as described in thefollowing:

Command Description

APpend Appends a data set on the local host to a file on the foreign host

BINary Sets the transfer type to IMAGE

CD Changes the working directory

CDUp Changes to the parent of the current working directory

CLEar Sets the protection level for data transfers to CLEAR

CLose Disconnects from the foreign host

COMpress Sets the data transfer mode to compressed mode

CWd Changes the working directory (Synonymous with CD)

DELEte Deletes a single file on the foreign host

DELImit Displays the delimiter character between the file_name and file_type

DIr Lists the directory entries for files on the foreign host

Note: Format is from Connect:Direct for z/OS Plug-in

Chapter 5. User Guide 673

Command Description

EBcdic Sets the transfer type to EBCDIC

Get Copies a file from the foreign host to your local host

Note: "(REPLACE" supported

GLob Toggles globbing (the expansion of metacharacters in file names) for the MDelete,MGet, and MPut subcommands

LCd Changes the working directory on the local host

LPwd Displays the name of the active working directory on the local host

LS Lists the names of files on the foreign host

MDelete Deletes multiple files on the foreign host

MGet Copies multiple files from the foreign host to the local host

Note: "(REPLACE" supported

MPut Copies multiple files on the local host to the foreign host

PRIvate Sets the protection level for data transfers to PRIVATE

PROtect CLEAR PROTECT sets the protection level for data transfers on data connections. CLEARsets SECURE=(ENC=N) in COPY steps.

PROtect PRIVATE PROTECT sets the protection level for data transfers on data connections. PRIVATEsets SECURE=(ENC=Y) in COPY steps.

PUt Copies a file on the local host to the foreign host

PWd Displays the name of the active working directory on the foreign host

QUIt Leaves the FTP command environment

REName Renames a file on the foreign host

RMdir Removes a directory

SENDSite Enables or disables automatic transmission of the SIte subcommand

Note: Used to determine whether to propagate DCB or use SITE/LOCSITE

Partially Supported FTP CommandsThe following FTP commands are supported by IBM Sterling Connect:Direct FTP+ with limitationsdescribed in the Notes:

Command Description Note

AScii Sets the transfer type to ASCII Treated as EBCDIC

BIG5 Sets the transfer type to BIG5.BIG is the minimum abbreviationfor BIG5.

Only to set DBCS= table in IBM Connect:Direct

HAngeul Sets the transfer type toHANGEUL

Only to set DBCS= table in IBM Connect:Direct

JIS78kj Sets the transfer type to JIS78KJ Only to set DBCS= table in IBM Connect:Direct

JIS83kj Sets the transfer type to JIS83KJ Only to set DBCS= table in IBM Connect:Direct

Ksc5601 Sets the transfer type to KSC5601 Only to set DBCS= table in IBM Connect:Direct

674 IBM Connect:Direct for z/OS: Documentation

Command Description Note

LMkdir Create a directory on the localhost

"(LIKE" ignored

LOCSIte Specifies information that is usedby the local host to provideservice specific to that hostsystem

Ignores all but:

• BLOCKS• BLKSIZE• BLOCKSIZE• CONDISP• CYLINDERS• DIRECTORY• LRECL• PRIMARY• RECFM• SECONDARY• TRACKS

Errors out on:

• TRUNCATE• WRAPRECORD

MKdir Creates a directory on the foreignhost

"(LIKE" ignored

MOde Specifies the mode or data formatof the transfer

MODE C honored as COMPRESS. All othersignored.

Open Opens a connection to a foreignhost

Port ignored

Pass Supplies a password to the foreignhost

No :userdata or account_informationsupported (ignored)

PROMpt Toggles interactive promptingfor MDelete, MGet, and MPutcommands

Toggles prompt switch

PROXy Executes an FTP subcommand ona secondary control connection

Treated as OPEN statement

PROTect SAFE Sets SECURE=(ENC=Y) in COPYstep

Treated as PROTECT PRIVATE

QUOte Sends an uninterpreted string ofdata

Interprets command locally

SAfe Sets the protection level on datatransfers to safe

Treated as PRIVATE. Sets SECURE=(ENC=Y) inthe COPY step.

SChinese Sets the transfer type toSCHINESE

Only to set DBCS= table in IBM Connect:Direct

Chapter 5. User Guide 675

Command Description Note

SIte Sends information to theforeign host using site-specificcommands

Ignores all but:

• BLOCKS• BLKSIZE• BLOCKSIZE• CYLINDERS• DIRECTORY• FILETYPE JES• LRECL• PDSTYPE• PRIMARY• RECFM• TRACKS

Errors out on:

• TRUNCATE• WRAPRECORD

SUnique Toggles the storage methods NAME/NONAME not supported

Used to set DISP=NEW or DISP=RPL for outputfile

TChinese Sets the transfer type toTCHINESE

Only to set DBCS= table in IBM Connect:Direct

TYpe Specifies the transfer type Ignores all but:

• TYPE I = BINARY• TYPE A = ASCII• TYPE E = EBCDIC• TYPE B 2 = EUCKANJI• TYPE F = IBMKANJI• TYPE B 5 = HANGEUL• TYPE B 4 = JIS78KJ• TYPE B 3 = JIS83KJ• TYPE B 6 = KSC5601• TYPE B 1 = SJISKANJI• TYPE B = SJISKANJI

User Identifies you to a foreign host No :userdata and account_informationsupported (ignored)

FTP Commands Accepted, But IgnoredThe following commands are recognized, accepted, and ignored by IBM Sterling Connect:Direct FTP+.These commands do not produce errors.

FTP commands that are not supported or recognized, are ignored with appropriate messages. However, ifIBM Sterling Connect:Direct FTP+ is in exit mode (exit or exit= specified in the remote host statement),these commands stop the script and terminate the step. This is how z/OS FTP behaves.

676 IBM Connect:Direct for z/OS: Documentation

(LOC)SITE subcommands that are not supported or recognized are ignored and do not terminate thestep, even in exit mode. The exceptions to this z/OS FTP behavior are the (LOC)SITE WRAPRECORD andTRUNCATE subcommands. If these subcommands are specified, they always terminate the script (RC=8when not in exit mode and with the user's return code when in exit mode).

• ?• !• ACCount• BLock• CCc• CProtect• DEBug• DUMP• EUCKANJI• FEature• FIle• HElp• Ibmkanji• LANGuage• LOCSTat• NOop• RECord• REStart• SENDPort• SJiskanji• SRestart• STAtus• STREam• STRucture• SYstem• TSO• UCs2• Verbose

Chapter 5. User Guide 677

678 IBM Connect:Direct for z/OS: Documentation

Chapter 6. Facilities Guide

IBM Connect:Direct for z/OS Facilities OverviewIBM Connect:Direct for z/OS links technologies and moves information between networked systems andcomputers. It manages high-performance transfers by providing:

• Automation• Reliability• Efficient use of resources• Application integration• Ease of use

Note: Examples and source are mentioned in this document. Make any modifications and customizationsin a site private PDS and not in an SMP/E target PDS, unless you make them via a USERMOD.

Important: When you are using CICS API in Connect:Direct, pair SIGNONs with SIGNOFFs to avoid usingmemory and rendering the interface inactive.

IBM Connect:Direct offers choices in communications protocols, hardware platforms, and operatingsystems. It provides the flexibility to move information among mainframes, midrange systems, desktopsystems, and LAN-based workstations.

The following facilities are provided to fill specific needs:

• The Activity Reporting System (ARS) works with Connect:Direct for z/OS to produce reports of IBMConnect:Direct activity using the SAS software.

• The Console Operator interface enables you to issue all Connect:Direct for z/OS commands from a z/OSconsole by using a MODIFY command.

• Event Services Support (ESS) generates events asynchronously in IBM Connect:Direct and can be usedby external management and automated operations applications that require real-time notification ofIBM Connect:Direct activities.

• The Spool Transfer facility enables you to transfer Job Entry Subsystem (JES) spool files by copyingfrom JES spool files, to JES print queues, and to JES reader queues.

ARS Report Examples

IBM Connect:Direct for z/OS Activity ReportYou can request reports in the following ways:

• Through ARS screens using TSO/ISPF• Through a IBM Connect:Direct Process that is defined to automatically request reports• Through a pre-defined batch job stream that is run by a job scheduling subsystem

The IBM Connect:Direct for z/OS Activity Report lists IBM Connect:Direct activity by Process step. TheARS software sorts the steps for each secondary node (SNODE) location by user ID and then by Processnumber, for a specified time period.

You can specify the start date and time and the stop date and time. Following is an example of the IBMConnect:Direct for z/OS Activity Report:

© Copyright IBM Corp. 1993, 2021 679

The following table contains a description of the report fields.

Report Field Description

NODE IBM Connect:Direct node where the statistics file is being examined.

SNODE IBM Connect:Direct secondary node.

USERID IBM Connect:Direct user ID.

PROC # IBM Connect:Direct Process number.

PROC NAME IBM Connect:Direct Process name.

STEP NAME Name (or label) assigned to the Process step.

FUNCTION IBM Connect:Direct activity. Valid Process steps are COPY, RUN JOB, RUNTASK, and SUBMIT (within a Process).

ELAPSE TIME Function duration time in hh:mm:ss.hh format.

PNODE IBM Connect:Direct primary node.

CC IBM Connect:Direct completion code in hexadecimal format.

EXC Exception field is displayed “***” when a Process step does not completesuccessfully.

MSG ID IBM Connect:Direct message ID.

DATE When activity began. Date format is mm/dd/yyyy. Process start date does notconform to the DATEFORM initialization parameter.

CLASS IBM Connect:Direct Session Class

IBM Connect:Direct for z/OS Summary ReportThe IBM Connect:Direct for z/OS Summary Report summarizes activity for the node where the statisticsfile are examined. The report categorizes IBM Connect:Direct activity by SNODE for a specified timeperiod and a summary for all SNODEs.

Information includes:

680 IBM Connect:Direct for z/OS: Documentation

• Total Process steps run• Total COPY steps run• Total RUN JOB steps run, and RUN JOB steps submitted at this node• Total RUN TASK steps run, RUN TASK steps executed at this node• Total SUBMIT (within a Process) steps run and number of Processes submitted at this node• Number of successful steps and unsuccessful steps• Total bytes tested, written, sent, and received by this node• Total elapsed time for all Process steps in this time period• Average time to complete a Process step• Total elapsed time for all COPY steps• Average time to complete a COPY step• Effective send and receive rates

You can specify the start date and time and the stop date and time.

Following is an example of the IBM Connect:Direct for z/OS Summary Report

The following table contains a description of the report fields.

Report Field Description

NODE Node where the statistics file is being examined.

SNODE IBM Connect:Direct secondary node.

FIRST FUNCTION Actual date/time that first Process step began executing duringspecified time period. Includes any step that started before specifiedtime, but is under way or completes during the time period.

LAST FUNCTION Actual date/time last Process step finished executing duringspecified time period. If a step started during specified time periodbut ended after requested stop time or stop date, it is not included inthis report.

PROCESS STEPS COMPLETED Total number of Process steps completed in time period.

Chapter 6. Facilities Guide 681

Report Field Description

TOTAL COPY STEPS Total number of COPY steps run.

% TOTAL STEPS RUN WERECOPIES

Percentage of total steps run that are COPY steps.

TOTAL RUNJOB STEPS Total number of RUN JOB steps run.

% TOTAL STEPS RUN WERERUNJOB

Percentage of total steps run that are RUN JOB steps.

# RUNJOBS SUBMITTED Number of RUN JOB steps submitted to run at “NODE.”

TOTAL RUNTASK STEPS Total RUN TASK steps run.

% TOTAL STEPS RUN WERERUNTASKS

Percentage of total steps run that are RUN TASK steps.

# RUNTASKS ATTACHED Number of RUN TASK steps that are attached on “NODE.”

TOTAL SUBMIT STEPS Total number of SUBMIT steps run.

% TOTAL STEPS RUN WERESUBMITS

Percentage of total steps run that are SUBMIT (within a Process)steps.

# SUBMITS (WITHIN APROCESS)

Number of SUBMIT (within a Process) steps submitted to run at“NODE.”

SUCCESSFUL STEPS Total number of successful steps.

% OF TOTAL STEPS RUN WITHZERO RETURN CODE

Percentage of total successful steps.

UNSUCCESSFUL STEPS Total number of unsuccessful steps.

% OF TOTAL STEPS RUN WITHNON-ZERO RET CD

Percentage of total unsuccessful steps.

TOTAL BYTES WERE READ Total number of bytes read by “NODE.”

TOTAL BYTES WERE SENT Total number of bytes sent by “NODE.”

TOTAL BYTES WERE WRITTEN Total number of bytes written by “NODE.”

TOTAL BYTES WERE RECEIVED Total number of bytes received by “NODE.”

WAS TOTAL “FUNCTION” TIME Sum of elapsed times of all individual Process steps. The elapsedtime for this calculation is the time period between when the stepstarted and when the step completed.

WAS AVERAGE TIME TOCOMPLETE A FUNCTION

Total function time divided by number of Process steps run.

WAS TOTAL“COPY” TIME Sum of elapsed times for all individual COPY steps. The elapsed timefor this calculation is the time period between when the step startedand when the step completed.

WAS AVERAGE TIME TOCOMPLETE A COPY

Total COPY time divided by the total number of COPY steps run.

EFFECTIVE SEND RATE Total bytes sent divided by elapsed time. For this calculation, theelapsed time is the time between when the first COPY step in thedata set began and the last COPY step in the data set completed.

682 IBM Connect:Direct for z/OS: Documentation

Report Field Description

EFFECTIVE RECEIVE RATE Total bytes received divided by elapsed time. For this calculation, theelapsed time is the time between when the first COPY step in thedata set began and the last COPY step in the data set completed.

IBM Connect:Direct Exception ReportThe IBM Connect:Direct Exception Report lists Process steps that did not complete successfully. TheARS software sorts Process steps by SNODE, by user ID, and by Process number. The report displaysinformation unique to the executed Process step. For example, information displayed for a failed COPYstep differs from that of a failed RUN TASK step. A summary of exception cases is listed at the end of thereport.

You specify the start date and time and stop date and time. Following are the report fields.

Report Field Description

NODE IBM Connect:Direct node where the statistics file is being examined.

USERID IBM Connect:Direct user ID.

PROC # IBM Connect:Direct Process number.

PROC NAME IBM Connect:Direct Process name.

STEP NAME Name (or label) assigned to the Process step.

**function type** IBM Connect:Direct activity. Valid Process steps are PDS COPY,NONPDS COPY, RUN JOB, RUN TASK, and SUBMIT (within aProcess).

mm/dd/yyyy Data Process step began executing.

PNODE IBM Connect:Direct primary node.

SNODE IBM Connect:Direct secondary node.

COMPLETION CODE IBM Connect:Direct completion code in hexadecimal format.

Chapter 6. Facilities Guide 683

Report Field Description

MSG ID IBM Connect:Direct message ID.

SENDING NODE (COPY) Sending IBM Connect:Direct node location name.

SRC DSNAME (COPY) Source data set name.

RECEIVING NODE (COPY) Receiving IBM Connect:Direct node location name.

DEST DSNAME (COPY) Destination data set name.

DATASET CONTAINING JOB (RUNJOB) Data set containing job.

INTENDED NODE FOR JOBSUBMISSION

(RUNJOB) Intended node location where the job is submitted.

PROGRAM NAME (RUNTASK) Program name.

INTENDED NODE FOR PROGRAMEXECUTION

(RUNTASK) Intended attach node where the program is run.

DATASET CONTAINING PROCESS (SUBMIT) Data set containing Process.

INTENDED NODE FOR PROCESSSUBMISSION

(SUBMIT) Intended node location where the Process is submitted.

message Error message for IBM Connect:Direct message ID.

NON-SUCCESSFUL STEPS Total number of unsuccessful Process steps.

PROCESS STEPS RUN Total number of Process steps run.

% TOTAL PROCESS STEPS WITHNON-ZERO CODE

Percentage of Process steps unsuccessful.

NON-SUCCESSFUL COPIES Number of unsuccessful COPY steps.

COPY STEPS RUN Total number of COPY steps run.

% TOTAL RUN JOB STEPS WITHNON-ZERO CODE

Percentage of RUN JOB steps unsuccessful.

NON-SUCCESSFUL RUNTASKS Number of unsuccessful RUN TASK steps.

RUNTASK STEPS RUN Total number of RUN TASK steps run.

% TOTAL RUNTASK STEPS WITHNON-ZERO CODE

Percentage of RUN TASK steps unsuccessful.

NON-SUCCESSFUL SUBMITS Number of unsuccessful SUBMIT (within a Process) steps.

SUBMIT STEPS RUN Total number of SUBMIT (within a Process) steps run.

% TOTAL SUBMIT STEPS WITHNON-ZERO CODE

Percentage of SUBMIT (within a Process) steps unsuccessful.

Security Violations ReportThe IBM Connect:Direct for z/OS Security Violations Report lists the following types of violations for aspecified time period:

Signon security failures—Failure caused by an invalid user ID or password that signed on to IBMConnect:Direct. Each violation is recorded.

Process security failures—This failure is caused when a Process does not run due to an invalid securityauthorization. An example is a Process that does not run because the user is not defined in the IBMConnect:Direct authorization file at the remote node.

684 IBM Connect:Direct for z/OS: Documentation

Data set access security failures—Failure due to insufficient authority to access a data set.

A sample report follows:

1 IBM Connect:Direct Security Violations Report 2 NODE = SC.DUB.MWATL1 13:35 Friday, February 25, 2011 VIOLATION USERID CC MSG ID DATE TIME TYPE MyCCente 00000008 RACF001I 02/25/2011 12:21:12.5 SIGNON MWATL1 00000008 RACF097I 02/25/2011 12:23:04.4 SIGNON

You can specify the start date and time and the stop date and time.

Included in these reports are security message IDs generated by any security subsystem used with IBMConnect:Direct. Security subsystems supported include:

• IBM Resource Access Control Facility (RACF)• CA-ACF2 and CA-TOP SECRET by Computer Associates, Inc.

The following table contains a description of the report fields:

Report Field Description

NODE IBM Connect:Direct node where the statistics file is examined.

USERID IBM Connect:Direct user ID that created the security violation.

CC IBM Connect:Direct completion code in hexadecimal format.

MSG ID Security system message ID: IBM Connect:Direct, ACF2, RACF, orTOP SECRET.

DATE Date security violation occurred.

TIME Time security violation occurred.

VIOLATION TYPE Type of security violation. Valid types are SIGNON, PROCESS, andDATASET.

Connect:Direct for z/OS Function ReportsThe Function Reports provide detailed information about specific Process steps for a specified timeperiod. The following reports are included:

• IBM Connect:Direct for z/OS Non-PDS Copy Report• IBM Connect:Direct PDS Copy Report• IBM Connect:Direct Run Job Report• IBM Connect:Direct Run Task Report• IBM Connect:Direct for z/OS Submit Within a Process Report

You can request the start date and time and the stop date and time when requesting one of theConnect:Direct for z/OS Function Reports.

IBM Connect:Direct for z/OS Non-PDS Copy ReportThe IBM Connect:Direct for z/OS Non-PDS Copy Report provides information about COPY steps involvingthese transfers:

• Non-PDS data set <--------> Non-PDS data set• Non-PDS data set <--------> PDS data set member• PDS data set member <--------> Non-PDS data set

Following is an example of the IBM Connect:Direct for z/OS Non-PDS Copy Report.

Chapter 6. Facilities Guide 685

This report includes all NonPDS COPY step transmissions for a specified time period. The ARS softwaresorts COPY information for each SNODE by user ID and then in ascending order by Process number. Thefollowing table contains a description of the report fields.

Report Field Descriptions

NODE IBM Connect:Direct node where the statistics file is examined

USERID IBM Connect:Direct user ID

PROC # IBM Connect:Direct Process number

PROC NAME IBM Connect:Direct Process name

STEP NAME Name (or label) assigned to a COPY step

mm/dd/yyyy Date COPY step began executing

PNODE IBM Connect:Direct primary node

SNODE IBM Connect:Direct secondary node

TRANSMISSION TIME Elapsed time between the COPY step start and the COPY stepcompletion

COMPLETION CODE IBM Connect:Direct completion code in hexadecimal format

MSG ID IBM Connect:Direct message ID

message Short message for IBM Connect:Direct message ID

SRC DSNAME Source data set name

DEST DSNAME Destination data set name

REPORT FIELD Description of report

SENDING NODE Name of node sending the data set

RECEIVING NODE Name of node receiving the data set

686 IBM Connect:Direct for z/OS: Documentation

Report Field Descriptions

BYTES READ Number of bytes read by sending node

BYTES WRITTEN Number of bytes written by receiving node

BLOCKS READ Number of blocks read by sending node

BLOCKS WRITTEN Blocks written by receiving node (either blocks or records isdisplayed)

RECS READ Number of records read by sending node

RECS WRITTEN Number of records written by receiving node

BYTES SENT Number of bytes sent by sending node

BYTES RECEIVED Number of bytes received by receiving node

COMPRESSION% Compression percentage for sending data set

COMPRESSION% Compression percentage for receiving data set

VOLSER Sending volume serial number

VOLSER Receiving volume serial number

IBM Connect:Direct for z/OS PDS Copy ReportThe IBM Connect:Direct for z/OS PDS Copy Report provides information for each COPY step involving thePDS data set to PDS data set transfer.

Following is an example of the IBM Connect:Direct for z/OS PDS Copy Report.

This report lists all PDS COPY step transmissions by Process number for a specified time period. It listssending data set members names with each destination data set member name.

The accuracy of the data in this report is not guaranteed if you restart IBM Connect:Direct using theTCQ=COLD initialization parameter during the time period specified. ARS uses the Process number in thestatistics file to match PDS member names with a specific COPY step. Because a COLD restart begins

Chapter 6. Facilities Guide 687

numbering Processes from 1, ARS may not associate PDS member names correctly with the appropriatePDS Copy step.

The following table describes the report fields.

Report Field Description

NODE IBM Connect:Direct node where the statistics file is examined

USERID IBM Connect:Direct user ID

PROC # IBM Connect:Direct Process number

PROC NAME IBM Connect:Direct Process name

STEP NAME Name (or label) assigned to a COPY step

mm/dd/yyyy Date COPY step began executing

PNODE Name of primary node

SNODE Name of secondary node

TRANSMISSION TIME Time between the COPY step start and the COPY step completion

COMPLETION CODE IBM Connect:Direct completion code in hexadecimal format

MSG ID IBM Connect:Direct message ID

message Short message for IBM Connect:Direct message ID

SRC DSNAME Source data set name

DEST DSNAME Destination data set name

SENDING NODE Name of node sending the data set

REPORT FIELD Description of report

RECEIVING NODE Name of node receiving the data set

BYTES READ Number of bytes read by sending node

BYTES WRITTEN Number of bytes written by receiving node

BLOCKS READ Number of blocks read by sending node

BLOCKS WRITTEN Number of blocks written by receiving node (blocks or records isdisplayed)

RECS READ Number of records read by sending node

RECS WRITTEN Number of records written by receiving node

BYTES SENT Number of bytes sent by sending node

BYTES RECEIVED Number of bytes received by receiving node

COMPRESSION% Compression percentage for sending data set

COMPRESSION% Compression percentage for receiving data set

VOLSER Sending volume serial number

VOLSER Receiving volume serial number

MEMBER LIST List of sending member names and receiving member names

688 IBM Connect:Direct for z/OS: Documentation

IBM Connect:Direct for z/OS Run Job ReportThe IBM Connect:Direct for z/OS Run Job Report lists the jobs submitted for execution using the IBMConnect:Direct RUN JOB statement. Jobs are listed for a specified time period. Following is an example ofthe IBM Connect:Direct for z/OS Run Job Report.

1 IBM Connect:Direct for z/OS RUNJOB Report NODE = SC.DUB.MWATL1 USERID PROC # PROC NAME STEP NAME RUNJOB INFORMATION ****** ****** ********* ********* ********************************************************* MWATL1 6 MWCOPY RJ 02/25/2011 PNODE = SC.DUB.MWATL1 SNODE = SC.DUB.MWATL1 COMPLETION CODE = 00000000 MSG ID = SRJA000I C:D RUN JOB FUNCTION COMPLETED SUCCESSFULLY. ================================================ DSNAME ==> MWATL1.JCL.LIB(NDMBAT1) JOB # ==> 93960 JOB SUBMITTED ON SC.DUB.MWATL1

The ARS software sorts all RUN JOB steps for each SNODE by userid and then in ascending order byProcess number.

The following table contains a description of the report fields.

Report Field Description

NODE IBM Connect:Direct node where the statistics file is being examined

USERID IBM Connect:Direct user ID

PROC # IBM Connect:Direct Process number

PROC NAME IBM Connect:Direct Process name

STEP NAME Name (or label) assigned to a RUN JOB step

mm/dd/yyyy Date RUN JOB step submitted to run

PNODE IBM Connect:Direct primary node

REPORT FIELD Description of report

SNODE IBM Connect:Direct secondary node

COMPLETION CODE IBM Connect:Direct completion code in hexadecimal format

MSG ID IBM Connect:Direct message ID

message Short message for IBM Connect:Direct message ID

DSNAME Data set name containing job stream to be submitted

JOB # Number assigned to job by operating system

JOB SUBMITTED ON IBM Connect:Direct node where the job is submitted to run

Run Task ReportThe IBM Connect:Direct for z/OS Run Task Report tracks all tasks (programs) for a specified time periodthat executed under the control of the IBM Connect:Direct RUN TASK statement. Following is an exampleof the IBM Connect:Direct for z/OS Run Task Report.

Chapter 6. Facilities Guide 689

The ARS software sorts all RUN TASK steps for each SNODE by userid and then in ascending order byProcess number.

The following table contains a description of the report fields.

Report Field Description

NODE IBM Connect:Direct node where the statistics file is being examined

USERID IBM Connect:Direct user ID

PROC # IBM Connect:Direct Process number

PROC NAME IBM Connect:Direct Process name

STEP NAME Name (or label) assigned to a RUN TASK step

mm/dd/yyyy Date RUN TASK step attached and executed

PNODE IBM Connect:Direct primary node

REPORT FIELD Description of report

SNODE IBM Connect:Direct secondary node

COMPLETION CODE IBM Connect:Direct completion code in hexadecimal format

MSG ID IBM Connect:Direct message ID

message Short message for IBM Connect:Direct message ID

PROGRAM NAME Name of program module attached

PROGRAM ATTACHED ON IBM Connect:Direct node where the task is attached and executed

IBM Connect:Direct for z/OS Submit Within a Process ReportThe IBM Connect:Direct for z/OS Submit Within a Process Report lists Processes that are submittedto Connect:Direct for execution using the IBM Connect:Direct Submit (within a Process) statement fora specified time period. Following is an example of the IBM Connect:Direct for z/OS Submit Within aProcess Report.

690 IBM Connect:Direct for z/OS: Documentation

IBM Connect:Direct for z/OS Submit within a Process Report NODE = SC.DUB.MWATL1- USERID PROC # PROC NAME STEP NAME SUBMIT INFORMATION ****** ****** ********* ********* ******************************************************************************- MWATL1 1 OS3903 STEP01 02/25/2011 PNODE = SC.DUB.MWATL1 SNODE = SC.DUB.MWATL1 COMPLETION CODE = 00000000 MSG ID = SSUB000I THE SUBMIT CONTROL BLOCK HAS BEEN SUCCESSFULLY CONSTRUCTED. ============================================================================== DSNAME ==> MWATL1.NDM.PROCESS.LIB(OS3903) PROCESS SUBMITTED ON SC.DUB.MWATL10 --------------------------------------------------------------------------------------------------------------------------- MWATL1 4 PDS STEP2 02/25/2011 PNODE = SC.DUB.MWATL1 SNODE = SC.DUB.MWATL1 COMPLETION CODE = 00000000 MSG ID = SSUB000I THE SUBMIT CONTROL BLOCK HAS BEEN SUCCESSFULLY CONSTRUCTED. ============================================================================== DSNAME ==> MWATL1.NDM.PROCESS.LIB(PDS) PROCESS SUBMITTED ON SC.DUB.MWATL10 --------------------------------------------------------------------------------------------------------------------------- MWATL1 4 PDS STEP2 02/25/2011 PNODE = SC.DUB.MWATL1 SNODE = SC.DUB.MWATL1 COMPLETION CODE = 00000000 MSG ID = SSUB000I THE SUBMIT CONTROL BLOCK HAS BEEN SUCCESSFULLY CONSTRUCTED. ============================================================================== DSNAME ==> MWATL1.NDM.PROCESS.LIB(PDS) PROCESS SUBMITTED ON SC.DUB.MWATL10 --------------------------------------------------------------------------------------------------------------------------- MWATL1 7 RTBR14 STEP2 02/25/2011 PNODE = SC.DUB.MWATL1 SNODE = SC.DUB.MWATL1 COMPLETION CODE = 00000000 MSG ID = SSUB000I THE SUBMIT CONTROL BLOCK HAS BEEN SUCCESSFULLY CONSTRUCTED. ============================================================================== DSNAME ==> MWATL1.NDM.PROCESS.LIB(RTBR14) PROCESS SUBMITTED ON SC.DUB.MWATL10 --------------------------------------------------------------------------------------------------------------------------- MWATL1 8 RTBR14 STEP2 02/25/2011 PNODE = SC.DUB.MWATL1 SNODE = SC.DUB.MWATL1 COMPLETION CODE = 00000000 MSG ID = SSUB000I THE SUBMIT CONTROL BLOCK HAS BEEN SUCCESSFULLY CONSTRUCTED. ============================================================================== DSNAME ==> MWATL1.NDM.PROCESS.LIB(RTBR14) PROCESS SUBMITTED ON SC.DUB.MWATL10 --------------------------------------------------------------------------------------------------------------------------- MWATL1 9 RTBR14 STEP2 02/25/2011 PNODE = SC.DUB.MWATL1 SNODE = SC.DUB.MWATL1 COMPLETION CODE = 00000000 MSG ID = SSUB000I THE SUBMIT CONTROL BLOCK HAS BEEN SUCCESSFULLY CONSTRUCTED. ============================================================================= DSNAME ==> MWATL1.NDM.PROCESS.LIB(RTBR14) PROCESS SUBMITTED ON SC.DUB.MWATL1

The ARS software sorts all SUBMIT steps for each SNODE by userid and then in ascending order byProcess number.

The following table contains a description of the report fields.

Report Field Description

NODE IBM Connect:Direct node where the statistics file is being examined

USERID IBM Connect:Direct user ID

PROC # IBM Connect:Direct Process number

PROC NAME IBM Connect:Direct Process name

STEP NAME Name (or label) assigned to a SUBMIT (within a Process) step

Chapter 6. Facilities Guide 691

Report Field Description

mm/dd/yyyy Date SUBMIT (within a Process) step ran

PNODE IBM Connect:Direct primary node

REPORT FIELD Description of report

SNODE IBM Connect:Direct secondary node

COMPLETION CODE IBM Connect:Direct completion code in hexadecimal format

MSG ID IBM Connect:Direct message ID

message Short message for IBM Connect:Direct message ID

DSNAME Data set name containing the IBM Connect:Direct Process

Only available when SUBNODE=PNODE.

PROCESS SUBMITTED ON IBM Connect:Direct node where the Process was submitted to run

Activity Reporting SystemThe Activity Reporting System (ARS) produces reports of IBM Connect:Direct activity. While IBMConnect:Direct produces statistics, ARS enables you to access more information and provides sortingcapabilities.

You can request ARS reports in three ways:

• Through ARS screens using IBM Time Sharing Option/Interactive System Productivity Facility (TSO/ISPF)

• Automatically through a IBM Connect:Direct Process• Schedule a batch job through a job scheduling subsystem

With ARS, you do not have to pass data to z/OS system management facilities (SMF) or write SAS requeststo print IBM Connect:Direct activity reports. Use ARS as a standard reporting format throughout a networkfor tracking IBM Connect:Direct activity.

Note: ARS requires a SAS base running under z/OS and Connect:Direct for z/OS must be active.

ARS and IBM Connect:DirectIBM Connect:Direct automatically collects statistical data and stores it in a data set. ARS can access thisstatistical data and produce the following reports for a selected time period:

• IBM Connect:Direct Activity Report lists activity by Process step• IBM Connect:Direct Summary Report summarizes all activity

IBM Connect:Direct Exception Report lists all Process steps that are not successful

IBM Connect:Direct Security Violations Report lists security violations by signon security failures,Process security failures, and data set access security failures

IBM Connect:Direct Function Reports provides the activity reports for the following types of Processsteps:

– Non-Partitioned Data Set (PDS) COPY– PDS COPY– RUN JOB– RUN TASK– Submit Within a Process

Following are two methods to request ARS reports:

692 IBM Connect:Direct for z/OS: Documentation

• Through the ARS screens where you can create a job stream that requests reports. The screensautomatically build the job or allow you to edit the sample report job stream.

• By using the sample JCL member that is provided with ARS.

Business Solutions Using ARSARS provides data center management with additional tools to monitor and track IBM Connect:Directusage. Use the information in the reports to track attempted security violations, analyze capacity planningrelated data, examine IBM Connect:Direct utilization, and isolate failed IBM Connect:Direct Processes.

The following table describes how to use ARS.

Function Description

Data CenterManagement

The data center manager wants to keep track of IBM Connect:Directactivities. The IBM Connect:Direct Activity Report lists all Process steps thatoccurred in this data center during a time period. The IBM Connect:DirectNonPDS Copy Report and IBM Connect:Direct PDS Copy Report provideadditional information on all COPY steps performed.

Security Violations A system administrator requests a list of any IBM Connect:Direct-relatedsecurity violations on a daily basis. The IBM Connect:Direct SecurityViolations Report lists the following violations:

• Sign on security failures• Processes not run due to lack of authorization• Data set access security violations

Capacity Planning The capacity planner at a data center needs to know how many bytes aretransferring between this data center and other data centers and the totaltransmission times. The IBM Connect:Direct Summary Report provides thistype of information by remote data center for a specified time period.

IBM Connect:DirectUtilization

The data center administrator studies IBM Connect:Direct utilization byexamining how many application programs are submitted or invoked usingIBM Connect:Direct. The administrator uses this information with a jobscheduling system to produce a comprehensive analysis of all jobs run ata data center.

Two ARS reports provide this type of utilization summary.

The IBM Connect:Direct Run Job Report provides information about all jobssubmitted by IBM Connect:Direct.

The IBM Connect:Direct Run Task Report provides information about allprograms executed under the control of IBM Connect:Direct.

Problem Isolation The IBM Connect:Direct Exception Report is an excellent tool for researchingwhy a Process does not run. This report lists each failed Process for arequested time period along with the reason for the failure.

Requesting ARS Statistical ReportsTo request ARS statistical reports, complete the following procedures:

• Request the ARS report using ARS screens• Run the job

ARS screens build a job stream to produce any of the ARS reports. For this reason, the screens are mostuseful in cases where you need individual reports instead of volume reports.

After ARS screens build the job stream and submit it to run, the job performs the following:

Chapter 6. Facilities Guide 693

• Signs on to IBM Connect:Direct• Creates a temporary data set to hold the specified statistics• Accesses the IBM Connect:Direct statistics file and copies statistics to a temporary data set• Executes the ARS report routine using the IBM Connect:Direct statistics as input data• Sends the report to the selected output location• Deletes the temporary data set

Requesting Reports Using ARS ScreensThe ARS screens identify the information to build the job. Certain information is retained betweensessions to prevent the need to enter the same information each time you request a report.

To access the ARS screens through the IUI:

Select ADMIN from the Primary Options Menu.

View Modify Control Create Execute Help------------------------------------------------------------------------------CD.ART IBM Connect:Direct for z/OS Primary Options MenuOption ===>

Select one of the following:

CF - Copy a file ********************* SB - Submit a predefined process * * DF - Define a process using ISPF Edit * Today: 08.30.2018 * SS - View statistics for a completed process * Time: 14:00 * S2 - Advanced view statistics * UID: USER12 * MB - Submit a batch to Connect:Enterprise for z/OS * * CP - Change characteristics of a process * OPT Enabled * DP - Delete a non-executing process * OPT Part-Enabled * FP - Flush an executing process * OPT Disabled * SP - View data about an executing process * * PS - Suspend an executing process ********************* MSG - View Connect:Direct message text SW - Swap among concurrent Connect:Direct sessions SD - View/Change your Connect:Direct signon information defaults NM - View information in the Connect:Direct network map WHO - View characteristics of your Connect:Direct IUI environment SPF - Enter ISPF/PDF AUTH - View your Connect:Direct function authorization MS - Sign on to multiple Connect:Direct nodes concurrently ADMIN - Perform Connect:Direct administrative functions

1. From the Administrative Options Menu, select ARS.

694 IBM Connect:Direct for z/OS: Documentation

View Modify Control Delete Secure+ Help------------------------------------------------------------------------------CD.ART Connect:Direct Administrative Options MenuOption ===>

Select one of the following:

ST - View type record ********************* IT - Insert/Update type record * * DT - Delete type record * Today: 08.30.2018 * SU - View user authorization record * Time: 14:05 * IU - Insert/Update user authorization record * UID: USER12 * DU - Delete user authorization record * * TS - View Connect:Direct tasks * OPT Enabled * TF - Flush a Connect:Direct task * OPT Part-Enabled * S - Execute Secure Plus Commands * OPT Disabled * MD - Modify Connect:Direct trace characteristics * * C - Enter a native Connect:Direct command ********************* SN - Terminate Connect:Direct ARS - ARS reporting facility NM - View information in the Connect:Direct network map UNM - Update the Connect:Direct network map INQ - Inquire about DTF internal status STAT - Perform statistics functions

2. To request the report, provide signon data, and specify the time period for the report, continue with thefollowing steps.

3. To submit the job stream without changing any data, type SUB (submit) at the CMD field and thenpress Enter.

$cd.node Connect:Direct for z/OS - ARS REPORT OPTIONS CMD ==> hh:mm AC - ACTIVITY PS - NON-PDS COPY SM - SUMMARY PO - PDS COPY EX - EXCEPTION RJ - RUNJOB SC - SECURITY RT - RUNTASK SB - SUBMIT REPORT TYPE ==> EDIT JCL ==> (Y,N) Connect:Direct SIGNON PARAMETERS -------------------------------- USER ID ==> $uid PASSWORD ==> NETMAP NAME ==> $cd.netmap TRANSPORT ==> NET COMMUNICATION ADDRESS ==> ( , ) REPORTING RANGE --------------- START DATE ==> START TIME ==> STOP DATE ==> STOP TIME ==>

The following table contains a description of the screen fields.

Field Description

REPORT TYPE Specifies the ARS report.

EDIT JCL Specifies an option to edit JCL.

USER ID Specifies the userid for signing on to IBM Connect:Direct, if your securityenvironment requires it. (optional)

PASSWORD Specifies the password needed to access IBM Connect:Direct. (optional)

NETMAP NAME Specifies the name of the IBM Connect:Direct Network Map.

TRANSPORT Enables override of signon defaults for DGADBATC transport type.

COMMUNICATIONADDRESS

Specifies port number and IP address with TRANSPORT=TCP.

Chapter 6. Facilities Guide 695

Field Description

REPORTING RANGE Identifies the date, day or time period that you want the requested reportto cover. (optional)

If all four fields are blank, the contents of the statistics file is used.

START DATE or STOPDATE

Specifies the date or day that the statistics records are selected for the ARSreport.

You can specify the day (dd), month (mm), and year (yy for 2-digit yearand yyyy for 4-digit year). Use periods or backslashes (\) to separate thecomponents of a date value.

You can specify the date (dd), month (mm), and year (yy) in one ofthe following formats: yymmdd or yyyymmdd; yy/mm/dd or yyyy/mm/dd;yy.mm.dd or yyyy.mm.dd; mmddyy or mmddyyyy; mm/dd/yy or mm/dd/yyyy; mm.dd.yy or mm.dd.yyyy; or the Julian date, yyddd or yyyyddd;yy/ddd or yyyy/ddd; or yy.ddd or yyyy.ddd. If you only specify the date,the time defaults to 00:00.

This date must have the same format as specified in the DATEFORMinitialization parameter.

You can also use day in these fields to indicate day of the week for whichthe statistics records are searched. Valid names include MOnday, TUesday,WEdnesday, THursday, FRiday, SAturday, and SUnday.

You can also specify TODAY, which searches for the statistics recordstoday; or TOMORROW, which searches for statistics records the next day;or YESTER, which searches for statistics records for yesterday.

START TIME or STOPTIME

Specifies the time of day in hours (hh), minutes (mm), and seconds (ss)when the statistics records are selected for the ARS report. Specify AM orPM. You can express the time of day using the 24-hour clock or the 12-hourclock. If you use the 24-hour clock, valid times are 00:00-24:00. If you usethe 12-hour clock, you can express 1:00 hours as 1:00AM, and you canexpress 1:00 PM as 13:00 hours. If you do not use AM and PM, the 24-hourclock is assumed. You do not need to specify minutes and seconds.

You can also specify NOON, which searches for the statistics records atnoon, or MIDNIGHT, which searches for the statistics records at midnight.

The default for the time is 00:00:00, the beginning of the day.

If you do not specify START TIME and STOP TIME but you do specify theSTART DATE and STOP DATE, the time range default is 00:00 to 24:00.

ARS Connect:Direct Requirements ScreenThe ARS Connect:Direct Requirements screen in the following figure identifies specific job streamparameters for the job card and IBM Connect:Direct-related information.

696 IBM Connect:Direct for z/OS: Documentation

$cd.node Connect:Direct for z/OS - ARS (Job and File Requirements) CMD ==> hh:mm UP TO 3 LINES FOR JOBCARD INFO ==> ________________________________________________________________________ ==> ________________________________________________________________________ ==> ________________________________________________________________________ STEPLIB DATA SET NAME FOR Connect:Direct PROGRAMS (OPTIONAL): ==> ____________________________________________ ==> ____________________________________________ Connect:Direct PUBLIB PROCESS LIBRARIES (1 REQUIRED): ==> ____________________________________________ ==> ____________________________________________ Connect:Direct MESSAGE DATA SET NAME (REQUIRED): ==> ____________________________________________ UNIT SPECIFICATION FOR Connect:Direct TEMPORARY DATASET: ==> ________

The following table contains a description of the screen fields.

Field Description

JOBCARD INFO Typical job card information. Use the COND=(0,NE) for best results,meaning the job does not run if an error is found when configuring thejob.

STEPLIB DATA SET NAME FORConnect:Direct PROGRAMS

Name of the library containing the IBM Connect:Direct load modules.You can type two libraries in this section. Optional if the IBMConnect:Direct load modules are available via LINKLIST otherwise aSTEPLIB is required.

Connect:Direct PUBLICPROCESS LIBRARIES

Specifies the name of the library containing IBM Connect:DirectProcesses.

Connect:Direct MESSAGEDATA SET NAME

Specifies the name of the message data set containing the IBMConnect:Direct messages.

ARS SAS Requirements Screen and FieldsThe ARS SAS Requirements screen in the following figure identifies specific JCL parameters for SAS-related information.

$cd.node Connect:Direct for z/OS - ARS (SAS Files and Output) CMD ==> hh:mm SAS CATALOGED PROCEDURE (REQUIRED): ==> ____________________________________________ DATASET NAME CONTAINING SAS ROUTINES (REQUIRED): ==> ____________________________________________ ONE OF THE FOLLOWING MUST BE PROVIDED : OUTPUT DATA SET NAME : ==> ____________________________________________ OUTPUT (SYSOUT) CLASS : ==> _

The following table contains a description of the screen fields.

Field Description

SAS CATALOGEDPROCEDURE

Identifies the name of the SAS cataloged procedure, which is a collection of JCLstatements required to execute SAS for batch processing at your installation.

DATA SET NAMECONTAINING SASROUTINES

Specifies where the ARS routines ($CD.SDGAMAP) that interact with SAS arelocated.

Chapter 6. Facilities Guide 697

Field Description

OUTPUT DATA SETNAME

You must preallocate the sequential data set designated in this field with thefollowing attributes:

RECFM=FBA

LRECL=240

BLKSIZE=3120

If this field is left blank, you must specify the OUTPUT (SYSOUT) CLASS field.

OUTPUT (SYSOUT)CLASS

Specifies the SYSOUT class that automatically sends the output to a designatedprinter queue (optional). If you leave this field blank, you must specify theOUTPUT DATASET NAME field.

Note: If you are requesting the IBM Connect:Direct Summary report and routingit to a data set, ensure that the data set is empty. If the data set is notempty, this report is placed after the data already in the data set. The IBMConnect:Direct Summary Report is automatically allocated with DISP=MODinstead of DISP=SHR.

Job Streams CreatedAfter completing the procedure, ARS builds a job stream, as in the following example. If you requestedEDIT, ARS displays the job after completing the screens.

You can review the job stream before submitting it. Following is an example of the JCL which is generatedusing member DGAJARS from $CD.SDGASENU.

//JOBNAME JOB (ACCT), ’NAME’, NOTIFY=TSOID,TIME=((1),// REGION=0M,MSGCLASS=X,CLASS=B//*//*//DGADBATC EXEC PGM=DGADBATC,PARM=’YYSLN’//STEPLIB DD DISP=SHR,DSN=$CD.SDGALINK//SYSUDUMP DD SYSOUT=*//DMPUBLIB DD DISP=SHR,DSN=$CD.SDGAPROC//DMMSGFIL DISP=SHR,DSN=$CD.MSG//TEMPDSN DSN=&CDAPI,DISP=(NEW,PASS),UNIT=PTEMP,// DCB=(DSORG=PS,RECFM=VBA,LRECL=4100,BLKSIZE=4104),// SPACE=(4104,(70,13))//DMPRINT DD SYSOUT=*//SYSIN DD *SIGNON USERID=(NAME,,) -NETMAP=$CD.NETMAP TMPDD=TEMPDSNSEL STAT WHERE (STARTT = (06/1/2010,12:00AM) - STOPT = 07/1/2010,11:59PM) ) FILESIGNOFF/*//*///SASTEP EXEC $SASPROC,// OPTIONS=’DQUOTE MACRO MACROGEN MERROR MISSING="-"’//WORK DD UNIT=PTEMP,SPACE=(CYL,(20,10))//NDMX0001 DD DISP=(OLD,DELETE),DSN=&CDAPI//DMMSGFIL DD DISP=SHR,DSN=$CD.MSG//FT20F001 DD DISP=SHR,DSN=$OUTPUT.DATASET.NAME//SYSIN DD DISP=SHR,DSN=$CD.SDGAMAP(ACTIVITY)

Running the JobWhen a job runs, it performs the following:

• Signs on to IBM Connect:Direct• Creates a temporary data set to hold the specified statistics• Copies statistics to the temporary data set

698 IBM Connect:Direct for z/OS: Documentation

• Executes the ARS report routine using the IBM Connect:Direct statistics as input data• Sends the report to the selected output location• Deletes the temporary data set

Requesting Multiple ARS Reports or Scheduled ProcessingYou can request ARS reports without using the ARS screens. You can submit multiple ARS reports at onetime or submit ARS reports for scheduled processing.

You can request ARS reports without using ARS screens by editing a sample job stream to specifyprocessing requirements and report types. Also, when the output of a multiple report request is routed toa data set, some ARS report routines can require a minor edit change.

Modifying the Sample Job StreamModify the sample job stream in $CD.SDGAJCL(DGAJARS2) in order to customize the job stream with yourcompanies information.

These steps provide line-by-line instructions for modifying the sample job stream. These modificationsare also detailed in the $CD.SDGAJCL(DGAJARS2) file.

1. Modify the job card to uniquely identify your job.2. Change $CD.SDGALINK to the appropriate IBM Connect:Direct load library name.3. Change $CD.SDGAPROC to the appropriate IBM Connect:Direct Process library name.4. Change all occurrences of $CDVSAM.MSG to the IBM Connect:Direct message data set name.5. Change $UID to your IBM Connect:Direct user ID. Also add the password, if needed.6. Change $CDVSAM.NETMAP to your Network Map data set name.7. Change all occurrences of $UNITNAME to the valid unit name.8. Change $SASPROC to the name of the SAS cataloged procedure used at your installation.9. Route the output to one of the two options:

• Route to the SYSOUT class. Look for FT20F001 DD.• Change all occurrences of $OUTPUT.DATASET.NAME to the name of the data set where you route

the output. Preallocate this data set as FBA with an LRECL of 240 and BLKSIZE of 3120. Ensurethat the data set is empty before running this job. Complete the instructions in Multiple Reports toan Output Data Set.

10. Change $CD.SDGAMAP to the name of the data set containing the SAS programs.

Note: If you would like to define the time span that will be reported, modify the SEL Statisticscommand in the SYSIN stream of the DMBATCH step to include start and stop times. The default is areport on the entire STAT file.

Job Stream DefinitionsThe following table defines the parameters and SAS options for the sample job stream.

Report Field Definition

JOBCARD INFO Specifies the typical job card information. Use the COND=(0,NE) for best results. Thismeans that the second step of the job does not run if an error occurs in the first step.

DGADBATC Specifies the program name of the IBM Connect:Direct batch interface.

STEPLIB Specifies the library containing the IBM Connect:Direct load modules.

DMPUBLIB Specifies the library containing the IBM Connect:Direct Processes.

DMMSGFIL Specifies the IBM Connect:Direct message data set that accesses the messages.

Chapter 6. Facilities Guide 699

Report Field Definition

TEMPDSN Specifies the temporary data set containing the extract from the IBM Connect:Directstatistics file that is used as input to SAS. This is always specified as (NEW, PASS) sothat when you create the data set, the extracted data is saved in it, and then passedon to the next step.

DMPRINT(Optional)

Specifies where the job output from DGADBATC goes. This is useful if an error occursin DGADBATC.

SYSPRINT Specifies where the job execution messages goes.

SYSIN Contains the IBM Connect:Direct control statements to extract from the statistics file.Represent SYSIN as a sequential data set, PDS member, or instream data set.

SASTEP Specifies the name of the SAS cataloged procedure used at your installation with thefollowing options:

DQUOTE specifies that the system accepts double quotes.

MACRO specifies that the SAS macro library is available.

MACROGEN specifies that the system can print SAS macros.

MERROR specifies that a warning message is produced if a name is prefixed with apercent sign to indicate a SAS macro, but the name is not a valid SAS macro.

MISSING specifies that dashes (-) are inserted when a numeric character is missing inthe report field.

WORK Specifies the work area used by SAS for processing.

NDMX0001 Specifies the temporary data set that contains the extract from the IBMConnect:Direct statistics file. Specify the data set parameters (OLD, DELETE) so thatthe data set is deleted automatically after processing.

DMMSGFIL Specifies the name of the IBM Connect:Direct message data set.

SASPROGS Identifies the name of the data set containing the SAS routines to produce the reports.See %INCLUDE parameter in this table.

FT20F001 Specifies the DD statement used by SAS to route output. This DD statement can beeither output to a data set or SYSOUT class. If it is to a data set, you must preallocatethe data set, it must be sequential, and have the following attributes:

RECFM=FBA; LRECL=240; BLKSIZE=3120.

SYSIN Specifies SYSIN for SAS.

%INCLUDE Contains a special SAS control statement that enables you to execute SAS programsthat are stored separately from their JCL. The first name after SASPROGS identifiesthe DD name that references the location of the SAS programs. The requested ARSreport routine names are placed inside of the parentheses:

DGAACTIV specifies the IBM Connect:Direct for z/OS Activity Report

DGAAEXEC specifies the IBM Connect:Direct for z/OS PDS Copy Report

DGAARUNJ specifies the IBM Connect:Direct for z/OS Run Job Report.

DGAARUNT specifies the IBM Connect:Direct for z/OS Run Task Report.

DGAASEC specifies the IBM Connect:Direct for z/OS Security Violations Report.

DGAASUB specifies the IBM Connect:Direct for z/OS Submit Within a Process Report.

DGAASUM specifies the IBM Connect:Direct for z/OS Summary Report.

700 IBM Connect:Direct for z/OS: Documentation

Sample IBM Connect:Direct Process That Submits Job StreamThe DGAXRPRC member in $CD.SDGASAMP in the following figure contains a IBM Connect:Direct Processthat runs the job stream discussed in the previous section, Modifying the Sample Job Stream.

You can set up the sample Process to run automatically on a specified time interval, by submittingthis Process with the IBM Connect:Direct SUBMIT command, specifying the STARTT parameter andRETAIN=YES parameter.

RPTPROC -* THIS PROCESS WILL SUBMIT FOR EXECUTION THE JCL TO RUN ARS* CHANGE $SECONDARY.NODE TO THE DESIRED SNODE NAME FOR THE PROCESS* CHANGE $TSOID TO YOUR TSO ID* CHANGE $CD.SDGACNTL(DGAJARS) TO THE DATA SET NAME CONTAINING THE JCL* TO RUN ARS PROCESS - SNODE=$SECONDARY.NODE - NOTIFY=$TSOID STEPONE - RUN JOB ( - DSN=$CD.SDGACNTL(DGAJARS) - )

You need to modify the following items if you choose to use this sample Process. Copy DGAXRPRC from$CD.SDGASAMP to your process library before editing it.

1. Change $SECONDARY.NODE to the appropriate SNODE.2. Change $TSOID to your TSO ID.3. Change $CD.SDGAJCL(DGAJARS) to the data set name containing the job that runs ARS.

Multiple Reports to an Output Data SetComplete this procedure only when you request multiple ARS report types in one job and the reports aresent to an output data set. The IBM Connect:Direct Activity Report and Security Violations Report requirea minor edit change in the ARS routine if you include them in a multiple report request.

Before modifying the ARS routines, make a copy of the $CD.SDGAMAP, which contains all report routines.Use the first copy when you request one report (in batch mode or using the ARS screens). The secondcopy can contain the modified routines when you make multiple report requests in a job.

CAUTION: $CD.SDGAMAP contains members ALIASed. If you edit an alias, it becomes a member.

You can submit the ARS report routines using TSO. The routines are in the $CD.SDGAMAP. The followingtable lists the types of reports and the corresponding members in the $CD.SDGAMAP that requiremodification.

Report Type Member Name

IBM Connect:Direct Activity Report DGAACTIV

IBM Connect:Direct Security Violations Report DGAASEC

Modify the PROC PRINTTO statement listed in the members so that the output from one report appendsrather than overlaying output from the previous report in the designated output file. Change the ARSreport routine from:

PROC PRINTTO NEW UNIT=20

to:

Chapter 6. Facilities Guide 701

PROC PRINTTO UNIT=20;

ARS Record LayoutsTo customize ARS reports, modify the ARS reports or develop new reports. Examples include:

• Change ARS report headings, spacing, field titles, and output format• Access additional information from the IBM Connect:Direct statistics file to enhance ARS reports or to

develop new reports

The ARS routines do not use all of the IBM Connect:Direct fields in the IBM Connect:Direct statisticsrecords. The SAS Informat variables for these records are located in the $CD.SDGAMAP library. Accessthe information by the member names listed in the following table.

Note: Use two-character designations for records types when browsing the IBM Connect:Direct statisticsfile.

Member Name Contents of Member Record Types

DGAAAER Authorization Event Record IU=INSert USER UU=UPDate USERSU=SELect USER DU=DELete USER

DGAACPTR Change Process Termination Record CH=CHange PROCess

DGAACTR Copy Termination Record CT=COPY

DGAADPTR Delete Process Termination Record DP=DELete PROCess

DGAADTR Display Statistics Record SP=SELect PROCess DT=SELectTASK FT=FLUSH TASK SS=SELectSTATistics SN=SELect NETmap

DGAAFPTR Flush Process Termination Record FP=FLUSH PROCess

DGAAFMCR PDS Member Copy Record MC=PDS member COPY

DGAAPPSR Process Submit Statistics Record PS=SUBmit statement SW=SUBmitcommand

DGAAPTR Process Termination Record PT=PROCess

DGAARJTR Run Job Termination Record RJ=RUN JOB

DGAARTTR Run Task Termination Record RT=RUN TASK

DGAASFR Signon/Signoff Statistics Record SI=SIGNON SO=SIGNOFF

DGAASDCR Start IBM Connect:Direct Command Record SD=Start IBM Connect:Direct

DGAASTDC Stop IBM Connect:Direct Statistics Record ST=STOP IBM Connect:Direct

DGAAWTOS Write to Operator (WTO) Statistics Record WT=Write to Operator

Description of an SAS VariableThe SAS Informat variables for these records are located in the $CD.SDGAMAP library. An example ofan SAS Informat variable is @5 SASFIELD PK1. Variable descriptions for this example are listed in thefollowing table.

Variable Description

@n Identifies the position of the variable in the IBM Connect:Direct statistics record (relativeto 1). Always identified by an @.

702 IBM Connect:Direct for z/OS: Documentation

Variable Description

SASFIELD Specifies the SAS name for the corresponding IBM Connect:Direct field name. The SASname variable must follow the position variable (@n).

PK1 Specifies the type and length of the SAS Informat variable used in the maps. The typevariable must follow the name variable (SASFIELD).

Type variable used in the maps are:

HEX—numeric hexadecimal IB—integer binary PD—packed decimal PIB—positive integerbinary PK—packed unsigned $n—standard character $CHAR—characters with blanks$HEX—character hexadecimal $VARYING—variable-length values

Authorization Event RecordThe following table shows each field available in the Authorization Event record. The DGAAAER memberof the $CD.SDGAMAP library contains the SAS maps of the IBM Connect:Direct statistics record.

Field Names Field Description

AERECLN Length of this record.

AERTYPE Record type indicates specific data in statistics record: IU=INSert;UU=UPDate USER; SU=SELect USER; and DU=DELete USER.

AERTIME Time that event was recorded in hh/mm/ss/tt format.

AEDATE Date that event was recorded in Julian date format (yyyydddf).

AEPROCNM Process name.

AEPROCNO Process number.

AEUNODE User node of the submitter.

AEUID Userid of the submitter.

AESTEP Step name or label.

AESTIME Time that Process started in hh/mm/ss/tt format.

AESDATE Date that Process started in Julian date format (yyyydddf).

AESCC Step completion code.

AEMSGID Message ID.

AESDSNL Length of data set name.

AESDSN Source data set name.

AESDSTYP Data set type (LIB, DSN).

AEEVENT Event code.

AEEVENTQ Event code qualifier.

Change Process Termination RecordThe following table shows each field available in the IBM Connect:Direct Change Process Terminationrecord. The DGAACPTR member of the $CD.SDGAMAP library contains the SAS maps of the IBMConnect:Direct statistics record.

Chapter 6. Facilities Guide 703

Field Names Field Description

CHRECLN Length of this record.

CHRTYPE Record type – CH indicates the Change Process Termination Record.

CHTIME Time that CHange PROCess command completed in hh/mm/ss/tt format.

CHDATE Date that CHange PROCess command completed in Julian date format (yyyydddf).

CHPROCNM Process name.

CHPROCNO Process number.

CHSTEP Step name or label.

CHUNODE User node ID of the submitter.

CHUID Userid of the submitter.

CHSTIME Time that CHange PROCess command started in hh/mm/ss/tt format.

CHSDATE Date that CHange PROCess command started in Julian date format (yyyydddf).

CHSCC Step completion code-displays normal completion code.

CHMSGID Message ID.

CHRMNID Node where message routed.

CHRMUID Userid where message routed.

CHSCHTME Time that Process was scheduled in hh/mm/ss/tt format.

CHSCHDTE Date that Process was scheduled in Julian date format (yyyydddf).

CHSCHDAY Day that Process was scheduled.

CHPRTY New Process priority in the IBM Connect:Direct Transmission Control Queue (TCQ).

CHRETAIN Keeps copy in TCQ after execution.

CHPROC ALL/PROCNAME/PROCNUMBER.

CHNDEST New destination node.

CHHOLD Process status in hold queue: Q=quiesce or I=immediate.

CHNPRTY New priority.

CHREL Release Processes=R.

CHRET Retain Processes=R.

CHNRMNID New node ID messages to be routed.

CHNRMUID New userid messages to be routed.

CHNEWTME New scheduled time in hh/mm/ss/tt format.

CHNEWDTE New scheduled date in Julian date format (yyyydddf).

CHNPLCLP New PNODE PLEXCLASS

CHPLCLP Old PNODE PLEXCLASS value

CHNPLCLS New SNODE PLEXCLASS value

CHPLCLS Old SNODE PLEXCLASS value

CHNODNM NODE name to be changed

704 IBM Connect:Direct for z/OS: Documentation

Field Names Field Description

CHRFRSH 'R' is refresh from NM

Copy Termination RecordThe following table shows each field available in the Copy Termination record. The DGAACTR member ofthe $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

CTCLASS Session class.

CTRECLN Length of this record.

CTRTYPE Record type – CT indicates the Copy Termination record.

CTTIME Time that COPY step completed in hh/mm/ss/tt format.

CTDATE Date that COPY step completed in Julian date format(yyyydddf).

CTSTIME Time that COPY step started in hh/mm/ss/tt format.

CTSDATE Date that COPY step started in Julian date format (yyyydddf).

CTSCC Step completion code. Displays normal completion code.

CTMSGID Message ID.

CTPROCNM Process name.

CTPROCNO Process number.

CTSTEP Step name or label.

CTUNODE User node ID of the submitter.

CTUID Userid of the submitter.

CTPNODE Name of the node examining its IBM Connect:Direct statisticsfile.

CTSNODE Name of the other node.

CTNODE This node is P(node) or S(node).

CTFROM Direction of data: Snode to Pnode or Pnode to Snode

CTTRANS File translation. Includes: ASCII-TO-EBCDIC; EBCDIC-TO-ASCII; EBCDIC-TO-ASCII DIF; compressed; and compacted.

CTTRANS2 Transmission options. Includes: PDS-to-PDS copy; errororiginated on other node; sending PDS member to sequentialDSN; sending DSN sequential DSN to PDS member; and COPYis restarted.

CTRUSZ Request/response unit (RU) size.

CTPACCT# Displacement to Pnode account data length.

CTSACCT# Displacement to Snode account data length.

CTINBYTE Number of bytes read from data set.

CTINRECN Number of records read from data set.

CTINBLK Number of blocks read from data set.

Chapter 6. Facilities Guide 705

Field Names Field Description

CTSBYTES Number of bytes sent.

CTOBYTE Number of bytes written to data set.

CTOTRECN Number of records written to data set.

CTOTBLK Number of blocks written to data set.

CTRBYTES Number of bytes received.

CTNOKB Number of kilobytes sent.

CTNOMEMS Number of members sent.

CTNOALIS Number of aliases sent.

CTNOMEMX Number of members selected but not sent.

CTNOALIX Number of aliases selected but not sent.

CTNOMEMR Number of members received.

CTNOALIR Number of aliases received.

CTCMPTBL The compaction table name.

CTSDSTYP Source data set type: ESDS, KSDS, RRDS, PDS, SAM, or LIB.

CTSDISP1 Source data set disposition status: O=OLD and S=SHR.

CTSDISP2 Source data set disposition normal termination: D=DELETEand K=KEEP.

CTSDISP3 Source data set disposition abnormal termination: D=DELETEand K=KEEP.

CTSDSNL Length of the source data set name.

CTSDSN Source data set name.

CTTYPE Type file key, if Type is specified in a Process step.

CTDDSTYP Destination data set type.

CTDDISP1 Destination data set disposition status: M=MOD; N=NEW;O=OLD; and S=SHR.

CTDDISP2 Destination data set disposition normal termination: C=CATLGand K=KEEP.

CTDDISP3 Destination data set disposition abnormal termination:C=CATLG; K=KEEP; and D=DELETE.

CTDDSNL Length of destination data set name.

CTDDSN Destination data set name.

CTMEMBER Member name for PS to PO copies.

CTOMSGID Message ID from other node.

CTRTNCD Return code from other node.

CTNVTAMS Number of VTAM sends.

CTNVTAMR Number of VTAM receives.

CTDSPVLR Displacement of receiving VOLSER list.

706 IBM Connect:Direct for z/OS: Documentation

Field Names Field Description

CTDSPVLS Displacement of sending VOLSER list

CTTBOFS TCP buffer size used.

CTV2BUFS V2 buffer size.

CTNEGBF Negotiated V2 buffer size.

CTSUBJOB Submitter's jobname

CTSUBJID Submitter's jobid

CTECP0S CPU time spent running on a CP

CTECP1S CPU time spent running on a zIIP

CTECP2S zIIP qualified amount of CTECP0S

CTECP0R CPU time spent running on a CP

CTECP1R CPU time spent running on a zIIP

CTECP2R zIIP qualified amount of CTECP0R

CTZFBA2 Reserved

CTZFBA1 zFBA Device Range

CTZLIBVS ZLIB Version (Send) blanks=1.2.3

CTZLIBVR ZLIB Version (Recv) blanks=1.2.3

CTSTEPOS Step offset in TCQ

CTSMFID SMF ID that created this record

CTCLASS Process Session Class

CTGPFLAG CTGPFLAG

CTSDCB Source DSN DCB Attributes

CTSLRECL SRC LRECL

CTSBLKSZ SRC BLKSIZE

CTSRECFM SEC RECFM

CTSDSORG SRC DSORG

CTDDCB Destination DSN DCB Attributes

CTDLRECL Destination LRECL

CTDBLKSZ Destination BLKSIZE

CTDRECFM Destination RECFM

CTDDSORG Destination DSORG

CTFASPPL fasp.policy

CTFASPBW fasp.bandwidth (bits, 1K= 1000 bits)

CTFASPFT fasp.filesize.threshold (bytes/1024bytes)

CTFLAG17 CTFLAG17

CTFLAG18 CTFLAG18

Chapter 6. Facilities Guide 707

Field Names Field Description

CTXTIME Process Stop Time

CTXDATE Process Stop Date

CTPNRLS Pnode C:D Version

CTSNRLS Snode C:D Version

CTDDTTYP Copy destination DATAYPE FLAG:

• CTDDATB- DESTINATION DATATYPE=BINARY• CTDDATT- DESTINATION DATATYPE=TEXT• CTDDATV- DESTINATION DATATYPE=VB

CTSDTTYP Copy Source DATAYPE FLAG:

• CTSDATB- SOURCE DATATYPE=BINARY• CTSDATT- SOURCE DATATYPE=TEXT• CTSDATV- SOURCE DATATYPE=VB

CTDXLATE DESTINATION XLATE FLAG:

• CTDXLTY- DESTINATION XLATE=YES• CTDXLTN- DESTINATION XLATE=NO

CTSXLATE SOURCE XLATE FLAG:

• CTSXLTY- SOURCE XLATE=YES• CTSXLTN- SOURCE XLATE=NO

CTDSBLNK DESTINATION STRIP.BLANKS FLAG:

• CTDSBKY- DESTINATION STRIP.BLANKS=YES• CTDSBKN- DESTINATION STRIP.BLANKS=NO• CTDSBKI- DESTINATION STRIP.BLANKS=I

CTSSBLNK DESTINATION STRIP.BLANKS FLAG:

• CTSSBKY- SOURCE STRIP.BLANKS=YES• CTSSBKN- SOURCE STRIP.BLANKS=NO• CTSSBKI- SOURCE STRIP.BLANKS=I

Delete Process Termination RecordThe following table shows fields available in the Delete Process Termination record. The DGAADPTRmember of the $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

DPRECLN Length of this record.

DPRTYPE Record type—DP indicates the Delete Process Termination record.

DPTIME Time that DELete PROCess command completed in hh/mm/ss/tt format.

DPDATE Date that DELete PROCess command completed in Julian date format(yyyydddf).

DPPROCNM Process name.

708 IBM Connect:Direct for z/OS: Documentation

Field Names Field Description

DPPROCNO Process number.

DPSTEP Step name or label.

DPUNODE User node iD of the submitter.

DPUID Userid of the submitter.

DPSTIME Time that DELete PROCess command started in hh/mm/ss/tt format.

DPSDATE Date that DELete PROCess command started in Julian format (yyyydddf).

DPSCC Step completion code. Displays normal completion code.

DPMSGID Message ID.

DPDPRNM Name of the deleted Process.

DPDPRNOP Number of the deleted Process.

DPRMNID Route message node of deleted Process.

DPRMUID Route message userid of deleted Process.

Display Statistics RecordThe following table contains each field available in the Display Statistics record. The DGAADTR member ofthe $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Name Field Description

DTRECLN Length of this record.

DTRTYPE Record type indicates specific data in statistics record: SP=SELect PROCess; DT=SELectTASK; FT=FLUSH TASK; SS=SELect STATistics; and SN=SELect NETMAP.

DTTIME Time that command completed in hh/mm/ss/tt format.

DTDATE Date that command completed in Julian date format (yyyydddf).

DTPROCNM Process name.

DTPROCNO Process number.

DTSTEP Step name or label.

DTUNODE User node ID of the submitter.

DTUID Userid of the submitter.

DTSTIME Time that command started in hh/mm/ss/tt format.

DTSDATE Date that command started in Julian date format (yyyydddf).

DTSCC Step completion code. Displays normal completion code.

DTMSGID Message ID.

DTDFLNM Name of the displayed data set.

DTNVTAMS Number of VTAM sends.

DTNVTAMR Number of VTAM receives.

DTGETS Number of GETS.

DTPUTS Number of PUTS.

Chapter 6. Facilities Guide 709

Flush/Suspend Process Termination RecordThe following table shows each field in the Flush Process/Suspend Process Termination record. TheDGAAFPTR member of the $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

FPRECLN Length of this record.

FPRTYPE Record type–FP indicates the Flush Process Termination record.

FPTIME Time that FLUSH PROCess command completed in hh/mm/ss/tt format.

FPDATE Date that FLUSH PROCess command completed in Julian date format (yyyydddf).

FPPROCNM Process name.

FPPROCNO Process number.

FPSTEP Step name or label.

FPUNODE User node ID of the submitter.

FPUID Userid of the submitter.

FPSTIME Time that FLUSH PROCess command started in hh/mm/ss/tt format.

FPSDATE Date that FLUSH PROCess command started in Julian date format (yyyydddf).

FPSCC Step completion code. Displays normal completion code.

FPMSGID Message ID.

FPDPRNM Name of the flushed Process.

FPDPRNOP Number of the flushed Process.

FPRMNID Route message node of flushed Process.

FPRMUID Route message userid of flushed Process.

PDS Member Copy RecordThe following table shows each field available in the PDS Member Copy record. The DGAAFMCR memberof the $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

MCRECLN Length of this record.

MCRTYPE Record type–MC indicates the PDS Member Copy record.

MCTIME Time that COPY step completed in hh/mm/ss/tt format.

MCDATE Date that COPY step completed in Julian date format (yyyydddf).

MCSTIME Time that member processing started in hh/mm/ss/tt format.

MCSDATE Date that member processing started in Julian date format (yyyydddf).

MCSCC Step completion code. Displays normal completion code.

MCMSGID Message ID.

MCPROCNM Process name.

MCPROCNO Process number.

MCSTEP Step name or label.

710 IBM Connect:Direct for z/OS: Documentation

Field Names Field Description

MCUNODE User node ID of the submitter.

MCUID Userid of the submitter.

MCPNODE The Pnode name for this Process.

MCSNODE The Snode name for this Process.

MCNODE This node is P(node) or S(node).

MCFROM Direction of data: P(node) to Snode or S(node) to Pnode.

MCTNAME Name of member on destination PDS.

MCFNAME Name of member on source PDS (if different).

MCANAME Name of member for which node is an alias.

MCNRECS The number of records.

MCNBLKS The number of blocks.

Process Submit Statistics RecordThe following table describes fields in the Process Submit Statistics record. The DGAAPPSR member ofthe $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

PSSRECLN Length of this record.

PSSRTYPE Record type indicates specific data in statistics record: PS=SUBmitstatement and SW=SUBmit command within a Process.

PSSCTIME Time that Process completed in hh/mm/ss/tt format.

PSSCDATE Date that Process completed in Julian date format (yyyydddf).

PSSSTIME Time that Process started in hh/mm/ss/tt format.

PSSSDATE Date that Process started in Julian date format (yyyydddf).

PSSSCC Step completion code. Displays normal completion code.

PSSMSGID Message ID.

PSSPRCNM Process name.

PSSPRCNO Process number.

PSSSTEP Step name or label.

PSSUNODE Submitter's symbolic node name.

PSSUID Userid of the submitter.

PSSPNODE Pnode name for this Process.

PSSSNODE Snode name for this Process.

PSSNODE This node is P(node) or S(node).

PSSFROM Direction of data: P(node) to Snode or S(node) to Pnode.

PSSROSIZ The number of bytes in the Process.

PSSRMNID Route message userid of Process.

Chapter 6. Facilities Guide 711

Field Names Field Description

PSSFUNCD The function code for the SUBMIT.

PSSSYNTX The syntax error in SUBmit command.

PSSPARSE The parse error in SUBmit command.

PSSPACT# Displacement to Pnode account data.

PSSSACT# Displacement to Snode account data.

PSSDSN# Displacement to data set name.

PSSUBJOB Submitter's jobname

PSSUBJID Submitter's jobid

Process Termination RecordThe following table describes fields in the Process Termination record. The DGAAPTR member of the$CD.SDGAMAP library contains the SAS maps of the IBM Connect:Direct statistics record.

Field Names Field Description

PTRECLN Length of this record.

PTRTYPE Record type–PT indicates the Process Termination record.

PTTIME Time that Process completed in hh/mm/ss/tt format.

PTDATE Date that Process completed in Julian date format (yyyydddf).

PTSTIME Time that Process started in hh/mm/ss/tt format.

PTSDATE Date that Process started in Julian date format (yyyydddf)

PTSCC Step completion code. Displays normal completion code.

PTMSGID Message ID.

PTPROCNM Process name.

PTPROCNO Process number.

PTSTEP Step name or label.

PTUNODE Submitter's symbolic node name.

PTUID Userid of the submitter.

PTPNODE Pnode name for this Process.

PTSNODE Snode name for this Process.

PTNODE This node is P(node) or S(node).

PTFROM Direction of data: P(node) to Snode or S(node) to Pnode.

PTUNPRNO Process number unique to submitter's node.

PTRMNID Route message userid of Process.

PTRMUID Userid where message is routed.

PTSUBTME Time that Process was submitted in hh/mm/ss/tt format.

PTSUBDTE Date that Process submitted in Julian date format (yyyydddf).

PTSCHTME Time that Process was scheduled in hh/mm/ss/tt format.

712 IBM Connect:Direct for z/OS: Documentation

Field Names Field Description

PTSCHDTE Date that Process was scheduled in Julian date format (yyyydddf).

PTSCHDAY Day Process was scheduled.

PTSTMTN Number of statements.

PTPRTY Process selection priority.

PTSUBJOB Submitter's jobname

PTSUBJID Submitter's jobid

Run Job Termination RecordThe following table describes fields in the Run Job Termination record. The DGAARJTR member of the$CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

RJCLASS Session class.

RJRECLN Length of this record.

RJRTYPE Record type–RJ indicates the Run Job Termination record.

RJTIME Time that RUN JOB step completed in hh/mm/ss/tt format.

RJDATE Date that RUN JOB step completed in Julian date format (yyyydddf).

RJSTIME Time that RUN JOB step started in hh/mm/ss/tt format.

RJSDATE Date that RUN JOB step started in Julian date format (yyyydddf).

RJSCC Step completion code. Displays normal completion code.

RJMSGID Message ID.

RJPROCNM Process name.

RJPROCNO Process number.

RJSTEP Step name or label.

RJUNODE Submitter's symbolic node name.

RJUID Userid of the submitter.

RJPNODE Pnode name for this Process.

RJSNODE Snode name for this Process.

RJNODE This node is P(node) or S(node).

RJFROM Direction of data: P(node) to Snode or S(node) to Pnode.

RJJOBNM Job name.

RJJOBNO Job number.

RJSYRCD System return code.

RJDDSN Displacement to data set name.

RJPACCT# Displacement to Pnode account data.

RJSACCT# Displacement to Snode account data.

RJSUBJOB Submitter's jobname

Chapter 6. Facilities Guide 713

Field Names Field Description

RJSUBJID Submitter's jobid

Run Task Termination RecordThe following table shows each field in the Run Task Termination record. The DGAARTTR member of the$CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

RTRECLN Length of this record.

RTRTYPE Record type–RT indicates the Run Task Termination record.

RTTIME Time that RUN TASK step completed in hh/mm/ss/tt format.

RTDATE Date that RUN TASK step completed in Julian date format (yyyydddf).

RTSTIME Time that RUN TASK step started in hh/mm/ss/tt format.

RTSDATE Date that RUN TASK step started in Julian date format (yyyydddf).

RTSCC Step completion code. Displays normal completion code.

RTMSGID Message ID.

RTPROCNM Process name.

RTPROCNO Process number.

RTSTEP Step name or label.

RTUNODE Submitter's symbolic node name.

RTUID Userid of the submitter.

RTPNODE Pnode name for this Process.

RTSNODE Snode name for this Process.

RTNODE This node is P(node) or S(node).

RTFROM Direction of data: P(node) to Snode or S(node) to Pnode.

RTMODNM Name of the RUN TASK program.

RTSYSRTN System return code.

RTPARMLN Length of the parameter list.

RTPACCT# Displacement to Pnode account data.

RTSACCT# Displacement to Snode account data.

RTSUBJOB Submitter's jobname

RTSUBJID Submitter's jobid

RTCLASS Session class

Signon/Signoff Statistics RecordThe following table shows each field in the Signon/Signoff Statistics record. The DGAASFR member of the$CD.SDGAMAP library contains the SAS maps of the statistics record.

714 IBM Connect:Direct for z/OS: Documentation

Field Names Field Description

SIRECLN Length of this record.

SIRTYPE Record type indicates specific data in the statistics record: SI=SIGNON commandand SO=SIGNOFF command.

SITIME Time that SIGNON/SIGNOFF command completed in hh/mm/ss/tt format.

SIDATE Date that SIGNON/SIGNOFF command completed in Julian date format (yyyydddf).

SIUNODE User symbolic node ID.

SIUID Userid of the submitter.

SISCC Step completion code. Displays normal completion code.

SIMSGID Message ID.

Start IBM Connect:Direct Command RecordThe following table shows each field available in the Start IBM Connect:Direct Command record. TheDGAASDCR member of the $CD.SDGAMAP library contains the SAS maps of the IBM Connect:Directstatistics record.

Field Names Field Description

SDRECLN Length of this record.

SDRTYPE Record type–SD indicates the Start IBM Connect:Direct Command record.

SDTIME Time that Start IBM Connect:Direct command completed in hh/mm/ss/tt format.

SDDATE Date that Start IBM Connect:Direct command completed in Julian date format(yyyydddf).

SDPROCNM Process name.

SDPROCNO Process number.

SDSTEP Step name or label.

SDUNODE Submitter's symbolic node name.

SDUID Userid of the submitter.

SDSTIME Time that Start IBM Connect:Direct command was issued in hh/mm/ss/tt format.

SDSDATE Date the Start IBM Connect:Direct command was issued in Julian date format(yyyydddf).

SDSCC Step completion code. Displays normal completion code.

SDMSGID Message ID.

Stop IBM Connect:Direct Statistics RecordThe following table shows each field available in the Stop Statistics record. The DGAASTDC member ofthe $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

TDRECLN Length of this record.

TDRTYPE Record type–ST indicates the Stop IBM Connect:Direct Statistics record.

TDTIME Time that STOP IBM Connect:Direct command completed in hh/mm/ss/tt format.

Chapter 6. Facilities Guide 715

Field Names Field Description

TDDATE Date that STOP IBM Connect:Direct command completed in Julian date format(yyyydddf).

TDPROCNM Process name.

TDPROCNO Process number.

TDSTEP Step name or label.

TDUNODE User node of the submitter.

TDUID Userid of the submitter.

TDSTIME Time that STOP IBM Connect:Direct command was issued in hh/mm/ss/tt format.

TDSDATE Date that STOP IBM Connect:Direct command was issued in Julian date format(yyyydddf).

TDSCC Step completion code. Displays normal completion code.

TDSTOP IBM Connect:Direct shutdown types: W=Step shutdown; X=Immediate shutdown;Y=Quiescent shutdown; and Z=Forced shutdown by an abend.

TDMSGID Message ID.

Write to Operator (WTO) Statistics RecordThe following table shows each field available in the WTO Statistics record. The DGAAWTOS member ofthe $CD.SDGAMAP library contains the SAS maps of the statistics record.

Field Names Field Description

WTRECLN Length of this record.

WTRTYPE Record type–WT indicates the WTO Statistics record.

WTCTIME Time that Process completed in hh/mm/ss/tt format.

WTCDATE Date that Process completed in Julian date format (yyyydddf).

WTSTIME Time that function started in hh/mm/ss/tt format.

WTSDATE Date that function started in Julian date format (yyyydddf).

WTSCC Step completion code. Displays normal completion code.

WTMSGID Message ID.

WTPROCNM Process name.

WTPROCNO Process number.

WTSTEP Step name or label.

WTUNODE Submitter's symbolic node name.

WTUID Userid of the submitter.

WTPNODE The Pnode name for this Process.

WTSNODE The Snode name for this Process.

WTNODE This node is P(node) or S(node).

WTFROM Direction of data: P(node) to Snode or S(node) to Pnode.

WTTASKNO Task number that issued the WTO.

716 IBM Connect:Direct for z/OS: Documentation

The Operator InterfaceThe Operator Interface enables you to issue Connect:Direct for z/OS commands from a z/OS consoleusing a MODIFY command.

Access the Operator Interface after IBM Connect:Direct initializes if you specify the initializationparameters MCS.CLIST and MCS.SIGNON.

Following is the syntax for the MCS.CLIST and MCS.SIGNON initialization parameters:

MCS.CLIST=console operator's CLIST library (dsn)MCS.SIGNON=(SIGNON USERID=(userid,password))

An automatic signon is issued after the first IBM Connect:Direct CLIST is invoked using the informationin MCS.SIGNON. This session is active until you submit a CLIST that contains a IBM Connect:DirectSIGNOFF command.

You can create easy to remember customized IBM Connect:Direct commands with the Operator Interfacethrough a CLIST-type facility. The software supports symbolic substitution and CLIST-type parametersallowing you to alter IBM Connect:Direct commands without changing the CLIST.

In a IBM Connect:Direct/Plex, if you issue a console operator command to a IBM Connect:Direct/Server,the console interface actually signs on to the IBM Connect:Direct/Manager. As a result, any commandsissued to IBM Connect:Direct/Server are actually issued to the IBM Connect:Direct/Manager, which is theonly IBM Connect:Direct/Plex member that accepts operator commands.

Concatenation of Operator CLISTCurrently, the OPLIST can only be defined in the initialization parameter, MCS.CLIST. This does not allowthe user to concatenate their own OPLIST.

The current syntax for the initialization parameter (initparm) is

MCS.CLIST = oplist_dsn

The MCS.CLIST and MCS.SIGNON syntax remains unchanged. However, if the startup JCL contains theDD statement DGAOPLS, IBM Connect:Direct builds and saves the dsn list from the JCL instead of usingthe MCS.CLIST parameter. The JCL statement provides an override of the initialization parameter.

//DGAOPLS DD DSN=oplist_dsn_1//DD DSN=oplist_dsn_2//DD DSN=oplist_dsn_n

Note: If the IBM Connect:Direct Server initialization finds the DGAOPLS DD allocated, the MCS.CLISTinitialization parameter is ignored. However, the MCS.SIGNON initialization parameter is still required.

Sample Connect:Direct for z/OS CLISTsThe IBM Connect:Direct sample CLIST library, SDGAOPLS, contains the sample CLISTs included in thefollowing table. Use these CLISTs to build customized IBM Connect:Direct commands with symbolicparameters that allow you to customize the CLIST at submission time. Sample operator commands foreach CLIST are listed in the comment section.

CLIST Name Command Description

DGAOCEV SECURE CERTCK Execute the Secure Certck. Performs the CertificateExpiration validation.

DGAOCRF SECURE REFRESH Execute the Secure refresh. Refreshes the SecurePlusSSL/TLS environment.

Chapter 6. Facilities Guide 717

CLIST Name Command Description

DGAOCMD CMD Provides a general format for issuing a IBM Connect:Directcommand.

DGAODP DELETE PROCESS Shows six ways to delete a Process using this CLIST.

DGAODUMP STOP CD (Force) Stops IBM Connect:Direct using the FORCE parameter andproduces abnormal ending (abend) 4095 and a dump.

DGAOIPRM DISPLAY INITPARMS Displays initialization parameters to the operator console.In a PLEX environment, it works as follows:

• Displays the global initialization parameters• Defaults to the manager's local initialization parameters• Allows the name of a server to display the server's global

and local initialization parameters

DGAOMSG SELECT MSG Shows a detail of the IBM Connect:Direct messagerequested.

DGAONM SELECT NETMAP Displays entire NETMAP or it allows for one parameter – anode name.

DGAORLSE CHANGE PROCESS Shows three ways to release a Process.

DGAOSOFF SIGNOFF Signs the operator off IBM Connect:Direct.

DGAOSON SIGNON Connects the operator to IBM Connect:Direct.

DGAOSP SELECT PROCESS Shows six ways to display Process status information.

DGAOSS SELECT STATISTICS Shows seven ways to select statistics for display.

DGAOSTAT SELECT STATISTICS Shows three ways to select statistics for display covering aspecific time period.

DGAOSTOP STOP CD Stops IBM Connect:Direct using the STOP IMMEDIATEcommand. To perform an immediate shutdown in a PLEXenvironment from the operator console, issue the followingcommand: F CD,STOP | CDPLEX. To stop a specific server,use this command: F CD,STOP | WHERE(SERVER=name)

DGAOSUB SUBMIT PROCESS Shows two ways to submit a Process.

DGAOSUSP SUSPEND PROCESS Shows four ways to suspend a Process.

DGAOSWAP SWAP NODE Swaps operator to another node in a multiple sessionenvironment.

DGAOTS SELECT TASK Shows active tasks.

DGAOVP VIEW PROCESS Displays a specific Process.

Rules for Setting Up Connect:Direct for z/OS CLISTsThe following rules apply when setting up an operator CLIST:

• All operator CLISTs must have a PROC record as the first record in the CLIST. The PROC record definesthe parameters and keywords that are passed to the CLIST.

• You can stack multiple IBM Connect:Direct commands in one CLIST, but you only need one PROCstatement.

• A number between 0 and 24 (inclusive) must follow the PROC identifier. This number indicates thenumber of positional parameters used by the CLIST.

718 IBM Connect:Direct for z/OS: Documentation

• Parameter names (one to eight characters each) that correspond to each positional parameter followthe number. If no positional parameters exist, specify PROC 0.

• If you define more than one positional parameter on the PROC statement, you do not need to specifytrailing positional parameters in the command unless you also specify a keyword parameter.

• Use commas to indicate null values.• A positional parameter is terminated by the first blank encountered.• You can specify optional keyword parameters after the positional parameters. Enclose default values in

parentheses after each keyword name.• Use a hyphen (-) to indicate that a IBM Connect:Direct command continues on the next line. An example

follows.

PROC 1 PNUM SELECT PROCESS WHERE( - PNUM=&PNUM)

• You can use comments in the CLIST only if you include an asterisk (*) in the first column.• Sequence numbers are not allowed.

Connect:Direct for z/OS CommandsSubmit the IBM Connect:Direct commands to the Operator Interface using the MODIFY commandinterface. This operator command lets you submit a CLIST containing IBM Connect:Direct commands,and modify the IBM Connect:Direct commands by substituting symbolic parameters with real values.

The command format is:

F jobname,clist [options]

Following is a description of the parameters:

Parameter Description

F The short form of the Administrator MODIFY command.

jobname The name on the job statement of the job stream that brings up the DTF.

Caution: If jobname is a IBM Connect:Direct/Server, the command is redirected to theIBM Connect:Direct/Manager.

clist The name of the CLIST containing the IBM Connect:Direct command.

options Optional positional and keyword parameters to be passed to the CLIST.

CLIST ExamplesThe following are CLIST examples and operator commands that submit the CLIST examples. As someexamples show, you can use symbolic parameters to modify the IBM Connect:Direct command at thetime of submission. For example purposes, CDDTF is the jobname.

CLIST with Command and No ParametersThe following CLIST SELX command contains one command and no parameters:

PROC 0 SEL PROC WHERE(QUEUE=EXEC)

To execute SELX, type the following operator command.

Chapter 6. Facilities Guide 719

F CDDTF,SELX

When you issue the operator command, a Select Process command for Processes on the executing queueinitiates. As a result, a list of these Processes is displayed.

CLIST with Command and One ParameterIn this example, the CLIST SELQ contains one command and one positional parameter (SUBD).

PROC 1 SUBD SEL PROC WHERE(QUEUE=&SUBD)

The following options present two ways to submit SELQ:

• When you issue the following command, TIMER (timer queue) is substituted for &SUBD. This commanddisplays all Processes on the timer queue.

F CDDTF,SELQ TIMER

• When you issue the following command, ALL is substituted for &SUBD in the CLIST SELQ. This commanddisplays all Processes on all queues.

F CDDTF,SELQ ALL

CLIST with Command and Multiple ParametersIn this example, the CLIST SUB contains one command, two positional parameters (PROC and PARMS),and one keyword parameter (SNODE).

PROC 2 PROC PARMS SNODE(OTHER.NODE) SUB PROC=&PROC SNODE=&SNODE &PARMS

The following options present four ways to execute SUB:

• When you issue the following command, PAYROLL is substituted for &PROC. This substitution causesthe Process PAYROLL to be submitted.

F CDDTF,SUB PAYROLL

• Because no SNODE is specified, the SNODE defaults to OTHER.NODE.• When you issue the following command, CHECKS is substituted for &PROC and HOLD=YES is

substituted for &PARMS. These cause the Process CHECKS to be submitted as a held Process.

F CDDTF,SUB CHECKS HOLD=YES

Because no SNODE is specified, the SNODE defaults to OTHER.NODE.• When you issue this command, ORDERS is substituted for &PROC and CD.CHICAGO is substituted for

&SNODE. These cause the Process ORDERS to be submitted to run in session with the secondary nodecalled CD.CHICAGO.

F CDDTF,SUB ORDERS,,SNODE=(CD.CHICAGO)

Because PROC and PARMS are positional parameters, commas are required.

720 IBM Connect:Direct for z/OS: Documentation

• When you issue the following command, CONFIRM is substituted for &PROC andHOLD=NO,STARTT=(FRIDAY,NOON) is substituted for &PARMS. These submit the Process CONFIRMso that it runs at noon on Friday.

F CDDTF,SUB CONFIRM HOLD=NO,STARTT=(FRIDAY,NOON)

The SNODE defaults to OTHER.NODE because no SNODE is specified.

CLIST with Command and %IF %ELSE %EIFIn this example, the CLIST NM contains 1 command and 1 positional parameter.

PROC 1 NODE %IF &NODE = , SEL NETMAP WHERE (NODE=*) %ELSE SEL NETMAP WHERE (NODE=&NODE) %EIF

If you enter no operands it displays the entire netmap. If you enter a node it displays that node only.

Operation MessagesIBM Connect:Direct operation diagnostic messages are formatted into multiple lines so that errors andexception conditions are easy to read. Operator messages are sent to:

• The route code given in the IBM Connect:Direct initialization parameters• The ddname NDMLOG, if it is allocated

The COPY termination message (SVTM052I) is displayed in four lines, as follows:• The first line shows the step label, the operation (COPY), the Process name and number, the associated

node name, and the session class.• The second line shows the FROM file name.• The third line shows the TO file name.• The fourth line shows the completion code and message ID. If the COPY does not complete

successfully, the first four positions of the last line contain the “####” flag.

When session errors occur, the error message is formatted into two lines, as follows:• The first line gives as much information as possible in the same format as the COPY termination

message (Process name and number, and associated node name).• The second line gives the text of the error message. The first four positions of the second line contain

the “****” flag.

The following example shows two IBM Connect:Direct operation error messages following a COPYtermination message.

SVTM052I STEP1 COPY PROCESS1( 126)PNODE=CD.NODE.A (002) FROM SYSA.SAM.DATA.SET TO SYSB.TEST.SAM.DATA.SET #### COMPLETED 00000010/SCPA010ISVTM045I PROCESS1( 126)PNODE=CD.NODE.A **** RPLERRCK:CD/CD SESSION FAILURESVTM050I PROCESS1( 126)PNODE=CD.NODE.A **** PROCESS INTERRUPTED:RECOVERY INITIATED

Chapter 6. Facilities Guide 721

Stopping IBM Connect:DirectTo stop Connect:Direct for z/OS, use the following command, which executes the STOP CLIST using theOperator Interface.

F jobname,STOP

Note: The default value for the STOP CLIST is Immediate or I.

Following is a description of the parameters:

Parameter Description

F The short form of the Administrator MODIFY command.

jobname The name on the job statement of the job stream that brings up the DTF.

Caution: If jobname is a IBM Connect:Direct/Server, the command is redirected to theIBM Connect:Direct/Manager.

clist The name of the CLIST containing the IBM Connect:Direct command.

options Optional positional and keyword parameters to be passed to the CLIST.

Stopping a IBM Connect:Direct/Plex Manager and All ServersTo stop a IBM Connect:Direct/Plex from the console, use the following command which executes theSTOP CLIST using the Operator Interface:

F jobname,STOP [Q|S|I|R|F,] CDPLEX [,RECOVER]

Stopping an Individual IBM Connect:Direct/Plex ServerTo stop a IBM Connect:Direct/Plex Server from the console, use the following command which executesthe STOP CLIST using the Operator Interface:

F jobname,STOP [Q|S|I|R|F,] WHERE(SERVER=name) [,RECOVER]

About Tape Mount MessagesConnect:Direct for z/OS supports the transmission of tape files. IBM Connect:Direct implements separateand distinct messages to control tape management, providing the greatest flexibility to operators inmanaging tape transfers.

Tape Pre-mount MessageThis optional message is issued prior to allocating a tape device. It tells you that IBM Connect:Directrequires a specific volume on a specific device type. With this message, you can:

• Control the number of tape units available to Connect:Direct for tape transfers.• Locate the volumes before the transfer occurs.

You are required to respond to this message when the required resources are available.

Tape Mount MessagesThese messages are also optional. The first message (WTO) is in the format of the z/OS mount message.The second message is issued as a WTOR to inform the operator to mount a specific volume on a specific

722 IBM Connect:Direct for z/OS: Documentation

device. The third message is issued only if TAPE.PREMOUNT=LIST. Message SVST00C is displayed listingall volume-serial numbers of the requested file. If you are unable to satisfy the specific request, you canreply CANCEL to cancel the request. This message is also used to drive the visual display devices attachedto 3480-type devices.

Note: If you use tape silos in your environment, search for Tapemount Exit. To prevent the IBMConnect:Direct environment from locking up due to an outstanding tape mount request, the IBMConnect:Direct tapemount exit provides an interface to StorageTek Tape Silo Software to query the silo todetermine that all VOLS required for a tape file are present.

Setting Up Connect:Direct for z/OS Tape Pre-mount Messages• To issue the IBM Connect:Direct tape pre-mount messages, specify TAPE.PREMOUNT=YES|LIST in the

IBM Connect:Direct initialization parameter file.

Setting Up Connect:Direct for z/OS Tape Mount Messages• Issue the IBM Connect:Direct tape mount messages in place of the z/OS mount message. The IBM

Connect:Direct mount messages consist of a z/OS-format mount message followed by a WTOR issuedto the descriptor and route codes specified by the DESC.TAPE and ROUTCDE.TAPE.

• You can suppress the IBM Connect:Direct message by specifying ROUTCDE.TAPE=(0) in theinitialization parameters. The defaults are DESC.TAPE=(2) ROUTCDE.TAPE=(5,11). If you suppress IBMConnect:Direct tape mount messages, the standard z/OS mount messages are issued with relatedserialization during mount processing.

• If you specify ROUTCDE.TAPE=(0), causing IBM Connect:Direct not to issue the mount messages, thenthe normal z/OS mount message is issued when the dataset is opened. The z/OS mount processingholds an ENQ on the SYSZTIOT resource. This ENQ causes all other IBM Connect:Direct Processes tohang at allocation, open, and deallocation until the tape is mounted.

• If you use the IBM Connect:Direct tape mount message, the tape already is on the tape drive at opentime and z/OS mount processing does not hold the SYSZTIOT resource.

Connect:Direct for z/OS Tape Pre-mount MessagesFollowing is the format of a IBM Connect:Direct tape pre-mount message.

SVST000B - C:D REQUIRES VOL=SCRTCH TYPE=TAPE 6250/1600BPI REPLY "GO" WHEN READY

To continue processing, reply GO to the message. While this message is outstanding, no unit is allocated.However, the session for this transfer request remains active.

Connect:Direct for z/OS Tape Mount MessagesFollowing is the format of a IBM Connect:Direct tape mount message issued during a specific taperequest.

Chapter 6. Facilities Guide 723

If no tape is available or if you want to end the copy, reply CANCEL to the tape mount message.

Tape Device AllocationAfter the GO reply to a pre-mount message, and following the pre-mount processing, IBM Connect:Directallocates a tape device using Defer mounting. If an allocation error occurs, and the allocation error codeis in the ALLOC.CODES parameter of the IBM Connect:Direct initialization parameters, IBM Connect:Directretries the operation.

When device allocation completes successfully, IBM Connect:Direct issues a z/OS-format Open mountmessage to allow tape management and visual display routines to process the request. The format of themessage follows.

IEC501A M,cuu,volser,sl,,jobn,dsn,pnum,pnam,step

Following the IEC501A message, IBM Connect:Direct issues a WTOR to allow you to mount the tape orcancel the request.

Terminating the Tape MountA COPY step within a Process requiring a tape to be mounted causes the tape mount message to display.You can terminate the COPY step with a CANCEL reply. Any other reply causes IBM Connect:Direct toreissue the mount message.

If you are using both the tape pre-mount message and the tape mount message, and want to cancelthe request, reply GO to the tape pre-mount (SVST000B) and CANCEL to the tape mount message(SVST000A). If you do not want to terminate the copy step, the mount message disappears when the tapeis mounted.

Verifying Volume RequestsFor standard label tapes, Connect:Direct for z/OS verifies the volume serial number for a specific volumerequest. If you mount the wrong volume, the following message is issued and the volume is dismounted.

SVST001I - D cuu,volser --- IS NOT THE REQUESTED VOLUME

Mount the correct volume, or reply CANCEL to the reissued SVST000A mount message.

724 IBM Connect:Direct for z/OS: Documentation

Handling Multivolume FilesThe Connect:Direct for z/OS mount message is issued only for the first volume of a file, when amultivolume file is requested. Subsequent mount requests causes a SYSZTIOT enqueue during end-of-volume processing.

To keep IBM Connect:Direct from long waits while a second or subsequent volume is mounted, useUNIT=(unit,P) or UNIT=(unit,n) for the UNIT keyword of the COPY statement.

Connect:Direct for z/OS Messages on 3480 DisplayThe 3480 tape drive has an 8-character display. IBM Connect:Direct issues messages to this displayconcerning tape processing in the following manner:

• When a tape is to be dismounted, the first character position of the display contains a D. Positions 2–7consist of the tape’s volume serial number. Position eight contains an N if the tape is nonlabeled or an Sif the tape has standard labels.

• When a tape is to be mounted, the first character position of the display contains an M. Positions 2–7consist of the tape’s volume serial number. Position eight contains an N if the tape is nonlabeled or an Sif the tape has standard labels.

• When a tape is loaded, the first character position of the display is blank. Positions 2–7 consist of thetape’s volume serial number. Position eight contains an N if the tape is nonlabeled or an S if the tape hasstandard labels.

Event Services SupportIBM Connect:Direct Event Services Support (ESS) implements an asynchronous, event-generation facilityin IBM Connect:Direct. ESS is designed for use by external management and automated operationsapplications that require real-time notification of IBM Connect:Direct activities. ESS supports a publish orsubscribe protocol with optional guaranteed event delivery and automated recovery.

Customer applications register interest in receiving event data, and specify the types of event data theapplication receives through the new event services commands. ESS supports a user exit point and anoptional API for interface communication with user-written CICS automation applications.

ESS Concepts and ComponentsESS provides real-time delivery of IBM Connect:Direct event records to interested application interfaces.ESS is based on the existing IBM Connect:Direct statistics facility and is designed to:

• Minimize the server-performance overhead for ESS processing• Prevent adverse impact on IBM Connect:Direct server reliability

ESS is a low-level IBM Connect:Direct server technology that enables you to layer multiple APIs. Anend-user application interfaces with the API rather than the low-level ESS core technology. This designenables future extension of ESS to support multiple application interface protocols and publishing of thesame event data to several event consumer applications.

System InterfacesESS supports the event services exit and the CICS API interface.

An application can access event data through an ESS exit. A sample event exit (DGAXEV01) is in thesample library, and writes the event data to a predefined data set.

A CICS API initiates event processing by signing on to IBM Connect:Direct through the current CICS APIand issuing ESS commands. The CICS API provided with IBM Connect:Direct writes event data to a CICSTransient Data Queue (TDQ). A sample program, DGAQ249, shows how to read an event record from theTDQ.

Chapter 6. Facilities Guide 725

System AdvantagesBuilding on the existing statistics facility has the following advantages:

• Event Definition

Because ESS event records are IBM Connect:Direct statistics records, ESS does not restrict eventsto abnormal activities. This design enables ESS-enabled applications to initiate procedures based oneither successful or unsuccessful Process statements.

• Historical Data Recovery

The IBM Connect:Direct statistics file functions as the historical repository of ESS event data. ESSsupports optional automated recovery of past event data if an event consumer application fails. Uponrestart, ESS requests old event records from the statistics file.

The API automatically manages the restart point for an ESS-enabled application. This API tracksthe last successfully delivered event record to a designated subscriber. Upon restart, the APIresynchronizes event processing by issuing a SELect STATistics command to retrieve the historical eventdata and deliver it to the restarted event consumer.

• Event Record Types

The event record types give external applications greater visibility into IBM Connect:Direct activities andimprove the reliability and responsiveness of interface applications in a production environment. ESSsupports several IBM Connect:Direct event record types, including:

– Process Initialization (PI) occurs immediately prior to the execution of the first Process statement in aProcess.

– Step Start (CI, JI, TI) events occur immediately prior to the execution of a COPY, RUN JOB, or RUNTASK statement.

– COPY Step I/O Start (CE) occurs just before the first COPY step I/O in a Process.– Queue Change (QW, QH, QE, QT) events occur whenever a Process moves from one logical queue

to another in the TCQ. The sample initialization parameters provided in the base IBM Connect:Directinstall the $CD.SDGAPARM data set and specify STAT.EXCLUDE=(QE, QH, QT, QW). This specificationprevents IBM Connect:Direct from producing the queue change records. If you want queue changerecords, you must set this parameter appropriately.

ESS also supports basic event filtering. When an event consumer application registers interest in receivingevents, the application can restrict the types of event data that it wants to receive. These options supportthe same filtering syntax as the SELect STATistics command. Following are two possible selections:

• A fault management application can request notification of COPY requests that did not completenormally, QH (Queue Hold) events or both. When such an event occurs, the fault managementapplication can then poll IBM Connect:Direct through SELect STATistics or SELect PROCess toinvestigate the problem further.

• An application registers interest in all events for a small group of mission-critical Processes.

Event Services Support ArchitectureESS uses three components to provide real-time information about IBM Connect:Direct activities:

• Client application• API• IBM Connect:Direct server

ESS communicates with client application interfaces through the CICS API or an ESS user exit.

The components interact to accomplish the following tasks:

• Define which events are reported to the client application• Turn event services requests on and off• Register event data

726 IBM Connect:Direct for z/OS: Documentation

• Report event data

The following diagram details ESS with a CICS application using the IBM Connect:Direct CICS API. Thestructure consists of the following components:

The client application defines the event data requests and issues commands through a user-writtenprogram. The DGAE transaction ID causes DGAQ247 to be driven. This sample program demonstrates themethod to issue ESS commands.

• The API receives and passes event data and ESS commands to the IBM Connect:Direct server, andmaintains information for the guaranteed delivery feature.

• The IBM Connect:Direct server is the Data Transmission Facility (DTF) that processes ESS commandsand sends the requested event data to the client application through the API.

Chapter 6. Facilities Guide 727

ESS Data Flow Using CICS APIDefine the event services environment by specifying the types of event data your application receives.These definitions are the event data requests that you issue through the DGAQ247 program or a user-written program.

After you define the event data requests for the client application and activate the request by issuing theEVENT SERVICES START command, ESS processes the event data as follows:

• Upon receiving the EVENT SERVICES START ID parameter, the API (DGAQ012) passes the command tothe DTF through a VTAM session.

When a requested event occurs, the DTF sends the event data to the API for distribution to the TransientData Queue (TDQ).

• The event data is then available to the client application through the DGAQ249 Sample Program. TheDGAQ249 program provides a way to read event data from the TDQ and processes the data for use byyour application.

The following diagram illustrates the flow of event data from the DTF to the client application:

728 IBM Connect:Direct for z/OS: Documentation

Deciding What Event Data to CollectDeciding what event data to collect requires that you understand the types of data the ESS deliversand how you can use this data in your event consumer application. Although it is technically possible torequest all event data for all Processes in the system, it is usually unnecessary and impractical to do so.Typically, an event consumer application is interested in a subset of event data.

Note: Statistics records excluded through the API STAT command or a DTF statistics exit, or by coding theDTF STAT.EXCLUDE initialization parameter, are not available to ESS.

Following are commonly requested event data:

• All event data for a Process or group of Processes

Requesting all event data provides the most detailed trace of Process execution. This information isuseful when testing an event consumer application. However, it is unnecessary after an application goesinto production.

• Major event data for a Process or group of Processes

This request is the most common subset specification. For normal production work, this request gives asufficient trace of Process execution, and minimizes overhead for ESS processing and event records byyour application.

• Subset of event data for a particular Process, set of Processes, or all Processes

For example, an application executes a procedure when a IBM Connect:Direct Process terminates. Inthis case, it may be sufficient to register interest in PT (Process Termination) records only. As a secondexample, a fault reporting application needs CT (Copy Termination) statements that did not completenormally (signalling the failure of a IBM Connect:Direct file transfer request).

ESS Event Record ExamplesThe following examples show the ESS event records from a single Copy Process. The examples show therecords produced from Process submittal until normal Process termination. The examples assume thatno IBM Connect:Direct commands affecting the Process [including the SELect PROCess command] areissued between Process submittal and termination.

Chapter 6. Facilities Guide 729

ESS Event Records Example 1 (No Retries)

In this example, the Process does not undergo a Process retry for any reason. The sequence of ESS eventrecords produced by this Process are listed in the following table:

Record Type Record Description

PS Process submit

QE Process moved to EXEC queue

PI Process initiation

CI COPY step statement start

CE COPY step I/O start

CT COPY termination

NL Last statement (null step 1)

PT Process termination

ESS Event Records Example 2 (One Retry)

This example shows the sequence of ESS records that are produced if the same Process undergoesa single Process retry. IBM Connect:Direct commands are deliberately issued to suspend the Processand then release it for retry. As a result, the following record sequence includes the various operatorcommands required. The events are in sequential order.

Record Type Record Description

PS Process submit

QE Process moved to EXEC queue

PI Process initiation

CI COPY step statement start

CE COPY step I/O start

FS Suspend Process command issued

CT COPY termination (as a result of requested SUSPEND)

QH Process moved to HOLD queue

CH Change Process command issued with RELEASE=Yes

QE Process moved to EXEC queue

PI Process initiation

CI COPY step start

CE COPY I/O start

CT COPY termination

NL Last statement in Process end

PT Process termination

730 IBM Connect:Direct for z/OS: Documentation

Using ESS with the CICS APIThe CICS API writes event data to the Transient Data Queue (TDQ). Your CICS application must include aprogram to read these event records from the TDQ and send them for processing..

To enable a CICS application for ESS:

Warning: Automated Connect:Direct CICS tasks that are repeated and issue a SIGNON without aSIGNOFF can consume memory and render the interface inactive.

1. Decide what event data the application requires.2. Verify that the Connect:Direct CICS API software is installed and working. Refer to the Connect:Direct

installation documentation for information.3. Create an ESS registration program. Include this program in the startup portion of your application. It

must be called whenever your application wants to initiate event record collection. This program mustperform the following:

• Sign on to the Connect:Direct CICS API.• Issue the EVENT SERVICES CREATE command to register interest in receiving event data and to

specify event record filter criteria.• Specify the ID parameter to identify a subscriber for your application. Specify the WHERE and

ORWHERE parameters for filtering criteria.

• Issue the EVENT SERVICES START command and specify the ID parameter to initiate eventreception.

4. Create a customer interface program to read event records from the CICS TDQ and send them forprocessing. The sample interface program (DGAQ249) demonstrates how to read an event record fromthe TDQ. The application must issue an EXEC CICS READQ TD QUEUE instruction.

5. Modify the application to process the ESS event records.6. Embed a call to the EVENT SERVICES STOP ID=subscriber_name parameter in the location to stop

collecting event data.

Using ESS with the ESS User ExitYou can execute Event Services commands through any existing IBM Connect:Direct API such as CICS,ISPF, and the batch interface. However, not all IBM Connect:Direct APIs can process synchronous eventdata received from an EVENT SERVICES START command. In some cases, it is preferable not to have theIBM Connect:Direct API process synchronous event data. The event services exit provides an alternative.Rather than passing synchronous event data back to the API that issued the EVENT SERVICES START(ESS) command, an exit processes the event data.

The ESS exit acts as an extension to the IBM Connect:Direct server. When a synchronous event occurs,IBM Connect:Direct calls the event services exit. An event exit control block is passed for each event andcontains the following:

• Address of the event record• Flags indicating first or last call• Fields for the user to indicate return code and message

DGA$EVCB, found in $CD.SDGAMAC, maps the event exit control block. The sample exit, DGAXEV01, isin $CD.SDGASAMP.

The event services exit is called as a subtask from IBM Connect:Direct so that the user code waiting forsystem services does not directly effect IBM Connect:Direct processing. The sample exit (DGAXEV01)writes each event record to a predefined data set. You must modify DGAXEV01 to specify the name ofyour event exit data set, and you must define the data set to accommodate records up to 2048 bytes inlength.

Chapter 6. Facilities Guide 731

Using the ESS ExitEach record passed to the exit consists of a record header and an event record. DGA$NHDR, in$CD.SDGAMAC, maps the record header. Other members in $CD.SDGAMAC map the event records. SeeEvent Services Record, to determine which member maps a particular event record.

The exit must reside in a load library accessible to the IBM Connect:Direct server (DTF). This exitaccommodates systems where I/O calls must be done below the line.

To use the ESS user exit:

1. Create an ESS exit program that can process the requested event records.2. Decide what event data your application requires.3. Verify that your software is correctly installed and working.4. Create an ESS registration program. Include this program in the startup portion of your application.

It is called whenever your application initiates event record collection. This program must accomplishthe following tasks:

• Signon to IBM Connect:Direct through the CICS API, the ISPF IUI, or the batch interface.• Issue the EVENT SERVICES CREATE command to register interest in receiving event data and

specify event record filter criteria.• Specify the EXIT parameter to identify the name of your exit program, and the ID parameter to

identify a subscriber name for your application. Specify the WHERE and ORWHERE parameters foryour filtering criteria. Refer to EVENT SERVICES CREATE Command Format for more informationabout event filter criteria.

• Issue the EVENT SERVICES START command and specify the ID parameter to initiate eventreception.

Embed a call to the EVENT SERVICES STOP ID=subscriber_name parameter in your application whereyou want to stop collecting event data. If the user application does not process records fast enough,the internal queue, which holds asynchronous events, becomes full. When the queue is full, eventprocessing for this request ends, and Connect:Direct writes a WTOR message. To customize theinternal queue size, specify the MAXQCNT parameter.

Issuing Event Services Commands

EVENT SERVICES CREATE Command FormatThe EVENT SERVICES CREATE command enables you to create a new request for event data and definewhich data is sent to your application. The EVENT SERVICES CREATE command uses the following formatand parameters:

Command Parameters

EVENT [SERVICES]CREATE

ID=event-request-name

WHERE (CCODE | PNAME | PNUMber | STARTT | STOPT | USER | SNODE | TYPE |FNAME | CASE | LASTSEQ | MAXQCNT | EXIT)

ORWHERE | =(CCODE | PNAME | PNUMber | USER | SNODE | TYPE | FNAME)

Required ParametersThe EVENT SERVICES CREATE command has two required parameters.

ID=event-request-namespecifies a logical name for the event services request. This name is a text string of 1–16 characters.You can use any printable characters. You cannot use embedded blanks.

WHERE (CCODE = (condition, completion code) | PNAME = name | (list)

732 IBM Connect:Direct for z/OS: Documentation

PNUMber = number | (list)STARTT = ([date | day] [,hh:mm:ssXM])STOPT = ([date | day] [,hh:mm:ssXM])USER = name | (list)SNODE = name | (list)TYPE = id | (list)FNAME = dsname | (list)CASE = YES | NOLASTSEQ=nMXQCNT=nEXIT=exitname)

specifies selection criteria for event records.

You must specify at least one WHERE () subparameter, such as CCODE, PNAME, PNUMBER, or TYPE.CCODE = (condition, completion code)

specifies selection by completion code.

condition specifies a relationship to the completion code given in the subsequent positionalparameter. The options for specifying condition are:

GT greater than LT less than EQ equal to NE not equal to GE greater than or equal to LE less thanor equal to

completion specifies a completion code value ranging from 1 to 2,147,483,647 so the RUN TASKcan pass all values.

For example, if you specify CCODE = (GT,0), you see event records in which the step completioncode is greater than zero, as long as the records also meet other specified criteria.

PNAME = name | (list)

specifies selection by Process name. Specify a list of Processes by enclosing them in parentheses.You can use a wild card character (*) at the end of the name.

For example, if you specify PNAME=TEST*, then all records with TEST in the first four charactersof the Process name field are selected. Records having TEST, TEST123, and TESTX all satisfy theselection criterion.

name specifies the name of the Process to select.

(list) specifies a list of Process names to select. Enclose the list in parentheses. SeparateProcesses in the list with commas.

PNUMber = number | (list)

specifies selection by Process number. To request a list of Processes, enclose them inparentheses. The range is 1–99999.

number specifies the number of the Process to select.

STARTT = ([date | day] [,hh:mm:ssXM])

specifies selection by start date and time. Specify STARTT as a date and time prior to the currenttime. If you set this parameter, the event records retrieved from the statistics file begin with thedate and time you specified and continue until the current time is reached. At that point, eventrecords are processed as they occur.

Note: If you specify STARTT and LASTSEQ with the EVENT SERVICES START command, thosevalues replace the values specified for these parameters in the EVENT SERVICES CREATEcommand. When you use the time specification in conjunction with the LASTSEQ parameter, youmust include hours, minutes, seconds, and hundredths of seconds in the format hh:mm:ss.th.

Chapter 6. Facilities Guide 733

date specifies the starting date from which event records are retrieved from the statistics file. Youcan specify the date in either Gregorian or Julian format.

If you use a Gregorian date format, set the DATEFORM initialization parameter to the appropriatedate format. Otherwise, the date format defaults to the platform date format. You do not need toset the DATEFORM parameter for Julian date format.

The following table shows the acceptable date formats:

Format DATEFORMParameter

Date Format

Gregorian DATEFORM=MDY mmddyy or mmddyyyy

mm/dd/yy or mm/dd/yyyy

mm.dd.yy or mm.dd.yyyy

Gregorian DATEFORM=DMY ddmmyy or ddmmyyyy

dd/mm/yy or dd/mm/yyyy

dd.mm.yy or dd.mm.yyyy

Gregorian DATEFORM=YMD yymmdd or yyyymmdd

yy/mm/dd or yyyy/mm/dd

yy.mm.dd or yyyy.mm.dd

Gregorian DATEFORM=YDM yyddmm or yyyyddmm

yy/dd/mm or yyyy/dd/mm

yy.dd.mm or yyyy.dd.mm

Julian N/A yyddd or yyyyddd

yy/ddd or yyyy/ddd

yy.ddd or yyyy.ddd

Note: If RETAIN=Y, you cannot specify a date in the STARTT parameter of the initialization file.

day specifies the day of the week to select. Valid names include MOnday, TUesday, WEdnesday,THursday, FRiday, SAturday, and SUnday. You can also specify YESTER to retrieve event recordscreated since yesterday, or TODAY to retrieve event records created today.

hh:mm:ssXM indicates the start time of day in hours (hh), minutes (mm), and seconds (ss)selected. XM indicates AM or PM. You can use the 24-hour clock or the 12-hour clock. If youuse the 24-hour clock, valid times are 00:00-24:00. If you use the 12-hour clock, valid times are00:00-12:00 and you must indicate AM or PM. For example, 01:00 hours on the 24 hour clock isexpressed as 1:00AM on the 12 hour clock. If you do not specify AM or PM, IBM Connect:Directassumes the 24-hour clock. You do not need to specify minutes and seconds. You can also specifyNOON to retrieve event records starting at noon, or MIDNIGHT to retrieve event records starting atmidnight. The default for the time is 00:00:00, the beginning of the day.

If you do not specify the STARTT parameter, event processing begins with the current time.

STOPT = ([date | day] [,hh:mm:ssXM])

specifies when interest in event data ends.

date specifies the stop date when event processing ends. You can specify the date in eitherGregorian or Julian format.

Refer to the STARTT subparameter for a discussion of Gregorian and Julian date formats.

734 IBM Connect:Direct for z/OS: Documentation

If you specify only the date, the time defaults to 24:00:00.

day specifies the day of the week to select. Valid values include MOnday, TUesday, WEdnesday,THursday, FRiday, SAturday, and SUnday. You can also specify TODAY.

hh:mm:ssXM indicates the stop time of day in hours (hh), minutes (mm), and seconds (ss) toselect. XM indicates AM or PM. You can use the 24-hour clock or the 12-hour clock. If you usethe 24-hour clock, valid times are 00:00-24:00. If you use the 12-hour clock, valid times are00:00-12:00 and you must indicate AM or PM. For example, 01:00 hours on the 24 hour clock isexpressed as 1:00AM on the 12 hour clock. If you do not specify AM or PM, IBM Connect:Directassumes the 24-hour clock.

You do not need to specify minutes and seconds. You can also specify NOON to retrieve eventrecords starting at noon, or MIDNIGHT to retrieve event records starting at midnight. The defaulttime is 24:00:00, the end of the day.

If you do not specify the STOPT parameter, you must issue an EVENT SERVICES STOP commandto stop event processing.

USER = name | (list)

limits the selected event records to those written for userids with the specified name. You canspecify a list of names by enclosing them in parentheses. You can use wild card characters. Forexample, if you specify USER = SYS$*, then records with SYS$ in the first four characters ofthe userid field are selected. Records having SYS$BOB, SYS$ADM, and SYS$0001 all satisfy thisselection criterion. Userid names can be up to 64 characters in length and can contain lowercasecharacters.

name specifies the userid to select.

(list) specifies a list of userids to select. Enclose the list in parentheses. Separate userids in the listwith commas.

SNODE = name | (list)

limits the selected event records to those written for Processes where the specified node nameacted as SNODE. You can specify a list of names by enclosing them in parentheses. You canuse wild card characters. For example, if you specify SNODE=DALLAS*, then all records withDALLAS in the first six characters of the SNODE field are selected. Records having DALLAS.PROD,DALLAS.TEST, and DALLAS all satisfy this selection criterion. SNODE names can contain lowercasecharacters.

name specifies the SNODE to select.

(list) specifies a list of SNODES to select. Enclose the list in parentheses. Separate SNODES in thelist with commas.

TYPE = id | (list)

specifies the event record types to select. Every event record that IBM Connect:Direct generateshas an associated record-type identifier. Each identifier is two characters long and indicates theevent or function that generated the record. The identifier also indicates the record format andcontents.

id specifies the event record type.

(list) specifies a list of event record types to select. Enclose the list in parentheses. Separaterecord types in the list with commas.

FNAME=dsname | (list)

limits the selected event records to those that contain the specified filename. The FNAMEsubparameter is valid for the following record types: Copy Termination (CT), Run Job (RJ), StartIBM Connect:Direct (SD), and Submit within Process (SW).

name specifies the filename to select.

Chapter 6. Facilities Guide 735

(list) specifies a list of filenames to select. Enclose the list in parentheses. Separate filenames inthe list with commas.

The meaning of the filename within these records is unique for each record type. For example,the Run Job record contains the filename of the submitted JCL. Filenames can be up to 254characters in length and can contain lowercase characters. Filenames must conform to yourplatform's naming conventions.

CASE=YES | NO

specifies whether lowercase or mixed-case data is permitted for the USER, SNODE, and FNAMEsubparameters. The CASE subparameter overrides the global CASE option defined at signon forthe SELECT STATISTICS command.

YES changes the data in USER, SNODE, and FNAME to uppercase regardless of the actual dataspecified.

NO preserves the actual case entered for the USER, SNODE, and FNAME subparameters.

The CASE defaults to the setting defined in the session defaults, if nothing is specified.

LASTSEQ=n

specifies the last sequence number (for Restart capability) associated with the date/time stamp.Use it with the STARTT parameter. This information is provided by CICS when you issue a CREATEEVENT SERVICES REQUEST command for an event services request that finished abnormally.

MAXQCNT=n

specifies the maximum number of elements that can reside in the internal event queue for thisrequest. All events that match the WHERE criteria for this request are placed on an internal queue.If events occur faster than the API can process them, the queue can become full. If the queuebecomes full, IBM Connect:Direct terminates event services requests. You can modify the queuesize using MAXQCNT. Each queue element takes approximately 2K in storage. The default is 100.

EXIT=exitname

specifies the name of an EVENT SERVICES OPTION exit. The sample exit DGAXEV01 is providedin the sample library. Event data is processed by an exit rather than the calling API, if EXIT isspecified.

Optional ParametersThe following parameters are optional for the EVENT SERVICES CREATE command.

ORWHERE (CCODE = (condition, completion code) | PNAME = name | (list)PNUMber = number | (list)USER = name | (list)SNODE = name | (list)TYPE = id | (list)FNAME = dsname | (list)

specifies which statistics records you want to examine.

The subparameters, such as CCODE, PNAME, PNUMBER, and TYPE, are optional, but you must specifyat least one.

The parameters for the ORWHERE keyword are defined in the WHERE keyword section.

Sample CommandThe following is an example of the EVENT SERVICES CREATE command.

EVENT CREATE ID=PROCESS_TERM WHERE(TYPE=PT)

736 IBM Connect:Direct for z/OS: Documentation

EVENT SERVICES START Command FormatThe EVENT SERVICES START command enables you to start a specific notification request for event data.This command provides parameters where you can define what data (date, time, and sequence) is sent toyour application.

The EVENT SERVICES START command uses the following format and parameters.

Command Parameters

EVENT [SERVICES]START

ID=event-request-name

WHERE=(STARTT | LASTSEQ | KEEPRREC | ( for CICS only)TRACE) (CICS only)

Required ParameterThe EVENT SERVICES START command has one required parameter.

ID=event-request-namespecifies the logical name of the event services request to start. Specify this name in a CREATE EVENTSERVICES command.

Optional ParametersThe following parameter is optional for the EVENT SERVICES START command.

WHERE(STARTT | LASTSEQ | KEEPRREC | TRACE)

sets restriction on event records meeting the following selection criteria.STARTT=([date|day][,hh:mm:ssXM])

specifies selection by designated starting date and time. STARTT must be a date and time prior tothe current time. If you specify this parameter, the event records retrieved from the statistics filebegins with the date and time you specified, and continues until the current time is reached. Atthat point, event records are processed as they occur.

For a complete explanation of the subparameters, refer to EVENT SERVICES CREATE CommandFormat.

LASTSEQ=nspecifies the last sequence number (for Restart capability) associated with the date/time stamp.Use this parameter with the STARTT parameter. This information is provided by CICS when youissue a CREATE EVENT SERVICES REQUEST command for an event services request that finishedabnormally.

KEEPRREC (CICS-only)specifies that the restart record created by IBM Connect:Direct is kept, regardless of whetherthe event request completed abnormally or not. If KEEPRREC is not specified, the restart recordcreated by IBM Connect:Direct is deleted if the event request completes normally.

TRACE (CICS-only)specifies that every event record placed on the CICS TDQ is also written to the NDMTRACEtemporary storage (TS) queue. You can use the NDMTRACE temporary storage queue to verify thatEVENT records are flowing to the transient data queue.

Sample CommandFollowing is an example of the EVENT SERVICES START command.

EVENT START ID=PROCESS_TERM

Chapter 6. Facilities Guide 737

EVENT SERVICES STOP Command FormatThe EVENT SERVICES STOP command stops event notification for a specific event services request.

The EVENT SERVICES STOP command stops event notification and deletes the event request from thesystem.

The EVENT SERVICES STOP command uses the following format and parameters.

Command Parameters

EVENT [SERVICES]STOP

ID=event-request-name

IMMEDIATE

Required ParameterThe EVENT SERVICES STOP command has one required parameter.ID=event-request-name

specifies the logical name of the event services request to start. This name must match a namespecified in a CREATE EVENT SERVICES command.

Optional ParameterThe EVENT SERVICES STOP command has one optional parameter.IMMEDIATE

indicates that no more event records can be sent. If you do not specify IMMEDIATE, all records on theinternal EVENT queue are sent before the EVENT request is terminated.

EVENT SERVICES DISPLAY Command FormatThe EVENT SERVICES DISPLAY command enables you to display event data for a specific event servicesrequest. The EVENT SERVICES DISPLAY command uses the following format and parameter.

Command Parameter

EVENT [SERVICES]DISPLAY

ID=event-request-name

Required ParametersThe EVENT SERVICES DISPLAY command has no required parameters.

Optional ParameterThe EVENT SERVICES DISPLAY command has one optional parameter.ID=event-request-name

specifies the logical name of the event services request to display. This name must match a namespecified in a CREATE EVENT SERVICES command. If you do not specify this parameter, all eventservices requests are displayed.

CICS ESS CustomizationThe IBM Connect:Direct CICS interface enables you to use IBM Connect:Direct through the CustomerInformation Control System (CICS) from local and remote sites. The system includes a set of nestedmenus, prompts for required information, online Help facilities, and monitoring features for currentstatus.

738 IBM Connect:Direct for z/OS: Documentation

In addition to the IBM Connect:Direct IUI, a facility is provided that enables you to issue standard IBMConnect:Direct commands from a CICS application program. You can use this interface for both terminaland non-terminal tasks. Following are two typical uses for this API:

• For terminal tasks, the API enables an installer to provide their own user interface to all or part of IBMConnect:Direct or work with IBM Connect:Direct from application programs using the DGAN transaction.

• For non-terminal tasks, the API enables an installer to write background transactions whichprogrammatically issue IBM Connect:Direct commands. The most typical sequence is SIGNON -SUBMIT - SIGNOFF. In this case, the SIGNON generates a SIGNON TYPE=CICS, and the SIGNOFFresults in a cleanup operation of the signon table entry, temporary storage, and so forth.

To avoid having to sign on before each command and sign off after each command, the user applicationcan pass a logical task number through the Q012TASK field. If Q012TASK is used, a user program cansign on once and issue multiple commands in pseudo-conversational mode. A signoff is only neededwhen the user application is terminating.

An example of the use of this facility is provided in member DGAQ247 of the $CD.SDGASAMP. Thisprogram enables you to type IBM Connect:Direct commands on a screen and view the resulting returncode, message number, message text, and Process number assigned to your IBM Connect:Direct Process.In addition, the CICS application displays the name of the CICS Temporary Storage (TS) queue where theresults of your command are stored, the count of items in the queue, and the maximum record length inthe queue.

You must install both IBM Connect:Direct and the IBM Connect:Direct CICS interface, and they must beoperating for the IBM Connect:Direct CICS API to function.

The following elements are required to use DGAQ247:

Component Description

DGAQ247 The program source, written in assembly language

DGAQM98 The BMS map used by DGAQ247

DGAQBMST A parsing macro used by DGAQ247

DGAQCA12 A command-level COMMAREA passed to the CICS Interface

Following is a sample IBM Connect:Direct API DRIVER screen. It shows data after the ESS registrationprogram has signed on to the IBM Connect:Direct CICS API driver and issued an EVENT SERVICESCREATE command.

CONNECT:Direct API DRIVER COMMAND EVENT SERVICES CREATE ID=MESOO031 WHERE(MAXQCNT=998 LASTSEQ=1 STARTT=(02.14.2010,04:14:12.45) STOPT=(12.31.2041,24:00:00.00) TYPE=(QE,QW,QH,QT,PI,CE,CT,PT,CI,RJ,RT,JI,TI,SW,DP) ) COMMAND RC 0000 COMMAND MSG ID SOPM000I COMMAND MSG An EVENT REQUEST HAS COMPLETED NORMALLY PROCESS NUMBER TD EXIT COUNT TS QUEUE NAME TS MAX LRECL EVENT RESTART DATA WHERE(STARTT=(00000,00:00:00.00),LASTSEQ=000) PF keys: 3 Exit 5 Signon 6 Command 7 Signoff

The following table describes the Driver fields:

Field Description

COMMAND This 3-line field contains your API command.

COMMAND RC This 4-character field contains the return code from your API Process.

Chapter 6. Facilities Guide 739

Field Description

COMMAND MSG ID This 8-character field contains the identification number of the messageassociated with your API Process.

COMMAND MSG This 64-character field contains the text of the message.

PROCESS NUMBER This 6-character field contains the Process number assigned by the system to yourAPI Process.

TD EXIT COUNT This 6-character field contains the number of bytes indicating how much data iswritten by the exit module for your API Process.

TS QUEUE NAME This 8-character field contains the name of the TS queue used during your APIrequest.

TS MAX LRECL This 4-character field contains the maximum logical record length in bytes of theTS queue.

EVENT RESTARTDATA

This 62-character field contains the DATE/TIME/SEQ of the last event recordsuccessfully received. Data is only displayed if an EVENT SERVICES CREATEcommand is issued and a previous event services request had ended abnormally.

CICS API OptionTo use the sample program, you must first change DGAQ247 to issue a valid SIGNON command foryour environment (the SIGNON command is defined near the end of the source module). Include a validUSERID, PASSWORD, and NODE. Before executing this program as a transaction, you must be signed onto CICS. Also observe the following items.

• Assemble DGAQM98 and then DGAQ247. Sample JCL is in the $CD.SDGASAMP. Assemble DGAQM98and DGAQ247 as follows:

– Use member DGAXASMB to assemble DGAQM98– Use member DGAXASMC to assemble DGAQ247

• Use the IBM Connect:Direct Administrative (DGAA) transaction to verify that the CICS Interface and theappropriate node are both active.

• Use transaction DGAN to display DGAQM98.

The program checks for the presence of a communications area in the Exec Interface Block (EIB). Ifnone is present, or if you press the Clear key, the DGAQM98 map is sent and a RETURN TRANSID isperformed to invoke the transaction again when you press Enter.

• If you pressed the PF3 or PF15 key, the program terminates.• The DGAQM98 map is received. If you pressed PF5 or PF17, a IBM Connect:Direct SIGNON request is

generated and the results of the command are presented in the map.• Following a successful signon (that is, the return code on DGAQM98 after the SIGNON is zero), you can

type a valid IBM Connect:Direct command on the line provided in the DGAQM98 map and press PF6 orPF18 to send the command to the IBM Connect:Direct DTF. Command results are displayed when theyare returned from the DTF.

• To signoff from the DTF, press PF7 or PF19.

When you type a command through the DGAQM98 screen, its length is determined and the addressof the length and command are placed in the DGAQC12 communications area at label Q012CMDA.Program DGAQ012 is then invoked through an EXEC CICS LINK command. When control returns toDGAQ247, the DGAQC12 communications area contain the results of the command.

Note: The DGAQ247 does not display the results of the issued command stored in CICS temporarystorage. Retrieve these records programmatically or view them using the CICS CEBR transaction.

740 IBM Connect:Direct for z/OS: Documentation

Use the techniques in the DGAQ247 sample program to issue any valid IBM Connect:Direct command.Results of commands such as SELECT PROCESS and SELECT STATISTICS are written to CICS temporarystorage; other commands may produce no output.

Accessing the API Module (DGAQ012)• Access the API by linking to program DGAQ012 within your CICS program/transaction as follows.

EXEC CICS LINK PROGRAM('DGAQ012') COMMAREA(Q012COMM) + LENGTH(Q012CMLH)

The COMMAREA Q012COMM is defined by macro DGAQCA12 in $CD.SDGASAMP and is also providedin $CD.SDGASAMP. A COBOL version of this record layout is provided as member DGAQAPIC in thesample library. A brief description of each of the fields follows:

Field AssemblerDirective

Format Description

Q012CMDA DS XL4 Full word containing the address of the commandto be issued to IBM Connect:Direct. Thecommand must be in the following format:CMDLEN DS H

Length of CMDTEXT that IBM Connect:Directrecognizes, not including length of CMDLEN.

CMDTEXT DS ClxCommand text

Q012RETC DS XL4 Return code received after the command isinvoked.

0: request completed successfully1: C:D-CICS interface level error2: C:D-CICS node level error3: C:D-CICS signon level error5: invalid COMMAREA or command passed toCICS API8 and above: unsuccessful request

Q012TDCT DS XL4 TDEXIT ITEM COUNT. The field contains thenumber of records received from the IBMConnect:Direct DTF.

Q012CMDA is the only required parameter you must set before the EXEC CICS LINK to DGAQ012.For optimum performance, follow the example of DGAQ247 and initialize all fields before linking toDGAQ012.

Any output generated by issuing the command is returned in a temporary storage queue. Your terminalID is displayed as the last four characters in the unique TS queue name.

LASTSEQ ParameterAll event records contain a unique timestamp that consists of date, time, and sequence number. EachEVENT SERVICES request is associated with an ID. The IBM Connect:Direct CICS API creates a restartrecord for an ID when an EVENT SERVICES CREATE command is processed.

After an event record is successfully delivered to the Transient Data Queue, its timestamp is saved in therestart file. If event services processing ends abnormally, the restart record is retained. The restart recordis also retained when you specify KEEPRREC (keep restart record) in the EVENT START statement.

Chapter 6. Facilities Guide 741

When an EVENT SERVICES CREATE command is processed, the restart file is searched for a recordmatching the ID of the CREATE. If a match is found, the date, time, and sequence number of the lastsuccessfully delivered event record is returned. When you use the time specification in conjunction withthe LASTSEQ parameter, you must include hours, minutes, seconds, and hundredths of seconds in theformat hh:mm:ss.th.

Field AssemblerDirective

Format Description

Q012TDMX DS XL2 TDEXIT MAX ITEM SIZE - the maximum record sizereceived from the IBM Connect:Direct DTF.

Q012PROC DS CL6 Process number of the latest submitted Process.

Q012TSKY DS CL8 Temporary storage ID - the name of the CICS TSqueue that contains the command output.

Q012MSID DS CL8 Message ID returned from the Connect:Direct forz/OS DTF.

Q012MSTX DS CL64 Message Text returned from the Connect:Direct forz/OS DTF.

Q012DTE DS PL4 Date of the last event acknowledgment.

Q012TME DS XL4 Time of the last event acknowledgment.

Q012SEQ DS XL2 Sequence number of the last eventacknowledgment.

Note: DGAQ012 requires that it run in CICS key. For the transaction that executes a program linkingDGAQ012, set the following parameters in the CEDA definitions (or in the RDO for that program):

• TaskDataLoc:ANY• TaskDataKey:CICS

If missed event data is required, use this information as the STARTT and LASTSEQ values as in thefollowing example.

Event records beginning after this timestamp are processed.

Event Record from the Transient Data QueueThe sample program DGAQ249 reads an ESS event record from the Transient Data queue. The sampleprogram DGAQ249 is in $CD.SDGASAMP. Use JCL DGAXASMC in $CD.SDGASAMP to assemble DGAQ249.

Each record passed to the user application consists of a record header and an event record. DGA$NHDR ,which is in the IBM Connect:Direct sample library, maps the record header. Members in the sample libraryalso map the event records. Search for Event Services Record Descriptions to determine which membermaps a particular event record.

Event Services Record DescriptionsESS enables you to create ESS-enabled applications. Following is reference information about eventrecord types and attributes that help you create applications. For a list of statistics record types, searchfor Using IBM Connect:Direct Exits.

Assembler DSECT members are in the sample library. Access the information by the member nameslisted in the following table. Use the two-character designations for record types when you browse theIBM Connect:Direct statistics file.

Event Record Type AttributesESS has several statistics record types. This section summarizes the attributes of these record types.

742 IBM Connect:Direct for z/OS: Documentation

Most record types have the following common attributes:

• Process name• Process number• Message ID• Submitter’s symbolic node name• PNODE name for this Process• SNODE name for this Process• THISNODE (This node is P[node] or S[node].)

The following paragraphs detail the attributes of specific record types. For ease of reference, theinformation is grouped according to event type or enhancement type, and they are presentedalphabetically.

Event Record TypesRecord type attributes for event records are described in the following paragraphs. The information isorganized alphabetically by record type identifier.CI (COPY Step Initiation)

This record is created immediately prior to the execution of any tasks associated with a COPYstatement. The intent of this record is to capture the timing of such work as data set allocation prior toany I/O occurring. In addition to the common attributes, CI has the following individual attributes:

• COPY step start date/time• Step name or label• CI record retry count• Transfer direction• Source file name• Destination file name• Member name (when applicable)

CE (COPY I/O Start)

This record is created immediately prior to the first block of data transferred in a COPY statement. Inaddition to the common attributes, CE has the following individual attributes:

• COPY I/O start date/time• Step name or label• CE record retry count

EI (Event Request Initiation)

This record is created upon completion of a EVENT SERVICES START command.

Note: The common attributes for Process-related records do not apply to this record.

The following attributes apply to this event:

• Date/Time the command completed• User ID of the user who issued the command• Event services request ID• Completion code for the command• Command parameter string

EL (Event Session Lost)

This record is created when the IBM Connect:Direct DTF is lost.

Chapter 6. Facilities Guide 743

ET (Event Request Stop)

This record is created when an EVENT SERVICES STOP command completes.

Note: The common attributes for Process-related records do not apply to this record.

The following attributes apply to this event:

• Date/Time the command completed• User ID of user who issued the command• Event services request ID• Completion code for the command

JI (RUN JOB Start)

This record is created immediately before the job specified by the RUN TASK statement is submitted.In addition to common attributes, JI has the following individual attributes:

• RUN JOB start date/time• Step name or label• Job name• JI record retry count

QE (Process moved to EXEC queue)

This record is created when a Process is moved to the execution queue. In addition to the commonattributes, QE has the following individual attributes:

• Process execution start date/time• QE record retry count

PI (Process Initiation)

This record is created immediately prior to when the first Process step is executed. In addition to thecommon attributes, PI has the following individual attributes:

• Queue change date/time• Execution queue status value• PI record retry count

QH (Process moved to the HOLD queue)

This record is created when a Process is moved to the Hold queue, through a problem during Processexecution or submission, a SUSPEND PROCESS command issued or a session failure. The reason isidentified by the Hold queue status value. In addition to the common attributes, QH has the followingindividual attributes:

• Queue change date/time• Hold queue status value• QH record retry count

QT (Process moved to the TIMER queue)

This record is created whenever a Process is moved to the Timer queue, normally through a Processretry. In addition to the common attributes, QT has the following individual attributes:

• Queue change date/time• Timer queue status value• QT record retry count

QW (Process moved to the WAIT queue)

This record is created whenever a Process is moved to the Wait queue from the Hold or Timer queues.In addition to the common attributes, QW has the following individual attributes:

744 IBM Connect:Direct for z/OS: Documentation

• Queue change date/time• Wait queue status value• QW record retry count

TI (RUN TASK Initiation)

This record is created immediately prior to the initiation of the task specified by the RUN TASKstatement. In addition to the common attributes, TI has the following individual attributes:

• RUN TASK start date/time• Step name or label• Program name• TI record retry count• Date/time• Process name and number• Event name• Event trigger• Event type

Event Record Enhancements

An enhancement to existing statistics records is described in the following paragraph.

CT (COPY Termination) Record Enhancements

The existing CT record is enhanced to include the following information:

• Total number of retries for the COPY step• Total amount of data moved for all attempts of the COPY• Type keywords specified in a COPY step to retrieve data set defaults for allocating the destinationfile

Spool Transfer FacilityIBM Connect:Direct Spool Transfer is an interface that enables you to transfer Job Entry Subsystem (JES)spool files in the following ways:

• Copy from JES Spool Files

The VPS/CDI option and the VPSSCDI program manage input from JES spool files. Using this featureallows IBM Connect:Direct to transfer spool from one system to another.

• Copy to JES Print Queues

IBM Connect:Direct dynamically allocates a print file and writes the input file directly to the JES Spool.• Copy to JES Reader Queues

IBM Connect:Direct dynamically allocates an internal reader and writes the input file directly to the JESReader.

For outbound transfers, this feature requires the following additional products from Levi, Ray & Schoup(LRS):

• VTAM Printer Support (VPS)• VPS IBM Connect:Direct Interface (VPS/CDI) Option

Note: To send output to JES2 or JES3 (Reader or a printer queue), you do not need the VTAM PrinterSupport and VPS IBM Connect:Direct Interface (VPS/CDI) Option components.

IBM Connect:Direct Spool Transfer uses standard IBM Connect:Direct facilities, which provideautomation, reliability, management, interoperability, and security.

Chapter 6. Facilities Guide 745

Spool Transfer ComponentsThe major components of IBM Connect:Direct Spool Transfer are:

• VTAM Printer Support (VPS) System• Application Program Interface (API)• Data Transmission Facility (DTF)• The following diagram shows the relationship between these components. This chapter summarizes the

function of each component.

You implement IBM Connect:Direct Spool Transfer by changing definitions in the VPS initialization. Pleaserefer to the Levi, Ray & Shoup documentation for their VPS product for correct implementation of VPS.

VTAM Printer SupportConnect:Direct for z/OS uses VTAM Printer Support (VPS) to retrieve JES spool files for processing.Expansion of the VPS application includes IBM Connect:Direct support for moving print files from the JESspool to any IBM Connect:Direct node. The VPS module (VPSSCDI) directs spooled output from JES to theIBM Connect:Direct API for file transfer.

The following diagram illustrates the flow of the print file through this process.

VPS passes control to the IBM Connect:Direct API at the following times:

Phase Description

SystemInitialization

When a JES spool file is sent through IBM Connect:Direct, VPS first transferscontrol to the IBM Connect:Direct API for printer initialization and the API issues aSIGNON to the local DTF.

746 IBM Connect:Direct for z/OS: Documentation

Phase Description

PrinterInitialization

After signon, VPS copies the print files to a disk file and sends it to the IBMConnect:Direct API.

SYSOUT Data SetReady

The IBM Connect:Direct API constructs a SUBMIT PROCESS command to sendprinter attributes, data set name, and the submitter's user ID to the local DTF.

If the SUBMIT fails because the Process can not be found or the SNODE isunavailable, the print file is returned to the JES print queue according to the valuesspecified in the requeue parameters. If the SUBMIT fails for another reason, VPSdeletes the staged data set, drains its DTF WRITER, and leaves the JES spool file inthe JES queue for restart.

If the SUBMIT is successful, VPS releases ownership of the staged data set to IBMConnect:Direct, and the JES spool file is PURGED from JES.

Printer Termination When no more JES files are printing to IBM Connect:Direct, a printer terminationrequest is sent to IBM Connect:Direct API.

SystemTermination

The IBM Connect:Direct API then sends a SIGNOFF command to the local DTF.

You can change VPSSCDI to modify IBM Connect:Direct control blocks prior to calling DGASVPSA.

IBM Connect:Direct APIThe IBM Connect:Direct API (DGASVPSA) communicates with the Data Transmission Facility through anapplication interface. DGASVPSA signs on to the local DTF, submits a Process, and signs off of the localDTF.

Module orCommand

Description

DGASVPSA DGASVPSA is part of the VPS interface and is distributed in $CD.SDGASAMP. Thisprogram is in source form. You can assemble and link-edit when you install a newrelease of IBM Connect:Direct VPS.

It uses the VPS system log for reporting exception conditions and informationalmessages describing the Processes submitted to the local DTF. This log serves asone central point to determine the status of any print file controlled by VPS.

The DGASVPSA program receives control from VPSSCDI and validates thefunction calls and control block fields passed by VPSSCDI. If a function executessuccessfully, the program returns a condition code of 0 (zero) to the VPSSCDI.

If a noncritical error occurs, DGASVPSA returns a code of 4 to VPSSCDI to indicatethat VPS requeues the print file according to VPS printer specifications.

If DGASVPSA detects a critical error, it returns a code of 8 or greater, indicating thatVPS can EDRAIN the printer.

A function call of PRINTER INITIALIZATION causes a SIGNON to be sent to thelocal DTF as defined in the network map specification for this printer.

A function call of DATA SET SYSOUT READY invokes the routines to validate thecontrol blocks and build the IBM Connect:Direct SUBMIT PROCESS command andsend it to the local DTF.

A function call of PRINTER TERMINATION sends a SIGNOFF to the local DTF.

DGASVPSA uses the IBM Connect:Direct API interface module (DGADCHLA) tocommunicate with the Data Transmission Facility.

Chapter 6. Facilities Guide 747

Module orCommand

Description

VPSSCDI The VPS module VPSSCDI, the interface to IBM Connect:Direct, is distributed inVPS. This program is in source form and you can reassemble and link-edit it whenyou install a new release of VPS or IBM Connect:Direct.

SIGNON This command uses the network map specification for the specified IBMConnect:Direct printer.

If you do not have a network map override specified in the VPS printer definitiontable (CDNETMAP), the SIGNON command uses the DMNETMAP DD statement inthe VPS startup JCL for the network map.

SIGNON Security The SIGNON command for DGASVPSA does not pass a user id or password. Ifyou use the Stage 1 security exit, user id associated with the VPS started task isextracted and the user id and a special password (assigned by the Stage 1 exit) isplaced in the UICB, a user interface control block used for security.

If the Stage 1 processing is successful, the SIGNON command passes to the DTF,where the DTF Stage 2 security is invoked. The Stage 2 exit recognizes the specialpassword, as assigned by the Stage 1 exit. All verification calls to the securitysystem are by user id only.

If you send to a secured IBM Connect:Direct, you can specify user id and passwordby adding the SNODEID specification to the Process. All Processes submitted bythe VPS API have the security access level associated with the VPS job or startedtask, unless the security is overridden by PNODEID, SNODEID, and/or securepoint-of-entry (SPOE) translation.

Process NamesVPS print files are routed through the IBM Connect:Direct network by specifying the SNODE keyword onthe submitted Process. To provide flexibility, you can set up the VPS IBM Connect:Direct printer either tosubmit a single Process name regardless of printer class or to submit a Process name with the printeroutput class appended to the name.

By appending the printer class to the name, one VPS/CDI printer can submit up to 36 different Processnames, one for each printer class A–Z or 0–9. You can control the Process name being submitted with theVPS printer name and VPS printer definitions as follows:

• Define the CDSNODE in the VPS Printer Definition Table• Define the CDPMBR in the VPS Printer Definition Table• Use a VPS printer name of seven characters or less• Use a VPS printer name of eight characters

This flexibility enables a VPS printer to submit Processes that send print files to one or more IBMConnect:Direct SNODEs.

Use the following table to select the best method for your environment.

Where to Code Keyword Requirements Results

Use Default (Do notcode)

None 1 to 7-character printername

Process name is the VPS Printer namewith the class appended.

Use Default (Do notcode)

None 8-character printername

Process name is the VPS Printername.

748 IBM Connect:Direct for z/OS: Documentation

Where to Code Keyword Requirements Results

VPS Printer DefinitionTable

CDSNODE Value for CDSNODE

Process name specifiedin CDPMBR

Process name is the printer name.(Class is not appended.)

VPS Printer DefinitionTable

CDSNODECDPMBR

Value for CDSNODE andCDPMBR

Process name is the name specifiedin CDPMBR. (Class is not appended.)

VPS Printer DefinitionTable

CDPMBR 8 characters Process member name remains thesame for all print files. (Class is notappended.)

VPS Printer DefinitionTable

CDPMBR Up to 7 characters Process name is the name specifiedin CDPMBR (Class is appended.)

Note: IBM Connect:Direct searches the IBM Connect:Direct Process library, SDGAPROC, for the Processname. You must define the Process names in the Process library.

For example, if you select CDPMBR=CDPROC and the output print class is A, IBM Connect:Direct searchesthe Process library for the Process name of CDPROCA. If you select an output print class of C for the sameprinter, IBM Connect:Direct searches for the Process name CDPROCC.

However, if you use an eight-character name such as CDPMBR=DGAXPRC1, the Process name for thatprinter is DGAXPRC1, regardless of the printer class.

Sample Process to Display Attributes in the SUBMIT StatementThe following sample Process is provided in the Install Process Library, SDGAPROC. This exampleshows all attributes that can pass from DGASVPSA to the local IBM Connect:Direct DTF in the SUBMITstatement. Any value of X’00’ passed from VPS to DGASVPSA is considered a null value, and the SUBMITcommand does not pass the corresponding field to the Process. For example, if your printer output DDstatement does not code COPIES, then the symbolic &COPIES is not passed in the SUBMIT command.

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* */ /* C:D-ZOS JES SPOOL TRANSFER FACILITY SAMPLE PROCESS */ /* */ /* CHANGE $CD.PROC TO THE Z/OS PROC LIBRARY THAT YOU HAVE */ /* INSTALLED THE PROC GENER INTO. THE CONNECT:DIRECT */ /* INSTALLATION LOADED THIS MEMBER INTO YOUR */ /* CONNECT:DIRECT PROCESS LIBRARY. */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ CDPROCES PROC SNODE=&SNODE, - &ADDR1=, /* ADDRESS LINE 1 */ - &ADDR2=, /* ADDRESS LINE 1 */ - &ADDR3=, /* ADDRESS LINE 1 */ - &ADDR4=, /* ADDRESS LINE 1 */ - &BLDG=, /* BUILDING */ - &BURST=, /* BURST=YES OR NO */ - &CHARS=, /* CHAR ARRANGEMENT TABLE */ - &CKPTL=, /* CKPTLINE */ - &CKPTP=, /* CKPTPAGE */ - &CKPTS=, /* CKPTSEC */ - &CLASS=, /* OUTPUT CLASS */ - &CMOD=, /* COPY MODIFICATION MOD */ - &CMTTC=, /* COPY MODULE TABLE REF */ - &CNTL=, /* DEFAULT SPACING */ - &COMPACT=, /* COMPACTATION TABLE */ - &COPIES=, /* OUTPUT NUMBER COPIES */ - &COPYG=, /* COPY GROUP(S) */ - &DATCK=, /* DATACK */ - &DEFAULT=, /* DEFAULT */ - &DEPT=, /* DEPARTMENT */ - &DEST=, /* OUTPUT DESTINATION */ - &FCB=, /* OUTPUT WTR FCB */ - &FLASH=, /* FLASH FORMS OVERLAY */ - &FLSCT=, /* FLASH FORMS OVERLAY CNT*/ - &FMDEF=, /* FORMDEF */ -

Chapter 6. Facilities Guide 749

&FORM=, /* OUTPUT FORM */ - &GROUPID=, /* GROUPID */ - &INDEX=, /* INDEX */ - &JACCT=, /* JOB ACCOUNTING NUMBER */ - &JESDS=, /* JESDS */ - &JOBID=, /* JES ASSIGNED JOB ID */ - &JOBNM=, /* JOB NAME */ - &JPNAME=, /* JOB PROGRAMMERS NAME */ - &JPROC=, /* JOB PROC NAME */ - &JROOM=, /* JOB PROGRAMMERS ROOM */ - &JSECL=, /* SECURITY LABEL */ - &LINDEX=, /* LINDEX */ - &LINECT=, /* LINES PER PAGE */ - &NAME=, /* NAME */ - &NOTIFY1=, /* 1ST NOTIFY ID */ - &NOTIFY2=, /* 2ND NOTIFY ID */ - &NOTIFY3=, /* 3RD NOTIFY ID */ - &NOTIFY4=, /* 4TH NOTIFY ID */ - &OPTCD=, /* OPTCD=J SPECIFIED */ - &PGDEF=, /* PAGEDEF */ - &PIMCT=, /* PIMSG MSG-COUNT */ - &PIMSG=, /* PIMSG */ - &PRMODE=, /* PRMODE */ - &PRTY=, /* PRTY */ - &ROOM=, /* ROOM */ - &STEPDD=, /* STEP DDNAME */ - &STEPNM=, /* STEP NAME */ - &SUBNAME=, /* SUBMITTERS NAME */ - &THRES=, /* THRESHLD */ - &TITLE=, /* TITLE */ - &TRC=, /* TRC */ - &UCS=, /* OUTPUT WTR UCS */ - &UDATA01=, /* 1ST USERDATA */ - &UDATA02=, /* 2ND USERDATA */ - &UDATA03=, /* 3RD USERDATA */ - &UDATA04=, /* 4TH USERDATA */ - &UDATA05=, /* 5TH USERDATA */ - &UDATA06=, /* 6TH USERDATA */ - &UDATA07=, /* 7TH USERDATA */ - &UDATA08=, /* 8TH USERDATA */ - &UDATA09=, /* 9TH USERDATA */ - &UDATA10=, /* 10TH USERDATA */ - &UDATA11=, /* 11TH USERDATA */ - &UDATA12=, /* 12TH USERDATA */ - &UDATA13=, /* 13TH USERDATA */ - &UDATA14=, /* 14TH USERDATA */ - &UDATA15=, /* 15TH USERDATA */ - &UDATA16=, /* 16TH USERDATA */ - &ULIB1=, /* 1ST USERLIB LIBRARY */ - &ULIB2=, /* 2ND USERLIB LIBRARY */ - &ULIB3=, /* 3RD USERLIB LIBRARY */ - &ULIB4=, /* 4TH USERLIB LIBRARY */ - &ULIB5=, /* 5TH USERLIB LIBRARY */ - &ULIB6=, /* 6TH USERLIB LIBRARY */ - &ULIB7=, /* 7TH USERLIB LIBRARY */ - &ULIB8=, /* 8TH USERLIB LIBRARY */ - &VPSDSN=, /* VPS PRINTER STAGED DSN */ - &WRITER=, /* OUTPUT WRITER NAME */ - &WTR=, /* OUTPUT WTR NAME (OLD) */ - &OUTDSN=&SUBNAME..&JOBNM..&JOBID..&STEPNM..&STEPDD /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* COPY FILE STAGED BY VPSSCDI */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ STEP01 COPY FROM(PNODE - DSN=&VPSDSN - DISP=SHR ) - CKPT=10M - COMPRESS EXT - TO(SNODE - DSN=&OUTDSN - DISP=(NEW,CATLG,DELETE) ) /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* DELETE FILE STAGED BY VPSSCDI */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ STEP02 IF (STEP01 = 0) THEN STEP03 RUN TASK (PGM=DMRTDYN - PARM=(C"ALLOC DSN=&VPSDSN,DISP=(OLD,DELETE)" - F'-1' - C"UNALLOC DSN=&VPSDSN")) EIF /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* EXECUTE PROC GENER TO PRINT THE OUTPUT FILE */

750 IBM Connect:Direct for z/OS: Documentation

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ STEP04 RUN TASK (PGM=DMRTSUB - PARM=("DSN=$CD.PROC(GENER),DISP=SHR", - "ADDR1 &ADDR1", - "ADDR2 &ADDR2", - "ADDR3 &ADDR3", - "ADDR4 &ADDR4", - "BLDG &BLDG", - "BURST &BURST", - "CHARS &CHARS", - "CKPTL &CKPTL", - "CKPTP &CKPTP", - "CKPTS &CKPTS", - "CLASS &CLASS", - "CMOD &CMOD", - "CMTTC &CMTTC", - "CNTL &CNTL", - "COMPACT &COMPACT", - "COPIES &COPIES", - "COPYG &COPYG", - "DATCK &DATCK", - "DEFAULT &DEFAULT", - "DEPT &DEPT", - "DEST &DEST", - "FCB &FCB", - "FLASH &FLASH", - "FLSCT &FLSCT", - "FMDEF &FMDEF", - "FORM &FORM", - "GROUPID &GROUPID", - "INDEX &INDEX", - "INPUT &OUTDSN", - "JACCT &JACCT", - "JESDS &JESDS", - "JNOTIFY &JNOTIFY", - "JOBID &JOBID", - "JOBNM &JOBNM", - "JPNAME &JPNAME", - "JPROC &JPROC", - "JROOM &JROOM", - "JSECL &JSECL", - "LINDEX &LINDEX", - "LINECT &LINECT", - "NAME &NAME", - "NOTIFY1 &NOTIFY1", - "NOTIFY2 &NOTIFY2", - "NOTIFY3 &NOTIFY3", - "NOTIFY4 &NOTIFY4", - "OPTCD &OPTCD", - "PGDEF &PGDEF", - "PIMCT &PIMCT", - "PIMSG &PIMSG", - "PRMODE &PRMODE", - "PRTY &PRTY", - "ROOM &ROOM", - "STEPDD &STEPDD", - "STEPNM &STEPNM", - "SUBNAME &SUBNAME", - "THRES &THRES", - "TITLE &TITLE", - "TRC &TRC", - "UCS &UCS", - "UDATA01 &UDATA01", - "UDATA02 &UDATA02", - "UDATA03 &UDATA03", - "UDATA04 &UDATA04", - "UDATA05 &UDATA05", - "UDATA06 &UDATA06", - "UDATA07 &UDATA07", - "UDATA08 &UDATA08", - "UDATA09 &UDATA09", - "UDATA10 &UDATA10", - "UDATA11 &UDATA11", - "UDATA12 &UDATA12", - "UDATA13 &UDATA13", - "UDATA14 &UDATA14", - "UDATA15 &UDATA15", - "UDATA16 &UDATA16", - "ULIB1 &ULIB1", - "ULIB2 &ULIB2", - "ULIB3 &ULIB3", - "ULIB4 &ULIB4", -

Chapter 6. Facilities Guide 751

"ULIB5 &ULIB5", - "ULIB6 &ULIB6", - "ULIB7 &ULIB7", - "ULIB8 &ULIB8", - "VPSDSN &VPSDSN", - "WRITER &WRITER", - "WTR &WTR", - )) SNODE EXIT

DGAPGNER JobThe following sample JCL is provided in the Install Process Library, SDGASAMP. This example is theDGAPGNER job that is submitted by DGADTSUB in STEP 04 of the preceding Process example. Because itruns on the SNODE, it shows how you can print files back into the JES spool at the remote site.

If IBM Connect:Direct Spool Transfer is enabled at the remote site, use IBM Connect:Direct to transferoutput back into the JES spool. Refer to Output to the JES Reader.

CAUTION: When you use this JCL to test your own VPS, a print loop can occur if you use thesymbolic &DEST on the same VPS system from which you submitted the print job.

//&JOBNM JOB (00000),&PGMR,PRTY=12,TIME=(10),//REGION=4096K,MSGLEVEL=(1,1),MSGCLASS=X //*//STEP01 EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DSN=&INPUT,// DISP=(OLD,DELETE,KEEP)//SYSUT2 DD SYSOUT=&CLASS,COPIES=&COPIES,DEST=&DEST//*//*ADDR1=&ADDR1//*ADDR2=&ADDR2//*ADDR3=&ADDR3//*ADDR4=&ADDR4//*BLDG=&BLDG//*BURST=&BURST//*CHARS=&CHARS//*CKPTL=&CKPTL//*CKPTP=&CKPTP//*CKPTS=&CKPTS//*CLASS=&CLASS//*CMOD=&CMOD//*CMTTC=&CMTTC//*CNTL=&CNTL//*COMPACT=&COMPACT//*COPIES=&COPIES//*COPYG=&COPYG//*DATCK=&DATCK//*DEFAULT=&DEFAULT//*DEPT=&DEPT//*DEST=&DEST//*FCB=&FCB//*FLASH=&FLASH//*FLSCT=&FLSCT//*FMDEF=&FMDEF//*FORM=&FORM//*GROUPID=&GROUPID//*HOLD=&HOLD//*INDEX=&INDEX//*INPUT=&INPUT//*JACCT=&JACCT//*JESDS=&JESDS//*JNOTIFY=&JNOTIFY//*JOBID=&JOBID//*JOBNM=&JOBNM//*JPNAME=&JPNAME//*JPROC=&JPROC//*JROOM=&JROOM//*JSECL=&JSECL//*LINDEX=&LINDEX//*LINECT=&LINECT//*NAME=&NAME//*NOTIFY1=&NOTIFY1//*NOTIFY2=&NOTIFY2//*NOTIFY3=&NOTIFY3

752 IBM Connect:Direct for z/OS: Documentation

//*NOTIFY4=&NOTIFY4//*OPTCD=&OPTCD//*PGDEF=&PGDEF//*PIMCT=&PIMCT//*PIMSG=&PIMSG//*PRMODE=&PRMODE//*PRTY=&PRTY//*ROOM=&ROOM//*STEPDD=&STEPDD//*STEPNM=&STEPNM//*SUBNAME=&SUBNAME//*THRES=&THRES//*TITLE=&TITLE//*TRC=&TRC//*UCS=&UCS//*UDATA01=&UDATA01//*UDATA02=&UDATA02//*UDATA03=&UDATA03//*UDATA04=&UDATA04//*UDATA05=&UDATA05//*UDATA06=&UDATA06//*UDATA07=&UDATA07//*UDATA08=&UDATA08//*UDATA09=&UDATA09//*UDATA10=&UDATA10//*UDATA11=&UDATA11//*UDATA12=&UDATA12//*UDATA13=&UDATA13//*UDATA14=&UDATA14//*UDATA15=&UDATA15//*UDATA16=&UDATA16//*ULIB1=&ULIB1//*ULIB2=&ULIB2//*ULIB3=&ULIB3//*ULIB4=&ULIB4//*ULIB5=&ULIB5//*ULIB6=&ULIB6//*ULIB7=&ULIB7//*ULIB8=&ULIB8//*VPSDSN=&VPSDSN//*WRITER=&WRITER//*WTR=&WTR

Symbolic DefinitionsThis topic identifies the parameters that can be passed to the Process submitted by the IBMConnect:Direct API.

Job and Jobstep ValuesThe following table lists the job and jobstep values.

Parameter Definition

&JACCT Job accounting number

&JNOTIFY NOTIFY value

&JOBID JOB ID assigned by JES

&JOBNM JOB name

&JPNAME Name of the programmer

&JPROC Procedure name

&JROOM Room number of the programmer

&JSECL Security label

&STEPDD DD name of the print file DD statement

&STEPNM Process step name

Chapter 6. Facilities Guide 753

Parameter Definition

&SUBNAME User ID of the submitter

&VPSDSN Printer staged data set

Printer File AttributesRefer to Sample Process for SYSOUT for the available parameters and associated symbolic names forprint file attributes passed by the VPSSCDI interface program. Any non-zero attributes for a printerfile cause the corresponding symbolic name to be generated on the SUBMIT command created by theIBM Connect:Direct interface program, DGASVPSA . You can reference these symbolic names in the IBMConnect:Direct Process you are submitting.

Customizing VPSSCDIVPSSCDI creates the control blocks that the IBM Connect:Direct API uses to build the SIGNON, SUBMIT,and SIGNOFF commands. Any customized validation or modification to the IBM Connect:Direct controlblocks is done at this point.

You can change printer values to reflect the destination environment. For example, you can change thedestination name to a printer name at your location.

You can perform security or usage validation by validating any fields and either continuing the processingor returning to VPS with the appropriate return code settings.

The VPS return code settings are:

• RC=00 Normal execution continues.• RC=04 Print file is requeued per VPS printer specifications.• RC=08 The printer is EDRAINed.

Note: Do not change VPS control blocks.

Transferring Data to the JES Reader or SpoolIBM Connect:Direct Spool Transfer transfers data from any IBM Connect:Direct node and routes jobcontrol language (JCL) statements to the JES reader or sends files to the JES spool.

By transferring data to the JES reader, any IBM Connect:Direct node can send z/OS JCL to the JES reader.Unlike the IBM Connect:Direct RUN JOB, z/OS JCL can be located where the Process is executing, on anymedia that IBM Connect:Direct supports.

The RUN JOB Security Exit provides a standard interface for security verification of job streams beforethey are submitted. For information on the RUN JOB Security Exit, search for Implementing Security.

IBM Connect:Direct Spool Transfer uses dynamic allocation (SVC 99) to allocate the JES spool file.You can also use the OUTADD and OUTDEL macros to allocate an OUTPUT DD reference statementdynamically.

You can print a IBM Connect:Direct banner page at the beginning of each print report. For information,search for IBM Connect:Direct Banners.

IBM Connect:Direct Spool Transfer supports the checkpoint/restart facility. IBM Connect:Direct takes acheckpoint at the top of form of the page printed after the checkpoint interval. Top of form is one of thefollowing:

• X’F1’ for ASA carriage control• X’8B’ for machine carriage control• LINECT (line count) if NOCC or the TOF=X’xx’ is specified in the Process

754 IBM Connect:Direct for z/OS: Documentation

Output to the JES ReaderUse IBM Connect:Direct syntax to transfer data to the JES reader. To initiate this transfer, specify thekeyword, READER, in the COPY TO Process statement for IBM Connect:Direct nodes where this feature isenabled.

For older releases of IBM Connect:Direct that do not support the READER keyword, use the SYSOPTSparameter OUTPUT=READER.

Examples of JCL OutputYou can adapt the following Process language examples to output JCL into the JES reader. Theseexamples are in the Sample Library, SDGAPROC.

Using the READER KeywordThe following sample Process (DGAPRDR2) uses the READER keyword to output JCL into the JES reader.

CDTORDR2 PROCESS SNODE=xx.xxx.xxxxx -STEP01 COPY FROM(PNODE - DSN=SAMPLE.JCL.LIB(JCL) - DISP=SHR - ) - TO(SNODE - READER - ) EXIT

Using the SYSOPTSThe following sample Process (DGAPRDR1) uses SYSOPTS to output JCL into the JES reader.

CDTORDR1 PROCESS SNODE=xx.xxx.xxxxx -STEP01 COPY FROM(PNODE - DSN=SAMPLE.JCL.LIB(JCL) - DISP=SHR - ) - TO(SNODE - DSN=NULLFILE - DISP=RPL - SYSOPTS="OUTPUT=READER" - ) EXIT

Output to JES Spool FilesYou can also use IBM Connect:Direct syntax to direct files transferred through IBM Connect:Direct directlyto the JES2/JES3 spool.

Copying a file into the JES spool is controlled through the SYSOUT=(....,....) keyword on the COPY TOProcess statement. Keyword and parameter definitions are in COPY TO Syntax to Support Spool Transfer.

You can specify all keywords available on the z/OS JCL SYSOUT DD statement within the IBMConnect:Direct SYSOUT=(...) Process keyword. The format of all subparameters within the IBMConnect:Direct SYSOUT=(...) follows the rules in the OS/390 JCL Reference Guide for that keyword.

Note: You cannot use SYSOUT=class because the IBM Connect:Direct feature requires that you specify allsubparameters within parentheses.

Chapter 6. Facilities Guide 755