The Mainframe Gateway for OpenVMS (MGO) can replace any other SNA Gateway for used with OpenVMS application programs. This includes CT, ST, SNA Access and SNA Access Server Gateway.

The Mainframe Gateway for OpenVMS is a software-only solution. No new or additional hardware is required. After the software is installed and configured on the IBM mainframe, the Mainframe Gateway for OpenVMS appears to the OpenVMS systems as another HP SNA gateway.

OpenVMS Application Architecture using HP SNA Gateway

OpenVMS Application Architecture using

Mainframe Gateway for OpenVMS

1.1 Prerequisites

The Mainframe Gateway for OpenVMS (MGO) may be used in place of other (HP) SNA Gateways when:

• OpenVMS systems has a TCP software stack installed and operational

• IBM mainframe has TCP software stack installed and operational

• Both OpenVMS and mainframe systems are connected by a network that supports TCP communications between the two systems

• The IBM mainframe operating system is OS/390 V2.R10 or any version of z/OS that is currently supported by IBM

No new software need be installed on the OpenVMS systems. All current versions of OpenVMS SNA products already support both DECnet and TCP communications.

No changes are needed in OpenVMS application programs.

Configuration changes are required on the OpenVMS systems. If the OpenVMS system initiates contact with the mainframe, then the gateway name must be changed to the IP name (or dotted decimal address) of the IBM mainframe. If OpenVMS system passively awaits contact from the mainframe, the 'listen' information needs to specify a TCP port number.

The Mainframe Gateway for OpenVMS must be installed on the IBM mainframe. This manual contains detailed information on the installation procedure in chapters 2 and 3. Chapters 4 and 5 describe the configuration process.

No changes are needed in IBM mainframe application programs.

1.2 Data Access Inc

Data Access Inc, and its sister company Systems & Communications Sciences (S&CSI), offer a variety of IBM mainframe related software products and services. DAI and S&CSI have worked closely with HP (and Compaq and Digital) since 1980.

In 1986, Data Access developed the mainframe portion of Digital's Data Transfer Facility for VMS product. Digital, Compaq, and HP have continued to distribute this product under a royalty agreement with DAI. Throughout this period, DAI has provided 7x24 engineering level support to the DEC/Compaq/HP support organizations.

The Mainframe Gateway for OpenVMS was developed with the knowledge and cooperation of HP. The product is designed to work with HP products, but it is the sole property of Data Access Incorporated.

For more information, please see our web site www.data-access-inc.com or send mail to info@data-access-inc.com.

1.3 Who Should Use This Book

This publication is intended for people responsible for installing, configuring, and using the Mainframe Based Gateway. The following topics are covered:

• Installation of the software on the mainframe

• Configuration of the software

• Log file messages

• Mainframe operator console commands and responses

1.4 How This Book Is Organized

Chapters two and three describe installation of the Mainframe Based Gateway software and the installation verification procedure. These chapters are intended for use by IBM mainframe system programmers. The reader is expected to have experience in installing software products on IBM mainframes using SMP/E. Some experience with mainframe TCP/IP configuration issues is also assumed. Knowledge of VTAM, OpenVMS, or OpenVMS SNA products is not required.

Chapters four and five describe the mainframe configuration process. Chapter four covers VTAM configuration. Chapter five covers development of a MGO configuration file. Since some VTAM parameters must match MGO configuration parameters, these chapters are intended to be used together.

Chapter six documents log file messages.

Chapter seven describes the console commands and responses.

Chapter eight contains sample configuration information and job control language.

1.5 Associated Documents

While installing and configuring the software, it may be helpful to refer to these IBM manuals:

• SNA Resource Definition Reference (SC31-8778)

• IP Configuration Reference (SC31-8776)

• SMP/E for z/OS and OS/390 User’s Guide (SA22-7773)

1.6 Conventions

This manual uses the following conventions:

1.7 Disclaimers

The following are trademarks or registered trademarks of Hewlett Packard:

HP, Compaq, Digital, DEC, DECnet, VAX, Alpha, and OpenVMS.

