Program Communication facilities

Overview

Model 204 provides facilities that allow a User Language request to communicate with user-written CICS programs, CMS EXECs, or SNA Communications Server (formerly VTAM) application programs. These facilities for program, or intersystem, communication (between Model 204 and another system — CICS or CMS — on the same machine or between Model 204 and another system on a different machine) are as follows:

• TPROCESS, or Terminal Process, a process-to-process communication facility in CICS and CMS — A request can identify a CICS program or CMS EXEC and trigger its execution. In addition, the User Language request can communicate with the CICS program or CMS EXEC.
• Transfer Control — A request can identify a CICS program or SNA Communications Server application and transfer control to it.

Horizon

Model 204 also offers, as an optional feature, its distributed application facility, Horizon, which supports the LU 6.2 protocol of IBM's Systems Network Architecture (SNA). Horizon allows Model 204 applications to participate in program-to-program processing by communicating through SNA Communications Server with one or more other programs. Communication takes place over an SNA network, using verbs and protocols conforming to LU 6.2 architecture. Horizon uses User Language statements and Model 204 commands.

BATCH2

The Model 204 BATCH2 utility program enables you to pass a User Language request to a Model 204 Online that is running in a separate region, partition, or virtual machine. The BATCH2 connection emulates a line-by-line terminal.

Partner process definition

A partner process is the entity that is the object of program communication statements in a User Language request. For example, if a request transfers control to a CICS program, the CICS program is referred to as the partner process. Similarly, if a request communicates with a CMS REXX EXEC, the EXEC is referred to as the partner process.

With Horizon, when a request communicates with another request that resides in a separate Model 204 Online, the initiating request is the client process, while the responding request is referred to as the server process.

Network entity definition

Before a SOUL request can participate in Program Communication, the network entities link, processgroup, and process must be defined by using the DEFINE LINK, DEFINE PROCESSGROUP, and DEFINE PROCESS commands. Also, the defined link must be enabled by the OPEN LINK command. These commands can be issued only by a user with system manager privileges, or in the User 0 stream.

TCP/IP Sockets Interface for Model 204

The TCP/IP Sockets Interface for Model 204 makes Model 204 a server or a client by writing a User Language application using calls that closely follow the Berkeley Socket Interface. The IBM programming interface comes with TCP/IP on your operating system; you can consult IBM documentation for more details.

TPROCESS (terminal process) communication

The TPROCESS facility allows a User Language request "conversational" communication with a CICS program or CMS EXEC. This communication is achieved by using special statements, functions, and subcommands. User Language also allows some level of coordination of the use of the terminal by the request and the partner process.

The TPROCESS discussion that follows is divided into a section for each partner in a TPROCESS communication. The description of the User Language side of a TPROCESS communication begins in User Language TPROCESS communication. CICS TPROCESS communication is discussed on CICS TPROCESS communication. CMS TPROCESS communication is discussed on CMS TPROCESS communication.

Sample programs for a TPROCESS communication between a CICS program and a User Language request begin on CICS TPROCESS example. Sample programs for a TPROCESS communication between a CMS EXEC and a User Language request begin on CMS TPROCESS example.

TPROCESS applications cannot use the SECTRLOG trusted login option. Using trusted Login results in the following message:

M204.1786: PROCESS-TO-PROCESS NOT SUPPORTED ON THIS THREAD

User Language TPROCESS communication

The discussion of the User Language part of a TPROCESS conversation is contained largely in the descriptions of the individual statements, which begin in OPEN PROCESS statement. The statements are summarized in User Language communication statements. Coordination of control of the conversation is described below.

Controlling the conversation

To use TPROCESS communication, the DEFINE LINK command must specify PROTOCOL=MASTER. This indicates that the User Language request controls, at every point in the conversation, whether the partner process can issue a send or receive operation. If the partner process issues a send or receive operation at a point when the User Language request issues the same operation, the partner process is informed that the operation is invalid. The User Language request is not informed that the partner process attempted the invalid operation. This is the sense in which the User Language request acts as the "master" in the conversation.

The SIGNAL operation can be used by either partner to interrupt the other. It does not affect the control of the conversation by the User Language request. It can be issued at any point in the conversation by either the User Language request or the partner process. The SIGNAL operation can be used to indicate that some part of the TPROCESS conversation has completed, for example, as an end-of-data flag after a stream of consecutive SENDs, or to communicate that some error condition has been encountered.

User Language communication statements

The User Language TPROCESS communication statements are summarized in the following table and discussed in detail in the sections that follow. Handling errors during statement processing is described in Error handling for TPROCESS statements.

TPROCESS User Language statements

Statement	Description
CLOSE PROCESS	Ends the conversation between the request and the partner process.
FLUSH PROCESS	Supports increased router method independence in User Language.
OPEN PROCESS	Begins a conversation between a request and a partner process.
RECEIVE	Receives data from a partner process.
SEND	Transmits data from a request to a partner process.
SIGNAL PROCESS	Signals interruption of the conversation in process.

CLOSE PROCESS statement

The CLOSE PROCESS statement ends the conversation between a User Language request and a partner process.

Syntax

The format of the CLOSE PROCESS statement is:

CLOSE PROCESS {cid | processname | %variable} [SYNCLEVEL | FLUSH | %variable]

Where:

• cid refers to a conversation ID, and processname refers to a partner process defined in a DEFINE PROCESS command that must be open. This CID or process name can be provided as the value of a %variable.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the CLOSE statement.
• SYNCLEVEL, FLUSH, and %variable (used as the second parameter) have no effect, except to allow portability from one TRANSPORT/PROTOCOL combination to another (see the DEFINE LINK command).

After the CLOSE PROCESS statement is issued, the request can resume output to the terminal if the output was suppressed by the OPEN PROCESS statement.

Note: The syntax for this statement with Horizon varies slightly; see the Horizon syntax.

OPEN PROCESS statement

The OPEN PROCESS statement begins a conversation between a User Language request and the partner process.

Syntax

The format of the OPEN PROCESS statement is:

OPEN PROCESS {processname | %variable} [CID {name | %variable}]

Where:

• processname refers to a partner process defined in a DEFINE PROCESS command. The partner process name also can be provided as the value of a %variable.
• CID specifies the ID for use in subsequent User Language statements for the conversation. If CID is not given, the process name is used as the ID. CID must be specified if there are two or more active conversations with the same process name. And, if CID is specified, subsequent conversation statements must also specify the same CID value.

If the DEFINE PROCESSGROUP command contains TERMINAL=REMOTE, the terminal is assumed to be under the partner's control, and any User Language terminal output, except error messages produced by the request, are discarded and cause the request to be cancelled.

If TERMINAL=LOCAL is specified, the terminal is assumed to be under control of the User Language request, and the partner program should not write to it.

Note: The syntax for this statement with Horizon varies slightly; see the Horizon syntax.

RECEIVE statement

The RECEIVE statement receives data from a partner process.

Syntax

The format of the RECEIVE statement is:

RECEIVE {IMAGE imagename | %variable} FROM {cid | processname | %variable} [RESULT %variable]

Where:

• imagename specifies that the receiving area is an image previously defined by an image definition. The image automatically is set active by the RECEIVE statement.

  This area also can be a %variable. The data received from the partner process is assumed to be in string form and is converted to the type of %variable.

• cid refers to a conversation ID, and processname refers to a partner process defined in a DEFINE PROCESS command that must be open. This CID or process name can be provided as the value of a %variable.

  If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the RECEIVE statement.

• RESULT returns the following values:
  • If $STATUS = 0, "Data complete"
  • If $STATUS = 1, "Data truncated"
  • If i$STATUS > 1, "Null"

If the receiving area is not large enough to accommodate the data transmitted by the partner process, the following actions occur:

• If the receiving area is an image, truncation occurs. However, a warning message is not issued. This type of truncation is caused by one of the following conditions:
  • The full screen buffer area (that is, FSCB) is not large enough to accommodate the data; therefore, the excess data is lost.

    Refer to FSCB (full-screen buffer) for more information on its size requirements.

  • The data has been received into the full screen buffer area; however, the image defined is not large enough to receive the data.

    The %imagename:READLEN %variable can be checked to determine the actual length of the data to be received. The IDENTIFY statement with a larger image can be used to access all of the data.

• If the receiving area is a %variable, truncation occurs.

Note: The syntax for this statement with Horizon varies slightly; see the Horizon syntax.

SEND statement

The SEND statement initiates the transmission of data from a User Language request to a partner process.

Later in the conversation, the request can ensure that the partner process has successfully processed the data either by using a RECEIVE statement or by detecting (using the $STATUS function) a signal operation issued by the partner process.

Either of these synchronization methods can be used; however, the request and the partner process must agree on how synchronization is performed.

Syntax

The format of the SEND statement is:

SEND {IMAGE imagename |'string' | %variable} TO {cid | processname | %variable} [REQSEND %variable] [FLUSH]

Where:

• imagename specifies that the object to be sent is an image previously defined by an image definition. The image must be set active by either the READ IMAGE, PREPARE, or IDENTIFY statement before it can be used by the SEND statement.

  The object also can be a quoted string or a %variable. A %variable is converted to string form (that is, the sequence of characters generated by a PRINT %variable statement) before being sent to the partner process.

• cid refers to a conversation ID, and processname refers to a partner process defined in a DEFINE PROCESS command that must be open. This CID or process name can be provided as the value of a %variable.

  If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the SEND statement.

• REQSEND and FLUSH allow portability from one TRANSPORT/PROTOCOL combination to another (see the DEFINE LINK command). REQSEND always returns a 0 for a TPROCESS conversation.

Truncation occurs and a warning message is issued if the data being sent exceeds the length (that is, the value of the DATALEN option) specified on the DEFINE PROCESS command.

Note: The syntax for this statement with Horizon varies slightly; see the Horizon syntax.

SIGNAL PROCESS statement

The SIGNAL PROCESS statement provides a mechanism by which a request can signal an interruption of the conversation in process.

Syntax

The format of the SIGNAL PROCESS statement is:

SIGNAL PROCESS {cid | processname | %variable} {nnn | %variable}

Where:

• cid refers to a conversation ID, and processname refers to a partner process defined in a DEFINE PROCESS command that must be open. This CID or process name can be provided as the value of a %variable.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the SIGNAL statement.
• n is an arbitrary number assigned to this SIGNAL. This number must be an integer in the range of -2,147,483,648 through +2,147,483,647 (a four-byte binary value). This number also can be provided as a %variable. If neither n nor a %variable is specified, a default value of 0 is used.

The SIGNAL PROCESS statement causes the next communication attempted by the partner process to be suppressed, and to return an indication that the signal occurred with the value sent by the SIGNAL PROCESS statement.

Note: The syntax for this statement with Horizon varies slightly; see the Horizon syntax.

Error handling for TPROCESS statements

Error conditions encountered during the processing of CLOSE PROCESS, OPEN PROCESS, RECEIVE, SEND, and SIGNAL PROCESS statements generate Model 204 error messages that are not automatically displayed on the terminal. The request should check for errors by using the $Status and $StatusD functions. You can retrieve the text of the most recently issued error message by using the $Errmsg function.

If more than one error occurs during the processing of a statement, $Status, $StatusD, and $Errmsg retain the error that has the highest level of severity. If multiple errors have the same (and highest) level of severity, $Status, $StatusD, and $Errmsg retain the error that occurred the earliest. For more information on these functions, refer to SOUL $functions.

The values returned by $Status are summarized in Error handling for TPROCESS statements.

$Status return values

Return value	Error level	Result/action
0	Success	The message text set to null.
1	Warning	The statement generating this code has completed, but a warning condition was encountered. $StatusD provides a detailed warning code.
2	Signal	A SIGNAL has been received from the partner process. The $StatusD function provides the SIGNAL value. If this code is received on a: SIGNAL statement, then the SIGNAL was transmitted to the partner process. SEND statement, the data transmitted was not received by the partner process and was discarded. RECEIVE statement, no data was received and the contents of the receiving area are unpredictable.
3		The User Language statement is invalid in this conversation state.
4 or greater	Serious Error	If this code is generated by a CLOSE PROCESS statement, then the CLOSE PROCESS functions have been completed to the greatest degree possible. Any other statement that generates this code did not complete at all. $StatusD provides a detailed error code.

Error handling for TPROCESS statements provides the message text returned by the $Errmsg function, depending upon the values returned by the $Status and $StatusD functions. For a detailed explanation of these messages, see the M204.xxxx descriptions in the Model 204 core messages, where xxxx is the $StatusD value.

$Errmsg text per $Status / $StatusD

$Status	$StatusD	Text returned by the $Errmsg function
0	0	Successful: Error message area set to null
1	1785	Data received has been truncated
2	ANY	A SIGNAL has been received: Error message area is set to null
3	1254	User Language statement invalid in this conversation state
4	89	No I/O allowed on terminal while TPROCESS is in effect
5	1521	Remote process does not exist or required access not authorized
5	1572	Process xxxxxxxx is not open
5	1746	PROCESS, PROCESSGROUP, or LINK not found
5	1786	TPROCESS not supported on this thread
5	1791	Partner process will not accept defined protocol, mode, or terminal
5	1806	Process not defined for transfer
10	1787	The defined TPROCESS buffer size is too large
10	1788	Unable to allocate necessary TPROCESS data areas
51	1793	Partner process is not active
52	1796	TPROCESS communications link has been closed
54	1784	Invalid TPROCESS status code
54	1789	Invalid TPROCESS message

CICS TPROCESS communication

Program communication functions in CICS are invoked with calls: the calls IFRECV, IFSENDX, and IFSGNL are used to communicate with the User Language request. IFPREP is used to set and query session parameters.

CICS TPROCESS support requirements are described below. The rest of the CICS TPROCESS discussion contains a summary and then individual descriptions of the CICS TPROCESS calls, followed on CICS TPROCESS example by a sample CICS conversation program.

Support required for CICS TPROCESS

In the discussion in this section, it is assumed that the user is accessing Model 204 through the CICS full screen interface (IODEV=11). The data set or file definition statements for Model 204 files that are accessed by CICS applications are included in the JCL for the Model 204 region, not the CICS region.

In order for the CICS program to communicate with the request, the program, as identified by the DEFINE PROCESS command and invoked by the OPEN PROCESS statement, must be link-edited with the IFPPCI module. IFPPCI must be preprocessed and assembled at installation time.

The pseudo conversational CICS support provided for 3270 full screen interface transactions that is used in TPROCESS communications requires that the M204PSFS module must be also preprocessed and assembled at installation time. This allows a User Language request to initiate terminal I/O in conversational mode with a CICS partner program.

M204PSFS, the CICS full screen interface module, must have a TWA defined. For more information about the Model 204 CICS full screen interface, see the Rocket Model 204 installation page for your operating system.

CICS TPROCESS calls

The IFPPCI module, described further on the Rocket Model 204 installation page for IBM z/OS, has five entry points that can be called by the CICS program. The entry points, and the functions they provide, are summarized in CICS TPROCESS calls. Each call is discussed in greater detail on the pages that follow. The notation conventions used for the individual call descriptions are discussed below.

CICS TPROCESS calls

Call	Description
IFCSA	Prior to Model 204 V3R1, passed the address of the Common System Area (CSA) to the CICS Interface. As of V3R1, the IFCSA call does not function, but is not upwardly incompatible.
IFPREP	Allows the CICS program to set session defaults and retrieve information regarding the TPROCESS conversation.
IFRECV	Receives data from the User Language request.
IFSEND	Sends data to the User Language request.
IFSGNL	Signals the User Language request, interrupting the conversation.

Notation conventions for CICS call descriptions

Call name and syntax

The syntax of calls is presented in this format:

callname|alias (parm1, parm2,...parmn)

Where:

• callname is a keyword that specifies the name of the function.
• parm1 is the first parameter in the call list. You must specify parameters in the proper sequence, as shown (parm2 follows parm1; parmn is last).

  A comma delimiter (,) separates parameters in the list, and the entire parameter list is enclosed inside parentheses, for illustrative purposes only. (When coding calls, use whatever delimiter and format that are valid in your programming language.)

Parameters

Each parameter description provides a three-character code having the following format:

[X,y,z]

Where:

• X specifies that the parameter is used for input or output operations, and is either of the following codes:
  • I (input)
  • O (output)
• y specifies that the parameter, if coded, must be defined in the host language program as one of three possible data type variables, and is one of the following codes:
  • i (integer whose maximum length is 4 bytes)
  • s (short character string whose maximum length is 32 bytes)
  • c (character string whose maximum length is the buffer size)
• z specifies whether the parameter must be coded in the call, and is either (or both) of the following codes:
  • r (required)
  • o (optional)

Example

For example, RETCODE [O,i,r] where:

• O specifies that RETCODE is an output parameter
• i specifies an integer type variable (maximum length is 4 bytes)
• r specifies that RETCODE is required

Individual call descriptions

The individual CICS TPROCESS calls are described on the pages that follow. The completion codes and corresponding completion detail values for the calls are summarized in CICS completion codes.

IFCSA

As of Model 204 Version 3.1 and later, the IFCSA call is no longer required in IFAM2 programs, as it no longer performs a function. For purposes of upward compatibility the IFCSA call can remain in your current programs.

Prior to Model 204 Version 3.1, the IFCSA call was required to be the first call issued during the IFAM2 session. The IFCSA call passed the Common System Area (CSA) address.

IFPREP

The IFPREP call prepares the session for TPROCESS communications. IFPREP enables your CICS program to set session defaults and retrieve information on a TPROCESS conversation.

Syntax

The format of the IFPREP call is:

IFPREP(RETCODE,RC_DETAIL,PROCESS_ID,LANG_IND,DATA_LEN)

Parameters

Specify the parameters in the syntax order shown above.

