Horizon connections to non-Model 204 systems

From m204wiki
Revision as of 21:43, 16 October 2015 by ELowell (talk | contribs) (→‎Connecting to VAX/VMS: - deleted obsolete section)
Jump to navigation Jump to search

Connecting to CICS

Compared to a Model 204-to-Model 204 Horizon conversation, a Model 204-to-CICS Horizon conversation requires some additional conceptual understanding (of the CICS side) but little additional programming effort for the Model 204 side. The Model 204 network administration adjustments to CICS protocols are largely transparent to the programmer. There are no changes to the Horizon conversation interface "verbs."

This overview presents a discussion of how Horizon and CICS connect. The rest of this section describes how to prepare the SNA Communications Server (formerly VTAM), Model 204, and CICS network definitions and how to implement and maintain the operation of the connection.

Horizon connectivity versus CICS Interface connectivity

Horizon connectivity to CICS differs in several respects from the CRAM-based Model 204 CICS (terminal) Interface:

  • The Model 204 CICS Interface operates only when the Model 204 and CICS systems are resident on the same z/OS machine. Horizon connects to CICS on the same or on a widely separated machine.
  • Special Model 204 software or SVCs or both must be installed in CICS and z/OS for the CICS Interface, but not for Horizon. In Horizon, software in Model 204 communicates peer-to-peer with native CICS software.
  • The CICS Interface is primarily a means for a CICS-controlled terminal user to run programs in Model 204. Horizon is a means for CICS and Model 204 application programs to converse and share data as peers.
  • The application programming in CICS that corresponds to Horizon SOUL programming is done with a set of extensions to CICS Command Level programming. Like Horizon SOUL statements, these CICS commands each correspond, often very closely, to an APPC verb.
  • Horizon connectivity is through SNA Communications Server. Both Model 204 and CICS therefore must implement "logical units" to serve as their entry points into the SNA network. In Model 204, this entry point is the Horizon "link," of which there may be several. In CICS, this entry point is the single LU that also serves the CICS terminal handler.

The following figure shows the components of the Horizon/CICS environment. LU 6.2 conversations between CICS transactions and Model 204 procedures can be started from a terminal controlled by either system.

The Horizon/CICS environment

One LU for CICS; multiple LUs for Model 204

In the previous figure, "The Horizon/CICS environment", CICS has one LU and Model 204 has several. This does not imply any essential difference between the two systems. Model 204's ability to provide more than one link simply offers some extra flexibility in system management. The cost is some added complexity in system administration.

For example, you can assign one link for applications transferring large amounts of data between the two systems per request, and you can assign one link for applications with heavy request volume but relatively short data transfers per request. Such a scheme optimizes response time. The cost is that you have to maintain extra definitions for the second link and its associated processgroups.

"The Horizon/CICS environment" shows many sessions in progress simultaneously between CICS and one of the Model 204 links. Such a configuration is called "parallel sessions." A simpler configuration is possible: each Model 204 link can support just one session, with users employing that session for program-to-program conversations in series, that is, one after the other.

Note: Separate additional links per CICS region are required if Model 204 connects to more than one CICS region simultaneously. For more information about this, see Network definition requirements.

Supporting CICS parallel sessions

To support the parallel sessions configuration between CICS and Model 204, you must prepare "CNOS" support: support for special intersystem protocols used by the system software for setting up, terminating, and dynamically controlling the sessions between the two systems.

CNOS support preparation is described in Horizon CNOS connections. This preparation includes updating the SNA Communications Server "logmode" definitions and APPL statements, as well as updating definition commands in Model 204 and CICS.

SNA Communications Server Definition Statements

This section describes the SNA Communications Server network preparation required for LU 6.2 support: updating the SNA Communications Server "logmode" definitions, determining session parameters, and coding the APPL statements.

Preparing the log mode definitions

Mode table configuration, including an example of recommended mode table entry values for Horizon, is discussed in Defining the network to SNA Communications Server.

The following are recommendations for mode table configuration:

  • Use only one table for all LU 6.2 sessions, between all systems. Let this table's first entry--which serves as the default entry--be the most widely applicable one, such as the one with the values for single-session support recommended in Horizon network management.
  • If using CNOS sessions, include an SNASVCMG entry and an entry with parallel session support somewhere in the table.
  • Code the table's name on the MODETAB parameter of the APPL statements for both CICS and for each of the Horizon links in MODEL 204.
  • Omit the DLOGMOD parameter.
  • For all but CNOS connections, omit the MODENAME parameter on both the Horizon PROCESSGROUP and the CICS CONNECTION definitions.
  • For CNOS connections, include MODENAME in the Horizon PROCESSGROUP and the CICS CONNECTION definitions. This MODENAME will be the name of the parallel-sessions entry in the single, common mode table for LU 6.2.

