Configuring TCPaccess to connect to OMVS / USS

Document ID : KB000052843
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

TCPaccess can run with or without connecting to OMVS. Most current applications using sockets require that the stack supply OMVS connectivity. This document outlines how to enable that connectivity.

Solution:

Here are the instructions regarding setup of TCPaccess 6.0 to run with OMVS.

  1. This document consolidates information found in several TCPaccess manuals.

    Chapter 4 in the Planning Guide gives you the general information on configuring TCPaccess for Open Edition, which mainly involves setting up the BPXPRMxx member.

    More detailed information can be found in Chapter 7 of the Customization guide and Chapter 7 in the C Sockets Programmers Reference.

  2. The PFSLOAD needs to be in OMVS startup, and needs to be high enough up that OMVS gets our T010PFSA module for Open Edition. It must also be APF authorized.

    We do not recommend placing the PFSLOAD in the LINKLIST, as no other app uses it, and any changes must be implemented using IPL anyway.

  3. The TCPaccess address space must be defined to your security package with a valid Open Edition MVS security segment.
    As a transport provider it also requires superuser privileges in USS. To facilitate this, define the TCPaccess started task UID as UID=0, or as a trusted environment in the RACF started class profile for the TCPaccess system address space.
    To define the OMVS segment for the TCPaccess stack user ID tcpaccess_user enter the following commands:

  • For CA ACF2 for z/OS systems, enter the following commands:
      SET PROFILE(USER) DIV(OMVS) 
      INSERT tcpaccess_user UID(0) HOME(/) PROGRAM(/bin/sh)
  • For CA Top Secret for z/OS systems, enter the following commands:
      TSS ADD(tcpaccess_user) HOME(/) OMVSPGM(/bin/sh) UID(0) 
      GROUP(OMVSGRP)
  • For RACF systems, enter the following command:
      ALU tcpaccess_user OMVS(UID(0) HOME(/) PROGRAM(/bin/sh))