The following are trademarks or registered trademarks of International Business Machines:

IBM, OS/390, z/OS, and VTAM.

All other trademarks and registered trademarks are the property of their respective holders.

1.8 Edition Notice

This edition applies to Version 1.1 of Mainframe Gateway for OpenVMS and all subsequent releases and modifications unless otherwise noted.

DAI welcomes your comments. Please send your comments to the address shown in the next section.

By sending information to DAI, DAI is granted nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to the sender.

© Copyright Data Access Incorporated (a New Hampshire, USA Corporation) 2004. All rights reserved.

1.9 Contact Information

E-mail: info@data-access-inc.com for general, sales, or account information

support@data-access-inc.com for technical information or assistance

Web site: www.data-access-inc.com

Telephone: 603-491-6270

Fax: 603-878-1929

Mail: Data Access Inc.

244 Poor Farm Rd

New Ipswich, NH 03071-3922

2. Introduction

This chapter provides an overview of the installation process for the Mainframe Gateway for OpenVMS (MGO).

2.1 Required Software for OS/390 or z/OS Systems

The Mainframe Gateway for OpenVMS software requires the following system software:

• OS/390 V2R10 or z/OS V1R4 (or later) running in 31 or 64 bit mode

• System Modification Program/Extended (SMP/E)

• Communications Server (VTAM and TCPIP)

2.2 Disk Space Requirements

Approximately 400 tracks are required.

2.3 Installation Overview

The installation process consists of these steps:

• Copy the binary ‘Install Kit’ to the IBM mainframe

• Unpack the ‘Install Kit’ using the TSO RECEIVE command

• Run a job in the unpacked version of the 'Install Kit' to create an installation library

• Customize jobs in the installation library by adding site specific information

• Create the SMP/E related files and VSAM clusters

• Initialize the MGO SMP/E environment

• Perform SMP/E RECEIVE, APPLY, and ACCEPT processing

• Run the Installation Verification Procedure

Chapter 3 contains detailed instructions for performing each step.

2.4 License

The Mainframe Gateway for OpenVMS is protected by a License. A license is included in installation kit. For information on updated licenses, please contact the Data Access.

A license IS NOT REQUIRED to install the MGO software or to execute the Installation Verification Procedure.

A license IS REQUIRED to use the MGO software to allow OpenVMS based applications to communicate with mainframe base application programs.

2.5 Post Installation Activities

After installation, configuration information needs to be created or changed to make use of the MGO. Three distinct types of configuration information must be created or modified:

• SNA (or VTAM) Application Major Node definitions

• MGO configuration file

• OpenVMS configuration changes

The SNA (or VTAM) Application Major Nodes contain parameter for each SNA logical unit that the MGO supports. Chapter four contains information on defining information for Application Major Nodes.

The MGO configuration file contains parameter values used to communicate with the mainframe TCPIP and SNA software. Chapter 5 contains information on developing the configuration file.

The OpenVMS configuration changes are usually limited to changing the Gateway name (or IP address) to a value for the IBM mainframe.

If a firewall or a SAF security package is used to restrict TCPIP operations, the firewall or security package rules may need to be modified.

Most OpenVMS access routine products initiate TCPIP connections to the MGO product. Examples include the SNA 3270 Terminal Emulator and the SNA RJE product. The firewall must allow TCP connections:

• From the OpenVMS systems using any TCP port number

• To the mainframe at TCP port number 108 (or other value specified on the TCP-PORT statement in the MGO configuration file)

• On all mainframe TCP interface addresses (or specific IP address specified on the TCP-INTERFACE statement in the MGO configuration file).

Instead of initiating TCPIP connections, some OpenVMS access routine products expect to receive TCPIP connections. The SNA 3270 Access Services product is an example. To use these products, the firewall must allow TCP connections:

• From the IBM mainframe using any mainframe TCP port number (unless a port number range is specified in the MGO configuration file on the LU-ADDRESS statement)

• From any IBM mainframe TCP interface (unless a specific interface is specified by the TCP-INTEFACE statement in the MGO configuration file)