Determining session characteristics

When sessions are started from Model 204, the SNA Communications Server session parameters are determined by reference to the Model 204 network entity definitions, the APPL statements for CICS, and the common mode table for Horizon and CICS LU 6.2. Finally, the session parameters are checked by CICS against CICS definitions before the bind is accepted.

The following figure, "SNA Communications Server session parameter selection", shows the steps in the bind selection process when Model 204 initiates the process. The mode table configuration in the following figure allows a common, default entry to be chosen when no MODENAME is specified in the Model 204 definitions (sequence (A) in figure) and a specific entry for CICS parallel-session support (sequence (B) in figure) when the entry is specified on the DEFINE PROCESSGROUP command. Such a configuration is recommended for connections between Horizon and CICS.

When sessions are started from CICS, the bind process steps in the following figure are reversed.

SNA Communications Server Session Parameter Selection

Following is a brief description of the sequence in the previous figure:

Step Description
(1) The session is started from Model 204. The processgroup name specified after the AT parameter indicates where (with which processgroup and link definition) to find the session characteristics.
(2) MODENAME, if any, points to a specific mode table entry. If MODENAME is not specified (as shown), the default mode table entry is used.
REMOTEID indicates the CICS LU.
(3) The SNA Communications Server APPL statement for the CICS LU points to the common mode table, TABLU62.
(4) TABLU62, the common mode table, the name of which precedes the list of entries. The first entry in the list, here MODELU62, is the default. As recommended in Preparing the log mode definitions, the default entry specified is the one with the session parameters for single-session support.
(5) The CICS connection definitions are checked by CICS when the Bind arrives.
(6) The result is a Bind for single-session support.

Coding the APPL statement

The APPL statements for the Horizon links to CICS are identical to those for Model 204-Model 204 links.

Typically, you have to modify the CICS APPL statement to include parameters relevant to LU 6.2 support (PARSESS=YES, etc.). You need to add a MODETAB parameter, since other than LU 6.2 connections, CICS will not have been the secondary LU in any application. The MODETAB parameter should point to the common LU 6.2 table, as stated in the mode table configuration recommendations in Preparing the log mode definitions.

Model 204-Side Definition Commands

The DEFINE command specifications prepare the Model 204-side of the connection to CICS. The CICS and Model 204 staffs must coordinate at definition time with regard to the names used (for REMOTEID, PARTNER, and so on).

For information about the DEFINE commands for CNOS parallel sessions, see Horizon CNOS connections.

Network definition requirements

The DEFINE command specifications listed below are modified or require special attention for CICS single-session support.

  • DEFINE LINK command PROTOCOL parameter

    One Horizon link must be reserved for each CICS system to which the Model 204 system connects. Each of these links appears to CICS to be a separate system.

  • DEFINE PROCESSGROUP command MODENAME parameter

    The MODENAME parameter is required on the definition for the processgroup whose REMOTEID parameter points to the CICS partner. More than one processgroup can be defined for this link, but the MODENAME (and REMOTEID) must be the same on each.

    (On the CICS side, CICS online resource definition or CICS DFHTCT macros specify the LU/mode definition (CICS "connection" and "sessions" definitions) which identifies the Model 204 system. If more than one processgroup, as mentioned above, is defined on the Model 204 side for the Horizon link, the CICS definitions do not change in any way.)

  • DEFINE PROCESS command PARTNER parameter

    The PARTNER parameter value must be the four-character CICS transaction ID in which the CICS partner program is to run.

  • DEFINE PROCESS command PARTNER parameter

    The PARTNER parameter value must be the four-character CICS transaction ID in which the CICS partner program is to run.

  • DEFINE LINK command SESSIONS parameter and DEFINE PROCESSGROUP command INLIMIT and OUTLIMIT parameters

    The CICS and Model 204 staffs must coordinate with regard to initial values for session limits specified on the Model 204 DEFINE PROCESSGROUP command and on the CICS DEFINE SESSIONS. It is suggested that the total be set high and that it be divided equally between inbound and outbound sessions.

    That is, let SESSIONS on the DEFINE LINK command be high, and let the INLIMIT value equal the OUTLIMIT value on the DEFINE PROCESSGROUP command. These Model 204-side values are to correspond to two values on the CICS SESSIONS MAXIMUM definition, as follows:

    • The total number of application sessions allowed with the named Model 204 link is indicated by the first MAXIMUM value in CICS and by the sum of INLIMIT and OUTLIMIT in Model 204.
    • The number within the above total reserved for sessions on which CICS is assured to win any contention for a chance to start an application conversation is indicated by the second MAXIMUM value in CICS and by INLIMIT in Model 204.

    The difference between the two CICS MAXIMUM values is the number of sessions on which CICS defers to Model 204 when both wish to use the session.

    Note: The Model 204 DEFINE LINK SESSIONS value should include two extra control sessions which are not used for applications. None of the values on the processgroup definition (and none of the CICS values) includes these two extra sessions.