Parameter	Discussion
RETCODE	[O,i,r] The Model 204 return code is a required output parameter. The code is a binary integer value. CICS completion codes displays all the CICS TPROCESS return codes.
RC_DETAIL	[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. Model 204 returns a second level code which indicates the status of the TPROCESS conversation.
PROCESS_ID	[O,i,r] The process identifier is a required output parameter. Specify an integer variable. Model 204 returns a value that must be referenced in subsequent IFSEND, IFRECV, and IFSGNL calls to transmit data in TPROCESS applications.
LANG_IND	[I,i,r] The language indicator is a required input parameter which establishes the calling sequence convention to be used corresponding to the host language. The indicator specifies the format of arguments that are passed in subsequent calls. Specify one of the following integer values: 1 - PL/I F-level, and BAL languages 2 - COBOL, Fortran, and BAL languages 3 - PL/I with + Optimizer / Checkout compilers, VS/Fortran, and BAL languages Any convention can be specified for use with the BAL language, and the BAL programmer must adhere to the convention that is specified when coding arguments.
DATA_LEN	[O,i,r] The data length is a required output parameter. Specify an integer value. Model 204 returns the value of the DATALEN parameter in the DEFINE PROCESS command.

Notes and tips

IFPREP must be called before the IFSEND, IFRECV, or IFSGNL calls.

Completion codes (RETCODE) applicable

The completion codes that apply to the IFPREP call are:

0	Successful
4	Error. Refer to CICS completion codes.

IFRECV

IFRECV enables the CICS program to receive a data stream from its partner, the User Language request.

Syntax

The format for the IFRECV call is:

IFRECV(RETCODE,RC_DETAIL,PROCESS_ID,DATA_AREA,DATA_LEN)

Parameters

Specify the parameters in the syntax order shown above.

Parameter	Discussion
RETCODE	[O,i,r] The Model 204 return code is a required output parameter. The code is a binary integer value. CICS completion codes displays all the CICS TPROCESS return codes.
RC_DETAIL	[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. Model 204 returns a second level code which, indicates the status of the TPROCESS conversation.
PROCESS_ID	[I,i,r] The process identifier is a required input parameter. Specify an integer variable, the value that is returned by Model 204 in the preceding IFPREP call.
DATA_AREA	[O,c,r] The data area is a required output parameter which specifies the address of the user's data area. Specify a character string variable. This area receives the data stream that is sent by the User Language request to the HLI program.
DATA_LEN	[I,i,r] The data length is a required input parameter if the language indicator parameter (LANG_IND) setting is 2 (COBOL, Fortran, BAL) in the preceding IFPREP call. Specify an integer value, the length of the receiving area. Model 204 returns the value which is the actual length of the data that was moved into the receiving area.

Note: The data area length is optional if the language indicator parameter (LANG_IND) setting is 1 or 3 (PL/I, VS/Fortran, BAL) in the preceding IFPREP call.

Notes and tips

Use the IFRECV call to receive data from a User Language request in a CICS TPROCESS conversation.

Completion codes (RETCODE) applicable

The completion codes that apply to the IFRECV call are:

0	Successful
1	Warning
2	No data was received and the contents of the data area and data area length arguments are unpredictable.
4	Error. Refer to CICS completion codes.

IFSEND

IFSEND enables the CICS program to send a data stream to its partner, the User Language request.

Syntax

The format of the IFSEND call is:

IFSEND(RETCODE,RC_DETAIL,PROCESS_ID,DATA_AREA,DATA_LEN)

Parameters

Specify the parameters in the syntax order shown above.

Parameters	Discussion
RETCODE	[O,i,r] The Model 204 return code is a required output parameter. The code is a binary integer value. CICS completion codes displays all the CICS TPROCESS return codes.
RC_DETAIL	[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. Model 204 returns a second level code which indicates the status of the TPROCESS conversation.
PROCESS_ID	[I,i,r] The process identifier is a required input parameter. Specify an integer variable, the value that is returned by Model 204 in the preceding IFPREP call.
DATA_AREA	[O,c,r] The data area is a required output parameter which specifies the address of the user's data area. Specify a character string variable. This area receives the data stream that is sent by the User Language request to the HLI program.
DATA_LEN	[I,i,r] The data length is a required input parameter if the language indicator parameter (LANG_IND) setting is 2 (COBOL, Fortran, BAL) in the preceding IFPREP call. Specify an integer value, the length of the receiving area. Model 204 returns the value which is the actual length of the data that was moved into the receiving area.

Note: The data area length is optional if the language indicator parameter (LANG_IND) setting is 1 or 3 (PL/I, VS/Fortran, BAL) in the preceding IFPREP call.

Notes and tips

Use the IFSEND call to send data to a User Language request in a CICS TPROCESS conversation.

Completion codes (RETCODE) applicable

The completion codes that apply to the IFSEND call are:

0	Successful
1	Warning
2	Signal received. The data specified in the data area argument was not transmitted.
4	Error. Refer to CICS completion codes.

IFSGNL

IFSGNL enables your CICS program to send a signal to its partner, the User Language request. The signal causes the next communication attempted by the request to complete with $STATUS set to 2 and $STATUSD set to the value passed to the IFSGNL call.

Syntax

The format of the IFSGNL call is:

IFSGNL(RETCODE,RC_DETAIL,PROCESS_ID,SGNL_VAL)

Parameters

Specify the parameters in the syntax order shown above.

Parameters	Discussion
RETCODE	[O,i,r] The Model 204 return code is a required output parameter. The code is a binary integer value. CICS completion codes displays all the CICS TPROCESS return codes.
RC_DETAIL	[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. Model 204 returns a second level code which indicates the status of the TPROCESS conversation.
PROCESS_ID	[I,i,r] The process identifier is a required input parameter. Specify an integer variable, the value that is returned by Model 204 in the preceding IFPREP call.
SGNL_VAL	[I,i,o] The signal value is an optional input parameter. Specify a fullword binary value in the range -2,147,483,648 through +2,147,483,647. If the signal value is not specified, it defaults to 0.

Notes and tips

Use the IFSGNL call to signal the User Language request in a CICS TPROCESS conversation.

CICS completion codes

CICS completion codes describes the completion codes and corresponding completion detail values for the IFPREP, IFRECV, IFSEND, and IFSGNL calls.

TPROCESS completion codes

Code	Completion detail value	Description
0	0	For the current release, the value is always zero.
1	11	If the call was IFSEND, the call is truncated before transmission. If the call was IFRECV, the data is truncated during receipt.
2	ANY	This argument is equal to the signal value specified by the User Language request. It can be an integer between -2,147,483,648 and 2,147,483,647.
3		(reserved for future use)
4		There is a severe error.
4	10	CRAM/IUCV link closed.
4	11	Remote process active upon detachment.
4	12	No data received. Call IFSEND to transmit data. The contents of the data area and the data area length are unpredictable.
4	13	No data sent. Call IFRECV to receive data.
4	100	User Language request issued a CLOSE PROCESS statement.
4	102	Connection error.
4	200	Not enough memory to allocate IFCB.
4	201	IFPREP has not been called.
4	202	Not enough arguments were passed.
4	301	Syntax error encountered in CMS Host Language Interface subcommand. Subcommand ignored.
4	302	Error assigning a value to variable while processing an IFRECV command. Data discarded.

CICS TPROCESS example

In this example, the User Language request communicates with a CICS program using the SEND and RECEIVE statements. The request sends two numbers to the CICS program. The CICS program adds the numbers together and sends the sum back to the User Language request.

DEFINE LINK LK4CICS WITH SCOPE=SYSTEM - TRANSPORT=TERMINAL - PROTOCOL=MASTER DEFINE PROCESSGROUP PGP4CICS WITH SCOPE=SYSTEM - LINK=LK4CICS - TERMINAL=LOCAL DEFINE PROCESS PS4CICS WITH SCOPE=SYSTEM - DESTINATION=PGP4CICS - PARTNER=PARTNER - DATALEN=100 - MODE=LINK OPEN LINK LK4CICS BEGIN SCREEN SCR1 MAX PFKEY 12 TITLE 'CP PROCESS-TO-PROCESS EXAMPLE' AT 12 BRIGHT SKIP 2 LINES PROMPT 'INPUT TWO NUMBERS, TO BE TRANSMITTED - TO THE CICS' PROMPT 'PARTNER PROCESS WHICH WILL RETURN THE - VALUE OF THE SUM' SKIP 2 LINES PROMPT 'INPUT FIRST VALUE :' AT 12 INPUT - VAL1 LEN 4 NUMERIC PROMPT 'INPUT SECOND VALUE :' AT 12 INPUT VAL2 - LEN 4 NUMERIC SKIP 2 LINES PROMPT 'ENTER X TO STOP RUN:' AT 12 INPUT EOJ LEN 1 END SCREEN * IMAGE IMG1 VALUE1 IS ZONED LEN 4 UNSIGNED VALUE2 IS ZONED LEN 4 UNSIGNED FILLER IS STRING LEN 72 END IMAGE * IMAGE IMG2 VALUE1 IS ZONED LEN 5 UNSIGNED FILLER IS STRING LEN 75 END IMAGE * PREPARE IMAGE IMG1 PREPARE IMAGE IMG2 * OPEN PROCESS PS4CICS IF $STATUS GT 1 THEN PRINT 'OPEN PROCESS FAILED, $STATUSD =' AND $STATUSD AND $ERRMSG JUMP TO STOP.RUN END IF * MAIN.LOOP: * READ SCREEN SCR1 %IMG1:VALUE1 = %SCR1:VAL1 %IMG1:VALUE2 = %SCR1:VAL2 * IF %SCR1:EOJ EQ 'X' THEN JUMP TO STOP.RUN END IF * SEND IMAGE IMG1 TO PS4CICS IF $STATUS GT 1 THEN PRINT 'SEND FAILED, $STATUSD =' AND - $STATUSD AND $ERRMSG JUMP TO STOP.RUN END IF * RECEIVE IMAGE IMG2 FROM PS4CICS IF $STATUS GT 1 THEN PRINT 'RECEIVE FAILED, $STATUSD =' AND - $STATUSD AND $ERRMSG JUMP TO STOP.RUN END IF * PRINT 'THE VALUE RETURNED IS' AND %IMG2:VALUE1 * JUMP TO MAIN.LOOP * STOP.RUN: * CLOSE PROCESS PS4CICS PRINT 'END OF SAMPLE CP PROGRAM' END

CICS partner

The following sample CICS program could communicate with the above User Language request to perform the addition operation and send back the sum to the request.

********************************************* * THIS IS AN EXAMPLE OF A CICS 'PARTNER PROCESS' * PROGRAM. * ITS PURPOSE IS TO PROVIDE A SKELETON, FROM WHICH A MORE * COMPLEX PROGRAM CAN BE DEVELOPED. * THE LOGIC OF THIS PROGRAM IS AS FOLLOWS: * * 1) RECEIVE A MESSAGE FROM THE USER LANGUAGE PARTNER. * THIS MESSAGE CONTAINS 2 NUMBERS. * 2) ADD THESE NUMBERS TOGETHER * 3) SEND A MESSAGE TO THE USER LANGUAGE PARTNER THAT * CONTAINS THE SUM. * 4) CONTINUE THIS LOOP (STEP 1 THRU 3) UNTIL THE USER * LANGUAGE PARTNER CLOSES THE CONVERSATION. ********************************************** EJECT IDENTIFICATION DIVISION. PROGRAM-ID. PARTNER. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. DATA DIVISION. WORKING-STORAGE SECTION. 01 CONTROL-FLAGS. 05 EOJ-FLAG PIC X(01) VALUE 'N'. 01 CALL-PARAMETER-AREA. 05 COMPLETION-CODE PIC S9(05) VALUE +0 COMP. 05 COMPLETION-DETAIL PIC S9(05) VALUE +0 COMP. 05 LANGUAGE-INDICATOR PIC S9(05) VALUE +2 COMP. 05 PROCESS-IDENTIFIER PIC S9(05) VALUE +0 COMP. 05 DATA-LENGTH PIC S9(05) VALUE +0 COMP. 01 RECV-AREA-LENGTH PIC S9(05) VALUE +80 COMP. 01 RECV-AREA. 05 RECV-VALUE-1 PIC 9(04) VALUE 0. 05 RECV-VALUE-2 PIC 9(04) VALUE 0. 05 FILLER PIC X(72) VALUE SPACES. 01 SEND-AREA-LENGTH PIC S9(05) VALUE +80 COMP. 01 SEND-AREA. 05 SEND-VALUE PIC 9(05) VALUE 0. 05 FILLER PIC X(75) VALUE SPACES. LINKAGE SECTION. 01 LINKAGE-POINTERS USAGE COMP. 05 FILLER PIC S9(08). PROCEDURE DIVISION. *************************************** * MAINLINE ROUTINE **************************************** PERFORM 100-INITIALIZE THRU 100-EXIT. ** ** (TO MAKE PROGRAM LOOP UNTIL "X" IS ENTERED ON SCREEN) ** PERFORM 200-MAIN-LOOP THRU 200-EXIT UNTIL EOJ-FLAG = 'Y'. ** ** PERFORM 200-MAIN-LOOP THRU 200-EXIT. ** EXEC CICS RETURN END-EXEC. GOBACK. ***************************************** * SUB-ROUTINES USED IN MAINLINE ***************************************** 100-INITIALIZE. MOVE ' ' TO EOJ-FLAG. EXEC CICS ENTER TRACEID(001) END-EXEC. MOVE 2 TO LANGUAGE-INDICATOR. EXEC CICS ENTER TRACEID(002) END-EXEC. CALL 'IFPREP' USING COMPLETION-CODE COMPLETION-DETAIL PROCESS-IDENTIFIER LANGUAGE-INDICATOR DATA-LENGTH. IF COMPLETION-CODE > 1 MOVE 'Y' TO EOJ-FLAG. 100-EXIT. EXIT. 200-MAIN-LOOP. EXEC CICS ENTER TRACEID(003) END-EXEC. CALL 'IFRECV' USING COMPLETION-CODE COMPLETION-DETAIL PROCESS-IDENTIFIER RECV-AREA RECV-AREA-LENGTH. IF COMPLETION-CODE > 1 MOVE 'Y' TO EOJ-FLAG GO TO 200-EXIT. COMPUTE SEND-VALUE = RECV-VALUE-1 + RECV-VALUE-2. EXEC CICS ENTER TRACEID(004) END-EXEC. CALL 'IFSEND' USING COMPLETION-CODE COMPLETION-DETAIL PROCESS-IDENTIFIER SEND-AREA SEND-AREA-LENGTH. IF COMPLETION-CODE > 1 MOVE 'Y' TO EOJ-FLAG. 200-EXIT. EXIT.

CMS TPROCESS communication

Model 204 can support communication between a User Language request and one concurrent CMS partner process. A REXX or EXEC2 EXEC communicates with a User Language program by using data transmission subcommands directed to the Model 204 environment. These subcommands are available for use only with the CMS interface.

In CMS, program communication functions are called via subcommands. The subcommands IFRECV, IFSENDX, and IFSGNL are used to communicate with the User Language request. Two other subcommands, IFSET and IFEXTRACT, are used to set and query session parameters.

CMS TPROCESS requirements are described below. The rest of the CMS TPROCESS discussion contains a summary and then individual descriptions of the CMS TPROCESS subcommands followed by sample CMS EXEC and User Language TPROCESS conversation programs.

Requirements for using CMS TPROCESS

Model 204 supports communication between a User Language request and one concurrent CMS partner process, subject to these restrictions:

1. In the discussion that follows, it is assumed that the user is accessing Model 204 through IUCV and through the CMS full screen interface (IODEV=41).
2. The Model 204 environment, as the target of a subcommand, must be explicitly established with the ADDRESS command in REXX, or the &PRESUME or &SUBCOMMAND commands in EXEC2.
3. The CMS partner process must be written in System Product Interpreter language (REXX) or EXEC2. The partner process communicates through the standard CMS SUBCOM interface, which is supported by these languages.
4. CMS must be at z/VM/SP Release 3, or later.
5. The user interface module (M204USER), invoked by the M204 command, must be installed as either a saved segment or a Nucleus Extension.

Many CMS commands that an EXEC can call run in the User Area. These commands would overlay the interface module if it also ran in the User Area, causing unpredictable results.

See the description of the M204 EXEC in the Rocket Model 204 System Manager's Guide for more information about invoking the user interface module.

CMS TPROCESS subcommands

The subcommands used in CMS TPROCESS are summarized in Subcommand summary, and their return codes are summarized in Return codes. The subcommands discussion begins in Individual subcommand descriptions.

Subcommand summary

CMS TPROCESS subcommands

Subcommand	Description
IFEXTRACT and IFSET	Allows the CMS EXEC to set session defaults and retrieve information regarding the TPROCESS conversation.
IFRECV	Receives data from the User Language request.
IFSENDX	Sends data to the User Language request.
IFSGNL	Signals the User Language request, interrupting the conversation.

Return codes

Return codes lists return codes defined for the subcommands. CICS completion codes displays these codes and their corresponding completion detail values.

Return codes CMS TPROCESS subcommands

Code	Completion detail value	Description
0	Successful
1	Warning	Data transfer cannot have completed as expected. Refer to the completion detail variable, if one has been defined, for more information.
2	Signal received	See the completion detail variable, if one has been defined, for the signal value. No data was sent/received. For IFRECV, the value of the target variable has not been changed.
3		(reserved for future use)
4	Error	The subcommand did not complete successfully. See CICS completion codes for the completion detail code.

Individual subcommand descriptions

The individual CMS TPROCESS subcommands are described in this section.

IFEXTRACT

The IFEXTRACT subcommand obtains current parameter values from the Model 204 conversation partner.

Syntax

The format of the IFEXTRACT subcommand is:

IFEXTRACT parameter