• To the OpenVMS system using the IP addresses and TCP port numbers specified on the LU-ADDRESS statements in the MGO configuration file.

3. Software Installation Procedure

This chapter describes the installation process for the Mainframe Gateway for OpenVMS (MGO). The reader is assumed to be familiar with common IBM mainframe tools and facilities including SMP/E, TSO, FTP, and operator console commands.

3.1 Move Installation Material to the Mainframe

The MGO software is distributed in a variety of ways: email attachment, FTP, or a CD.

Regardless of the distribution method, the software consists of a single SMP/E function with a Function Modification Identifier of MGO1100.

The instructions in this section are assume that a Window PC is being used as a work station and that the PC can access the IBM mainframe via FTP.

If you have a CD containing DAI software, the 'install.kit' file is in the '/software' directory.

If you received the software as an email attachment, unzip the attached file.

Otherwise, follow the instructions to download the 'install.kit' file from the FTP site or the wet site.

Copy the 'install.kit' file to the mainframe. The mainframe file will be used as input by the TSO RECEIVE command, so the mainframe file must consist of 80 byte fixed length records.

Use any convenient method such as FTP, PC File Transfer (IND$FILE), or Data Transfer Facility. The example below illustrates the use of FTP to allocate an appropriate mainframe file and do the file transfer. Be sure to use a ‘binary’ or ‘image’ copy mode.

Example: Sample FTP session to transfer ‘install.kit’ to z/OS Mainframe

ftp your.mainframe.name

220-Connection message from mainframe.

User: user01

331 Send password please.

Password: mypasswd

230 USER01 is logged on. Working directory is “USER01.”

ftp>

ftp> quote site lrecl=80

200 SITE command was accepted

ftp> quote site blksize=6160

200 SITE command was accepted

ftp> quote site recfm=fb

200 SITE command was accepted

ftp> bin

200 Representation type is Image.

ftp> put install.kit

ftp> bye

Depending on your FTP client type, you may have to use ‘locsite’, ‘literal site’, or ‘quote site’ in place of ‘site’.

Once the data has been copied to the mainframe, use the ‘TSO RECEIVE’ to unpack the install kit into a new partitioned data set.

Example:

tso receive indsn(‘USER01.INSTALL.KIT’)

INMR901I Dataset MGO.INSTALL.KIT from DAI on NODENAME

INMR906A Enter restore parameters or 'DELETE' or 'END' +

da(‘USER01.INSTALL.KITLIB’)

…

If the installation kit library contains member PROGDIR, please read it. If present, it may contain installation notes or instructions that are more up to date than this manual.

3.2 Create the Sample JOBS Library

To create a library of sample SMP/E jobs, edit and execute member $UNLOAD in the install kit library. The edits required are:

• JOB card information

• Data set name on the SYSIN DD card. This should be the name of the install kit library (USER01.INSTALL.KITLIB).

• Data set name on the SYSUT2 DD card. This should be the name of the new SMP/E sample job library (USER01.INSTALL.JOBS).

Example: Edited Version of $UNLOAD from the install kit library:

//MYJOB JOB ,MYNAME,CLASS=A,MSGCLASS=X

//RESORE EXEC PGM=IEBUPDTE,PARM=NEW

//SYSPRINT DD SYSOUT=*

//SYSUT2 DD DSN=USER01.INSTALL.JOBS,DISP=(,CATLG,DELTE),

// UNIT=SYSDA,DDB=(LRECL=80,BLKSIZE=7200,RECFM=FB),

// SPACE=(7200,(150.15,10))

//SYSIN DD DSN=USER01.INSTALL.KITLIB($FILE11),DISP=SHR

//

3.3 Tailor the Installation Jobs Material

The installation jobs library contains sample jobs that can be modified and then submitted to install MGO using SMP/E. The required modifications are

• JOB card information

• High level qualifier names for various libraries

• High level qualifier for new SMP/E environment

• Disk drive UNIT types and volume serial numbers

A REXX script, MGOINIT, can used to perform the modifications. Execute the script and provide answers to the questions it asks.