CICS-Side Definition Commands

The CICS Inter-communication Facilities Guide explains the statements and parameters needed to configure LU 6.2 connections in CICS. Especially relevant to CICS connections to Model 204 are the CICS CONNECTION and SESSIONS definitions. These definitions, taken together, roughly correspond to the Model 204 PROCESSGROUP definition.

LU 6.2 network definition considerations

This section discusses aspects of the CONNECTION and SESSIONS definitions that are important for Model 204 LU 6.2 connections.

Parameter names used are for CICS RDO.

  • MODENAME (on SESSIONS) is required for both single- and parallel-session connections.
  • SINGLESESS (on CONNECTION) determines whether or not parallel sessions are supported (SINGLESESS=N invokes the support).
  • BINDPASSWORD (on CONNECTION) must be left blank.
  • There are two values required on MAXIMUM (on SESSIONS). The first of these refers to the total number of concurrent application sessions allowed with any one Model 204 "link." The second specifies the number of sessions out of the total on which CICS will be assured the ability to start a conversation.
  • RECEIVESIZE and SENDSIZE (on CONNECTIONS) are the maximum values CICS allows for RUSIZES on a Bind from another system. CICS negotiates the Bind values downward to these values. For ease of administration, code all values the same: the two values for RUSIZES in the logmode entry and these two CICS parameters. 2048 is a good value.

Security considerations

The levels of security support for conversations invoked from the Model 204 side are specified on the ATTACHSEC parameter (on CONNECTION). They should correspond to Horizon security values as shown in the following table:

CICS LU 6.2 Security Support Compared to Horizon

CICS side Model 204 side
LOCAL IDSOURCE=NONE (no security)
IDENTIFY LOGIN=TRUST +

UIDSOURCE=OPEN or
UIDSOURCE=CURRENT

(Model 204 sends user ID but no password)
VERIFY UIDSOURCE=OPEN or

UIDSOURCE=CURRENT +
OPEN PROCESS PASSWORD

(Model 204 sends user ID and password)

Note: For conversations invoked on the CICS side, the security level is always equivalent to "identify": CICS always sends a user ID but never sends a password.

Specifying the Model 204 partner program

In CICS, the partner program name for conversations invoked from the CICS side is not specified on a definition statement, but rather in the application program's EXEC CICS CONNECT command. The PROCNAME parameter on this command must be the appropriate process name in Model 204.

Note: CICS insists that the PROCNAME parameter name be four characters in length. Hence, the name of a server process invoked from CICS also must be four characters in length.

Maintaining Operations

This section describes the principal operating functions for each side in Horizon to CICS conversations: establishing the connection, changing session limits, and executing an orderly shutdown.

Establishing the connection

Once the Horizon link is open and the CICS connection definitions are put "in service," you can set up the connection between the two systems. "In service" status in CICS does not involve ACB open as does Horizon's OPEN LINK, but is similar to "started" status for the link in Horizon. Like link opening in Horizon, however, it can be configured to occur automatically at system startup, instead of by doing CEMT I CONN followed by ACQ.

Since you can initiate the connection setup from either system, choose one system as the focal point for control of connection. Using one system as the focal point simplifies the establishment and takedown of the connection.

When Model 204 is the focal point

If Model 204 is designated as the focal point, the first outbound process of the run that is opened on the link, before its open completes, accomplishes the establishment of the connection. The Model 204 system administrator has no special commands to issue.

When this first conversation opens, the MONITOR LINK command display shows two control sessions active on the link in addition to the application session. "X" in the session FLGS (flags) column on the display indicates these control sessions. "S" indicates that Model 204 was the source of the connection. "T" indicates that CICS started the connection and Model 204 was, in CNOS terminology, the connection "target."

The audit trail shows a message stating the names of the link, processgroup (for the application process just opened), and CICS LU name and that the connection is established. If the SOUL program issues $ERRMSG, the same message is displayed as that on the audit trail. Otherwise, the connection establishment process is transparent to the program.

Should the connection attempt fail at any time during set up of the control sessions or during CNOS Initialize exchange, the status of the connection is reset entirely and a second conversation attempt is allowed to try the connection process again. Failure audit messages record the attempted connection and the reason for the failure. The program attempting the first OPEN PROCESS may detect a failure in the connection process as a $STATUS/$STATUSD code of 13/3 or 53/3.