where parameter is a parameter relating to the TPROCESS conversation. For information about setting these parameters, see the IFSET subcommand.

Parameter	Specifies
STATUSDVAR	Name of the variable in which the user wants to receive completion detail codes and signal values. If this parameter is not set, completion detail codes and signal values are not provided to the user.
LANGINT	Interface used when setting EXEC variables.
DATALEN	Maximum data length in bytes that an IFSENDX or IFRECV operation can process.

Notes and tips

IFEXTRACT returns parameter information in either of the following forms:

• variable parametername.0 specifies number of values returned (n)
• variables parametername.1-n specifies parameter values

  where parametername is STATUSDVAR, LANGINT, or DATALEN and the values returned are as shown in IFEXTRACT.

  Returned values for IFEXTRACT parameters

  Parameter	Returned value	Equal to:
  STATUSDVAR	STATUSDVAR.0	1, if a STATUSDVAR has been set, 0 if not
  STATUSDVAR	STATUSDVAR.1	Name of the current STATUSDVAR variable, if one is set
  LANGINT	variable LANGINT.0	1
  LANGINT	variable LANGINT.1	Current value of LANGINT
  DATALEN	DATALEN.0	1
  DATALEN	DATALEN.1	Current value of DATALEN

IFRECV

The CMS partner process must issue an IFRECV subcommand to receive data from the User Language request.

Syntax

The format of the IFRECV subcommand is:

IFRECV expression

Where:

expression is a statement that evaluates to a single CMS EXEC2 or REXX symbol. The symbol is taken as the name of the target variable which contains the transmitted data when IFRECV completes. The expression argument to IFRECV must evaluate to a single symbol name. For EXEC2, the resulting symbol name must be stripped of its preceding ampersand (&).

Examples

In the REXX example that follows, the line enclosed by quotation marks is passed as a literal string to the Model 204 interface. The variable 'NAME' is set to the received value:

ADDRESS M204 'IFRECV NAME' IF RC = 0 THEN IF NAME = ABC ...

In this example, the expression 'item1 item2' is evaluated by the interpreter, and the string 'ABCDEFGH' is used as the target variable name:

ITEM2 = EFGH ITEM1 = ABCD 'IFRECV' item1 item2 IF RC = 0 THEN IF ABCDEFGH = 12345 ...

The target variable used in this example is &CAR:

IFRECV CAR &IF &RC ¬= 0 &GOTO -ERROR &IF &CAR = PINTO ...

Because the interpreter evaluates &CAR in the IFRECV command, the target variable used in this example is &MAKEMODEL:

&CAR = &CONCAT OF MAKE MODEL IFRECV &CAR &IF &RC ¬= 0 &GOTO -ERROR &IF &MAKEMODEL = PINTO

IFSENDX

The CMS partner process must issue an IFSENDX subcommand to send data to the User Language procedure.

Syntax

The format of the IFSENDX subcommand is:

IFSENDX [expression]

Where:

expression is optional and specifies an arbitrary EXEC2 or REXX expression that is evaluated by the interpreter. The result is sent to Model 204. The expression begins with the second byte following the IFSENDX keyword. If no expression is coded, a null string is sent.

IFSET

The IFSET subcommand sets parameter values for the TPROCESS conversation.

Syntax

The format of the IFSET subcommand is:

IFSET parameter value

Where:

parameter is one of the parameters relating to the TPROCESS conversation. You can specify a value for either of these parameters:

• STATUSDVAR

  The STATUSDVAR parameter specifies the name of the variable in which the user wants to receive detail completion codes and signal values. IFSET should be used to set the STATUSDVAR parameter before issuing IFSENDX, IFRECV, or IFSGNL. If STATUSDVAR is not set, detail completion codes and signal values are not provided to the user.

  The value given for STATUSDVAR in an IFSET subcommand must resolve to a valid symbol name.

• LANGINT

  The LANGINT parameter specifies the interface used when setting EXEC variables. For EXEC2 users, the only valid value is DIRECT, the default. REXX users can specify SYMBOLIC.

Setting LANGINT

LANGINT affects the treatment of the variable name specified for STATUSDVAR in the IFSET subcommand and in the IFRECV subcommand.

If the value specified is SYMBOLIC and the variable is a compound symbol, normal REXX substitution occurs for everything after the stem. Alternatively, if the value of LANGINT is DIRECT, the name is considered a literal. No substitution occurs.

In the following example, the DIRECT setting causes the symbol DATA.J to receive each of the ten values specified, whereas the SYMBOLIC setting causes an array DATA.1 through DATA.10 to receive the values because J is evaluated by REXX when LANGINT is set to SYMBOLIC.

DO J = 1 TO 10 'IFRECV DATA.J' IF RC ¬=0 THEN LEAVE END

Refer to the IBM z/VM/SP System Product Interpreter Reference for information about the distinction between the DIRECT and SYMBOLIC interfaces to REXX variables.

DATALEN cannot be set

The DATALEN parameter specifies the maximum data length in bytes that an IFSENDX or IFRECV operation can process. DATALEN is set by the Model 204 DEFINE PROCESS command and cannot be changed by the IFSET subcommand.

IFSGNL

The CMS partner process can issue an IFSGNL subcommand to interrupt the conversation. A signal subcommand suppresses the next communication attempted by the SOUL request, causing the request to complete with $STATUS set to 2 and $STATUSD set to the value passed to the IFSGNL subcommand.

Syntax

The format of the IFSGNL subcommand is:

IFSGNL [expression]

Where:

expression is optional and, if specified, must resolve to an integer value in the range -2,147,483,648 through +2,147,483,647. If no expression is coded, the default value is 0.

Notes and tips

A signal subcommand suppresses the next communication attempted by the User Language request. IFSGNL returns a completion code of 2 and the value that was sent in the expression by the IFSGNL subcommand.

CMS TPROCESS example

In this example, the SOUL request communicates with a CMS EXEC using the SEND and RECEIVE statements. The purpose of the example is to copy (or "upload") a CMS file into a Model 204 file.

* * THE DEFINE COMMANDS USUALLY ARE IN THE USER ZERO STREAM. * OTHERWISE, THE SYSTEM MANAGER IS NEEDED. * THEY ARE SHOWN HERE FOR DOCUMENTATION PURPOSES. * NOTICE THE REQUIRED OPEN LINK COMMAND. * ONCE OPENED, THE LINK REMAINS OPEN UNTIL EXPLICITLY * CLOSED BY AN EOJ OR BY THE FORCE OPTION OF THE CLOSE LINK * COMMAND. * DEFINE LINK LINK11 WITH SCOPE=SYSTEM - TRANSPORT=TERMINAL PROTOCOL=MASTER DEFINE PROCESSGROUP PGRP11 WITH SCOPE=SYSTEM - LINK=LINK11 TERMINAL=LOCAL DEFINE PROCESS UPLOAD WITH SCOPE=SYSTEM DATALEN=255 - MODE=EXEC DESTINATION=PGRP11 PARTNER=DBASE3 OPEN LINK LINK11 * * UPLOAD RECORDS FROM A CMS FILE. * RESTRICTION: THE MAXIMUM LENGTH OF ANY LINE IS 255. * BEGIN %DATA STRING LEN 255 %FN STRING COMMON %CNT FIXED COMMON * %CNT = 0 %FN = $READ('CMS FILE NAME TYPE MODE') OPEN PROCESS UPLOAD IF $STATUS NE 0 THEN CALL EXIT ('ATTACHING TO REXX PROGRAM') END IF SEND %FN TO UPLOAD IF $STATUS NE 0 THEN CALL EXIT ('SENDING FILENAME TO REXX PROGRAM') END IF REPEAT RECEIVE %DATA FROM UPLOAD IF $STATUS NE 0 THEN * * END OF FILE IF SIGNAL 0 ISSUED: * IF $STATUS EQ 2 AND $STATUSD EQ 0 THEN CALL EXIT('') END IF * * OTHERWISE, THIS IS A TERMINATING ERROR: * CALL EXIT ('RECEIVING RECORD FROM REXX PROGRAM') END IF %CNT = %CNT + 1 STORE RECORD ID = 'UPLOAD' DATA = %DATA END STORE END REPEAT * * SUBROUTINE TO EXIT THE UPLOAD OPERATION, WITH OPTIONAL * ERROR MESSAGE: * SUBROUTINE EXIT (%MSG STRING LEN 40) %EM STRING LEN 80 %FN STRING COMMON %CNT FIXED COMMON * * SAVE INDICATORS BEFORE CLOSING PROCESS: * %ST = $STATUS %STD = $STATUSD %EM = $ERRMSG CLOSE PROCESS UPLOAD PRINT %CNT AND 'RECORDS UPLOADED FROM CMS FILE' AND %FN * * IF THIS IS AN ERROR EXIT, PRINT ERROR INDICATORS: * IF %MSG NE '' THEN PRINT 'ERROR' AND %MSG PRINT 'STATUS' AND %ST AND 'DETAIL' AND %STD PRINT 'ERROR MESSAGE:' AND %EM END IF STOP END

CMS partner

The following sample CMS EXEC could communicate with the above SOUL request to upload a file:

/* Upload file to SOUL */ 'MAKEBUF' buf = rc /* Tell M204 the name of statusdvar, and get the file id: */ address M204 'IFSET STATUSDVAR statusdvar' address M204 'IFRECV fileid' if rc ¬= 0 then call exit 'receiving fileid, from SOUL' /* Stack the records from the file: */ qd = queued() 'EXECIO * DISKR' fileid'(FIFO FINIS' if rc ¬= 0 then call exit 'reading CMS file' fileid /* Send the records to User Language: */ do i = 1 to queued() - qd parse pull line address M204 'IFSENDX' line if rc ¬= 0 then call exit 'sending line' i 'of CMS file' fileid ', to User Language' end /* Send signal indicating successful end of file: */ address M204 'IFSGNL 0' exit /* Exit with error message: */ exit: parse arg msg say 'Error' msg say 'RC' rc 'detail' statusdvar 'DROPBUF' buf exit

Transfer Control facility

The Transfer Control facility allows a SOUL request to identify a partner CICS program or SNA Communications Server application and transfer control to it. In addition, the request is allowed to pass a parameter area to the partner. Once the transfer has been effected, the user is disconnected from Model 204.

Requirements and considerations

The Transfer Control facility requirements and considerations for a "local" transfer to CICS differ from those for a "remote" transfer to a SNA Communications Server application. For example, if the transfer is to a CICS partner, the partner is a "process" identified by the value of the PARTNER parameter of the DEFINE PROCESS command. If the transfer is to a SNA Communications Server partner, the partner is an application identified by the value of the REMOTEID parameter of the DEFINE PROCESSGROUP command.

The description of the Transfer Control facility is divided into separate discussions for CICS and for SNA Communications Server.

CICS Transfer Control

The CICS Transfer Control facility allows a User Language request to identify a partner CICS program and transfer control to it. The transfer can be started by a user logged on to Model 204 through the CICS Interface. The User Language request is allowed to pass a parameter area to the partner.

System manager requirements

To use the Transfer Control facility:

• The DEFINE LINK, DEFINE PROCESSGROUP, DEFINE PROCESS, and OPEN LINK commands must be issued.
• The DEFINE LINK command must specify PROTOCOL=TRANSFER.
• The DEFINE PROCESS command must specify MODE=XCTL.
• The CICS partner process must be a CICS program defined to CICS.

TRANSFER statement

The TRANSFER statement is used to transfer control from a request to a CICS partner process. Any User Language statements between the TRANSFER statement and the request's END statement are not executed before the actual transfer of control.

Syntax

The format of the TRANSFER statement for CICS is:

TRANSFER [CONTROL] TO PROCESS {processname | %variable} [PASSING {IMAGE imagename | 'string' | %variable}]

Where:

• processname refers to a partner process defined in an already issued DEFINE PROCESS command. This name also can be provided as the value of a %variable.
• The PASSING clause identifies the data to be passed to the CICS program (the partner process). This data can be specified as an image, where imagename is an image previously defined in an image definition. The data also can be a quoted string or a %variable.

Execution

When the TRANSFER statement is executed, Model 204 first commits the current transaction with a COMMIT RELEASE statement. (For a detailed description of the COMMIT RELEASE statement, refer to RELEASE option.) After the transaction is committed, the following actions are performed:

• The user is disconnected from Model 204.
• The user is transferred to the specified partner process.
• The following Model 204 message appears in the audit trail:

*** M204.1899: TRANSFER STATEMENT COMPLETE, USER DISCONNECTED

This message can invoke an active ON ERROR unit and/or subsystem error procedure. (See Application Subsystem development for more information about error procedures and subsystems.) Rocket Software recommends that you treat this message not as an error message but as an indication of normal completion of the TRANSFER statement.

Receiving the transferred data

To receive the data passed by the User Language request, the CICS program can use instructions with the following format:

EXEC CICS HANDLE CONDITION QIDERR(label1) LENGERR(label2) EXEC CICS READQ TS QUEUE(queue_name) X ITEM(item_number) X INTO(buffer) LENGTH(buffer_length)

where queue_name is an 8-byte TS queue name made up of the string RECV followed by the terminal ID.

If the HANDLE CONDITION statement is omitted, and an error occurs reading the TS queue, the CICS program is abnormally terminated.

Example

PROCEDURE TRANSFER.TO.CICS * * TRANSFER CONTROL TO A CICS PROGRAM * THE DEFINE COMMANDS USUALLY ARE IN THE USER ZERO STREAM. * OTHERWISE, THE SYSTEM MANAGER IS NEEDED. * THEY ARE SHOWN HERE FOR DOCUMENTATION PURPOSES. * NOTICE THE REQUIRED OPEN LINK COMMAND. * ONCE OPENED, THE LINK REMAINS OPEN UNTIL EXPLICITLY * CLOSED BY AN EOJ OR BY THE FORCE OPTION OF THE CLOSE * LINK COMMAND. * DEFINE LINK LINK1 WITH SCOPE=SYSTEM TRANSPORT=TERMINAL - PROTOCOL=TRANSFER DEFINE PROCESSGROUP GROUP1 WITH SCOPE=SYSTEM - LINK=LINK1 DEFINE PROCESS CICSTRAN WITH SCOPE=SYSTEM DATALEN=40 - MODE=XCTL DESTINATION=GROUP1 PARTNER=CICSPGM OPEN LINK LINK1 * * BEGIN %TEXT IS STRING LEN 20 . . . ERROR.PROC: ON ERROR %TEXT = $ERRMSG IF %TEXT = 'M204.1899: TRANSFER ' THEN PRINT 'THE TRANSFER TO CICS WAS - SUCCESSFUL.' ELSE PRINT 'THE TRANSFER TO CICS HAS FAILED.' PRINT 'THE ERROR ENCOUNTERED IS: ' - WITH $ERRMSG END IF END ON . . . TRANSFER CONTROL TO PROCESS CICSTRAN PASSING %PARM.DATA . . . END PROCEDURE

SNA Communications Server Transfer Control

SNA Communications Server Transfer Control enables a Model 204 Online application in a SNA Communications Server network to simultaneously transfer control of the terminal and pass a command string to another designated SNA Communications Server application. Typically this transfer is from one Model 204 Online to another and is transparent to the user, involving no additional password entry or disruption for the terminal user. Upon transfer, the user is disconnected from the original application.

When the user transfers the terminal to another application, that application processes the accompanying command string, which can be as many as 255 bytes. If the destination application is a Model 204 Online, the command string can be formatted to log the user into an application subsystem, making the transfer transparent to the user.

When finished in the destination Online, the user can be transferred back to the original Model 204 Online or to another application in the SNA Communications Server network.

Terminology

In this section:

• The Model 204 Online from which a user is transferred is also referred to as the initial or transferring side, or Online.
• The application to which a user transfers is also referred to as the receiving or destination side, Online, or application.

System manager requirements

To use the Transfer Control facility, the DEFINE LINK, DEFINE PROCESSGROUP, DEFINE PROCESS, and OPEN LINK commands must be issued for the side initiating the transfer. These are system manager commands. The DEFINE LINK command must specify PROTOCOL=TRANSFER. The DEFINE PROCESS command must specify MODE=PASS.

When DEFINE PROCESS is set with MODE=PASS, only z/OS and z/VSE IODEV=7 users are allowed to initiate the TRANSFER statement.

The SNA Communications Server APPL statement that defines the transferring Model 204 Online to SNA Communications Server must include AUTH=(PASS,ACQ). The name in this statement is the same as the VTAMNAME User 0 parameter setting for the Model 204 Online. Arrange this with your SNA Communications Server systems programmer.

Security concerns are discussed in Security for Model 204-to-Model 204 transfers.

TRANSFER statement format and execution

The TRANSFER statement is used to transfer control from a User Language request to a SNA Communications Server application. Issuing TRANSFER in the request initiates this process.

The SNA Communications Server application transferred to is identified by its SNA Communications Server applid, which is the User 0 VTAMNAME parameter value for Model 204 destinations. This applid is specified on the REMOTEID parameter of the DEFINE PROCESSGROUP command for the Online initiating the transfer.

The TRANSFER statement for a SNA Communications Server transfer is valid only if the DEFINE PROCESS command for the Model 204 Online initiating the transfer specifies MODE=PASS and the DEFINE LINK command specifies PROTOCOL=TRANSFER.

If the user is transferred to another Model 204 Online, the command string passed at the time of transfer can be formatted by Transfer Control to automatically log the user in at the destination Online. TRANSFER statement and DEFINE PROCESS command options determine how the command string is to be formatted. For more information about these options, see the description of the PASSING parameter below, and also see Login command line formatting.

Syntax

The format of the TRANSFER statement is:

TRANSFER [CONTROL] TO PROCESS {processname | %variable} [WITH] [USERID {%variable | 'string'}] [PASSWORD {%variable | 'string'}] [ACCOUNT {%variable | 'string'}] [PASSING {IMAGE imagename | 'string' | %variable}]