Example: Sample execution of MGOINIT script:

-----------------------------MGOINIT---------------------------------

Do you need to customize the installation JCL? (Y|N) y

------------------------JCL UPDATE PROCESS--------------------------

The fully qualified name of the install dataset is USER01.INSTALL.JOBS

If you are running MGOINIT the first time, then there are no previous values are displayed in the parenthesis. Previous values will be displayed in the parenthesis during subsequent executions of MGOINIT.

If you hit enter without specifying a value then the value in parenthesis will be used. If you type in HX at any prompt you will terminate this REXX exec

You can optionally specify two lines for the jobcard statement

Enter the first line of the jobcard ()?

//MGO0001 JOB ,MYNAME,CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)

Enter the second line of the jobcard (this is optional) ()?

The second line of the jobcard is

Enter the high level qualifier for MGO target libraries ()?

USER01.MGO1000.TLIB

Enter the high level qualifier for MGO DLIBs ()?

USER01.MGO1100.DLIB

Enter the volume serial number for MGO target libraries ()?

TSOVL1

Enter the volume serial number for MGO DLIBs ()

TSOVL1

Enter the generic unit name for MGO target libraries (3390)

SYSDA

Enter the generic unit name for MGO DLIBs (3390)

SYSDA

Enter the high level qualifier of all SMP/E work files in the MGO global, target, and DLIB zones ()

USER01.MGO1100.SMPE

Enter the high level qualifier of the MGO global CSI dataset used for

controlling the MGO target and DLIB zones ()

USER01.MGO1100.SMPECSI

Enter the high level qualifier of the MGO target zone CSI dataset ()

TYREE.MGO1100.SMPECSI2

Enter the high level qualifier of the MGO DLIB CSI dataset () USER01.MGO1100.SMPECSI3

The high level qualifier of the MGO DLIB CSI dataset is

USER01.MGO1100.SMPECSI3

Enter the high level qualifier used by SMP/E to create SMP/E temporary libraries during MGO RECEIVE processing ()

USER01.MGO1100.SMPE4

Enter the volume serial number for all SMP/E work files in the MGO global, target, and DLIB zones ()

TSOVL1

Enter the volume serial number used to allocate the MGO Global CSI dataset ()

TSOVl1

Enter the volume serial number used to allocate the MGO target CSI dataset()

TSOVL1

Enter the volume serial number used to allocate the MGO DLIB CSI dataset ()

TSOVL1

Enter the generic unit name for all SMP/E work files in the MGO global,

target, and DLIB zones (3390)

SYSDA

Enter the generic unit name used to allocate the MGO Global CSI dataset (3390)

SYSDA

Enter generic unit name used to allocate the MGO target CSI dataset (3390)

SYSDA

Enter generic unit name used to allocate the MGO DLIB CSI dataset (3390)

SYSDA

Enter the library into which you downloaded the install package ()?

USERO1.INSTALL.KITLIB

Enter the name of the library which contains the SMPMGO procedure ()?

USER01.INSTALL.JOBS

If you would like review these JCL update values from the beginning, type in Y, anything else will start the editing process

DO NOT HIT ATTENTION WHILE MGOINIT EXEC IS EDITING MEMBERS!

INPUT

USER01.INSTALL.JOBS(SMGO01) HAS BEEN EDITED FOR SUBMIT

INPUT

USER01.INSTALL.JOBS(SMGO02) HAS BEEN EDITED FOR SUBMIT

INPUT

USER01.INSTALL.JOBS(SMGO03) HAS BEEN EDITED FOR SUBMIT

INPUT

USER01.INSTALL.JOBS(SMGO04) HAS BEEN EDITED FOR SUBMIT

INPUT

USER01.INSTALL.JOBS(SMGO05) HAS BEEN EDITED FOR SUBMIT

INPUT

USER01.INSTALL.JOBS(SMGO06) HAS BEEN EDITED FOR SUBMIT

INPUT

USER01.INSTALL.JOBS(SMPMGO) HAS BEEN EDITED FOR SUBMIT

INPUT

