DEFINE PROCESS command: Horizon for TCP/IP and VTAM

Summary

Privileges

User 0 or system manager

Function

Defines a Horizon process for reference by User Language statements

Syntax

DEFINE PROCESS name [LIKE previousname] WITH SCOPE=SYSTEM DATALEN=nnnnn [TIMEOUT=nnnnn] [CONFIRM | NOCONFIRM] {client-options | server-options}

client-options

DESTINATION={processgroup | (pg1,sym1,pg2,sym2,...)} PARTNER=partnername [UIDSOURCE={NONE | CURRENT | OPEN}] [{ACCTSOURCE= | PROFSOURCE=}{NONE | CURRENT | OPEN}] [RESTRICT={NONE | APSY}]

server-options

FROM=(pg1 [,pg2]...) SUBSYSTEM=subsystemname [SUBSYSPARM='subsystem-parameter-line']

Where:

• name:

  • Refers in client OPEN PROCESS statements to the client (outbound) process, which initiates the conversation

  • Associates a server (inbound) process, which accepts a remote request, with a subsystem

  • Must be one of the following for Parallel Query Option/204 processes:

    If a server, name must be CCAD2S

    If a client, name must be CCAD2C

    The length of name must be eight characters or fewer. The keyword ALL and any names prefixed with CCA are reserved and cannot be used.

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

• SCOPE=SYSTEM is required and indicates that the process entity definition is available to all users of the Model 204 system for the entire length of the online run.

• DATALEN specifies the size of a Horizon conversation buffer. Data is shipped over the session from the sending side's conversation buffer to the receiving side's conversation buffer. Set DATALEN greater than or equal to the largest IMAGE size, %variable length, or SQL data packet shipped over the session. An insufficiently large conversation buffer causes inefficient sending of data or some truncation of data received.

  Each SQL logical record (SLR) is packaged as one or more chunks called general data streams (GDSs). GDS size depends on the data buffer length. Each GDS is packaged and shipped across the network as on or more network units:

  • SNA Communications Server request units (RUs), the SNA Communications Server mode entry parameter RUSIZES sets the RU size.

  • TCP/IP transmission units (TUs), the TCP/IP size is fixed at 4096 bytes.

  To set DATALEN, you should consider both GDSs received and GDSs sent.

  • To accommodate GDSs received, DATALEN must be greater than or equal to the client data length setting (the PC client configuration parameter Datalen or Data Buffer Length, or the TCP/IP environment variable datalen).

  • To optimize performance for GDSs sent, DATLEN should be equal to the since-last statistic setting plus five, to a maximum of 4101.

    DATALEN is not used for PQO processes.

    The DATALEN minimum is 537 and the maximum is 32763.

    DATALEN and the DEFINE LINK command parameter INBUFSIZE are independent. They refer to different buffers.

• TIMEOUT provides a terminal timeout facility. It specifies the number of seconds a thread waits for the completion of a User Language request that involves a physical network transmission.

• CONFIRM, FLUSH, and RECEIVE are examples of User Language statements that cause a physical network transmission. For example RECEIVE may wait for a reply no longer than the value of TIMEOUT for a physical network transmission.

• If the TIMEOUT limit is exceeded, the session is abnormally terminated. Specify the time in seconds. Zero is the default; it indicates no time limit.

• CONFIRM or NOCONFIRM specifies whether or not the applications can perform confirmation processing through the use of the User Language CONFIRM statement. CONFIRM or NOCONFIRM determines at OPEN PROCESS time the synchronization level (SYNCLEVEL) that the client and server processes can use on a conversation. The default is NOCONFIRM.

  A client process and its corresponding server process must both specify the same CONFIRM value for any OPEN PROCESS request to succeed.

  CONFIRM and NOCONFIRM are not used for PQO processes.

Client process options

DESTINATION associates the process with a processgroup. In turn, the processgroup links the process with a remote site and internal resource limit group. The processgroup can be either a single client processgroup or a list of paired items with the following format:

pg1,sym1,pg2,sym2 ...

Where:

pg1, pg2, ...	are processgroup names and must be the same as the processgroup names specified on DEFINE PROCESSGROUP commands.
sym1, sym2, ...	are symbolic names that can be used with the AT parameter of the OPEN PROCESS User Language statement to refer to the processgroup(s) associated with the symbolic name(s). If DESTINATION=processgroup is specified, then the process is associated with that processgroup. If DESTINATION=(pg1,sym1, pg2,sym2, ...) is specified, the process can be associated with any of processgroups pg1, pg2, and so on when the OPEN PROCESS statement is issued. The AT parameter of the OPEN PROCESS must specify one of the symbolic destinations, whereupon the corresponding processgroup for that symbolic destination becomes the actual destination. If the AT parameter is not used in the OPEN PROCESS statement, the first processgroup (pg1) is used. For PQO processes, only a symbolic destination name specified here can be used with AT to specify a remote file location. If the value of DESTINATION is specified in processgroup-symbolic name format, each processgroup included must be paired with a symbolic name (and vice versa) or the DEFINE PROCESS command is rejected. A benefit of using symbolic names within a User Language request is that a system manager can change actual processgroup names without affecting the application program. For example, the DEFINE PROCESSGROUP command has: DESTINATION=(PGRP1,BOSTON) The OPEN PROCESS statement is: OPEN PROCESS name AT BOSTON Then the system manager can change the processgroup name, PGRP1, without having to modify the User Language application.
PARTNER	specifies the name of the conversation partner program. It is the same name used on the DEFINE PROCESS command for the server process at the remote node. PARTNER is not used for PQO processes.
UIDSOURCE	specifies the source of the user ID to be used for login at the remote node: NONE causes Model 204 not to transmit any user ID, password, or account number to the remote node. This must be used when the remote partner does not accept any security information from Model 204. NONE is the default value. CURRENT means that at OPEN PROCESS time, the current user ID is transmitted for LOGIN at the remote node. If the user is not currently logged in, no user ID is transmitted. OPEN permits the User Language request to specify the USERID and PASSWORD operands on OPEN PROCESS and override the current user ID value. The system manager might wish to disallow this to maintain tighter control over which user ID a local user can be known as at a remote node. UIDSOURCE is not used for PQO processes.
ACCTSOURCE	and PROFSOURCE specify options for ACCOUNT or PROFILE on the OPEN PROCESS statement similar to those for UIDSOURCE. ACCTSOURCE and PROFSOURCE are not used for PQO processes.
RESTRICT	specifies whether the User Language OPEN PROCESS statement can be issued outside of an application subsystem. If set to APSY, OPEN PROCESS fails if issued outside of an application subsystem. If set to NONE (the default), OPEN PROCESS is allowed outside of an application subsystem management facility subsystem. RESTRICT is not used for PQO processes.

Server process options

The following options are valid only for server processes.

FROM	associates the process with one or a set of processgroups. The values of pg1, pg2, and so on must be the same as the processgroup names specified on DEFINE PROCESSGROUP commands at the server. A request for the server process received from a client node is accepted only if all the following requirements are met on a definition of one of the server processgroups pg1, pg2 and so on: LINK value matches the link to which the request is directed. REMOTEID value matches the client node name. LOGIN value matches the client processgroup at the remote node. The first processgroup in the FROM list that matches the REMOTEID and LOGIN indicator on the incoming conversation request is always used. The matching processgroup associates the process with internal resource limits such as the maximum number of concurrent conversations.
SUBSYSTEM	indicates the Model 204 application subsystem invoked by an inbound conversation request.
SUBSYSPARM	indicates the subsystem parameter line to be passed to this SUBSYSTEM. The maximum length is 255 characters. SUBSYSTEM and SUBSYSPARM are not used for PQO processes. When the server subsystem is invoked, the SUBSYSPARM value string is stored in the command-line global variable specified in the subsystem definition. If the subsystem definition does not specify a command line global variable, SUBSYSPARM is ignored. When the SUBSYSPARM value string is stored in the command line global variable, Horizon automatically appends two characters: a blank and a semicolon (;), in that order. By varying the SUBSYSPARM values, Horizon developers can implement different server processes as single application subsystems. User Language programs can thereby be tested without having to define a new subsystem. For more information about testing application programs using this parameter with the Rocket-provided subsystem, RPI, see Application testing with the RPI subsystem. Supply the subsystem parameter line within quotation marks, if it contains any blanks, commas, or equal signs. The quotation marks cause Model 204 to treat the entire quoted string as a single token. If the quotation marks are not supplied, then blanks, commas, and equal signs are taken as token delimiters, causing Model 204 to treat the subsystem parameter line as having multiple tokens, and thus reject the DEFINE PROCESS command.

Example

Sample (non-PQO) client process:

DEFINE PROCESS TIRES WITH - SCOPE=SYSTEM - DESTINATION=PARTS - PARTNER=QRYTIRES - TIMEOUT=60

Sample (non-PQO) server process:

DEFINE PROCESS QRYTIRES WITH - SCOPE=SYSTEM - FROM=(INVENTRY) - SUBSYSTEM=QTIRES - TIMEOUT=60

Usage notes

The DEFINE PROCESS command specifies client (outbound) and server (inbound) processes. The DESTINATION or FROM parameter associates the process name with a set of processgroups, each of which associates the process with a link. By assigning processes to specific processgroups, the system manager can control their use of network resources.

There are two types of processes:

• A client process, typically identified by the use of a PARTNER name. The DEFINE PROCESS command associates a symbolic name with the actual conversation partner transaction name. This allows the actual name of the conversation transaction to be modified without requiring changes to User Language requests.

• A server process, typically identified by the use of the SUBSYSTEM parameter. Identifying the inbound process with the SUBSYSTEM option allows modification of the subsystem name without having to change the name that selects the transaction.

For more information about Horizon network and entities, see Horizon network management. For more information about PQO entities, see PQO: Defining a PQO network.