DEFINE PROCESSGROUP command: Horizon for VTAM

Summary

Privileges: User 0 or system manager
Function: Connects the process to a specific link, identifies the remote node, and provides a pool of sessions to be used by multiple processes. It also groups processes by attributes, such as the maximum number of concurrent conversations, to facilitate resource allocation by application.

Syntax

DEFINE PAROCESSGROUP name [LIKE previousname] WITH SCOPE=SYSTEM LINK=linkname REMOTEID=applid [INLIMIT={nnnn | 0}] [OUTLIMIT={nnnn | 0} | NOINLIMIT] [RETAIN={nnnn | RETAINALL}] [MODENAME=mode-ent] [LOGIN={TRUST | NOTRUST}] [GUESTUSER={ACCEPT | REJECT}]

Where:

name

is used on DEFINE PROCESS commands to refer to this group of processes. The length of the name must be eight characters or less. If more than one processgroup is defined, each must be unique. ALL is a reserved word and cannot be used.

LIKE

is optional and gives the processgroup currently being defined the attributes of the processgroup referred to by previousname. If you specify LIKE previousname, you must specify WITH SCOPE=SYSTEM.

SCOPE=SYSTEM

indicates that the definition is available to all users of the Model 204 system for the entire run.

LINK

is used to associate the processgroup with a locally defined link that implies the transport type and the conversation protocol. linkname must be the same as specified on a local DEFINE LINK command.

REMOTEID

is the name of the LU at the remote node with which the processgroup communicates. This name is the SNA Communications Server APPL definition name (applid value) of the remote node. This REMOTEID value must match the LOCALID value specified on the DEFINE LINK command at the remote node.

INLIMIT

sets the maximum number of concurrent inbound conversations, that is, conversations initiated by the partner. INLIMIT=0, the default, indicates that no inbound conversations are allowed. If INLIMIT=nnnn is specified, the maximum value is 9999.

NOINLIMIT specifies that there is no limit on the number of inbound conversations. INLIMIT=nnnn and NOINLIMIT are mutually exclusive.

OUTLIMIT

limits the number of concurrent outbound conversations. OUTLIMIT=0, the default, specifies that no outbound conversations are allowed. If OUTLIMIT=nnnn is specified, the maximum value is 9999.

NOOUTLIMIT specifies that there is no limit on the number of outbound conversations. OUTLIMIT=nnnn and NOOUTLIMIT are mutually exclusive.

RETAIN

specifies the number of sessions retained as each conversation ends. RETAIN=0 specifies that a session is released when it ends. If RETAIN=nnnn is specified, the maximum value is 9999.

RETAINALL specifies that each session started is retained for the length of the run. RETAIN=nnnn and RETAINALL are mutually exclusive options. The default is RETAINALL.

The system manager can define as many sessions on the link as required by the processgroups and cannot specify a RETAIN value on any of the processgroup definitions.

MODENAME

refers to the SNA Communications Server mode table entry to be used when a SNA Communications Server session is established for an outbound conversation. The most significant item in the mode table is the size of the RU (request/response unit) to be shipped between the two nodes.

Mode table entries can be tuned for network utilization, for the applications using the session, and for the class of service (COS) table entry name. If no MODENAME is specified, the mode table entry associated with the REMOTEID value is used to establish the session.

LOGIN

specifies whether a local server process requires a password from the remote client process at OPEN FILE time. Valid values are TRUST and NOTRUST. These options are reflected in and must agree with the SNA Communications Server logmode entry PSERVIC setting.

TRUST

specifies that the local system manager trusts the remote system to verify a user ID shipped in an inbound conversation request. The incoming user is, therefore, logged in without a password at the local server process and assigned privileges from either CCASTAT or an external security package. However, if a password is provided, it is used; if it is invalid, login fails.

TRUST is required for Parallel Query Option/204.

NOTRUST

, the default, specifies that the local system manager requires a valid password to be present in the inbound conversation request.

GUESTUSER

permits a user who is defined in neither CCASTAT nor an external security package to log in with privileges of X'00'. Such a user is referred to as a guest. Login user privileges are listed in the LOGCTL command description. GUESTUSER options follow:

ACCEPT