USER01.INSTALL.JOBS(VERIFY) HAS BEEN EDITED FOR SUBMIT

END OF EDITING PROCESS

3.4 SMP Catalog Procedure

Member SMPMGO is a cataloged procedure needed by jobs SMGO03 through SMGO06. Do one of the following:

• Copy SMPMGO to one of the system procedure libraries

• Edit members SMGO03 through SMGO06 to convert the “JCLLIB” statement form a comment into a JCL statement.

• Edit members SMGO03 through SMGO06 by inserting SMPMGO into each job as an in-line procedure (be sure to add a "// PEND" statement).

3.5 Allocate Files Needed by SMP/E

Submit jobs SMGO01, SMGO02, and SMGO03 to allocate and initialize the various files needed by SMP/E.

3.6 Run the SMP/E Jobs

Submit job SMGO04 to perform SMP/E RECEIVE processing. This job moves function MGO1100 into the SMPPTS data set and places the associated data records into the temporary SMPTLIB data sets for subsequent processing.

Submit job SMGO05 to perform SMP/E APPLY processing. This job loads the target libraries. A return code of 4 is normal because a normal return code of 8 is returned during the link edit steps of the APPLY.

Submit job SMGO06 to perform SMP/E ACCEPT processing. This job loads the distribution libraries. For this job, a return code of ‘4’ is acceptable.

3.7 Run the Installation Verification Procedure

The IVP procedure verifies that the Mainframe Gateway for OpenVMS is properly installed and can communicate with the mainframe’s TCPIP software. If a Web Browser (on a PC or OpenVMS system) is available, the IVP can also verify that the MGO is reachable from the TCPIP network.

3.7.1 Start the IVP

To start the IVP, submit the VERIFY job.

The VERIFY job uses member IVPCONF of the sample library for input configuration information. IVPCONF contains nothing but comments. If problems are encountered in the IVP procedure, some of the comments may need to be converted to configuration statements (by deleting the ‘*’ in column 1).

A license is not required for execution of the IVP.

A VTAM application major node is not required for execution of the IVP.

3.7.2 Expected Results

After starting the IVP, examine the log file (defined by the SYSPRINT DD statement in MGOIVP). The MGO log file should contain two messages:

095300 ---- 01 I DATE: 040615

095300 ---- 00 I COMMENT: COPYRIGHT (C) 2004 BY DATA ACCESS …

095300 ---- 00 I DATA-ACCESS-INC-V1.1 - PTF:0000

095300 ---- 00 I COMMENT:

095301 ---- 06 I TCP: INITIALIZE API SUCESSFUL

From the mainframe operator’s console, or a TSO session enabled for console commands, issue a modify command to the MGO:

F mgoname,HELP

The MGO should respond with a list of available command in the console log and in the MGO log file.

095320 ---- 04 C INPUT: MODIFY: HELP

095320 ---- 05 C OUTPUT: SUPPORTED REQUESTS:

095320 ---- 05 C OUTPUT: HELP

095320 ---- 05 C OUTPUT: SHOW BUFFERS

095320 ---- 05 C OUTPUT: SHOW CONNECTIONS

095320 ---- 05 C OUTPUT: SHOW LOGICAL UNITS

095320 ---- 05 C OUTPUT: SET TRACE ON

095320 ---- 05 C OUTPUT: SET TRACE FULL

095320 ---- 05 C OUTPUT: SET TRACE OFF

095320 ---- 05 C OUTPUT: SET VTAM OPEN

On the address line of a Web Browser (Internet Explorer running on a PC), type the IBM mainframes IP name or dotted decimal address followed by “:108”. The “:108” tells the web browser to connect to TCP port 108 on the mainframe.

http://your.mainframe.dns.name:108

or

http://dotted.decimal.IP.address:108

The Web Browser should display a simple web page containing the product name, product version, and PTF level. The MGO log file should have one additional line:

095330 0001 23 I CLEANUP: CLEANUP INVOKED 00000:00000 00001:0033

If this output is observed, the MGO software is properly installed and communications with the mainframe TCPIP stack is operational.

