z/OS Environments

This section provides information about installing and running Entire Net-Work in the z/OS operating system environment. It covers the following topics:


Library Requirements

The source library requires one cylinder of 3390 DASD space. The load library requires four cylinders. See the section Installation Media Information and the Software AG Product Delivery Report for additional information.

Installation Procedure

To install Entire Net-Work on a z/OS system, perform the following steps for each machine:

Step 1: Copy the Installation Media Contents

Copy the data sets from the supplied installation medium to your disk before you perform the individual installation procedure for each component to be installed.

The way you copy the data sets depends on the installation method and the medium used:

  • If you use System Maintenance Aid (SMA), refer to the copy job instructions provided in the System Maintenance Aid documentation.

  • If you are not using SMA and want to copy the data sets from CD-ROM, refer to the README.TXT file on the CD-ROM.

  • If you are not using SMA and want to copy the data sets from tape, follow the instructions in this section.

This section explains how to copy all data sets from tape to disk.

Step 1: Copy Data Set COPY.JOB from Tape to Disk

  • Modify the following sample job according to your requirements:

    //SAGTAPE JOB SAG,CLASS=1,MSGCLASS=X
    //* ---------------------------------
    //COPY EXEC PGM=IEBGENER
    //SYSUT1 DD DSN=COPY.JOB,
    // DISP=(OLD,PASS),
    // UNIT=(CASS,,DEFER),
    // VOL=(,RETAIN,SER=tape-volser),
    // LABEL=(2,SL)
    //SYSUT2 DD DSN=hilev.COPY.JOB,
    // DISP=(NEW,CATLG,DELETE),
    // UNIT=3390,VOL=SER=disk-volser,
    // SPACE=(TRK,(1,1),RLSE),
    // DCB=*.SYSUT1
    //SYSPRINT DD SYSOUT=*
    //SYSIN DD DUMMY
    //

    where:

    tape-volser is the VOLSER of the tape, for example: T12345,
    hilev is a valid high-level qualifier, and
    disk-volser is the VOLSER of the disk.

  • Execute the job to copy the data set COPY.JOB to your disk.

Step 2: Modify hilev.COPY.JOB on Your Disk

  • Modify hilev.COPY.JOB according to your requirements:

    Set EXPDT to a valid expiration date, for example, 99365.

    Set HILEV to a valid high-level qualifier, for example, USERLIB.

    Set LOCATION to a storage location, for example, STORCLAS=ABC or UNIT=3390,VOL=SER=USR123.

Step 3: Submit COPY.JOB

  • Execute hilev.COPY.JOB to copy single, multiple, or all data sets to your disk.

Step 2: Install the Adabas SVC

In systems where Adabas is not already installed, install the Adabas SVC.

Refer to the Adabas Installation Manual for specific details.

Step 3: Prepare and Install the Product License File(s)

You must install a valid license file on all mainframe platforms in which your Software AG mainframe product is installed. The license file is provided as an XML document (encoding is US-ASCII) and must remain in that format -- even on the mainframe. It must not be modified. Any modification of the license file will invalidate the digital signature and the license check will fail. If the check fails, you will not be able to run the product. In the event of a check failure, please contact your Software AG technical support representative.

License License Load Module License DDNAME
Entire Net-Work (WCP) NETLIC DDLIC
Entire Net-Work TCP/IP Option (WTC) WTCLIC DDLWTC
Entire Net-Work for zIIP AZPADLIC DDLAZPAD

The following table indicates which licenses are required when Entire-NetWork products and options are used.

  WCP License NETLIC or DDLIC WTC License WTCLIC or DDLWTC ( see note 1) AZPAD License AZPADLIC or DDLAZPAD ( see note 2)
WCP YES NO YES
WCP+WTC YES YES YES
WCA NO NO YES
WDX NO NO YES
ADATCP NO YES YES

Note 1

WTC license is checked if a TCPI or TCPX driver is used

Note 2

AZPAD license is checked if ADARUN ZIIP=YES

Note:
Thirty days before the license expires, license check failure messages are produced. Your software product will still function, but these messages warn you that it is time to obtain a new license.

In this step, you will prepare the license file (obtain it from e-mail or the installation media and store it on your z/OS system) and then install it:

Preparing the Product License File

The product license file is supplied on the individual customer installation media or separately via an e-mail attachment. Before you can install the license, you must transfer it from e-mail or the installation media and store it on a z/OS system. This section describes how to do this for a license distributed either by e-mail or on the installation media.