indicates that guest users are accepted. The guest enters a subsystem and is assigned login privileges by the subsystem. This option relieves the server's system manage from having to define every individual client user in the server's security database. Accepting guest users implies that the server system manager has confidence in Application Subsystem security to protect the server program.

An end user at a terminal can never be a guest user. This status is reserved for client users, who have no choice about which subsystem they are destined for, and who inevitably pass through Application Subsystem security processing.

REJECT

, the default, prohibits guest users; any guest user LOGIN fails.

Example

In the basic Horizon definitions below, the PARTS processgroup supports seven outbound conversations and no inbound conversations. It points to the remote Model 204 system identified to the network as M204B. The INVENTRY processgroup supports two outbound conversations and five inbound conversations. It points to the remote Model 204 system identified to the network as M204A.

DEFINE PROCESSGROUP PARTS WITH - SCOPE=SYSTEM - LINK=LINK1 - REMOTEID=M204B - OUTLIMIT=7 - INLIMIT=0 - RETAIN=3 DEFINE PROCESSGROUP INVENTRY WITH - SCOPE=SYSTEM - LINK=LINK2 - REMOTEID=M204A - OUTLIMIT=2 - INLIMIT=5 - RETAIN=1

Usage notes

The DEFINE PROCESSGROUP command connects the processes associated with the named processgroup to a specific link. The processgroup definition can control the number of simultaneous conversations and direct the conversation to a remote node (specified in REMOTEID) with which the associated processes can communicate. Multiple processgroups can be defined with the same remote ID.

There must be at least one processgroup definition on a server for each client node and at least one on a client for each server node.

A Model 204 site may use different processgroup definitions to segregate groups of processes, for example, to isolate groups that participate in Model 204-to-Model 204 Horizon conversations from those that participate in Model 204-to-CICS Horizon conversations.

The RETAIN parameter limits the number of sessions with a particular remote node so that sessions can be free to be used by processgroups associated with other remote nodes. This is a variation from the architected LU 6.2 function (and the RETAINALL default) which specifies that all sessions, once activated, are always retained for a particular conversation partner and reused throughout the run.

Limiting sessions shared between processgroups

The RETAIN parameter may be used to limit the number of sessions that are shared between processgroups. A shared session is reused when a process using the session pool is opened. Sharing reduces the amount of network traffic and associated time required to bind and activate a session. This allows resources to remain allocated to busy processgroup definitions and to be released by those less frequently used.

A pool of sessions is shared between processgroups if the processgroups have the same values for these four parameters:

LINK REMOTEID MODENAME LOGIN

The number of sessions that are shared is determined by summing the values of the RETAIN parameter for all of the processgroups in the pool. As each new processgroup associated with the LINK-REMOTEID-MODENAME-LOGIN combination is processed, the value of the RETAIN parameter is added to the total number of sessions retained.

For example, if one processgroup specifies RETAIN=4, four sessions are retained. A second processgroup, pointing to the same shared sessions parameter combination as the first, specifies RETAIN=5. The five sessions are added to the previous RETAIN value total of four, and the total number of sessions retained becomes nine. These nine sessions can be used by processes belonging to either processgroup.

At any time, if a processgroup that specifies RETAINALL is encountered, all sessions are retained and can be used by processes belonging to any processgroup that is sharing sessions. RETAINALL overrides any RETAIN values.

When using the RETAIN parameter with pooled sessions, it is possible that the limit set by the SESSIONS parameter of DEFINE LINK may be exceeded. In the example above, if the corresponding DEFINE LINK specifies SESSIONS=4 and the number of retained sessions becomes nine, the conversation request fails.

You can also use the INLIMIT and OUTLIMIT parameters to define as many sessions on the link as are required by the processgroups without specifying a RETAIN value on any of the processgroup definitions. RETAINALL is the default, so each session activated for an inbound or outbound conversation (within the limits) is retained. The minimum number of sessions required by requesting and servicing processgroups on the link are always available.

The names for the link and processgroup entities for a given link are system-specific and are not pointed to by other systems in the network, unlike the LOCALID value of DEFINE LINK and the REMOTEID value of DEFINE PROCESSGROUP. Thus, you may assign the link and processgroup entities any names you choose, even names that are used on other systems. Also, they need not be changed if, for example, the LOCALID value of DEFINE LINK or the REMOTEID value of DEFINE PROCESSGROUP is changed.