3.7.3 Stop the IVP

To terminate the IVP, use the operator’s console halt command:

P mgoname

3.7.4 Quick Test with OpenVMS System

The instructions in the next two chapters contain detailed instructions for configuring MGO for operation with OpenVMS systems. Alternatively, follow these abbreviated instructions:

• Edit job MGOJCL in the sample library. The JOB card and the high level qualifier of the data set name parameters will need to be changed. After editing, the job will use the IVP configuration information plus a license and OpenVMS related information.

• Edit sample library member MGONODE to conform to your installation’s guidelines concerning VTAM application major nodes (MGONODE) and VTAM application names (MGOXX*). Then add the resulting member to your installation’s VTAMLST library.

• Activate the application major node (V NET,ACT,ID=MGONODE,SCOPE=ALL)

• If the VTAM application names (MGOXX*) were changed, make the same changes in member MGOCONF.

• Stop the IVP job (if it is still executing)

• Execute the MGOJCL job.

• From an OpenVMS system prompt, invoke the terminal emulator and connect to MGO on the mainframe: set host/sna mainframe.dns.name/wait

• From the SNA Terminal Emulator prompt: “PLEASE LOGON:” , type a logon request such as: logon applid(tso) logmode(d4c32782)

3.7.5 Trouble Shooting

If the second message in the MGO log file is “INITIALIZE API FAILED”, the MGO cannot communicate the TCPIP stack on the mainframe. If the message contains “FFFF / 03F3 - CHECK TCPIP STACK NAME”:

• Contact the person responsible for the TCPIP configuration on the mainframe to determine the name of TCPIP stack on your mainframe

• Edit the file referenced by the SYSIN DD statement in MGOIVP. Replace “TCPIPVX” with the name of the TCPIP stack on your mainframe.

• Delete the “*” before TCP-STACK (and make sure that the TCP-STACK now starts in column 1).

• Restart the IVP

If the same error recurs, please send mail to the Data Access support group at support@data-access-inc.com. Be sure to include a copy of the log file.

If the INITIALIZE API SUCCESSFUL may be followed by this message:

HHMMSS ---- 09 E TCP: BIND RC/ERRNO = FFFFFFFF/xx

TCP port 108 is not available for use by MGO. If the value of xx is ‘30’, the port is in use by some other application. If the value of xx is ‘0D’, the MGO application is not authorized to use port 108. If the value is neither ‘30’ nor ‘0D’, please contact the DAI support group for help in interpreting the error.

Either error condition can be bypassed (at least for the IVP), by changing the MGO configuration file to specify a port number other than 108:

• Edit the file referenced by the SYSIN DD statement in MGOIVP. Replace “108” in the TCP-PORT statement with some other (large) port number that is unlikely to be in use and unlikely to be restricted by firewalls/security. A value of 8108 may be a good choice.

• Delete the “*” before TCP-PORT (and make sure that the TCP-PORT now starts in column 1).

• Restart the IVP

• When accessing MGO from a Web Browser, use the same port number specified in the MGO configuration file (8108).

• To use an OpenVMS SNA application with a port number other than 108, on the OpenVMS system, specify

$DEFINE SNA_PORT_NUMBER "#8108"

If the expected page is not displayed on the Web Browser and no additional messages have been added to the MGO log file, a firewall (or other security measure) may be preventing the Web Browser request from reaching the MGO. Contact the Data Access support group, or the person responsible for you TCPIP network.

If the IVP (using a PC) is successful, but the OpenVMS SNA application cannot communicate with MGO, please generate a SNA LOG MASK trace on the OpenVMS system:

• In the OpenVMS SNA product environment, specify SNA LOG MASK trace:

$DEFINE SNA_TRANSPORT "nolocal,nodecnet,tcp"

$DEFINE SNALOG_MASK 0x7FFFFFFF

$DEFINE SNALOG_FILE disk:[dir]tracefile.txt

• Restart the OpenVMS SNA application

• Stop the OpenVMS SNA application