Where:

• processname is the name of a process defined in a DEFINE PROCESS command for the transferring side. This name also can be provided as the value of a %variable.
• USERID specifies the user ID of the user that is being transferred.

  USERID is allowed only if the DEFINE PROCESS command options MODE=PASS and UIDSOURCE=OPEN are specified.

  If USERID is specified, the Transfer Control facility assumes that the transfer is to another Model 204 Online, and it automatically formats and encrypts a LOGON command string for the destination Online. For more information about this formatting, see Login command line formatting.

  USERID can also be provided as the value of a %variable.

• PASSWORD specifies the password to be included in the LOGON command string sent to the Model 204 destination Online.

  PASSWORD is accepted only if the DEFINE PROCESS command options MODE=PASS and UIDSOURCE=CURRENT or UIDSOURCE=OPEN are specified. If MODE=PASS and UIDSOURCE=OPEN, and USERID is not specified on the TRANSFER statement, PASSWORD is ignored.

  PASSWORD can also be provided as the value of a %variable.

  Unlike the account and user ID, the current user password is not available in decrypted form to a Model 204 Online. If sending a password is appropriate, the User Language request must supply it.

• ACCOUNT specifies the account value to be included in the LOGON command string sent to the Model 204 destination Online.

  ACCOUNT is accepted only if the DEFINE PROCESS command option MODE=PASS and the TRANSFER option USERID are specified. ACCOUNT is overridden by the DEFINE PROCESS command option ACCTSOURCE (see Login command line formatting); it is ignored if USERID is not specified.

  ACCOUNT can also be provided as the value of a %variable.

• The PASSING clause identifies the data to be passed to the destination SNA Communications Server application.

  PASSING data can be specified as an image, where imagename is an image previously defined in an image definition. The data also can be a quoted string or a %variable.

  When MODE=PASS and either of the DEFINE PROCESS options UIDSOURCE=CURRENT or UIDSOURCE=OPEN are specified, it is assumed the SNA Communications Server application is another Model 204 Online. A LOGON command string is formatted automatically, and the PASSING data is attached to the end of the string. For more information about this automatic formatting, see Login command line formatting.

  Be sure that only Model 204 commands are entered in the PASSING data when transferring to another Model 204 Online.

Execution

When the request containing the TRANSFER statement is executed, the user is disconnected from Model 204 on the transferring side and transferred to the destination application. The following events are included:

• Transparent to the user, Model 204 issues an OPEN PROCESS in preparation for the transfer.
• The user stays connected to the initial Model 204 Online until that Online receives notification that a session is established with the destination SNA Communications Server application. Depending on the notification, the following actions are performed:

If the notification is that the session is rejected by the destination SNA Communications Server application, control is returned to the statement following the TRANSFER statement.

If the time waiting on notification exceeds the time specified on the TIMEOUT option of the DEFINE PROCESS command, the user is disconnected from the initial Model 204 Online and returned to SNA Communications Server.

If the notification is that the session is established with the destination SNA Communications Server application, the user is disconnected from the initial Model 204 Online and transferred to the specified destination.

• Before the disconnection preceding a transfer, Model 204 commits the current transaction with a COMMIT RELEASE statement. (For a detailed description of the COMMIT RELEASE statement, refer to RELEASE option.)

  After the disconnection, SNA Communications Server executes the CLSDST=PASS macro, which transfers the user to the SNA Communications Server application specified in the DEFINE PROCESSGROUP REMOTEID option.

• The following Model 204 message appears in the audit trail:

*** M204.1899: TRANSFER STATEMENT COMPLETE, USER DISCONNECTED

This message can invoke an active ON ERROR unit and/or subsystem error procedure. (For more information about error procedures and subsystems, see Application Subsystem development.) It is recommended that you treat this message not as an error message but as an indication of normal completion of the TRANSFER statement.

Login command line formatting

For transfers between Model 204 Onlines, the data passed at the time of transfer can include an automatically formatted (and encrypted) LOGON command string. The transferred user thereby gains access to the destination Model 204 Online without having to enter a password, and any other commands in the passed data are processed thereafter.

A transfer that enables login of a user without a password is called trusted. No password is formatted in the passed command line nor checked for at the receiving side: the receiving Online trusts that the transferring Online has verified the user's password and allows the user to log in without a password. This feature is also used by the Model 204 product Horizon, and is described in detail in Horizon network security.

Note: The exception to the previous feature is SNA Communications Server Transfer Control does not support Guest User that is used by Horizon.

A user can also transfer with an automatically formatted LOGON string that includes a password. Such a transfer is non-trusted and can only occur between two Model 204 Onlines. For transfers between Model 204 Onlines, the inclusion of an automatically formatted LOGON string is optional. Transfers to a non-Model 204 destination do not have the option of including an automatically formatted LOGON string.

The login formatting options are controlled by TRANSFER statement and DEFINE command parameter combinations which determine if or how the command string is to be formatted.

Components of transferred data

The data string passed during a transfer is the sum of two components, the automatically formatted login string and the value of the PASSING parameter.

The PASSING parameter contents is the value of the TRANSFER statement PASSING parameter. This string can contain whatever commands or data the transferring side is to have processed at the receiving side. For non-trusted Model 204 to Model 204 transfers, this string can contain a LOGON command line with optional password in addition to other Model 204 commands.

The login string contents depend on whether the transfer is trusted or not.

Components of formatted login string

If the transfer is trusted, the encrypted login string contains this information:

VTAM applid, LOGON userid, processgroupname

Where:

• SNA Communications Server applid is the transferring side's SNA Communications Server applid (User 0 parameter VTAMNAME value). This value must be the same as the receiving side's DEFINE PROCESSGROUP command REMOTEID parameter.
• LOGON is the Model 204 LOGON command.
• userid is the user ID to be logged in at the destination Online. If UIDSOURCE=CURRENT, the transferring user's current user ID is used. If UIDSOURCE=OPEN, the user ID specified on the TRANSFER statement USERID parameter is used.
• processgroupname is the name set in the receiving side's processgroup definition. This name must be the same as the value of the transferring side's DEFINE PROCESS command PARTNER parameter.

If the transfer is non-trusted, the encrypted string can contain this information:

VTAM applid, LOGON userid, password

Where:

• SNA Communications Server applid is as defined above. However, this value is not checked if the transfer is non-trusted.
• LOGON and userid are as defined above.
• password is the transferring user's. It is obtained from the TRANSFER statement PASSWORD parameter, if coded. If no PASSWORD is coded, the user is prompted for one at the destination Online.

Controlling login string formatting

This section summarizes the DEFINE command and TRANSFER statement parameter settings required to indicate whether a login string is automatically formatted and from where the user ID and password (if any) are obtained. The description is divided according to the type of transfer (trusted or non-trusted).

Where possible, the description includes the mutual dependencies of the TRANSFER statement parameters (USERID and PASSWORD), but leaves out the ACCOUNT parameter. For more information about these parameters, see TRANSFER statement and also Login command line formatting. Login command line formatting shows the effect on automatic login formatting of all the dependencies and combinations of the DEFINE PROCESS and TRANSFER parameters.

Trusted transfers

Trusted transfers are possible between Model 204 Onlines that have LOGIN=TRUST on both DEFINE PROCESSGROUPs.

1. Pass an automatically formatted login string with no password at the time of transfer along with whatever PASSING data is entered.
   • Make sure LOGIN=TRUST is specified on both DEFINE PROCESSGROUPs; LOGIN=NOTRUST is the default.
   • Make sure the receiving side's DEFINE PROCESSGROUP command REMOTEID parameter is set to the SNA Communications Server applid of the transferring side.
   • Make sure the transferring side's DEFINE PROCESS command PARTNER parameter is set to the processgroup name of the receiving side.
   • Indicate automatic formatting. Set the transferring side's DEFINE PROCESS command UIDSOURCE parameter to a value other than the default, NONE. UIDSOURCE=NONE prevents automatic login formatting.
   • Indicate where to get the user ID. If UIDSOURCE=CURRENT, the transferring user's current user ID is used. If UIDSOURCE=OPEN, the user ID specified on the TRANSFER statement USERID parameter is used.

   The trusted feature is nullified if you include a password in the TRANSFER statement PASSWORD parameter. In this case, the transfer is permitted but the PASSWORD value is checked at the receiving side.

Non-trusted transfer options

Non-trusted transfers are between Model 204 Onlines that have LOGIN=NOTRUST set on either of the DEFINE PROCESSGROUP commands. Formatting options follow:

1. Pass an automatically formatted login string along with PASSING data.
   • Indicate automatic formatting. Set the transferring side's DEFINE PROCESS command UIDSOURCE parameter to a value other than the default, NONE. UIDSOURCE=NONE prevents automatic login formatting.
   • Indicate where to get the user ID. If UIDSOURCE=CURRENT, the transferring user's current user ID is used. If UIDSOURCE=OPEN, the user ID specified on the TRANSFER statement USERID parameter is used.
   • Indicate where to get the password. Provide for one either in the automatically formatted login string (code the TRANSFER statement PASSWORD parameter) or by entering it in response to a prompt at the receiving side.
2. Have no automatic login string formatted. This is the default option.

Indicate no automatic formatting by not setting the DEFINE PROCESS command UIDSOURCE parameter. UIDSOURCE=NONE, the default, prevents automatic formatting of the login string. UIDSOURCE=OPEN with the TRANSFER statement USERID parameter not set also means do not automatically format a login string (see Login command line formatting).

LOGIN need not be set since LOGIN=NOTRUST is the default.

Include any login information in the PASSING data.

Coordinating TRANSFER and DEFINE PROCESS parameters

The options selected in the DEFINE PROCESS and TRANSFER CONTROL statement determine whether the Transfer Control facility automatically formats a Model 204 login data string.

Login command line formatting shows the resulting determination for the DEFINE PROCESS and TRANSFER CONTROL combinations. The values in the table have the following meanings:

DPU	Depends if USERID is set or not
ERR	Cancel request and issue error message
N/A	Not applicable
NO	No automatic formatting; assume transfer is to a non-Model 204 SNA Communications Server application
YES	Automatically format login data

Security for Model 204-to-Model 204 transfers

SNA Communications Server Transfer Control enables transfer from one Model 204 Online to another without the necessity of entering a password at the destination Online. To be sure that such a transfer is secure, the Transfer Control facility has security measures to control:

• The users who can access the destination Model 204 Online
• The system from which a user can transfer
• The format of the passed data

The rest of this section discusses Transfer Control facility protection for transfers from one Model 204 Online to another. For transfer to a non-Model 204 application, there is no automatic formatting and passing of a login command line. The security measures described below are not applicable.

User access protection

The Transfer Control facility uses Model 204 login and subsystem security to facilitate and secure the access of a transferred user to the receiving Model 204 system.

Login security ordinarily ensures that a user has a valid user ID and, if included, a valid password. Transfer Control uses the trusted partner feature, which enables login of a transferred user without a password.

A trusted transfer requires that both Model 204 Onlines involved have LOGIN=TRUST included in their processgroup definitions. The transferred user is logged in without a password and is assigned privileges as usual (from CCASTAT or an external security package) according to user ID.

For more information about login privileges, see the login security description in DEFINE PROCESSGROUP command: Transfer Control and see Subsystem_security.

Note: Only ACF2 is supported for Trusted Login; Security Server (formerly RACF) and Top Secret are not. Also, Guest User is not supported for SNA Communications Server Transfer Control.

You can optionally include a password in the data passed in a transfer where both sides have LOGIN=TRUST. However, such a transfer thereby becomes non-trusted. The password is checked at the receiving side and the user is processed according to normal Model 204 login security. Non-trusted transfers between Model 204 Onlines always require that a valid password be supplied to the receiving side.

System-level protection

DEFINE command parameter settings at both Model 204 systems participating in a trusted transfer must be coordinated to enable an automatic login upon transfer to take place:

• DEFINE PROCESSGROUP

  The receiving side's REMOTEID parameter must be set to the SNA Communications Server applid of the transferring side. This SNA Communications Server applid is part of the formatted command line passed to and checked at the receiving side. An invalid applid value prevents automatic login at the receiving side.

• DEFINE PROCESS

  The transferring side's PARTNER parameter must be set to the processgroup name of the receiving side. This processgroup name is part of the formatted command line passed to and checked at the receiving side. An invalid PARTNER value prevents automatic login at the receiving side.

These DEFINE command parameter settings are not checked at the receiving side if the transfer is non-trusted.

Command line protection

Both trusted and non-trusted transfers between Model 204 Onlines can include an accompanying automatically formatted LOGIN command string. Whether this automatic formatting occurs depends on the parameter options set on the TRANSFER statement and on the transferring side's DEFINE PROCESS command. For more information about this automatic formatting, see Login command line formatting.

The Transfer Control facility protects an automatically formatted LOGIN command string by encryption. The encrypted string is decrypted by the receiving Online.

$REMOTE for transferring back

For transfers into a Model 204 Online from another Model 204 Online, the $REMOTE function simplifies transfer back to the initial Online. $REMOTE returns the SNA Communications Server applid of the original Model 204 Online. This value is used by a User Language request at the destination Online if a return transfer is desired.

Syntax

The $REMOTE function takes no arguments. If an IODEV=7 thread is used to connect to a Model 204 Online, $REMOTE returns an 8-byte character string consisting of the SNA Communications Server applid of a remote Model 204 Online. If the user transferred into the Model 204 Online from a non-Model 204 Online, $REMOTE returns blanks. $REMOTE returns a value only if used with an IODEV=7 thread.

Operation

In the discussion that follows, the "initial side" is the Model 204 Online from which a user is transferred. The "receiving side" is the Model 204 Online to which the user is transferred.

Implementing a return transfer with $REMOTE requires coordination of the receiving side's network definitions and return TRANSFER statement.

1. Network definitions

   Set up the receiving side's DEFINE LINK and DEFINE PROCESSGROUP commands as recommended thus far beginning in SNA Communications Server Transfer Control, in the DEFINE command descriptions, and in SNA Communications Server Transfer Control examples. The DEFINE PROCESS definition involves the crucial tactic: Define a process with the same process name as the process group definition REMOTEID value, namely, the SNA Communications Server applid of the initial side.

2. TRANSFER statement

   Capture the value of $REMOTE in a %variable. Use this %variable as the processname %variable on a TRANSFER statement issued at the receiving side.

   The TRANSFER statement is thus directed via $REMOTE to the process definition, and via the process definition to the processgroup REMOTEID, which points to the initial side.

   This approach increases in value as the number of potential transfer partners increases. Only a new process and processgroup have to be defined for each new partner; the User Language request with the TRANSFER statement remains the same.

Example

In the following example, a user has been transferred into a Model 204 Online with SNA Communications Server applid M204B, from a Model 204 Online with SNA Communications Server applid M204A. Using the following DEFINE commands and User Language request, the user is transferred back to the initial Model 204 Online, M204A, logged in with the current user ID and trusted password, and placed into an APSY subsystem called INQUIRY.

* * Network Definitions for M204B, the * destination Online: DEFINE LINK M204BL WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP M204BPG WITH SCOPE=SYSTEM - LINK=M204BL - REMOTEID=M204A - LOGIN=TRUST DEFINE PROCESS M204A WITH SCOPE=SYSTEM - PARTNER=M204APG - DESTINATION=M204BPG - DATALEN=100 - MODE=PASS - UIDSOURCE=CURRENT * * * Opening of the link: OPEN LINK M204BL *

The User Language statements for transferring back to M204A follow:

BEGIN . . . %PROCSNAME = $REMOTE %DATA = 'INQUIRY' . . . TRANSFER CONTROL TO PROCESS %PROCSNAME - PASSING %DATA . . . END

When a transfer fails

When a TRANSFER statement is invoked and the transfer fails, the $REMOTE function returns an 8-character string of blanks.

Error handling

Error conditions during SNA Communications Server transfers are listed below followed by their remedies.

• The session is not established when attempting transfer to a SNA Communications Server application, and the user is left in native SNA Communications Server.

  For example, if a user is transferred to a Model 204 Online and no threads are available, the session is rejected and the user is left in native SNA Communications Server. In this case, the initial Model 204 Online is notified that the session was not established in the destination SNA Communications Server application. The user is not logged out of the initial Model 204 Online until either this notification is received or the TIMEOUT parameter on the DEFINE PROCESS command expires.

• The TIMEOUT parameter is a safeguard against a terminal hang while establishing the session with the destination SNA Communications Server application.
• An incorrect password or user ID is passed to the destination Online with the transfer, and the user is left at command level in the destination Online.

  The user can attempt to login manually to the destination Online. Once the login process is correctly completed, the rest of the passed command string is processed.

• After the user is logged in at the destination Model 204 Online, an error occurs while the rest of the command string is being processed; the user is left at command level in the destination Online.

  A message is issued indicating the user's original Model 204 Online VTAMNAME and current Model 204 Online VTAMNAME. Also, the User Language $REMOTE function is available. $REMOTE returns to the User Language request the SNA Communications Server applid of the Model 204 Online that initiated the transfer.

  A User Language request can use the SNA Communications Server applid of the initial Online to transfer the user back to that Online, as described on $REMOTE for transferring back.

SNA Communications Server Transfer Control examples

This section has a series of examples of SNA Communications Server transfers. The examples show different combinations of partner characteristics (Model 204 and non-Model 204, trusted and non-trusted) and formatting of command lines (automatically formatted login or user-formatted).

Example 1: To a non-Model 204 SNA Communications Server application

The transfer is to a SNA Communications Server application other than Model 204. The user is logged out of Model 204 and transferred into the SNA Communications Server application ANYAPPL. For the side initiating the transfer:

* Network definitions DEFINE LINK TRANF1 WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP TRANF1PG WITH SCOPE=SYSTEM - LINK=TRANF1 - REMOTEID=ANYAPPL DEFINE PROCESS TRANF1PR WITH SCOPE=SYSTEM - DESTINATION=TRANF1PG - PARTNER=ANYAPPL - DATALEN=100 - MODE=PASS * Link opening OPEN LINK TRANF1 * User Language BEGIN . . %DATA='TRANSFERRED FROM A MODEL204 ONLINE' TRANSFER CONTROL TO PROCESS TRANF1PR PASSING %DATA . . . END

Comments

Since the side receiving the transfer is not a Model 204 application, no Model 204 login string is formatted. The value of the DEFINE PROCESS parameter PARTNER is the SNA Communications Server applid of the destination and not the name of the process group defined at the destination. The SNA Communications Server applid is used because the application transferred to is not a Model 204 Online, which rules out the possibility of a trusted transfer.

Example 2: From Model 204 to another Model 204, with NOTRUST

The user transfers from a Model 204 Online to another Model 204 Online. The processgroups for both partners are defined with LOGIN=NOTRUST (the default). The transferring user is logged out of the initial Model 204 Online and transferred to the receiving side, whose SNA Communications Server applid is M204B. M204B accepts this user as a normal SNA Communications Server login and processes the rest of the passed data string. For the side initiating the transfer:

* Network definitions DEFINE LINK TRANF1 WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP TRANF1PG WITH SCOPE=SYSTEM - LINK=TRANF1 - REMOTEID=M204B DEFINE PROCESS TRANF1PR WITH SCOPE=SYSTEM - DESTINATION=TRANF1PG - PARTNER=M204B - DATALEN=100 - MODE=PASS * Link opening OPEN LINK TRANF1 * User Language BEGIN . . %DATA='LOGON USERID;PASSWORD;OPEN PROCFILE; - I PROC' . . TRANSFER CONTROL TO PROCESS TRANF1PR PASSING - %DATA . . END

Comments

The Model 204 login data string is formatted "manually" in the User Language request (see %DATA). The value of the DEFINE PROCESS parameter PARTNER is the SNA Communications Server applid of the destination and not the name of the process group defined at the destination. The process group name is not required because the transfer is not a trusted transfer.

Since the transfer is to a non-trusted Model 204 Online, and a transfer out of that Online is not anticipated, the LINK, PROCESSGROUP, and PROCESS definitions for that Online are not necessary. These definitions are required only for the side initiating a transfer or for both sides when a transfer is trusted.

Example 3: From Model 204 to Model 204 with formatted login data string

The user transfers from a Model 204 Online to another Model 204 Online. The processgroups for both sides are defined with LOGIN=NOTRUST, by default. The LOGON command data string containing the current user ID is built at transfer time. The password is prompted for by the User Language request and passed in the login data string at the time of transfer. For the side initiating the transfer:

* Network definitions DEFINE LINK TRANF1 WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP TRANF1PG WITH SCOPE=SYSTEM - LINK=TRANF1 - REMOTEID=M204B DEFINE PROCESS TRANF1PR WITH SCOPE=SYSTEM - DESTINATION=TRANF1PG - PARTNER=M204B - DATALEN=100 - MODE=PASS - UIDSOURCE=CURRENT * Link opening OPEN LINK TRANF1 * User Language BEGIN . . %PSWD=$READ('ENTER PASSWORD') . . %DATA='OPEN MYFILE;I MYPROC' . . TRANSFER CONTROL TO PROCESS TRANF1PR WITH - PASSWORD %PSWD PASSING %DATA . . END

Comments

The LOGON command line has the format:

LOGON currentuserid;password;OPEN MYFILE;I MYPROC

The current user ID is formatted into the login command string because UIDSOURCE=CURRENT is set on the process definition. The password prompted for at the time of transfer (by $Read) is also formatted into the login command string.

Since the transfer is not trusted, a password must be provided. Once the correct password is identified, the rest of the passed data string is processed. If a correct password is not provided, the user can try to manually log in. If the user eventually logs in successfully, the rest of the passed data string is processed.

Since UIDSOURCE=CURRENT, the transfer is assumed to be to another Model 204 Online, and the login data string is encrypted. The string is decrypted upon receipt by M204B, the Online to which the user is transferred.

The value of the DEFINE PROCESS parameter PARTNER is the SNA Communications Server applid of the destination, and not the name of the processgroup defined at the destination. The processgroup name is not required because the transfer is not a trusted transfer.

Since the transfer is to a non-trusted Model 204 Online, and a transfer out of that Online is not anticipated, the LINK, PROCESSGROUP, and PROCESS definitions for that Online are unnecessary. These definitions are required only for the side initiating a transfer or for both sides when a transfer is trusted.

Example 4: From Model 204 to Model 204, with TRUST

The user transfers from a Model 204 Online to another Model 204 Online. The system managers have set both Model 204 Onlines to LOGIN=TRUST. The user is transferred without a password. For M204A, the side initiating the transfer:

* Network definitions DEFINE LINK M204AL WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP M204APG WITH SCOPE=SYSTEM - LINK=M204AL - REMOTEID=M204B - LOGIN=TRUST DEFINE PROCESS M204APR WITH SCOPE=SYSTEM - PARTNER=M204BPG - DESTINATION=M204APG - DATALEN=100 - MODE=PASS - UIDSOURCE=CURRENT * Link opening OPEN LINK M204AL

For M204B, the Online to which the user is transferred:

* Network definitions DEFINE LINK M204BL WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP M204BPG WITH SCOPE=SYSTEM - LINK=M204BL - REMOTEID=M204A - LOGIN=TRUST DEFINE PROCESS M204BPR WITH SCOPE=SYSTEM - PARTNER=M204APG - DESTINATION=M204BPG - DATALEN=100 - MODE=PASS - UIDSOURCE=CURRENT * Link opening OPEN LINK M204BL

Now the user logs into M204A:

* Initiating the transfer from M204A * User Language BEGIN . . %DATA='OPEN FILE;I PROC' . . TRANSFER CONTROL TO PROCESS M204APR PASSING %DATA . . END

At this point the user has been logged out of M204A and has been logged into M204B.

Comments

An encrypted login data string is built using the current user ID, M204B's process group name (M204BPG), no password (since the transfer is trusted), and the contents of %DATA.

The value of the DEFINE PROCESS parameter PARTNER is the process group defined at the destination and not the SNA Communications Server applid of the destination Online. The process group is used because the transfer is trusted. For security, the destination process group name is passed in the login command line and checked.

The user is logged into M204B without a password for two reasons:

• M204A knows the trusted processgroup name of M204B (PARTNER=M204BPG).
• M204B's processgroup M204BPG is set with REMOTEID equal to M204A's SNA Communications Server applid and LOGIN=TRUST.

Since the transfer to M204B is to a trusted Model 204 Online, the LINK and PROCESSGROUP definitions for that Online are necessary. The PROCESS definition for that Online is optional, unless a transfer out of that Online is anticipated.

Although the process definition for M204B is not necessary for a transfer to M204B, it can be specially defined so that M204B can transfer the user back to the initial Online, M204A. For more information about return transfers, see Security for Model 204-to-Model 204 transfers.

Example 5: From trusted to non-trusted Model 204

The user transfers from a trusted Model 204 Online to a non-trusted Model 204 Online. The user is prompted for a password in the destined Online, after which the rest of the login data string is acted upon. For M204A, the side initiating the transfer:

* Network definitions DEFINE LINK M204AL WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP M204APG WITH SCOPE=SYSTEM - LINK=M204AL - REMOTEID=M204B - LOGIN=TRUST DEFINE PROCESS M204APR WITH SCOPE=SYSTEM - PARTNER=M204BPG - DESTINATION=M204APG - DATALEN=100 - MODE=PASS - UIDSOURCE=OPEN * Link opening OPEN LINK M204AL

For M204B, the Online to which the user is transferred:

* Network definitions DEFINE LINK M204BL WITH SCOPE=SYSTEM - PROTOCOL=TRANSFER - TRANSPORT=TERMINAL DEFINE PROCESSGROUP M204BPG WITH SCOPE=SYSTEM - LINK=M204BL - REMOTEID=M204A - LOGIN=NOTRUST * Link opening OPEN LINK M204BL * User Language BEGIN . . %UID=$READ('ENTER USERID') . . %DATA='OPEN FILE;I PROC' . . TRANSFER CONTROL TO PROCESS M024APR WITH USERID - %UID PASSING %DATA . . END

Comments

A login data string is built using %UID, no password, and the %DATA contents. The login data string is encrypted and passed to M204B. M204B decrypts the login data string and prompts for a password.

Because the processgroup M204BPG is defined with LOGIN=NOTRUST, and no password is passed, the user is prompted for a password. After the correct password is entered, the rest of the passed data string is processed. If the correct password is not given, the user can try to manually log in. If the user eventually logs in successfully, the rest of the passed data string is processed.

The value of the DEFINE PROCESS parameter PARTNER is the processgroup defined at the receiving side. It could also be the SNA Communications Server applid of the receiving Online. Because the transfer is not trusted, the processgroup name is neither passed with the login command line nor checked for at the receiving Online.

Since the transfer to M204B is to a non-trusted Model 204 Online, the LINK and PROCESSGROUP definitions for that Online are not necessary. The PROCESS definition for that Online is optional unless a transfer out of that Online is anticipated.

Horizon

This section provides a brief overview of the optional distributed application facility, Horizon, and the User Language statements that support it. For detailed information about using Horizon, see the Horizon wiki topics. This information includes syntax and usage description for the User Language statements and Model 204 commands, as well as information relating to the installation and use of a Horizon network.

IBM has determined a set of conventions governing communication between different members of a computer network. These conventions, defining the structure of the network and the rules for communication within the network, are IBM's Systems Network Architecture (SNA). One subset of these conventions are the LU (logical unit) 6.2 protocols, which are conversation rules that cover SNA program-to-program communications.

The LU 6.2 protocols govern communication between Model 204 programs residing in the same or different Online environments. Other protocols govern other types of communication. For example, communication between User Language requests and CICS programs or CMS EXECs in the same Online environment use non-conversational process-to-process protocols.

Horizon verbs are Model 204 commands and User Language statements

The LU 6.2 conversation rules are enforced by software that consists of a group of instructions, or verbs, that control the maintenance of the network and the interactions between conversation partners. The Model 204 LU 6.2 interface, Horizon, is a collection of Model 204 commands and User Language statements:

• The Model 204 commands define and control a network that includes the host Model 204 program.
• The User Language statements correspond to LU 6.2 conversation verb definitions and govern conversations between the host Model 204 program and other partner Model 204 or non-Model 204 programs.

Horizon uses variations of several of the User Language statements and Model 204 commands that are used with the TPROCESS facility (discussed on User Language TPROCESS communication).

LU 6.2 security considerations slightly affect some SUBSYSMGMT screens (see System requirements for Application Subsystems and Security interfaces).

User Language interface

The LU 6.2 User Language statements that can be issued by a program are dependent on the state of the particular conversation. This state can be determined through the use of the QUERY PROCESS statement, which is described in this section.

In keeping with error handling for TPROCESS (discussed on Error handling for TPROCESS statements), error conditions encountered during the execution of the Horizon User Language statements are not displayed on the terminal. The User Language request should check for errors by using the $STATUS and $STATUSD functions. The text of the most recently issued error message can be retrieved by using the $Errmsg function.

OPEN PROCESS statement

The OPEN PROCESS statement initiates the conversation. This involves the allocation of an existing session or the starting of a new session, if possible.

There are two distinct uses of the OPEN PROCESS statement:

• The client process uses OPEN PROCESS to allocate an outbound conversation; that is, to invoke a server process. Allocation involves creating control blocks, getting control of a session for the conversation, and requesting the initiation of the server process at the remote site with optional initialization parameters.
• The server process uses OPEN PROCESS to identify an inbound conversation. An inbound OPEN PROCESS statement (that is, OPEN PROCESS with the ACCEPT operand) can be issued only by a server process. Its purpose is to get any initialization parameters specified in the initiation of the conversation by the client process.

In addition, the OPEN PROCESS statement establishes the conversation ID (CID) for both types of conversations.

CONFIRM statement

The CONFIRM statement sends a confirmation request to a remote process. The User Language request then waits for the receiver to issue CONFIRMED or SEND ERROR. This statement allows the local and remote processes to synchronize their processing with one another. The conversation buffer is flushed as a result of this statement.

CONFIRMED statement

The CONFIRMED statement sends a positive confirmation to the remote process that the last statement was executed successfully. This is issued only in response to a CONFIRM request.

CLOSE PROCESS statement

The CLOSE PROCESS statement deallocates the specified conversation from the process.

FLUSH PROCESS statement

The FLUSH PROCESS statement causes the conversation buffer to be sent to the conversation partner.

INVITE statement

The INVITE statement permits a program to request data from one or more partners simultaneously and allows the issuing program to continue to run while its requests for data are being processed. The INVITE statement causes the send buffer to be flushed to the partner, and places the partner in Send state, enabling the partner to send data when it is ready. After INVITE is issued, the issuing program continues to execute.

QUERY PROCESS statement

The QUERY PROCESS statement returns information about a conversation. The information returned depends on the parameters specified; the types of information include:

• Current conversation state of the conversation
• Name of the process group associated with the conversation
• Name of the LU at which the remote process is located
• Level of synchronization processing used for the conversation (that is, whether confirmation processing is allowed)
• Mode name for the session that the conversation is using

RECEIVE statement

The RECEIVE statement receives any data sent by the remote process.

SIGNAL PROCESS statement

The SIGNAL PROCESS statement notifies the remote process that the local process is requesting to enter SEND state.

SEND statement

The SEND statement transmits data to the remote process.

SEND ERROR statement

The SEND ERROR statement sends negative acknowledgments indicating that the local process detected an application error. SEND ERROR forces a conversation interruption.

TEST RECEIPT statement

The TEST RECEIPT statement determines whether or not a partner process has sent anything in reply to an INVITE statement. Using TEST RECEIPT allows the issuing program to perform other tasks while the partner is preparing its reply to the INVITE. After a reply is detected, the RECEIVE statement is used to store the data sent.

WAIT FOR RECEIPT statement

The WAIT FOR RECEIPT statement causes the issuing User Language program to stop running until a reply is received from the specified remote partner(s). After a reply is detected, the RECEIVE statement is used to store the data sent.

BATCH2 facility

The BATCH2 utility program accesses a Model 204 Online that is running in a separate region, partition, or virtual machine. BATCH2 establishes a remote User Language connection which emulates a line-by-line terminal.

The BATCH2 utility program reads a user-specified input data stream and transmits this data to the Model 204 Online. The resulting output generated by the Online is written to a user-specified output data stream.

You can set a job-step return code in BATCH2 jobs. In addition to the abnormal termination error codes, 300 and 600, BATCH2 now returns a user's return code to the job step or exec.

If BATCH2...	Return code value is...
Completes normally	Highest return code received by the user of the BATCH2 thread. Unlike in a single user job, this value is independent of the highest return code value for the entire Online job. When invoking BATCH2, the job-step or exec specifies the type of return code to return: a batch or Online value.
Terminates abnormally	Same completion codes as in previous releases, 300 or 600. These are return codes for the BATCH2 job itself and are not user values.

Usage notes

• The return code is specific to each user. If the User Language stream in the BATCH2 CCAIN file logs on more than one user, the value returned is for the last user logged on; it is not the highest return code received by any other user of the thread.
• If a user runs as a connected but not logged on user (that is, no user was logged on in the CCAIN stream), then BATCH2 returns no user return code; the return code is 0.
• BATCH2 logs the user out of Model 204 when it reaches the end of the CCAIN stream. If the LOGOUT command is explicitly entered in the CCAIN stream, then no user is logged on when BATCH2 terminates and issues its final LOGOUT. In this case the return code is not available to BATCH2 and the return code is 0. Therefore, to obtain the BATCH2 return code, do not enter the LOGOUT command in the CCAIN stream. Also, if message M204.0353 is set to NOTERM with the MSGCTL command, return codes will not be available unless CUSTOM=6 is set.
• $Jobcode can now be called by Online as well as batch users. This means that calls to $Jobcode can now be included in the CCAIN stream. See $Jobcode.

Support required for BATCH2

• The z/OS or z/VSE BATCH2 user must access Model 204 with an IODEV=29 thread; a CMS user must use an IODEV=39 thread.
• The M204IFAM EXEC must be available on the CMS machine that is running the BATCH2 utility.
• For z/OS and z/VSE, CRAM must be installed.

Specifying runtime parameters

You can specify the channel name of the Model 204 Online to which the BATCH2 utility is connecting and can control the messages BATCH2 displays in the output stream by setting the channel name and OMC runtime (User 0) parameters. Examples showing where and how these parameters are specified for each operating system are provided beginning with z/OS JCL using BATCH2 through CMS job using BATCH2.

Channel name parameter

The channel name determines the specific Model 204 Online with which BATCH2 establishes a connection.

The Model 204 system manager should supply the channel name for the Online to which you want to connect. If you do not specify the channel name parameter, a default value of M204PROD for z/OS and z/VSE or M204VMIO for z/VM is used.

Output Message Control (OMC) parameter

The OMC parameter allows you to specify a category of output messages to be discarded.

For example, suppose the input data stream contains an OPEN NEWFILE command. BATCH2 transmits this data to the ONLINE when it is read from the input data stream. The Online region sends BATCH2 the following message:

M204.0620: FILE NEWFILE OPENED

When this message is received, BATCH2 writes it to the output data stream.

If you do not want this type of message written to the output data stream, specify the appropriate value in the OMC parameter. In this example, the M204.0620 message belongs to the information message category (Class I). If you specify an OMC parameter value of 4, BATCH2 discards this and all Class I messages.

