DEFINE PROCESS command: Transfer Control partner: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Automatically generated page update)
 
m (add ID for DATALEN)
 
(6 intermediate revisions by the same user not shown)
Line 4: Line 4:
<dd>User 0 or system manager
<dd>User 0 or system manager
<dt>Function
<dt>Function
<dd>Defines a Transfer Control process for reference by the User Language TRANSFER statement. The process definition indicates the partner (CICS program or SNA Communications Server application), the type of transfer, and the characteristics of the transfer.  
<dd>Defines a Transfer Control process for reference by the SOUL <var>[[Statement syntax#TRANSFER|TRANSFER]]</var> statement. The process definition indicates the partner (CICS program or SNA Communications Server application), the type of transfer, and the characteristics of the transfer.  
</dl>
</dl>
==Syntax==
==Syntax==
<p class="syntax">DEFINE PROCESS name [LIKE previosname] WITH
<p class="syntax">DEFINE PROCESS <span class="term">name</span> [LIKE <span class="term">previousname</span>] WITH
   SCOPE=SYSTEM
   SCOPE=SYSTEM
   DESTINATION=processgroupname  
   DESTINATION=<span class="term">processgroupname</span>
   PARTNER=partnername
   PARTNER=<span class="term">partnername</span>
   DATALEN=nnnnn  
   DATALEN=<span class="term">nnnnn</span>
   MODE={XCTL | PASS}  
   MODE={XCTL | PASS}  
   [TIMEOUT=nnnnn]
   [TIMEOUT=<span class="term">nnnnn</span>]
   UIDSOURCE={NONE | CURRENT |OPEN}
   UIDSOURCE={NONE | CURRENT |OPEN}
   ACCTSOURCE={NONE | CURRENT | OPEN}
   ACCTSOURCE={NONE | CURRENT | OPEN}
</p>
</p>
<p>Where </p>
<p>Where: </p>
<table>  
<table>  
<tr>
<tr>
<th>name</th>
<th>name</th>
<td> is the local <var class="product">Model&nbsp;204</var> name for the process being defined. The User Language TRANSFER statement refers to this process by the name specified. The length of the name must be 1 to 8 characters.</td>
<td>The local <var class="product">Model&nbsp;204</var> name for the process being defined. The SOUL <var>TRANSFER</var> statement refers to this process by the name specified. The length of the name must be 1 to 8 characters.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var>LIKE</var></th>
<th><var>LIKE</var></th>
<td> gives the current link the attributes of the link entity referred to by previousname.</td>
<td>Gives the current link the attributes of the link entity referred to by <var class="term">previousname</var>.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var>SCOPE=SYSTEM</var></th>
<th><var>SCOPE=SYSTEM</var></th>
<td> indicates that the definition is available to all users of the <var class="product">Model&nbsp;204</var> system for the entire run.</td>
<td>Indicates that the definition is available to all users of the <var class="product">Model&nbsp;204</var> system for the entire run.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var>DESTINATION</var></th>
<th><var>DESTINATION</var></th>
<td> associates the process with the processgroup, processgroupname, defined by the DEFINE PROCESSGROUP command.</td>
<td>Associates the process with the processgroup, processgroupname, defined by the DEFINE PROCESSGROUP command.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var>PARTNER</var></th>
<th><var>PARTNER</var></th>
<td> specifies the name of the partner (as known in the remote environment) that is the object of the User Language TRANSFER statement and to which control is passed. Acceptable values for partnername (as many as eight characters) depend on what MODE, PROTOCOL, and LOGIN options are defined on the DEFINE PROCESS, DEFINE LINK, and DEFINE PROCESSGROUP commands, respectively:
<td>The name of the partner (as known in the remote environment) that is the object of the User Language TRANSFER statement and to which control is passed. Acceptable values for partnername (as many as eight characters) depend on what MODE, PROTOCOL, and LOGIN options are defined on the DEFINE PROCESS, DEFINE LINK, and DEFINE PROCESSGROUP commands, respectively:
<ul>  
<ul>  
<li>
<li>When <var>MODE=XCTL</var> and PROTOCOL=TRANSFER, partnername must be the name of a CICS program. The CICS program is the partner process and the object of the TRANSFER statement.</li>
<p>When <var>MODE=XCTL</var> and PROTOCOL=TRANSFER, partnername must be the name of a CICS program. The CICS program is the partner process and the object of the TRANSFER statement.</p>
</li>
   
   
<li>
<li>When <var>MODE=PASS</var> and PROTOCOL=TRANSFER, the transfer uses SNA Communications Server.  
<p>When <var>MODE=PASS</var> and PROTOCOL=TRANSFER, the transfer uses SNA Communications Server. </p>
<p>
For transfers to another <var class="product">Model&nbsp;204</var> region, partnername must be either the name of a processgroup defined in the destination region or the SNA Communications Server applid (User 0 VTAMNAME parameter value) of the destination region.  
For transfers to another <var class="product">Model&nbsp;204</var> region, partnername must be either the name of a processgroup defined in the destination region or the SNA Communications Server applid (User 0 VTAMNAME parameter value) of the destination region. </p>
<p>The choice of processgroup or SNA Communications Server applid depends on the LOGIN value of the accompanying DEFINE PROCESSGROUP command. LOGIN can be TRUST or NOTRUST: </p>
<p>
</li>
The choice of processgroup or SNA Communications Server applid depends on the LOGIN value of the accompanying DEFINE PROCESSGROUP command. LOGIN can be TRUST or NOTRUST: </p></li>
   
   
<li>
<li>If both partners are defined with LOGIN=TRUST, the transfer is "trusted": the command line passed to the partner is processed without a qualifying prompt for a password. The partnername value is checked for at the partner. It must be the name of a processgroup defined in the destination Online; if not, a password is prompted for.</li>
<p>If both partners are defined with LOGIN=TRUST, the transfer is "trusted": the command line passed to the partner is processed without a qualifying prompt for a password.   The partnername value is checked for at the partner. It must be the name of a processgroup defined in the destination Online; if not, a password is prompted for.</p>
</li>
   
   
<li>
<li>If either partner is defined with LOGIN=NOTRUST, the transferring user is prompted for a password. The partnername value is not checked for at the partner. It therefore can be either the name of a processgroup in, or the SNA Communications Server applid of, the destination region.  
<p>If either partner is defined with LOGIN=NOTRUST, the transferring user is prompted for a password. The partnername value is not checked for at the partner. It therefore can be either the name of a processgroup in, or the SNA Communications Server applid of, the destination region. </p>
<p>
<p>For transfers to a non-<var class="product">Model&nbsp;204</var> region, partnername must be the SNA Communications Server applid of the destined SNA Communications Server application.</p>
For transfers to a non-<var class="product">Model&nbsp;204</var> region, partnername must be the SNA Communications Server applid of the destined SNA Communications Server application.</p>
<p>The value specified for PARTNER can be as many as eight characters in length.</p>
<p>The value specified for PARTNER can be as many as eight characters in length.</p></li>
</li>
</ul>
</ul>
</td>
</td>
</tr>
</tr>
   
   
<tr>
<tr id="datalen">
<th><var>DATALEN</var></th>
<th><var>DATALEN</var></th>
<td> determines the maximum size of the data area that can be specified in the TRANSFER statement, and depends on the value of MODE.  
<td>Determines the maximum size of the data area that can be specified in the TRANSFER statement, and depends on the value of MODE.  
<ul>  
<ul>  
<li>
<li>If MODE=XCTL, the maximum data length is the CRAM buffer size, less 12 bytes.</li>
<p>If MODE=XCTL, the maximum data length is the CRAM buffer size, less 12 bytes.</p>
</li>
   
   
<li>
<li>If MODE=PASS, the maximum data length is 144 bytes.</li>
<p>If MODE=PASS, the maximum data length is 144 bytes.</p>
</li>
   
   
<li>
<li>The data area passed by the TRANSFER statement when MODE=PASS might include an automatically formatted login command string. When so, you must allow for an additional 12 bytes of overhead without exceeding the DATALEN limit of 144. If the formatted login command string is passed to a "trusted" partner, you must also allow for the length of the passed user ID and the length of the passed processgroup name. </li>
<p>The data area passed by the TRANSFER statement when MODE=PASS might include an automatically formatted login command string. When so, you must allow for an additional 12 bytes of overhead without exceeding the DATALEN limit of 144. If the formatted login command string is passed to a "trusted" partner, you must also allow for the length of the passed user ID and the length of the passed processgroup name. </p>
</ul>
</li>
</ul>
</td>
</td>
</tr>
</tr>
Line 87: Line 77:
<tr>
<tr>
<th><var>MODE</var></th>
<th><var>MODE</var></th>
<td> specifies the program control mechanism to be used. Acceptable values are as follows:  
<td>The program control mechanism to be used. Acceptable values are as follows:  
<table>  
<table>  
<tr>
<tr>
<th><var>XCTL</var></th>
<th><var>XCTL</var></th>
<td>, for transfers via CRAM to CICS partners.</td>
<td>For transfers via CRAM to CICS partners.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var>PASS</var></th>
<th><var>PASS</var></th>
<td>, for transfers via SNA Communications Server to <var class="product">Model&nbsp;204</var> or non-<var class="product">Model&nbsp;204</var> partners. </td>
<td>For transfers via SNA Communications Server to <var class="product">Model&nbsp;204</var> or non-<var class="product">Model&nbsp;204</var> partners. </td>
</tr>
</tr>
   
   
Line 105: Line 95:
<tr>
<tr>
<th><var>TIMEOUT</var></th>
<th><var>TIMEOUT</var></th>
<td> provides a terminal timeout facility, that is, the number of seconds a thread waits for notification that a session was established with the destined SNA Communications Server application.  Zero specifies no time limit and is the default.
<td>Provides a terminal timeout facility, that is, the number of seconds a thread waits for notification that a session was established with the destined SNA Communications Server application.  Zero specifies no time limit and is the default.
<p>TIMEOUT is valid only when MODE=PASS. </p>
<p>TIMEOUT is valid only when MODE=PASS. </p>
</td>
</td>
Line 112: Line 102:
<tr>
<tr>
<th><var>UIDSOURCE</var></th>
<th><var>UIDSOURCE</var></th>
<td> specifies from where to obtain the user ID for the login command string passed to the partner. The command string is specially formatted to log into the remote partner and includes the SNA Communications Server applid of the issuing partner. UIDSOURCE options are:   
<td>The place to obtain the user ID for the login command string passed to the partner. The command string is specially formatted to log into the remote partner and includes the SNA Communications Server applid of the issuing partner. UIDSOURCE options are:   
<table>  
<table>  
<tr>
<tr>
<th><var>NONE</var></th>
<th><var>NONE</var></th>
<td>, the default, means no command string is formatted by the Transfer Control facility.</td>
<td>The default, this means no command string is formatted by the Transfer Control facility.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var>CURRENT</var></th>
<th><var>CURRENT</var></th>
<td> means the current user ID is formatted into the passed command string when the TRANSFER statement is invoked.</td>
<td>The current user ID is formatted into the passed command string when the TRANSFER statement is invoked.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th><var>OPEN</var></th>
<th><var>OPEN</var></th>
<td> means the user ID that is formatted into the passed command string is taken from the USERID parameter of the TRANSFER statement. </td>
<td>The user ID that is formatted into the passed command string is taken from the USERID parameter of the TRANSFER statement. </td>
</tr>
</tr>
   
   
Line 136: Line 126:
<tr>
<tr>
<th><var>ACCTSOURCE</var></th>
<th><var>ACCTSOURCE</var></th>
<td> specifies from where to obtain the account ID for the command string passed to a partner when control is transferred. The ACCTSOURCE options are NONE, CURRENT, and OPEN, and apply to account ID the same as the UIDSOURCE options apply to user ID.  
<td>The place to obtain the account ID for the command string passed to a partner when control is transferred. The ACCTSOURCE options are NONE, CURRENT, and OPEN, and they apply to account ID the same as the UIDSOURCE options apply to user ID.  
<p>ACCTSOURCE is valid only when MODE=PASS. </p>
<p>
ACCTSOURCE is valid only when MODE=PASS. </p>
</td>
</td>
</tr>
</tr>
   
   
</table>
</table>
==Example==
==Example==
Transfer to a CICS program:  
Transfer to a CICS program:  
Line 155: Line 147:
   DATALEN=100 MODE=PASS  
   DATALEN=100 MODE=PASS  
</p>
</p>
==Usage notes==
==Usage notes==
<p>All three DEFINE commands-DEFINE LINK, DEFINE PROCESSGROUP, and DEFINE PROCESS-are necessary to fully define the process on the side from which the user is transferred. These commands are also required for the receiving side in a trusted SNA Communications Server transfer. </p>
<p>
<p>For detailed information about Transfer Control, refer to Program Communication Facilities in the <var>Model&nbsp;204 User Language Manual</var> and the Program Communication Facilities discussion in the <var>Model&nbsp;204 System Manager's Guide</var>. </p>
All three DEFINE commands (<var>[[DEFINE LINK command: Transfer Control|DEFINE LINK]]</var>, <var>[[DEFINE PROCESSGROUP command: Transfer Control|DEFINE PROCESSGROUP]]</var>, and <var>DEFINE PROCESS</var>) are necessary to fully define the process on the side from which the user is transferred. These commands are also required for the receiving side in a trusted SNA Communications Server transfer. </p>
<p>
For detailed information about Transfer Control, refer to [[Program Communication facilities#Transfer Control facility|Transfer Control facility]] and to [[Using Program Communication facilities]]. </p>
 
[[Category: System manager commands]]
[[Category: System manager commands]]
[[Category:Commands]]
[[Category:Commands]]

Latest revision as of 18:56, 13 October 2017

Summary

Privileges
User 0 or system manager
Function
Defines a Transfer Control process for reference by the SOUL TRANSFER statement. The process definition indicates the partner (CICS program or SNA Communications Server application), the type of transfer, and the characteristics of the transfer.

Syntax

DEFINE PROCESS name [LIKE previousname] WITH SCOPE=SYSTEM DESTINATION=processgroupname PARTNER=partnername DATALEN=nnnnn MODE={XCTL | PASS} [TIMEOUT=nnnnn] UIDSOURCE={NONE | CURRENT |OPEN} ACCTSOURCE={NONE | CURRENT | OPEN}

Where:

name The local Model 204 name for the process being defined. The SOUL TRANSFER statement refers to this process by the name specified. The length of the name must be 1 to 8 characters.
LIKE Gives the current link the attributes of the link entity referred to by previousname.
SCOPE=SYSTEM Indicates that the definition is available to all users of the Model 204 system for the entire run.
DESTINATION Associates the process with the processgroup, processgroupname, defined by the DEFINE PROCESSGROUP command.
PARTNER The name of the partner (as known in the remote environment) that is the object of the User Language TRANSFER statement and to which control is passed. Acceptable values for partnername (as many as eight characters) depend on what MODE, PROTOCOL, and LOGIN options are defined on the DEFINE PROCESS, DEFINE LINK, and DEFINE PROCESSGROUP commands, respectively:
  • When MODE=XCTL and PROTOCOL=TRANSFER, partnername must be the name of a CICS program. The CICS program is the partner process and the object of the TRANSFER statement.
  • When MODE=PASS and PROTOCOL=TRANSFER, the transfer uses SNA Communications Server.

    For transfers to another Model 204 region, partnername must be either the name of a processgroup defined in the destination region or the SNA Communications Server applid (User 0 VTAMNAME parameter value) of the destination region.

    The choice of processgroup or SNA Communications Server applid depends on the LOGIN value of the accompanying DEFINE PROCESSGROUP command. LOGIN can be TRUST or NOTRUST:

  • If both partners are defined with LOGIN=TRUST, the transfer is "trusted": the command line passed to the partner is processed without a qualifying prompt for a password. The partnername value is checked for at the partner. It must be the name of a processgroup defined in the destination Online; if not, a password is prompted for.
  • If either partner is defined with LOGIN=NOTRUST, the transferring user is prompted for a password. The partnername value is not checked for at the partner. It therefore can be either the name of a processgroup in, or the SNA Communications Server applid of, the destination region.

    For transfers to a non-Model 204 region, partnername must be the SNA Communications Server applid of the destined SNA Communications Server application.

    The value specified for PARTNER can be as many as eight characters in length.

DATALEN Determines the maximum size of the data area that can be specified in the TRANSFER statement, and depends on the value of MODE.
  • If MODE=XCTL, the maximum data length is the CRAM buffer size, less 12 bytes.
  • If MODE=PASS, the maximum data length is 144 bytes.
  • The data area passed by the TRANSFER statement when MODE=PASS might include an automatically formatted login command string. When so, you must allow for an additional 12 bytes of overhead without exceeding the DATALEN limit of 144. If the formatted login command string is passed to a "trusted" partner, you must also allow for the length of the passed user ID and the length of the passed processgroup name.
MODE The program control mechanism to be used. Acceptable values are as follows:
XCTL For transfers via CRAM to CICS partners.
PASS For transfers via SNA Communications Server to Model 204 or non-Model 204 partners.
TIMEOUT Provides a terminal timeout facility, that is, the number of seconds a thread waits for notification that a session was established with the destined SNA Communications Server application. Zero specifies no time limit and is the default.

TIMEOUT is valid only when MODE=PASS.

UIDSOURCE The place to obtain the user ID for the login command string passed to the partner. The command string is specially formatted to log into the remote partner and includes the SNA Communications Server applid of the issuing partner. UIDSOURCE options are:
NONE The default, this means no command string is formatted by the Transfer Control facility.
CURRENT The current user ID is formatted into the passed command string when the TRANSFER statement is invoked.
OPEN The user ID that is formatted into the passed command string is taken from the USERID parameter of the TRANSFER statement.

UIDSOURCE is valid only when MODE=PASS.

ACCTSOURCE The place to obtain the account ID for the command string passed to a partner when control is transferred. The ACCTSOURCE options are NONE, CURRENT, and OPEN, and they apply to account ID the same as the UIDSOURCE options apply to user ID.

ACCTSOURCE is valid only when MODE=PASS.

Example

Transfer to a CICS program:

DEFINE PROCESS CICSTRN1 WITH - SCOPE=SYSTEM PARTNER=CICSPGM - DESTINATION=GRP1 - DATALEN=256 MODE=XCTL

Transfer from a Model 204 Online to a Model 204 Online:

DEFINE PROCESS M204APR WITH - SCOPE=SYSTEM PARTNER=M204BPG - DESTINATION=M204APG - DATALEN=100 MODE=PASS

Usage notes

All three DEFINE commands (DEFINE LINK, DEFINE PROCESSGROUP, and DEFINE PROCESS) are necessary to fully define the process on the side from which the user is transferred. These commands are also required for the receiving side in a trusted SNA Communications Server transfer.

For detailed information about Transfer Control, refer to Transfer Control facility and to Using Program Communication facilities.