Start of instruction setTo prepare the license file from an e-mail attachment, complete the following steps:

  1. Transfer the license to z/OS, as described in Transferring a License File from PC to a z/OS Host Using FTP.

  2. Verify that the transferred license file is stored in an Entire Net-Work source library (with RECFM=F or FB and LRECL=80), taking care to preserve its format as ASCII.

Start of instruction setTo prepare the license file from the installation media, complete the following steps:

  • Verify that the license file is stored from the installation media into an Entire Net-Work source library (with RECFM=F or FB and LRECL=80), taking care to preserve its format as ASCII.

Installing the Product License File

Once the license file has been prepared, you can install it in one of two ways:

  • You can convert the license to a load module (NETLIC) that is then loaded by Entire Net-Work.

  • You can reference the license file in the Entire Net-Work startup job by DD statement.

This section describes both methods.

Start of instruction setTo convert the license file to a load module, complete the following steps:

  1. Review and modify sample job LICASM, as follows:

    • Change the STEPLIB DD statement to point to your license load library (MLCvrs.LOAD).

    • Change the SYSUT1 DD statement to point to the data set containing the Entire Net-Work license file you transferred to z/OS earlier.

    • Specify an appropriate user load library for the L.SYSLMOD DD statement.

      Note:
      This user load library must also be included in the STEPLIB concatenation for the Entire Net-Work.

  2. Submit sample job LICASM. This job runs the MAKE function of the LICUTIL utility to convert the license text file to an assembler source module. LICASM then links and assembles the assembler source to generate a load module called NETLIC, which is stored in the specified user load library (L.SYSLMOD DD statement). For more information about the LICUTIL utility, read Using The License Utility: LICUTIL.

  3. Update your Entire Net-Work startup jobs to reference the user load library so NETLIC will be loaded by Entire Net-Work, as described in Step 4: Customize the Entire Net-Work Startup Jobs.

Start of instruction setTo reference the license file in the Entire Net-Work startup job, complete the following steps:

  1. Make sure any previously-created NETLIC load module is inaccessible to the Entire Net-Work load library being used in your Entire Net-Work startup job. Entire Net-Work first tries to load NETLIC and, if unsuccessful, it reads from a DDLIC data set referenced in the Entire Net-Work startup job.

  2. Update your Entire Net-Work startup jobs to reference the license, as described in Step 4: Customize the Entire Net-Work Startup Jobs.

Step 4: Customize the Entire Net-Work Startup Jobs

Customize the Entire Net-Work startup jobs. The following modifications must be made:

  1. Software AG licensing requires that the modules LICMAIN and LICUTIL be loaded when Entire Net-Work starts up. These modules are distributed in the MLCvrs.LOAD library. You must either:

    • Copy LICMAIN and LICUTIL into NETWRK.vrs.LOAD; or

    • Concatenate MLCvrs.MVSLOAD with NETWRK.vrs.LOAD.

  2. Verify that the license file is correctly referenced in each startup job. Do either of the following:

    • Verify that the NETLIC load module, installed in Step 3: Prepare and Install the Product License File, is stored in a load library that is accessible to the Entire Net-Work load library. Add the user load library in which NETLIC resides to the STEPLIB concatenation of the Entire Net-Work startup job or copy the NETLIC library into NETWRK.vrs.LOAD.

    • Verify that there is no NETLIC load module accessible to the Entire Net-Work load library and that the following DD statement is included in the ADANUC job:

      //DDLIC     DD  DISP=SHR,DSN=dsn

      where dsn is the data set name of the license file loaded from the installation media (in ASCII format). Note that dsn could reference a member in a partitioned data set.

      Note:
      Entire Net-Work first tries to load NETLIC and, if unsuccessful, it reads from the DDLIC data set.

  3. Data set names for the database and libraries must be customized for your installation.

    Note:
    Be sure to include appropriate user load libraries.

Step 5: Modify the Entire Net-Work Parameters

Modify the Entire Net-Work parameters.

See the section Entire Net-Work Parameter Statements.

Step 6: Install Appropriate Line Drivers

Perform the line driver-dependent installation procedure and prepare the DRIVER and LINK statementsfor the TCPX line driver.

Step 7: Prepare Access Method-Specific Definitions

Prepare the required access method-specific definitions.

Step 8: Apply Corrective Maintenance

Apply corrective maintenance.

Refer to the Software AG Product Delivery Report to determine whether any files containing corrective maintenance (i.e., data sets named pppvrs.ZAPS) are supplied on the installation media. If so, restore the data sets using IEBCOPY, and then follow the corrective maintenance instructions in the $READMVS member.

APF Authorization

Certain line drivers require that Entire Net-Work run in supervisor state with AMODE (31). For other line drivers supervisor state is not required but does provide significant performance advantages. Using AMODE (31) allows buffers to be above the 16 MB line.

To run in supervisor state, the Entire Net-Work load library and all other load libraries in the STEPLIB concatenation must be APF-authorized. Also, ADARUN must be linked into one of these APF-authorized libraries with SETCODE AC(1). ADARUN can be linked as shown in the following example:

//LINKRUN EXEC PGM=IEWL    
//SYSPRINT   DD    SYSOUT=*
//SYSUT1     DD    UNIT=SYSDA,SPACE=(CYL,(1,1))
//ADALIB     DD    DSN=adabas.loadlib,DISP=SHR
//SYSLMOD    DD    DSN=network.loadlib,DISP=SHR   <=== APF-AUTHORIZED
//SYSLIN     DD    *
 MODE     AMODE(31),RMODE(24)
 INCLUDE  ADALIB(ADARUN)
 SETCODE  AC(1)
 NAME  ADARUN(R)

Execution Job Example

The following is an example of an Entire Net-Work z/OS execution job. (See the sample source member JCLNET in the source library for an alternate example.) More JCL may be needed, depending on the node configuration (types of line drivers, number of links, and so on). For more information, refer to the Simple Connection Line Driver documentation.

//*-------------------------------------------------------------* 
//*                     SAMPLE   JCL                            * 
//*-------------------------------------------------------------* 
//STEP1 EXEC PGM=ADARUN,REGION=2048K,TIME=1440       <--- see Note 1               
//STEPLIB  DD DISP=SHR,DSN=WCAvrs.LOAD,DCB=BLKSIZE=32760         
//         DD DSN=WAL.vrs.LOAD,DISP=SHR              <--- see Note 2 
//DDLIC DD DSN=NETWRK.vrs.LICENSE,DCB=(RECFM=FB,LRECL=80,BLKSIZE=80*n) <---See Note 3
//DDPRINT  DD SYSOUT=*                               <--- see Note 4            
//NETPRNT  DD DISP=SHR,DSN=WCAvrs.NETPRNT            <--- see Note 5             
//MPMDUMP  DD SYSOUT=*                               <--- see Note 6            
//SYSUDUMP DD SYSOUT=*                                            
//DDCARD   DD DISP=SHR,DSN=WCAvrs.SRCE(ADARUN)       <--- see Note 7             
//         DD DISP=SHR,DSN=WCAvrs.SRCE(FORCEN)                    
//DDKARTE  DD DISP=SHR,DSN=WCAvrs.SRCE(NWKWCA)      <--- see Note 8             

Here is a sample of the contents of library member NWKWCA, listing the Entire Net-Work parameter statements for this Entire Net-Work Administration execution:

*                    NODE STATEMENT                                  *  
*--------------------------------------------------------------------*  
NODE NODENAME CQTIMER=60,                -                              
              LOG=NO,                    -                              
              MAXPATH=10,                -                              
              NTRACE=1000,               -                              
              REPLYTIM=60,               -                              
              TIMER=20                                                  
*                                                                       
*---------------------------------------------------------------------- 
*                                                                     * 
*     DRIVER TCPX                                                     * 
*                                                                     * 
*---------------------------------------------------------------------- 
DRIVER  TCPX     API=OES,                                      -        
                 SERVERID=1996,                                -        
                 USERID=CCCC                                            
*---------------------------------------------------------------------- 
*                   E N D   O F   P A R A M E T E R S ..              * 
*----------------------------------------------------------------------