OMC options

Under z/OS or CMS, you can specify the OMC parameter value, in either decimal (ddd) or hexadecimal (hh) form, as any combination of the options in Specifying runtime parameters. Values can be summed. Equivalent bit settings for z/VSE are shown in z/VSE JCL using BATCH2.

OMC parameter options

Decimal (ddd)	Hexadecimal (hh)	Discards...
128	X'80'	Class E messages (error messages)
64	X'40'	New page indicator (page eject)
32	X'20'	This job, if the user is restarted
16	X'10'	Nondisplay input prompt messages
8	X'08'	$READ prompt messages
4	X'04'	Class I messages (informational messages)

The default value for the OMC parameter is zero, which results in these actions:

• All messages are written to the CCAOUT data stream.
• The new page requests are honored with a page eject.
• The user restarted condition is ignored.

User return code (URCTYPE) parameter

The URCTYPE parameter specifies the type of return code that BATCH2 returns to the job-step or exec that invoked the utility. The parameter is a single character:

Value	Returns
N (default)	Zero (0) and is equivalent to omitting the parameter
O	Online value
B	Batch value

Input and output data streams

BATCH2 uses the CCAIN and CCAOUT files for the input and output data streams, respectively. You can control some characteristics of the input and output data streams by setting User 0 input and output parameters.

Specifying input stream characteristics

CCAIN defines the input data stream to be transmitted to the Model 204 ONLINE. BATCH2 reads this data stream and transmits each record to the ONLINE.

The data stream appears to the ONLINE as if it were transmitted by a line-by-line terminal. Therefore, the INMRL and INCCC User 0 parameter values for this thread determine, respectively, the maximum length of the input line and the continuation character position.

Specifying output stream characteristics

CCAOUT defines where the output data stream, the output generated for this user from the Model 204 Online, is written. BATCH2 receives the output from the Online and writes each record to the output data stream.

Because BATCH2 emulates a line-by-line terminal, the values of the User 0 parameters OUTMRL and OUTCCC for this thread determine, respectively, the maximum length of the output line and the continuation character position.

Using *DEVICE command in BATCH2 jobs

To change the values used for OUTMRL and OUTLPP, use the *DEVICE command and the RESET command.

If an input line begins with *DEVICE, followed by a number, a comma, and another number, the first number is used to change the value used for OUTMRL and the second is used to change OUTLPP.

Note: The values of OUTMRL and OUTLPP (as returned by the VIEW command) are not actually updated, however, until the RESET command is issued.

This is the only way to affect the value of OUTMRL used for output lines; that is, the RESET OUTMRL command does not have the effect of changing the buffer size of OUTMRL unless it is preceded by a *DEVICE command.

Syntax

The format of the *DEVICE command is:

*DEVICE n1,n2

where n1 specifies characters per line, and n2 specifies lines per page.

For example, this line changes the value used for OUTMRL to 132 and OUTLPP to 55:

*DEVICE 132,55

You do not need to be logged in to issue this command.

z/OS JCL using BATCH2

This example shows sample JCL for a job that uses the BATCH2 facility running under z/OS.

// JOB //RUN EXEC PGM=BATCH2, // PARM='TESTM204,OMC=64,URCTYPE=B' //STEPLIB DD DSN=LOCAL.M204.LOAD,DISP=SHR //CCAOUT DD SYSOUT=C //CCAIN DD * LOGIN user ID password OPEN file . . . CLOSE ALL LOGOUT //

Syntax

The format of the PARM option on the EXEC statement is:

PARM='[subsysname:channel][,[OMC={X''hh'' | ddd}] [,URCTYPE={N | O | B}]]'

Where:

• subsysname is the zOS subsystem that Batch2 will use to communicate with the XDM task in order to make an IFDIAL connection. If subsysname is not specified, in which case the : would also be removed, then the subsysname would be picked up from the cram IGCLM244 module that the BATCH2 program loads.
• channel is the Online region channel name. If channel is not specified, the name defaults to M204PROD.
• OMC is the keyword which specifies the Output Message Control parameter. You can specify the OMC value in either hh or ddd form. If you do not specify a value, OMC defaults to 0.
• hh is a hex value from 00 to FF.
• ddd is a decimal value from 0 to 255.
• URCTYPE is the keyword that specifies the type of return code.

Commas must represent defaulted parameters, if later ones are specified.

PARM option examples

• In this example, the PARM= option specifies a channel name of TESTM204 and a hex value of 'F0' (the default) for the OMC parameter.

  // PARM='TESTM204,OMC=X''F0'''

• In this example, the PARM= option setting allows the channel name to default (to M204PROD). The decimal value of 4 for the OMC parameter causes class 1 (information) messages to be discarded.

  // PARM=',OMC=4'

z/VSE JCL using BATCH2

The following example-syntax shows JCL for a job that uses the BATCH2 utility running under z/VSE.

// JOB BATCH2 // DLBL M204LIB,'M204.PROD.LIBRARY' // EXTENT ,SYSnnn, balance of extent information // LIBDEF PHASE.SEARCH=M204LIB.V4R2 // DLBL CCAOUT,'M204.BATCH2.CCAOUT' // EXTENT SYSnnn, balance of extent information // UPSI bbbbbbbb // OPTION SYSPARM='channel' // EXEC BATCH2,SIZE=AUTO, PARM='channel,urctype' LOGIN user ID password OPEN file . . . CLOSE ALL LOGOUT /* /&

Where:

• bbbbbbbb in the UPSI statement in the preceding example is the Output Message Control (OMC) parameter in bits. If you do not specify a value, OMC defaults to all zeroes. In z/VSE, you can specify the OMC parameter as a combination of the option bits shown in z/VSE JCL using BATCH2:

  z/VSE OMC parameter options

  Setting	Description
  10000000	Discard class E messages (error messages)
  01000000	Ignore new page indicator (page eject)
  00100000	If the user is restarted, terminate this job
  00010000	Discard nondisplay input prompt messages
  00001000	Discard $READ prompt messages
  00000100	Discard class I messages (informational messages)

• channel in the OPTION SYSPARM statement in the preceding example is the Online partition channel name. If channel is not specified, the name defaults to M204PROD. See Specifying runtime parameters for a description of channel name.
• urctype specifies the type of return code, N, O, or B, to return the job step. See Specifying runtime parameters for return code values and meaning.

Example

// UPSE 00000000 // EXEC BATCH2,SIZE=AUTO,PARM='CRIOCHNL,B'

CMS job using BATCH2

This example shows sample commands for a job that uses the BATCH2 utility running under CMS.

&TRACE ERR FILEDEF CCAIN DISK BATCH2 CCAIN A FILEDEF CCAOUT DISK BATCH2 CCAOUT A M204BAT2 TESTM204 64 X'0' 'B'

Syntax

The command to execute the BATCH2 module shown in the example above is:

M204BAT2 [channel][X'hh' | ddd]['N' | 'O' | 'B']

Where:

• channel is the Online region line mode channel name set by the VMIOCHNL CCAIN parameter. If channel is not specified, the name defaults to M204VMIO. See Specifying runtime parameters for a description of channel name.
• hh is a hex value from 00 to FF and ddd is a decimal value from 0 to 255. You can specify the OMC value in either hexadecimal (hh) or decimal (ddd) form. For a description of valid values, see Specifying runtime parameters. If no value is specified, the OMC parameter defaults to 0.
• 'N', 'O', or 'B' specifies the return value of the URCTYPE parameter. See Specifying runtime parameters for return code values and meanings.

M204BAT2 statement examples

• In this example, the M204BAT2 statement specifies a channel name of TESTM204 and a hex value of 0 (the default) for the OMC parameter. Invoke M204BAT2 with the URCTYPE parameter in quotes:

  M204BAT2 TESTM204 X'0' 'B'

• In this example, the M204BAT2 statement allows the channel name to default (M204VMIO). The decimal value of 4 for the OMC parameter causes class 1 (information) messages to be discarded.

  M204BAT2 4

Using M204IFAM EXEC

During initialization, the BATCH2 utility invokes a procedure called M204IFAM EXEC to obtain the name of the virtual machine running the Model 204 ONLINE and to obtain the needed IUCV communication method.

Note: The M204IFAM EXEC must be available on the CMS machine that is running the BATCH2 utility.

An example of an M204IFAM EXEC is:

Syntax

&STACK LIFO userid IUCV

Where:

• userid is the name of the virtual machine that is running the Model 204 Online.
• IUCV indicates the IUCV communication method.

REXX EXEC for BATCH2

This example shows an EXEC that runs the BATCH2 utility. The EXEC dynamically creates an M204IFAM EXEC file:

/* REXX example of BATCH2 EXEC */ arg m204 ccain channel option if arg() = 0 then signal noentry if m204 = '?' then signal noentry continue: 'erase m204ifam exec a' 'erase batch2 ccaout a' 'EXECIO 1 DISKW M204IFAM EXEC A (FINIS ST &STACK LIFO' m204 'IUCV' 'filedef ccain disk' ccain 'ccain a' 'filedef ccaout disk' ccain 'ccaout a' 'M204BAT2' channel option eexit: exit rc noentry: say 'To use BATCH2 EXEC enter the following arguments:' say 'M204 service machine, BATCH2 ccain, channel and BATCH2 options' rc=4 signal eexit

BATCH2 completion codes

Upon termination, the BATCH2 facility returns a completion code. BATCH2 completion codes lists possible values:

BATCH2 completion codes

Setting	Description
0	Successful completion
300	Abnormal termination. Refer to CCAOUT for an error message. If a completion code of 300 is returned, an error message appears in the CCAOUT data stream. Some possible errors are: Invalid channel name parameter value. Invalid OMC parameter value. CCAIN data stream could not be opened.
600	The CCAOUT data stream could not be opened.

Thread signaling and synchronization facilities

In some applications, User Language programmers need to coordinate processing of two or more threads. For example, one thread may perform process-to-process communication, and then signal the completion of the process to a user represented by a SNA Communications Server thread. At that moment, the user may be working or waiting for the signal.

User Language has signaling and synchronization capabilities. A thread can:

• Send a signal that an event associated with the signal is finished
• Wait for the signal to arrive and examine the contents of a signal

Implementing thread signaling and synchronization in User Language

The signal is implemented using an Event Control Block (ECB), a permanent data structure in memory that indicates the event state and user supplied data associated with the event. The ECB is shared by all threads participating in the synchronization process.

• To send a signal to a thread, a SOUL application uses the $Post function, which marks the event as posted (or completed) and causes the waiting thread to wake up and resume processing. Furthermore, you can supply a numeric post code that is stored in the ECB, which may be examined by the waiting thread or threads.
• To wait for a signal, a SOUL application uses the $Wait function that puts a thread in a wait state until the event is posted by another thread and the signal arrives.

ECB-related functions

Using the $Post and $Wait functions, you can synchronize the execution of two threads. A SOUL application may associate a string of text with an ECB using the $EcbDSet function; the text may be read by other threads using $EcbDGet function.

The following $functions, are available for implementing signaling and synchronization between threads:

$Functions for signaling and synchronization

$Function	Purpose
$EcbDGet	Retrieve string data associated with an ECB.
$EcbDSet	Associate a string of data with an ECB.
$EcbTest	Test an ECB to see whether it is posted or not.
$Post	Indicate that an event has occurred. The thread waiting on an ECB can resume processing.
$UnPost	Indicate that an event did not occur or recur.
$Wait	Suspend a user until an event happens and the ECB is posted.

You can also use these functions to implement a third-party software backup plan for Model 204; see Programming a third-party backup.

Assigning and using an ECB number

The ECBs used to synchronize threads are referenced by number in the ECB-related functions. SOUL programmers should carefully choose the ECB numbers for use by threads and applications.

Programming thread synchronization in User Language

Programming thread synchronization in User Language using the ECB-related functions requires a clear understanding of how threads interact with each other. You must avoid situations where deadlocks are possible; for example, when Thread A waits on the signal from Thread B, which is already waiting on a signal from Thread A. In this situation, both threads are unable to run and will wait indefinitely until canceled with a BUMP command.

You must take into consideration that once posted, the ECB remains posted until explicitly unposted using the $UnPost function. The $Wait function does not change the ECB contents after completion, so the next invocation of the $Wait function with the unchanged ECB has exactly the same effect as the first one. Use the $UnPost function after all the threads waiting on the event have had a chance to run and check the ECB.

Posting and unposting ECBs

Posting an ECB does not mean that all threads waiting on that ECB can run immediately. Those waiting threads are now eligible to run and will be dispatched by the Model 204 scheduler based on priority and available resources.

If an ECB is posted and then immediately unposted, any threads that have not yet run and are still waiting on that ECB will never see the post and will continue to wait.

Only an unposted ECB may be posted. Attempting to post an already posted ECB produces a non zero return code; the content of the ECB is not changed.

A string may be associated with an ECB using the $EcbDSet or $Post functions. However, in most cases you should use the $Post function to associate a string with an ECB. The $Post function stores a string only if the referenced ECB is unposted; the $EcbDSet function stores a string regardless of the state of the ECB.

Thread synchronization programming details

The number of ECBs available to an Online is determined by the NECBS parameter set in CCAIN. The parameter cannot be reset.

ECBs are referenced by a number from 1 to NECBS and are available to any User Language application running on any thread. Therefore, care must be taken when assigning an ECB number to a processes or an application to avoid conflicts. A thread or an application cannot reserve an ECB, because it universal in scope.

You may use a %variable to program an ECB number in all the ECB-related $functions.

If the $EcbDSet function associates a string with an ECB more than once, the $EcbDGet function can retrieve only the most recent string.

Pay special attention to initialization of the synchronization process, since some applications may be sensitive to the order in which threads are initialized. When Model 204 is initialized, all ECBs are reset to zero, indicating that no events have yet happened. A thread restart has no effect on any ECBs. Therefore, Thread A waiting on a particular ECB will remain waiting even if Thread B, which intended to post that ECB, is restarted prior to the evaluation of the $POST call.

Examples of programming thread synchronization

To better understand how User Language synchronization is implemented, lets look at the following example. Thread A (server) performs a service for many client threads. To request a service, a client thread B posts ECB 5, sets a post code indicating the required service, and passes the ECB number. It waits for the service completion, which will be a string associated with ECB 5.

The client thread B also checks whether the post operation was successful. Another client thread C may have already posted ECB 5. In that case, the client thread B waits on ECB 3, which is posted when server thread A finishes with the current request. No provisions for restart are made. If thread A is bumped or fails before it posts ECB 12, client thread B is left in a permanent wait state. A BUMP command or a procedure, which posts thread B with a post code indicating a restart, may be required.

Server thread A

BEGIN REPEAT FOREVER %X = $POST(3,1) %X = $WAIT(5) %CLIENT.ECB = $ECBDGET(5) %POSTCODE = $STATUSD %X = $UNPOST(5) %X = $UNPOST(3) IF %POSTCODE = 1 THEN PERFORM TYPE 1 SERVICE ELSEIF %POSTCODE = 2 THEN PERFORM TYPE 2 SERVICE ELSEIF %POSTCODE = 10 THEN /? REQUEST TO BRING DOWN THE SERVER THREAD ?/ %X = $POST(%CLIENT.ECB,0) /? INDICATE TO CLIENT THE REQUEST COMPLETED ?/ JUMP TO EXIT END IF IF SERVICE SUCCESSFUL THEN %X = $POST(%CLIENT.ECB,0) /? INDICATE TO CLIENT THE REQUEST ?/ /? COMPLETED SUCCESSFULLY ?/ ELSE %X = $POST(%CLIENT.ECB,100) /? INDICATE AN ERROR RETURN ?/ END IF END REPEAT EXIT: END

Client thread B

BEGIN %MYECB = 12 %ACTION = 1 START: %X = $POST(5,%ACTION,%MYECB) /? POST SERVER THREAD AND PASS REQUEST TYPE ?/ /? AND ECB NUMBER  ?/ IF %X = 14 THEN /? IF ECB ALREADY POSTED WAIT TILL SERVER ?/ /? IS FREE  ?/ %X = $WAIT(3) JUMP TO START END IF %X = $WAIT(%MYECB) %POSTCODE=$STATUSD %X = $UNPOST(%MYECB) ========* CHECK %POSTCODE AND CONTINUE PROCESSING END

Each client thread should use a different ECB number for %MYECB.

Note: Server thread A code first copies the post code and data into %variables, then it unposts ECB 5. As soon as ECB 5 is unposted, a client thread may post it again and change the post code and associated string.

TCP/IP Sockets Interface for Model 204

The TCP/IP Sockets Interface for Model 204 gives you the ease and flexibility of making Model 204 a server or a client simply by writing a User Language application using calls that are described in this section.

The TCP/IP Socket Interface for Model 204 is designed to follow as closely as possible the Berkeley Sockets interface, as implemented and documented by IBM. Except for the REGISTER call, all the TCP/IP Sockets Interface for Model 204 calls result in an IBM call of almost the same name.

The IBM programming interface comes with TCP/IP on your operating system. You can consult IBM documentation for more details.

Linking FUNU for ASCII to EBCDIC conversion

Because it is very common to perform ASCII to EBCDIC conversion and back with a TCP/IP interface, Rocket Software recommends that you link the FUNU module during your Model 204 installation process or relink it later when you decide to use the TCP/IP Sockets Interface for Model 204. This ensures access to the $ASCII and $EBCDIC functions, which are used for EBCDIC and ASCII conversion to send and receive messages.

• For z/VSE, link the FUNU.A member
• For z/VM, link the FUNU module
• For z/OS, edit the SOCKETS parameter in INSPARMS to SOCKETS=Y and provide a decryption key during the installation process.

Understanding sockets

