Horizon network management

From m204wiki
Revision as of 22:04, 13 October 2017 by ELowell (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Overview

When using Model 204 Horizon, the system manager must consider the following issues:

  • Network definition

    Network definition involves defining the network to Model 204 (using the DEFINE command) and defining the network to SNA Communications Server (formerly VTAM) or a TCP/IP product.

  • Network administration

    Network administration involves using the network administration commands to manipulate the network entities defined to Model 204.

  • Network security

    Network security involves using DEFINE command security parameters in conjunction with Application Subsystem security to provide the desired protection for network resources. Network security is described in Horizon network security.

  • Model 204 Online configuration preparation

    Online configuration preparation involves the following modification of system input (CCAIN): allotting Horizon inbound threads (IODEV=27) and adding to the NSUBTKS parameter value for LU 6.2/SNA Communications Server pseudo subtasks.

  • Application program testing

    The Remote Procedure Invocation (RPI) subsystem, included as part of DICTIONARY installation, is an option that simplifies the testing of Horizon application programs.

Defining the Network to Model 204

Before partner programs can converse over Horizon, the network, including the programs and their interconnections, must be defined to Model 204. In addition, the network must be defined to SNA Communications Server, which supports Horizon. Each Model 204 system in the network provides a definition of the link, processgroup, and process entities using respectively the DEFINE LINK, DEFINE PROCESS, and DEFINE PROCESSGROUP commands.

Defining the network to Is described in
Model 204 This topic, as well as these:
SNA Communications Server Defining the network to SNA Communications Server

Network entities requiring definition

This section introduces the network definition commands. For Model 204, Horizon network definition involves identifying network entities with DEFINE commands. These entities and their interdependencies form the network's logical layer. Parameters of the DEFINE command for each entity point to names of related entities within the network and thereby determine the network's communication paths.

The following three network entities must be defined with the Model 204 DEFINE command before a Horizon application can run successfully:

  • Link -- Defines the transport mechanism and protocol to be used for communications, and specifies a node name to be used when Model 204 connects to the SNA network so that other nodes within the network can refer to this node by name.
  • Processgroup -- Connects the process to a specific link and groups processes according to certain attributes, such as session usage, to facilitate resource allocation. It also defines a remote node with which a process can communicate.
  • Process -- Defines the local conversation program. If the process is a client process, it also identifies the remote conversation partner or partner process. If the process is a server process, it identifies the subsystem which is to be invoked when the client process issues an inbound conversation request.

Note: CNOS connections require the definition of two additional definition commands: DEFINE REMOTE and DEFINE SESSIONGROUP. See Horizon CNOS connections for more information.

Creating a Horizon network

A large department store chain has its headquarters in New York and branches located in various states in the U.S. Three Model 204 online systems are running in three different locations: the headquarters in New York, one branch in San Francisco, and one branch in Boston. The figure "Physical Network Configuration for Polling Application" below shows the network to be defined to Model 204.

Polling application with one-way communication

The following figure illustrates a polling application where communication is initiated in only one way: from headquarters to the two branches. Headquarters needs to access the weekly sales figures in San Francisco and Boston.

Physical Network Configuration for Polling Application

DEFINE parameters for network entities

This figure illustrates the logical view from the Model 204 System 1 at headquarters and at the Boston Branch, Systems 1 and 2 respectively. The boxes contain skeleton entity definitions: named entities plus the appropriate DEFINE command parameters. The arrows in the figure "Logical Network View from New York and Boston" show how the parameters interrelate: straight arrows show intrasystem correspondence; bent arrows show intersystem correspondence.

Logical Network View from New York and Boston

Defining the link

Each Model 204 system is identified to the network through the LOCALID parameter of the DEFINE LINK command. In this example, the LOCALID for the New York headquarters is M204HQ; the LOCALID for the Boston Branch is M204BO.

Defining the processgroup

The DEFINE PROCESSGROUP command uses the REMOTEID parameter to specify the remote node with which a process wishes to communicate. Processgroup PGCLI1 in headquarters specifies REMOTEID M204BO, which points to the Boston branch; processgroup PGSRV in the Boston branch specifies REMOTEID M204HQ, which points to the New York headquarters.

Defining the process

The DEFINE PROCESS command for the client process in headquarters specifies PARTNER=WSALES, the server process in Boston. The server process WSALES in Boston specifies SUBSYSTEM=WKS, the subsystem to be invoked when the client process initiates a conversation.

Defining a Horizon network

Example 1: Polling application

The following is a step-by-step description of how the DEFINE commands are set up for a polling application where the conversations are initiated from one central location. This example is based on the department store application described in the physical network example in figure "Physical Network Configuration for Polling Application". DEFINE commands for the headquarters in New York are described first.

Defining the link for the client side

New York headquarters initiates a conversation to determine the weekly sales figures at the Boston and San Francisco branches. New York headquarters is therefore the client system. The first command required is DEFINE LINK:

DEFINE LINK LINKCLI WITH - SCOPE=SYSTEM - TRANSPORT=VTAM - PROTOCOL=LU62 - SESSIONS=6 - LOCALID=M204HQ - INBUFSIZE=2048

This definition provides the following specifications:

  • The transport type (SNA Communications Server) and the protocol (LU62) to be used for communications.
  • The maximum number of sessions that can be used by Horizon applications (6).
  • The identification of the New York headquarters' Model 204 system to the SNA network (M204HQ).
  • The size of the "receive" buffer, which receives data transferred over the session (2048 bytes, the recommended value).

Defining the processgroup for the client side

The next step is setting up the processgroup definitions:

DEFINE PROCESSGROUP PGCLI1 WITH - SCOPE=SYSTEM - LINK=LINKCLI - REMOTEID=M204BO - OUTLIMIT=5 - INLIMIT=0 - RETAIN=4

DEFINE PROCESSGROUP PGCLI2 WITH - SCOPE=SYSTEM - LINK=LINKCLI - REMOTEID=M204SF - OUTLIMIT=3 - INLIMIT=0 - RETAIN=0

This definition provides the following specifications:

  • The first processgroup defined above, PGCLI1, is to converse with the Model 204 system at the Boston branch (REMOTEID=M204BO).
  • PGCLI1 allows a maximum of five concurrent outbound conversations (OUTLIMIT=5).
  • Since the headquarters is initiating all the conversations and is not expected to receive any inbound conversation requests, no inbound conversations have to be specified (INLIMIT=0).
  • Four sessions are retained.
  • The second processgroup, PGCLI2, is to converse with the Model 204 system at the San Francisco branch.
  • PGCLI2 allows only three concurrent outbound conversations.
  • Since the headquarters is initiating all conversations and is not expected to receive any inbound conversation requests, no inbound conversations have to be specified.
  • No sessions are retained when processes belonging to PGCLI2 are closed.

Defining the client process

Lastly, the system manager defines the remote conversation partner with the DEFINE PROCESS command as follows:

DEFINE PROCESS WKSALES WITH - SCOPE=SYSTEM - DESTINATION=(PGCLI1,BOSTON,PGCLI2,SF) - PARTNER=WSALES - DATALEN=2048 - CONFIRM

The definition provides the following specifications:

  • Process WKSALES belongs to processgroups PGCLI1 and PGCLI2, which directs the conversation to either the Boston or San Francisco branches.
  • WKSALES is a client process and its partner name is WSALES, the process name on the server system.
  • The maximum data area expected to be received from the server processes on either the Boston or San Francisco branches is 2048 bytes.
  • Confirmation processing is allowed.

Logically viewing the network

The network as seen by the system manager at the New York headquarters is shown in the figure "Logical Network Configuration at New York Headquarters."

Logical network configuration at New York headquarters

This figure shows the relationship of the process to the processgroups and the processgroups to the link. Notice that the two processgroups support a total of eight concurrent outbound conversations, while the link supports only six sessions for these outbound conversations.

PGCLI2 is assumed to be a less active processgroup that requires fewer and shorter conversations. Its RETAIN value of zero means that when its conversations end, its sessions are freed up for use by the busier PGCLI1.

Preserving an available session

This is an example of tuning RETAIN and OUTLIMIT values so that it is possible not to run out of available sessions. See the discussion of RETAIN in Defining a Horizon network for more information about sharing sessions and network resource use.

The sessions are allocated on a first come, first served basis. They remain allocated to a remote node unless the link is closed, a STOP LINK or STOP PROCESSGROUP command is issued, or the session is ended by the remote node. The effects of STOP LINK and STOP PROCESSGROUP are described further in STOP command: Stopping a Horizon or Model 204 SQL link or processgroup.

The session used by each outbound conversation with PGCLI2 is released as soon as the conversation ends, as specified by the RETAIN value of zero in PGCLI2's processgroup definition.

Defining the link for the server side

Since the branches receive inbound conversation requests from the New York headquarters for weekly sales figures, they are server systems. The DEFINE commands for one of the branches, Boston, are as follows, beginning with DEFINE LINK:

DEFINE LINK LINKSRV WITH - SCOPE=SYSTEM - TRANSPORT=VTAM - PROTOCOL=LU62 - SESSIONS=5 - LOCALID=M204BO - INBUFSIZE=2048

This definition provides the following specifications:

  • The transport type (SNA Communications Server) and the protocol (LU62) to be used for communications.
  • The maximum number of sessions that can be used by Horizon applications (5).
  • The identification of the Boston branch's Model 204 system to the SNA network (M204BO).
  • The size of the "receive" buffer, which receives data transferred over the session (2048 bytes, the recommended value).

Defining the processgroup for the server side

The next step is setting up the processgroup definition:

DEFINE PROCESSGROUP PGSRV WITH - SCOPE=SYSTEM - LINK=LINKSRV - REMOTEID=M204HQ - OUTLIMIT=0 - INLIMIT=5 - RETAINALL

The definition provides the following specifications:

  • Processgroup PGSRV needs to converse with the Model 204 system at the New York headquarters, as indicated by the REMOTEID value of M204HQ.
  • PGSRV allows a maximum of five concurrent inbound conversations and no outbound conversations, since the Boston branch is not expected to initiate any conversations.
  • All sessions are retained.

Defining the server process

Lastly, the DEFINE PROCESS command specifies the subsystem to be invoked by an inbound conversation request from the client:

DEFINE PROCESS WSALES WITH - SCOPE=SYSTEM - FROM=PGSRV - SUBSYSTEM=WKS - DATALEN=2048 - CONFIRM

The definition provides the following specifications:

  • Process WSALES belongs to processgroup PGSRV, which directs the conversation to the New York headquarters.
  • WSALES is a server process and the subsystem associated with it is WKS.
  • The maximum data area expected to be received from the client process is 2048 bytes.
  • Confirmation processing is allowed. Even if the SOUL CONFIRM statement is not used in the subsystem procedures, CONFIRM is included in the server process definition because the client process has CONFIRM in its definition. Both the client and server processes must specify the same option.

Example 2: Polling application extension

The following example highlights the RETAIN parameter of the DEFINE PROCESSGROUP command. The department store application described in the previous example is expanded here, requiring more than weekly sales figures from the Boston and San Francisco branches. Suppose that the New York headquarters also requires the payroll and personnel information at the branches in order to print paychecks on a monthly basis.

Logical view of the network

The logical view of the network at New York headquarters is illustrated in the figure "Processgroups Sharing Sessions." The system manager uses two different processgroups to handle sales and payroll applications. Using two processgroups limits the maximum number of concurrent outbound conversations for each type of application.

Processgroups Sharing Sessions

Processgroups sharing sessions

Processgroups SALES1 and ADMIN1 (and SALES2 and ADMIN2) are able to share sessions because of four parameter values they have in common:

  • LINK=LINKCLI
  • REMOTEID=M204BO
  • LOGIN=NOTRUST (the default)
  • MODENAME (not specified)

Processgroups SALES1 and ADMIN1 can retain a total of seven sessions since SALES1 is specified with RETAIN=5 and ADMIN1 is specified with RETAIN=2.

Note: The sessions are shared by SALES1 and ADMIN1. This does not mean that five sessions are retained specifically for SALES1 and two for ADMIN1.

Processgroups SALES2 and ADMIN2 can retain a total of six sessions since SALES2 is specified with RETAIN=3 and ADMIN2 is specified with RETAIN=3. Since SALES2 has NOOUTLIMIT, it is possible for all six sessions to be used by processes belonging to SALES2.

Example 3: Two-way conversation initiation application

The polling application in the figure "Physical Network Configuration for Polling Application" involved communication initiated in only one way: from one central location, the headquarters, to the two main branches. Communication can also be initiated from more than one direction.

For example, the Boston branch mentioned in the previous example may require access to the inventory in a sub-branch located in Cambridge. If the Boston branch runs out of stock on an item, it can be determined whether Cambridge has the item available, and the customer can be sent to that branch. Similarly, the Cambridge branch can do a query on the Boston branch's inventory.

Physical network configuration

The figure "Two-way conversation initiation" shows the physical network configuration for this type of application.

Two-way conversation initiation

Logical network view

The figure "Logical Network Configuration for Boston Branch" shows the logical network configuration for the two-way inventory application as viewed from the Boston branch. Processgroup INVENTRY points to M204CB, which identifies the Cambridge branch. Both the OUTLIMIT and INLIMIT parameters for processgroup INVENTRY are set to nonzero values: it is possible to initiate conversations or receive inbound conversation requests.

Logical network configuration for Boston branch

Example 4: Local node testing

A single Model 204 system can represent both the client and the server system for initial development and testing purposes. You can set up two SNA Communications Server APPL definitions for the same Model 204 ONLINE, and use two different link definitions to refer to these APPL definitions using the LOCALID parameter. For more information about SNA Communications Server APPL definitions, see Defining the Network to SNA Communications Server.

Logical network view

The figure "Client and server processes on a single system" shows the interrelationship of the network entities for a single Model 204 system acting as client and server. The entity names must be unique since they reside within the same Model 204 online system. The arrows in the figure show how the DEFINE command parameters interrelate: straight line arrows show intrasystem correspondence; bent line arrows show intersystem correspondence.

Client and server processes on a single system

Defining the links

DEFINE LINK LINKCLI WITH - SCOPE=SYSTEM - TRANSPORT=VTAM - PROTOCOL=LU62 - SESSIONS=5 - INBUFSIZE=2048 - LOCALID=M204HQ1

DEFINE LINK LINKSRV WITH - SCOPE=SYSTEM - TRANSPORT=VTAM - PROTOCOL=LU62 - SESSIONS=5 - INBUFSIZE=2048 - LOCALID=M204HQ2

Defining the processgroups

DEFINE PROCESSGROUP SALESCLI WITH - SCOPE=SYSTEM - LINK=LINKCLI - REMOTEID=M204HQ2 - OUTLIMIT=3 - INLIMIT=0 - RETAIN=3

DEFINE PROCESSGROUP SALESSRV WITH - SCOPE=SYSTEM - LINK=LINKSRV - REMOTEID=M204HQ1 - OUTLIMIT=0 - INLIMIT=3 - RETAIN=3

Defining the processes

DEFINE PROCESS WKSALECL WITH - SCOPE=SYSTEM - DESTINATION=SALESCLI - PARTNER=WKSALESR - DATALEN=2048 - IMEOUT=60

DEFINE PROCESS WKSALESR WITH - SCOPE=SYSTEM - FROM=SALESSRV - SUBSYSTEM=WKS - DATALEN=2048 - TIMEOUT=60

Defining the network to SNA Communications Server

This section describes how to set up the SNA Communications Server network support for Horizon.

Throughout the discussion in this section, the term "link" refers to a Horizon link. Although not a communication line like an SNA Communications Server or SNA link, a Horizon link, in fact, corresponds to an SNA logical unit (LU). That is, a Horizon link serves as a logical port between an application program and the network.

You define Horizon to the SNA Communications Server network in two areas of the VTAMLST data set:

  1. APPL definition statements
  2. Mode table entries

An APPL statement for each Horizon "link" is required to establish that Horizon link as a logical unit (LU) within the network.

An entry in a mode table is required to specify the particular set of SNA protocols (the session mode) desired for a session between two Horizon LUs. In this case the protocols are characteristic of LU type 6.2.

The APPL statements for network definition and Coding the mode table entry for SNA Communications Server network definition sections that follow describe how to code the APPL statements and the mode table entries to define the SNA Communications Server network.

APPL statements for network definition

SNA Communications Server network definition for host-to-host communications (such as a Model 204-to-Model 204 Horizon conversation) differs from that for terminal-to-host environments. In host-to-host environments, a single entity type can take either the primary or the secondary role in the conversation. Terminal-to-host environments, have two entity types, one of which always takes the primary role and the other of which always takes the secondary role.

APPL statement per Horizon online

Horizon Model 204-to-Model 204 sessions involve one type of LU: a SNA Communications Server application LU. Terminal-to-host communications involve two different types of LUs: a SNA Communications Server application LU and several terminal LUs. These LU types are defined in SNA Communications Server in separate places. Host Onlines (SNA Communications Server application LUs) are defined by APPL statements; terminals are defined in LU macros.

APPL statement dual function

In a Horizon Model 204-to-Model 204 session, both partners are SNA Communications Server application LUs and both are defined to SNA Communications Server by APPL statements. Yet, on any particular Horizon session, one partner is the primary end and the other one is the secondary, just as in a terminal-to-host session. The APPL statement for a Horizon system must therefore provide information about both the primary and secondary ends. In terminal-to-host systems the APPL statement carries the primary information and the LU macros carry the secondary information.

Thus, for example, the APPL statement for a Horizon system must point to a mode table (while for terminal-to-host systems the LU macro does). Also, since each Horizon link supports multiple sessions, where the link can be primary on one and secondary on another, information for both roles must be included on each APPL.

Coding the APPL statements for Horizon support

The APPL statements are coded within the library SYS1.VTAMLST (in z/OS) or within a file with filetype VTAMLST (in CMS).

You should group together all the APPL statements for all the Model 204 systems running under a particular SNA Communications Server in the same VTAMLST member or file, for ease of activating the APPL statements.

How many APPL statements are required?

In addition to the APPL statement required for Model 204 SNA Communications Server terminal support, you must code at least one APPL statement for each Model 204 system involved in a Horizon conversation.

Each additional link to the network requires an additional APPL statement.

Activation of APPL statements

For each SNA Communications Server that supports Horizon "links," the relevant APPL statements must be activated before Model 204 and Horizon can use the network. Generally, this activation occurs automatically at SNA Communications Server startup. However, if direct operator control of APPL activation is desired, entire groups of APPLs (major nodes) can be activated at one time.

APPL statement parameters

Most of the two dozen or so parameters on the APPL statement default to values appropriate to Horizon systems. Only four parameters must be specified by the SNA Communications Server systems programmer. Technical Support recommends that two other parameters be specified as well, to make network maintenance easier. A seventh parameter, again optional, is relevant only where Horizon node name protection is desired.

The required parameters for the APPL statement, when used for defining SNA Communications Server support for Horizon links, are shown in the following simplified syntax chart that does not include all APPL statement parameters.

name APPL AUTH=ACQ, PARSESS=YES, MODETAB=tablename, Optional: DLOGMOD=entryname, VPACING=5, PRTCT=password

Where:

  • name must be the same as the LOCALID parameter of the corresponding DEFINE LINK command. This name is the LU name, the name of the SNA network entity that participates in network sessions with a partner LU. The APPL name (and LOCALID) of the remote Horizon "link" becomes the REMOTEID parameter for defining the partner systems in Model 204. The value of name on each APPL definition statement must be unique within the entire network.

    Note: Do not confuse the APPL name with the ACBNAME parameter. The ACBNAME parameter refers to the name used when a SNA Communications Server application LU issues a request to open communications with the network. The ACBNAME can be the same as or different from the APPL name, and it does not need to be unique within the network. Its default is the APPL name.

    While it can be of some use to code a value for ACBNAME in terminal-to-host systems with multiple copies of the host Online, it is not helpful for host-to-host systems such as Horizon. Moreover, if ACBNAME is coded on the APPL statement, the LOCALID parameter in the DEFINE LINK command must be set to this ACBNAME value, while the REMOTEID parameter in the DEFINE PROCESSGROUP command must still be set according to the APPL name.

    The name parameter of the APPL statement for SNA Communications Server terminal support must be the same as the VTAMNAME parameter in the User 0 CCAIN of Model 204.

  • AUTH (authorize) is required and must specify ACQ (acquire). This specification lets Model 204 acquire sessions with other LUs. In Horizon, Model 204 regularly does this when starting outbound conversations. This parameter setting authorizes the Model 204 SIMLOGON SNA Communications Server request when acquiring sessions.
  • Parallel session support, the PARSESS parameter, is required and must be set to YES. This setting causes SNA Communications Server to prepare support--primarily in terms of network addressing tables--for more than one session to take place concurrently between the same pair of LUs.

    All the sessions allowed by the SESSIONS parameter on the Model 204 DEFINE LINK command can take place concurrently with the same remote system, with each bearing a program-to-program conversation.

    Note: If PARSESS parameter defaults to NO, Model 204 fails in its attempt to start a second, simultaneous conversation.

  • MODETAB is a required parameter. It ties the APPL definition to the mode definition that specifies the particular set of SNA protocols required for the LU 6.2 session between two LUs.

    MODETAB points SNA Communications Server to the table containing the mode definition. An entry in the table is a set of characteristics, or session parameters, that is applied when a session is established. These parameters are sent from the LU that acquires the session to the partner LU so that both share a common set of rules.

    Generally, unless the environment already contains systems using LU 6.2, the SNA Communications Server systems programmer should construct a new, separate table for LU 6.2 session parameters, with one entry in it. (As described in Preparing the log mode definitions and in Horizon CNOS connections, parallel sessions connections might require two entries.)

    If the entry for the LU 6.2 session parameters will be placed in a table containing other LU 6.2 entries, code the DLOGMOD parameter (in addition to the MODETAB parameter) to specify which entry is desired.

    Note: If MODETAB is not coded at all, SNA Communications Server uses an inappropriate default mode table for the LU 6.2 sessions. Unlike the situation for the mode entry, there is no way for a SNA Communications Server application to supply the name of the proper mode table to SNA Communications Server dynamically upon starting the session; there is accordingly no corresponding DEFINE parameter in Model 204.

    Another way to specify the entry is to use the Model 204 DEFINE commands rather than specifying the mode definition in SNA Communications Server. To do so, code the name of the SNA Communications Server mode table entry on the MODENAME parameter of the DEFINE PROCESSGROUP command.

    If the mode table specified in MODETAB contains more than one set of session parameters, SNA Communications Server selects the first entry, by default. To specify an entry that is not the first one in the table, you must use either the DLOGMOD parameter in the SNA Communications Server APPL statement or the MODENAME parameter in the Model 204 DEFINE LINK command.

  • APPC=NO is required if you are using SNA Communications Server 3.3 or later SNA Communications Server versions. The NO option, which is the default, is required even though Horizon is an LU 6.2 implementation. APPC is not valid for versions of SNA Communications Server earlier than SNA Communications Server 3.3.
  • DLOGMOD is an optional parameter that specifies the name of a particular entry in the mode table that has the parameters to be used for the session. The value specified for DLOGMOD must match a MODEENT entry name in the specified table.

    DLOGMOD is described further in the description of MODETAB, above.

  • VPACING (SNA Communications Server pacing) is an optional parameter. This is the maximum number of messages, or chain elements, received by the LU during a session before an acknowledgment, a pacing response, is sent to the partner LU.

    The value of the VPACING parameter must match the value of the SSNDPAC parameter in the partner's mode table that limits the number of messages sent before a response is received. A value of five (messages) for both is recommended to accommodate average message length.

    • SNA Communications Server pacing is also discussed in SNA Communications Server tuning for Horizon.
    • PRTCT (protect password) is an optional parameter that provides a security feature in network access. When the PSWD parameter is coded on the Model 204 DEFINE LINK command, the issuer of the OPEN LINK command is prompted for a password. The password entered must match the value of the PRTCT parameter, or SNA Communications Server rejects the Online request to open communications for the named LU. Horizon network security fully describes Horizon security features.

Coding the mode table entry for SNA Communications Server network definition

As described in APPL Statements for Network Definition, the APPL statement corresponding to a Horizon link points directly to a table, each of whose entries is a set of session characteristics (session parameters). The entire set is actually sent from the LU that acquires the session (the primary LU) to the partner LU (the secondary LU) in the Bind message that establishes the session. The two halves of the session are thereby able to share a common set of rules.

MODETAB, also called logon mode table

The MODETAB table is often called a logon mode table or logmode table and its entries logmodes because, prior to the introduction of program-to-program communications, the table entries referred to the characteristics of a terminal and were set up for the session when the terminal logged on to the network. In a program-to-program session, neither end is a terminal and, strictly speaking, there is no logon being done. However, the notion of a set of session parameters controlling the rules of the session between the two partners still pertains.

Where mode tables reside

Mode tables are assembled and link edited into a load library usually called SYS1.VTAMLIB (in z/OS) or into a file with filetype LOADLIB (in VM). The source code may be entered anywhere, but is usually entered into SYS1.VTAMLST in z/OS or a file with filetype VTAMLST in VM.

Creating a mode table entry

The SNA Communications Server systems programmer must create an entry in the SNA Communications Server mode table to specify the particular set of SNA protocols desired for the session between two Horizon LUs.

This entry is one of the following:

  • The first or only entry in the table.
  • An entry whose LOGMODE parameter value matches the value of the optional DLOGMOD parameter of the APPL statement.

    DLOGMOD parameter of the APPL statement.

  • An entry whose LOGMODE parameter value is the same as the MODENAME parameter value of the Model 204 DEFINE PROCESSGROUP command.

Recommended mode table parameter values

Generally you should set the mode table entry with the parameter values shown below. Most of these parameters specify LU type 6.2 variations on basic SNA protocols. Exceptional cases are cited in Modifications for specific systems and applications.

tablename MODETAB entryname MODEENT LOGMODE=entryname TYPE=X'00', FMPROF=X'13', TSPROF=X'07', PRIPROT=X'B0', SECPROT=X'B0', COMPROT=X'50B1', RUSIZES=X'8888', SSNDPAC=X'05', PSERVIC=X'060200000000000000102000' . . . . (Entries for systems other than . . Model 204 may follow here.) tablename MODEEND

Note: Unlike the case for the APPL name, there is no uniqueness requirement for mode entry names; the same name may appear in more than one table. There is also no need to activate mode tables. The proper table is simply link edited into the library and is accessed from there by as many copies of SNA Communications Server as are designated to use that library.

Modifications for specific systems and applications

The nature of a particular system or application may require modifications to the values of the following parameters of the mode table entry to support Horizon:

  • RUSIZES
  • SSNDPAC

The COS= parameter in the mode table entry may also need to be modified to meet system and application requirements.

The situations requiring such modifications are discussed in SNA Communications Server tuning for Horizon.

Modifications for parallel session connections are discussed in Defining CNOS support to SNA Communications Server. In particular, the PSERVIC value must be different.

Modifications for connections to VAX/VMS systems are discussed in Connecting to VAX/VMS.

Setting the PSERVIC security byte

You might need to review the tenth byte of your PSERVIC setting, which is equivalent to the 23rd byte of the bind between the Horizon partners. PSERVIC describes the layout of the presentation services (PS) portion of the bind.

The tenth byte of PSERVIC governs security options. Three options are relevant:

  • X'00' means no security information is accepted by the Horizon primary partner. The secondary partner does not send any user ID or password.
  • X'10' means security information is accepted by the Horizon primary partner. The secondary partner sends user ID and password.
  • X'12' means security information is accepted by the Horizon primary partner, and the Already-Verified indicator is accepted in lieu of a password. The secondary partner sends user ID but no password.

These settings must correspond to the Horizon DEFINE PROCESSGROUP command LOGIN parameter or Horizon rejects any conversations for the processgroup.

As shown below, the PSERVIC settings must also correspond to the Model 204 SYSOPT parameter X'10' bit setting, which indicates (on or off) whether login is required for access to MODEL 204.

X'00' corresponds to LOGIN=NOTRUST, SYSOPT X'10' bit off
X'10' corresponds to LOGIN=NOTRUST, SYSOPT X'10' bit on
X'12' corresponds to LOGIN=TRUST, SYSOPT X'10' bit on

Network administration commands

Network administration concerns are those that have to do with the day-to-day operation of the Model 204 network. These operation tasks are governed by the network administration commands.

The network administration commands are used to manipulate the different network entities (link, processgroup, and process) once they have been defined. These commands, also called network control commands, can be placed in the User 0 stream or within a Model 204 procedure. They require that the issuer be either User 0, a system administrator, or a system manager. They can also be issued at command level.

The network control commands include:

Preparing the ONLINE configuration

This section describes CCAIN stream parameters the system manager must set appropriately for Horizon to function successfully. The parameters discussed here are the system input (CCAIN) parameters IODEV and NSUBTKS. ONLINE configuration preparation includes allotting Horizon inbound threads (IODEV=27) and adding to the NSUBTKS parameter value for LU 6.2/SNA Communications Server pseudo subtasks.

IODEV specification for Horizon inbound threads

Processing inbound conversation requests requires that Model 204 have a pool of Horizon threads available for running the server programs. These threads must be defined in the server CCAIN stream as part of the Model 204 ONLINE configuration.

A new IODEV number, 27, defines Horizon inbound conversation threads. The NOTERM parameter is required on the first user parameter line that specifies IODEV=27. NOTERM indicates how many threads are to be allocated for Horizon inbound conversation processing.

To guarantee that there is no shortage of Horizon inbound threads and that all incoming conversation requests can be processed, set the NOTERM parameter to the total of INLIMIT values on all DEFINE PROCESSGROUP commands for the server system.

For more information about IODEV 27, see Defining the user environment (CCAIN).

Modifying the NSUBTKS parameter

The number of pseudo subtasks that can be used by Model 204 during a run must be increased by 4 per open link if Horizon is running in CMS, or increased by 2 per open link if Horizon is running in z/OS.

NSUBTKS is a user zero parameter.

See Pseudo subtasks for more information.

Application testing with the RPI subsystem

A server process always invokes an application subsystem. This implies that before a SOUL program can be run as a server process it must first be defined as a Model 204 application subsystem. For running or testing ad hoc procedures, this definition of the procedure as a subsystem may be inconvenient.

The Model 204 Remote Procedure Invocation (RPI) subsystem permits ad hoc procedures that have not been defined as application subsystems to be invoked by server processes. RPI is simply an initiator subsystem that invokes a specified procedure from a specified procedure file.

For more information about developing application subsystems, see SOUL.

RPI subsystem installation

The RPI subsystem is installed automatically and defined to the Application Subsystem facility as part of DICTIONARY installation. It must be installed on the system in which the server program to be tested runs.

System manager responsibilities

Before the RPI subsystem can be used, a system manager has two responsibilities:

  1. Ensure that the procedure file containing the procedure to be tested permits the procedure to be invoked.
  2. Ensure that the procedure to be tested is defined as a process.

Each of these is described separately below.

Ensuring the procedure file permits procedure inclusion

You cannot include a procedure from the procedure file if the file is private or if it is does not grant sufficient privileges to include a member procedure. You must take the file type and file privileges into account and choose one of two options for opening the procedure file:

  1. Open the procedure file automatically when the RPI subsystem is invoked. Do this by adding the procedure file to the RPI subsystem definition using the SUBSYSMGMT facility.
  2. Let RPI attempt to open the file. Do this by appropriate coding of the DEFINE PROCESS command SUBSYSPARM parameter, which is discussed below.

The following considerations affect your choice of option:

  • RPI can open a public or semipublic procedure file that is not defined to the RPI subsystem as long as the default privileges for the file are sufficient to allow procedure INCLUDEs. For such files, the second option above is simpler.
  • RPI cannot open private files and files not given sufficient privileges to allow procedure INCLUDEs. Such files must be added to the RPI subsystem definition to be automatically opened.
  • If you rely on the first option above, you must update the RPI subsystem definition whenever you test a procedure from a new procedure file.

Ensuring the procedure to be tested is defined as a process

For each procedure to be tested, supply a DEFINE PROCESS command that includes the following parameters:

SUBSYSTEM=RPI SUBSYSPARM='[file] [procedure] [OPEN | NOOPEN]'

Where:

  • file is the Model 204 procedure file containing the procedure.
  • procedure is the name of the procedure to be invoked.
  • OPEN is appropriate if the procedure file is not defined to the RPI subsystem and RPI must try to open it.
  • NOOPEN is appropriate if the procedure file is defined to the RPI subsystem and has been automatically opened.

For example, the DEFINE PROCESS command below allows server process ANSWERQ to run the RPI subsystem and invoke the ad hoc procedure MYPROC from TESTFILE, as specified in SUBSYSPARM.

DEFINE PROCESS ANSWERQ WITH SCOPE=SYSTEM DATALEN=2048 - FROM=BOULDER SUBSYSTEM=RPI - SUBSYSPARM='TESTFILE MYPROC OPEN'

Application developer responsibilities

The application developer testing under RPI must know the following:

  • The communication global variable for RPI is COMM. Every procedure being included is responsible for setting this.
  • The exit value for COMM is EXIT. The inbound procedure must set this when it terminates.

As always, neglecting to set the communication variable leads to looping or other errors. An inbound process that is looping does not usually call attention to itself until it fills up the CCAAUDIT file.

  • You cannot use RPI to test a procedure that expects to receive data in the command line global variable. This variable is reserved for use by RPI.