Notes:

  1. The region size required varies with the number and type of links, as well as other operating parameters.
  2. The second data set of the STEPLIB concatenation should always be your most current Adabas load library (Entire Net-Work Administration Version 6.3 requires Adabas mainframe Version 8 or above) or the Adabas limited library (WAL), as provided on the Entire Net-Work installation media, unless you have been specifically instructed otherwise by Software AG.
  3. DDLIC contains the binary license key. It is only required if a license module is not present in the STEPLIB.
  4. All Entire Net-Work Administration print output is written to DDPRINT.
  5. All diagnostic information from tracing, logging, and abends is written to the NETPRNT file if it is open (otherwise it is written to the DDPRINT file). NETPRNT can be allocated to a large data set that can be copied when closed. The data set should be created with the DCB attributes RECFM=FBA and LRECL=121. To do this, allocate the file SHR. This causes the data set to be erased at the time the file is opened. Be aware that the diagnostic information is very large and will fill a data set quickly. When this happens, the file is closed and all additional output is sent to DDPRINT. This diagnostic information is created by Entire Net-Work and does not include the operating system dump information written to SYSUDUMP.
  6. If MPMDUMP is defined, a snap dump is produced during any abnormal termination. In some error situations, the MPMDUMP dump may contain more pertinent information than the SYSUDUMP dump.
  7. DDCARD contains the ADARUN parameters or it identifies the library member in which the ADARUN parameters are defined. These ADARUN parameters define the interregion communications parameters for Entire Net-Work. See the section ADARUN Parameters.
  8. DDKARTE contains Entire Net-Work parameter statements or identifies the library member in which the parameter statements are defined. These parameter statements describe the local environment and the network connections for this node. See the section Entire Net-Work Parameter Statements.

Entire Net-Work can also be installed as a started task; no special considerations apply.

Entire Net-Work uses cross-memory services similar to Adabas in z/OS systems. As a result, z/OS removes the address space and initiator when Entire Net-Work terminates operation. This is normal and should not be regarded as an error.

Entering Operator Commands

During execution, a number of operator commands may be issued to Entire Net-Work to display or modify the system status. These commands are essentially identical for all operating environments. See the section Entire Net-Work Operator Commands.

The way in which operator commands are presented to Entire Net-Work depends on the operating system and is identical to the way operator commands are presented to Adabas.

In z/OS environments, the following operator commands are used:

MODIFY (abbreviation = F)
STOP (abbreviation = P)

The STOP command serves as an alternative to the NETEND command and terminates Entire Net-Work. Its synonyms are described as part of the following example.

Example:

Entering the following long form MODIFY command results in the following status displays (assuming that NETWK is the name of the started task running Entire Net-Work):

MODIFY NETWK,D STATS
NET0090I: BUFFER USAGE STATISTICS:
NET0091I: ASYNCH. BUFFERS:     000016 (= 24.2 %) OF 000064 K USED
NET0091I: LONG TERM BUFFERS:   000000 (=  0.4 %) OF 000064 K USED
NET0091I: SHORT TERM BUFFERS:  000000 (=  6.1 %) OF 001025 K USED
NET0091I: ATTACHED BUFFERS:    000000 (= 11.9 %) OF 000080 K USED
NET0091I: REQUEST QUEUE:       000000 (=  6.0 %) OF 000050 RQES USED
NET0087I: 0000010847 REQUESTS FROM LOCAL RQ

The following two commands are equivalent ways to terminate the Entire Net-Work session:

F NETWK,NETEND
P NETWK

Installing Entire Net-Work for zIIP

This section is organized as follows:

Prerequisites

Prerequisite for Entire Net-Work for zIIP is a z13 mainframe with one or more zIIP engines, running z/OS 2.1 or above. Entire Net-Work for zIIP needs one zIIP engine to perform effectively.

To run with zIIP support enabled (e.g., ADARUN parameter ZIIP=YES), the Entire Net-Work kernel must be APF-authorized.

Libraries

The support of Entire Net-Work for zIIP requires the following Adabas for zIIP library:

  • AZP835.LOAD

Entire Net-Work for zIIP requires that the Adabas SVC contains support for zIIP:

  • Module ADASVC from the AZP835.LOAD library supports Adabas Version 8.3 databases.

  • If the Adabas SVC used for running Entire Net-Work for zIIP is also to be used for Adabas Version 8.4 databases, use a Version 8.4 ADASVC with the following maintenance applied:

    • ADASVC from ADA842.LOAD: Apply zap AO842003.

    • ADASVC from ADA841.LOAD: Apply zap AO841008.

For the Entire Net-Work for zIIP license check (see License below), use the Mainframe License Check version 1.3.3 from the following library:

  • MLC133.LOAD

License

Entire Net-Work for zIIP requires an associated license file (AZPAD) in addition to the Entire Net-Work license file. This is the same license file that is used for an Adabas nucleus. If the AZPAD license is not provided or erroneous, the kernel will run with Entire Net-Work for zIIP deactivated (ZIIP=NO).

The AZPAD license can be transferred to the mainframe in the same way as the Entire Net-Work license. The license can be made available to the nucleus as a load module with the name AZPADLIC. This is similar to the handling of the Entire Net-Work license load module NETLIC described in Software AG Mainframe Product Licensing. Alternatively, the license file can be referred to by a ‘DDLAZPAD’ DD statement in the nucleus job/started task. This is a fallback in case the AZPADLIC module cannot be loaded.

Installation Steps

Start of instruction setPerform the following steps to install Entire Net-Work for zIIP

  1. Add the Adabas for zIIP load library to your Entire Net-Work startup jobs (see also Libraries, above).

  2. Set up the required license modules or datasets (see License above).

  3. Install the Adabas SVC that contains zIIP support.

    • Module ADASVC from the AZP835.LOAD library supports Adabas Version 8.3 databases.

    • Module ADASVC from the ADA842.LOAD library, with zap AO842003 applied, supports Adabas Version 8.4 and Adabas Version 8.3 databases, including Adabas for zIIP.

      Alternatively, use module ADASVC from the ADA841.LOAD library, with zap AO841008 applied.

  4. Specify ADARUN parameter ZIIP=YES.

  5. Start the Entire Net-Work kernel.

Enabling Direct TCP/IP Access (ADATCP) to Your Adabas Nucleus

This section covers the following topics:

Connection Through a Direct TCP/IP Link

The database must be UES-enabled for TCP/IP access.

A TCP/IP link uses Entire Net-Work modules. These modules communicate using the standard ADALNK module. Translation tables can be customized and reassembled and then made available in the Adabas STEPLIB. The Adabas ADALNK module is supplied with the LNKUES module and the default translation tables ASC2EBC and EBC2ASC.

The Entire Net-Work WCPvrs and WTCvrs libraries must be defined in the STEPLIB concatenation. The sample startup job for a UES-enabled nucleus with TCP/IP support is provided in member ADANUCT. For more information, read JCL Required for UES and TCP/IP Support (z/OS), in the Adabas z/OS Installation Guide.

UES-enabled databases are connected directly through TCP/IP using the Adabas standard batch or TSO link routine ADALNK. The sample job stream to link the ADALNK module with your modified translation tables is ALNKUES.

In addition, the ADALNK module must have the correct SVC set in the LNKGBLS module.

Step 1: Assemble the LNKGBLS module with the correct SVC

The LNKGBLS is delivered in the ADAvrs.SRCE library and its assemble job is in ADAvrs.JOBS(ASMGBLS). Use the job as a guide to assemble the LNKGBLS module with the correct SVC.

Step 2: Assemble the Two Translation Tables into the Adabas Load Library (SMA Job Number I056)

Assemble the ASCII to EBCDIC and EBCDIC to ASCII translation tables, either default or customized. Use job ALNKUES in the ADAvrs.JOBS library as a guide for customizing site-specific JCL.

Step 3: Link the Translation Tables and LNKUES into ADALNK

It is now necessary to (re)link ADALNK with LNKUES and your customized and reassembled translation tables.

Link the ADALNK, ASC2EBC, EBC2ASC, LNKUES, and other user exit modules into a final ADALNK module that is UES-enabled. Place this load module into a "USER.LOAD" library. Sample job LNKLNK8 is provided as a guide in the ADAvrs.JOBS library.

Step 4: Make ADALNK Available to the Adabas Nucleus

The (re)linked ADALNK must be made available to the Adabas nucleus.

If you are calling Adabas Version 8 directly through a TCP/IP link and the correct ADALNK is not available to the Adabas nucleus or the SVC has not been set correctly, Adabas produces unexpected results, such as response code 148 (ADARSP148) and empty buffers.

Activating the TCP/IP Link

Start of instruction setTo activate a direct TCP/IP link to the Adabas nucleus:

  1. Set the ADARUN parameter TCPIP=YES.

  2. Specify a universal resource locator (URL) in the ADARUN parameter TCPURL.

Specifying a URL

The URL is a 20-byte address that conforms to the RFC specification for URLs.

You can specify the URL required to activate the direct TCP/IP link in the ADARUN parameter TCPURL. For more information, read TCPURL Parameter: TCP/IP Universal Resource Locator, in the Adabas Operations Manual.