Sockets is a method for communication between a client program and a server program in a network. A socket is defined as the endpoint in a connection. Sockets are created and used with a set of programming requests or function calls: for TCP/IP Sockets Interface for Model 204 the $SOCKET and $SOCKETX functions.

Sockets can also be used for communication between processes within the same computer.

Understanding sockets illustrates a typical sequence of socket requests in which a server handles data from a single client, and the client then ends the connection.

Common sequence of calls

Client calls		Server calls
Specify local--> TCP/IP address	INIT	INIT
	SOCKET	SOCKET BIND LISTEN	Get a socket to <-- receive connections; specify port
Specify remote--> address and port	CONNECT-->	SELECT ACCEPT
		SETSOCKOPT
Data traffic	WRITE-->	SELECT READ
	SELECT READ	<--WRITE
	SHUTDOWN CLOSE-->
	TERM	TERM

Using the TCP/IP Sockets Interface for Model 204

You can open and use Horizon links at the same time you are using the TCP/IP Sockets Interface for Model 204. However, you cannot use a Horizon verb such as SEND in the interface, nor can you use a call such as SELECT on a Horizon link.

To allow TCP/IP communications in your Online, the TCPNAME= in CCAIN should point to the z/OS TCP/IP module or the z/VM virtual machine for your operating system. This parameter will default, if not specified. See the Model 204 Parameter and Command Reference for details.

TCP/IP for z/VSE

The introduction of TCP/IP to z/VSE Model 204 means that z/VSE sites can access TCP/IP applications. Furthermore, to improve performance, you can write new applications or rewrite older applications to take advantage of TCP/IP. Using TCP/IP is significantly faster than using SNA, LU62, or APPC network service.

In z/VSE the system programmer can start TCP/IP stacks in one or more z/VSE partitions, and each TCP/IP stack has its own system ID.

Using the TCPNAME parameter for z/VSE

When the Model 204 Online starts, it needs to know which of the TCP/IP stacks to talk to. The stack name is passed using the TCPNAME parameter. The format is:

TCPNAME=00, TCPNAME=01, ...TCPNAME=nn

This means the system ID must be a 2-character numeric ID, and it must be coded. The default value for TCPNAME for the z/VSE operating system is 00, and may be coded if the system ID is other than 00.

This value is used when the first TCP/IP link is opened, and if there is an error setting the ID the following error message is displayed:

M204.2710: ERROR x SETTING TCP/IP SYSID nn

where

• x is the return code from the TCP interface
• nn is the value passed in TCPNAME

Using TCP/IP-related commands

Horizon on TCP/IP, the TCP/IP Sockets Interface for Model 204, and SQL/RCL are available to z/VSE sites. The syntax and usage for the following Model 204 commands that support Horizon for TCP/IP communication are described in the linked individual command descriptions:

• DEFINE LINK command: Horizon for TCP/IP

  In your DEFINE LINK commands when you set PROTOCOL=IP, you must set TRANSPORT=TCPVSE. TCP/IP software for z/VSE sites is available through IBM. Contact your IBM representative for details.

• DEFINE PROCESS command: Horizon for TCP/IP and VTAM
• DEFINE PROCESSGROUP command: Horizon for TCP/IP

$SOCKET function

The calls possible for the $SOCKET function are listed in this section with a description of purpose, syntax, and arguments. Keep in mind that the arguments for the calls are positional, so if you do not enter a value for a particular argument, you should enter a comma as a position marker.

On z/OS systems, the $SOCKET function supports IPv6 network addresses. You can increase the address parameter on the INIT, CONNECT, and ACCEPT calls from 15 to 45 bytes if you are using IPv6 addresses. Specify IPv4 addresses in the dotted decimal format. IPv6 addresses are in the colon-separated format.

Syntax

The following is syntax for the $SOCKET function

%returncode=$SOCKET('socket-call',argument1, argument2,...)

Where:

• socket-call is one of the calls described in this section.
• argument1, argument2,...are specified in the definition of each call.

Example

The following $SOCKET function illustrates a valid ACCEPT call:

%rc=$socket('ACCEPT',%lsocket,'%rport',%raddr)

ACCEPT call

The ACCEPT call responds to a connection request from a client after a SELECT call has detected input on the listening socket. This call is issued by the server. The address and port variables are updated, and the call returns the accepted socket number. The returned port variable is not needed; it is not the port number used by the client.

Syntax

('ACCEPT', passive-socket-number, 'port-variable-name', address-output[,interface])

Where:

• passive-socket-number specifies by integer the listening socket. It is usually the first socket obtained by a server.
• port-variable-name specifies a numeric fixed variable, which holds an output value as an integer. Enclose this argument in single quotation marks.
• address-output specifies the dotted decimal address of the client making the connection request. address-output is a 15-byte string argument in the format nnn.nnn.nnn.nnn.

  On z/OS systems, address-output can be an IPv6 address of 45 bytes. The IPv6 address format is up to 8 halfwords separated by colons: nn:nn:nn:nn:nn:nn:nn:nn, which can also be written as nn:nn:nn:nn::nn, with the double colon indicating missing halfwords of binary zeroes.

• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Example

%rc=$socket('ACCEPT',%lsocket,'%rport',%raddr,%pathname)

BIND call

The BIND call provides the socket number and port number.

Syntax

('BIND',socket,port[,interface])

Where:

• socket specifies, as an integer, the socket number.
• port specifies the server port number as an integer. port corresponds to the SERVPORT argument in a Model 204 DEFINE LINK command.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Usage

The BIND call is used only by the server to prepare a socket obtained by the server for connection requests from clients.

A standard TCP error code of 48 (decimal) means that the socket is still in use. TCP/IP holds on to a socket for a minute or so after it was last closed, so this error can occur even thought no application apparently has it open.

Example

%rc=$socket('BIND', %lsocket, %port)

CANCEL call

The CANCEL call ends an asynchronous request.

Syntax

('CANCEL', socket, 'callname'[,interface])

Where:

• socket specifies the socket used by the call being cancelled, or -1 to match any call.
• callname specifies the call being cancelled, as a literal enclosed in single quotation marks. This is usually 'SELECT' to cancel a SELECT call, 'READ' to cancel a READ call, or '*' to match any call.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Usage notes

Use CANCEL to cancel a call that has been issued by another thread. The thread doing the CANCEL must have registered with the same interface. If user USER1, for example, has issued a READ on socket 5, and no data is forthcoming on that socket, the READ will hang indefinitely, so USER2 can register with the interface and issue one of the following commands to cancel the hung call:

('CANCEL',5,'READ') ('CANCEL',-1,'READ') ('CANCEL',-1,'*') ('CANCEL',5,'*')

CLOSE call

The CLOSE call stops the use of a socket.

Syntax

('CLOSE', socket[,interface])

Where:

• socket, an integer, specifies the socket number.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Example

%rc=$Socket('CLOSE',%socket,%pathname)

Usage notes

Using the optional CLOSE call, a programmer can follow the standard practice of closing within the program anything that the program opened, rather than relying on the operating system to properly close down a socket when the interface is terminated.

CONNECT call

The CONNECT call is used by a client thread to associate with a server.

Syntax

('CONNECT', socket, port, address[,INTERFACE])

Where:

• socket, an integer, specifies the socket number returned from the SOCKET call.
• port specifies the server port number as an integer. This port corresponds to the SERVPORT argument in a Model 204 DEFINE LINK command.
• address specifies a dotted decimal internet address as a 15-byte string in the format nnn.nnn.nnn.nnn.

  On z/OS systems, address output can be an IPv6 address of 45 bytes. The IPv6 address format is up to 8 halfwords separated by colons: nn:nn:nn:nn:nn:nn:nn:nn, which can also be written as nn:nn:nn:nn::nn, with the double colon indicating missing halfwords of binary zeroes.

• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Example

%rc=$Socket('CONNECT',%socket,%remport,%remaddr,%pathname)

INIT call

The INIT call calls TCP/IP to create the interface in the local environment.

Syntax

('INIT', interface, address,port, max-connections, max-requests)

Where:

• interface specifies an up-to 8-character name for the local end of the TCP/IP connection.
• address specifies a dotted decimal internet address as a 15-byte string in the format nnn.nnn.nnn.nnn.

  On z/OS systems, address output can be an IPv6 address of 45 bytes. The IPv6 address format is up to 8 halfwords separated by colons: nn:nn:nn:nn:nn:nn:nn:nn, which can also be written as nn:nn:nn:nn::nn, with the double colon indicating missing halfwords of binary zeroes.

• port specifies the local port number as an integer. This port corresponds to the SERVPORT argument in a Model 204 DEFINE LINK command.
• max-connections specifies the maximum number of connections, as in a Model 204 DEFINE LINK command. The value of max-connections is an integer from 1 to 31. Technical Support recommends that you specify at least 3.
• max-requests specifies the maximum number of outstanding requests. Technical Support recommends that you set the value of max-requests to at least four up to a maximum of 31.

Usage notes

The number of sockets created for the interface is returned.

The INIT call corresponds to a Model 204 DEFINE and OPEN LINK command. INIT must be the first call.

Several users could use the same interface. Only the first user must make the INIT and the REGISTER calls; subsequent users need make only the REGISTER call.

Example

%rc = $socket('INIT',%pathname,%addr,%port,6,7)

LISTEN call

The LISTEN call indicates that a socket is to accept incoming connection requests.

Syntax

('LISTEN', socket, backlog[,INTERFACE])

Where:

• socket, an integer, specifies the socket number that was returned from the SOCKET call.
• backlog, an integer, specifies the maximum number of simultaneous connection requests. Make backlog not less than the expected maximum number of simultaneous connection requests from a client.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Usage note

The LISTEN call is used by the server to prepare a socket obtained by the server for connection requests from clients.

Example

%rc=$socket('LISTEN',%lsocket,10,%pathname)

READ call

The READ call receives data.

The return code is the amount of data transferred to the buffer. If this is zero, the socket has been closed by the session partner.

If there is no data available and the socket is in blocking mode, the socket waits indefinitely for data. If you receive less data than is available, a second READ call will receive the remaining data.

Syntax

('READ', socket,'buffer', maximum-length[, interface])

Where:

• socket, an integer, specifies the socket number.
• buffer specifies the output location for data on the read operation. The value is represented by a string percent variable or an image name. Enclose the value in quotation marks: for example, '%buff' and 'MYIMAGE' respectively.

  If the READ call expects less data than is available, subsequent READ calls accept the remaining data.

  If the READ call expects more data than is available, the READ variable is padded on the right with spaces.

• maximum-length specifies the maximum length of data as an integer.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Example

%rc=$socket('READ',%socket,'%fred',12,%pathname)

REGISTER call

The REGISTER call connects the calling user to the interface, but makes no extra call to TCP/IP.

Syntax

('REGISTER', interface)

Where interface specifies an up-to-8-character name for the TCP/IP environment, which identifies the host port.

Example

%rc=$socket('REGISTER',%pathname)

Usage notes

You must include a REGISTER call immediately after the INIT call when:

• You want to continue using the interface after the thread closes its last socket.
• A thread other than the one that created the interface wants to use the interface.

SELECT call

The SELECT call waits for an event on more than one socket. The thread waits until an event or timeout occurs. The call returns the number of sockets affected, or zero, if the call has timed out. The file descriptors (FDS) variables are updated to show which sockets have had events.

Syntax

('SELECT', highest-socket, 'readFDS-variable-name', 'writeFDS-variable-name', 'exceptFDS-variable-name', timeout[, interface])

Where:

• highest-socket specifies the highest socket number in the FDS arguments, plus one, as an integer. For example, if the FDS arguments select sockets 3, 2, and 0, specify 4, which is the highest socket plus 1.
• readFDS-variable-name specifies to TCP/IP which sockets to wait on for input. Enclose this integer argument in quotation marks, because this is a fixed 4-byte full word variable used to hold a value output.

  The integer is a bitmap that identifies a group of sockets whose activity you want to track. The rightmost bit represents socket 0 and the most left bit represents socket 31. If you set the bit ON, that means: tell me if anything happens to this socket.

• writeFDS-variable-name specifies to TCP/IP whether the socket(s) are ready for writing data. Enclose this integer argument in quotation marks, because this is a fixed 4-byte full word variable used to hold a value output.

  The integer is a bitmap that identifies a group of sockets whose activity you want to track. The rightmost bit represents socket 0 and the most left bit represents socket 31. If you set the bit ON, that means: tell me if anything happens to this socket.

• exceptFDS-variable-name specifies to TCP/IP to check for exceptions on the socket(s). Enclose this integer argument in quotation marks, because this is a fixed 4-byte full word variable used to hold a value output.

  The integer is a bitmap that identifies a group of sockets whose activity you want to track. The rightmost bit represents socket 0 and the most left bit represents socket 31. If you set the bit ON, that means: tell me if anything happens to this socket.

• timeout specifies a value in seconds, or a negative integer for no timeout.

  Value in seconds	Meaning
  -1	No time-out: waits for an event.
  0	Returns immediately, if no socket is selected.
  Greater than 0	The length of the time-out in seconds.

• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Usage

The SELECT call is used by the server to wait for connection requests from the client, and by both client and server to wait for data.

When a SELECT call on a listening socket returns showing that there is a connection request, the next server call must be an ACCEPT.

A SELECT call on a data socket that returns showing an event on a socket may have zero-length data, showing that the partner has shut down the socket.

Example

%rcC=$socket('SELECT', %highsock, '%readFds', '%writeFds', '%exFds', 0, %pathname)

Usage

Using the SELECT call you can have TCP tell you when there is activity on a group of sockets. You tell TCP which sockets interest you by creating a bitmap. For example, If you set ReadFDS to X'00000030', you are telling TCP to tell you when there is any input on sockets 4 or 5. The bitmap is set as follows: '00110000', and the rightmost bit stands for socket 0.

The setting of a bitmap works the same for the ExceptFDS and WriteFDS arguments, but these bitmaps tell TCP to check whether there are exceptions on the socket, or that the socket is ready for writing data, respectively.

The SELECT call should be used by both client and server before a READ call.

The SELECT call waits until there is activity on chosen sockets. The file descriptors (FDS) bitmap specifies the sockets that TCP/IP is to wait for. Each FDS variable is a full-word, so you can specify sockets 0 to 31 inclusive. The rightmost bit of each full-word represents socket 0.

In the Example procedure - Server, there is a sample subroutine to add a given socket number to a bitmap, and to delete a socket from a bitmap. If you are waiting on more than one socket (which would be unlikely for the functions interface), you would need to check on return from the SELECT call which sockets caused the event.

In the Example procedure - Server, the WriteFDS argument is set to zero, as the ready-to-write event is not of interest. If there is an exception event, as shown by the output exception FDS being non-zero, this is a serious communications error, and you must close the interface.

SHUTDOWN call

The optional SHUTDOWN call closes traffic in one direction — receive or send — or both directions.

Syntax

('SHUTDOWN', socket, shutdown-value[, interface])

Where:

• socket, an integer, specifies the socket number.
• shutdown-value specifies the type of traffic to make inactive, represented as an integer.

  Value	Meaning
  0	Receive
  1	Send
  2	Both send and receive

• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Example

%rc=$socket('SHUTDOWN',%socket,2,%pathname)

Usage notes

If you want to deactivate traffic in both directions you can issue a CLOSE call in place of a SHUTDOWN call.

SOCKET call

The SOCKET call allocates a socket.

Syntax

('SOCKET', domain, type, protocol[, interface])

Where:

• domain specifies the integer 2, which is required. On z/OS systems, specify 19 if you are using IPv6 (AF_INET6) addressing.
• type specifies the integer 1, which is required.
• protocol specifies the integer 0, which is required.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Usage notes

The new socket number is returned. The SOCKET call is used by both the server and client.

Example

%rc=$socket('SOCKET',2,1,0,%pathname)

TERM call

The TERM call attempts to close any open sockets, and deletes the interface; it corresponds to a Model 204 CLOSE LINK command.

Syntax

('TERM', interface)

Where interface specifies the 8-character name that was used in the INIT call.

Example

%rc=$socket('TERM',%pathname)

Usage notes

A TERM call does an implicit CLOSE call for all open sockets, accompanied by the following message for each open socket:

M204.2288: TCP/IP CLEANUP IS CLOSING SOCKET socket-number FOR USER userid

WRITE call

The WRITE call sends data.

Syntax

('WRITE', socket, 'buffer', length[, interface])

Where:

• socket, an integer, specifies the socket number.
• buffer specifies the data location, which can be a string percent variable or an image name. Enclose the value in quotation marks: for example, '%buff' and 'MYIMAGE' respectively.
• length specifies the length of data to be sent, in bytes. If this is less than the data in the variable or image, the data is truncated. If data is truncated and buffer is an image name, $STATUSD is set to -989, but this is a warning, and the data is transmitted correctly.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Usage

The call returns the number of bytes written, which can be zero.

Example

%rc = $socket('WRITE', %socket, '%fred', 7, %pathname)

$SOCKETX function

Syntax

%returncode=$SocketX('socket-call', socket, option-name)

Where:

• socket-call is the GETHOST, GETSOCKOPT, SETSOCKOPT, or GETINFO call. GETINFO is supported on z/OS systems only.
• socket is an integer that identifies the socket from an earlier ACCEPT or LISTEN call.
• option-name is an integer that identifies the option.

Option-name integer	IBM option
4	SO_REUSEADDR
8	SO_KEEPALIVE
32	SO_BROADCAST
256	SO_OOBINLINE
4097	SO_SNDBUF
4103	SO_ERROR
4104	SO_TYPE

Example

The following $SOCKETX function illustrates a valid GETSOCKOPT call:

%rc=$socketx('GETSOCKOPT',%socket,4097)

Usage notes

For an expanded discussion of the options listed in the previous table, consult IBM documentation.

GETHOST call