Note: The OMVS segment must contain the following:

  • A home directory (HOME)
  • A login shell (PROGRAM or OMVSPGM)
    In the above examples we are using the USS default values.
    Please change to match your environment if required.

    Once you have completed this process, you can confirm the contents of the OMVS segment using the following commands:

    • For CA ACF2 for z/OS systems, enter the following commands:
          SET PROFILE(USER) DIV(OMVS) 
          LIST tcpaccess_user 
    • For CA Top Secret for z/OS systems, enter the following command:
          TSS LIS(tcpaccess_user) DATA(ALL)
    • For RACF systems, enter the following command:
          LISTUSER tcpaccess_user OMVS NORACF
      • The TCPaccess DNR tables are not used for OE/USS processing; all OE/USS DNS calls go through the IBM RESOLVER.

      • If you are running multiple stacks on one LPAR, a SYSUNIQ statement needs be added to the TCPCFGxx to allow for correct hostname resolution of the stack. Syntax is:
      • SYSUNIQ SYSNAME(hostname)

        Where hostname specifies a 1 to 64 character value value (without any dotted notation) that uniquely identifies the TCPIP stack for USS / OE functions. Details are available in the Customization Guide Chapter 3, section on defining Stack Unique Settings.

        Please be aware that PTF TP10072 (SP3) adds case sensitivity to this statement, so please Ensure that the hostname value is in uppercase unless lowercase is specifically desired.

      • If you are running an OE application that uses ports in the well known range (0-1024), fix TP09439 (SP1) should be applied.
        Otherwise the application requires SUPERUSER authority to be able to bind to those ports.

      • SYSTCPD DD should point to an override to TCPIP.DATA with an NSINTERADDR statement pointing to one of your root nameservers. This DD stmt needs to be in the application that makes the OE socket calls.

        Information regarding setup of this and other related datasets is contained in the SAMP(TCPDATA) included with the TCPaccess 6.0 product. The other datasets m entioned in the SAMP lib are not needed if you are on a fairly current level of OS/390.

        For simplicity an example is included at the end of this document.

      • ENTRYPOINT (T010PFSA) is needed for asynchronous sockets in the BPXPRM.

        This message must appear in the TCPaccess joblog in order for Open Edition to work:

        T01OE004I Connection to OpenEdition established -- provider JOBNAME

        If the T01OE004I message does not appear, you are not connected to Open Edition.

        Here is a sample BPXPRMxx setup if you are running a single stack on an LPAR.
      • MAXPROCSYS(200) 
        MAXPROCUSER(25) 
        MAXUIDS(200) 
        MAXFILEPROC(1024) 
        MAXPTYS(256) 
        CTRACE(CTIBPX00) 
        STEPLIBLIST('/SYSTEM/STEPLIB') 
        FILESYSTYPE TYPE(HFS) 
        ENTRYPOINT(GFUAINIT) 
         
        FILESYSTYPE TYPE(SNSTCP60) <=======We recommend that this parameter match the 
                                           STC name of your TCPaccess stack 
        ENTRYPOINT(T010PFSA) <=======Entrypoint for 6.0 stack, supports asynch sockets
        PARM('SYSID(ACSS)')
        NETWORK DOMAINNAME(AF_INET) 
        DOMAINNUMBER(2) 
        MAXSOCKETS(4096) 
        TYPE(SNSTCP60) <========Matches FILESYSTYPE TYPE parameter
         
        ROOT FILESYSTEM('OMVS.ROOT522') TYPE(HFS) MODE(RDWR) 
        MOUNT FILESYSTEM('DEV.OMVS.HFS') MOUNTPOINT('/u') 
        TYPE(HFS) MODE(RDWR) MAXTHREADTASKS(50)

      Here is a sample BPXPRM if you are setting up multiple stacks on 1 LPAR that use the same install libraries, or, as in this case, you are setting up an IBM and a TCPaccess stack.

      Open Edition (Unix Systems Services) should be set up to connect up to all stacks.

      Do this by editing the BPXPRMxx member in the SYS1.PARMLIB. Stacks should be defined as SUBFILESYSTYPEs under CINET.

      Entrypoint for all 6.0 TCPaccess stacks is T010PFSA. Please be aware that ports used by Open Edition cannot be shared between stacks with this setup.

      Again, more information regarding Open Edition can be found in the Chapter 4 of the TCPaccess Planning Guide and Chapter 7 of the C Sockets Programmers Reference.

      Sample BPXPRM:
      MAXPROCSYS(200) 
      MAXPROCUSER(25) 
      MAXUIDS(200) 
      MAXFILEPROC(1024) 
      MAXTHREADTASKS(50) 
      MAXPTYS(256) 
      CTRACE(CTIBPX00) 
      STEPLIBLIST('/etc/steplib') 
      FILESYSTYPE TYPE(HFS) 
      ENTRYPOINT(GFUAINIT) 
       
      FILESYSTYPE TYPE(CINET) 
      ENTRYPOINT(BPXTCINT)
       
      SUBFILESYSTYPE NAME(SNSTCP60) ) <==== This parameter must match 
                                            the STC name of your TCPaccess stack 
      DEFAULT
      PARM('SYSID(ACSS)')
      TYPE(CINET)
      ENTRYPOINT(T010PFSA
      SUBFILESYSTYPE NAME(TCPIP)
      TYPE(CINET)
      ENTRYPOINT(EZBPFINI)
      NETWORK DOMAINNAME(AF_INET) 
      DOMAINNUMBER(2) 
      INADDRANYPORT(20000) 
      INADDRANYCOUNT(1000) 
      MAXSOCKETS(60000) 
      TYPE(CINET) 
       
      ROOT FILESYSTEM('OMVS.ROOT522') TYPE(HFS) MODE(RDWR) 
      MOUNT FILESYSTEM('DEV.OMVS.HFS') MOUNTPOINT('/u') 
      TYPE(HFS) MODE(RDWR) MAXTHREADTASKS(50)
      Here is a sample setup for the hlq.TCPIP.DATA dataset that is pointed to using a SYSTCPD DD statement. The syntax is also correct, so this can be cut and pasted to a mainframe FB 80 dataset. This can be either a sequential dataset or PDS.

      This sample complements the example in the SAMP(TCPDATA) member, containing the statements needed to run OE, HPNS and IUCV applications. Please change the values to match your environment.
      ;started task name of your TCPaccess stack
      TCPIPJOBNAME SNSTCP60
      ;
      ;name of your domain
      DOMAINORIGIN CA.COM 
      ;
      ;IP address of domain nameserver, normally matches DNRNSCxx
      ;use multiple statements if you use more than one nameserver
      ;omit if you run the stack in LOCAL mode.
      NSINTERADDR 10.253.27.133
      ;
      ;VMCFNAME if you are running IUCV, default is VMCF
      ;not needed if you are not running IUCV 
      ;if running IBM?s VMCF use a non-default value to avoid conflicts
      VMCFNAME VMCF
      ;
      ;TCPaccess subsystem-ID, default is ACSS
      DNRSSID ACSS
      ;
      ;hlq for set of 5 MVS datasets
      ;you may not have these set up. Set to the same hlq as this dataset.
      DATASETPREFIX SNSTCP
      ;
      ;first qualifier of the fully qualified host name of the stack
      ;HOSTNAME + DOMAINORIGIN = fully qualified hostname.
      HOSTNAME FRED 
      ;
      ;the following values are the defaults used in this dataset.
      ;they may be coded or omitted.
      NSPORTADDR 53
      RESOLVEVIA UDP
      RESOLVERTIMEOUT 30
      RESOLVERUDPRETRIES 1
      ;
      ;
      ;
      ;The following are additional parameters that you may want to use for 
      ;OE/USS applications. Please be aware that these are NOT used by 
      ;TCPaccess, but by the IBM RESOLVER. Thus they will be ignored by 
      ;TCPaccess HPNS or IUCV applications where name resolution is done 
      ;through the TCPaccess DNR tables, thus they are all commented out in 
      ;this example.
      ;For more information regarding use of these parameters please consult 
      ;the appropriate IBM manuals.
      ;
      ;The SEARCH parameter is used instead of DOMAINORIGIN if your 
      ;environment has multiple domain names that may need to be searched 
      ;through. Domain names are delimited by a space.
      ;Be sure to comment out DOMAINORIGIN if using this.
      ;
      ;EXAMPLE:
      ;SEARCH MYCA.COM YOURCA.COM CA.COM
      ;
      ;
      ;The LOOKUP parameter denotes whether or not you want to use local DNS 
      ;tables before accessing the nameserver.
      ;
      ;EXAMPLE:
      ;LOOKUP LOCAL DNS
      ;
      ;The COMMONSEARCH / NOCOMMONSEARCH overrides what is defined in 
      ;RESOLVER.
      ;
      ;EXAMPLE:
      ;COMMONSEARCH