The trace file will contain a record of the OpenVMS SNA application's attempt's to communicate with the MGO application. Contact the Data Access support group at support@data-access-inc.com. Be sure to include a copy of the log file, the trace file, and a description of any additional symptoms.

4. SNA Configuration Information

This chapter describes the tasks you must perform to allow the Mainframe Gateway for OpenVMS (MGO) to access application programs (and 3270 terminals) on you SNA network.

Like the HP provided SNA Gateways, the Mainframe Gateway for OpenVMS is associated with a number of SNA Logical Units. Each OpenVMS application program uses one or more of these logical units to communicate with other components in the SNA network.

For other HP SNA Gateways, the logical units are defined by LU statements in Switched Major Nodes, Local SNA Major Nodes, or Channel Attached Major Nodes.

For the MGO, the logical units are defined by APPL statements in Application Major Nodes. One VTAM APPL statement is needed for each logical unit. All of the APPL statements can all be specified in a single Application Major Node, or distributed among many different nodes.

Each Application Major Node must be stored as a member of SYS1.VTAMLST (or the installation dependent equivalent). In addition, each major node must be ‘activated’ before MGO can use the APPL statements it contains (see ‘Activation of VTAM Resources’ at the end of this chapter).

Please see IBM’s SNA Resource Definition Reference (SC31-8778) manual for definitive information on all VTAM configuration issues.

4.1 Application Major Nodes and APPL Statements

The general format of VTAM Application Major Node is:

VBUILD TYPE=APPL

nodename GROUP keyword=value

luname APPL [keyword=value]

luname APPL [keyword=value]

The VBUILD statement declares that the information is an Application Major Node.

The GROUP statement provides a convenient way to specify “keyword=value” information that applies to all the APPL statements.

Each APPL statement defines one logical unit. Each APPL statement corresponds to one LU-NAME statement in the MGO configuration file. The APPL ‘luname’ value must match the SECOND parameter on the LU-NAME statement.

Some ‘keyword=value’ pairs are required for every APPL They can be coded on an APPL statement or on a preceding GROUP statement. The required parameters are:

SONSCIP=YES: This parameter controls the method that VTAM uses to notify the MGO of SNA session outages under some circumstances. The parameter is required because the VTAM provided default is “NO”

AUTH=(VPACE) or (VPACE,ACQ): The VPACE parameter indicates that the MGO is subject to the VPACING specification of secondary logical units when the MGO acts as the primary side of the SNA session. This value should always be specified to prevent excessive memory requirements within the MGO application. Use the (,ACQ) parameter for logical units that will initiate sessions with another logical unit. In general, only the OpenVMS 3270 Application Services access routine operates in this mode.

All other ‘keyword=value’ pairs are optional:

EAS=n: To conserve IBM mainframe resources, specify the estimated number of concurrent sessions using the EAS parameter. For logical units used with OpenVMS 3270 Application Services product, specify the expected number of concurrent sessions. For logical units used with all other OpenVMS applications, specify a value of 1. The value specified by the EAS is NOT critical. According to IBM’s documentation, it is used to control the amount of resources initially allocated to a logical unit. It is NOT used to enforce an upper limit on the number of concurrent sessions. The maximum number of sessions per logical unit is enforced by the MGO. Unless a larger number is specified on a MGO configuration LU-LIMIT statement, the MGO allows only one session per logical unit.

MODETAB: The name of the logmode table assigned to the logical unit. This table should contain entries appropriate for use with the OpenVMS applications.

DLOGMOD: The name of the entry in the logmode table to use as a default value when a specific entry is not specified elsewhere. If DLOGMOD is not specified, the first entry in the table becomes the default.

PRTCT: A password value that the MGO must supply in order to use the VTAM application name.

VPACING: Specifies the pacing count for data flowing from VTAM to the MGO. Valid values are 1 to 63. Large values may provide better performance but may also result in increased memory usage by MGO. A value of 16 should provide adequate performance and reasonable memory usage.

Example: A Sample Application Major Node

*

* MGONODE - VTAM APPLICATION MAJOR NODE

*

VBUILD TYPE=APPL