When CICS is the focal point

If CICS is the focal point, the CICS operator must "bring up the link" to Horizon as a regular, system startup activity. CICS log messages record the session limits specified in the CNOS Initialize exchange. Horizon's MONITOR LINK will show two idle control sessions active. Either CICS users or Model 204 users may then start conversations.

Changing CNOS session limits

At any time while the connection is up, the CICS operator can decrease the session limits on the connection with a CEMT SET MODENAME command. Horizon will overlay its current session limits with values carried in the CNOS Change command from CICS, and it will return a positive CNOS Reply. The new values are accepted or negotiated according to SNA standards.

In addition, CICS implements the session deactivation aspect of CNOS Change, whereby the CNOS sender designates one partner to be responsible for terminating those sessions in excess of the new limits. Since CICS always designates the CNOS "source" to do the termination, the Horizon system administrator sees some number of sessions lost. The audit messages reporting the lost sessions will not themselves refer to the CNOS Change process. However, they will be preceded by a message stating the receipt of the CNOS Change command from CICS.

For more information about Horizon CNOS support, see Horizon CNOS connections.

Executing an orderly shutdown

You can bring down a connection, as well as start one up, from either the Model 204 or the CICS side. To close the connection cleanly, however, the CICS side should implement shutdown procedures.

Shutdown from the Model 204 side

From Model 204, CLOSE LINK FORCE or EOJ bring the connection down in an unpredictable manner. Although there are no system abends or the like on the CICS side, and the connection is still re-startable from this point, the CICS log registers some peculiar system level errors.

Shutdown from the CICS side

Orderly shutdown from the CICS side does not involve ACB close. The following sequence of actions occurs:

  • The operator "takes down the link" with Model 204 by the CEMT SET CONNECTION RELEASED command.
  • Horizon prohibits outbound conversations. A message is audited stating that connection shutdown has begun by request from the CICS side.
  • CICS proceeds to drain all active application sessions and then terminates each session. The application sessions are terminated first, the two control sessions last.
  • When the control sessions end, the completion of the connection reset process is recorded on the audit trail.

Either side may now restart the connection at any time.

Connecting to OS/2 EE

This section discusses requirements for LU 6.2 conversations between OS/2 EE and Model 204. It is assumed that members of both staffs will coordinate with regard to the names and values used to meet the network definition and data transmission protocols. Information here is provided according to responsibility: there are sections for SNA Communications Server system programmers and application programmers, or their equivalents.

OS/2 products needed to support the connection

On each workstation involved in a program-to-program application with Model 204, OS/2 EE Communications Manager must be installed. This includes the APPC files required to compile programs that issue APPC requests.

A variety of physical link types are supported for connecting to the mainframe, among them SDLC and Token Ring (to channel-attached TR gateway). In addition, APPC is supported by OS/2 in an SNA Gateway configuration, where only one workstation need provide the physical link to the mainframe.

SNA Communications Server system programmer considerations

Special SNA Communications Server/NCP definition items are required:

  • When defining the PC's LUs to SNA Communications Server/NCP, the SNA Communications Server logo screen should not be displayed to the PS/2. This logo ("message 10") should be suppressed. Neglecting to suppress this message causes session binding to fail.

    This logo suppression can be done in either of two ways:

    • Not specifying a USS table in the SNA Communications Server APPLID
    • Pointing to a table that does not include the terminal operator messages

    Note: The IBM default USS table (ISTINCDT) does not include an MSG 10.

  • On an SDLC line, the SDLC window size (which in NCP is represented by the MAXOUT parameter on the PU macro for the PC LU) must also be entered in Communications Manager under the SDLC DLC ADAPTER PROFILE panel. The two values to adjust are:
    • Send window count
    • Receive window count
  • Large RUSIZES should be specified using the RUSIZES in the LOGMODE entry for the APPLID. A value of X'8888', representing 2K, is recommended. Also, in Communications Manager under the SDLC ADAPTER PROFILE panel, the maximum RUSIZE should be adjusted to reflect the 2K value.
  • On a switched SDLC line, the NODE ID on the SNA BASE PROFILE in Communications Manager must be in sync with the IDNUM parameter on the PU macro for the IBM PS/2 LU. Also, you must enter a value of "05D" in the IDBLK parameter in the PU macro.
  • You can use the recommended logmode table entry shown in the logon table section.

Application programmer considerations

IBM provides several sample programs written in C, FORTRAN and PL1. For testing, the C file requestor program was customized for Model 204. In this customizing process and APPC coding in general, there are several things to keep in mind:

  • On the TP_STARTED APPC command:
    • The lu_alias must be equal to the LU Alias specified on the LOCAL APPC LOGICAL UNIT PROFILE window in Communications Manager.
    • The tp_name should be equal to the name of the program on the workstation (that is, the XXXXXXXX.EXE module).
  • As a result of the TP_STARTED command, a tp_id is returned. This tp_id must be used on all future APPC calls.
  • On the MC_ALLOCATE APPC command:
    • The plu_alias is equal to the LU alias found on the PARTNER LU PROFILE window in Communications Manager.
    • The tp_name must be equal to the name of the process in Model 204 that is being used as the server routine (this must be presented in EBCDIC).
    • The mode_name must be equal to the Mode Name found on the TRANSMISSION SERVICE MODE PROFILE found in Communications Manager (this must be presented in EBCDIC).
    • Optionally, the pwd and user_id used to logon to Model 204 are included in the MC_ALLOCATE command (these must be presented in EBCDIC).
  • On the MC_SEND_DATA command, any data passed to Model 204 must be converted to EBCDIC before the command is executed.
  • On the MC_RECEIVE_AND_WAIT command, any returned data from Model 204 must be converted to ASCII after the command is executed.

    Note: The same memory location used for APPC calls is also used for the APPC SV_CONVERT routine. As a result, primary return codes, secondary return codes, and what-received indicators must be either saved or analyzed prior to executing the conversion routine. Failure to do so results in invalid processing due to the examination of returned values that have changed.

  • On the SV_CONVERT command, use the SV_G character set. It converts more characters than the SV_AE character set does, and it is user modifiable. The table is under the name supplied on the WORKSTATION PROFILE window in Communications Manager under the Translation Table File Name prompt.

Connecting to UNIX System V and AT&T LU 6.2 Facility

The AT&T LU 6.2 Facility is a software package for the AT&T workstations (3B1s, 3B2s) that run UNIX System V. UNIX System V uses SNA LU 6.2 to communicate with other LU 6.2 supporting platforms.

This section discusses requirements for LU 6.2 conversations between the AT&T LU 6.2 Facility and Model 204. It is assumed that members of both staffs will coordinate with regard to the names and values used to meet the network definition and data transmission protocols. Information here is provided according to responsibility: there are sections for SNA Communications Server system programmers, system managers, and application programmers, or their equivalents.

Products needed to support the connection

  • AT&T LU 6.2 Facility
  • AT&T 3B1,B2 workstations running UNIX System V.

SNA Communications Server system or network considerations

Special SNA Communications Server/NCP definition items are required:

  • The EXCHID on the UNIX system for LOCAL NODE (switched lines only) must match the SNA Communications Server/NCP Major Node definition for PU: that is, EXCHID must equal IDBLK plus IDNUM. For example:

    If IDBLK=03E and IDNUM=0002, EXCHID=03E0002

  • AT&T LU 6.2 LINE definition parameter MAX_BTU must equal SNA Communications Server/NCP PU's MAXDATA. If HDX=YES on the AT&T LINE definition, set DUPLEX to HALF on the SNA Communications Server/NCP LINE definition. If HDX=NO, set DUPLEX to FULL.
  • Let NRZI=NO for both the AT&T LU 6.2 LINE definition and the SNA Communications Server/NCP GROUP definition.
  • AT&T LU 6.2 entity STATION parameter ADDRESS must equal SNA Communications Server/NCP PU's ADDR.
  • The SNA Communications Server/NCP LU pacing parameters VPACING and PACING must match the AT&T MODE definition parameters SPCT and RPCT, respectively.

System manager considerations

The REMOTEID parameter on the Model 204 DEFINE PROCESSGROUP command must match the UNIX LOCAL LU NNAM parameter. The LOCAL LU is similar to the SNA Communications Server/NCP LU, and both addresses must match.

The UNIX REMOTE LU NNAM parameter must match the Model 204 DEFINE LINK command LOCALID parameter.

Application programmer considerations

Sample programs used to demonstrate the UNIX System V and AT&T LU 6.2 Facility connection to Model 204 duplicated the C program flow from the AT&T 3B2 Computer AT&T LU 6.2 Facility Administrator's and Programmer's Guide, Release 2.0.

ASCII to EBCDIC conversion must be done on the UNIX side.
C subroutines are provided to do this.

If you pass a user ID and password from the UNIX System V workstation to Model 204, avoid mixed case. It is necessary to force UPPERCASE to avoid errors.

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Horizon_connections_to_non-Model_204_systems&oldid=81182"