The GETHOST call translates a host name to a network address (or addresses in the format of nnn.nnn.nnn.nnn).

Syntax

('GETHOST', hostname, 'address-array')

Where:

• hostname specifies a 25-byte string to be translated to a dotted decimal address in the format nnn.nnn.nnn.nnn.
• address-array, which is enclosed in single-quotation marks, specifies an image containing an array of 15-byte strings for output. The GETHOST call will populate the address array with the retrieved dotted-decimal network address(es).

Usage notes

• It is useful for a client to translate a server to a dotted-decimal address before issuing the CONNECT call.
• The GETHOST call, which corresponds to the IBM GETHOSTBYNAME call, can be issued even if no interface has been created.
• To translate the domain name on z/OS systems, you need to supply a DD card for the SYSTCPD data set, as in this example:

  //SYSTCPD DD DSN=TCPIP.PROFILE(TCPDATA), DISP=SHR

• If you want to make use of IPv6 addressing, use GETINFO instead of GETHOST.
• The GETHOST call is not supported on z/VM systems.

GETSOCKOPT call

The GETSOCKOPT call retrieves the current setting of a socket option. The return code is the value of the option. For Boolean values, this is 1 for YES or ON, and 0 for NO or OFF.

Syntax

('GETSOCKOPT', socket, option-name[, interface])

Where:

• socket is an integer that identifies the socket.
• option-name is an integer that identifies the option.

  Integer	Option
  4	SO_REUSEADDR
  8	SO_KEEPALIVE
  32	SO_BROADCAST
  256	SO_OOBINLINE
  4097	SO_SNDBUF
  4103	SO_ERROR
  4104	SO_TYPE

• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Example

%rc=$socketx('GETSOCKOPT',%socket,4097,%pathname)

SETSOCKOPT call

The SETSOCKOPT call resets a socket option.

Syntax

('SETSOCKOPT', socket, option-name, option-value[, interface])

Where:

• socket is an integer that identifies the socket.
• option-name is an integer that identifies the option.

  Integer	Option
  4	SO_REUSEADDR
  8	SO_KEEPALIVE
  32	SO_BROADCAST
  256	SO_OOBINLINE
  4097	SO_SNDBUF
  4103	SO_ERROR
  4104	SO_TYPE

• option-value specifies an integer. Consult the IBM documentation for the option values.
• interface specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.

Example

The following $SOCKETX function illustrates a SOCKOPT call to set on the KEEPALIVE option:

%rc=$socketx('SETSOCKOPT',8,1,%pathname)

GETINFO call

(Available on z/OS systems only.) The GETINFO call invokes the GETADDRINFO service to translate a network symbolic address to an IPv4 or IPv6 address.

Syntax

$SOCKETX('GETINFO', name, output-structure, flag-fullword, family)

Where the flag and family fullwords, described in the Application Programming Interface Reference manual, have the following values:

* FLAG WORD= (FULLWORD) FLAG WORD FOR GETADDRINFO CALL * VALID VALUES (ADDITIVE) ARE * AI_PASSIVE : 1 - get value suitable for listening * AI_CANONNAMEOK : 2 * AI_NUMERICHOST : 4 * AI_NUMERICSERV : 8 * AI_V4MAPPED : 16 - include V4-mapped IPV6 addresses * AI_ALL : 32 - get all possible addresses * AI_ADDRCONFIG : 64 family fullword: fixed value or literal * USED TO LIMIT THE ADDRESSES RETURNED * VALID VALUES ARE * AI_UNSPEC : 0 - get both IPV4 and IPV6 * AI_INET : 2 - get IPV4 only * AI_INET6 : 19 - get IPV6 only

The default for both the flags and family fullwords is zero.

The output structure, which can be either variable or image, is:

ADDRESS1 STRING LEN 45 first address FAMILY1 STRING LEN 1 4, 6, or space ADDRESS2 STRING LEN 45 second address FAMILY2 STRING LEN 1 4, 6, or space

With a return code zero result, it is possible that ADDRESS2 and FAMILY2 are both set to spaces if there is only one address returned that fits the supplied criteria.

The following sample procedure illustrates the GETINFO call:

BEGIN DECLARE %PATH1 STRING LEN 80 DECLARE %FAMILY FIXED DECLARE %FLAGS FIXED DECLARE %I FIXED %PATH1 = $READ('SYMBOLIC NAME?') %PATH1 = $UNBLANK(%PATH1) %FAMILY = $READ('FAMILY - 0 (ANY) 2 (IPV4) OR 19 (IPV6)') %FLAGS = $READ('FLAGS - 1 (PASSIVE) 16 (V4MAPPED) 32 (ALL)') IMAGE GHOUTPUT ARRAY OCCURS 2 ADDRESS IS STRING LEN 45 FAMILY IS STRING LEN 1 END ARRAY END IMAGE PREPARE IMAGE GHOUTPUT DECLARE %RC FIXED %RC = $SOCKETX('GETINFO',%PATH1,'GHOUTPUT',%FLAGS,%FAMILY) FOR %I FROM 1 TO 2 PRINT 'ADDRESS FROM GETINFO ' AND %GHOUTPUT:ADDRESS(%I) PRINT 'FAMILY FROM GETINFO ' AND %GHOUTPUT:FAMILY(%I) END FOR PRINT 'RC ' AND %RC END

which will give output like this:

$$SYMBOLIC NAME? MYHOST $$FAMILY - 0 (ANY) 2 (IPV4) OR 19 (IPV6) 0 $$FLAGS - 1 (PASSIVE) 16 (V4MAPPED) 32 (ALL) 48 ADDRESS FROM GETINFO 2001:23:20:55::206 FAMILY FROM GETINFO 6 ADDRESS FROM GETINFO ::FFFF:191.28.55.206 FAMILY FROM GETINFO 6 RC 0

Note: In the previous example, two addresses are returned, because the ALL flag (32) was included, and the second address returned is a v4-mapped IPv6 address.

Error codes, examples, and limitations

Error codes for calls

The error codes listed in Error codes for calls were written specifically for TCP/IP Sockets Interface for Model 204. Additional error codes you might encounter are described in IBM documentation for TCP/IP for z/OS: API Reference.

The following error codes are valid when the return code is -1, except for -991, which can occur after a successful READ call, where the return code is the number of bytes transferred to the variable.

Error codes returned by $STATUSD

Values	Meaning
-999	Invalid argument.
-998	Call attempted, other than the INIT call, when the user is not registered with a functions interface.
-997	Failure attempting to allocate storage.
-996	This is a failure writing data into an output variable or image.
-995	The link is an incorrect type (for INIT, REGISTER, and TERM calls)
-994	The socket has not been released. In the case of a CLOSE call, the socket is of the wrong type — possibly a Horizon socket.
-993	There has been a physical error on the interface.
-992	The pathname is unknown (for REGISTER and TERM calls only).
-991	On a READ call, the string is shorter than the length parameter. The data received is truncated.
-990	Socket not found.
-989	On a WRITE call this is a warning code that shows that the image being sent was truncated.
-988	Error on GETHOSTBYNAME call.
-987	Error deleting the temporary interface after GETHOST call.
-986	The CANCEL call found no matching call to cancel; no action was taken.
-985	The socket number obtained on a SOCKET or ACCEPT was above the limit of 31, so it has been closed. It may be that 32 sockets are already in use. Or, if many sockets are opened and closed quickly, perhaps not enough time — one minute — has elapsed to reuse a free socket. You can close an open socket, or you can wait to reuse a free socket.
-984	Universal Buffer not there.
-983	Universal Buffer length error.
-982	Universal Buffer allocation error.

Example procedure - Server

This code is included on the installation distribution medium. See the individual operating system installation page for its location. The following code is called SOCKSMPS, located as follows:

Operating system	Located
z/OS	JCLLIB data set
z/VM	193 C
z/VSE	Jrrr sublib where rrr is the release number

BEGIN * This is an example of the server side of the sockets * interface DECLARE %PATHNAME STRING LEN 8 DECLARE %SOCKET FIXED DECLARE %LSOCKET FIXED DECLARE %HIGHSOCK FIXED DECLARE %NEWSOCK FIXED DECLARE %TSOCKET FIXED DECLARE %PORT FIXED DECLARE %RPORT FIXED DECLARE %ADDR STRING LEN 15 DECLARE %RADDR STRING LEN 15 * NNN.NNN.NNN.NNN (dotted decimal internet address) is * 15 characters long (maximum) DECLARE %RC FIXED DECLARE %SOMAX FIXED DECLARE %READFDS FIXED DECLARE %EXFDS FIXED DECLARE %WRITEFDS FIXED DECLARE %FRED STRING LEN 12 DECLARE %FN STRING LEN 10 %PATHNAME = 'TCPS' * %PATHNAME is 8 characters - the link name * %LSOCKET is the listening socket, %SOCKET for data %PORT = 7633 %SOMAX = 8 %FRED = 'DATA OUT' %ADDR = '193.208.28.129' %RADDR = '193.208.28.129' %RC = 0 %READFDS = 0 %EXFDS = %READFDS %WRITEFDS = %READFDS * %HIGHSOCK is used in SELECT calls for the highest number * of sockets in an FDS %HIGHSOCK = 0 * In the following call, 6 is the maximum number of * connections and 7 is the maximum number of requests. %RC = $SOCKET('INIT',%PATHNAME,%ADDR,%PORT,6,7) %RC = $SOCKET('REGISTER',%PATHNAME) * 2,1,0 are the domain, type, and protocol %RC = $SOCKET('SOCKET',2,1,0) %LSOCKET = %RC %NEWSOCK = %LSOCKET * call ADDSOCK to add the new socket to the FDS and * update %HIGHSOCK CALL ADDSOCK %RC = $SOCKET('BIND',%LSOCKET,%PORT) %RC = $SOCKET('LISTEN',%LSOCKET,10) * Wait for a connection %RC = $SOCKET('SELECT',%HIGHSOCK, - '%READFDS','%WRITEFDS','%EXFDS',0) * -1 is error IF %RC < 0 THEN JUMP TO SELECT.ERROR END IF AUDIT 'AFTER SELECT READ FDS IS ' AND %READFDS * >1 shows that sockets have been selected IF %RC > 0 THEN * But is's bad news if it's an exception FDS IF %EXFDS > 0 THEN AUDIT 'EXCEPTION FDS NON-ZERO ' AND %EXFDS JUMP TO SELECT.ERROR ELSE JUMP TO SELECT.ACCEPT END IF END IF * If rc=0, there has been a time-out, which should not happen * if the timeout argument is -1. JUMP TO COMMON.END * SELECT.ACCEPT: * The listen has resulted in a connection request - accept it * Note that quotation marks enclose the port argument in the * call - we are passing the name of the variable, not its * value, because the port number will be placed in the * variable by the function. %RC = $SOCKET('ACCEPT',%LSOCKET,'%RPORT',%RADDR) IF %RC GT 0 THEN AUDIT 'REMOTE ADDRESS IS ' AND %RADDR AUDIT 'REMOTE PORT IS ' AND %RPORT AUDIT 'NEW SOCKET IS ' AND %RC %SOCKET = %RC ELSE JUMP TO COMMON.END END IF * %NEWSOCK = %LSOCKET CALL DELSOCK * Use DELSOCK to delete the listening socket from the FDS %NEWSOCK = %SOCKET * We now need to select on the data socket instead of the * listening socket (Socket 1) * Call ADDSOCK to add the new socket to the FDS and * update %HIGHSOCK CALL ADDSOCK * * 8 is SO_KEEPALIVE, which we set ON (0 is OFF, 1 is ON) %RC = $SOCKET('SETSOCKOPT',%SOCKET,8,1) * Wait for data SELECT2: %RC = $SOCKET('SELECT',%HIGHSOCK, - '%READFDS','%WRITEFDS','%EXFDS',0) * -1 is error IF %RC < 0 THEN JUMP TO SELECT.ERROR END IF AUDIT 'AFTER SELECT READ FDS IS ' AND %READFDS * >1 shows that sockets were selected IF %RC > 0 THEN * But it's bad news if it's an exception FDS IF %EXFDS > 0 THEN AUDIT 'EXCEPTION FDS NON-ZERO ' AND %EXFDS JUMP TO SELECT.ERROR ELSE JUMP TO SELECT.READ END IF END IF * rc=0 (time-out) JUMP TO COMMON.END * SELECT.READ: * Note that on the READ, the buffer variable name is enclosed * in quotation marks. %RC = $SOCKET('READ',%SOCKET,'%FRED',12) IF %RC < 0 THEN AUDIT 'READ ERROR' JUMP TO COMMON.END END IF IF %RC = 0 THEN * If number of bytes = 0, this is remote socket close JUMP TO COMMON.END END IF * Read again until we detect a close JUMP TO SELECT2 * %RC = $SOCKET('WRITE',%SOCKET,%FRED,7) JUMP TO COMMON.END SELECT.ERROR: AUDIT 'SELECT ERROR' COMMON.END: * Deactivate and close the data socket IF %SOCKET GE 0 THEN %RC = $SOCKET('SHUTDOWN',%SOCKET,2) %RC = $SOCKET('CLOSE',%SOCKET) END IF * Deactivate and close the listening socket IF %LSOCKET GE 0 THEN %RC = $SOCKET('SHUTDOWN',%LSOCKET,2) %RC = $SOCKET('CLOSE',%LSOCKET) END IF * %RC = $SOCKET('TERM',%PATHNAME) ADDSOCK: SUBROUTINE * Adds NEWSOCK to the FDS bitmap %READFDS = %READFDS + $RXPI(2, %NEWSOCK) %WRITEFDS = 0 %EXFDS = %READFDS %TSOCKET = %NEWSOCK + 1 IF %TSOCKET GT %HIGHSOCK THEN %HIGHSOCK = %TSOCKET END IF * END SUBROUTINE ADDSOCK * DELSOCK: SUBROUTINE * Deletes NEWSOCK from the FDS bitmap %READFDS = %READFDS - $RXPI(2, %NEWSOCK) %WRITEFDS = 0 %EXFDS = %READFDS %TSOCKET = %NEWSOCK + 1 IF %TSOCKET = %HIGHSOCK THEN %HIGHSOCK = %HIGHSOCK - 1 END IF END SUBROUTINE DELSOCK END

Example procedure - Client

This code is included on the installation distribution medium. See the individual operating system installation page for its location. The following code is called SOCKSMPC, located as follows:

Operating system	Located
z/OS	JCLLIB data set
z/VM	193 C
z/VSE	J610 sublib

BEGIN * This is an example of the client side of a sockets interface. DECLARE %PATHNAME STRING LEN 8 DECLARE %SOCKET FIXED DECLARE %PORT FIXED DECLARE %REMPORT FIXED DECLARE %FRED STRING LEN 12 DECLARE %ADDR STRING LEN 15 DECLARE %RC FIXED DECLARE %SOMAX FIXED DECLARE %FN STRING LEN 10 %PATHNAME = 'TCP9C' %FRED = 'HARRY' * Pathname is 8 chars - the link name %PORT = 7644 %REMPORT = 7633 %ADDR = '193.208.28.147' %REMADDR = '193.208.28.129' * %RC = $SOCKET('INIT',%PATHNAME,%ADDR,%PORT,6,7) %RC = $SOCKET('REGISTER',%PATHNAME) %RC = $SOCKET('SOCKET',2,1,0) %SOCKET = %RC %RC = $SOCKET('CONNECT',%SOCKET,%REMPORT,%REMADDR) * Note that on the WRITE call, the buffer variable name * is enclosed in quotation marks. %RC = $SOCKET('WRITE',%SOCKET,'%FRED',5) * 4097 is SO_SNDBUF %RC = $SOCKET('GETSOCKOPT',%SOCKET,4097) IF $STATUSD NE 0 THEN AUDIT 'ERR RETURN FROM GETSOCKOPT ' AND %RC AND $STATUSD ELSE AUDIT 'RETURN FROM GETSOCKOPT ' AND %RC AND $STATUSD %SOMAX = %RC AUDIT 'MAX OUTBUF IS ' AND %SOMAX END IF * 0 is receive, 1 is send, 2 is both %RC = $SOCKET('SHUTDOWN',%SOCKET,2) %RC = $SOCKET('CLOSE',%SOCKET) %RC = $SOCKET('TERM',%PATHNAME) END

Limitations to TCP/IP Sockets Interface for Model 204

True communications programming requires an event-driven architecture, where independent threads can respond to external events, such as messages from TCP/IP. SOUL is a procedural language and is limited for event-driven processing, although it is possible to do some sockets programming.

Horizon can respond to asynchronous events by means of pseudo subtasks (PSTs) that wait for external events to occur. It controls sessions between servers and clients by borrowing the concepts of session and conversation from SNA LU6.2. It separates the layer involving the calls from the higher layer that processes conversational requests, such as SEND and RECEIVE. It also imposes a state discipline on the conversation, so that in a certain state some requests are illegal. A conversation in RECEIVE state, for example, cannot simply issue a SEND; the SOUL statement would get a state error.

With the TCP/IP Socket Interface for Model 204, there is no concept of session or conversation, and there is no state discipline. A call may result in an error, but the error is either a syntax error or an error returned by TCP/IP. This means that the programmer is a responsible for tracking of the state of a connection.

The calls do not operate on interfaces that were not created using the calls themselves. This protects Horizon links from being manipulated incorrectly by rogue function calls.

There is a restriction that a user can operate on only one TCP/IP interface at a time using function calls. The user may, however, also be registered with one or more Horizon interfaces.

The SELECT call takes bitmaps as input. It is not convenient to manipulate bitmaps as strings in User Language, so the call expects a 4-byte full-word FDS, instead of a variable-length string. This means that the maximum socket that can be selected in a SELECT call is currently 31. The Example procedure - Server has subroutines for updating the bitmaps.