**

MGONODE GROUP SONSCIP=YES,AUTH=(VPACE),EAS=1

MGOXXA APPL

MGOXXB APPL

MGOXXC APPL

MGOXXD APPL

MGOXXE APPL AUTH=(VPACE,ACQ),DLOGMOD=D4C32782,EAS=50

The VTAM Application Major Node contains definitions for six logical units. Each logical unit inherits the ‘keyword=value’ parameters specified on the GROUP statement.

Logical units MGOXXA through MGOXXE would provide access to IBM mainframe application programs for most OpenVMS SNA applications.

Logical unit MGOXXF could be used with the SNA 3270 Application Server to support multiple concurrent sessions with IBM 3270 compatible terminals.

The name that precedes each VTAM APPL statements must match a parameter in the MGO configuration file statements. The next example shows a fragment of an MGO configuration file that corresponds to the VTAM Application Major Node in the previous example. The MGO configuration file requirements are covered in detail in the next section.

Example: MGO Configuration File Information

*

*

LU-NAME ABC1 MGOXXA * OpenVMS name ABC1 = VTAM name MGOXXA

LU-NAME ABC2 MGOXXB * OpenVMS name ABC2 = VTAM name MGOXXB

LU-NAME ABC3 MGOXXC * OpenVMS name ABC3 = VTAM name MGOXXC

LU-NAME ABC4 MGOXXD * OpenVMS name ABC4 = VTAM name MGOXXD

LU-NAME ABC5 MGOXXF * OpenVMS name ABC6 = VTAM name MGOXXE

*

LU-LIMIT ABC5 50 *Session Limit for LU ABC5

LU-ADDRESS ABC5 11.22.33.44 8043 *OpenVMS IP address & PORT

*

4.2 VTAM Activation Commands

Both the major node and the APPL must be activated. In a production environment, the major node names are usually included in a list of resources that are activated when VTAM starts. During installation and testing, it may be more convenient to manually activate the resources. A VARY operating system console commands could be used to activate the APPL definitions shown in the previous section:

V NET,ACT,ID=MGONODE,SCOPE=ALL

Or

V NET,ACT,ID=MGONODE,SCOPE=ONLY

V NET,ACT,ID=MGOXXA

V NET,ACT,ID=MGOXXB

V NET,ACT,ID=MGOXXE

The ‘SCOPE=ALL’ parameter indicates that all the logical units defined within MGONODE 2 are to be activated. The ‘SCOPE=ONLY’ parameter indicates that the activate request applies only to the application major node and NOT to the logical units within the node.

If the APPL statements are not defined or not activated when the MGO starts, error messages are generated for each missing or inactive logical unit. After the APPL statements are defined and activated, issue the MGO ‘SET VTAM OPEN” command to attempt to use the newly activated logical units.

F jobname,SET VTAM OPEN

A DISPLAY operating system console command can also be used to display the state of application major nodes and logical units. To display the status of an application major node:

D NET,ID=MGONODE

Possible responses:

IST453I ID PARAMETER VALUE P390.MGONODE NOT VALID

Or

IST097I DISPLAY ACCEPTED

IST075I NAME = MGONODE, TYPE = APPL SEGMENT 081

IST486I STATUS= ACTIV, DESIRED STATE= ACTIV

IST314I END

The first response (IST453I) indicates that the name MGONODE has not been defined or in not currently active.

The second response (IST486I) shows that the major node is active.

A ‘,E’ at the end of the display command indicates that the display should include every logical unit within the application major node.

D NET,ID=MGONODE,E

IST097I DISPLAY ACCEPTED

IST075I NAME = MGONODE1, TYPE = APPL SEGMENT 084

IST486I STATUS= ACTIV, DESIRED STATE= ACTIV

IST360I APPLICATIONS:

IST080I MGOXXA CONCT MGOXXB CONCT MGOXXC CONCT

IST080I MGOXXD CONCT MGOXXE CONCT

IST314I END

The value following each logical unit name (messages IST080I) indicates the state of each logical unit. The most common states and their meaning are: